Claude Sdk Permissions

Permissions in the Claude Agent SDK

Three layers control what Claude can do:

1. allowed_tools / disallowed_tools — static allowlists / blocklists by tool name.
2. permission_mode — one of six policies that govern unspecified tools.
3. can_use_tool — a callback for dynamic, per-call decisions.

Get this right once and you don't think about it again. Get it wrong and either the agent stalls on prompts you can't answer (server deploys) or runs commands you didn't intend.

The big mental model

allowed_tools is pre-approval, not availability. Listing a tool there means "don't prompt; just run it." Tools available to Claude come from the underlying tool surface (built-in tools the SDK exposes, plus any mcp_servers you wire). disallowed_tools is the only knob that removes availability.

Two implications:

• A tool not in allowed_tools isn't blocked — it just triggers the permission flow set by permission_mode.
• A tool in allowed_tools that doesn't actually exist (typo, wrong server prefix) silently does nothing.

The six permission_mode values

Production server deploys

Two safe configurations for a server that runs unattended:

# Strict — only what you've enumerated runs.
ClaudeAgentOptions(
    permission_mode="dontAsk",
    allowed_tools=[
        "mcp__tools__lookup_user",
        "mcp__tools__send_email",
        "mcp__fs__read_file",
    ],
    disallowed_tools=["Bash"],   # belt-and-suspenders
)

# Looser — accept edits but explicit about destructive surfaces.
ClaudeAgentOptions(
    permission_mode="acceptEdits",
    disallowed_tools=["Bash"],
    allowed_tools=["mcp__tools__safe_op"],
)

The second is right when the agent is editing code in a sandbox. The first is right for any agent acting on shared state (DBs, email, user data).

permission_mode="bypassPermissions" is rarely the right answer. The only legitimate case: the agent runs in a one-shot Docker container with no persistent state and no network access to anything that matters. If you're tempted to use it because prompts are annoying in dev, switch to dontAsk and explicitly list what you trust.

The can_use_tool callback

For decisions that can't be expressed as a static list:

async def can_use_tool(tool_name: str, tool_input: dict, context):
    # Block writes outside /workspace
    if tool_name in ("Write", "Edit"):
        path = tool_input.get("file_path", "")
        if not path.startswith("/workspace/"):
            return {"behavior": "deny", "message": f"Outside workspace: {path}"}

    # Rate-limit expensive tool
    if tool_name == "mcp__tools__expensive_query":
        if rate_limiter.is_throttled():
            return {"behavior": "deny", "message": "Rate limited; try again in 30s"}

    return {"behavior": "allow", "updatedInput": tool_input}

options = ClaudeAgentOptions(can_use_tool=can_use_tool)

The callback can also rewrite the input via updatedInput — useful for redaction (strip secrets from arguments before they hit a tool) and normalization (ensure paths are absolute, etc).

can_use_tool runs after allowed_tools would have approved a call. If you want it to gate everything, leave allowed_tools empty and let the callback decide.

Common mistakes

• Empty allowed_tools with permission_mode="default" in a server deploy. Claude prompts on every call; the server has no human to answer; everything stalls. Either populate allowed_tools or switch to dontAsk.
• Forgetting the mcp__server__ prefix. allowed_tools=["lookup_user"] doesn't pre-approve mcp__tools__lookup_user. Use the full name.
• Trusting bypassPermissions because it's convenient. Production-grade agents start strict and relax deliberately. Easy to widen access later; hard to recover from rm -rf running unattended.
• disallowed_tools collision with allowed_tools. disallowed_tools wins. If you list Bash in both, Claude can't call it.

Picking a default for a new agent

For nuvel-scaffolded server agents, the default is acceptEdits — change it to dontAsk once you know exactly which tools the agent should call.