[Feature]: Enrich SubagentCapture with SDKTaskNotificationMessage data

[sjnims]

Parent Issue

Sub-issue of #344 (Leverage Additional SDK v0.2.25 Capabilities)
Follow-up to #348 (Phase 2a)

Feature Type

SDK integration (Agent SDK)

Problem or Need

SDKTaskNotificationMessage is currently captured as a generic SDKEventCapture in sdk_events[] on ExecutionResult (implemented in #348 Phase 1). This provides basic storage but loses the opportunity to correlate task notifications with existing SubagentCapture entries, which would enrich subagent lifecycle tracking for Stage 4 evaluation.

The SDKTaskNotificationMessage contains:

• task_id — correlates with SubagentCapture.agentId
• status — "completed" | "failed" | "stopped"
• output_file — path to task output
• summary — LLM-generated summary of task result

Proposed Solution

Move SDKTaskNotificationMessage from generic capture to targeted SubagentCapture enrichment:

1. Extend SubagentCapture in src/types/transcript.ts with optional fields:

   • taskStatus?: "completed" | "failed" | "stopped"
   • taskOutputFile?: string
   • taskSummary?: string

2. Update SDKEventCollector.processMessage() in src/stages/3-execution/sdk-event-collector.ts:

   • Accept subagentCaptures: SubagentCapture[] as a third parameter
   • Handle isTaskNotificationMessage() with targeted enrichment (correlate task_id → agentId)
   • Fall through to generic capture if no matching SubagentCapture is found

3. Update callers in agent-executor.ts and session-batching.ts to pass subagentCaptures to processMessage()

4. Add tests for correlation logic, including edge cases:

   • Task notification matching an existing SubagentCapture
   • Task notification with no matching SubagentCapture (falls to generic)
   • Overlap with SubagentStop hook data (complementary, not conflicting)

Files Affected

• src/types/transcript.ts — Extend SubagentCapture
• src/stages/3-execution/sdk-event-collector.ts — Add targeted enrichment
• src/stages/3-execution/agent-executor.ts — Pass subagentCaptures to collector
• src/stages/3-execution/session-batching.ts — Pass subagentCaptures to collector
• tests/unit/stages/3-execution/sdk-event-collector.test.ts — New test cases

Risk Assessment

Low risk. Additive optional fields on SubagentCapture. The type guard isTaskNotificationMessage() already exists from #348. No state migration needed.

Priority Rationale

Medium value — enriches subagent tracking with completion status and summaries. Low effort given the foundation from #348.

---

🤖 Created with Claude Code

[claude]

Analysis: Enrich SubagentCapture with SDKTaskNotificationMessage Data

1. Problem Assessment

Clearly defined? Yes the issue is well-scoped with specific types, fields, files, and a clear correlation mechanism (task_id to agentId).

Key observation: The issue references sdk-event-collector.ts and SDKEventCapture/sdk_events[] as existing infrastructure, but neither exists yet in the codebase. These appear to be part of the parent issue #348 (Phase 1), which is still open. This issue (#354) is labeled as Follow-up to #348 (Phase 2a), meaning it depends on #348 establishing the foundational message handling infrastructure first.

What is missing from the issue:

• No mention of the dependency ordering. [Feature]: Handle new SDK v0.2.25 message types in transcript capture #348 Phase 1 needs to land first to provide the isTaskNotificationMessage() type guard and any generic SDK event capture infrastructure
• The issue assumes SDKTaskNotificationMessage is already captured generically in sdk_events[], but that field does not exist on ExecutionResult (src/types/transcript.ts:199-222) yet

Root cause: SubagentCapture (src/types/transcript.ts:49-62) currently only captures hook-sourced lifecycle data (start/stop timestamps, transcript path). SDK message-stream data (SDKTaskNotificationMessage) carries complementary information (completion status, output file, summary) that would enrich the same logical entity but through a different capture path.

Pipeline impact: Primarily Stage 3 (Execution) for capture, with downstream benefits to Stage 4 (Evaluation) where detectFromSubagentCaptures() (src/stages/4-evaluation/detection/agents.ts:28-51) currently only uses agentType, agentId, startTimestamp, and stopTimestamp.

---

2. Proposed Solution Evaluation

The issue proposes a clean, focused approach. Evaluation of each part:

a) Extending SubagentCapture with optional fields Sound approach. Adding taskStatus, taskOutputFile, and taskSummary as optional fields is backwards-compatible and follows the existing pattern (see stopTimestamp?, transcriptPath?, stopHookActive? at src/types/transcript.ts:57-61). No state migration needed since these are optional fields on data within ExecutionResult, not in PipelineState.

b) Updating SDKEventCollector.processMessage() to accept subagentCaptures This is where the dependency on #348 matters. The file src/stages/3-execution/sdk-event-collector.ts does not exist yet. Currently, SDK message processing happens via:

• HookResponseCollector.processMessage() in src/stages/3-execution/hook-capture.ts:398-429 (handles SDKHookResponseMessage only)
• Direct message iteration in agent-executor.ts:572-584 and session-batching.ts:414-442

