Skip to content

feat(subagents): let spawn_run pick the backend a sub-agent runs on - #18150

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
billygerhard:feat/subagent-backend
Oct 11, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
billygerhard:feat/subagent-backend

Conversation

@billygerhard

@billygerhard billygerhard commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: an orchestrating agent can start each sub-agent on whichever installed backend (Kiro, Claude, Codex, ...) suits the task.

Today every sub-agent runs on the gateway's configured backend. spawn_run can pick a model and an effort, but not the harness, so an orchestrator cannot send a review to Claude and a refactor to Codex in one wave. The only workaround is to change the gateway default, which moves every chat with it.

Why it matters

Different harnesses are good at different work. Without a per-spawn backend, multi-harness orchestration means a human switching the global default between waves. This is the core of the backend-selection plan in #13892.

Not a goal

  • No per-chat backend picker or other UI. That is feat: per-chat backend selection #15978, which builds on the same factory tier.
  • No new backend adapters. This routes to backends the build already registers and governance allows.
  • spawn_sub_agents (the blocking variant) is unchanged; it does not take model either.

What changed (motivation → approach → change)

Goal → reuse the one backend-selection gate the provider factory already calls (members.select_provider_backend), giving it a first tier for an explicit backend, and carry that value from the tool to the factory → the change:

  • Tool (mcp_tools/spawn.py, validation.py): spawn_run takes backend batch-wide, and a tasks[] object can override it per task. Names are spelled the way governance rules spell them (kiro, claude, codex), so Kiro is nameable and a falsy value is never mistaken for a pick.
  • Endpoint (messaging_api/spawn.py): /api/spawn maps the name to the backend id. It refuses a backend this gateway cannot start, before the manager counts the spawn:
    • not a known backend, or not in selectable_backend_values() (governance): 400 unknown_backend.
    • allowed but not installed on this machine (backend_install.probe_backend, run off the event loop and cached; a probe that cannot decide does not block): 400 backend_not_installed with its install_command.
    • installed after the gateway started (restart_required: the gateway still caches its absence, so a start would fail): 400 backend_restart_required.
    • Both refusals list only the backends that can start, so an agent's retry picks one that works.
    • It is refused rather than degraded: the factory's gate would quietly fall back to Kiro, and a task sent to another harness silently running on Kiro, or failing at cold start, is the failure this argument exists to prevent.
  • Effort report (subagent.py): the tool's effort_dropped/effort_applied line is judged on the requested backend. The model is translated into that backend's namespace, and a backend that advertises its own effort levels at session start (Pi) gets no verdict instead of a false "dropped". An effort_applied note names the channel that delivers the level: kiro-cli's cli.json key for the Kiro family, or the harness's live config option (e.g. reasoning_effort on Codex). The channel is decided by opt-in membership in the sets the provider gates on (ACP_BACKENDS_KIRO_SLASH_COMMANDS, ACP_BACKENDS_EFFORT_VIA_CONFIG_OPTION). A backend in neither (opencode, goose) never receives the level, so it is reported as dropped.
  • Manager (subagent.py, admission/gate.py, admission/pump.py, subagent_persistence.py): SubagentInfo.backend (None = the default) rides the stagger queue and the run record (state.json backend).
  • Run (subagent_manager/run.py): a backend rules out the shared runtime, which is the parent's process on the parent's backend. The value reaches the factory as backend_override.
  • Factory and allocator (config/loader.py, members.py, session_allocation.py): backend_override is a named factory kwarg, so it can never be swallowed by **_kwargs. It is the first tier of the selection gate (override → member-DM route → configured default), and it still passes resolve_selected_backend. The allocator skips the warm pool for it (bypass_backend_override), because a pooled child runs the default backend.
  • Successors (session.py, session_allocation.py, session_lifecycle.py): the session records the backend_override it started with, and allocation_identity carries it. A reset respawn or a compaction restart of that session therefore comes back on the same harness instead of the default.
  • Follow-ups (continuation.py, run_control.py): spawn_continue inherits the run's backend from the live record or state.json, because the conversation lives on that harness. A retry also runs on the original backend.
  • Docs: src/kiro_crew/docs/subagents.md and docs/system-specs/modules/subagent.md.

