F5.3 F5

ClaudeAgentOptions: Configuring What an Agent Can Do

The Agent SDK’s value is in its rich configuration. ClaudeAgentOptions is where you define an agent’s behavior, capabilities, safety limits, and integrations — far beyond what the raw Messages API offers.

Key configuration fields

  • system_prompt — persistent behavioral instructions. Role, tone, decision-making guidelines. This frames everything the agent does.
  • allowed_tools — whitelist of available tools. Only listed tools exist for the agent. Everything else is structurally unavailable.
  • permission_mode — controls approval workflow (default, acceptEdits, full, plan). Determines whether tool calls need user confirmation.
  • max_turns — caps the number of reasoning-action cycles. Safety mechanism against infinite loops.
  • hooks — event handlers for tool calls and other agent events.
  • mcp_servers — external MCP servers for additional tools and data sources.

There is no auto_learn field. Agents don’t self-modify their prompts. Improvement requires manual developer updates.

allowed_tools: whitelist, not blacklist

allowed_tools works as a whitelist: allowed_tools=["Read", "WebSearch"] means the agent has exactly Read and WebSearch. Bash, Write, Edit — none of them exist for this agent. There’s no blocked_tools blacklist. No per-tool tool_permissions dictionary. You list what’s in, everything else is out.

This is structural enforcement. The model cannot decide to use a tool that isn’t on the list, regardless of how clever or urgent the situation seems. Contrast this with prompt-based restrictions (“never use Bash”) which the model may ignore under certain conditions.

allowed_tools vs permission_mode

These control different dimensions:

  • allowed_tools = which tools exist (capability). A research agent with allowed_tools=["Read", "WebSearch"] cannot use Bash regardless of permission mode.
  • permission_mode = how tool calls are approved (oversight). A full-access agent with permission_mode="default" has all tools but needs confirmation for each use.

An agent can have broad tools with strict oversight (many tools, default mode). Or narrow tools with no oversight (few tools, full mode). They’re independent controls.

Practical configuration

A research agent that should only search and read:

options = ClaudeAgentOptions(
    system_prompt="You are a research assistant...",
    allowed_tools=["Read", "WebSearch"],
    permission_mode="full",
    max_turns=20
)

The agent can search the web and read files autonomously (full mode), but cannot execute shell commands or modify files (not in allowed_tools). If it gets stuck in a loop, it stops after 20 turns.

One-liner: ClaudeAgentOptions configures agent behavior through system_prompt, restricts capabilities via whitelist-based allowed_tools, and controls oversight with permission_mode — two independent dimensions of tool access.