Lesson 06 — The Permission System

1. System Overview

Every time Claude wants to use a tool — run a bash command, edit a file, call an MCP endpoint — the permission system runs a multi-step decision pipeline. The pipeline produces one of three outcomes:

The three inputs to the pipeline are: the tool being requested, its input (e.g., the shell command), and the current permission context (mode, rules from all sources, session state).

2. The Decision Pipeline

The pipeline is implemented in hasPermissionsToUseToolInner() in permissions.ts. Steps are numbered to match the inline comments in the source.

Each numbered step corresponds directly to the // 1a, 1b, 1c... comments in permissions.ts, making the source self-documenting.

3. The 5 Permission Modes

The mode controls which pipeline branch executes for any ask result. It is stored in toolPermissionContext.mode.

const PERMISSION_MODE_CONFIG = {
  default:           { title: 'Default',            color: 'text',       external: 'default' },
  plan:              { title: 'Plan Mode',          color: 'planMode',  external: 'plan' },
  acceptEdits:       { title: 'Accept edits',       color: 'autoAccept', external: 'acceptEdits' },
  bypassPermissions: { title: 'Bypass Permissions', color: 'error',      external: 'bypassPermissions' },
  dontAsk:           { title: "Don't Ask",          color: 'error',      external: 'dontAsk' },
  // auto is ANT-only, enabled by feature('TRANSCRIPT_CLASSIFIER')
  auto:              { title: 'Auto mode',          color: 'warning',    external: 'default' },
}

4. Rule Matching System

Every rule is a string of the form ToolName or ToolName(content), stored in allow/deny/ask lists. Parsing is handled by permissionRuleParser.ts.

Rule string format

// Tool-wide rule — no content
"Bash"                 // match any Bash command
"mcp__myserver"        // match all tools from myserver MCP
"mcp__myserver__*"     // same, wildcard variant

// Content-specific rules (three types)
"Bash(npm install)"    // exact match
"Bash(npm:*)"          // legacy prefix — matches anything starting with "npm"
"Bash(git add *)"      // wildcard — * matches any sequence of chars
"Bash(git ad\* file)"  // escaped * — matches literal asterisk

Three content rule types (shellRuleMatching.ts)

// Rule: "git *"
// Matches both:
"git add"     // command with argument
"git"         // bare command — optional trailing match
// This aligns wildcard semantics with legacy prefix "git:*"

// "Bash(python -c \"print\\(1\\)\")"  →
function permissionRuleValueFromString(ruleString) {
  const openIdx  = findFirstUnescapedChar(ruleString, '(')
  const closeIdx = findLastUnescapedChar(ruleString, ')')

  if (openIdx === -1) return { toolName: normalizeLegacyToolName(ruleString) }

  const toolName   = ruleString.substring(0, openIdx)
  const rawContent = ruleString.substring(openIdx + 1, closeIdx)

  // Empty or standalone "*" → treat as tool-wide rule
  if (rawContent === '' || rawContent === '*')
    return { toolName: normalizeLegacyToolName(toolName) }

  return { toolName: normalizeLegacyToolName(toolName), ruleContent: unescapeRuleContent(rawContent) }
}

const LEGACY_TOOL_NAME_ALIASES = {
  Task:            AGENT_TOOL_NAME,     // → "Agent"
  KillShell:       TASK_STOP_TOOL_NAME, // → "TaskStop"
  AgentOutputTool: TASK_OUTPUT_TOOL_NAME,
  BashOutputTool:  TASK_OUTPUT_TOOL_NAME,
}

5. Rule Sources & Priority

Rules are loaded from multiple sources and merged. When allowManagedPermissionRulesOnly is set in policySettings, all non-policy sources are ignored.

Settings JSON format

{
  "permissions": {
    "allow": ["Bash(npm:*)", "Bash(git status)"],
    "deny":  ["WebFetch"],
    "ask":   ["Bash(npm publish:*)"]
  }
}

6. Auto Mode & the AI Classifier

When mode is auto, instead of prompting the user, Claude routes ambiguous tool uses through a secondary Claude model (the "YOLO classifier") that decides allow/deny based on a system prompt describing allowed and prohibited action categories.

Fast paths (skip the classifier API call)

1. Non-classifiable safety checks: Writing to .git/ or shell configs — never auto-approved even by the classifier.
2. acceptEdits fast path: If the tool would be allowed in acceptEdits mode (file edits inside CWD), allow immediately without calling the classifier.
3. Safe tool allowlist: Read-only tools (FileRead, Grep, Glob, LSP, TodoWrite, sleep, etc.) skip the classifier entirely. The list is in classifierDecision.ts.

