# 2459 Agent Sdk Permissions Dd0efe6c

> SDK Permissions

- Skill: `tools-only/2459-agent-sdk-permissions-dd0efe6c` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/2459-agent-sdk-permissions-dd0efe6c`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/2459-agent-sdk-permissions-dd0efe6c/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/2459-agent-sdk-permissions-dd0efe6c

---


# SDK Permissions

The Claude Agent SDK provides powerful permission controls that allow you to manage how Claude uses tools in your application.

This guide covers how to implement permission systems using the `canUseTool` callback, hooks, and settings.json permission rules. For complete API documentation, see the [TypeScript SDK reference](https://platform.claude.com/docs/en/agent-sdk/typescript).

## Overview

The Claude Agent SDK provides four complementary ways to control tool usage:

1. **[Permission Modes](https://platform.claude.com/docs/en/agent-sdk/permissions#permission-modes)** - Global permission behavior settings that affect all tools
2. **[canUseTool callback](https://platform.claude.com/docs/en/agent-sdk/typescript#canusetool)** - Runtime permission handler for cases not covered by other rules
3. **[Hooks](https://platform.claude.com/docs/en/agent-sdk/typescript#hook-types)** - Fine-grained control over every tool execution with custom logic
4. **[Permission rules (settings.json)](https://code.claude.com/docs/en/settings#permission-settings)** - Declarative allow/deny rules with integrated bash command parsing

Use cases for each approach:

- 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

    %%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D"}, "flowchart": {"edgeLabelMarginX": 12, "edgeLabelMarginY": 8}}}%%
    flowchart TD
        Start([Tool request]) --> PreHook(PreToolUse Hook)

        PreHook -->|  Allow  | Execute(Execute Tool)
        PreHook -->|  Deny  | Denied(Denied)
        PreHook -->|  Ask  | Callback(canUseTool Callback)
        PreHook -->|  Continue  | Deny(Check Deny Rules)

        Deny -->|  Match  | Denied
        Deny -->|  No Match  | Allow(Check Allow Rules)

        Allow -->|  Match  | Execute
        Allow -->|  No Match  | Ask(Check Ask Rules)

        Ask -->|  Match  | Callback
        Ask -->|  No Match  | Mode{Permission Mode?}

        Mode -->|  bypassPermissions  | Execute
        Mode -->|  Other modes  | Callback

        Callback -->|  Allow  | Execute
        Callback -->|  Deny  | Denied

        Denied --> DeniedResponse([Feedback to agent])

        Execute --> PostHook(PostToolUse Hook)
        PostHook --> Done([Tool Response])

        style Start fill:#F0F0EB,stroke:#D9D8D5,color:#191919

        style Denied fill:#BF4D43,color:#fff
        style DeniedResponse fill:#BF4D43,color:#fff
        style Execute fill:#DAAF91,color:#191919
        style Done fill:#DAAF91,color:#191919

        classDef hookClass fill:#CC785C,color:#fff
        class PreHook,PostHook hookClass

        classDef ruleClass fill:#EBDBBC,color:#191919
        class Deny,Allow,Ask ruleClass

        classDef modeClass fill:#A8DAEF,color:#191919
        class Mode modeClass

        classDef callbackClass fill:#D4A27F,color:#191919
        class Callback callbackClass

**Processing Order:** PreToolUse Hook → Deny Rules → Allow Rules → Ask Rules → Permission Mode Check → canUseTool Callback → PostToolUse Hook

## Permission Modes

Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling `query()` or change it dynamically during streaming sessions.

### Available Modes

The SDK supports four permission modes, each with different behavior:

| Mode | Description | Tool Behavior |
|----|----|----|
| `default` | Standard permission behavior | Normal permission checks apply |
| `plan` | Planning mode - no execution | Claude can only use read-only tools; presents a plan before execution **(Not currently supported in SDK)** |
| `acceptEdits` | Auto-accept file edits | File edits and filesystem operations are automatically approved |
| `bypassPermissions` | Bypass all permission checks | All tools run without permission prompts (use with caution) |

### Setting Permission Mode

You can set the permission mode in two ways:

#### 1\. Initial Configuration

Set the mode when creating a query:

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

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

#### 2\. Dynamic Mode Changes (Streaming Only)

Change the mode during a streaming session:

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

    // 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`)

In accept edits mode:

- 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

Auto-approved operations:

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

#### Bypass Permissions Mode (`bypassPermissions`)

In bypass permissions mode:

- **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

Permission modes are evaluated at a specific point in the permission flow:

1. **Hooks execute first** - Can allow, deny, ask, or continue
2. **Deny rules** are checked - Block tools regardless of mode
3. **Allow rules** are checked - Permit tools if matched
4. **Ask rules** are checked - Prompt for permission if matched
5. **Permission mode** is evaluated:
    - **`bypassPermissions` mode** - If active, allows all remaining tools
    - **Other modes** - Defer to `canUseTool` callback
6. **`canUseTool` callback** - Handles remaining cases

This means:

- Hooks can always control tool use, even in `bypassPermissions` mode
- Explicit deny rules override all permission modes
- Ask rules are evaluated before permission modes
- `bypassPermissions` mode overrides the `canUseTool` callback for unmatched tools

### 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

Example of mode progression:

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

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

## canUseTool

The `canUseTool` callback is passed as an option when calling the `query` function. It receives the tool name and input parameters, and must return a decision- either allow or deny.

canUseTool fires whenever Claude Code would show a permission prompt to a user, e.g. hooks and permission rules do not cover it and it is not in acceptEdits mode.

Here's a complete example showing how to implement interactive tool approval:

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

    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);
        }
      }
    });

## Related Resources

- [Hooks Guide](https://code.claude.com/docs/en/hooks-guide) - Learn how to implement hooks for fine-grained control over tool execution
- [Settings: Permission Rules](https://code.claude.com/docs/en/settings#permission-settings) - Configure declarative allow/deny rules with bash command parsing