fix: tighten acp tool updates

Author: thymikee

docs/adr/0008-command-descriptor-registry.md

@@ -47,8 +47,8 @@ every consumer table is **derived** by pure, parity-tested projection:
 
 ACP is a consumer of the command surface, not a new command registry. It advertises the same runnable
 commands through `available_commands_update` and parses prompt text into CLI-shaped command lines
-before executing through the existing command contracts and `AgentDeviceClient` path. Its slash-command
-syntax is an ACP transport affordance, not a separate command identity.
+before executing through the CLI command reader, existing command contracts, and `AgentDeviceClient`.
+Its slash-command syntax is an ACP transport affordance, not a separate command identity.
 
 This **composes with**, and is bound by, ADR 0003's four invariants: daemon-owned declaration (never inlined
 into the public surface), the predicate interface unchanged, no leakage of daemon-only traits into public

src/acp/__tests__/prompt-runner.test.ts

@@ -145,8 +145,14 @@ test('unparseable lines fail individually while runnable lines still execute', a
   assert.equal(stopReason, 'end_turn');
   assert.deepEqual(executed, ['devices']);
   const failedCall = updates[0] as Extract<AcpSessionUpdate, { sessionUpdate: 'tool_call' }>;
-  assert.equal(failedCall.status, 'failed');
-  assert.match(JSON.stringify(failedCall.content), /Unknown command: frobnicate/);
+  assert.equal(failedCall.status, 'in_progress');
+  const failedUpdate = updates[1] as Extract<
+    AcpSessionUpdate,
+    { sessionUpdate: 'tool_call_update' }
+  >;
+  assert.equal(failedUpdate.toolCallId, failedCall.toolCallId);
+  assert.equal(failedUpdate.status, 'failed');
+  assert.match(JSON.stringify(failedUpdate.content), /Unknown command: frobnicate/);
 });
 
 test('sticky flags from one line carry into later lines of the same session', async () => {
@@ -213,6 +219,33 @@ test('screenshot results attach an inline image when the artifact is readable',
   assert.ok(image, 'expected an inline image content block');
 });
 
+test('large ref-issuing command results omit rawOutput from completed tool updates', async () => {
+  const rawOutputs: unknown[] = [];
+  const runner = runnerWith({
+    runCommandLine: async ({ command }) => ({
+      result:
+        command === 'snapshot'
+          ? { nodes: [{ ref: 'e1', label: 'Checkout' }], refsGeneration: 7 }
+          : { ref: '@e1', label: 'Checkout', refsGeneration: 7 },
+      cliOutput: { data: {}, text: `${command} done` },
+    }),
+  });
+  const { updates, sendUpdate } = collectUpdates();
+
+  await runner.runPrompt({
+    session: makeSession(),
+    promptText: 'snapshot -i\nfind Checkout',
+    sendUpdate,
+  });
+
+  for (const update of updates) {
+    if (update.sessionUpdate === 'tool_call_update' && update.status === 'completed') {
+      rawOutputs.push(update.rawOutput);
+    }
+  }
+  assert.deepEqual(rawOutputs, [undefined, undefined]);
+});
+
 test('daemon progress events stream as in_progress tool call updates', async () => {
   let progressSink: RequestProgressSink | undefined;
   const runner = runnerWith({

src/acp/prompt-runner.ts

@@ -53,14 +53,7 @@ export function createPromptRunner(deps: PromptRunnerDeps = {}): PromptRunner {
       for (const line of lines) {
         if (session.cancelled) return 'cancelled';
         if (line.kind === 'error') {
-          sendUpdate({
-            sessionUpdate: 'tool_call',
-            toolCallId: nextToolCallId(session),
-            title: line.line,
-            kind: 'other',
-            status: 'failed',
-            content: [textContent(line.error)],
-          });
+          sendParseErrorToolCall(session, line, sendUpdate);
           outcomes.push(`✗ ${line.line} — ${line.error}`);
           continue;
         }
@@ -124,7 +117,7 @@ async function runCommandToolCall(params: {
       toolCallId,
       status: 'completed',
       content: commandResultContent({ line, result, text: cliOutput?.text ?? undefined, deps }),
-      rawOutput: result,
+      ...rawOutputUpdate(line, result),
     });
     return `✓ ${line.line}`;
   } catch (error) {
@@ -140,6 +133,32 @@ async function runCommandToolCall(params: {
   }
 }
 
+function sendParseErrorToolCall(
+  session: AcpSessionState,
+  line: { line: string; error: string },
+  sendUpdate: AcpUpdateSink,
+): void {
+  const toolCallId = nextToolCallId(session);
+  sendUpdate({
+    sessionUpdate: 'tool_call',
+    toolCallId,
+    title: line.line,
+    kind: 'other',
+    status: 'in_progress',
+  });
+  sendUpdate({
+    sessionUpdate: 'tool_call_update',
+    toolCallId,
+    status: 'failed',
+    content: [textContent(line.error)],
+  });
+}
+
+function rawOutputUpdate(line: RunnableLine, result: unknown): { rawOutput?: unknown } {
+  if (line.command === 'snapshot' || line.command === 'find') return {};
+  return { rawOutput: result };
+}
+
 function commandResultContent(params: {
   line: RunnableLine;
   result: unknown;

src/utils/cli-command-overrides.ts

@@ -13,7 +13,7 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = {
   acp: {
     helpDescription: `Start the stdio ACP (Agent Client Protocol) agent.
 
-ACP is a deterministic agent interface for ACP-capable editors and agent clients. It does not add LLM behavior: each text prompt line is parsed as one agent-device command line, with optional ACP slash-command syntax such as /devices or /snapshot -i. Commands execute through the same command contracts and AgentDeviceClient path as CLI/MCP commands, while stdout remains newline-delimited JSON-RPC only.`,
+ACP is a deterministic agent interface for ACP-capable editors and agent clients. It does not add LLM behavior: each text prompt line is parsed as one agent-device command line, with optional ACP slash-command syntax such as /devices or /snapshot -i. Commands execute through the CLI command reader, shared command contracts, and AgentDeviceClient; stdout remains newline-delimited JSON-RPC only.`,
     summary: 'Start ACP agent',
   },
   cdp: {

website/docs/docs/agent-setup.md

@@ -9,7 +9,7 @@ description: Configure Cursor, Codex, Claude Code, Windsurf, Cline, Goose, Zed,
 
 Use this page to wire Cursor, Codex, Claude Code, Windsurf, Cline, Goose, Zed, ACP clients, or another coding agent into mobile, TV, desktop, and web app verification. It covers skills, project rules, MCP setup, and ACP setup for React Native QA, Expo app verification, iOS Simulator automation, Android Emulator automation, tvOS checks, Android TV checks, web browser sessions, debugging, profiling, and exploratory QA.
 
-The short version: install the CLI, make the agent read version-matched help, and let the agent use CLI commands, MCP tools, or the ACP agent depending on what its client supports. MCP tools and ACP command turns use command contracts backed by the same `AgentDeviceClient` execution path as the CLI adapters.
+The short version: install the CLI, make the agent read version-matched help, and let the agent use CLI commands, MCP tools, or the ACP agent depending on what its client supports. MCP tools and ACP command turns share command contracts and the same daemon/client implementation; ACP reads CLI-shaped prompt lines while MCP receives structured tool input.
 
 ## Prerequisite: install the CLI
 
@@ -92,10 +92,12 @@ Registry metadata uses MCP name `io.github.callstackincubator/agent-device`, npm
 
 ## ACP agent (Zed and other ACP clients)
 
-`agent-device acp` starts a stdio [ACP](https://agentclientprotocol.com/) (Agent Client Protocol) agent, so ACP clients such as Zed can drive devices from the agent panel. It is a deterministic agent, not an LLM: each line of a prompt is one agent-device command in CLI syntax (ACP slash commands such as `/devices` and an optional leading `agent-device` are accepted), executed through the same command contracts and `AgentDeviceClient` path as MCP tools. Command executions stream back as ACP tool calls with daemon progress updates, screenshots attach as inline images, and available commands are advertised per session.
+`agent-device acp` starts a stdio [ACP](https://agentclientprotocol.com/) (Agent Client Protocol) agent, so ACP clients such as Zed can drive devices from the agent panel. It is a deterministic agent, not an LLM: each line of a prompt is one agent-device command in CLI syntax (ACP slash commands such as `/devices` and an optional leading `agent-device` are accepted), executed through the CLI command reader, shared command contracts, and `AgentDeviceClient`. Command executions stream back as ACP tool calls with daemon progress updates, screenshots attach as inline images, and available commands are advertised per session.
 
 Target selection sticks within a session: after `open com.example.app --platform ios`, later lines such as `snapshot -i` reuse the same `--platform`, `--device`, `--udid`, `--session`, and `--state-dir` values until a line overrides them. Project config resolution uses the working directory the ACP client passes on `session/new`.
 
+Refs follow CLI semantics in ACP prompts. MCP tools auto-pin plain refs across tool calls, but ACP prompt lines do not add MCP ref-generation pins; after another `snapshot` or `find`, use the current refs from the latest output or durable selectors.
+
 Zed `settings.json`:
 
 ```json

website/docs/docs/commands.md

@@ -38,7 +38,7 @@ For ACP-aware clients that support Agent Client Protocol agents, run:
 agent-device acp
 ```
 
-The ACP agent exposes installed commands as a deterministic prompt-line interface. ACP clients send prompt text such as `/devices` or `snapshot -i`; `agent-device` parses one command per line, executes through the same command contracts and `AgentDeviceClient` path, streams ACP tool-call updates, and refuses natural-language prompts instead of guessing.
+The ACP agent exposes installed commands as a deterministic prompt-line interface. ACP clients send prompt text such as `/devices` or `snapshot -i`; `agent-device` parses one command per line, executes through the CLI command reader, shared command contracts, and `AgentDeviceClient`, streams ACP tool-call updates, and refuses natural-language prompts instead of guessing.
 
 ## Navigation
 

website/docs/docs/introduction.md

@@ -63,7 +63,7 @@ It complements scripted test frameworks such as Appium, Maestro, Detox, XCTest,
 
 MCP support exposes direct structured tools for installed `agent-device` commands. Tools use structured input contracts through `AgentDeviceClient`, so MCP clients can call device workflows directly while the daemon remains the execution source of truth.
 
-ACP support exposes a deterministic stdio agent for ACP-capable editors and agent clients. The ACP agent interprets prompt text as explicit `agent-device` command lines, including advertised slash commands such as `/devices`, and executes them through the same command contracts and `AgentDeviceClient` path. It is not an LLM and does not guess natural-language actions.
+ACP support exposes a deterministic stdio agent for ACP-capable editors and agent clients. The ACP agent interprets prompt text as explicit `agent-device` command lines, including advertised slash commands such as `/devices`, and executes them through the CLI command reader, shared command contracts, and `AgentDeviceClient`. It is not an LLM and does not guess natural-language actions.
 
 ## Next steps