const SAFE_YOLO_ALLOWLISTED_TOOLS = new Set([
  // Read-only file operations
  FILE_READ_TOOL_NAME,
  GREP_TOOL_NAME, GLOB_TOOL_NAME, LSP_TOOL_NAME,
  TOOL_SEARCH_TOOL_NAME, LIST_MCP_RESOURCES_TOOL_NAME,
  // Task management (metadata only)
  TODO_WRITE_TOOL_NAME,
  TASK_CREATE_TOOL_NAME, TASK_GET_TOOL_NAME, TASK_UPDATE_TOOL_NAME,
  TASK_LIST_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_TOOL_NAME,
  // Plan mode / UI
  ASK_USER_QUESTION_TOOL_NAME,
  ENTER_PLAN_MODE_TOOL_NAME, EXIT_PLAN_MODE_TOOL_NAME,
  // Misc
  SLEEP_TOOL_NAME,
  YOLO_CLASSIFIER_TOOL_NAME, // the classifier itself
])

Denial tracking

The classifier tracks consecutive and total denials to detect runaway loops. When limits are hit, it falls back to prompting the user:

const DENIAL_LIMITS = {
  maxConsecutive: 3,   // 3 denials in a row → prompt user
  maxTotal:      20,   // 20 total denials this session → prompt user
}

function shouldFallbackToPrompting(state) {
  return state.consecutiveDenials >= DENIAL_LIMITS.maxConsecutive
      || state.totalDenials       >= DENIAL_LIMITS.maxTotal
}

A successful tool use resets the consecutive count (but not the total).

Dangerous patterns stripped at auto mode entry

When entering auto mode, permissionSetup.ts strips allow rules that would let Claude bypass the classifier entirely:

const DANGEROUS_BASH_PATTERNS = [
  // Script interpreters (arbitrary code execution)
  'python', 'node', 'deno', 'ruby', 'perl', 'php', 'lua',
  // Package runners
  'npx', 'bunx', 'npm run', 'yarn run', 'bun run',
  // Shells & execution multipliers
  'bash', 'sh', 'eval', 'exec', 'sudo', 'xargs',
  // ... plus ANT-only: gh, curl, wget, git, kubectl, aws, gcloud
]

Existing allow rules matching these patterns are removed from the context when auto mode is activated, ensuring the classifier sees all shell commands.

Classifier fail modes

7. Shadowed Rule Detection

A permission rule can be unreachable — written correctly but never evaluated because a more general rule fires first. shadowedRuleDetection.ts detects and reports these conflicts.

// Example: allow rule is deny-shadowed
permissions.deny  = ["Bash"]      // ← fires first, blocks everything
permissions.allow = ["Bash(ls:*)"] // ← never reached → shadowed!

// Fix: remove the tool-wide "Bash" from deny,
// or add more specific deny rules instead.

8. Permission Explainer

When a permission prompt appears, the permissionExplainer.ts makes a side API call (using the current model) to generate a human-readable explanation of what the command does, why Claude wants to run it, and the risk level.

// Structured output schema returned by the explainer model
{
  explanation: "What this command does (1-2 sentences)",
  reasoning:   "I need to check the file contents",  // starts with "I"
  risk:        "Modifies files outside the working directory",
  riskLevel:   "HIGH"  // LOW | MEDIUM | HIGH
}

• Uses sideQuery() — a separate API call that does NOT count toward the main session's token totals.
• The model is forced to use a specific tool (explain_command) for guaranteed structured output.
• Can be disabled via permissionExplainerEnabled: false in global config.
• Includes up to 1,000 chars of recent conversation context so the "why" answer is grounded in what Claude was doing.

9. Key Takeaways

• Deny rules are always checked first — before bypass mode, before allow rules, before tool-specific logic. They are the only unconditional block.
• bypassPermissions is not truly unconditional — it cannot bypass deny rules, content-specific ask rules, safety checks on protected paths, or tools that require user interaction.
• Safety-check paths are bypass-immune by design — .git/, .claude/, .vscode/, and shell config files always prompt, preventing silent config corruption.
• Rule specificity matters for shadowing — a tool-wide deny or ask rule silently makes all specific allow rules for that tool unreachable. The shadow detector warns about this.
• Auto mode has layered fast paths — safe allowlist → acceptEdits check → classifier. Only the last step costs an API call.
• Classifier denial limits prevent infinite loops — after 3 consecutive or 20 total classifier denials, the system falls back to prompting a human.
• Rule sources form a layered override system — enterprise policy can lock down rules completely with allowManagedPermissionRulesOnly, preventing any user overrides.
• Legacy rule names are auto-migrated — rules using old tool names (Task, KillShell) are transparently rewritten to current canonical names at parse time.