---
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*
