CODAGT-757: run chat tool calls once, and cancel them truthfully

Status: revision 4, being implemented as two draft PRs. Earlier revisions are kept outside the repo (/home/coder/wt/PLAN-revision-2.md, PLAN-revision-3.md) and as local tags codagt-757-rev2/* and codagt-757-rev3/*.

Goal: the fewest lines that stop duplicate side effects and give truthful interrupt results. Rare cases that cost more than they are worth keep today's behavior (section 4).

1. Terms

2. User stories

• US1 One run per tool call. A task retry or an ownership change sends the same tool call ID; the agent returns the saved response (for execute, the running or exited process) instead of running again. Holds while the agent keeps running.
• US2 Interrupt stops unresolved execute. Foreground and background processes of unresolved calls are killed. The result is "tool call was canceled while running" with the output so far, or the real result if the command had finished.
• US3 Interrupted edits have a definite result. "tool call was canceled before it ran; no changes were made" if the agent never received the edit, otherwise the real edit result.
• US4 No run after an interrupt. A start, edit, or write that reaches the agent after the interrupt's cancel is refused.
• US5 Timeouts are not restarted. The agent keeps waitUntil from the first start, so a retried foreground execute waits only for the rest of its timeout.
• US6 Processes the model knows about survive. Only unresolved calls are canceled.
• US7 Old agents behave as today. They ignore the header; the cancel route responds with 404, which gives today's generic interrupt result. No detection code.
• US8 Chats stay apart. The agent keys tool call records and processes by chat ID. A tool call ID is read only from a request that has a chat ID; a process started without a chat ID is keyed by the zero UUID.

3. Design

Agent (agent/agenttoolcall, agentproc)

• Coder-Tool-Call-Id is read by agentchat.Middleware into agentchat.Context.ToolCallID, next to the chat ID (and logged as tool_call_id). Handlers and the middleware below read it from the context.

• A table keyed by chat ID and tool call ID. A record is running (with a channel that closes when the run finishes), done (with the saved response), or canceled.

• One middleware, registered once for the whole agent API right after agentchat.Middleware: a request whose context carries a tool call ID runs once per chat and ID. Without a tool call ID: unchanged. With it:

  Record	Action
  none	run the handler once, save its response, return it
  running or done	wait, return the saved response
  canceled	409, do nothing

  A handler panic saves a 500 saying the outcome is unknown, so repeats and cancels do not wait forever.

• POST /api/v0/tool-calls/{id}/cancel, mounted from Table.Routes(): no record stores a canceled record, kills a process with that ID (it outlives the record), and responds with received: false. A record is marked canceled, the cancel waits for the run to finish, kills its process if the ID has one, and responds with received: true and the saved response.

• Processes are keyed by chat ID and process ID. A process started with a tool call ID uses it as its process ID; a start for a key that already has a process returns that process. Output, signal, list, and kill see only the requester's chat's processes. The start request's timeout_ms sets the process's waitUntil at the first start; a repeat does not move it, and the process keeps running after it. A start with both background and a non-zero timeout_ms is rejected with 400, since only regular output waits read background processes. A blocking output wait with timeout_from_start_process=true (the execute tool's own wait) returns at exit, at waitUntil, or at the existing 5-minute cap; other waits, such as process_output's, ignore waitUntil. The output response reports timed_out (running past waitUntil) and canceled (killed by a cancel).

• Adding a record deletes records that no request or cancel has used for an hour (forgetAfter), to bound memory. chatd resends every unresolved call on each retry, and a long batch is retried about every 15 minutes, so a batch that chatd is still retrying keeps its records.

• Exited processes stay listed for an hour after they exit (5 minutes on main). Redesigning this retention is CODAGT-1220.

SDK (codersdk/workspacesdk)

• CoderToolCallIDHeader, WithToolCallID(ctx, id), ToolCallIDFromContext(ctx). Only StartProcess, EditFiles, and WriteFile send the header, because only they act.
• CancelToolCall(ctx, id) (CancelToolCallResponse, error); CancelToolCallResponse{Received bool; Status int; ContentType string; Body []byte} with one decoder per saved response, each calling the decode code of the method it mirrors: StartProcessResult(), EditFilesResult(), WriteFileResult().
• StartProcessRequest.TimeoutMs; ProcessOutputOptions.TimeoutFromStartProcess; ProcessOutputResponse.TimedOut, Canceled.

chatd (coderd/x/chatd)

• The dispatcher gives each tool call's context its tool call ID (chattool.ToolCallIDs), attached with WithToolCallID. Only the three acting SDK methods send it. A call whose provider tool call ID is empty or repeats in the message gets none and behaves as today, since calls sharing an ID would get each other's saved responses.

• execute foreground sends timeout_ms, waits with timeout_from_start_process=true, and waits until the output response reports exit or timed_out. chatd's own timeout, counted from each attempt, stays as a backstop, which gives an old agent (it ignores timeout_ms) today's behavior.

• The interrupt task reads the unresolved execute, edit_files, and write_file calls that have a tool call ID in its locked read (the same read that checks the chat is still in the state the task started for). After releasing the lock, it dials the agent once and sends one cancel per call, all at once, under one 30-second timeout. A cancel waits for a running call to finish, so sending them at once keeps one slow call from using up the others' time. A panic in one cancel gives that call the generic text. Results:

  Response	execute	edit_files / write_file
  received: false	read the output: not found gives the plain-text error tool call was canceled before it ran; no changes were made; found is handled like a saved success	tool call was canceled before it ran; no changes were made
  saved error response	the start error, as today	the edit or write error, as today
  saved success	read the output after the process exits (the kill does not wait for the exit): canceled gives tool call was canceled while running with the output so far, marked "canceled": true (the UI shows the killed marker); exited gives the real result	the edit or write result
  404, error, timeout	today's generic text, and a warning log	today's generic text, and a warning log

  Results go into the existing commit path (committedPendingLocalToolCancellationMessages, FinishInterruption) as a map by provider tool call ID.

4. Not handled

Retries keep today's behavior (the tool runs again):

• An agent restart mid-call. The restart already killed the process.
• A retry more than an hour after chatd last sent the call (for example after a coderd outage), once a newer tool call deleted the record, unless the process is still listed.
• An agent that stays connected but never responds.
• Two agent processes with one token at the same time.
• Windows: a cancel kills the sh process only, as process_signal does today.
• A process that exits on its own just before a cancel's kill can be reported as canceled while running.

An execute that finished early in a batch that stays unresolved (for example next to a long sibling) keeps its record while chatd retries, but its process is removed an hour after it exits, the next time any chat lists processes. Later retries then get an output error ("get process output: ...") instead of its result. It does not run again, but its output is lost (CODAGT-1220).

After a retry, an execute result's wall_duration_ms counts only the last attempt (a 20-minute timeout showed "for 5m" in UAT): chatd measures it per attempt, and the agent's responses do not carry the process's start time. The timeout itself counts from the first start (CODAGT-1243).

Interrupts give a false "canceled before it ran" when the agent has no record of a call that did reach it. Today these cases give the generic text. Accepted to keep the change small; a complete fix needs a record that survives the agent process or a comparison of the call's age with the agent's uptime, both rejected (section 6):

• an edit or write interrupted more than an hour after chatd last sent it (only after an outage, since every retry sends it again);
• an agent restart, or the chat moving to another agent, after the call ran;
• a rolling chatd upgrade in which an old replica ran the call without the header;
• an execute whose process exited more than an hour earlier and was dropped from the process list after the record was deleted.

A workspace that cannot be reached during the interrupt records no cancel, so a request that arrives later still runs. The committed result is today's generic text.

5. PRs

1. feat: run chat tool calls once per tool call ID on the agent #29946 mafredri/codagt-757/01-sdk-tool-call: agent and SDK.
2. feat: send tool call IDs and cancel unresolved calls on interrupt #29954 mafredri/codagt-757/02-agent-tool-call-records: chatd.

#29958, #29965, #29976, and #29978 are closed as superseded. Branches are rewritten from main and force-pushed (operator approval, 2026-09-28).

6. Decisions (2026-09-28, operator)

• LOC reduction first; do not pay for rare cases; relax user stories to allow simpler designs.
• No agent protobuf, manifest, agent API version, or coderd database changes. The contract lives in the agent HTTP API.
• No comparison between chatd's and the agent's clocks, and no old-agent detection. The one-hour expiry uses only the agent's clock.
• Interrupts kill unresolved background processes and processes past waitUntil (accepted earlier).
• Edits, archives, and other generic cancellations sending a cancel first: follow-up work (CODAGT-1222).
• Implement fast; reviews and fixes afterwards. Hooks are off in this workspace.
• After review: received: false for execute falls back to the process list, and the remaining false results are documented in section 4 rather than fixed. Attach and kill respect chat boundaries.
• Third-party review: adopted the panic fix, chat checks, the empty or repeated provider ID guard, the section 4 additions, and tests for concurrent requests, panics, cancels during a run, and cross-chat access. Rejected: buffering request bodies (write_file is atomic, so a cut-off upload saves a true error); retention counted from run end (recorded runs are short; the process list covers execute); restricting IDs to three tools and per-route middleware (the SDK sends the header only from the three acting methods); a mixed clock (already one clock); reporting time left on retry (the timeout counts from the first start).
• Only the execute tool's own wait stops at waitUntil (timeout_from_execute=true); process_output waits keep their own timeout. A background start with a timeout is rejected (operator, after the first review round).
• 2026-09-29, after Codex and Copilot review: interrupt cancels are sent at once, and the timeout is 30 seconds instead of 10, because a chance of a real result is worth the wait more than unknown results. Processes are keyed by chat ID and process ID; non-chat requests seeing chat processes was a bug, not compatibility to keep, and the key makes Codex's cross-chat start race unreachable. Exited processes stay an hour instead of 5 minutes; the redesign is CODAGT-1220. entryMaxAge is renamed forgetAfter.
• 2026-09-29, second review round: the interrupt reads its cancelable calls under the chat lock (ARCHITECTURE.md runner rule); the output read after a cancel waits for the exit; each cancel goroutine recovers panics. Not changed: a cancel that gives up (timeout, or chatd went away) does not kill a process whose start is still running, since the interrupt then records the generic text; the size cap keeps the default budget.
• 2026-09-29, third-party finding: a record's age was counted from when it was added, so in a batch with a long execute, an edit's record could be deleted while chatd still retried the batch, and the edit ran again. Every request or cancel that finds a record now resets its age. This replaces the earlier rejection of retention counted from run end.
• 2026-09-29, UAT round 1 (FAIL on one UI regression: canceled and not-run execute cards read "Ran ... for 0ms"): the canceled result passes the agent's canceled flag through as "canceled": true, and the UI shows it with the marker it already uses for commands killed by process_signal; "not run" is a plain-text error like the edits' "not applied" ("Failed to run"); a zero wall_duration_ms is left out. Rejected: marking the canceled JSON result is_error, which says "Failed to run" for a command that ran, makes interrupts the only execute failures flagged as errors, and would drop the output from the model on replay (only the error field of an is_error JSON part reaches it). The collapsed card not marking any failed command (exit code, timeout) is a separate UI question. The per-attempt duration after a retry is documented in section 4 (operator: a chatd and agent API issue; a WebSocket between them in the future would remove the blindness, and also the start-then-wait of execute).
• 2026-09-30, operator: one result text per outcome for all three tools, without naming the transport: tool call was canceled before it ran; no changes were made and tool call was canceled while running. CancelToolCall has a case per tool name and rejects other tools before sending. The agent's cancel hook is named cancel, not kill, because it also serves edits. ARCHITECTURE.md states the at-most-once exception and the interrupt's cancel step instead of a TODO. Comments keep only what the code does not show. TimeoutFromExecute (timeout_from_execute) is renamed TimeoutFromStartProcess (timeout_from_start_process), because it is part of the agent process API and should not be named after a chatd tool.
• Tests: each behavior is asserted once, at the highest layer that reaches it (real SDK and agent; one chatd end-to-end interrupt test with a real agent); unit tests only for what those cannot reach. Tests are deterministic: fake clock for time, no real-time deadlines or timed polls, assertions that hold in every interleaving.