Agents lack a secure, turn-scoped path for proposing terminal actions

[vanzue]

Note

This issue documents the problem addressed by #484. It focuses on transporting and confirming terminal-action proposals. Reporting the eventual output or exit status of a confirmed command is a separate problem.

Problem

Terminal Agent and Autofix need to propose actions such as:

• Run or insert a command in an existing pane.
• Open a tab or split.
• Start a delegated task.
• Present multiple choices for user confirmation.

These proposals must appear as trusted recommendation cards and must not mutate the terminal until the user confirms them.

Previously, there was no reliable end-to-end contract for an agent to submit these proposals.

Parsing structured JSON from ACP Assistant messages is not an acceptable transport:

• Assistant text is user-visible chat content, not a trusted control channel.
• Ordinary model output could accidentally resemble an action payload.
• Parsing chat text conflates explanation with terminal mutation.
• The agent receives no immediate validation feedback.
• Invalid or unsupported proposals can silently degrade into text.
• Session, tab, pane, and turn ownership cannot be safely established from model-authored JSON.

Routing proposal state through wta-master is also undesirable. The master owns the shared agent process and multiplexes ACP sessions, but recommendation cards and their lifecycle belong to an individual Helper. Routing proposal tokens and acknowledgements through the master adds unnecessary shared state and increases the risk of cross-tab, stale-turn, and lifecycle errors.

User impact

Without a dedicated proposal path:

1. An agent may describe a useful terminal action but cannot reliably surface the existing recommendation-card UI.
2. The application may need to interpret visible Assistant text as executable intent.
3. A proposal can outlive the turn, session, Helper, or pane for which it was generated.
4. A proposal may be routed to the wrong Helper when multiple tabs or windows share one agent process.
5. Users may see duplicate confirmation prompts: one from ACP permission handling and another from the recommendation card.
6. The agent cannot distinguish an accepted proposal from one rejected by validation, cancelled by the user, or invalidated by lifecycle changes.

Required behavior

Provide one explicit, typed path for terminal-action proposals with these properties:

• The agent submits the proposal by executing a canonical WTA CLI command.
• The proposal is routed directly to the Helper that owns the current turn.
• Proposal JSON contains actions only; it cannot select a Helper, session, window, tab, or pane.
• Each turn receives an opaque, short-lived, one-use channel.
• Only the exact canonical invocation for the current turn can be silently approved.
• Modified, unapproved, stale, cross-Helper, and replayed requests fail closed.
• Assistant text always remains visible chat content and is never parsed into actions.
• The existing recommendation card remains the only visible confirmation and terminal-mutation boundary.
• The agent receives both:
  • an immediate validation result;
  • the final user or lifecycle decision.

Proposed implementation

Use a short-lived WTA CLI process connected directly to a per-Helper named pipe:

Agent CLI
  -> wta propose-terminal-actions
  -> per-Helper named pipe
  -> recommendation card
  -> user confirmation
  -> existing wtcli/COM executor

At the start of each turn, the Helper issues an opaque channel and injects the canonical invocation into the agent prompt:

& "$env:WTA_CLI_PATH" propose-terminal-actions `
    --channel <opaque-turn-channel> `
    --payload-json '<compact-json>'

Before executing the command, the Agent CLI sends its normal ACP permission request. The owning Helper recognizes the exact canonical invocation, records the payload digest, and silently selects AllowOnce.

The short-lived CLI then connects directly to the Helper. The Helper validates:

• Helper ownership;
• active session and turn;
• channel freshness and lease;
• prior ACP permission approval;
• exact payload digest;
• one-use and replay state;
• proposal schema and action policy.

After validation, the Helper surfaces the existing recommendation card. The CLI remains connected until the user confirms or cancels the card, or until the proposal is invalidated.

wta-master continues to own the shared agent process, ACP multiplexing, and permission forwarding, but does not own proposal channels, payloads, cards, or results.

Out of scope

• Executing terminal actions from the proposal CLI itself.
• Parsing actions from Assistant text.
• Removing the existing recommendation-card confirmation.
• Treating arbitrary model-authored commands as trusted.
• Reporting the eventual stdout, stderr, or exit status of the confirmed command.
• Persisting proposal channels across Helper restarts.

Acceptance criteria

• Terminal Agent and Autofix can surface existing recommendation cards through the WTA CLI.
• Assistant JSON is rendered as ordinary chat text and never creates a card.
• No terminal mutation occurs before card confirmation.
• Exactly one visible user confirmation is required.
• Proposal JSON cannot choose its routing target.
• Wrong-Helper, stale-turn, expired, modified, unapproved, and replayed requests are rejected.
• Starting a new turn invalidates the previous turn's proposal channel.
• Stashing and restoring an agent pane preserves its active Helper and proposal state.
• Closing or restarting the Helper invalidates outstanding proposals.
• The agent receives structured validation and final-decision responses.
• Multiple tabs and windows cannot consume one another's proposals.

Related work

• Route WTA CLI terminal-action proposals directly to Helpers #484 implements the direct Helper proposal path described here.
• Supersedes the MCP-based proposal implementation in Superseded: Replace model-authored terminal action JSON with typed MCP proposals #428.