​

SDK Permissions

​

Overview

1. Permission Modes - Global permission behavior settings that affect all tools
2. canUseTool callback - Runtime permission handler for cases not covered by other rules
3. Hooks - Fine-grained control over every tool execution with custom logic
4. Permission rules (settings.json) - Declarative allow/deny rules with integrated bash command parsing

• Permission modes - Set overall permission behavior (planning, auto-accepting edits, bypassing checks)
• canUseTool - Dynamic approval for uncovered cases, prompts user for permission
• Hooks - Programmatic control over all tool executions
• Permission rules - Static policies with intelligent bash command parsing

​

Permission Flow Diagram

​

Permission Modes

​

Available Modes

​

Setting Permission Mode

​

1. Initial Configuration

import { query } from "@anthropic-ai/claude-code";

const result = await query({
  prompt: "Help me refactor this code",
  options: {
    permissionMode: 'default'  // Standard permission mode
  }
});

​

2. Dynamic Mode Changes (Streaming Only)

import { query } from "@anthropic-ai/claude-code";

// Create an async generator for streaming input
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "Let's start with default permissions" 
    }
  };
  
  // Later in the conversation...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "Now let's speed up development"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // Start in default mode
  }
});

// Change mode dynamically
await q.setPermissionMode('acceptEdits');

// Process messages
for await (const message of q) {
  console.log(message);
}

​

Mode-Specific Behaviors

​

Accept Edits Mode (acceptEdits)

• All file edits are automatically approved
• Filesystem operations (mkdir, touch, rm, etc.) are auto-approved
• Other tools still require normal permissions
• Speeds up development when you trust Claude’s edits
• Useful for rapid prototyping and iterations

• File edits (Edit, MultiEdit, Write tools)
• Bash filesystem commands (mkdir, touch, rm, mv, cp)
• File creation and deletion

​

Bypass Permissions Mode (bypassPermissions)

• ALL tool uses are automatically approved
• No permission prompts appear
• Hooks still execute (can still block operations)
• Use with extreme caution - Claude has full system access
• Recommended only for controlled environments

​

Mode Priority in Permission Flow

1. Hooks execute first - Can override any mode
2. Deny rules are checked - Block tools regardless of mode
3. bypassPermissions mode - If active, allows all remaining tools
4. Allow rules are checked
5. Other modes affect specific tool behaviors
6. canUseTool callback - Handles remaining cases

• Hooks can always block tool use, even in bypassPermissions mode
• Explicit deny rules override all permission modes
• bypassPermissions mode overrides allow rules and canUseTool

​

Best Practices

1. Use default mode for controlled execution with normal permission checks
2. Use acceptEdits mode when working on isolated files or directories
3. Avoid bypassPermissions in production or on systems with sensitive data
4. Combine modes with hooks for fine-grained control
5. Switch modes dynamically based on task progress and confidence

// Start in default mode for controlled execution
permissionMode: 'default'

// Switch to acceptEdits for rapid iteration
await q.setPermissionMode('acceptEdits')

​

canUseTool

import { query } from "@anthropic-ai/claude-code";

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 Tool Request:");
  console.log(`   Tool: ${toolName}`);
  
  // Display tool parameters
  if (input && Object.keys(input).length > 0) {
    console.log("   Parameters:");
    for (const [key, value] of Object.entries(input)) {
      let displayValue = value;
      if (typeof value === 'string' && value.length > 100) {
        displayValue = value.substring(0, 100) + "...";
      } else if (typeof value === 'object') {
        displayValue = JSON.stringify(value, null, 2);
      }
      console.log(`     ${key}: ${displayValue}`);
    }
  }
  
  // Get user approval (replace with your UI logic)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ Approved\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ Denied\n");
    return {
      behavior: "deny",
      message: "User denied permission for this tool"
    };
  }
}

// Use the permission callback
const result = await query({
  prompt: "Help me analyze this codebase",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

​

Using Hooks for Tool Control

​

Hook Implementation

import { query } from "@anthropic-ai/claude-code";

const result = await query({
  prompt: "Help me refactor this code",
  options: {
    hooks: {
      PreToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Tool request: ${input.tool_name}`);
          
          // Parse and validate tool input yourself
          if (input.tool_name === "Bash") {
            const command = input.tool_input.command;
            if (command.startsWith("rm -rf")) {
              return {
                decision: "block",
                reason: "Dangerous command blocked"
              };
            }
          }
          
          return { continue: true };
        }]
      }],
      PostToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Tool completed: ${input.tool_name}`);
          // Log or audit tool results
          return { continue: true };
        }]
      }]
    }
  }
});

​

Key Differences from canUseTool

• Scope: Hooks are called for all tool uses; canUseTool handles cases not covered by permission rules
• Control: Hooks require parsing and validating inputs yourself
• Events: Hooks support multiple events (PreToolUse, PostToolUse, etc.) for different stages

​

Using Permission Rules (settings.json)

​

Configuration Structure

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./secrets/**)",
      "WebFetch"
    ],
    "ask": [
      "Bash(git push:*)",
      "Write(./production/**)"
    ]
  }
}

​

Rule Syntax

• Bash rules: Use prefix matching (not regex). Example: Bash(npm:*) matches any command starting with “npm”
• File rules: Support glob patterns. Example: Read(./src/**/*.ts) matches TypeScript files in src
• Tool-only rules: Omit parentheses to control entire tools. Example: WebFetch blocks all web fetches

​

Using with SDK

​

Permission Evaluation Order

1. Deny rules are checked first - if matched, tool use is blocked
2. Allow rules are checked next - if matched, tool use is permitted
3. Ask rules are checked - if matched, user is prompted
4. canUseTool callback is invoked for any remaining cases

​

Bash Command Parsing

• Handles pipes, redirects, and command substitution
• Recognizes dangerous patterns like rm -rf or curl | sh
• Supports wildcards and prefix matching

• Bash(git:*) - Matches any git command
• Bash(npm run test) - Matches exact command
• Bash(npm run test:*) - Matches npm run test:unit, test:integration, etc.

​

Best Practices

1. Start with default mode for standard permission checks
2. Use permission rules for static policies, especially bash commands (see permission settings)
3. Use hooks to log, audit, or transform all tool uses (see hook types)
4. Use canUseTool for dynamic decisions on uncovered cases (see CanUseTool type)
5. Layer defenses by combining modes, rules, hooks, and callbacks for critical applications