Extending your agent: tools, permissions, hooks, subagents, sessions, prompts, skills

INVENTORY = {"widget": 42, "gadget": 0, "sprocket": 7}

@tool(
    "get_stock",                                                   # (1) the name Claude will call
    "Look up how many units of a product are in stock",            # (2) Claude reads this to decide WHEN to use it
    {"product": Annotated[str, "Product name, lowercase"]},        # (3) simple schema: field -> type (+ description)
    annotations=ToolAnnotations(readOnlyHint=True),                # (4) "doesn't change anything" -> may run in parallel
)
async def get_stock(args):
    product = args["product"].lower().rstrip("s")
    if product not in INVENTORY:
        return {"content": [{"type": "text", "text": f"Unknown product: {product}"}], "is_error": True}   # (5) an error Claude can read
    return {"content": [{"type": "text", "text": f"{product}: {INVENTORY[product]} units"}]}             # (6) a normal result

@tool(
    "reorder", "Place a reorder for a product",
    {"type": "object",                                             # (7) full JSON Schema for enums / optional fields
     "properties": {"product": {"type": "string"},
                    "quantity": {"type": "integer", "minimum": 1, "maximum": 1000},
                    "priority": {"type": "string", "enum": ["normal", "rush"]}},
     "required": ["product", "quantity"]})                         # (8) priority is optional
async def reorder(args):
    priority = args.get("priority", "normal")
    INVENTORY[args["product"]] = INVENTORY.get(args["product"], 0) + args["quantity"]
    return {"content": [{"type": "text", "text": f"Reorder placed: {args['quantity']} x {args['product']} ({priority}). New stock: {INVENTORY[args['product']]}"}]}

inventory_server = create_sdk_mcp_server(name="inventory", version="1.0.0", tools=[get_stock, reorder])   # (9) bundle

options = ClaudeAgentOptions(
    mcp_servers={"inventory": inventory_server},   # (10) "inventory" becomes the middle of mcp__inventory__get_stock
    allowed_tools=["mcp__inventory__*"],           # (11) approve every tool on this server
    tools=[],                                      # (12) no built-in tools: this agent can ONLY use ours
)

MCP tools visible at init: ['mcp__inventory__get_stock', 'mcp__inventory__reorder']
MCP servers: [{'name': 'inventory', 'status': 'connected', 'source': 'sdk'}]
[tool call] mcp__inventory__get_stock({'product': 'widgets'})
[tool call] mcp__inventory__get_stock({'product': 'gadgets'})
[tool result] [{'type': 'text', 'text': 'widget: 42 units'}]
[tool result] [{'type': 'text', 'text': 'gadget: 0 units'}]
[tool call] mcp__inventory__get_stock({'product': 'doohickeys'})
[tool result] ERROR Unknown product: doohickey
[tool call] mcp__inventory__reorder({'product': 'gadget', 'quantity': 25, 'priority': 'rush'})
[tool result] [{'type': 'text', 'text': 'Reorder placed: 25 x gadget (rush). New stock: 25'}]

Final answer: Widgets: 42 in stock. Gadgets: were out of stock, so I placed a rush reorder for 25 (now at 25).
Doohickeys aren't a recognized product in inventory, so I couldn't check them.

Inventory after run: {'widget': 42, 'gadget': 25, 'sprocket': 7}

const convert = tool(
  "convert_temperature",
  "Convert a temperature between Celsius and Fahrenheit",
  { value: z.number().describe("The temperature value"), from: z.enum(["C", "F"]) },   // Zod shape
  async ({ value, from }) => {                                                          // typed args
    const result = from === "C" ? (value * 9) / 5 + 32 : ((value - 32) * 5) / 9;
    return { content: [{ type: "text", text: `${value}°${from} = ${result.toFixed(1)}°${from === "C" ? "F" : "C"}` }] };
  },
  { annotations: { readOnlyHint: true } },
);
const server = createSdkMcpServer({ name: "temps", version: "1.0.0", tools: [convert] });

