fix(queue): keep tool action outcomes out of the steering queue (#20582)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents ask a person to approve a governed tool action (for example,
create a Notebook page) before the tool runs
> - Approve means run: the tool runs as soon as the person approves it,
and the approval card then shows Executed, Failed or Declined
> - After the tool runs, the server wakes the agent with the recorded
result. When another turn is active, that wake waits behind it
> - The composer queue lists waiting interaction receipts as messages.
The result wake carries the approval's interaction id and status, so the
queue shows "Accepted: Approve tool action" with an Interrupt control,
after the tool already ran
> - People read this row as an approval that is still not done, and
Interrupt stops their current turn only to deliver a tool result
> - This pull request keeps tool action outcome wakes out of the
composer queue and out of its steer, interrupt and discard actions
> - The benefit is a steering pane that shows only messages the person
can act on, while the agent still receives the tool result after the
current turn

## Linked Issues or Issue Description

**What happened?**
After a person approves a governed tool action, the tool runs and its
card shows Succeeded. When the person then sends a new message, the
composer queue shows a row "Accepted: Approve tool action" with
Interrupt and Discard controls. The row stays until the active turn
ends.

**What did you expect?**
The steering pane does not show the tool result as a queued message. The
approval card already shows the outcome. The agent receives the result
after the current turn.

**Steps to reproduce**
1. Let an agent request approval for a governed tool action
(`request_confirmation` with `payload.toolAction`).
2. Approve it. The tool runs and the card shows Succeeded.
3. Send a new message so a new turn starts before the result wake runs.
4. See "Accepted: Approve tool action" in the composer queue.

## What Changed

- Add `isToolActionOutcomeReceipt` in
`server/src/services/queued-interaction-response.ts`. It identifies an
interaction receipt wake that carries a tool action (`toolAction`
identity or `toolActionRequestIds`).
- `findQueuedCommentWake` in `server/src/routes/issues.ts` skips these
wakes, so `GET /issues/:id/queued-comments` does not list them. The
payload projection adds only the tool action's `actionRequestId`,
`toolName` and `toolActionRequestIds`, never its result text.
- The locked by-id queue lookup (steer, interrupt, discard) rejects
these wakes with `queued_comment_not_pending`, so a stale client cannot
interrupt a turn for a tool result.
- Delivery, stranded-queue recovery and the handback hold
(`readQueuedInteractionResponse`, `hasQueuedInteractionResponse`) do not
change. The agent still receives the result.
- Add route tests for accepted and declined tool action outcomes. They
check that the queue is empty, the wake stays
`deferred_issue_execution`, and the issue still has owed interaction
input.

## Verification

- `cd server && npx vitest run
src/__tests__/issue-queued-comments-routes.test.ts
src/services/issue-queued-comment-queue.test.ts`: 137 of 137 tests pass.
The new tests fail without the fix (the queue lists the receipt).
- On a heavily loaded machine (load average about 25), the embedded
Postgres `afterAll` teardown timed out once at 30 s after all tests
passed. This is not related to the change.
- `cd server && npx tsc --noEmit -p .`: clean.

## Risks

- Low risk. The change only filters the user-facing queue view and its
by-id actions.
- A tool action outcome wake no longer appears as an Interrupt target.
Before, Interrupt could deliver a tool result into a new turn early. Now
the result arrives when the current turn ends, as for other system
deliveries.
- #13160 refactors the same steering path. One of the two PRs may need a
small rebase.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, browser inspection of staging).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

server/src/__tests__/issue-queued-comments-routes.test.ts

@@ -575,6 +575,33 @@ describeEmbeddedPostgres("issue queued-comment routes", () => {
     expect(await db.select().from(heartbeatRuns)).toHaveLength(3);
   });
 
