Skip to content

fix(spawn): backport generated-spec roster fix to release/0.8.0 - #15314

Merged
bolichen97 merged 1 commit into
release/0.8.0from
backport/0.8.0-spawn-internal-agent-specs
Sep 30, 2026
Merged

bolichen97 merged 1 commit into
release/0.8.0from
backport/0.8.0-spawn-internal-agent-specs

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Ship the generated-spec roster fix (#15271) on the 0.8 line, so on a 0.8.0.x build sub-agents stop failing because the model picked the side turn's <agent>--readonly spec.

This is a backport of #15271 to release/0.8.0. The root cause, design and evidence are in #15271: every spawn roster offered the derived read-only spec, the gate accepted it, and the child's kiro-cli then refused the mode with a hint to run kirocrew setup --agent-only, which never writes that file.

Why it matters

0.8.0.x is on the stable channel. On a 0.8.0 build, any install that has used a side reply can hand the model a sub-agent name that always fails, so sub-agent spawns fail by default until someone deletes the file by hand.

Not a goal

What changed (motivation → approach → change)

One commit, following the release-branch backport shape of #11339, #11645 and #15151 (source SHA as a cherry picked from trailer):

Commit Source on main What it brings
fix(spawn): backport generated-spec roster fix to release/0.8.0 #15271, merged as 5c4f8a5 agent_discovery.is_internal_agent_spec; the filtered spawn_run roster, spawn_list and refusal roster; the agent_internal refusal in _validate_agent and the wave short-circuit; the app-ownership exclusion (subagent + SpawnSDK); side_readonly_spec.unavailable_mode_explanation (keyed on the owner marker, run off the loop) at the three ACP mode refusals; the spec paragraphs in subagent.md and side.md

This is cut from the MERGED commit on main (5c4f8a53a6), and every added and removed line matches it. The follow-up remedy wording, #15348, is not merged yet. It will be added here as a second commit once it lands, or backported on its own.

Two import-list conflicts were resolved, and no logic changed. In mcp_tools/spawn.py, release/0.8.0 does not import format_subagent_usage from subagent, so only is_internal_agent_spec was added. In acp/client.py, release/0.8.0 still imports is_credential_propagation_delay (main dropped it), so both imports were kept. Every other hunk applied cleanly.

Backwards compatibility

Compatible, for the same reasons as #15271. Only specs carrying the side turn's owner marker (plus skill-view aliases, which discovery already hid) stop being listed or accepted, and spawning one was already failing at the child's set_mode.

Tests

The same tests as #15271: test/test_spawn_internal_agent_specs.py (new), plus the added cases in test/test_acp_runtime.py and test/test_acp_set_mode_all_agents.py. On this branch the touched-module suites pass (1920 passed across the touched-module and neighbouring suites; 712 in: those three files plus test_agent_roster_shared.py, test_spawn_agent_roster.py, test_side_readonly_spec.py, test_spawn_parent_available_agents.py and test_app_spawn_capability.py, test_agent_spec_hardened_reads.py).

Manual verification

As in #15271: reproduced against a throwaway KIRO_HOME with the real publisher. The roster and gate output before and after is in that PR.

Related Issues

Backport of #15271. Supersedes #15272 (same commit, re-opened from a same-repo branch because fork PRs into release branches do not start the review lanes).

Pattern harvest

Rule candidate: review-prompt
Pattern: a spec Kiro Crew writes into the shared ~/.kiro/agents registry for its own machinery must be recognised by one predicate (is_internal_agent_spec) at every roster and gate that reads that directory.

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

@bolichen97
bolichen97 requested a review from a team as a code owner September 30, 2026 06:04
@bolichen97
bolichen97 requested review from kyleseaman and removed request for a team September 30, 2026 06:04
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 30, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Local test evidence for 0d98d90fcb209cdd0ed0edd440ed47ae68f41c0d (the head of this PR). Backend CI does not run for PRs into release branches, so this is the backend proof.

Checkout: origin/release/0.8.0 plus this one commit (git cherry-pick -x 866a328c41). CPython 3.12.13, Linux, PYTHONPATH=<worktree>/src.

$ python -m pytest -q -n 8 \
    test/test_spawn_internal_agent_specs.py test/test_acp_set_mode_all_agents.py \
    test/test_agent_roster_shared.py test/test_spawn_agent_roster.py \
    test/test_side_readonly_spec.py test/test_spawn_parent_available_agents.py \
    test/test_app_spawn_capability.py test/test_acp_runtime.py \
    test/test_agent_spec_hardened_reads.py test/test_admission_gate.py \
    test/test_subagent_coverage.py test/test_api_server.py \
    test/test_agent_discovery*.py test/test_acp_client*.py
===================== 1920 passed, 333 warnings in 24.83s ======================

$ mypy src/kiro_crew
Success: no issues found in 1860 source files

$ black --check --target-version py310 <touched .py> && isort --check-only <touched .py> && flake8 <touched .py>
(clean)

The same change on main (#15271 @ 866a328c41) is green across its whole CI matrix: backend 3.12 and Windows shards, lint and type check, coverage, E2E and frontend. Its PR Readiness has passed.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Confirm byte parity with 5c4f8a53a6 via git range-diff; numstat and both conflict hunks match, but a full interdiff wasn't run here.

[DESIGN-REVIEWED] bdaeec8

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of bdaeec816b99a4b569dccac54fa1cf725978405e — 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

Verify #15271 is merged on main and this diff matches its merged commit 212a804 — the description itself makes merging before that a non-goal.

What this change ships

Inventory (7 items) — 6 justified

Intent: FIX (backport) — stop sub-agent spawns on 0.8.0 failing because rosters offered the side turn's generated <agent>--readonly spec.

  1. Spawn rosters (spawn_run hint, spawn_list, unknown-agent refusal) no longer list generated specs — justified
  2. Naming a generated spec is refused with new agent_internal code, pointing to the base agent — justified
  3. A spawn wave stops re-posting a name refused as internal — justified
  4. App ownership checks no longer count <app>--<agent>--readonly as the app's agent (host gate + SpawnSDK) — justified
  5. The ACP "Agent mode not available" refusal explains the derived spec and drops the wrong kirocrew setup hint (three sites) — justified
  6. Skill-view alias rows also match the predicate, though discovery already hides them (agent_discovery.py:1557) — rides along: harm-free defense carried from fix(spawn): keep generated side-reply specs out of the sub-agent roster #15271; zero observable change today
  7. subagent.md/side.md sections updated in the same commit — justified

[FIRST-PRINCIPLES-REVIEWED] bdaeec8

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of bdaeec816b99a4b569dccac54fa1cf725978405e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] bdaeec8

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

@bolichen97

Copy link
Copy Markdown
Contributor Author

Answering the Design and First Principles verification asks on 0d98d90fcb:

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] bdaeec8

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

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

