> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Agent SDK

> Trace the tool calls of agents you build with the Claude Agent SDK (TypeScript and Python) with Zespan hooks.

> [!NOTE]
>
> Available via: the **Zespan hooks** (TypeScript and Python). This is for agents you build and run with the Claude Agent SDK library. It is not a plugin for the Claude Code application.

The Claude Agent SDK runs hooks around every tool use. Zespan's hooks turn each tool use into one Zespan `tool` span with its name, arguments, result and error status, so the tool-level checks of the domain packs can read it.

| Hook | What Zespan does |
| - | - |
| `PreToolUse` | remembers the call (name, arguments, start time) |
| `PostToolUse` | sends one tool span with the result |
| `PostToolUseFailure` | sends one tool span with `status: error` and the error text |
| `SessionEnd`, `Stop` | closes any tool use that never got a post hook, as an error ("the tool did not finish before the session ended") |

The hooks only observe. They return an empty output, so permissions and tool results are never changed, and nothing in them throws into your agent.

> [tab] TypeScript
>
> ```ts theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
> import { query } from "@anthropic-ai/claude-agent-sdk";
> import { initZespan, claudeAgentHooks } from "@zespan/sdk";
>
> initZespan({ apiKey: "zsp_..." });
>
> for await (const message of query({
>   prompt: "Fix the failing test",
>   options: { hooks: claudeAgentHooks(/* your existing hooks, or nothing */) },
> })) {
>   // ...
> }
> ```

> [tab] Python
>
> ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
> import zespan
> from claude_agent_sdk import ClaudeAgentOptions, query
> from zespan.integrations.claude_agent_sdk import claude_agent_hooks
>
> zespan.init(api_key="zsp_...")
> options = ClaudeAgentOptions(hooks=claude_agent_hooks())  # or claude_agent_hooks(your_hooks)
> async for message in query(prompt="Fix the failing test", options=options):
>     ...
> ```
>
> Install with `pip install zespan[claude-agent-sdk]`.

Your own hooks keep running first; Zespan's are added after them and your hook object is not changed. Setting `storeToolIO: false` (`store_tool_io=False`) drops arguments and results and keeps the tool name and status. Set `ZESPAN_CLAUDE_AGENT=off` to stop the hooks without a code change.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.