Backwards compatibility

Compatible: backend is optional and absent by default. A spawn without it takes exactly the old path: no factory kwarg, same sharing and pool decisions, same state.json keys. Old queue rows and run records lack the key and read as "default".

Removes nothing: the change only adds an optional argument, field and record key.

Tests

test/test_spawn_backend.py (52 tests):

  • Schema: accepts backend names and refuses malformed ones, per task too.
  • Tool: sends the backend batch-wide, lets a task override it, and omits it when unset. The tool advertises the field.
  • Endpoint: claude reaches spawn. kiro reaches it as "". An absent value reaches it as None. A known-but-disallowed backend and an unknown one are refused with unknown_backend and the list. An allowed-but-missing backend is refused with backend_not_installed, its install command, and a list that leaves it out. A backend installed after the gateway started is refused with backend_restart_required. A probe that cannot decide does not block. spawn is not called on any refusal.
  • Manager: records the value, and a queued spawn drains with it.
  • Run: the factory receives backend_override (including "" for Kiro) on a dedicated process. The shared runtime is never used, and sharing is ruled out by a backend.
  • Selection gate: the override beats the member route and the default. "" is an override, not unset. No override changes nothing. An override that stopped being selectable degrades to Kiro.
  • Warm pool: skipped for an override.
  • Successors: allocation_identity carries the backend, including "" for Kiro, and omits it for a session that never named one. Registration stamps it.
  • Effort report: no verdict on an advertised-effort backend. The applied note names the channel the backend actually uses: cli.json for the Kiro family, the live config option for an adapter harness. A backend that takes no effort (opencode, goose) is reported dropped, never applied. The model is resolved in the requested backend's namespace. The endpoint hands the backend to the verdict.
  • Follow-ups: a continuation inherits from the live record and from state.json. A run predating the field continues on the default. The spawn writes the record. A retry keeps the backend.

Mutation probes: removing each of the 19 load-bearing lines fails the suite. They are the factory kwarg, the sharing guard, the queue key, continuation inheritance, the endpoint membership check, the install filter, the restart-required filter, the session stamp, the successor identity, the selection tier, the record key, the retry key, the per-task override, the verdict's backend argument, the applied note's channel choice, the config-option membership check, the no-effort drop reason, the advertised-effort guard and the namespace translation.

Ran locally:

  • 7,202 tests across the spawn, subagent, composition-contract, pool and validation suites.
  • 2,773 across harness parity, backend governance, config loader, provider dispatch, session and MCP coverage.
  • 8,944 across the session, compaction, continuation and composition-contract suites after the successor change.
  • 1,602 across spawn, subagent, messaging and effort. The one test that patches the effort verdict was updated for the new backend keyword.
  • black, flake8, isort, mypy, comment-history, brand, feature-map and docs-lint.

Manual verification

Run end to end on an isolated gateway built from this branch, with Kiro as the gateway default. Full output is in the PR comment below.

  • /api/spawn {backend: "claude", keep: true} completed on Claude. The run record says backend: claude, provider: claude_code, and gives the session id.
  • spawn_continue on that run loaded the same Claude session (claude-acp ... resume=<same session id>). It answered from the first run's context: it recalled the code word it was given.
  • backend: "codex", which is allowed by policy but not installed on that host, was refused as backend_not_installed with its install command. backend: "nonesuch" was refused as unknown_backend. Both listed claude, kas and kiro, the backends installed and allowed on that host.

Related Issues

Part of #13892

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@billygerhard
billygerhard requested review from a team and KiroCrewCaptain as code owners October 8, 2026 12:59
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 8, 2026
@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 9010a26cb1c83b387e86e5688f378785ad6d5934 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

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 9010a26cb1c83b387e86e5688f378785ad6d5934 via the fork AI-review pipeline — 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: PASS

