kandev/docs/plans/acp-shell-command-output/task-01-backend-normalization.md

id, title, status, wave, depends_on, plan, spec

id	title	status	wave	depends_on	plan	spec
01-backend-normalization	Backend shell output normalization	done	1		plan.md	../../specs/ui/requirements/acp-shell-command-output.md

Task 01: Backend Shell Output Normalization

Acceptance

• The normalized shell contract distinguishes explicit exit 0, nonzero exit, and unknown exit, and bounds each output field to 256 KiB with valid UTF-8 tail retention.
• Table-driven tests cover final Codex, Claude, OpenCode, and Auggie shapes, including precedence and malformed/absent exits.
• Append, cumulative replace, final replace, final-without-output, and truncation behavior cannot duplicate or silently discard retained output.

Verification

make -C apps/backend fmt
(cd apps/backend && go test ./internal/agentctl/server/adapter/transport/acp -run 'Test.*Shell|TestNormalizerResult')

Files likely touched

• apps/backend/internal/agentctl/types/streams/tool_payload.go
• apps/backend/internal/agentctl/server/adapter/transport/acp/normalize.go
• apps/backend/internal/agentctl/server/adapter/transport/acp/normalize_test.go
• apps/backend/internal/agentctl/server/adapter/transport/acp/shell_output.go (new, if needed)
• apps/backend/internal/agentctl/server/adapter/transport/acp/shell_output_test.go (new, if needed)

Dependencies

None.

Inputs

• Spec sections What, Data model, and Failure modes.
• Existing NormalizeToolResult and extractRawOutput patterns in normalize.go, plus the checked-in provider cases in shell_output_test.go.
• Provider mappings and captured-shape summaries pinned in the feature spec; raw ACP captures were investigation artifacts, not repository fixtures.

Output contract

Report the normalization API chosen, provider precedence, truncation behavior, tests run, files changed, blockers, and follow-up risks. Set this task to done and update plan.md only after targeted tests pass.

Completion Report

• Added NormalizeShellToolUpdate and final-result normalization with independent stdout/stderr presence and truncation state, explicit-field precedence, optional exit codes, and 256 KiB UTF-8 tail retention.
• Covered Codex, Claude, OpenCode, and Auggie final shapes, malformed/absent exits, precedence, live append/replace behavior, partial stream merges, and truncation.
• Changed shell_output.go, shell_output_test.go, normalize.go, normalize_test.go, and the normalized stream payload type.
• Targeted ACP adapter tests, full backend tests, formatting, and backend lint passed. No blockers remain; new provider-specific shapes require new fixtures.