Skip to content

feat(acp): ClaudeHarness, claude-agent-acp on the shared runtime with per-session setup (not routed) - #37521

Merged
chenmingwei23 merged 2 commits into
mainfrom
feat/claude-harness
Nov 15, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
feat/claude-harness

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

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), because harness_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: the settings.local.json seed 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

  • No routing: claude is not added to ACP_BACKENDS_ACP_RUNTIME, so every claude chat still runs on ClaudeAcpClient.
  • Each chat's own 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.
  • No change to kiro-cli, KAS or codex sessions.

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 _HARNESSES and not routed. Spawn: the adapter argv with no seed, measured adapter-only (CORE_RSS_DEPTH = 0 plus any resident sandbox launcher, ceiling 512 MB), because the per-session claude children grow with the number of chats and a whole-subtree ceiling would recycle every chat. Teardown: session/close as a request, which ends one session and keeps its record. Protocol version, client capabilities and the CLAUDE_CODE_EXECUTABLE lookup are the per-chat client's.
  • Per-session seams on HarnessAdapter, all inert by default: prepare_session, permission_surface_owned, session_meta, after_session_start, end_session, behind per_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): a ClaudeAcpClient that 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.claudeCode envelope, and runs the same starting-mode pin. Its two transport steps are its own: session/set_mode goes out for this session on the shared connection, and a refusal sends session/close for this session only. It never kills the process.
  • Runtime wiring. create_session and load_session prepare 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_session and evict_session end the state, which removes the seed. A start that fails at any step removes it too. A late session/new that 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 ClaudeHarness sets per_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/close teardown, adapter-only RSS, no seed at spawn); each of two sessions writes its own seed in its own folder; end_session removes it once; the envelope is the session's own and a zero-tool session that mounts a server is refused; the pin sends session/set_mode for this session, and a refused pin closes only this session; a real AcpRuntime start writes the seed, sends the envelope, and the teardown sends session/close and removes the seed; a refused session/new leaves 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.
  • Local: these files and the claude spawn tests, serially, plus isort, flake8, black (pinned) and mypy on the changed modules.

Other suggestions

The routing change that follows adds claude to ACP_BACKENDS_ACP_RUNTIME behind 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

  • 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

@chenmingwei23
chenmingwei23 requested review from CrysisDeu and removed request for a team November 15, 2026 05:27
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of eb28aa7f09503a3a8fc4ca8b3c71360e766c36c4 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the seams are off unless per_session_state is set, only the unrouted ClaudeHarness sets it, and the per-chat claude path is the same logic moved into shared helpers.

Notes

  • ClaudeHarness stores _work_dir on the harness itself during resolve_spawn, so the thinking-display default follows the folder the process started in, not each session's folder. The per-session seed exists precisely because of this one-process-many-folders problem. Before claude is routed, either move this decision into prepare_session or state that it is per-process.
  • The credential-mask contract tests now use acp_tool_gate.is_enforced instead of the AGENT_SPEC check. That matches the test docstring ("A host this core's tool gate ENFORCES must carry a credential mask"), and claude's per-chat launch has no mask today either. If claude later moves to VERIFIED_SEEDED_SETTINGS, the same test will start requiring a mask, so plan the mask with that change.

[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 .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

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of eb28aa7f09503a3a8fc4ca8b3c71360e766c36c4 — 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 does not.

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 _HARNESSES table's own comment records.

Notes

  • Item 2 — one consumer, generalized: five seams plus per_session_state were added to HarnessAdapter. A grep for per_session_state = True finds one harness: ClaudeHarness. The kiro, KAS and codex harnesses only read the default. Subtraction: when routing lands, keep only the seams claude actually exercises (for example, fold permission_surface_owned into the state that prepare_session returns), not a general per-host contract.

What this change ships

Inventory (7 items) — 6 justified

Intent: let one shared claude-agent-acp process serve several chats safely, as the first step before routing (#5033). This is an ADDITION.

  1. A claude harness is registered for the shared runtime, with no session routed to it — justified
  2. The harness base gains per-session prepare/meta/pin/end hooks, inert unless the flag is set — one consumer, generalized
  3. A per-session claude state reuses the per-chat client's seed, envelope and pin, but closes only its own session — justified
  4. The per-chat claude launch's argv resolution and env defaults move into shared helpers both drivers call — justified
  5. A late session/new on a host with per-session state is torn down, not adopted — justified
  6. The mirror is now told, per session, whether Crew's seed governs the permission surface — justified
  7. Contract tests key the credential-mask checks on is_enforced and exempt claude from "no runtime harness" — justified

[FIRST-PRINCIPLES-REVIEWED] eb28aa7

Description read

[DESCRIPTION-READ] 1adf57c950e89d02bd429f81e97e0ae1255b470436deb8e020d51baaf84cb7c1

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

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] eb28aa7

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable eb28aa7f09503a3a8fc4ca8b3c71360e766c36c4 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] eb28aa7

