Skip to main content
Every tool invocation passes through a centralized permission check before execution. The permission system is located in src/hooks/toolPermission/ and is the single chokepoint for all potentially destructive operations.

​
Permission modes

Prompts the user for approval before each potentially destructive operation. This is the standard mode for interactive sessions.

​
How it works

1

Tool is invoked

The Query Engine calls a tool as part of the LLM’s tool-call loop.
2

checkPermissions() is called

The tool’s checkPermissions(input, context) method is called, returning a result of the shape:
{ granted: boolean, reason?: string, prompt?: string }
3

Rules are checked

The permission handler checks the invocation against the configured rule set. If a matching wildcard rule grants approval, the tool proceeds immediately.
4

User is prompted or auto-approved

If no rule matches, the system either prompts the user (terminal or IDE) or auto-approves based on the active permission mode.

​
Permission rules

Rules use wildcard patterns to match specific tool invocations. They are configured in project or user settings. 
Bash(git *)           # Allow all git commands
Bash(npm test)        # Allow 'npm test' specifically
FileEdit(/src/*)      # Allow edits to anything under src/
FileRead(*)           # Allow reading any file
The pattern format is ToolName(argument-pattern). Wildcards (*) match any sequence of characters within the argument.
Use the narrowest rule that covers your workflow. Bash(*) grants unrestricted shell access — prefer specific patterns like Bash(npm test) or Bash(git *).

​
Key files

PermissionContext.ts

src/hooks/toolPermission/PermissionContext.tsHolds the active permission mode and rule set. Passed into every tool execution context.

handlers/

src/hooks/toolPermission/handlers/Per-tool permission handlers that implement the approval logic for each tool category.

permissionLogging.ts

src/hooks/toolPermission/permissionLogging.tsLogs all permission decisions for auditing and debugging.

types/permissions.ts

src/types/permissions.tsTypeScript types for the permission rule schema, decision objects, and mode enums.

​
Tool permission interface

Each tool implements a checkPermissions() method that the permission system calls before execution: 
checkPermissions(input: ToolInput, context: ToolContext): PermissionResult
Where PermissionResult is: 
interface PermissionResult {
  granted: boolean
  reason?: string   // Shown in audit log
  prompt?: string   // Shown to user if prompting
}
  • /memory command — Manage project and user memories
  • Architecture — How the permission system fits into the Query Engine’s tool-call loop

Build docs developers (and LLMs) love

Get started for freeTalk to us