tool_use: mcp__temps__convert_temperature({"value":100,"from":"F"})
tool_result: [{"type":"text","text":"100°F = 37.8°C"}]
tool_use: mcp__temps__convert_temperature({"value":37,"from":"C"})
tool_result: [{"type":"text","text":"37°C = 98.6°F"}]
answer: 100°F is 37.8°C, and 37°C is 98.6°F.

options = ClaudeAgentOptions(
    mcp_servers={
        # a local program, talking over stdin/stdout ("stdio")
        "filesystem": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]},
        # a remote server over HTTP, with an auth header
        "github": {"type": "http", "url": "https://api.githubcopilot.com/mcp/",
                   "headers": {"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}"}},
        # a remote server over SSE
        "remote-api": {"type": "sse", "url": "https://api.example.com/mcp/sse"},
    },
    allowed_tools=["mcp__filesystem__read_file", "mcp__github__list_issues", "mcp__remote-api__*"],
)

tool call ─► 1 hooks ─► 2 deny rules ─► 3 ask rules ─► 4 permission mode ─► 5 allow rules ─► 6 can_use_tool
              │ deny      │ deny          │ -> callback   │ bypass: approve     │ match: approve   │ allow / deny
              ▼           ▼               ▼               │ acceptEdits: edits  ▼                  ▼
            blocked     blocked         callback          ▼ ok                run                decision

async def can_use_tool(tool_name, input_data, context):
    if tool_name == "Bash" and "rm " in input_data.get("command", ""):                 # (1) inspect the COMMAND, not just the tool
        return PermissionResultDeny(message="User policy: deletion is not allowed. Leave the file in place.")  # (2) Claude reads this
    if tool_name == "Write":
        path = input_data["file_path"]
        if "/scratch/" not in path:
            new_path = path.rsplit("/", 1)[0] + "/scratch/" + path.rsplit("/", 1)[1]
            return PermissionResultAllow(updated_input={**input_data, "file_path": new_path})   # (3) approve with a changed input
    return PermissionResultAllow(updated_input=input_data)                             # (4) approve as requested

async def noop_hook(input_data, tool_use_id, context):   # (5) required with plain query(): keeps the control channel open
    return {"continue_": True}

async def prompt_stream():                                # (6) can_use_tool needs streaming input
    yield {"type": "user", "message": {"role": "user", "content": "Create a file named notes.txt containing 'hello', then delete it with rm."}}

async for message in query(prompt=prompt_stream(), options=ClaudeAgentOptions(
        cwd=PROJECT, permission_mode="default", can_use_tool=can_use_tool,
        hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[noop_hook])]})):
    ...

[tool_result] ERROR User policy: deletion is not allowed. Leave the file in place.

[result] success: I created notes.txt with "hello", but deletion is blocked by policy, so I left the file in place instead of running `rm`.
[result] permission_denials: [{'tool_name': 'Bash', 'tool_use_id': 'toolu_012B...', 'tool_input': {'command': 'cd ".../project" && echo \'hello\' > notes.txt && cat notes.txt && rm notes.txt && ls notes.txt 2>&1', ...}}]

Decisions made by can_use_tool:
   ('deny', 'Bash', 'cd ".../project" && echo \'hello\' > notes.txt && cat notes.txt && rm notes.txt && ls notes.txt 2>&1')

{"questions": [{"question": "How should I format the output?", "header": "Format",
                "options": [{"label": "Summary", "description": "Brief overview"}, {"label": "Detailed", "description": "Full explanation"}],
                "multiSelect": false}]}

async def my_hook(input_data, tool_use_id, context) -> dict:
    # input_data: hook_event_name, session_id, cwd, and event fields (PreToolUse: tool_name, tool_input, tool_use_id)
    # tool_use_id: links PreToolUse and PostToolUse for the same call
    return {}

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")               # (1) the Write/Edit input
    if file_path.split("/")[-1] in (".env", ".env.local"):
        return {"hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",                                    # (2) block it
            "permissionDecisionReason": "Policy: .env files may not be created or modified by the agent"}}
    return {}                                                                # (3) no opinion

async def audit(input_data, tool_use_id, context):
    audit_log.append((input_data["tool_name"], tool_use_id)); return {}      # (4) every successful tool call

