Claude Agent SDK

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.

TypeScript
Python

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 */) },
})) {
  // ...
}

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.

Overview

CLI

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Gateways

Vector Databases

Custom / Other

Guides

Claude Agent SDK