fix(pi): align agent instrumentation with tracing spec

.changeset/fix-pi-instrumentation.md

@@ -0,0 +1,10 @@
+---
+"braintrust": patch
+---
+
+fix(pi): align agent instrumentation with tracing spec
+
+Capture nested session tool calls and their application spans, record tool
+approval only when execution is observed, and preserve tracing context across
+SDK copies. Align Pi errors, attachments, usage metrics, and metadata with the
+instrumentation specification.

e2e/scenarios/pi-coding-agent-instrumentation/__snapshots__/pi-coding-agent-v0-auto-hook.span-tree.txt

@@ -1,11 +1,13 @@
 span_tree:
 └── pi-coding-agent-root [task]
     metadata: {
-      "scenario": "pi-coding-agent-instrumentation"
+      "scenario": "pi-coding-agent-instrumentation",
+      "testRunId": "<run:1>"
     }
     └── pi-coding-agent-prompt-operation
         metadata: {
-          "operation": "prompt"
+          "operation": "prompt",
+          "testRunId": "<run:1>"
         }
         └── AgentSession.prompt [task]
             input: "Use the bash tool to run `printf pi_tool_ok` exactly once, then reply with exactly PI_CODING_AGENT_OK and include the command output."
@@ -21,15 +23,105 @@ span_tree:
             ]
             metadata: {
               "model": "claude-haiku-4-5",
+              "pi_coding_agent.active_tools": [
+                "bash"
+              ],
               "pi_coding_agent.api": "anthropic-messages",
+              "pi_coding_agent.expand_prompt_templates": false,
               "pi_coding_agent.model": "claude-haiku-4-5",
+              "pi_coding_agent.model_name": "Claude Haiku 4.5 (latest)",
               "pi_coding_agent.operation": "AgentSession.prompt",
+              "pi_coding_agent.session_id": "<session-id>",
               "pi_coding_agent.source": "rpc",
+              "pi_coding_agent.thinking_level": "off",
+              "pi_coding_agent.version": "0.79.1",
               "provider": "anthropic"
             }
