kandev/docs/plans/acp-shell-command-echo/plan.md

spec, created, status, issue

spec	created	status	issue
docs/specs/ui/requirements/acp-shell-command-output.md	2026-08-10	implemented	https://github.com/kdlbs/kandev/issues/2480

Implementation Plan: ACP Shell Command Echo Normalization

Overview

OMP sends the visible $ <command> text and the command result as adjacent ACP content items, while its structured final rawOutput does not expose a stdout field recognized by Kandev. Kandev currently treats any non-nil final rawOutput as proof that stdout was already normalized, so it skips the final command-echo strip and persists the two content items glued together. The repair makes that state reflect whether stdout was actually recognized and adds an adapter-level regression test for OMP's exact event shape.

Backend

Track actual final-stdout normalization

Files:

• apps/backend/internal/agentctl/server/adapter/transport/acp/shell_output.go
• apps/backend/internal/agentctl/server/adapter/transport/acp/tool_call_update_test.go

Changes:

• Make applyFinalShellResult report whether the final result contained a recognized stdout field and therefore committed the leading-command normalization.
• In NormalizeShellToolUpdate, derive finalStdoutCommitted from that result instead of setting it for every non-nil rawOutput.
• Preserve the existing single-strip guarantee when the final result does contain recognized stdout, including real output that legitimately starts with a second $ <command> line.
• Add an adapter-level regression test that seeds OMP's execute tool call and completes it with two adjacent text content items ($ <command> and real output) plus its structured rawOutput container.

No persistence, API, frontend, or provider-specific branch is added. The existing provider-neutral ACP adapter remains the normalization boundary established by ADR-0036.

Tests

• What: OMP's structured final shell update removes the leading command presentation content and preserves the complete adjacent real output. File: apps/backend/internal/agentctl/server/adapter/transport/acp/tool_call_update_test.go. How: Adapter integration test through convertToolCallUpdate and convertToolCallResultUpdate using the current OMP mapper shape.
• What: Recognized final stdout is normalized exactly once and cumulative/live shell paths keep their existing behavior. File: existing tests in apps/backend/internal/agentctl/server/adapter/transport/acp/shell_output_test.go. How: Run the full ACP adapter package after the focused red/green regression.

No browser E2E is added because the browser contract and renderer do not change; the defect occurs before persistence at the ACP adapter boundary, and the adapter integration test exercises the complete changed path.

Verification Results

Diagnostic reproduction completed before implementation:

• The throwaway OMP regression failed as expected because Kandev retained $ <command> directly before /usr/bin/gh.
• The throwaway test was removed after confirming the root cause.
• Focused regressions passed: 2 tests.
• Full ACP adapter package passed: 764 tests.

PR fixup verification:

• Review remediation commit 59f10560c8563a3fd68a5885cb555ecddaa302fc added exit-code assertions for the metadata-only OMP result, clarified the recognized-stdout wording, and changed the task verification to use the repository backend test target.
• Focused regressions passed: 2 tests.
• rtk make -C apps/backend test passed.
• At the exact PR head above, CI reported 36 passed, 0 failed, and two E2E shards still in progress: E2E Shard 2/14 and E2E Shard 6/14.
• The review thread was replied to and resolved; no unresolved review threads or actionable issue comments remain. GitHub reports the PR as mergeable with mergeStateStatus=UNSTABLE while those checks run.

Implementation Waves And Parallel Candidates

• Task 01: Normalize OMP structured final shell output (done)

The task is sequential. It owns the complete repair and its regression coverage; no subagent delegation is authorized by this plan.

Risks And Out Of Scope

• The fix must distinguish “final result present” from “final stdout recognized” without stripping an already-normalized value twice.
• This repair does not infer or synthesize a separator between arbitrary content items. It removes only the already-evidenced leading $ <command> presentation content.
• Provider-side output missing before it reaches Kandev remains out of scope.
• Installing or changing OMP is out of scope; the captured public mapper shape and failing Kandev adapter reproduction are sufficient to own this repair.