Skip to content

fix(subagent): refuse tool requests once a stop is in progress - #20743

Merged
chenmingwei23 merged 2 commits into
mainfrom
replace/18955
Oct 15, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
replace/18955

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A sub-agent that the user has stopped never gets another tool approved, even when its session teardown fails.

A Stop on a running sub-agent tears its session down first and cancels the run task after that (subagent_manager/terminal.py, the reset in _force_reap, then _cancel_task_intentionally). When the run is waiting on a person for a tool approval through the dashboard, ApprovalCoordinator.request turns that cancel into a denial, so the run loop resumes and reads its next event.

When the teardown works, that read hits the dead stream and the run ends. The trigger needs two failures together: the session reset hangs past _RESET_TIMEOUT or raises, AND the SIGKILL fallback after it also fails to stop the process. Then the stream is still live. The backend's next permission request went through the normal ladder, and a grant that answers without a card (slot trust, --approval yolo or reads, auto_approve_sources, parent_policy=auto, a hook grant) approved a tool after the user pressed Stop.

Observed in-process with the real run loop, the real stop and the real approval coordinator, with fakes for the backend, the reset and the kill. The order in every run was: Stop, reset, kill failed, cancel, the approval returns denied, tool A rejected, the backend sends tool B, B is granted, approve_tool is sent for B.

Why it matters

A tool that runs after a Stop is the worst outcome a stop can have: the user pressed Stop to prevent exactly that. The likelihood is low, because it needs both a failed session reset and a failed kill.

Not a goal

  • Changing the cancel swallow in ApprovalCoordinator.request (except (asyncio.TimeoutError, asyncio.CancelledError): return False), or its question twin. That behaviour is documented as intended ("Request interactive approval and deny on timeout or cancellation", DashboardState.request_approval). Re-raising there would change that documented contract for every caller of DashboardState.request_approval, not only sub-agent runs; this fix closes the hole at the one place that approves tools for a sub-agent run.
  • Making the session reset or the kill fallback more reliable. They are what failed, and they keep their own records and audits.
  • The session-sharing stop path (the shared provider's shutdown()). _force_reap sets _reap_started before either branch, so the guard applies there too, but that path was not driven separately.
  • Tools a backend runs without asking for permission. The host cannot gate those, and the teardown is what ends them.

What changed (motivation → approach → change)

  • Symptom: a tool request read after a Stop was settled by the ordinary ladder, so a grant could approve it.
  • Root cause: the permission branch in subagent_manager/run.py never checked whether a stop was in progress. The stop's own ordering (teardown before cancel) was the only thing that kept the request from being read, and that ordering does not hold when the teardown fails. A check made once, at the top of the branch, is not enough either: the branch awaits the diagnostics write and the subagent_tool event, and the ladder awaits the spec hooks, the gate and a person, so a stop can land after the check and before the approval is sent.
  • Change: tool_permission.Policy gains stopping, a live predicate. settle reads it before its first stage (tool_permission.py:410) and before it asks a person (tool_permission.py:437), and _allow reads it at the commit point of every approval (tool_permission.py:521), with no await between that read and wire.allow. A grant, the gate's hit and a person's yes all reach the wire only through _allow, so once the predicate holds the request is answered by tool_permission.bail(..., "stopped"): the SEL row is written with error: "stopped" and the request is rejected bare on the wire. The run passes its predicate (_reap_started, user_stopped or reaped; subagent_manager/run.py:280, wired at subagent_manager/run.py:2087) and also reads it when it reads a request (subagent_manager/run.py:3266), before any floor, grant or person is consulted. "stopped" joins BailReason and the sub-agent refusal rows, so a Stop is recorded as a stop, not as a turn limit or a person's no.
  • The transport's own awaits come after _allow's read: approve_tool still awaits the security floor's thread hop and the stdin write lock before it writes the allow. _allow hands the predicate to the wire (tool_permission.py:524), and AcpWire passes it as withdraw_if to a provider type that declares approval_withdrawable (tool_permission.py:553): AcpProvider and AcpSessionProvider, while any other provider keeps the base approval_withdrawable of False (providers/base.py:119). Once the floor's thread hop returns, both transports read withdraw_if again (acp/session_handle.py:2556, acp/client_permissions.py:282), and once more under the write lock right before the frame is written (acp/session_handle.py:2583, acp/client_permissions.py:303). The shared runtime reads it as withdrawal_check, ahead of its own liveness check (acp/runtime.py:5453), and keeps a caller's before_write, where a timed grant's deadline goes, after that check (acp/runtime.py:5450): a runtime that died while the answer waited for the lock raises AcpRuntimeDead, so the chat path takes the session-reset recovery instead of asking a person about an ended grant. AcpClient has no liveness check under its lock and reads the withdrawal in its before_write, ahead of the deadline. Once it holds, no byte of the allow is written, the request's records are put back, and permission_floor.ApprovalWithdrawn makes _allow bail the request as stopped (tool_permission.py:525), answered once with the agent's own reject option.
  • The stop bail ends the run, as the two limit bails do: the loop breaks after the bail (subagent_manager/run.py:3275) and after a settle the ladder bailed as stopped (subagent_manager/run.py:3364), and the stream's own ending arms record the stop (with _reap_started set, the reap's ending: subagent_manager/run.py:3629). A person's no that a stop's cancel caused reads on, so a stream the stop tore down still ends at its next read, as before.
  • docs/system-specs/modules/subagent.md and docs/system-specs/common/injected-messages.md list the new bail beside the two limit bails, and the first says where the stop is read and what ends the run; docs/system-specs/modules/acp-client.md documents withdraw_if.
  • Port note: since fix(subagent): refuse tool requests once a stop is in progress #18955 was written, main split AcpClient's methods into acp/client_* owner modules. AcpClient.approve_tool's change (the withdraw_if reads and the put-back of the request's records) now lives in acp/client_permissions.py; the put-back is the module-level helper _restore_withdrawn(client, ...), not a new bound member, so the frozen member inventory in test/test_client_bindings.py changes only in approve_tool's signature digest (the new optional withdraw_if keyword).

