Redesign session MCP tools around user intent (#683)

* Redesign session MCP tools around user intent

Replace mechanical terminal send/open actions with distinct command, workspace, and delegation tools whose names and fields match user intent. Keep schemas strict, routing trusted, and prompts, permissions, docs, and E2E fixtures aligned.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Simplify the terminal agent prompt

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Resolve unfamiliar command-like identifiers first

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Address Session MCP review feedback

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Align MCP text schemas with runtime validation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Require dynamic Session MCP titles for hiding

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Clarify terminal action execution ownership

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Describe Session MCP actions by user outcome

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Finalize intent-based Session MCP actions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Address Session MCP review feedback

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Clarify Session MCP workspace fields

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

* Use public delegation error wording

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

---------

Copilot-Session: 7bf01f6f-59c6-43fa-b68d-ffa432fde56d

Author: vanzue

AGENTS.md

@@ -25,8 +25,8 @@ Agent or human CLI --> wta/wtcli --> COM IProtocolServer --> Windows Terminal
   using the same key share one process and multiplex sessions through it.
 - **WT Protocol** is the terminal-control boundary. `wtcli.exe` activates
   `IProtocolServer` through the package COM registration.
-- **Session MCP** exposes `terminal_send`, `terminal_open`,
-  `terminal_open_and_send`, and `request_user_input`.
+- **Session MCP** exposes `run_command_in_current_shell`, `create_workspace`,
+  `delegate_task_in_new_workspace`, and `request_user_input`.
   It routes requests to the owning helper and never executes terminal actions
   itself.
 - Agent panes are ordinary `ConptyConnection` panes hosting `wta-helper`; C++

doc/release-check-list.md

@@ -203,7 +203,9 @@ Net effect: UT shrinks the manual matrix to "did the wiring and UI connect", not
 - [ ] `C260` `[new]` `[UT✓]` `[E2E]` **Leaving BYOK restarts and restores cloud models:** Clearing the custom model selection rebuilds the shared agent stack, reconnects Copilot without provider overrides, and restores its native cloud catalog. _(UT: clean cloud discovery and settings rebuild tests; #447; E2E: `Feature.ByokProvider`.)_
 - [ ] `C261` `[new]` `[UT✓]` `[E2E]` **Compact height keeps the recommendation and input usable:** At the real Agent Pane splitter minimum, the selected recommendation summary, Run/Insert actions, and editable input remain visible, and Insert still targets the owning shell without discarding its draft. _(UT: compact action-panel planning, recommendation rendering, and minimum-size tests; #580; E2E: `Feature.AgentCompactLayout`.)_
 - [ ] `C258` `[new]` `[UT✓]` `[E2E]` **Proposal MCP routing is isolated per tab:** Each ACP session receives a distinct proposal MCP server identity, and tool calls route only to that session's owning Helper even after another tab connects. _(UT: `server_configs_isolate_session_identity_and_capability`, proposal MCP capability routing tests; #560; E2E: `Feature.ProposalMcpRouting`.)_
-- [ ] `C284` `[new]` `[UT✓]` `[E2E]` **Tab-targeted terminal actions accept a direction hint across Session MCP:** A validated `open_and_send` request may retain a direction hint when its destination is a new tab. _(#599; E2E: `Feature.AgentProtocolExperience`.)_
+- [ ] `C284` `[new]` `[UT✓]` `[E2E]` **New-tab command workspaces accept a split-direction hint across Session MCP:** A validated `create_workspace` request with a command may retain a `split_direction` hint when its placement is `new_tab`. _(#599; E2E: `Feature.AgentProtocolExperience`.)_
+- [ ] `C285` `[new]` `[UT✓]` `[E2E]` **Empty workspaces open without sending a command across Session MCP:** After confirmation, `create_workspace` with `command` omitted creates a new empty terminal tab without typing the proposal summary into its shell. _(#683; E2E: `Feature.AgentProtocolExperience`.)_
+- [ ] `C286` `[new]` `[UT✓]` `[E2E]` **Delegated tasks reach the configured agent in a new workspace across Session MCP:** After confirmation, `delegate_task_in_new_workspace` opens a new terminal tab with the configured delegate command and passes it the exact requested task. _(#683; E2E: `Feature.AgentProtocolExperience`.)_
 - [x] `C081` `[UT✓]` **Unknown slash command is safe:** Unknown `/command` does not lose user input or crash.
 - [ ] `C225` `[E2E]` **`/agent` picker works:** `/agent` opens a keyboard-operable picker containing the current installed/allowed agents, and selecting the current agent is a safe no-op.
 - [ ] `C241` `[new]` `[E2E]` **`/agent` completion selection is safe:** Enter activates the highlighted matching agent without rebuilding the pane or changing the global default when it is already selected. _(#487; E2E: `Feature.PerTabAgent`.)_

doc/specs/WTA-terminal-action-proposals.md

@@ -13,19 +13,19 @@ and every eligible ACP session receives a distinct bearer capability:
 
 ```text
 ACP session
-  -> HTTP MCP: intellterm_<public-id>/{terminal_send,terminal_open,terminal_open_and_send,request_user_input}
+  -> HTTP MCP: intellterm_<public-id>/{run_command_in_current_shell,create_workspace,delegate_task_in_new_workspace,request_user_input}
   -> wta-master capability -> ACP SessionId
   -> session_to_helper -> existing master/helper ACP pipe
   -> owning Helper
-       -> terminal_* -> recommendation card -> wtcli/COM executor
+       -> action tool -> recommendation card -> wtcli/COM executor
        -> request_user_input -> blocking choice/freeform modal -> structured answer
 ```
 
 The endpoint presents typed terminal actions for review and blocking
 clarification questions. It cannot read or mutate Windows Terminal. The
 existing card confirmation is the sole mutation boundary.
 
-The `terminal_*` tools return as soon as the Helper commits its card;
+The three action tools return as soon as the Helper commits its card;
 confirmation or cancellation then happens independently. `request_user_input`
 deliberately keeps the MCP call open until the user answers, cancels, the
 caller disconnects, or the ten-minute timeout expires.
@@ -90,46 +90,82 @@ Server name:
 intellterm_<public-id>
 ```
 
-Tools:
+Tools (four total):
 
 ```text
-terminal_send
-terminal_open
-terminal_open_and_send
+run_command_in_current_shell
+create_workspace
+delegate_task_in_new_workspace
 request_user_input
 ```
 
+The first three are terminal-action proposal tools. `request_user_input` is a
+separate blocking clarification tool and does not create a terminal-action
+proposal.
+
 The server supports MCP `initialize`, `ping`, `tools/list`, and `tools/call`
 over stateless Streamable HTTP JSON-RPC. POST responses use JSON or HTTP 202
 for notifications; GET and DELETE return 405 because server-initiated streams
 are unnecessary. It exposes no terminal read or execution tools.
 
-Input, for `terminal_send`:
+Input, for `run_command_in_current_shell`:
 
 ```json
 {
-  "title": "Run tests",
-  "rationale": "Verify the current change.",
-  "input": "cargo test"
+  "summary": "Run tests",
+  "reason": "Verify the current change.",
+  "command": "cargo test"
 }
 ```
 
-Each MCP call proposes exactly one action. One tool per action shape, rather
-than a single tool with a `type` discriminator, so each schema advertises
-exactly the fields that action accepts and `additionalProperties: false`
-rejects a field belonging to another action. The action tools are:
-
-- `terminal_send`: submit input to the trusted active pane;
-- `terminal_open`: open an empty tab or panel;
-- `terminal_open_and_send`: open a tab or panel and submit input there.
+Each terminal-action MCP call proposes exactly one user-visible terminal
+outcome. The tools separate current-shell execution, workspace creation, and
+delegation rather than exposing a mechanical action discriminator. Each
+schema advertises exactly the fields that intent accepts, and
+`additionalProperties: false` rejects fields belonging to another intent. The
+action tools are:
+
+- `run_command_in_current_shell`: propose one shell command for the trusted
+  active pane;
+- `create_workspace`: create a new terminal workspace, optionally initialized
+  with one shell command;
+- `delegate_task_in_new_workspace`: start the configured delegate agent in a
+  new workspace with a self-contained task.
+
+The exact public payloads are:
+
+| Tool | Required | Optional |
+|---|---|---|
+| `run_command_in_current_shell` | `summary`, `command` | `reason` |
+| `create_workspace` | `summary`, `placement` | `reason`, `command`, `working_directory`, `split_direction`, `profile` |
+| `delegate_task_in_new_workspace` | `summary`, `task`, `placement` | `reason`, `working_directory`, `split_direction` |
+
+`placement` is `new_tab` or `new_split`. `split_direction` is `right`, `left`,
+`up`, `down`, or `auto`; it affects only `new_split` and is accepted but
+ignored for `new_tab` compatibility. `create_workspace.command` is optional:
+omitting it creates an empty workspace, while supplying it runs that command
+after creation. `delegate_task_in_new_workspace` deliberately exposes neither
+a profile nor an agent selector. The Helper always substitutes the configured
+delegate agent and rejects the request when no valid delegate is configured. A
+model cannot name an arbitrary agent.
+
+The Helper maps these public intents into the existing internal action model:
+
+| Public tool | Internal action |
+|---|---|
+| `run_command_in_current_shell` | `RecommendedAction::Send` |
+| `create_workspace` without `command` | `RecommendedAction::Open` |
+| `create_workspace` with `command` | `RecommendedAction::OpenAndSend` with delegation disabled |
+| `delegate_task_in_new_workspace` | `RecommendedAction::OpenAndSend` with delegation enabled and no profile |
 
-The open tools may include `cwd`, `profile`, and panel `direction`. The
-user-facing `title` also becomes the requested destination title.
-`terminal_open_and_send` may set `delegate: true`; the Helper substitutes the
-configured delegate agent. A model cannot name an arbitrary agent.
+`new_tab` maps to the existing `Tab` target and `new_split` maps to `Panel`.
+The user-facing `summary` becomes the recommendation title and, for workspace
+tools targeting `new_tab`, the initial tab title. `working_directory`,
+`split_direction`, and `profile` map to the existing internal fields without
+changing trusted active-pane routing.
 
-Autofix uses the same tools but the Helper supplies the trusted Autofix origin
-and requires a `terminal_send` action.
+Autofix uses only `run_command_in_current_shell`; the Helper supplies the
+trusted Autofix origin and requires the resulting internal `Send` action.
 
 Tool result statuses:
 
@@ -195,8 +231,8 @@ execution path.
 Permission remains an optional compatibility preflight. Some agents call MCP
 without requesting permission.
 
-When an adapter requests permission for one of the
-`intellterm_<public-id>/terminal_*` action tools, the Helper:
+When an adapter requests permission for one of the three terminal-action tools
+advertised by an `intellterm_<public-id>` server, the Helper:
 
 1. verifies the trusted ACP SessionId owns the current issued turn;
 2. silently selects `AllowOnce`; and

doc/specs/llm-agent-event-integration.md

@@ -446,16 +446,22 @@ exit $EXIT_CODE
 
 ### Pattern C: Native ACP hooks (zero-effort for ACP agents)
 
-Agents that speak ACP already have structured tool-use lifecycle. The ACP host
-(`wta` TUI mode) can emit events on their behalf — no agent modification needed:
+ACP agents can call the Session MCP terminal-action tools, but this path is a
+proposal handoff rather than an immediate execution/completion lifecycle:
 
 ```
-ACP agent calls tool "run_command"
-  → wta emits agent.tool.invoked {tool: "run_command", args_summary: "cargo test"}
-  → wta executes in pane
-  → wta emits agent.tool.completed {tool: "run_command", exit_code: 0, duration_ms: 4200}
+ACP agent calls tool "run_command_in_current_shell"
+  → Session MCP validates and routes the request to the owning Helper
+  → Helper creates and commits a confirmation card
+  → MCP returns accepted
+  → user later confirms or cancels the card
+  → on confirmation, the existing terminal executor runs the action
 ```
 
+`agent.tool.invoked` can represent the MCP call and proposal handoff. WTA
+currently receives no executor completion callback carrying an exit code or
+duration, so this path cannot emit `agent.tool.completed`.
+
 ### Pattern D: MCP tool (for MCP-connected agents)
 
 Expose `send_event` as an MCP tool so agents calling `wta mcp` can publish events

test/e2e/README.md

@@ -19,7 +19,7 @@ authenticated ACP agents. Current status (run on the Store package):
 | `Feature.FreFlow.Tests.ps1` | §0 FRE overlay click-through (Next→Save, privacy link, close-safety) | 5 |
 | `Feature.FreExecutionPolicy.Tests.ps1` | §0 FRE execution-policy verdict (deterministic via registry; **Dev**, auto-skips) | 3 (1 conditional skip) |
 | `Feature.AgentPaneInteraction.Tests.ps1` | open/hide/focus, input/rendering, slash, Copilot chat | 14 |
-| `Feature.AgentProtocolExperience.Tests.ps1` | PRs #599/#601/#606/#610/#611/#612/#616/#634: terminal actions, ACP tool/transcript rendering, clarification input, session configuration, model title, and replacement cleanup across the deployed helper/master boundary | 6 |
+| `Feature.AgentProtocolExperience.Tests.ps1` | PRs #599/#601/#606/#610/#611/#612/#616/#634/#683: intent-based terminal actions (including empty workspaces and configured delegation), ACP tool/transcript rendering, clarification input, session configuration, model title, and replacement cleanup across the deployed helper/master boundary | 8 |
 | `Feature.AgentImageAttachmentEditing.Tests.ps1` | PR #536: inline image tokens move and delete atomically while preserving adjacent prompt text | 1 |
 | `Feature.AgentModelSync.Tests.ps1` | PR #538: ACP config-option updates replace stale session model state in the active picker | 1 |
 | `Feature.AgentModelLifecycle.Tests.ps1` | PR #554: `/model` hot-apply and Settings-driven model restart/reconnect lifecycle | 2 |
@@ -54,11 +54,11 @@ authenticated ACP agents. Current status (run on the Store package):
 | `Feature.AgentChat.Tests.ps1` / `Feature.AgentPopup.Tests.ps1` | agent chat + `/` popup/menu interaction | 1 + 3 |
 | `Feature.AgentPaneMove.Tests.ps1` | PR #429: `/move` stays per-tab, preserves global position, and restores agent input focus | 1 |
 
-**Coverage: 139 of 141 automatable `[E2E]` checklist items are implemented.**
-**Test status: 124 baseline feature cases pass + 3 documented skips** (`wta sessions list` is
+**Coverage: 141 of 143 automatable `[E2E]` checklist items are implemented.**
+**Test status: 126 baseline feature cases pass + 3 documented skips** (`wta sessions list` is
 identity-gated — see `Feature.SessionList.Tests.ps1`), plus 2 PR #481 WSL-backend cases and 2
 PR #488 delegate-source cases that run only when a runnable distro (and, for the #481 chat
-case, an installed+authenticated native agent) is available. The 139 implemented checklist
+case, an installed+authenticated native agent) is available. The 141 implemented checklist
 items map to the baseline cases plus the deterministic settings/persistence assertions. The
 remaining new items are the two profile agent picker UIs; they stay explicit E2E work rather
 than being falsely credited by the JSON-level runtime tests. Other

test/e2e/fixtures/Mock-AcpInteractionAgent.ps1

@@ -104,10 +104,12 @@ function Invoke-UserInputTool {
     Invoke-RestMethod -Method Post -Uri $Server.url -Headers $headers -ContentType 'application/json' -Body $body
 }
 
-function Invoke-TerminalActionTool {
+function Invoke-SessionMcpTool {
     param(
         [Parameter(Mandatory)]$Server,
-        [Parameter(Mandatory)][string]$Marker
+        [Parameter(Mandatory)][string]$Name,
+        [Parameter(Mandatory)][hashtable]$Arguments,
+        [Parameter(Mandatory)][int]$Id
     )
 
     $headers = @{ 'mcp-protocol-version' = '2025-06-18' }
@@ -118,16 +120,11 @@ function Invoke-TerminalActionTool {
     }
     $body = @{
         jsonrpc = '2.0'
-        id = 2
+        id = $Id
         method = 'tools/call'
         params = @{
-            name = 'terminal_open_and_send'
-            arguments = @{
-                title = "Direction $Marker"
-                input = "echo $Marker"
-                target = 'tab'
-                direction = 'auto'
-            }
+            name = $Name
+            arguments = $Arguments
         }
     } | ConvertTo-Json -Depth 12 -Compress
     Invoke-RestMethod -Method Post -Uri $Server.url -Headers $headers -ContentType 'application/json' -Body $body
@@ -157,8 +154,9 @@ while ($null -ne ($line = [Console]::In.ReadLine())) {
         'session/new' {
             $sessionCounter++
             $sessionId = "interaction-$PID-$sessionCounter"
-            $sessionMcpServers[$sessionId] = @($request.params.mcpServers) | Select-Object -First 1
-            Write-FixtureLog -Message "session/new|$sessionId"
+            $server = @($request.params.mcpServers) | Select-Object -First 1
+            $sessionMcpServers[$sessionId] = $server
+            Write-FixtureLog -Message "session/new|$sessionId|mcp_server=$([string]$server.name)"
             Send-AcpMessage @{
                 jsonrpc = '2.0'
                 id = $request.id
@@ -282,7 +280,12 @@ while ($null -ne ($line = [Console]::In.ReadLine())) {
                     throw 'session/new did not provide a Session MCP server'
                 }
                 $marker = $Matches.marker
-                $response = Invoke-TerminalActionTool -Server $server -Marker $marker
+                $response = Invoke-SessionMcpTool -Server $server -Name 'create_workspace' -Id 2 -Arguments @{
+                    summary = "Direction $marker"
+                    command = "echo $marker"
+                    placement = 'new_tab'
+                    split_direction = 'auto'
+                }
                 $result = $response.result.structuredContent | ConvertTo-Json -Depth 20 -Compress
                 Write-FixtureLog -Message "tab-direction-result|$result"
                 Send-AcpMessage @{
@@ -291,6 +294,43 @@ while ($null -ne ($line = [Console]::In.ReadLine())) {
                     result = @{ stopReason = 'end_turn' }
                 }
             }
+            elseif ($promptText -match 'EMPTY_WORKSPACE_(?<marker>[A-F0-9]+)') {
+                $server = $sessionMcpServers[$sessionId]
+                if (-not $server) {
+                    throw 'session/new did not provide a Session MCP server'
+                }
+                $marker = $Matches.marker
+                $response = Invoke-SessionMcpTool -Server $server -Name 'create_workspace' -Id 3 -Arguments @{
+                    summary = "Empty workspace EMPTY_COMMAND_SENTINEL_$marker"
+                    placement = 'new_tab'
+                }
+                $result = $response.result.structuredContent | ConvertTo-Json -Depth 20 -Compress
+                Write-FixtureLog -Message "empty-workspace-result|$result"
+                Send-AcpMessage @{
+                    jsonrpc = '2.0'
+                    id = $request.id
+                    result = @{ stopReason = 'end_turn' }
+                }
+            }
+            elseif ($promptText -match 'DELEGATE_WORKSPACE_(?<marker>[A-F0-9]+)') {
+                $server = $sessionMcpServers[$sessionId]
+                if (-not $server) {
+                    throw 'session/new did not provide a Session MCP server'
+                }
+                $marker = $Matches.marker
+                $response = Invoke-SessionMcpTool -Server $server -Name 'delegate_task_in_new_workspace' -Id 4 -Arguments @{
+                    summary = "Delegate workspace $marker"
+                    task = "DELEGATED_TASK_$marker"
+                    placement = 'new_tab'
+                }
+                $result = $response.result.structuredContent | ConvertTo-Json -Depth 20 -Compress
+                Write-FixtureLog -Message "delegate-workspace-result|$result"
+                Send-AcpMessage @{
+                    jsonrpc = '2.0'
+                    id = $request.id
+                    result = @{ stopReason = 'end_turn' }
+                }
+            }
             else {
                 Send-TextUpdate -SessionId $sessionId -Text "ACK:$promptText"
                 Send-AcpMessage @{

test/e2e/fixtures/Mock-AcpProposalAgent.ps1

@@ -37,10 +37,10 @@ function Invoke-ProposalTool {
         id = 1
         method = 'tools/call'
         params = @{
-            name = 'terminal_send'
+            name = 'run_command_in_current_shell'
             arguments = @{
-                title = "Run echo $Marker"
-                input = "echo $Marker"
+                summary = "Run echo $Marker"
+                command = "echo $Marker"
             }
         }
     } | ConvertTo-Json -Depth 12 -Compress