[Feature]: Add SessionStart/SessionEnd hooks for lifecycle tracking

[sjnims]

Parent Issue

Sub-issue of #344 (Leverage Additional SDK v0.2.25 Capabilities)

Feature Type

SDK integration (Agent SDK)

Problem or Need

Session timing currently relies on manual Date.now() calls (agent-executor.ts:226, session-batching.ts:703). This doesn't distinguish between session startup time (subprocess spawn + plugin load + MCP initialization) and actual execution time. This gap makes it harder to diagnose performance issues in session batching.

Proposed Solution

Implement SDK v0.2.25 SessionStart and SessionEnd hooks to track session lifecycle events.

Benefits:

• Accurate timing for session startup vs execution
• Better diagnostics for session batching performance
• Helps identify slow plugin/MCP initialization

Implementation approach:

• Add SessionStart and SessionEnd hook types to hooks-factory.ts
• Follow existing HookCallbackMatcher pattern
• Capture timing data for diagnostics
• Useful for session batching metrics

Files Affected

• src/stages/3-execution/hooks-factory.ts — New hook types
• src/stages/3-execution/sdk-client.ts — QueryOptions hooks, new input types
• src/types/transcript.ts — New capture types

Risk Assessment

Low risk — Purely observational hooks. No changes to execution behavior.

Priority Rationale

Medium value for diagnostics. Primarily useful for session batching metrics and debugging.

---

🤖 Created with Claude Code

[claude]

Analysis: Add SessionStart/SessionEnd hooks for lifecycle tracking

1. Problem Assessment

The problem is clearly defined. Session timing currently uses Date.now() bookends around the entire query execution (e.g., agent-executor.ts:235, session-batching.ts:701), which conflates subprocess startup, plugin loading, MCP initialization, and actual LLM execution into a single duration metric. This makes it difficult to diagnose whether slow sessions are caused by infrastructure overhead or actual execution.

Affected stage: Stage 3 (Execution) primarily, with minor additions to the transcript types layer.

What's already in place: The type system already defines SessionStart and SessionEnd in HookEventType (src/types/components.ts:106-107). Stage 1 analysis (src/stages/1-analysis/hook-analyzer.ts:41-42) already parses these event types from plugin hooks.json files. Stage 2 generation (src/stages/2-generation/hook-scenario-generator.ts:98-99, 349-350) already generates scenarios for them. Stage 4 evaluation already detects hook responses for any event type. The gap is specifically in Stage 3 execution — the hooks factory and SDK client don't register SessionStart/SessionEnd capture hooks.

2. Proposed Solution(s)

The issue's proposed approach is sound. Adding SessionStart and SessionEnd hook types to the hooks factory following the existing HookCallbackMatcher pattern is the natural extension. Specific evaluation:

Changes needed:

1. src/stages/3-execution/sdk-client.ts — Import and re-export SessionStartHookInput and SessionEndHookInput types from the SDK (if they exist in v0.2.25). Add SessionStartHookConfig and SessionEndHookConfig type aliases.

2. src/stages/3-execution/hooks-factory.ts — Extend SDKHooksConfig interface to include SessionStart and SessionEnd keys. These are observational/stateless hooks (they don't need per-scenario callbacks), so they belong in createBatchStatelessHooks() or can be standalone. Update assembleHooksConfig() and createCaptureHooksConfig() to include them.

3. src/types/transcript.ts — Optionally add a SessionTimingCapture interface to store structured timing data (session start timestamp, session end timestamp, derived startup duration). This could be added to ExecutionResult.

4. src/stages/3-execution/tool-capture-hooks.ts — Add createSessionStartHook() and createSessionEndHook() factory functions following the pattern of existing hook creators.

Tradeoffs:

• Low risk — These are purely observational hooks. They don't modify execution behavior or return values that affect tool use decisions.
• SDK dependency — Need to verify that SessionStartHookInput and SessionEndHookInput types are actually exported from @anthropic-ai/claude-agent-sdk@^0.2.25. If not, the input type will need to be defined locally or typed as unknown.
• Session batching interaction — In batched_by_component mode, SessionStart fires once at batch start and SessionEnd fires once at batch end. This is correct behavior — the timing captures overall session lifecycle. But it means individual scenario timing within a batch won't benefit from these hooks.

3. Alternative Approaches

A. SDK SessionStart/SessionEnd hooks (proposed) — Register hooks through the SDK's hook system.

• Pros: Leverages SDK infrastructure, accurate timing from the SDK's perspective, consistent with existing hook patterns.
• Cons: SDK dependency for type availability, limited granularity in batched mode.

B. Wrap query execution with manual timing markers — Instead of SDK hooks, add timing capture points around the query() call with a "first message received" marker.

• Pros: No SDK type dependency, works with any SDK version.
• Cons: Less accurate (measures from our code, not from SDK internals), doesn't capture SDK-internal startup phases, duplicates what the SDK hooks provide natively.

C. Parse SDK system init messages for timing — The SDK sends system messages with subtype: "init" (see sdk-client.ts:247-251). Use timestamps from these messages to infer startup time.

• Pros: Already available without new hooks, no SDK API changes needed.
• Cons: System messages don't have explicit timestamps, less structured, fragile if SDK message format changes.

4. Implementation Considerations

Files affected:

• src/stages/3-execution/hooks-factory.ts — SDKHooksConfig interface, assembleHooksConfig(), createCaptureHooksConfig(), createBatchStatelessHooks()
• src/stages/3-execution/sdk-client.ts — New type imports/re-exports
• src/stages/3-execution/tool-capture-hooks.ts — New hook creator functions
• src/types/transcript.ts — Optional SessionTimingCapture type, ExecutionResult extension

Breaking changes: None. The SDKHooksConfig interface gains new optional keys. ExecutionResult gets optional new fields. All changes are additive.

State/resume impact: None. Session timing is transient execution data, not persisted in state. No migration needed in src/state/operations.ts.

Testing requirements:

• Unit tests for createSessionStartHook() and createSessionEndHook() in tool-capture-hooks.test.ts
• Unit tests for updated assembleHooksConfig() and createCaptureHooksConfig() in hooks-factory.test.ts
• Verify SDKHooksConfig type changes compile correctly
• Integration testing would require a live SDK session (existing e2e test infrastructure)

Session batching consideration: In batched mode (session-batching.ts), SessionStart fires when the first scenario's query creates the session, and SessionEnd fires when the session is terminated. The /clear commands between scenarios within a batch do NOT trigger these hooks. This is expected and useful — it gives batch-level lifecycle timing.

5. Recommendation

Recommend Approach A (SDK hooks) as proposed in the issue. It's the cleanest solution, follows existing patterns, and provides the most accurate timing data.

Implementation order:

1. Verify SessionStartHookInput/SessionEndHookInput exist in SDK v0.2.25 types. If not, define minimal local types.
2. Add type exports in sdk-client.ts
3. Add createSessionStartHook() / createSessionEndHook() in tool-capture-hooks.ts — these should capture timestamps and store them in a new timing structure
4. Update SDKHooksConfig, assembleHooksConfig(), and createCaptureHooksConfig() in hooks-factory.ts
5. Optionally add session_timing field to ExecutionResult in transcript.ts
6. Add unit tests for new functions
7. Verify existing tests still pass

Classification note: The SessionStart hook is stateless (no per-scenario callback needed) since it just captures a timestamp. SessionEnd is similarly stateless. Both can be created once per batch and reused.

Follow-up issues to consider:

• Expose session timing metrics in Stage 4 evaluation reports (separate issue)
• Add timing breakdown to dry-run cost estimation output