Two implementation paths depending on #348 status:

• If [Feature]: Handle new SDK v0.2.25 message types in transcript capture #348 lands first: Add task notification handling to the new SDKEventCollector
• If implementing independently: Add a dedicated isTaskNotificationMessage() type guard and handle it directly in the message iteration loops

c) Correlation logic (task_id to agentId) The existing captureMap pattern in tool-capture-hooks.ts:220-233 provides a proven correlation mechanism. The same map (keyed by agent ID) can be used to look up and enrich captures when a task notification arrives.

d) Fall-through to generic capture Good defensive design. If SDKEventCapture/sdk_events[] exists (from #348), unmatched notifications get generic storage. If implementing independently, unmatched notifications would simply be ignored.

Tradeoffs:

• Adding subagentCaptures as a parameter to processMessage() creates coupling between the event collector and subagent capture lifecycle. This is acceptable given they are semantically related.
• The taskSummary field is LLM-generated text, potentially useful for Stage 4 LLM judge context but should not be used for programmatic detection.

Edge cases identified in issue: Comprehensive, covering matching, non-matching, and SubagentStop overlap.

---

3. Alternative Approaches

Alternative A: Separate TaskNotificationCapture type

• Create a new TaskNotificationCapture interface instead of enriching SubagentCapture
• Store as task_notifications on ExecutionResult, correlate in Stage 4
• Pros: Cleaner separation of concerns; no mutation of existing captures
• Cons: Pushes correlation complexity to Stage 4; duplicates agent ID references

Alternative B: Handle in message iteration loop directly (no SDKEventCollector)

• Add isTaskNotificationMessage() type guard to sdk-client.ts
• Handle directly in agent-executor.ts:572-584 and session-batching.ts:414-442 message loops
• Pros: No dependency on [Feature]: Handle new SDK v0.2.25 message types in transcript capture #348; simpler; can land immediately
• Cons: Adds more logic to already-complex message loops; does not compose well when more message types are added

Alternative C: Post-processing approach

• After iteration, scan ctx.messages for task notifications and correlate with subagentCaptures
• Pros: No changes to message loop; clean separation
• Cons: Requires re-scanning messages; loses real-time enrichment

Recommendation: The issue proposed solution (enriching SubagentCapture in-place) is the best approach. It follows the existing mutation pattern established by createSubagentStopHook() (tool-capture-hooks.ts:250-268).

---

4. Implementation Considerations

Files affected (verified against codebase):

File	Change	Lines
src/types/transcript.ts	Add 3 optional fields to SubagentCapture	~49-62
src/stages/3-execution/sdk-client.ts	Add isTaskNotificationMessage() type guard + export	New
src/stages/3-execution/hook-capture.ts OR new sdk-event-collector.ts	Task notification processing with subagentCaptures correlation	~398-429 or new
src/stages/3-execution/agent-executor.ts	Pass captureMap to processor; call in message loop	~572-576
src/stages/3-execution/session-batching.ts	Same as agent-executor	~414-416
src/stages/4-evaluation/detection/agents.ts	Enrich evidence string with taskStatus/taskSummary	~35-46
tests/unit/stages/3-execution/	Test correlation logic	New test cases

Breaking changes: None. All new fields are optional. No state migration needed.

Testing requirements:

• Unit tests for isTaskNotificationMessage() type guard
• Unit tests for correlation logic: match found, no match (fall-through), multiple notifications for same agent
• Unit tests for SubagentStop + TaskNotification overlap (complementary, not conflicting)
• Integration consideration: verify captureMap is accessible from the message processing context

State/resume impact: None. SubagentCapture lives in ExecutionResult (Stage 3 output), not in PipelineState.

Dependency on #348: The issue references SDKEventCollector which does not exist yet. Implementation can proceed independently using Alternative B or wait for #348 Phase 1.

---

5. Recommendation

Recommended approach: Implement the issue proposed solution with one adjustment: decouple from #348 by handling task notifications directly in the message iteration loops rather than through the not-yet-existing SDKEventCollector. If/when #348 lands, the logic can be refactored into the collector.

Implementation order:

1. Add type guard isTaskNotificationMessage() in sdk-client.ts
2. Extend SubagentCapture Add taskStatus?, taskOutputFile?, taskSummary? to src/types/transcript.ts
3. Add enrichment logic Create enrichSubagentFromTaskNotification() utility that correlates task_id to agentId via captureMap
4. Wire into message loops Call in both agent-executor.ts:572-584 and session-batching.ts:414-442
5. Enhance Stage 4 detection Update detectFromSubagentCaptures() in agents.ts to include taskStatus in evidence
6. Tests Cover all edge cases listed in the issue

Follow-up issues to consider:

• If [Feature]: Handle new SDK v0.2.25 message types in transcript capture #348 lands later, consolidate task notification handling into SDKEventCollector
• Consider whether taskSummary should be passed to the LLM judge as additional evaluation context