@bolichen97
bolichen97 force-pushed the backport/0.8.0-spawn-internal-agent-specs branch from 0d98d90 to 7d0a127 Compare September 30, 2026 07:29
@bolichen97

Copy link
Copy Markdown
Contributor Author

Opus 5's advisory on 0d98d90fcb was right. When the base is the host default (kirocrew--readonly, the common case), the remedy told the user to name kirocrew, which no roster offers, and it never said what actually recovers: a new session, whose kiro-cli lists the agents again. I fixed this upstream in #15271 (now 212a804d60) and re-cut this backport from that commit. The new head is 7d0a127c63. The remedy now reads:

A new session starts a kiro-cli that lists it. It is not a sub-agent: to spawn its source agent, name 'scout', or omit 'agent' when that is the default agent.

Local test evidence for 7d0a127c63b0df6dfad22e70d3e78636a9d75d17 (origin/release/0.8.0 plus git cherry-pick -x 212a804d60; CPython 3.12.13, Linux). Backend CI does not run for release-branch PRs:

$ python -m pytest -q -n 8 test/test_spawn_internal_agent_specs.py test/test_acp_set_mode_all_agents.py \
    test/test_agent_roster_shared.py test/test_spawn_agent_roster.py test/test_side_readonly_spec.py \
    test/test_spawn_parent_available_agents.py test/test_app_spawn_capability.py test/test_acp_runtime.py \
    test/test_agent_spec_hardened_reads.py test/test_admission_gate.py test/test_subagent_coverage.py \
    test/test_api_server.py test/test_agent_discovery*.py test/test_acp_client*.py
