~18 min · options, configuration, ClaudeAgentOptions
Level 0Observer
0 XP0/64 lessons0/13 achievements
0/150 XP to next level150 XP to go0% complete
The configuration object
ClaudeAgentOptions is the single place every agent decision lives. Working directory, system prompt, allowed tools, MCP servers, hooks, model selection, max thinking tokens, environment variables — all of it. Treat it like a typed config struct, not a free-for-all kwargs blob.
The fields you will touch most
cwd (working directory), system_prompt (preset, string, or list of blocks), allowed_tools (list of tool names; restrict from the default set), model (which Claude tier), permission_mode ('default' / 'acceptEdits' / 'bypassPermissions' / 'plan'), mcp_servers (dict mapping server name to launch config), hooks (PreToolUse, PostToolUse, etc.), env (environment variables for the subprocess).
Avoid bypassPermissions in production
permission_mode='bypassPermissions' disables every permission gate. Useful for trusted CI scripts, dangerous for anything user-facing. Default to 'default' (interactive prompts) or 'acceptEdits' (auto-accept file writes only) and document why if you ever need to bypass.
Principle: Options is policy. The agent's behavior is the options object's shape, not the prompt's wording.
Code
A production-shaped options object·python
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
cwd="/srv/myapp",
model="claude-sonnet-4-6",
system_prompt="You are a deployment review assistant. Read CHANGELOG.md and report risks.",
allowed_tools=["Read", "Grep", "Bash"], # no Write, no Edit
permission_mode="default", # ask before any tool use
env={"PATH": "/usr/local/bin:/usr/bin"},
max_thinking_tokens=8192,
)
Restricting tools to read-only·python
# The Agent SDK ships a default tool list; you whitelist a subset for a given agent.
READ_ONLY_TOOLS = ["Read", "Grep", "Glob", "WebFetch"]
options = ClaudeAgentOptions(
cwd="/data/audit",
allowed_tools=READ_ONLY_TOOLS,
permission_mode="acceptEdits", # irrelevant since no edit tools allowed
system_prompt="You are a read-only auditor. Never modify files.",
)
For one Agent SDK call in your code, audit the options object. Verify model is pinned, allowed_tools is the smallest set that works, permission_mode is conservative, and system_prompt is structured (not stream-of-consciousness).
Hint
If you cannot remember why a tool is allowed, remove it. If breakage exposes the need, add it back with a comment.
Progress
Progress is local-only — sign in to sync across devices.