+  // A composer snapshot taken before the card was recognised as a tool action
+  // must not steer or interrupt the active turn just to deliver its result.
+  it.each([
+    { action: "steer", native: true },
+    { action: "interrupt", native: false },
+  ] as const)("refuses to $action with a tool action's outcome from a stale snapshot", async ({ action, native }) => {
+    const seeded = await seedResponseQueue(native);
+    const client = app(seeded.companyId);
+    const stale = await request(client).get(`/api/issues/${seeded.issueId}/queued-comments`).expect(200);
+    expect(stale.body.entries).toHaveLength(1);
+    await db.update(issueThreadInteractions).set({ title: "Approve tool action", payload: { version: 1, prompt: "Create the page?",
+      toolAction: { toolName: "notebook_create_page", actionRequestId: randomUUID() } } as never })
+      .where(eq(issueThreadInteractions.id, seeded.interactionId));
+    const steerCalls = steerNativeSessionMock.mock.calls.length;
+    const body = { queueId: seeded.wakeId, targetRunId: seeded.runId, revision: stale.body.revision };
+    const endpoint = action === "steer"
+      ? `/api/issues/${seeded.issueId}/queued-comments/${seeded.interactionId}/steer`
+      : `/api/issues/${seeded.issueId}/queued-comments/interrupt`;
+    const result = await request(client).post(endpoint).send(body).expect(409);
+    expect(result.body.details.code).toBe("queued_comment_not_pending");
+    expect(steerNativeSessionMock.mock.calls).toHaveLength(steerCalls);
+    expect((await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, seeded.runId)))[0].status).toBe("running");
+    // The result is still owed to the agent after the current turn.
+    expect((await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.id, seeded.wakeId)))[0].status)
+      .toBe("deferred_issue_execution");
+  });
+
   it("steers a saved approval only on click and acknowledges retries once", async () => {
     const seeded = await seedResponseQueue(true);
     await seedDispatchIdentity(seeded);
@@ -791,6 +818,37 @@ describeEmbeddedPostgres("issue queued-comment routes", () => {
     expect(await hasQueuedInteractionResponse(db, seeded.companyId, seeded.issueId, seeded.agentId)).toBe(true);
   });
 
+  // Approve = run: the tool already ran (or was declined) when its outcome wake
+  // is deferred behind a later turn. That wake hands the recorded result to the
+  // agent; it is not a message the person still has to send, so the composer
+  // queue must not show it as "Accepted: Approve tool action".
+  // The outcome delivery carries the tool action; a recovered continuation
+  // carries only the interaction id, so the saved card must decide.
+  it.each((["delivery", "recovery"] as const).flatMap(wakeShape => ([
+    { status: "accepted", outcome: "executed", wakeShape },
+    { status: "rejected", outcome: "rejected", wakeShape },
+  ] as const)))("does not queue a $status tool action's outcome ($wakeShape wake) as a message", async ({ status, outcome, wakeShape }) => {
+    const toolActionCase = {
+      kind: "request_confirmation", status, title: "Approve tool action", label: `${status}`,
+      payload: { version: 1, prompt: "Create the page?", toolAction: { toolName: "notebook_create_page", actionRequestId: randomUUID() } },
+      result: { version: 1, outcome: status, toolAction: { executionStatus: outcome, resultSummary: "Page created" } },
+    } as unknown as (typeof deliveredReceiptCases)[number];
+    const seeded = await seedDeliveredReceipt(toolActionCase, null);
+    const [wake] = await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.id, seeded.staleWakeId));
+    if (wakeShape === "delivery") {
+      const toolAction = { toolName: "notebook_create_page", actionRequestId: randomUUID(), executionStatus: outcome };
+      await db.update(agentWakeupRequests).set({ requestedByActorType: "user", requestedByActorId: "queue-owner",
+        payload: { ...wake.payload, interactionKind: "request_confirmation", toolAction, toolActions: [toolAction],
+          toolActionRequestIds: [toolAction.actionRequestId] } }).where(eq(agentWakeupRequests.id, seeded.staleWakeId));
+    }
+    const queue = await request(app(seeded.companyId)).get(`/api/issues/${seeded.issueId}/queued-comments`).expect(200);
+    expect(queue.body.entries).toEqual([]);
+    // Hiding the row must not drop the outcome: the agent still receives it.
+    const [after] = await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.id, seeded.staleWakeId));
+    expect(after.status).toBe("deferred_issue_execution");
+    expect(await hasQueuedInteractionResponse(db, seeded.companyId, seeded.issueId, seeded.agentId)).toBe(true);
+  });
+
   it("shows a later undelivered receipt instead of an earlier delivered one", async () => {
     const seeded = await seedDeliveredReceipt(deliveredReceiptCases[3], "succeeded");
     const pendingId = randomUUID();

server/src/routes/issues.ts

@@ -7602,7 +7602,8 @@ export function issueRoutes(
       if (wake.status === "deferred_issue_execution") {
         if (isReceipt) {
           const response = await readReceipt();
-          if (response) receipt = { wake, state: "deferred", queueRun: null, response };
+          // A tool action's outcome is delivered, never listed (approve = run).
+          if (response && !response.toolActionOutcome) receipt = { wake, state: "deferred", queueRun: null, response };
           continue;
         }
         return { wake, state: "deferred", queueRun: null };
@@ -7624,7 +7625,7 @@ export function issueRoutes(
         .then((runRows) => runRows[0] ?? null);
       if (queueRun && isReceipt) {
         const response = await readReceipt();
-        if (response) receipt = { wake, state: "queued", queueRun, response };
+        if (response && !response.toolActionOutcome) receipt = { wake, state: "queued", queueRun, response };
       }
       else if (queueRun) return { wake, state: "queued", queueRun };
     }
@@ -7790,7 +7791,11 @@ export function issueRoutes(
     if (
       !wake ||
       readObject(wake.payload).issueId !== input.issue.id ||
-      (queuedCommentIdsFromWakePayload(wake.payload).length === 0 && !queuedInteractionId(wake.payload))
+      (queuedCommentIdsFromWakePayload(wake.payload).length === 0 && !queuedInteractionId(wake.payload)) ||
+      // A tool action's outcome is never a message to steer, interrupt or discard.
+      (queuedInteractionId(wake.payload) &&
+        (await readQueuedInteractionResponse(input.tx as unknown as Db, input.issue.companyId, input.issue.id, wake.payload))
+          ?.toolActionOutcome)
     ) {
       throw conflict("The queued message is no longer pending", {
         code: "queued_comment_not_pending",

server/src/services/queued-interaction-response.ts

@@ -16,6 +16,20 @@ export function queuedInteractionId(payload: unknown): string | null {
     ? p.interactionId : null;
 }
 
+/**
+ * A governed tool action resolves as approve = run: by the time a receipt for
+ * it waits behind another turn, the tool already ran or was declined, and the
+ * approval card shows that outcome. The receipt only hands the recorded result
+ * to the agent. It still counts as owed input for delivery and recovery, but it
+ * is not a message the person can send, steer or interrupt with, so the
+ * composer queue never lists it. The saved interaction decides this, because a
+ * recovered wake does not carry the tool action fields of the original one.
+ */
+export function isToolActionConfirmation(interaction: { kind: string; payload?: unknown }): boolean {
+  const toolAction = record(record(interaction.payload).toolAction);
+  return interaction.kind === "request_confirmation" && Object.keys(toolAction).length > 0;
+}
+
 /**
  * One readable line for a queued response. The steering body also carries the
  * typed JSON receipt for the agent; people only ever see this line.
@@ -115,7 +129,7 @@ export async function readQueuedInteractionResponse(db: Db, companyId: string, i
     requiresFreshSession: record(record(payload)._paperclipWakeContext).forceFreshSession === true,
     summary: heading,
   };
-  return { comment, source };
+  return { comment, source, toolActionOutcome: isToolActionConfirmation(interaction) };
 }
 
 /** A saved answer is a live continuation, even though its card is no longer pending. */