7 · The Permission System

The utils/permissions/ directory holds 21 files, and the core permissions.ts alone is 51 KB. This chapter gives the complete answer to one question: “on what grounds does this tool call get to run?”

7.1 Six Permission Modes

const PERMISSION_MODE_CONFIG: Partial<Record<PermissionMode, PermissionModeConfig>> = {
  default:           { title: 'Default',             symbol: '',    color: 'text' },
  plan:              { title: 'Plan Mode',           symbol: '⏸',   color: 'planMode' },
  acceptEdits:       { title: 'Accept edits',        symbol: '⏵⏵',  color: 'autoAccept' },
  bypassPermissions: { title: 'Bypass Permissions',  symbol: '⏵⏵',  color: 'error' },
  dontAsk:           { title: "Don't Ask",           symbol: '⏵⏵',  color: 'error' },
  ...(feature('TRANSCRIPT_CLASSIFIER') ? {
  auto:              { title: 'Auto mode',           symbol: '⏵⏵',  color: 'warning' },
  } : {}),
}

claude-code/src/utils/permissions/PermissionMode.ts

There's also a carefully drawn distinction at the type level:

export function isExternalPermissionMode(mode: PermissionMode): mode is ExternalPermissionMode {
  if (process.env.USER_TYPE !== 'ant') return true      // external users have no auto, so always true
  return mode !== 'auto' && mode !== 'bubble'
}

export function toExternalPermissionMode(mode: PermissionMode): ExternalPermissionMode {
  return getModeConfig(mode).external      // auto maps to default externally
}

Internal modes need an external mapping. The auto mode reports itself to external interfaces as default — so SDK users never see a mode value they can't understand and can't set.

7.2 The Ten-Step Decision Cascade

The core function hasPermissionsToUseToolInner() is a strictly ordered chain of checks, evaluated top to bottom; the first one that matches decides the outcome:

The four source comments on the bypass-immune layer

// 1d. Tool implementation denied (catches bash subcommand denies wrapped ...)
// 1e. Tool requires user interaction even in bypass mode
// 1f. Content-specific ask rules from tool.checkPermissions take precedence
//     over bypassPermissions mode. When a user explicitly configures a
//     content-specific ask rule (e.g. Bash(npm publish:*)), the tool's
//     checkPermissions returns {behavior:'ask', ...}. This must be respected
//     even in bypass mode, just as deny rules are respected at step 1d.
// 1g. Safety checks (e.g. .git/, .claude/, .vscode/, shell configs) are
//     bypass-immune — they must prompt even in bypassPermissions mode.

7.3 Auto Mode: Model Classifier + Three-Tier Fast Path

When the verdict lands on ASK and the current mode is auto, Claude Code doesn't pop a dialog. Instead it calls the model one more time to judge whether the action is safe. This dedicated call is the “classifier.”

But the classifier isn't cheap — it's an extra API request per tool call. So several layers stand in front of it:

if (feature('TRANSCRIPT_CLASSIFIER') &&
    (appState.toolPermissionContext.mode === 'auto' ||
     (appState.toolPermissionContext.mode === 'plan' && isAutoModeActive()))) {

  // Intercept 1: a safety check fired, and it's one the classifier "isn't allowed to approve"
  if (result.decisionReason?.type === 'safetyCheck' &&
      !result.decisionReason.classifierApprovable) {
    if (appState.toolPermissionContext.shouldAvoidPermissionPrompts) {
      return { behavior:'deny', message: result.message,
               decisionReason: { type:'asyncAgent',
                 reason:'Safety check requires interactive approval and permission '
                      + 'prompts are not available in this context' } }
    }
    return result       // stays ASK
  }

  // Intercept 2: the tool declares "a human must be present"
  if (tool.requiresUserInteraction?.() && result.behavior === 'ask') return result

  // Intercept 3: PowerShell (unless a special compile-time flag is on)
  if (tool.name === POWERSHELL_TOOL_NAME && !feature('POWERSHELL_AUTO_MODE')) { ... }

  // Fast path ①: pose as acceptEdits mode and ask the tool again
  if (result.behavior === 'ask' &&
      tool.name !== AGENT_TOOL_NAME && tool.name !== REPL_TOOL_NAME) {
    const acceptEditsResult = await tool.checkPermissions(parsedInput, {
      ...context,
      getAppState: () => ({ ...context.getAppState(),
        toolPermissionContext: { ...state.toolPermissionContext,
                                 mode: 'acceptEdits' as const } }),
    })
    if (acceptEditsResult.behavior === 'allow') {
      logEvent('tengu_auto_mode_decision', { decision:'allowed', fastPath:'acceptEdits', ... })
      return { behavior:'allow', updatedInput: acceptEditsResult.updatedInput ?? input,
               decisionReason: { type:'mode', mode:'auto' } }
    }
  }

  // Fast path ②: allowlist of safe tools
  if (classifierDecisionModule!.isAutoModeAllowlistedTool(tool.name)) {
    logEvent('tengu_auto_mode_decision', { decision:'allowed', fastPath:'allowlist', ... })
    return { behavior:'allow', updatedInput: input, decisionReason: { type:'mode', mode:'auto' } }
  }

  // Nothing matched → actually call the classifier
  const action = formatActionForClassifier(tool.name, input)
  setClassifierChecking(toolUseID)
  let classifierResult
  try {
    classifierResult = await classifyYoloAction(
      context.messages,                    // ★ the full transcript
      action,
      context.options.tools,
      appState.toolPermissionContext,
      context.abortController.signal)
  } finally {
    clearClassifierChecking(toolUseID)
  }
  ...
}