False positive or not applicable? A repository writer can comment:
/ai-review override gpt eb28aa7f09503a3a8fc4ca8b3c71360e766c36c4 false-positive: <reason, 20 to 500 characters>

@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 Nov 15, 2026
Base automatically changed from refactor/claude-out-of-acpclient to main November 15, 2026 06:11
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

  • No sensitive path changed; nothing to check.

@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 15, 2026
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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 eb28aa7f09 · 1376 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 15, 2026
@chenmingwei23
chenmingwei23 enabled auto-merge (squash) November 15, 2026 09:06
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@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 Nov 15, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thanks for this. The seam design is careful, but one defect in the new teardown path needs a fix before merge.

  1. acp/claude_shared_session.py:101-105 and acp/runtime_session_create.py:583-631: a failed pin leaves the session open on the shared runtime.

    • Trigger: a claude session starts on AcpRuntime in a mode that skips the gate (bypassPermissions, auto, or no mode reported), and the pinning session/set_mode gets an error answer or times out.
    • What happens: _claude_set_mode passes up what _send_and_await raises, which is AcpRuntimeError or AcpRequestTimeout. Neither one is an AcpError. _pin_claude_starting_mode catches only (AcpError, AcpTimeoutError) (client_claude_session.py:912), so _claude_stop_session never runs. after_session_start also runs before _finish_create_session adds 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. No session/close is 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 raw AcpRuntimeError instead of the worded "could not pin" refusal. load_session does 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, turn AcpRequestTimeout into AcpTimeoutError and any other AcpRuntimeError into AcpError. Or have create's except arm call asyncio.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.
  2. test/test_claude_shared_runtime.py:180 and :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 with AcpRuntimeError or AcpRequestTimeout, it fails: the wire shows session/new and session/set_mode with no session/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 AcpRuntimeError and AcpRequestTimeout, and assert session/close and the worded refusal.

Optional:

  • The owning specs were not updated, although the body ticks "Documentation updated". providers.md:1640 still says permission_surface_owned is always False. claude-code-provider.md:953 and :981 still name the removed ClaudeLaunch._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 --version probe. The sibling claude seed helpers pin installed_kiro_cli_version to SPEC_PERMISSIONS_MIN_VERSION for this reason.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 15, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Addressed on c7cf2fc (rebased onto main 197c3c2, after #37466 and #37579):

  1. Failed pin left the session open. Fixed both ways the review named:
    • ClaudeSharedSession._claude_set_mode raises AcpRequestTimeout as AcpTimeoutError and any other AcpRuntimeError as AcpError, so _pin_claude_starting_mode closes the session (session/close) and raises the worded "could not pin" refusal.
    • create_session adds the id to _unclaimed_new_sessions before after_session_start, so an exit the pin does not catch (a cancel) still reaches the shielded terminate_session.
  2. The failed-pin tests now raise what the transport raises: both are parametrized over AcpRuntimeError and AcpRequestTimeout, and the runtime-level one asserts session/close and the refusal. New test_a_start_cancelled_during_its_pin_closes_that_session covers the cancel. Reverting the mapping turns the four parametrized cases red; dropping the early _unclaimed_new_sessions.add turns the cancel test red.

Optional items: providers.md now says permission_surface_owned is the harness's per-session answer, and claude-code-provider.md names _apply_claude_env_defaults. The load-path test and the Kiro CLI version pin are not in this push.

Rebase conflicts: runtime_session_create.create_session keeps both member_context (main) and harness_state (this PR); its signature digest in test_runtime_bindings is updated.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 15, 2026
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@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 Nov 15, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approving on eb28aa7. Both required items from my earlier change request are fixed on this head:

  1. A failed pin left the session open: fixed. _claude_set_mode now maps AcpRequestTimeout to AcpTimeoutError and AcpRuntimeError to AcpError. create_session now adds the id to _unclaimed_new_sessions before after_session_start. A refused or cancelled pin therefore sends session/close for that session only.
  2. The failed-pin tests raised the wrong error type: fixed. Both are parametrized over AcpRuntimeError and AcpRequestTimeout, and they assert session/close and 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.py still run the host's real Kiro CLI --version and ssh -V probes, and the child leaves a log file in TMPDIR. An autouse fixture that pins kiro_crew.kiro_cli.installed_kiro_cli_version and sandbox._ssh_supports_accept_new would 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 of test_a_failed_pin_closes_that_session_and_keeps_the_process should land before #37540 routes claude.
  • ClaudeSharedSession.prepare never sets the side-session options, the spec allowlists, _session_mcp_cache or 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.

@chenmingwei23
chenmingwei23 merged commit 5f5d371 into main Nov 15, 2026
99 checks passed
@chenmingwei23
chenmingwei23 deleted the feat/claude-harness branch November 15, 2026 14:00
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 2026
@LuisBrel LuisBrel mentioned this pull request Nov 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.

3 participants