Skip to content

feat(acp): OpencodeHarness, opencode on the shared runtime with per-session checks (not routed) - #37620

Closed
chenmingwei23 wants to merge 1 commit into
feat/goose-harnessfrom
feat/opencode-harness
Closed

chenmingwei23 wants to merge 1 commit into
feat/goose-harnessfrom
feat/opencode-harness

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: an opencode session can run on the shared ACP process (AcpRuntime) with every check Crew runs for it on AcpClient, each check scoped to the right thing: the process or the one session.

opencode 1.19.1 serves several sessions from one opencode acp process and runs their turns in parallel (measured: one session running a 60 s shell command, the other answering in 0.13 s; session/close drops one session and session/load restores it on the same process). But every check Crew runs for opencode lives on the one-process-per-session path:

  • at spawn: the version gate, the read-back of opencode's own resolved permission config (opencode debug config), the per-tool deny rules seeded on OPENCODE_CONFIG_CONTENT, and the refusal of a switched-off tool on a server opencode mounts from its own config;
  • per session: the refusal of a session that inherited opencode's hosted fall-back model, and holding a shell permission back until the tool_call_update carrying its command has filled the trusted cache.

Why it matters

This is the second of three PRs that let opencode dashboard chats share one process under the ACP runtime sharing preview, split like goose (#37535, #37562, #37567). The first, #37602, moves opencode's session code off AcpClient. Users see no change from this PR: no session is routed to the shared runtime for opencode yet.

Not a goal

  • No routing: opencode is not added to ACP_BACKENDS_ACP_RUNTIME or to the chat-sharing set. The third PR adds the switch, the placement rules and the real-opencode lane test.
  • Which sessions may share one process. opencode registers a session's MCP servers on its folder, not on the session, and never removes them on session/close; two sessions in one folder see each other's tools, and a same-named server is replaced. Keeping same-folder chats apart is the placement's job and lands in the third PR.

What changed (motivation -> approach -> change)

The checks run per process on a path with no session -> the measured gate functions get the session facts they read from a probe object, and what the spawn found travels on the plan -> a stateless OpencodeHarness and four small seams.

  • OpencodeHarness (acp/harness/opencode.py), registered in _HARNESSES ahead of routing like claude and goose.
    • resolve_spawn: the same gates as OpencodeLaunch, same order (mask preflight, version gate, seed, sandboxed read-back, deny settlement), under the child's own environment and folder. The seed carries the spawning agent's deny rules.
    • The harness holds no state (test_no_harness_holds_state_beyond_its_backend_id): the seed rides the new SpawnPlan.spawn_env, applied after apply_spawn_env; the read-back rides the new SpawnPlan.host_state, which the runtime hands to each prepare_session as host_state. A process with no read-back serves no session.
    • prepare_session: refuses a session whose withheld server opencode mounts natively.
    • after_session_start: refuses an inheriting session on the hosted fall-back model, closing that session alone.
    • Teardown is session/close, awaited.
  • Seams on HarnessAdapter, each a no-op default so every other host is asked exactly as before:
    • projection_extras(state): keyword arguments for the mirror's session_projection; opencode passes harness_denies_in_force, so a server whose rule is not in force is withheld whole, as on AcpClient. Passed only when the session has host state.
    • harness_mcp_server_names(state): the session's placed servers plus those opencode's config mounts, handed to the permission parser so a fused <server>_<tool> title splits back exactly.
    • defers_shell_permission: the turn loop reads the session's next frame before judging a shell permission whose command is not cached yet (defer_shell_permission, the twin of OpencodeAcpClient._defer_shell_permission). Frames read ahead go on a local front queue the loop drains first.
  • Spawn context: SpawnContext.agent_env and extra_env, so a pre-spawn read-back resolves the same config files the child will.

Backwards compatibility

Compatible: no session is routed to OpencodeHarness; every other host's plan carries no spawn_env or host_state, its _mirrored_session_mcp call gets no new keyword, and host_defers_shell_permission is False for it.

Reader: src/kiro_crew/acp/runtime_session_setup.py:_mirrored_session_mcp -- gains an optional projection_extras, passed only for a session with host state -- test_the_runtime_hands_the_projection_the_rules_in_force
Reader: src/kiro_crew/acp/harness/base.py:SpawnPlan -- gains spawn_env and host_state, both empty by default -- test_the_spawn_hands_its_plan_to_the_child_and_to_every_session

Tests

  • New test/test_opencode_shared_runtime.py (25): the gates run under the child's environment and folder; the seed carries the spawning agent's deny rules and reaches the child through the plan; a failed read-back or an untested major refuses the spawn; a process with no read-back serves no session; each projection is held to the rules in force; a withheld server mounted natively refuses that session; the parser gets placed plus configured server names; an inherited hosted model closes only that session, a pinned or configured model never does; the shell-permission deferral reorders only a same-session, same-call, in-progress command update and returns every other frame; only a deferring host waits; the turn defers before building the permission event; through a real AcpRuntime.create_session, the projection receives the rules in force and a hosted fall-back closes the session and keeps the process. Each fails if its rule is removed.
  • test_acp_harness_contract.py: opencode joins ALL_BACKENDS and REGISTERED_AHEAD_OF_ROUTING, so every per-harness contract test runs on it.
  • test_runtime_bindings.py: the _mirrored_session_mcp signature digest and the spawn owner's written fields follow the change.
  • Run locally, one file at a time: the files above plus test_goose_shared_runtime.py, test_claude_shared_runtime.py, test_session_handle_bindings.py, test_harness_parity.py, test_acp_opencode_backend.py, test_client_bindings.py, and every test file that names _mirrored_session_mcp, SpawnContext(, SpawnPlan( or prepare_session(. mypy over src/kiro_crew/ is clean.
  • Inherited from the base branch, unchanged here: test_security_posture.py flags acp/harness/goose.py, and seven dispatch test files (test_transport_permission_floor.py, test_stuck_turn_watchdog.py, test_engine_fallback.py, test_acp_runtime_native_children.py, test_codex_native_subagent_cards.py, test_stale_watchdog_rearm.py, test_tool_call_classification_provenance_bound.py) fail the same way on feat(acp): GooseHarness, goose on the shared runtime with per-session checks (not routed) #37562's head a755c6817d without this PR and pass on main faac7eaa17: they come from the goose PR's per-session refusal in the turn loop meeting MagicMock runtimes.

Proof: not provable -- other: not routed; unit and runtime-level coverage here, a real opencode run in the PR that routes it

Manual verification

N/A -- nothing reaches this path yet. The routing PR runs real opencode on the shared runtime, in a pod, with the switch on and off.

Screenshots / video

N/A -- no UI change.

Related Issues

Part of #5033. Stacked on #37562; moves to main once the goose stack merges.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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 mbriones98 and removed request for a team November 15, 2026 14:04
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
…ession checks (not routed)

opencode 1.19.1 serves several sessions from one `opencode acp` process
and runs their turns in parallel, but everything Crew checks for it ran on
AcpClient, one process per session: the version gate and the read-back of
its resolved permission config at spawn, the per-tool deny rules seeded on
OPENCODE_CONFIG_CONTENT, the refusal of a withheld server opencode mounts
from its own config, the hosted fall-back refusal, and holding a shell
permission back until its command update reaches the trusted cache.

OpencodeHarness serves opencode on AcpRuntime. The spawn gates run once per
process, under the child's own environment (agent.env and the chat's
overlay, now on SpawnContext) and in its folder, through a probe object so
the measured functions run unchanged. The harness holds no state: the seed
rides SpawnPlan.spawn_env and the read-back rides SpawnPlan.host_state,
which the runtime hands to each prepare_session. Per session: the mirror's
projection is held to the deny rules in force (new projection_extras
seam), a withheld server mounted natively refuses that session, the hosted
fall-back closes that session alone, the permission parser gets the
session's server names (new harness_mcp_server_names seam), and the turn
loop reads a deferred shell permission's command update first (new
defers_shell_permission seam). Teardown is session/close.

Registered ahead of routing, like claude and goose: no session reaches it
until the chat-sharing change names opencode.
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: nothing is routed to this harness yet, every new seam defaults to a no-op, and the plan carries the spawn's state, so the harness itself stays stateless.

Notes

  • defer_shell_permission copies the matcher in OpencodeAcpClient._defer_shell_permission to decide which frame may fill the trusted shell-command cache. If you change one copy and not the other, the two paths will judge permissions differently. Have both call one predicate, or delete the AcpClient copy when the routing PR lands.
  • env.update(plan.spawn_env) is applied after apply_spawn_env, so any variable it carries overrides the child's environment. Pin spawn_env to the routing-seed key so a future host can't use it to override the sandbox or auth variables.

[DESIGN-REVIEWED] 0a33494

Description read

[DESCRIPTION-READ] 2336484e435240e34cf6b3750f706b6a5f35066eedd616608f163ee81a2917c6

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) — ✅ PASS

Premise-level review of 0a334940df99185f4715cb23282032bcc7455226 — 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 blocks. One duplicated predicate: the new shell-permission deferral is the third inline copy of the same frame check.

Notes

  • Item 5 — duplicate of src/kiro_crew/acp/client_turn.py:_is_mimocode_running_input: defer_shell_permission inlines the check "same session, tool_call_update, in_progress, non-empty rawInput.command, no content/rawOutput". The repo now has 3 copies (searched for update.get("status") == "in_progress" next to the rawInput command test): _is_mimocode_running_input, the inline one in _defer_opencode_shell_permission, and this new one. Subtraction: delete the inline condition block in session_handle_permissions.defer_shell_permission and call _is_mimocode_running_input(following, session_id, tool_call_id) instead.

What this change ships

Inventory (10 items) — 9 justified

Intent: let an opencode session run on the shared ACP process with every existing opencode check, each scoped to the process or to the one session. ADDITION (staged, not routed).

  1. opencode registered as a shared-runtime harness, with no sessions routed to it yet — justified
  2. Version gate, deny-rule seed and sandboxed config read-back run once per shared process, under the child's own environment and folder — justified
  3. A session whose withheld server opencode mounts natively is refused before session/new — justified
  4. A session that inherited opencode's hosted fall-back model is closed on its own; the process keeps running — justified
  5. A shell permission waits for its command update on the shared runtime — duplicate of client_turn._is_mimocode_running_input
  6. Each session's MCP projection is held to the deny rules actually in force (projection_extras) — justified
  7. The permission parser gets the session's placed and configured server names — justified
  8. SpawnPlan.spawn_env / host_state carry the seed and the read-back to the child and to sessions — justified
  9. SpawnContext.agent_env / extra_env so the read-back resolves the same config the child will — justified
  10. Teardown via awaited session/close — justified

[FIRST-PRINCIPLES-REVIEWED] 0a33494

Description read

[DESCRIPTION-READ] 55cb8fb7791747596f7bf141aa7e992f662210caac5c89119710089c830680c6

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

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0a33494

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

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 0a33494

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

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

@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
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Closing without merging; the branch feat/opencode-harness stays for later.

Why: this harness only pays off once opencode chats can share a process, and they cannot today without leaking tools between chats.

  • The chat-sharing key (ChatRuntimeKey) includes work_dir for every harness: the shared process mounts and enters its founder's folder, so only chats in the same folder can ever share one process.
  • opencode 1.19.1 registers each session's MCP servers on its folder, not on the session (sdk.mcp.add({directory, ...})), and session/close does not remove them. Measured on one opencode acp process: two sessions in one folder each saw the other's tools, a session opened later saw both, and a same-named server registered by the second session replaced the first one's, so the first session's calls reached the second session's server. Giving each session a symlinked folder did not help: opencode resolves the real path.
  • Keeping one chat per folder per process would make the switch a no-op, since every chat that could share is in the same folder.

So opencode chat sharing waits on opencode registering MCP servers per session and removing them on session/close. #37602 (moving the opencode session code off AcpClient, no behaviour change) stands on its own and stays open.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 15, 2026
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.

1 participant