claude-code/src/utils/permissions/permissions.ts

What's clever about fast path ①

It temporarily disguises the permission mode as acceptEdits and asks the tool again. The logic: if even the permissive mode would allow this operation, it's genuinely harmless, and there's no need to pay for a classifier call.

But two tools are explicitly excluded:

The classifier sees the full transcript

Note the first argument to classifyYoloAction(context.messages, ...): the entire transcript, not just this one command.

This matters. An rm -rf build/ is safe in the context of “the user asked to clean up build artifacts” and impossible to judge without that context. But it raises a problem: the full transcript can run to tens of thousands of tokens, and stuffing it into the classifier would blow it up.

So the tool interface has a method built specifically for this:

/**
 * Returns a compact representation of this tool use for the auto-mode
 * security classifier. Examples: `ls -la` for Bash, `/tmp/x: new content`
 * for Edit. Return '' to skip this tool in the classifier transcript
 * (e.g. tools with no security relevance). May return an object to avoid
 * double-encoding when the caller JSON-wraps the value.
 */
toAutoClassifierInput(input: z.infer<Input>): unknown

Each tool supplies its own compressed representation that keeps only the security-relevant semantics: Bash gives the command-line text, Edit gives “path + new content,” and tools with no security implications return an empty string and drop out of view entirely.

Consecutive-denial tracking: breaking deadlocks

// any successful allow resets the consecutive-denial counter
if (result.behavior === 'allow') {
  const currentDenialState = context.localDenialTracking ?? appState.denialTracking
  if (appState.toolPermissionContext.mode === 'auto' &&
      currentDenialState && currentDenialState.consecutiveDenials > 0) {
    const newDenialState = recordSuccess(currentDenialState)
    persistDenialState(context, newDenialState)
  }
  return result
}

Once consecutive denials hit a threshold, the system stops trusting the classifier and falls back to human confirmation. It guards against this deadlock: the classifier keeps denying because of some misjudgment, the model doesn't understand why and keeps rephrasing and retrying — both sides burn money and nothing ever moves forward.

Note the fallback in context.localDenialTracking ?? appState.denialTracking:

7.4 Permission Rule Syntax

Users can write permission rules in the config file. The syntax has two levels:

Three kinds of rules: alwaysAllowRules (always allow), alwaysDenyRules (always deny), and alwaysAskRules (always ask).

Whole-tool deny rules take effect “before the model ever sees the tool”

/**
 * Filters out tools that are blanket-denied by the permission context.
 * A tool is filtered out if there's a deny rule matching its name with no
 * ruleContent (i.e., a blanket deny for that tool).
 *
 * Uses the same matcher as the runtime permission check (step 1a), so MCP
 * server-prefix rules like `mcp__server` strip all tools from that server
 * before the model sees them — not just at call time.
 */
export function filterToolsByDenyRules<T>(tools, permissionContext): T[] {
  return tools.filter(tool => !getDenyRuleForTool(permissionContext, tool))
}

Shadowed-rule detection

utils/permissions/ has a file called shadowedRuleDetection.ts. The problem it solves:

