Repository navigation
feat(acp): ClaudeHarness, claude-agent-acp on the shared runtime with per-session setup (not routed) - #37521
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the seams are off unless Notes
[DESIGN-REVIEWED] eb28aa7 Description read[DESCRIPTION-READ] 53eedec9b89ccc4c6b10cc968de0334eda1b075a5ba5770cd6e011ec4d047878 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing here blocks. The new code has no runtime caller yet, which the Goal says on purpose, and registering a harness before it is routed is the convention the Notes
What this change shipsInventory (7 items) — 6 justifiedIntent: let one shared claude-agent-acp process serve several chats safely, as the first step before routing (#5033). This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] eb28aa7 Description read[DESCRIPTION-READ] 1adf57c950e89d02bd429f81e97e0ae1255b470436deb8e020d51baaf84cb7c1 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
af6235c to
80112eb
Compare
Sensitive Change Review
|
80112eb to
1043f30
Compare
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates an 18% chance that this change introduces a defect, above the 12% limit for approving on its own. This adds an unrouted ClaudeHarness, per-session hooks on HarnessAdapter that do nothing unless per_session_state is set, and a ClaudeSharedSession state object, with runtime wiring in create, load, terminate and evict. Claude stays out of ACP_BACKENDS_ACP_RUNTIME, so no chat reaches the new path. The per-chat ClaudeLaunch refactor is the same logic moved into shared helpers. The kiro-cli, KAS and codex paths are unchanged: every new branch requires per_session_state or a prepared state, and the new permission_surface_owned argument defaults to False. Test doubles that replace _mirrored_session_mcp or build a bare runtime were updated. Seed teardown is idempotent and covers a failed start, a cancelled start, a failed pin and a late session/new. A refused pin closes only that session. The contract-test switch to is_enforced keeps the same coverage for the existing harnesses (codex's SESSION_CONFIG is enforced). Tests cover the new behaviour well. The issues I found affect only the unrouted path and change nothing today. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
0647e37 to
2cec543
Compare
2cec543 to
9be28f5
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Thanks for this. The seam design is careful, but one defect in the new teardown path needs a fix before merge.
-
acp/claude_shared_session.py:101-105andacp/runtime_session_create.py:583-631: a failed pin leaves the session open on the shared runtime.- Trigger: a claude session starts on
AcpRuntimein a mode that skips the gate (bypassPermissions,auto, or no mode reported), and the pinningsession/set_modegets an error answer or times out. - What happens:
_claude_set_modepasses up what_send_and_awaitraises, which isAcpRuntimeErrororAcpRequestTimeout. Neither one is anAcpError._pin_claude_starting_modecatches only(AcpError, AcpTimeoutError)(client_claude_session.py:912), so_claude_stop_sessionnever runs.after_session_startalso runs before_finish_create_sessionadds the id to_unclaimed_new_sessions, so create's except arm at :625 does not terminate the session either. It only drops the state and removes the seed. Nosession/closeis sent. The session stays on the adapter in the permissive mode, with no handle and with its own child and MCP servers. The caller gets a rawAcpRuntimeErrorinstead of the worded "could not pin" refusal.load_sessiondoes not have this problem, because its except arm shield-terminates (runtime_session_load.py:501-511). Nothing routes to this code yet, but #37540 and #37563 build on it, and none of the stacked PRs changes this path. - Smallest fix: in
_claude_set_mode, turnAcpRequestTimeoutintoAcpTimeoutErrorand any otherAcpRuntimeErrorintoAcpError. Or have create's except arm callasyncio.shield(self.terminate_session(session_id))whenever a harness state was recorded, as load already does. Either change also answers the approver's open comment on this point.
- Trigger: a claude session starts on
-
test/test_claude_shared_runtime.py:180and:269: the failed-pin tests raise the wrong error type.- What happens: both fakes raise
AcpError, which the real transport never raises here. When the runtime-level test is run withAcpRuntimeErrororAcpRequestTimeout, it fails: the wire showssession/newandsession/set_modewith nosession/close. So the body's claim that "a refused pin closes only this session" holds only for the fakes. - Smallest fix: parametrize both fakes over
AcpRuntimeErrorandAcpRequestTimeout, and assertsession/closeand the worded refusal.
- What happens: both fakes raise
Optional:
- The owning specs were not updated, although the body ticks "Documentation updated".
providers.md:1640still sayspermission_surface_ownedis always False.claude-code-provider.md:953and:981still name the removedClaudeLaunch._apply_env_defaults. Seam 3b is not described anywhere. - No test covers the load path's seed, envelope or pin on a resumed transcript. A load-path version of the create test, with a refusal variant, would pin it.
- The seed-writing tests start the host's real Kiro CLI
--versionprobe. The sibling claude seed helpers pininstalled_kiro_cli_versiontoSPEC_PERMISSIONS_MIN_VERSIONfor this reason.
7a21d8b to
c7cf2fc
Compare
|
Addressed on c7cf2fc (rebased onto main 197c3c2, after #37466 and #37579):
Optional items: Rebase conflicts: |
… per-session setup (not routed)
c7cf2fc to
eb28aa7
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approving on eb28aa7. Both required items from my earlier change request are fixed on this head:
- A failed pin left the session open: fixed.
_claude_set_modenow mapsAcpRequestTimeouttoAcpTimeoutErrorandAcpRuntimeErrortoAcpError.create_sessionnow adds the id to_unclaimed_new_sessionsbeforeafter_session_start. A refused or cancelled pin therefore sendssession/closefor that session only. - The failed-pin tests raised the wrong error type: fixed. Both are parametrized over
AcpRuntimeErrorandAcpRequestTimeout, and they assertsession/closeand the worded refusal.
The optional items are partly done. The spec wording for permission_surface_owned and _apply_claude_env_defaults is fixed. The load-path test, the Kiro CLI probe pin and a description of the new seams are still open (see below).
This review verified the following on this head. Claude is still outside ACP_BACKENDS_ACP_RUNTIME, so no chat reaches the new path. The ClaudeLaunch refactor moves code without changing the per-chat behaviour. The kiro, KAS and codex paths only read per_session_state=False. The three touched test files pass (579 tests). Removing the early _unclaimed_new_sessions.add turns the cancel test red, and removing the create-path pin turns 3 tests red. One thing done well: ClaudeSharedSession reuses the per-chat seed, envelope and pin code and overrides only the transport steps, so a refused pin closes one session and never kills the shared process.
Security: the diff touches a trust boundary (permission_surface_owned), a new spawn path and the permission-mode pin. None of them is live. The only harness with per_session_state=True is the unrouted ClaudeHarness. permission_surface_owned defaults to False, so the MCP mirror withholds the array unless the session's own seed governs it. The credential-mask contract tests now key on is_enforced. That gives the same answer for kiro, KAS and codex, and claude's per-chat launch carries no mask on main either.
Optional:
- The seed tests in
test/test_claude_shared_runtime.pystill run the host's real Kiro CLI--versionandssh -Vprobes, and the child leaves a log file in TMPDIR. An autouse fixture that pinskiro_crew.kiro_cli.installed_kiro_cli_versionandsandbox._ssh_supports_accept_newwould stop that, as the sibling claude seed helpers do. - The load-path mode pin (
runtime_session_load.py:503) has no test, so skipping it turns nothing red. A load-path version oftest_a_failed_pin_closes_that_session_and_keeps_the_processshould land before #37540 routes claude. ClaudeSharedSession.preparenever sets the side-session options, the spec allowlists,_session_mcp_cacheor the worker built-in narrowing. So the envelope it builds will differ from the per-chat one once claude is routed. #37540 restores most of these, but none of the stacked PRs I checked carries the worker built-in narrowing onto the shared state. A spec paragraph for the new seams (per_session_state,prepare_session,session_meta,after_session_start,end_session) would also help the next harness.
Problem / Motivation
Goal: the shared ACP runtime can drive claude-agent-acp with each session's own settings seed, mode pin and teardown, while no session is routed to it yet.
The shared runtime (
AcpRuntime) serves kiro-cli, KAS and codex from one process per runtime. claude-agent-acp still runs one process per chat (ClaudeAcpClient), becauseharness_for("claude")has no harness and the runtime has nowhere to do the per-session work claude needs. On a per-chat process that work rides the process: thesettings.local.jsonseed is written at spawn, the starting-mode pin talks on the process's own pipe, and a failed pin ends the process. On a shared process each of those must belong to one session.Why it matters
Each claude chat today costs its own adapter process. Sharing one adapter across chats needs a harness first, and it has to be safe before any chat is routed to it: a seed written once per process would leave a second chat (in another folder especially) starting in whatever permission mode the user's own settings name, and a failed pin that ended the process would end every other chat on it. Users see no change from this PR.
Not a goal
ACP_BACKENDS_ACP_RUNTIME, so every claude chat still runs onClaudeAcpClient.KIROCREW_SESSION_KEY, permission mode and Side Chat flag reaching the shared session, the re-seed after a mid-session model change, and agent-started turns on the shared runtime: those land with the routing change.What changed (motivation -> approach -> change)
Claude's per-session work had no home on the shared runtime -> each session gets a state object that reuses the per-chat client's own methods -> the runtime asks the harness for that state per session, behind one flag.
ClaudeHarness(acp/harness/claude.py), registered in_HARNESSESand not routed. Spawn: the adapter argv with no seed, measured adapter-only (CORE_RSS_DEPTH = 0plus any resident sandbox launcher, ceiling 512 MB), because the per-sessionclaudechildren grow with the number of chats and a whole-subtree ceiling would recycle every chat. Teardown:session/closeas a request, which ends one session and keeps its record. Protocol version, client capabilities and theCLAUDE_CODE_EXECUTABLElookup are the per-chat client's.HarnessAdapter, all inert by default:prepare_session,permission_surface_owned,session_meta,after_session_start,end_session, behindper_session_state(False everywhere but claude). The runtime reads that flag before any of them, so kiro-cli, KAS and codex make no extra call (harness-parity H13).ClaudeSharedSession(acp/claude_shared_session.py): aClaudeAcpClientthat never starts a process. It writes the seed and side-session deny rules in the session's own folder before its request, builds its_meta.claudeCodeenvelope, and runs the same starting-mode pin. Its two transport steps are its own:session/set_modegoes out for this session on the shared connection, and a refusal sendssession/closefor this session only. It never kills the process.create_sessionandload_sessionprepare the state first (_create_session_with_harness_state,_load_session_with_harness_state), hand the mirror whether the seed governs the permission surface (the mirror withholds the whole array otherwise, as on the per-chat client), merge the envelope into the request, and run the pin before the handle exists.terminate_sessionandevict_sessionend the state, which removes the seed. A start that fails at any step removes it too. A latesession/newthat outlived its budget is torn down, not adopted, because it would have no pin or seed.Backwards compatibility
Compatible: every new seam defaults to doing nothing, only
ClaudeHarnesssetsper_session_state, and no backend set routes claude to the runtime.Removes nothing: no session is routed to the new harness, and the per-chat claude path is unchanged.
Tests
test/test_claude_shared_runtime.py(new): the harness answers (registered, not routed,session/closeteardown, adapter-only RSS, no seed at spawn); each of two sessions writes its own seed in its own folder;end_sessionremoves it once; the envelope is the session's own and a zero-tool session that mounts a server is refused; the pin sendssession/set_modefor this session, and a refused pin closes only this session; a realAcpRuntimestart writes the seed, sends the envelope, and the teardown sendssession/closeand removes the seed; a refusedsession/newleaves no seed; a failed pin closes that session and leaves the process running; kiro reaches none of the seams.test/test_acp_harness_contract.py: claude joins the harness checks. The credential-mask checks now select hosts the tool gate enforces (acp_tool_gate.is_enforced), which is what their docstrings say. claude (SEEDED_SETTINGS) is not enforced, and its per-chat launch carries no mask either, so the harness claims none. A bounded RSS scope may be depth 0.test/test_runtime_bindings.py: the inventory names the two new members and the changed signatures.Other suggestions
The routing change that follows adds claude to
ACP_BACKENDS_ACP_RUNTIMEbehind a switch that is off by default, threads each chat's permission mode, Side Chat flag and session key into the shared session, and runs the shared-runtime claude lane tests against a real adapter.Related Issues
Part of #5033
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)