Backwards compatibility

Compatible: a run with no stop in progress takes exactly the path it takes today; the new branch runs only for a run that is already being stopped, and it answers each request through the existing bail. An approval without withdraw_if reaches the transport exactly as before: each layer passes the keyword on only when it is given.
Removes nothing: the change adds one refusal rung, one optional Policy field (stopping, default None, so the task runner's ladder takes its path unchanged) and the reads of it, the optional keywords withdraw_if (approve_tool on both providers and both transports) and withdrawal_check (AcpRuntime.send_response and its protocol), the class attribute approval_withdrawable (default False) and permission_floor.ApprovalWithdrawn; no key, row, rung, path or public function is removed or renamed.

Tests

Tests are @javenciu's from #18955, unchanged except the one digest above. #18955's body lists what each one locks in and its red/green runs against main.

On this branch (origin/main 213339f + 2 commits), pytest -n 8:

  • test/test_subagent_stop_refuses_permission.py, test/test_tool_permission.py, test/test_transport_permission_floor.py, test/test_eval_subagent_deny_notice.py, test/test_client_bindings.py: 633 passed. This includes test_a_stop_landing_in_the_transport_awaits_writes_no_approval[dedicated-floor|write_lock], which drives AcpProvider over the real AcpClient, so the ported client_permissions.approve_tool is covered.
  • 35 more test/test_acp*, test/test_session*, test/test_subagent* and test/test_chat_runner* files that name approve_tool, client_permissions, send_response or withdraw (-n 16): 3,209 passed, 1 skipped.

black, isort, flake8 on the 15 changed Python files, mypy on the 10 changed source files, ./scripts/docs-lint.sh and COMMENT_HISTORY_BASE_REF=origin/main scripts/check_comment_history.py: all exit 0.

Manual verification

N/A: the trigger needs a session reset and a kill that both fail, which the unit tests drive with fakes; no real process is signalled.

Related Issues

Fixes #20734
Replaces #18955

All credit to @javenciu, who found the bug, wrote the fix and its tests in #18955. This same-repo PR carries their two commits (authorship kept) onto current main, which had split acp/client.py and so conflicted with the fork.

Pattern harvest

Rule candidate: review-prompt
Pattern: a stop that relies on its own ordering (tear down, then cancel) to keep a loop from acting, with no check of the stop flag at the point where the loop grants or executes work.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

javenciu and others added 2 commits October 15, 2026 08:07
A Stop tears the sub-agent's session down first and cancels the run
task after that. The dashboard approval wait turns that cancel into a
denial, so the run loop resumes and reads its next event. When the
session reset hangs or raises and the kill fallback also fails, the
stream is still live, and the next permission request went through the
normal ladder: a grant such as slot trust or --approval yolo approved
a tool after the user pressed Stop.

The permission branch now bails every request as "stopped" once
_reap_started, user_stopped or reaped is set, before any grant or
person is consulted. The bail is the ladder's own: the SEL row is
written with error "stopped" and the request is rejected bare on the
wire. "stopped" joins BailReason and the sub-agent refusal rows, and
the run's ladder-entry ratchet counts the new bail.

The cancel swallow in ApprovalCoordinator.request is unchanged; it is
documented as intended (deny on timeout or cancellation).
The stop check at the top of the permission branch ran once, before the
branch's own awaits (the diagnostics write and the subagent_tool event)
and before the ladder's (the spec hooks, the gate, a person's wait). A
Stop landing in any of them, while its session reset was still hanging,
let the request reach the wire as an approval: parent_policy=auto, the
gate's auto-approve or a person's yes sent approve_tool after the Stop.