options = ClaudeAgentOptions(
    cwd=PROJECT, permission_mode="acceptEdits", allowed_tools=["Read", "Write", "Edit", "Glob"],
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])],   # (5) only Write/Edit
           "PostToolUse": [HookMatcher(hooks=[audit])]})                                   # (6) every tool

[tool_result] ERROR PreToolUse:Write hook error: Policy: .env files may not be created or modified by the agent
[tool_result] File created successfully at: .../project/config.example.txt ...
Claude: I created `config.example.txt` with that line, but a security policy blocks me from creating or
modifying `.env` files — you'll need to create that one yourself.
[result] success, denials=[{'tool_name': 'Write', 'tool_use_id': 'toolu_01Bh...', 'tool_input': {'file_path': '.../project/.env', 'content': 'DATABASE_URL=sqlite:///users.db\n'}}]

Audit log (PostToolUse): [('Write', 'toolu_01FA...')]

  tool: Edit .../src/utils.py
  tool: Bash python3 -m unittest -q tests.test_utils
  [Stop hook] iteration 1: tests PASS, CHANGELOG.md missing, stop_hook_active=False     <- blocked
  tool: Bash ls -la
  tool: Write .../CHANGELOG.md
  [Stop hook] iteration 2: tests PASS, CHANGELOG.md present, stop_hook_active=True     <- allowed
[result] success after 7 turns, $0.0575

options = ClaudeAgentOptions(
    cwd=PROJECT,
    allowed_tools=["Read", "Grep", "Glob", "Agent"],          # (1) the parent needs Agent to delegate
    agents={
        "security-reviewer": AgentDefinition(
            description="Security code reviewer. Use for finding vulnerabilities in source files.",   # (2) WHEN to use it
            prompt="You are a security reviewer. Report each vulnerability as file:line and one sentence. Be brief. Never edit files.",  # (3) its system prompt
            tools=["Read", "Grep", "Glob"],                     # (4) read-only
            model="haiku",                                      # (5) cheaper model
        ),
    },
    hooks={"SubagentStart": [HookMatcher(hooks=[on_subagent_start])],
           "SubagentStop": [HookMatcher(hooks=[on_subagent_stop])]},
)
async for message in query(prompt="Use the security-reviewer agent to review src/app.py, then repeat its findings verbatim.", options=options):
    if isinstance(message, AssistantMessage):
        inside = " (inside subagent)" if message.parent_tool_use_id else ""       # (6) messages from inside carry parent_tool_use_id
        for block in message.content:
            if isinstance(block, ToolUseBlock) and block.name in ("Agent", "Task"):   # (7) the delegation call
                print(f"Subagent invoked: subagent_type={block.input.get('subagent_type')}")

  tool: Glob
Subagent invoked: subagent_type=security-reviewer model=None
  [hook SubagentStart] type=security-reviewer id=a0401eaaf13c8f1e0
  tool (inside subagent): Read
  [hook SubagentStop]  type=security-reviewer transcript=~/.claude/projects/.../subagents/agent-a0401eaaf13c8f1e0.jsonl

Final result:
 **1. SQL Injection (src/app.py:11)** ...
 **2. Hardcoded API Key (src/app.py:5)** ...
 **3. Missing Resource Cleanup on Exception (src/app.py:9-12)** ...

Per-model usage:
  claude-sonnet-5: in=6 out=599 cost=$0.0561
  claude-haiku-4-5-20251001: in=7791 out=564 cost=$0.0106

async def run(prompt, **opts):                                  # (1) one-shot helper returning (session_id, text)
    async for message in query(prompt=prompt, options=ClaudeAgentOptions(cwd=PROJECT, max_turns=4, **opts)):
        if isinstance(message, ResultMessage):
            return message.session_id, message.result

sid, _  = await run("Remember this code word: PELICAN. Reply only with 'noted'.", allowed_tools=[])
rid, t  = await run("What was the code word? One word.", resume=sid)                                  # (2) resume
fid, t  = await run("Change the code word to HERON and reply 'changed'.", resume=sid, fork_session=True) # (3) fork
_,   t  = await run("What is the code word? One word.", resume=sid)                                   # (4) original untouched?

