Claude Agent SDK¶

Real-time failure detection for agents built on the Claude Agent SDK, via pisama-agent-sdk.

This is hook-based, not trace-ingestion-based: detectors run inside the agent's own lifecycle while it is still executing, rather than over a completed trace.

Scope, stated plainly¶

pisama-agent-sdk ships two hooks, PreToolUse and PostToolUse. The covered surface is therefore tool-call behaviour: repeated tool errors, loops across the tool-call sequence, and destructive-command patterns.

Stop, SubagentStop and Notification hooks are not implemented. Anything you read elsewhere claiming five lifecycle hooks is wrong; that claim was corrected on 2026-07-28.

For multi-agent and sub-agent coordination analysis, ingest completed Claude Code sessions through pisama-claude-code instead. That is a separate path over a finished trace, and it is where the coordination detectors run.

Install¶

pip install pisama-agent-sdk

If you also want create_check_tool(), which registers a self-check tool the agent can call, pull in the SDK itself:

pip install "pisama-agent-sdk[claude]"

The base install deliberately does not depend on claude-agent-sdk. The hooks operate on the plain dict payloads the SDK hands them, so they work without it.

Passive monitoring¶

from pisama_agent_sdk import pre_tool_use_hook, post_tool_use_hook

agent.hooks.pre_tool_use = pre_tool_use_hook
agent.hooks.post_tool_use = post_tool_use_hook

Every tool call is now checked. When a detector fires, the hook returns a blocking signal, so the failure is caught before the next tool call rather than reported afterwards.

Active self-check¶

from pisama_agent_sdk import check

result = await check(
    output="The server is healthy based on the metrics.",
    context={"query": "Is auth-service down?", "sources": [...]},
)
if not result["passed"]:
    print(result["issues"])

As a tool the agent can call¶

from pisama_agent_sdk import create_check_tool
from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(custom_tools=[create_check_tool()])

Framework identifier¶

Traces and fix suggestions from this SDK use claude_sdk. Note this is not the same as claude_code, which identifies Claude Code session traces, a different product with its own detector pack.

Fix suggestions scoped to a framework only match when the caller populates DiagnosisResult.framework. It defaults to None, and the hooks forward result.framework or "", so a caller that never sets it will silently receive no framework-scoped fixes. If you expect managed_agents or claude_sdk fixes and see none, check that field first.

Detectors that apply¶

Tool failure cascade, loop detection, destructive command, plus the cross-cutting single-agent detectors on the reported output.

Per-detector measured F1 lives on the detection overview, generated from the capability registry. A number printed on an integration page implies it was measured on that integration's traces, which is not what the calibration lane measures.