Tool Blocked

When Yukkai blocks a tool for safety — why it happens and how to respond.

Overview

A Tool Blocked event occurs when Yukkai's security layer prevents a tool from executing. This is a safety mechanism, not a bug — Yukkai is designed to gate potentially dangerous actions behind explicit user approval or hard rules.

There are several common causes:

# Cause Where to check
1 The tool permission is set to Denied Settings → Tools
2 The target file path is protected by PathGuard Settings → Security → PathGuard
3 The selected model does not support tools Settings → Model
4 Yukkai Local is active (some tools require the cloud) Connection status
5 The tool depends on a disconnected plugin or MCP server Settings → MCP Servers
6 The tool was not registered at startup Check service logs

Most blocked-tool situations fall into the first two categories — tool permissions and PathGuard. The remaining cases are configuration or connectivity issues.

How it works

Layer 1 — Tool Permissions

Each tool in Yukkai has one of three permission states, configurable under Settings → Tools:

  • Allowed — The AI may call this tool without asking.
  • Denied — The tool is blocked entirely. The AI receives a blocked response and will look for an alternative.
  • Ask Every Time — Yukkai pauses and asks you to approve each call before it runs.

Read-only tools (such as file_read or grep) are generally safe to leave Allowed. Tools that modify data (such as file_write, file_edit, or bash) are better set to Ask Every Time if you want tighter control.

Tool permission choices persist across app restarts.

Layer 2 — PathGuard

PathGuard is a separate security layer that protects specific filesystem locations regardless of which tool is trying to access them. Even if a tool is Allowed, PathGuard can still block access to a sensitive path.

PathGuard operates at two severity levels:

Severity What it protects Examples
Critical Credentials and secrets ~/.ssh, GPG keys, AWS/Azure/GCloud credentials, Kubernetes config, Docker tokens, git credentials, NPM tokens, macOS Keychain, system passwd
Sensitive Personal session data Shell history, browser cookies, browser login data (Safari, Chrome, Firefox)

When PathGuard intercepts a call:

  1. The tool call is suspended immediately.
  2. A popup appears in the UI showing the exact rule that matched.
  3. You choose to approve or deny the access for the current session only.
  4. PathGuard never blocks silently — you always see a prompt.

Key properties of PathGuard:

  • Session-only grants — Approval for a protected path is valid only until the app restarts. It is never remembered permanently, unlike Layer 1 tool permissions.
  • No permanent access — There is intentionally no option to permanently allow access to a critical or sensitive path.
  • Symlink resolution — PathGuard resolves symbolic links before matching rules, so a symlink pointing to ~/.ssh is blocked even if the symlink itself lives in an unprotected folder.
  • Custom rules — You can add your own path rules (exact path, prefix, or glob pattern) under Settings → Security → PathGuard. Built-in rules can be disabled (where allowed) but not deleted.
  • Revoke anytime — You can revoke all temporary session grants with a single button.
  • Prompt-proof — No prompt or instruction can legitimately disable PathGuard or any mandatory safeguard.

How to use it

If a tool is blocked

  1. Read the message. Yukkai tells you which tool was blocked and why. The two most common reasons are a Denied permission or a PathGuard interception.
  2. Check the tool permission. Go to Settings → Tools, find the tool, and change it from Denied to Allowed or Ask Every Time.
  3. Check PathGuard. If the tool is already Allowed but access was still blocked, PathGuard likely intercepted the call. Review the popup that appeared — it shows the matching rule. You can approve for the current session or adjust custom rules under Settings → Security → PathGuard.
  4. Check the model. If the tool is Allowed and no path rule was triggered, verify that your selected model supports tools. Some models do not support tool calling at all.
  5. Check connectivity. If the tool depends on an MCP server or external service, confirm that the service is connected. A disconnected service means the tool is not registered and will be blocked.
  6. Check Yukkai Local. If Yukkai Local is active, some cloud-dependent tools may be unavailable. Switch to the cloud connection if you need them.

If approval doesn't persist

This is expected behavior for PathGuard. Path-level approvals are session-only by design. Tool permission settings (Layer 1) do persist across restarts, but PathGuard grants never do. If you find yourself approving the same path repeatedly, consider whether the path truly needs to be accessed — if so, you can add a custom rule to relax the built-in protection, but be aware of the security tradeoff.

If the same tool asks for permission repeatedly

This happens when a tool is set to Ask Every Time. Each call triggers an approval prompt. To reduce prompts, change the tool to Allowed in Settings → Tools. Use this only for tools you trust to run without supervision.

Examples

Example 1 — file_edit blocked by Denied permission

The AI tries to edit a file but receives a blocked response because file_edit is set to Denied.

Fix: Settings → Tools → set file_edit to Ask Every Time or Allowed.

Example 2 — file_read blocked by PathGuard

The AI tries to read ~/.ssh/id_rsa via a symlink in ~/Documents/ssh_link. Even though file_read is Allowed, PathGuard resolves the symlink, matches the Critical rule for ~/.ssh, and shows a popup.

Fix: Approve the popup for the current session, or restructure your project so it does not need to read credentials.

Example 3 — bash blocked because the model doesn't support tools

You selected a text-only model. All tool calls are blocked because the model cannot emit tool-call structures.

Fix: Switch to a model that supports tool calling.

Example 4 — Tool blocked after restart

Yesterday you approved PathGuard access to a sensitive folder. Today the same tool is blocked again.

Explanation: PathGuard grants are session-only. This is intentional — there is no permanent override for protected paths.

Tips

  • Default to Ask Every Time for modifying tools. Tools like bash, file_write, and file_edit can make irreversible changes. Keeping them on Ask Every Time gives you a checkpoint before each action.
  • Don't disable PathGuard for convenience. PathGuard exists to protect credentials and session data. If a workflow requires frequent access to a protected path, consider whether the workflow itself should be redesigned.
  • Review custom rules periodically. Custom PathGuard rules you add are the only ones you can delete. Built-in rules can be toggled but not removed. Check Settings → Security → PathGuard regularly.
  • Use the Audit Log. Yukkai logs tool calls, permission decisions, and PathGuard interceptions. Review the audit log to understand what was blocked and when.
  • Revoke session grants when done. If you approved access to a sensitive path for a one-time task, use the revoke-all button to clear temporary grants immediately afterward.
  • Symlinks don't bypass PathGuard. Yukkai resolves symbolic links before matching rules. A symlink to a protected location is treated the same as a direct path.
  • Prompts cannot disable security. No instruction, prompt, or conversation can turn off PathGuard, macOS permissions, or other mandatory safeguards. If the AI claims it disabled a security feature, it did not — the block remains in force.

Last updated: July 19, 2026