permission-system

Permission System

The pattern

Every tool call in Claude Code passes through a permission gate before execution. The gate is a checkPermissions(input, context) method defined on the tool itself. The framework calls this method before invoking call() — the tool never calls it manually. If the result has behavior: 'deny', the framework sends a tool_result with is_error: true back to the LLM and never invokes call() at all. This makes the permission boundary declarative: a tool that omits checkPermissions gets the default implementation, which returns { behavior: 'allow' } unconditionally.

Three permission modes control how the gate behaves: 'default' prompts the user for sensitive operations, 'bypass' grants everything silently, and 'auto' approves operations matching pre-approved rules.

Why this matters

Claude Code executes arbitrary shell commands, reads and writes files, and can make network requests. Running in a developer's local environment means a mistake has real consequences — files can be deleted, credentials can be exfiltrated, production systems can be modified. The permission system is a defense-in-depth layer: even if the LLM produces a malicious or incorrect tool call, the user is prompted before the side effect happens.

The system is per-input, not per-tool. checkPermissions receives the full parsed input, so a bash tool can be auto-approved for git status (read-only) while still prompting for rm -rf (destructive). Rules match tool names, command patterns, and file path globs, making the policy composable and auditable.

How to apply it

1. Implement checkPermissions(input, context) as a method on your tool definition — the framework calls it before call(), so no manual invocation is needed inside call().
2. Inside checkPermissions, read context.getAppState().toolPermissionContext and pass it to the appropriate utility (e.g., checkReadPermissionForTool, checkBashPermissionForTool) from src/utils/permissions/.
3. When defining a new tool, implement isDestructive?(input) if the tool performs irreversible mutations. This signals to the permission UI that extra confirmation is appropriate.
4. To add auto-approve rules, write them to ~/.claude/settings.json under permissions.allow. Rules use glob-like matchers: Bash(git *) approves all git bash commands; FileRead(src/*) approves file reads in src/.
5. The toolPermissionContext in AppState carries the current rules — read it via context.getAppState().toolPermissionContext.