Nothing to check.

What this change ships

Inventory (10 items) — 10 justified

Intent: an orchestrating agent sends each sub-agent to the installed harness that suits its task, without changing the gateway default. This is an ADDITION.

  1. spawn_run takes an optional batch-wide backend (kiro, claude, codex, ...); absent means the old path — justified
  2. A tasks[] object can set its own backend for one task in a wave — justified
  3. /api/spawn refuses an unknown, governance-denied, not-installed or installed-after-boot backend, listing what can start — justified
  4. The tool's error line shows the install command for a missing backend — justified
  5. A spawn with a backend never shares the parent's runtime and skips the warm pool — justified
  6. The provider factory's one selection gate gains a first tier for an explicit backend, still governance-resolved — justified
  7. A reset or compaction restart of that session comes back on the same harness — justified
  8. A queued spawn, a retry and spawn_continue keep the run's backend; state.json records it — justified
  9. The effort applied/dropped report is judged on the requested backend's channel and namespace — justified
  10. Docs: subagents.md and the subagent spec describe the new parameter — justified

[FIRST-PRINCIPLES-REVIEWED] 9010a26

Description read

[DESCRIPTION-READ] 86274613057b02c4657f264aacdeb1a0b433a4d4a1ccd495a5224d89fab8ec70

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 Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — 🟡 CONCERNS

Design-level review of 9010a26cb1c83b387e86e5688f378785ad6d5934 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

spawn_continue and retry skip the endpoint's backend refusal, so a backend that has since become unavailable silently falls back to Kiro on a follow-up.

Watch

  • Follow-ups bypass the refusal gate. continuation.py hands spawn(backend=backend) the backend it reads from state.json. run_control.py does the same through backend=getattr(old, "backend", None). Neither path goes through _requested_backend. Suppose governance narrows the allowed set, or the harness is uninstalled. The factory's resolve_selected_backend then "degrades to kiro". Kiro cannot load the original Claude or Codex conversation, so the follow-up starts over and nobody is told. The PR's own comment names this as the failure to prevent: "a follow-up on another backend could not load it, and would start over". Today that fallback is guarded only on the first spawn.
    Clears when: continuation and retry run the inherited backend through the same availability check, and refuse it with a reason instead of degrading; a test pins this for a backend that is no longer selectable.
  • No live test of a non-default child. Every test mocks the factory and the probe. The visible description gives no evidence that a sub-agent ever actually started on Claude or Codex, with its MCP tools mounted and the sandbox applied, under a Kiro parent. The manual-verification part of the description is past the truncation, so I could not check it.
    Clears when: the PR shows one live spawn_run(backend="claude"), or another non-default harness, that completes and reports back on a real gateway.

[DESIGN-REVIEWED] 9010a26

Description read

[DESCRIPTION-READ] 296f66ee790d2194e78e2cecb693503416f7aa84dbd26e1ea24f89047bc0a167

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 Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 9010a26cb1c83b387e86e5688f378785ad6d5934 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9010a26

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 9010a26cb1c83b387e86e5688f378785ad6d5934 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9010a26

@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 Oct 8, 2026
@billygerhard

Copy link
Copy Markdown
Contributor Author

Live run on an isolated gateway (kirocrew pod up kirocrew-wt-subagent-backend, built from this branch at 60f60f2ad5, gateway default backend = Kiro). Calls went straight to the pod's /api/spawn, which is what spawn_run posts to.

1. spawn_run(backend="claude", keep=true) from a Kiro-default gateway

POST /api/spawn {"task":"Remember the code word ZEBRA-42. Reply with exactly: OK, and nothing else.",
                 "backend":"claude","keep":true,"approval_mode":"auto","cwd":"/workplace/wilgerh/kc-pr18150-probe"}
-> {"id": "bcafb1d5486e3bf2", "status": "spawned", "conversation": "bcafb1d5486e3bf2"}
run bcafb1d5486e3bf2: done=True outcome=completed result='OK'