Policy gains a live stopping predicate. settle reads it before its first
stage and before it asks a person, and _allow reads it at the commit
point of every approval. Once it holds, the request goes through the
same audited stopped bail. The run passes its predicate (_reap_started,
user_stopped or reaped).

_allow also hands the predicate to the wire, because approve_tool still
awaits the security floor's thread hop and the stdin write lock before
it writes the allow. AcpWire passes it as withdraw_if to a provider type
that declares approval_withdrawable (AcpProvider, AcpSessionProvider),
and both transports read it after the floor and under the write lock,
right before the frame is written: AcpClient through its before_write
check, the shared runtime through a withdrawal_check it runs ahead of
its own liveness check. Once it holds, no byte is written, the request's
records are put back, and ApprovalWithdrawn makes _allow bail the
request as stopped: audited, and answered once with the agent's reject.
A timed grant's deadline stays in the runtime's before_write, which runs
after the liveness check, so a runtime that died during the lock wait
still raises AcpRuntimeDead rather than GrantEnded.

The stop bail now ends the run, as the limit bails do: the loop breaks
instead of continuing, after the bail at the top of the branch and after
a settle the ladder bailed as stopped, and the stream's own ending arms
record the stop. A person's no that a stop's cancel caused still reads
on, so a stream the stop tore down ends at its next read, as before.

Ported onto main after acp/client.py was split: the AcpClient.approve_tool
change now lives in acp/client_permissions.py.

Co-authored-by: cixuuz <26782336+cixuuz@users.noreply.github.com>
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision a3a2e3f3111a83d0129956cc1230068088b66b3b touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of a3a2e3f3111a83d0129956cc1230068088b66b3b — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify that _restore_withdrawn puts back exactly the records approve_tool took, so the stopped bail rejects the withdrawn request once and never leaves it unanswered.

[DESIGN-REVIEWED] a3a2e3f

Description read

[DESCRIPTION-READ] b5bfce88c8a4aee7839c0857515d1b470e43312ffb939e65d3f8b262e454c34b

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of a3a2e3f3111a83d0129956cc1230068088b66b3b — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The run-loop and ladder stop checks already close the reported hole. The transport-level withdraw_if layer adds new surface in six places to shorten a race that lasts for one await.