-            metrics: {
-              "duration": 0
-            }
+            ├── anthropic.messages.create [llm]
+            │   input: [
+            │     {
+            │       "content": "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n- bash: Execute bash commands (ls, grep, find, etc.)\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n- Use bash for file operations like ls, rg, find\n- Be concise in your responses\n- Show file paths clearly when working with files\n\nPi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):\n- Main documentation: <repo>/e2e/.bt-tmp/scenario-deps/pi-coding-agent-instrumentation-locked-<hash>/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.79.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/README.md\n- Additional docs: <repo>/e2e/.bt-tmp/scenario-deps/pi-coding-agent-instrumentation-locked-<hash>/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.79.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/docs\n- Examples: <repo>/e2e/.bt-tmp/scenario-deps/pi-coding-agent-instrumentation-locked-<hash>/node_modules/.pnpm/@earendil-works+pi-coding-agent@0.79.1_ws@8.21.0_zod@4.4.3/node_modules/@earendil-works/pi-coding-agent/examples (extensions, custom tools, SDK)\n- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory\n- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)\n- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)\nCurrent date: <timestamp>\nCurrent working directory: <repo>/e2e/scenarios/pi-coding-agent-instrumentation/",
+            │       "role": "system"
+            │     },
+            │     {
+            │       "content": [
+            │         {
+            │           "text": "Use the bash tool to run `printf pi_tool_ok` exactly once, then reply with exactly PI_CODING_AGENT_OK and include the command output.",
+            │           "type": "text"
+            │         }
+            │       ],
+            │       "role": "user"
+            │     }
+            │   ]
+            │   output: [
+            │     {
+            │       "finish_reason": "tool_calls",
+            │       "index": 0,
+            │       "message": {
+            │         "content": null,
+            │         "role": "assistant",
+            │         "tool_calls": [
+            │           {
+            │             "function": {
+            │               "arguments": "{\"command\":\"printf pi_tool_ok\"}",
+            │               "name": "bash"
+            │             },
+            │             "id": "<span:1>",
+            │             "type": "function"
+            │           }
+            │         ]
+            │       }
+            │     }
+            │   ]
+            │   metadata: {
+            │     "model": "claude-haiku-4-5",
+            │     "pi_coding_agent.api": "anthropic-messages",
+            │     "pi_coding_agent.max_retry_delay_ms": 0,
+            │     "pi_coding_agent.model": "claude-haiku-4-5",
+            │     "pi_coding_agent.model_name": "Claude Haiku 4.5 (latest)",
+            │     "pi_coding_agent.operation": "agent.streamFn",
+            │     "pi_coding_agent.response_id": "msg_011CgRoA9MLPbh7ZBCTQXMgD",
+            │     "pi_coding_agent.session_id": "<session-id>",
+            │     "pi_coding_agent.stop_reason": "toolUse",
+            │     "pi_coding_agent.transport": "auto",
+            │     "provider": "anthropic",
+            │     "tools": [
+            │       {
+            │         "function": {
+            │           "description": "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last 2000 lines or 50KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.",
+            │           "name": "bash",
+            │           "parameters": {
+            │             "properties": {
+            │               "command": {
+            │                 "description": "Bash command to execute",
+            │                 "type": "string"
+            │               },
+            │               "timeout": {
+            │                 "description": "Timeout in seconds (optional, no default timeout)",
+            │                 "type": "number"
+            │               }
+            │             },
+            │             "required": [
+            │               "command"
+            │             ],
+            │             "type": "object"
+            │           }
+            │         },
+            │         "type": "function"
+            │       }
+            │     ]
+            │   }
+            │   metrics: {
+            │     "completion_tokens": 57,
+            │     "estimated_cost": 0.001786,
+            │     "prompt_cache_creation_1h_tokens": 0,
+            │     "prompt_cache_creation_5m_tokens": 0,
+            │     "prompt_cache_creation_tokens": 0,
+            │     "prompt_cached_tokens": 0,
+            │     "prompt_tokens": 1501,
+            │     "time_to_first_token": 0,
+            │     "tokens": 1558
+            │   }
             ├── anthropic.messages.create [llm]
             │   input: [
             │     {
@@ -83,9 +175,14 @@ span_tree:
             │   metadata: {
             │     "model": "claude-haiku-4-5",
             │     "pi_coding_agent.api": "anthropic-messages",
+            │     "pi_coding_agent.max_retry_delay_ms": 0,
             │     "pi_coding_agent.model": "claude-haiku-4-5",
+            │     "pi_coding_agent.model_name": "Claude Haiku 4.5 (latest)",
             │     "pi_coding_agent.operation": "agent.streamFn",
+            │     "pi_coding_agent.response_id": "msg_011CgRoACeXDKGoyf2QJB3rN",
+            │     "pi_coding_agent.session_id": "<session-id>",
             │     "pi_coding_agent.stop_reason": "stop",
+            │     "pi_coding_agent.transport": "auto",
             │     "provider": "anthropic",
             │     "tools": [
             │       {
@@ -115,12 +212,14 @@ span_tree:
             │   }
             │   metrics: {
             │     "completion_tokens": 23,
-            │     "duration": 0,
+            │     "estimated_cost": 0.00169,
+            │     "prompt_cache_creation_1h_tokens": 0,
+            │     "prompt_cache_creation_5m_tokens": 0,
             │     "prompt_cache_creation_tokens": 0,
             │     "prompt_cached_tokens": 0,
-            │     "prompt_tokens": 2335,
+            │     "prompt_tokens": 1575,
             │     "time_to_first_token": 0,
-            │     "tokens": 2358
+            │     "tokens": 1598
             │   }
             └── bash [tool]
                 input: {
@@ -137,6 +236,8 @@ span_tree:
                 metadata: {
                   "gen_ai.tool.call.id": "<tool-call-id>",
                   "gen_ai.tool.name": "bash",
-                  "pi_coding_agent.tool.name": "bash"
+                  "pi_coding_agent.tool.is_error": false,
+                  "pi_coding_agent.tool.name": "bash",
+                  "tool_approval": "approved"
                 }
                 └── pi-tool-child