state.json: {"backend": "claude", "provider": "claude_code",
             "session_id": "daa1f235-c9a0-4d75-b7fe-a092eb849174", "keep": true}

2. spawn_continue on it: the same Claude session is loaded, and it remembers

POST /api/spawn/bcafb1d5486e3bf2/continue {"task":"What code word did I ask you to remember? Reply with only the code word."}
-> {"id": "d066aee221645090", "conversation": "bcafb1d5486e3bf2", "status": "spawned"}
run d066aee221645090: done=True outcome=completed result='ZEBRA-42'

state.json: {"backend": "claude", "provider": "claude_code",
             "session_id": "daa1f235-c9a0-4d75-b7fe-a092eb849174", "conversation_key": "subagent:bcafb1d5486e3bf2"}
gateway log: claude-acp stderr: [session/query] sessionId=daa1f235-c9a0-4d75-b7fe-a092eb849174
             resume=daa1f235-c9a0-4d75-b7fe-a092eb849174 apiType=native

3. Refusals from the same gateway (codex is allowed by policy but not installed on this host)

POST /api/spawn {"task":"x","backend":"codex"}
-> 400 {"error": "backend 'codex' is not installed on this machine (missing: codex-acp); choose one of ['claude', 'kas', 'kiro']",
        "code": "backend_not_installed", "backends": ["claude", "kas", "kiro"],
        "install_command": "npm i -g @agentclientprotocol/codex-acp"}

POST /api/spawn {"task":"x","backend":"nonesuch"}
-> 400 {"error": "backend 'nonesuch' is not available; choose one of ['claude', 'kas', 'kiro']",
        "code": "unknown_backend", "backends": ["claude", "kas", "kiro"]}

Setup notes (pod only):

  • The pod has no dashboard client to answer approval prompts. The spawn passed approval_mode: "auto", and the continuation ran with hooks.auto_approve_subagent_spawn: true in the pod's own config.
  • The run used an explicit cwd under an allowed root. In this pod, a keep-run continuation with no cwd is refused for a cwd reason on the default Kiro backend too, so that is not specific to this change.

@billygerhard
billygerhard force-pushed the feat/subagent-backend branch 2 times, most recently from 60f60f2 to 4f36b04 Compare October 8, 2026 15:28
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 8, 2026
@billygerhard
billygerhard force-pushed the feat/subagent-backend branch from 4f36b04 to 4b3cd5d Compare October 8, 2026 15:56
@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 Oct 8, 2026
@billygerhard
billygerhard force-pushed the feat/subagent-backend branch 2 times, most recently from a78a792 to 31dad2f Compare October 8, 2026 17:40
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 8, 2026
billygerhard added a commit to billygerhard/KiroCrew that referenced this pull request Oct 11, 2026
Propose an optional backend on spawn_run so an orchestrator can run one
sub-agent on another harness that governance already allows. A pick that
cannot start is refused with a typed code rather than run on Kiro, and
selection keeps the single construction gate. Implementation: kirodotdev#18150.
Refs kirodotdev#13892.
billygerhard added a commit to billygerhard/KiroCrew that referenced this pull request Oct 11, 2026
Propose an optional backend on spawn_run so an orchestrator can run one
sub-agent on another harness that governance already allows. A pick that
cannot start is refused with a typed code rather than run on Kiro, and
selection keeps the single construction gate. Implementation: kirodotdev#18150.
Refs kirodotdev#13892.
@bolichen97

Copy link
Copy Markdown
Contributor

Maintainer decision (bolichen97): yes, I want this feature, limited to the harnesses governance already allows. For RFC #18486 Q2: when the recorded backend can no longer start, continue and retry should refuse, not fall back to Kiro. Do that as a separate follow-up PR. In this PR, please change the tool schema text in mcp_tools/spawn.py so it promises the refusal only at spawn time, and surface install_command in the tool output (Opus finding). Then rebase.

Posted by an AI assistant at bolichen97's request, after a read-only review of this head.