Not justified as shipped

  • Item 3 — oversized: the description shows the defect as a next request that the ladder approved after the Stop, and items 1–2 stop that at run.py:3266 and _allow. The extra layer only covers a Stop that lands during the floor's thread hop or the write-lock wait, which is after _allow has already committed. Covering that one await adds withdraw_if on 2 providers and 2 transports, withdrawal_check on AcpRuntime.send_response, the class attribute approval_withdrawable (1 reader: AcpWire.allow), ApprovalWithdrawn, raise_if_withdrawn, and two _restore_withdrawn helpers.
    Subtraction: delete withdraw_if/withdrawal_check/approval_withdrawable/ApprovalWithdrawn/_restore_withdrawn, and keep _allow's synchronous read as the commit point.
    Clears when: the layer is removed, or a test shows a Stop landing inside the floor hop or the lock wait that items 1–2 do not refuse, with a cost a user would feel.

What this change ships

Inventory (5 items) — 4 justified

Intent: a sub-agent the user stopped never gets another tool approved, even when its teardown fails. This is a FIX.

  1. A stopped run refuses each new tool request as stopped and ends — justified
  2. The approval ladder checks for a stop before its first step, before asking a person, and at the approval commit point — justified
  3. The ACP transports re-check for a stop after the floor hop and under the write lock, and put the request back if it is withdrawn — oversized
  4. The audit trail and refusal rows record stopped instead of a turn limit or a person's no — justified
  5. The subagent, injected-messages and acp-client specs now describe the stop bail — justified

[FIRST-PRINCIPLES-REVIEWED] a3a2e3f

Description read

[DESCRIPTION-READ] 8dde8cf83aaa94dbbe6f8547870b12c345b5834b92c6705cf6709b9ae6f226df

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed a3a2e3f3111a83d0129956cc1230068088b66b3b — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] a3a2e3f

Verdict parsed from the review's SHA-scoped output markers for commit a3a2e3f3111a83d0129956cc1230068088b66b3b.

False positive or not applicable? A repository writer can comment:
/ai-review override fable a3a2e3f3111a83d0129956cc1230068088b66b3b: <one-sentence reason>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of a3a2e3f3111a83d0129956cc1230068088b66b3b and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a3a2e3f

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a3a2e3f3111a83d0129956cc1230068088b66b3b: <one-sentence reason>

@iamwhatever
iamwhatever marked this pull request as ready for review October 15, 2026 11:32
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 15, 2026 11:32
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 15, 2026

@chenmingwei23 chenmingwei23 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Batch approval: readiness: passed, no merge conflict, checks green.

@chenmingwei23
chenmingwei23 merged commit dfaebe4 into main Oct 15, 2026
128 of 151 checks passed
@chenmingwei23
chenmingwei23 deleted the replace/18955 branch October 15, 2026 15:42
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 15, 2026
jeeshofone added a commit to jeeshofone/KiroCrew that referenced this pull request Oct 15, 2026
…ng census

kirodotdev#20743 gave AcpProvider an `approval_withdrawable` class flag and a
`withdraw_if` keyword on `approve_tool`. The frozen census added with
kirodotdev#20838 listed neither, so test_acp_bindings failed on main. Add the flag
and update the `approve_tool` signature digest.

Fixes kirodotdev#20893
buluoray pushed a commit that referenced this pull request Oct 15, 2026
…gnature (#20902)

#20743 added AcpProvider.approval_withdrawable and the withdraw_if parameter on
approve_tool while #20838 froze the provider inventory, so test_acp_bindings
fails on main. Record both.

Closes #20901

Co-authored-by: Joe Guo <zejiangg@amazon.com>
@iamwhatever iamwhatever mentioned this pull request Oct 15, 2026
5 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Sub-agent can still get a tool approved after the user pressed Stop

3 participants