docs(08.1-01): complete agent output schema plan

Tasks completed: 3/3
- Define agent output schema with Zod
- Update ClaudeAgentManager to use schema and handle question flow
- Update AgentWaitingEvent to include structured question data

SUMMARY: .planning/phases/08.1-agent-output-schema/08.1-01-SUMMARY.md

.planning/ROADMAP.md

@@ -146,11 +146,10 @@ Plans:
 **Goal**: Define structured agent output schema (done/question/error discriminated union) and update ClaudeAgentManager to use `--json-schema` flag for validated output parsing
 **Depends on**: Phase 8
 **Research**: Unlikely (Zod schemas, Claude CLI flags documented)
-**Plans**: 2 plans
+**Plans**: 1 plan
 
 Plans:
-- [ ] 08.1-01: Agent Output Schema & ClaudeAgentManager
+- [x] 08.1-01: Agent Output Schema & ClaudeAgentManager
-- [ ] 08.1-02: MockAgentManager Schema Alignment
 
 #### Phase 9: Extended Scenarios
 
@@ -179,7 +178,7 @@ Phases execute in numeric order: 1 → 1.1 → 2 → 3 → 4 → 5 → 6 → 7
 | 6. Coordination | v1.0 | 3/3 | Complete | 2026-01-30 |
 | 7. Mock Agent & Test Harness | v1.1 | 2/2 | Complete | 2026-01-31 |
 | 8. E2E Scenario Tests | v1.1 | 2/2 | Complete | 2026-01-31 |
-| 8.1. Agent Output Schema | v1.1 | 0/2 | Not started | - |
+| 8.1. Agent Output Schema | v1.1 | 1/1 | Complete | 2026-01-31 |
 | 9. Extended Scenarios | v1.1 | 0/2 | Not started | - |
 
 ---

.planning/STATE.md

@@ -9,19 +9,19 @@ See: .planning/PROJECT.md (updated 2026-01-30)
 
 ## Current Position
 
-Phase: 8 of 9 (E2E Scenario Tests)
+Phase: 8.1 of 9 (Agent Output Schema)
-Plan: 2 of 2 in current phase
+Plan: 1 of 1 in current phase
 Status: Phase complete
-Last activity: 2026-01-31 — Completed 08-02-PLAN.md
+Last activity: 2026-01-31 — Completed 08.1-01-PLAN.md
 
-Progress: ████████░░ 80%
+Progress: █████████░ 85%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 31
+- Total plans completed: 32
 - Average duration: 3 min
-- Total execution time: 96 min
+- Total execution time: 101 min
 
 **By Phase (v1.0):**
 
@@ -36,7 +36,7 @@ Progress: ████████░░ 80%
 | 6 | 3/3 | 9 min | 3 min |
 
 **Recent Trend:**
-- Last 5 plans: 08-02 (3 min), 08-01 (3 min), 07-02 (4 min), 07-01 (2 min), 06-03 (3 min)
+- Last 5 plans: 08.1-01 (5 min), 08-02 (3 min), 08-01 (3 min), 07-02 (4 min), 07-01 (2 min)
 - Trend: Steady
 
 ## Accumulated Context
@@ -110,6 +110,9 @@ Recent decisions affecting current work:
 - 08-02: Agent crash tests verify task stays in_progress (not completed)
 - 08-02: Merge conflict tests require manual agentRepository seeding
 - 08-02: MockWorktreeManager setMergeResult for conflict scenarios
+- 08.1-01: Discriminated union with done/question/unrecoverable_error for agent output
+- 08.1-01: JSON schema passed to Claude CLI for validated output
+- 08.1-01: Options and multiSelect fields for structured question choices
 
 ### Pending Todos
 
@@ -129,5 +132,5 @@ None yet.
 ## Session Continuity
 
 Last session: 2026-01-31
-Stopped at: Completed 08-02-PLAN.md (Phase 8 complete)
+Stopped at: Completed 08.1-01-PLAN.md (Phase 8.1 complete)
 Resume file: None

.planning/phases/08.1-agent-output-schema/08.1-01-SUMMARY.md

@@ -0,0 +1,104 @@
+---
+phase: 08.1-agent-output-schema
+plan: 01
+subsystem: agent
+tags: [zod, json-schema, discriminated-union, claude-cli]
+
+# Dependency graph
+requires:
+  - phase: 04
+    provides: [AgentManager interface, ClaudeAgentManager adapter]
+provides:
+  - Structured agent output schema with Zod validation
+  - JSON schema for Claude CLI --json-schema flag
+  - Explicit question/resume flow via status field
+  - PendingQuestion type for structured question data
+affects: [coordination, dispatch, cli]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [discriminated-union-for-status, json-schema-cli-integration]
+
+key-files:
+  created: [src/agent/schema.ts]
+  modified: [src/agent/manager.ts, src/agent/types.ts, src/agent/mock-manager.ts, src/events/types.ts]
+
+key-decisions:
+  - "Discriminated union with done/question/unrecoverable_error status"
+  - "JSON schema passed to CLI for validated output"
+  - "Options and multiSelect fields for structured question choices"
+
+patterns-established:
+  - "Agent output schema: use discriminated union on status field"
+  - "CLI integration: pass --json-schema for structured output"
+
+# Metrics
+duration: 5min
+completed: 2026-01-31
+---
+
+# Phase 08.1 Plan 01: Agent Output Schema Summary
+
+**Structured agent output with Zod discriminated union for explicit done/question/error signaling via --json-schema CLI flag**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-01-31T14:20:00Z
+- **Completed:** 2026-01-31T14:25:31Z
+- **Tasks:** 3
+- **Files modified:** 7
+
+## Accomplishments
+
+- Created Zod schema with discriminated union (done/question/unrecoverable_error)
+- ClaudeAgentManager now passes --json-schema to Claude CLI for validated output
+- Agent question flow uses explicit status field instead of hacky string matching
+- AgentWaitingEvent includes structured options and multiSelect for rich question UI
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Define agent output schema** - `41598f5` (feat)
+2. **Task 2: Update ClaudeAgentManager** - `d9673d5` (feat)
+3. **Task 3: Update AgentWaitingEvent** - `3a3d3f4` (feat)
+
+## Files Created/Modified
+
+- `src/agent/schema.ts` - Zod schema and JSON schema export for agent output
+- `src/agent/manager.ts` - ClaudeAgentManager with --json-schema and structured parsing
+- `src/agent/types.ts` - PendingQuestion type and getPendingQuestion interface method
+- `src/agent/mock-manager.ts` - MockAgentManager with getPendingQuestion and options support
+- `src/agent/manager.test.ts` - Updated tests for new CLI args and result format
+- `src/events/types.ts` - AgentWaitingEvent with options and multiSelect fields
+- `src/dispatch/manager.test.ts` - Mock updated with getPendingQuestion
+
+## Decisions Made
+
+1. **Discriminated union on status** - Chose done/question/unrecoverable_error as the three status values to cover all agent outcomes explicitly
+2. **Dual schema export** - Both Zod (runtime validation) and JSON Schema (CLI flag) for maximum flexibility
+3. **Options in event payload** - Include question options in AgentWaitingEvent so consumers can render UI without calling getPendingQuestion
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- Schema is ready for use by Phase 9 (CLI commands)
+- MockAgentManager supports structured questions for testing
+- All verification checks pass
+
+---
+*Phase: 08.1-agent-output-schema*
+*Completed: 2026-01-31*