Real-time failure detection for the Claude Agent SDK

The Claude Agent SDK exposes lifecycle hooks (PreToolUse, PostToolUse, Stop, SubagentStop, Notification). Pisama hooks into all five and runs detectors in-flight. Failures are caught while the agent is still running, not post-hoc.

Sub-agent coordination is the headline feature: when a parent agent spawns a sub-agent, Pisama tracks the message graph and detects coordination drift, withholding (sub-agent has the answer, parent does not surface it), and loops across the parent/sub-agent boundary.

Detectors specific to Claude Agent SDK

  • Sub-agent coordination
    Parent never references sub-agent output
  • Tool failure cascade
    F1 0.900: repeated tool errors mid-session
  • Loop detection
    F1 0.830: parent ↔ sub-agent message cycles
  • Persona drift
    F1 0.794: sub-agent operates outside delegated scope
  • Information withholding
    F1 0.867: sub-agent has answer, parent omits

Install

pip install pisama pisama-agent-sdk
from pisama.agent_sdk import register_hooks

register_hooks()  # PreToolUse, PostToolUse, Stop, SubagentStop, Notification
# detectors fire on every hook. No separate instrumentation step

FAQ

What does "real-time" mean here?
Detectors run synchronously in the PostToolUse and SubagentStop hooks. If a tier-1/T2 detector fires, the failure is reported (and optionally injected back into the agent context as a Notification) before the next tool call. T3/T4 run async and report after the run.
Does this work with Claude Code skills and slash commands?
Yes. The hooks are SDK-level, so Claude Code, Claude Desktop with the SDK, and any custom Claude Agent SDK runner are covered. Slash commands appear as PreToolUse spans in the trace.

See the full detector taxonomy at /taxonomy, benchmark numbers at /benchmarks, or compare against other observability stacks at /vs.