spawn_run gains a backend argument (batch-wide, overridable per task) so an
orchestrator can hand each task to the harness that suits it. /api/spawn refuses
a backend this gateway cannot serve with the selectable list; the value rides
the queue, the run record, retries and continuations, forces the dedicated
process, skips the warm pool, and reaches the provider factory as the first
tier of select_provider_backend.

Part of kirodotdev#13892
@billygerhard
billygerhard force-pushed the feat/subagent-backend branch from c4c1406 to 9010a26 Compare October 11, 2026 04:18
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 11, 2026
billygerhard added a commit to billygerhard/KiroCrew that referenced this pull request Oct 11, 2026
Propose an optional backend on spawn_run so an orchestrator can run one
sub-agent on another harness that governance already allows. A pick that
cannot start is refused with a typed code rather than run on Kiro, and
selection keeps the single construction gate. Implementation: kirodotdev#18150.
Refs kirodotdev#13892.
@billygerhard

Copy link
Copy Markdown
Contributor Author

Done, and rebased onto main:

  • The spawn_run backend schema text (and subagents.md) now promises the refusal only at spawn time, and says a follow-up or retry asks for the run's backend.
  • A backend_not_installed refusal now shows its install_command in the tool output, with a test pinning it.

RFC #18486 records both answers. Refusing on continue and retry is Phase 2, which will be a follow-up PR after this one.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 11, 2026
billygerhard added a commit to billygerhard/KiroCrew that referenced this pull request Oct 11, 2026
Propose an optional backend on spawn_run so an orchestrator can run one
sub-agent on another harness that governance already allows. A pick that
cannot start is refused with a typed code rather than run on Kiro, and
selection keeps the single construction gate. Implementation: kirodotdev#18150.
Refs kirodotdev#13892.

@iamwhatever iamwhatever 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.

This adds spawn_run(backend=...), so an orchestrator can start a child on another allowed harness. The product question we held on is now settled. Maintainer bolichen97 approved the feature, limited to governance-allowed harnesses, and ruled that refusal on continue and retry ships as a separate follow-up (RFC #18486 Q2). Head 9010a26 does both things asked: the schema text and subagents.md promise refusal only at spawn time, and a backend_not_installed refusal shows install_command, with a test. I re-read the production diff and tried to get past the gate. The name is held to ^[a-z0-9][a-z0-9_-]*$, so it cannot inject into logs. An unknown name, or a known but governance-denied one, misses the selectable-only probe map and gets unknown_backend, listing only what can start. Missing and restart_required backends are refused, not degraded. The paths that skip /api/spawn (continuation from state.json, retry, admission pump, session rebuild) still pass members.select_provider_backend through resolve_selected_backend, so a tampered state.json can only pick a governance-allowed backend. Shared runtime and the warm pool are bypassed for an override, so a child cannot land on the parent's harness. The last Design Watch (follow-ups degrade silently) is the maintainer-ruled follow-up, not a defect here. Checks are green, it is mergeable on main, and there is no change request. — crew-pr-reviewer (deep re-check)

@iamwhatever
iamwhatever enabled auto-merge (squash) October 11, 2026 06:05
@iamwhatever
iamwhatever merged commit 10b6b54 into kirodotdev:main Oct 11, 2026
107 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 2026
billygerhard added a commit to billygerhard/KiroCrew that referenced this pull request Oct 11, 2026
Propose an optional backend on spawn_run so an orchestrator can run one
sub-agent on another harness that governance already allows. A pick that
cannot start is refused with a typed code rather than run on Kiro, and
selection keeps the single construction gate. Implementation: kirodotdev#18150.
Refs kirodotdev#13892.
billygerhard added a commit to billygerhard/KiroCrew that referenced this pull request Oct 11, 2026
Propose an optional backend on spawn_run so an orchestrator can run one
sub-agent on another harness that governance already allows. A pick that
cannot start is refused with a typed code rather than run on Kiro, and
selection keeps the single construction gate. Implementation: kirodotdev#18150.
Refs kirodotdev#13892.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants