AX-Copilot-Codex/docs/claw-code-parity-plan.md

Claw Code Parity Plan (Rewritten)

Scope

• Align AX Copilot with claw-code quality for loop reliability, permission/hook behavior, and session durability.

Update

• Updated: 2026-04-05 15:34 (KST)
• Rebased the AX Agent improvement plan on actual claw-code runtime files instead of earlier AX snapshots. The reference spine is now src/bootstrap/state.ts -> src/bridge/initReplBridge.ts -> src/bridge/sessionRunner.ts -> src/screens/REPL.tsx -> src/components/Messages.tsx -> src/components/StatusLine.tsx.
• AX Agent work should follow that same quality order: state first, execution second, render last. UI-only fixes that bypass state/execution should be treated as temporary.

Preserved History (Summary)

• Core loop guards and post-tool verification gates are already partially implemented.
• Plan Mode, parallel tool execution, and unknown-tool recovery are in place.
• Session restore hardening is ongoing.

Reference Map

claw-code reference	AX apply target	completion criteria	quality criteria
src/bootstrap/state.ts	src/AxCopilot/Views/ChatWindow.xaml.cs, src/AxCopilot/Services/Agent/AxAgentExecutionEngine.cs, src/AxCopilot/Services/ChatStorageService.cs	one canonical runtime/session state for current turn, queue, retry, execution events, and persisted snapshot	reopen/retry/queue flows do not create duplicate or blank assistant messages
src/bridge/initReplBridge.ts	src/AxCopilot/Services/Agent/AxAgentExecutionEngine.cs, src/AxCopilot/Services/LlmService.cs	send/regenerate/retry/queued follow-up/slash all enter through one prepared-execution path	same input under same settings takes same execution route regardless of entry point
src/bridge/sessionRunner.ts	src/AxCopilot/Services/Agent/AgentLoopService.cs, src/AxCopilot/Services/Agent/AgentLoopTransitions.cs, src/AxCopilot/Services/Agent/AgentLoopTransitions.Execution.cs	tool start/result/error/progress normalized once inside loop layer	Cowork/Code no longer flash repeated status strings or overshare debug payloads
src/bridge/bridgeMessaging.ts	src/AxCopilot/Views/ChatWindow.xaml.cs, src/AxCopilot/Services/Agent/AgentLoopService.cs	inbound execution events separated from display-only events before UI render	execution event replay does not duplicate visible timeline banners
src/screens/REPL.tsx	src/AxCopilot/Views/ChatWindow.xaml, src/AxCopilot/Views/ChatWindow.xaml.cs	screen state transitions, queue flow, retry flow, and composer state use shared runtime helpers	window resize, queue chaining, and retry feel stable instead of UI-patched
src/components/Messages.tsx	src/AxCopilot/Views/ChatWindow.xaml.cs	timeline derives from normalized conversation/session state only	no token-only completions, blank cards, or direct injected duplicates
src/components/StatusLine.tsx	src/AxCopilot/Views/ChatWindow.xaml, src/AxCopilot/Views/ChatWindow.xaml.cs	status strip computed from debounced runtime state, not multiple imperative refresh calls	metadata stays lightweight and does not overpower message timeline

AX Agent Improvement Phases

Phase A. Runtime State Canonicalization

• Reference: src/bootstrap/state.ts
• AX apply location: src/AxCopilot/Views/ChatWindow.xaml.cs, src/AxCopilot/Services/Agent/AxAgentExecutionEngine.cs, src/AxCopilot/Services/ChatStorageService.cs
• Completion criteria:
  • Chat, Cowork, Code all update one shared runtime/session state model.
  • queue, retry, post-compaction, and execution-event state can be restored after reopen.
• Quality criteria:
  • reopening a conversation reproduces the same visible timeline without extra assistant cards.
  • queue and execution badges remain in sync with the stored conversation.

Phase B. Prepared Execution Unification

• Reference: src/bridge/initReplBridge.ts
• AX apply location: src/AxCopilot/Services/Agent/AxAgentExecutionEngine.cs, src/AxCopilot/Services/LlmService.cs
• Completion criteria:
  • prompt stack assembly, execution mode choice, and final assistant commit are engine-owned.
  • send/regenerate/retry/queued follow-up/slash flows all call the same preparation API.
• Quality criteria:
  • behavior is deterministic per tab/settings combination.
  • UI stops building different prompt stacks for the same conversation state.

Phase C. AgentLoop Event Normalization

• Reference: src/bridge/sessionRunner.ts, src/bridge/bridgeMessaging.ts
• AX apply location: src/AxCopilot/Services/Agent/AgentLoopService.cs, src/AxCopilot/Services/Agent/AgentLoopTransitions.cs, src/AxCopilot/Services/Agent/AgentLoopTransitions.Execution.cs
• Completion criteria:
  • loop events are normalized into bounded activity/event records before UI consumption.
  • permission requests, failure states, retries, and completion states use a stable event shape.
• Quality criteria:
  • Cowork/Code no longer flash rapidly during long-running tool sequences.
  • file path/debug detail remains collapsed by default.

Phase D. Timeline Render Parity

• Reference: src/screens/REPL.tsx, src/components/Messages.tsx
• AX apply location: src/AxCopilot/Views/ChatWindow.xaml, src/AxCopilot/Views/ChatWindow.xaml.cs
• Completion criteria:
  • assistant/user messages, execution logs, compact boundaries, and queue summaries are rendered from one derived timeline model.
  • direct imperative bubble injection is removed from normal send/regenerate/retry flows.
• Quality criteria:
  • no blank assistant cards.
  • no token-only completion without visible content.
  • no duplicate event banners after re-render.

Phase E. Composer and Status Strip Simplification

• Reference: src/screens/REPL.tsx, src/components/StatusLine.tsx
• AX apply location: src/AxCopilot/Views/ChatWindow.xaml, src/AxCopilot/Views/ChatWindow.xaml.cs
• Completion criteria:
  • composer height grows only on explicit line breaks.
  • status strip, queue summary, and runtime activity all use debounced runtime updates.
  • Chat/Cowork/Code share one responsive width calculation policy.
• Quality criteria:
  • resizing feels natural.
  • composer does not keep growing after send.
  • metadata remains subordinate to the message timeline.

Phase F. Recovery, Resume, and Verification

• Reference: src/bootstrap/state.ts, src/bridge/sessionRunner.ts, src/screens/REPL.tsx
• AX apply location: src/AxCopilot/Views/ChatWindow.xaml.cs, src/AxCopilot/Services/Agent/AxAgentExecutionEngine.cs, src/AxCopilot/Services/ChatStorageService.cs
• Completion criteria:
  • reopen after interruption keeps queue, runtime summary, and latest visible assistant state consistent.
  • retry-last and regenerate do not depend on mutating InputBox.Text.
  • all three tabs pass reopen/retry/manual compact/manual stop/manual resume scenarios.
• Quality criteria:
  • stored conversation and rendered conversation stay identical after restore.
  • final reopened state matches the last completed runtime state.

Execution Tracks

1. Hook contract parity

• Structured hook output support (updatedInput, updatedPermissions, additionalContext).
• Runtime gating through settings toggles.

2. Session/state parity

• Deterministic run resume rules.
• Stable jsonl event schema + replay compatibility.

3. Recovery parity

• Failure-type classification and standardized retry guidance.
• Reduced repeated wrong-tool loops.

4. Completion parity

• Evidence-based finalization criteria for code/document tasks.

Done Criteria

• Internal parity scenarios pass target threshold.
• Resume/replay failures: zero.
• dotnet build warnings/errors: zero.

Validation Matrix

• Build: dotnet build src/AxCopilot/AxCopilot.csproj -c Release -v minimal -p:OutputPath=bin\\verify\\ -p:IntermediateOutputPath=obj\\verify\\
• Manual scenario 1: Chat send -> answer visible -> retry -> regenerate -> reopen conversation
• Manual scenario 2: Cowork tool run -> progress summary -> completion -> queue next request -> reopen
• Manual scenario 3: Code task with execution log noise -> completion -> compact -> next turn -> reopen
• Manual scenario 4: AX Agent internal settings change -> immediate runtime reflection without layout regression