[Abhijeet Prasad (AbhiPrasad)]

Fixes #973

AI Summary

Problem

Hook spans filter the hook's input_data through _HOOK_ALLOWED_FIELDS, a top-level allowlist. The allowlist is there to keep local paths such as cwd and transcript_path out of Braintrust. Any key not on the list is dropped.

claude-agent-sdk 0.2.166 (bundled Claude Code CLI) started sending more hook input fields. None of them were on the allowlist, so they never reached the span. error and is_interrupt on PostToolUseFailure were already missing before that release.

CLI hook input (PostToolUseFailure)          hook span input (before)
┌──────────────────────────────────┐         ┌──────────────────────────┐
│ hook_event_name  PostToolUseFail │ ──────▶ │ hook_event_name          │
│ session_id                       │ ──────▶ │ session_id               │
│ tool_name        Bash            │ ──────▶ │ tool_name                │
│ tool_input       {...}           │ ──────▶ │ tool_input               │
│ error            "Exit code 7"   │ ──╳     │                          │
│ is_interrupt     false           │ ──╳     │                          │
│ duration_ms      41              │ ──╳     │                          │
│ prompt_id        "4f1c…"         │ ──╳     │                          │
│ cwd / transcript_path            │ ──╳     │  (dropped on purpose)    │
└──────────────────────────────────┘         └──────────────────────────┘

Field	Hooks
prompt_id, effort	all hooks (BaseHookInput)
duration_ms	PostToolUse, PostToolUseFailure
error, is_interrupt	PostToolUseFailure
last_assistant_message	Stop, SubagentStop

So a failed tool's hook span didn't say why it failed, and hook spans couldn't be linked to the prompt they ran for.

Fix

Add the fields to the allowlist in py/src/braintrust/integrations/claude_agent_sdk/tracing.py:

 _HOOK_ALLOWED_FIELDS = frozenset(
     {
         # Common input fields
         "session_id",
         "hook_event_name",
+        "prompt_id",
+        "effort",
         # Event-specific input fields
         "tool_name",
         "tool_input",
         "tool_response",
+        "duration_ms",
+        "error",
+        "is_interrupt",
         "prompt",
         "message",
         "stop_hook_active",
+        "last_assistant_message",
         ...

It stays an allowlist, so cwd, transcript_path and agent_transcript_path are still dropped.

Decisions:

• background_tasks / session_crons stay excluded, as the issue asked. They are lists of shell commands and cron prompts that can be large and contain user content, so they need a separate decision.
• duration_ms goes in the span input only, not the metrics. It measures how long the tool ran. The hook span's own start and end measure the hook callback, so putting tool runtime in that span's metrics would be misleading.

The hook cassettes for latest were re-recorded with the pinned SDK so they contain the new fields. One new cassette covers PostToolUseFailure. test_tool_hooks_create_function_spans overlapped with test_hook_spans_parent_to_matching_tool_and_final_llm, so it was merged into that test and its cassettes were removed.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-19T21:57:46.756460Z	4ecd20a	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "Codex (@codex) review" or "Codex (@codex) security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.