===================== 1920 passed, 332 warnings in 24.26s ======================
$ mypy src/kiro_crew
Success: no issues found in 1860 source files
$ black --check / isort --check-only / flake8 on the touched .py files: clean
$ diff <(git show 212a804d60 | added/removed lines) <(git show 7d0a127c63 | added/removed lines)
(identical)

@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 Sep 30, 2026
@bolichen97
bolichen97 force-pushed the backport/0.8.0-spawn-internal-agent-specs branch from 7d0a127 to 233814f Compare September 30, 2026 08:01
A side turn publishes <agent>--readonly.json into ~/.kiro/agents, the
only directory kiro-cli loads specs from. Every spawn roster read that
directory unfiltered, so spawn_run's "Valid names right now",
spawn_list and the unknown-agent refusal offered the read-only spec,
and the gate accepted it. The child's kiro-cli, which lists agents only
at process start, then refused the mode and told the user to run
`kirocrew setup --agent-only`, which never writes that file.

agent_discovery.is_internal_agent_spec recognises Kiro Crew's own
generated specs (the read-only spec by its owner marker, skill-view
aliases by prefix). The rosters leave them out, _validate_agent refuses
a named one with its own code (agent_internal) and names the base
agent, and an app no longer owns a spec derived from its agent. The
three "Agent mode ... is not available" refusals explain a derived
read-only name instead of pointing at setup.

(cherry picked from commit 5c4f8a5)
@bolichen97
bolichen97 force-pushed the backport/0.8.0-spawn-internal-agent-specs branch from 233814f to bdaeec8 Compare September 30, 2026 08:01
@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 Sep 30, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

#15271 merged at 866a328c41 (squash 5c4f8a53a6, at 06:09Z) before the remedy fix I posted above could reach it. So this backport is re-cut from the merged commit, as its "Not a goal" requires. The new head is bdaeec816b, with the trailer cherry picked from commit 5c4f8a53a6. The remedy wording Opus flagged is now its own PR on main, #15348, and will reach 0.8 once that merges.

Local evidence for bdaeec816b99a4b569dccac54fa1cf725978405e (origin/release/0.8.0 + git cherry-pick -x 5c4f8a53a6; CPython 3.12.13, Linux). Backend CI does not run for release-branch PRs:

$ diff <(git show 5c4f8a53a6 | added/removed lines) <(git show bdaeec816b | added/removed lines)
(identical)
$ python -m pytest -q -n 8 <the same 14 test files as above>
===================== 1920 passed, 333 warnings in 20.99s ======================
$ mypy src/kiro_crew
Success: no issues found in 1860 source files
$ black --check / isort --check-only / flake8 on the touched .py files: clean

The earlier Opus 5, Design, First Principles and GPT failures on 7d0a127c63 were lane infrastructure, not verdicts. Each job reports "Could not read this PR's comments after 3 attempts": the Actions installation token hit its API rate limit.

@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 Sep 30, 2026
@bolichen97
bolichen97 merged commit 556bf8e into release/0.8.0 Sep 30, 2026
25 of 32 checks passed
@bolichen97
bolichen97 deleted the backport/0.8.0-spawn-internal-agent-specs branch September 30, 2026 16:57
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 30, 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