7.5 Sandboxing and Read-Only Command Detection

Read-only commands are allowed automatically

utils/shell/readOnlyCommandValidation.ts, 66.7 KB. Its job is to decide “is this shell command read-only?” If so, it can be allowed automatically without bothering the user.

That's much harder than it looks, because it has to handle:

• Pipes and redirects — ls | grep foo is read-only; ls > out.txt is not
• Command substitution — echo $(rm -rf /) hides a write inside
• Compound commands — cd /tmp && ls contains two commands, and both need judging
• Aliases and functions — the user may have aliased ls to something else

So the utils/bash/ directory contains a complete shell grammar parser: bashParser.ts (128 KB) + ast.ts (109 KB). It parses shell commands into an abstract syntax tree and analyzes the tree, instead of regex-matching strings.

And there's an experimental alternative implementation: the compile-time flags include TREE_SITTER_BASH and TREE_SITTER_BASH_SHADOW — the latter's name (shadow) shows they're validating the new parser in shadow mode: both parsers run at the same time, disagreements are logged, but the old parser's result is still the one used. That collects accuracy data on the new implementation at zero risk.

OS-level sandboxing

On macOS, Claude Code uses the system's built-in sandbox-exec mechanism (also known as seatbelt). It applies a policy file when a process launches, restricting which paths the process can access and whether it can reach the network.

Step 1b of the permission chain has a special branch tied to the sandbox:

// 1b. Check if the entire tool should always ask for permission
const askRule = getAskRuleForTool(...)
if (askRule) {
  // When "auto-allow inside the sandbox" is on, sandboxable commands skip the ask rule
  // and are auto-allowed through Bash's checkPermissions.
  // Commands that won't be sandboxed (on the exclude list, or with sandboxing explicitly off) still obey the ask rule.
  if (!canSandboxAutoAllow) {
    return { behavior:'ask', ... }
  }
  // otherwise fall through and let Bash's checkPermissions handle the per-command rules
}

The logic: if this command will run inside the sandbox, it doesn't matter that it “looks dangerous” — the sandbox will contain it. So the ask can be skipped. That's “trading stronger isolation for fewer interruptions.”

7.6 The Full Data Structure Behind a Permission Decision

export type ToolPermissionContext = DeepImmutable<{
  mode: PermissionMode
  additionalWorkingDirectories: Map<string, AdditionalWorkingDirectory>
  alwaysAllowRules: ToolPermissionRulesBySource
  alwaysDenyRules:  ToolPermissionRulesBySource
  alwaysAskRules:   ToolPermissionRulesBySource
  isBypassPermissionsModeAvailable: boolean
  isAutoModeAvailable?: boolean
  strippedDangerousRules?: ToolPermissionRulesBySource   // ★ dangerous rules that were stripped
  shouldAvoidPermissionPrompts?: boolean                 // background tasks: can't show a dialog
  awaitAutomatedChecksBeforeDialog?: boolean
  prePlanMode?: PermissionMode                           // mode before entering plan mode, for restoring
}>

Two fields deserve attention:

strippedDangerousRules: rules the system actively strips out

A user's config may contain rules that are “so broad they're dangerous.” The system strips them at load time and records what it stripped (so the UI can tell the user “this rule of yours was ignored because it's too broad”).

The concrete stripping logic is visible in the source, for example:

• isOverlyBroadPowerShellAllowRule — strips allow-everything rules like PowerShell(*)
• isDangerousPowerShellPermission — strips allow rules with prefixes like iex (download-and-execute) and Start-Process

DeepImmutable: immutability at the type level

This wrapper type makes the entire permission context completely read-only at the type-system level — any code that tries to mutate it fails to compile. Changes to permission state have to go through the dedicated applyPermissionUpdates() function, which guarantees every change passes through one unified validation and persistence path.

7.7 Explainability of Permission Decisions

Every permission decision carries a decisionReason field:

{ type: 'rule',        rule: {...} }            // a rule matched
{ type: 'mode',        mode: 'auto' }           // because of the current mode
{ type: 'hook',        hookName: 'PermissionRequest', reason: ... }  // decided by a hook
{ type: 'safetyCheck', classifierApprovable: false }   // safety check
{ type: 'asyncAgent',  reason: '...' }          // background task can't interact

And a dedicated module, permissionExplainer.ts, translates these reasons into plain language for the user.