rename_session(sid, "codeword-demo", directory=PROJECT)         # (5) on-disk housekeeping
info   = get_session_info(sid, directory=PROJECT)
recent = list_sessions(directory=PROJECT, limit=3)
msgs   = get_session_messages(sid, directory=PROJECT)

Original session: 1a2076ae-3291-4142-81df-ab350207c695 -> 'noted'
Resumed session:  1a2076ae-3291-4142-81df-ab350207c695 -> 'PELICAN'  (same id: True)
Forked session:   a0577f7e-79e3-446d-aa6b-735719e26400 -> 'changed'  (new id: True)
Original again:        -> 'PELICAN'

get_session_info: title='codeword-demo' first_prompt="Remember this code word: PELICAN. ..." cwd=.../demo/project
list_sessions (latest 3):
  1a2076ae-...  'codeword-demo'
  a0577f7e-...  "Remember this code word: PELICAN. Reply only with 'noted'."
  56b76917-...  'Reply: ok'
get_session_messages: 6 messages, roles=['user', 'assistant', 'user', 'assistant', 'user', 'assistant']

class SessionStore(Protocol):
    async def append(self, key: SessionKey, entries: list[SessionStoreEntry]) -> None: ...   # write entries, in order
    async def load(self, key: SessionKey) -> list[SessionStoreEntry] | None: ...              # read them back (None if unknown)
    # optional: list_sessions, list_session_summaries, delete, list_subkeys

store = InMemorySessionStore()                     # for tests; S3/Redis/Postgres adapters ship in the SDK repos' examples/
async for m in query(prompt="List the Python files under src/", options=ClaudeAgentOptions(session_store=store)):
    if isinstance(m, ResultMessage): session_id = m.session_id
async for m in query(prompt="Summarize what those files do", options=ClaudeAgentOptions(session_store=store, resume=session_id)):
    ...   # resumed from the store, possibly on another host

[default (minimal)]           "I'm Claude, an AI coding agent built on Anthropic's Claude Agent SDK that can help you read, write, and debug code and work with files in your project directory via a terminal-based interface."
[claude_code preset + append] "I'm Claude Code, Anthropic's CLI assistant, here to help you with software engineering tasks like coding, debugging, and running commands in your project.\n\nBANANA"
[custom string]               "Arrr, I be Claude, a scurvy code-slingin' agent here to help ye navigate files and tasks on yer machine!"

setting_sources=['project']: 'Yes. "Use type hints on all new or edited functions."'
setting_sources=[]:          "No. I don't have any project-specific instructions ... about type hints"

---
name: security-check
description: Run a security vulnerability scan over the project source
---
Analyze every file under `src/` for security vulnerabilities, including:
- SQL injection risks
- Exposed credentials
- Insecure configurations
Report each finding as `file:line - severity - one sentence`. Do not edit files.

async for message in query(
    prompt="/security-check",                                  # (1) dispatch by name
    options=ClaudeAgentOptions(cwd=PROJECT, setting_sources=["project"], skills="all",   # (2) load project skills, allow all
                               allowed_tools=["Read", "Grep", "Glob"], max_turns=8)):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        print("skills loaded:", message.data.get("skills"))    # (3) confirm

skills loaded: ['security-check', 'verify', 'debug', 'code-review', 'simplify', ...]
'security-check' in slash_commands: True
  tool: Bash
  tool: Read
  tool: Read
  tool: Read
result:
 - `src/app.py:5` - High - Hardcoded live API key (`sk-live-...`) committed in source instead of loaded from environment/secrets store.
 - `src/app.py:11` - Critical - SQL query built via f-string interpolation of unsanitized `name` parameter, enabling SQL injection.

options = ClaudeAgentOptions(plugins=[{"type": "local", "path": "./my-plugin"}])   # skills appear as /my-plugin:skill-name

my-plugin/
├── .claude-plugin/plugin.json   # optional
├── skills/my-skill/SKILL.md
├── agents/specialist.md
├── hooks/hooks.json
└── .mcp.json