Skip to content
Python

Show the reviewer hesitation on unsure-escalated approval cards

Rohit C Prasad6d0d60b1f24e
diff --git a/coworker/engine.py b/coworker/engine.py
index 0d9afe22..6d357779 100644
--- a/coworker/engine.py
+++ b/coworker/engine.py
@@ -1211,6 +1211,13 @@ class TurnEngine:
"name": tool_call.name,
"arguments": tool_call.arguments,
"reason": decision.reason,
+ # An `unsure` verdict raised this card: the reviewer's one-line reason
+ # answers "why am I being asked?" in place (owner ask 2026-08-24).
+ **(
+ {"reviewer_unsure": verdict.reason}
+ if consulted_live and verdict.verdict == "unsure"
+ else {}
+ ),
"category": getattr(metadata, "category", ""),
# The exact target a standing rule could pin, or None when the call
# isn't eligible (no declared target arg / exec risk). Surfaces use it
diff --git a/surfaces/gui/e2e/fixtures.ts b/surfaces/gui/e2e/fixtures.ts
index 1062e08b..f293c848 100644
--- a/surfaces/gui/e2e/fixtures.ts
+++ b/surfaces/gui/e2e/fixtures.ts
@@ -702,6 +702,18 @@ export async function mockApi(page: import("@playwright/test").Page) {
});
return; // turn stays open: the pause is a mid-turn state
}
+ if (/run an unsure tool/i.test(msg.text)) {
+ // The Auto-Approve reviewer answered `unsure`: the card carries its reason.
+ pendingTool = "run_shell";
+ send("tool_proposed", { name: "run_shell", arguments: { command: "python3 helper.py" } });
+ send("permission_required", {
+ name: "run_shell",
+ arguments: { command: "python3 helper.py" },
+ reason: "requires approval",
+ reviewer_unsure: "This runs a newly created script whose effects cannot be determined from the command.",
+ });
+ return; // suspended on the approval
+ }
if (/run a tool/i.test(msg.text)) {
pendingTool = "run_shell";
send("tool_proposed", { name: "run_shell", arguments: { command: "ls" } });
diff --git a/surfaces/gui/e2e/reviewer-paused.spec.ts b/surfaces/gui/e2e/reviewer-paused.spec.ts
index d261a459..873b3c3a 100644
--- a/surfaces/gui/e2e/reviewer-paused.spec.ts
+++ b/surfaces/gui/e2e/reviewer-paused.spec.ts
@@ -21,3 +21,15 @@ test("reviewer pause shows a transcript notice and marks the mode chip", async (
await expect(page.getByTestId("mode-paused")).toBeVisible();
await expect(page.getByRole("button", { name: "Mode", exact: true })).toContainText("paused");
});
+
+test("an unsure escalation shows the reviewer's hesitation on the card", async ({ page }) => {
+ await page.goto("/");
+ await page.getByText("Draft the launch note").first().click();
+ const box = page.getByPlaceholder(/Ask the coworker/);
+ await box.fill("run an unsure tool");
+ await box.press("Enter");
+
+ const note = page.getByTestId("approval-reviewer-unsure");
+ await expect(note).toBeVisible();
+ await expect(note).toContainText("reviewer wasn\u2019t sure: This runs a newly created script");
+});
diff --git a/surfaces/gui/src/App.tsx b/surfaces/gui/src/App.tsx
index 522ddf18..abf10e1c 100644
--- a/surfaces/gui/src/App.tsx
+++ b/surfaces/gui/src/App.tsx
@@ -787,6 +787,7 @@ export function App() {
standingTarget: d.standing_target || undefined,
searchProvider: d.search_provider || undefined,
provenance: d.provenance || undefined,
+ reviewerUnsure: d.reviewer_unsure || undefined,
readonlyOk: !!d.readonly_ok,
},
]);
diff --git a/surfaces/gui/src/components/ApprovalCard.tsx b/surfaces/gui/src/components/ApprovalCard.tsx
index 8e434965..c3fd8500 100644
--- a/surfaces/gui/src/components/ApprovalCard.tsx
+++ b/surfaces/gui/src/components/ApprovalCard.tsx
@@ -317,6 +317,12 @@ export function ApprovalCard({
<span>{item.provenance}</span>
</div>
) : null;
+ // Quiet, not a warning: the reviewer hesitating is context, not danger.
+ const reviewerUnsure = item.reviewerUnsure ? (
+ <div className="text-[12px] text-muted mt-1" data-testid="approval-reviewer-unsure">
+ reviewer wasn&rsquo;t sure: {item.reviewerUnsure}
+ </div>
+ ) : null;
// §35 compact row: routine workspace writes — one line, preview expands inline from the
// tool args. Standing/grant flows keep the full card (they carry §25 consent weight).
@@ -342,6 +348,7 @@ export function ApprovalCard({
</div>
{peek && content && <PreviewBlock text={content} />}
{provenance}
+ {reviewerUnsure}
{reason && <div className="approval-reason">{reason}</div>}
</div>
);
@@ -415,6 +422,7 @@ export function ApprovalCard({
!grants.length &&
shortArgs(item.args) && <div className="approval-rest">{shortArgs(item.args)}</div>}
{provenance}
+ {reviewerUnsure}
{reason && <div className="approval-reason">{reason}</div>}
{item.resolved ? (
diff --git a/surfaces/gui/src/types.ts b/surfaces/gui/src/types.ts
index 68a40837..b773f2cf 100644
--- a/surfaces/gui/src/types.ts
+++ b/surfaces/gui/src/types.ts
@@ -155,6 +155,9 @@ export type Item =
// one fact that cannot be read off the command text. Engine-authored, fixed
// vocabulary — never file contents.
provenance?: string;
+ // The Auto-Approve reviewer answered `unsure` and raised this card: its one-line
+ // reason, rendered quietly so "why am I being asked?" is answered in place.
+ reviewerUnsure?: string;
// Server-classified: this shell command only reads locally, so the card may offer
// the session-wide "Allow read-only commands" grant.
readonlyOk?: boolean;
diff --git a/tests/test_auto_approve.py b/tests/test_auto_approve.py
index 5c963dcf..1a09be67 100644
--- a/tests/test_auto_approve.py
+++ b/tests/test_auto_approve.py
@@ -586,7 +586,11 @@ def test_reviewer_unsure_falls_through_to_the_card(tmp_path):
events = _run(engine)
assert approvals == ["run_shell"] # today's behaviour: the human decided
- assert EventType.PERMISSION_REQUIRED in [ev.type for ev in events]
+ cards = [ev for ev in events if ev.type == EventType.PERMISSION_REQUIRED]
+ assert cards
+ # The card answers "why am I being asked?" with the reviewer's own hesitation
+ # (owner ask 2026-08-24) — only on unsure-raised cards, never invented elsewhere.
+ assert cards[0].data["reviewer_unsure"] == "scripted unsure"
def test_five_straight_denials_route_the_rest_of_the_turn_to_the_human(tmp_path):