Permission System

Response Options & Scopes

When a tool requires permission, the user can respond with various approval scopes, from narrowest to widest:

The key distinction between turn and idle: turn approval clears when the model finishes its current response, while idle approval persists across consecutive model turns until the session becomes inactive (no user input, no model activity).

Policy Evaluation Order

Permission decisions follow a strict, deterministic pipeline. Each step either produces a final decision or defers to the next:

1. Suspension check — Is idle/turn/all suspension active? → ALLOW
2. Sanitization — Shell injection, dangerous commands, path scope violations? → DENY
3. Session blacklist — Tool in runtime blacklist? → DENY
4. Static blacklist — Tool matches permissions.json blacklist pattern? → DENY
5. Session whitelist — Tool in runtime whitelist? → ALLOW
6. Static whitelist — Tool matches permissions.json whitelist pattern? → ALLOW
7. Default policy — "allow", "deny", or "ask"

Key principle: Blacklist always wins. If a tool appears in both the blacklist and whitelist, it is denied. Session rules override static configuration.

Auto-Approved Tools

Certain tools bypass the permission system entirely because they are inherently safe:

• Read-only operations — readFile, web_search, get_environment
• Pure computations — calculate
• User-initiated actions — Authentication commands, answerClarification
• Reversible operations — undoFileChange
• Meta-commands — permissions (managing the permission system itself)

Plugins declare their auto-approved tools via get_auto_approved_tools(). These are collected by the registry and added to the permission plugin's whitelist during initialization.

Permission Channels

The permission system is channel-agnostic. Different deployment scenarios use different channels to handle user interaction:

The WebhookChannel enables enterprise approval workflows: JAATO posts a permission request to an external system, which performs review (possibly by a human or policy engine) and returns a decision.

Thread Safety & Parallel Execution

When multiple tools execute in parallel and require permission, a channel lock ensures serialized prompts. Only one permission prompt is shown to the user at a time. Other threads wait for the lock, and upon acquiring it, re-check suspension state (another thread may have set "all" approval in the meantime).

Each tool call carries a unique call_id for matching permission requests to responses, which is essential when multiple permissions are pending simultaneously.

Sanitization (Security Layer)

An optional security layer runs before whitelist/blacklist evaluation. It checks for:

• Shell injection — Prevents command injection via ; rm -rf /, $(malicious), backtick execution
• Dangerous commands — Blocks destructive operations like sudo, rm, chmod 777, kill -9
• Path scope — Restricts file access to allowed directories, preventing ../../etc/passwd traversal

Sanitization violations result in immediate denial, regardless of whitelist or approval status. This provides defense-in-depth against prompt injection attacks that might trick the model into executing harmful operations.