[Feature]: Add dedicated FilesPersistedCapture from SDKFilesPersistedEvent

[sjnims]

Parent Issue

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

Feature Type

SDK integration (Agent SDK)

Problem or Need

SDKFilesPersistedEvent is currently captured as a generic SDKEventCapture in sdk_events[] on ExecutionResult (implemented in #348 Phase 1). The raw payload is preserved but not structured for programmatic use. A dedicated capture type would improve checkpoint debugging and enable Stage 4 to reason about file persistence reliability.

The SDKFilesPersistedEvent contains:

• files[] — { filename: string, file_id: string }[] — successfully persisted files
• failed[] — { filename: string, error: string }[] — files that failed to persist
• processed_at — ISO timestamp of persistence operation

Proposed Solution

Move SDKFilesPersistedEvent from generic capture to a dedicated type:

1. Add FilesPersistedCapture in src/types/transcript.ts:

   export interface FilesPersistedCapture {
     files: { filename: string; file_id: string }[];
     failed: { filename: string; error: string }[];
     processed_at: string;
     timestamp: number;
   }

2. Add optional field to ExecutionResult:

   • files_persisted_events?: FilesPersistedCapture[]

3. Update SDKEventCollector in src/stages/3-execution/sdk-event-collector.ts:

   • Handle isFilesPersistedEvent() with targeted capture instead of generic
   • Store structured data in a separate array

4. Wire through agent-executor.ts and session-batching.ts result building

5. Add tests for the new capture path

Files Affected

• src/types/transcript.ts — New FilesPersistedCapture interface, extend ExecutionResult
• src/types/index.ts — Export new type
• src/stages/3-execution/sdk-event-collector.ts — Targeted capture for files_persisted
• src/stages/3-execution/agent-executor.ts — Wire through to result
• src/stages/3-execution/session-batching.ts — Wire through to result
• tests/unit/stages/3-execution/sdk-event-collector.test.ts — New test cases

Risk Assessment

Low risk. New optional field on ExecutionResult. No state migration needed. The type guard isFilesPersistedEvent() already exists from #348.

Priority Rationale

Low-medium value — primarily useful for debugging checkpoint issues. Low effort given the foundation from #348. Could be deferred until file checkpointing problems are encountered in practice.

---

🤖 Created with Claude Code

[claude]

Issue Analysis: Add dedicated FilesPersistedCapture from SDKFilesPersistedEvent

1. Problem Assessment

Is the problem clearly defined? Yes — the issue is well-scoped. SDKFilesPersistedEvent data is currently captured generically (if at all) in the SDK message stream, and the proposal is to give it a dedicated, structured capture type analogous to SubagentCapture and HookResponseCapture.

Key observation: The SDKFilesPersistedEvent type and isFilesPersistedEvent() guard referenced in the issue do not currently exist in the codebase — there are zero references to "FilesPersisted", "files_persisted", or "isFilesPersistedEvent" anywhere in the source or tests. The issue states these come from #348 (Phase 2b), which means this feature depends on that prerequisite work being completed first.

Which stages are affected?

• Stage 3 (Execution): Primary — capture infrastructure needs a new collector/handler
• Stage 4 (Evaluation): Secondary — could eventually consume the structured data, though the issue doesn't propose detection logic changes

What might be missing:

• Confirmation that @anthropic-ai/claude-agent-sdk@^0.2.25 actually exports SDKFilesPersistedEvent as a message type (the SDK is not currently installed in CI, so this can't be verified here)
• Whether the event arrives via the message stream (like SDKHookResponseMessage) or via a hook callback — this determines the capture mechanism

2. Proposed Solution(s)

The issue's proposed solution is sound and follows existing patterns well. Evaluation:

New FilesPersistedCapture type — Correct approach. The proposed interface mirrors the pattern of HookResponseCapture (src/types/transcript.ts:68-85) and SubagentCapture (src/types/transcript.ts:49-62): a structured type with domain-specific fields plus a timestamp.

New field on ExecutionResult — Adding files_persisted_events?: FilesPersistedCapture[] follows the exact pattern of hook_responses? and subagent_captures? at src/types/transcript.ts:211-213. Optional field means no breaking changes.

Update capture mechanism — The issue references sdk-event-collector.ts which doesn't exist. The actual implementation would depend on how the event is delivered:

• If via message stream: Add detection to createHookResponseCollector().processMessage() in src/stages/3-execution/hook-capture.ts:401-418, or create a parallel collector
• If via SDK hook: Add a new hook type in src/stages/3-execution/hooks-factory.ts and src/stages/3-execution/tool-capture-hooks.ts

Tradeoffs & risks:

• Low risk: New optional field, additive change only
• No state migration needed: ExecutionResult is not persisted in PipelineState; it's only in transcript JSON files. Missing fields gracefully default to undefined
• Edge case: Empty arrays vs undefined — should follow existing convention (e.g., subagent_captures is conditionally included only when non-empty at src/stages/3-execution/agent-executor.ts:413-415)

3. Alternative Approaches

A. Dedicated collector (proposed) — New FilesPersistedCapture type + dedicated array on ExecutionResult

• Pros: Type-safe, queryable, follows existing patterns
• Cons: More code surface area for a low-priority feature

B. Extend HookResponseCollector to handle multiple system message types — Process files_persisted events inside the existing processMessage() at src/stages/3-execution/hook-capture.ts:401 and store them in a separate typed array on the same collector

• Pros: Reuses existing infrastructure, single message processing loop
• Cons: Couples unrelated concerns in one collector

C. Generic SDK event capture bag — Add a sdk_events?: Record<string, unknown[]> field and store all non-standard SDK events keyed by type

• Pros: Future-proof for other SDK event types
• Cons: Loses type safety, harder to consume in Stage 4

D. Defer entirely — As the issue notes, this is primarily useful for debugging checkpoint issues and could be deferred until actually needed

• Pros: Zero maintenance cost
• Cons: Loses structured data when debugging is eventually needed

4. Implementation Considerations

Files requiring changes:

File	Change
src/types/transcript.ts:199-222	Add FilesPersistedCapture interface, add optional field to ExecutionResult
src/types/index.ts:60-76	Export new type
src/stages/3-execution/hook-capture.ts	Add type guard + collector (or extend processMessage)
src/stages/3-execution/agent-executor.ts:206-270	Add to ExecutionContext, wire through prepareExecutionContext and finalizeExecution
src/stages/3-execution/agent-executor.ts:390-428	Add to BuildExecutionResultOptions and buildExecutionResult
src/stages/3-execution/session-batching.ts	Wire through batched execution path
tests/unit/stages/3-execution/hook-capture.test.ts	New test cases for capture
tests/unit/stages/3-execution/agent-executor.test.ts	Verify wiring

Breaking changes: None. All additions are optional fields.

State/resume impact: None. ExecutionResult is ephemeral per-run; the PipelineState type in src/state/ is unaffected.

Testing requirements:

• Unit tests for the new type guard (pattern: isFilesPersistedMessage())
• Unit tests for collector capturing structured data from mock SDK messages
• Unit tests verifying ExecutionResult includes the field when events are present and omits it when absent
• No integration or e2e tests needed since this is additive capture

5. Recommendation

Recommended approach: A (Dedicated collector) — as proposed in the issue.

This matches the established pattern (SubagentCapture, HookResponseCapture each have their own type + array + collector logic). Approach B would be a reasonable simplification but couples concerns unnecessarily.

Suggested implementation order:

1. Wait for prerequisite: Confirm [Feature]: Handle new SDK v0.2.25 message types in transcript capture #348 Phase 2b is merged and SDKFilesPersistedEvent / isFilesPersistedEvent() are available
2. Add types: FilesPersistedCapture in src/types/transcript.ts, export in src/types/index.ts
3. Add capture logic: Type guard + collector/processor in src/stages/3-execution/hook-capture.ts
4. Wire through execution: Update ExecutionContext, buildExecutionResult, and both agent-executor.ts and session-batching.ts
5. Add tests: Unit tests for capture logic and wiring
6. Optional follow-up: Stage 4 detection if file persistence reliability becomes a meaningful signal for evaluation

Follow-up issues to consider:

• Stage 4 consumption of FilesPersistedCapture for checkpoint reliability metrics (separate issue, only if needed)
• Documentation update in docs/ if file persistence debugging becomes a supported workflow