Skip to content

fix(subagent): hint before re-spawning every child whose state was unread - #19004

Merged
javenciu merged 1 commit into
kirodotdev:mainfrom
javenciu:fix/spawn-sub-agents-hint-for-every-unread-child
Oct 12, 2026
Merged

javenciu merged 1 commit into
kirodotdev:mainfrom
javenciu:fix/spawn-sub-agents-hint-for-every-unread-child

Conversation

@javenciu

@javenciu javenciu commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: when spawn_sub_agents cannot read a child's state at the end of its wait, the caller is told to check spawn_status before re-spawning, for a started child as well as a gate-deferred one.

spawn_sub_agents in src/kiro_crew/mcp_tools/spawn.py reads each child once more after its wait. When the gateway does not answer, mcp_core._get returns {"error": …} with no done. The collect loop reports that as an error entry, and adds the hint "accepted at spawn time; its state couldn't be read now; check spawn_status before re-spawning" only if aid in sa_deferred (mcp_tools/spawn.py:1606 at faa0b5b, current main), the children the gate answered with status: "queued". A child that started normally gets a bare error, though the loop's own comment says such a read "could be a transport failure … the agent may still be running".

Why it matters

The tool's own rule, above its queued record: "a caller that sees an error for accepted work dispatches it again, and then it runs twice." A bare error for a started child that is still running invites that second dispatch.

Not a goal

  • The status stays error; the settle, count and collect behaviour and the record's keys are unchanged. A gateway-unreachable entry is documented as an error in test_spawn_queued_reason.py (test_a_transport_failure_is_still_an_error), and this change keeps that.
  • An answer that carries done: False with an error keeps its exact keys, as test_failed_poll_of_an_unfinished_child_carries_no_text pins ("its block keeps its keys"); the hint keys on done being absent, which is when no row was read.
  • Another open change, fix(subagent): mark returned results only after the reply is written #17684, restructures spawn_sub_agents (it moves the collect loop into a helper that takes sa_deferred) and conflicts with this one in spawn.py; whichever lands second needs a rebase.

What changed (motivation → approach → change)

  • Symptom: a started child whose final read failed got an error entry with no hint.
  • Root cause: the hint was gated on sa_deferred.
  • Change (mcp_tools/spawn.py:1979-1983, +5 −1): the hint goes on an error entry when the child is not done and either it was deferred (as before) or the answer carries no done at all. self.sa_deferred is still read, so it stays. Since fix(mcp): park waiting tools off the worker so a wait stalls nobody #18841 the collect loop is _SubAgentsStep._collect, and the condition sits there.
  • Tests in test/test_spawn_queued_reason.py, class TestSpawnSubAgentsHintsEveryUnreadChild, through the real spawn_sub_agents (driven to its reply by the file's _settle, as the sibling classes are) with the gateway client stubbed: test_a_started_child_the_gateway_did_not_answer_for_gets_the_hint, and the control test_a_child_that_finished_with_an_error_gets_its_text_and_no_hint. Every existing test passes unchanged, including the deferred-child tests and the two above.

Backwards compatibility

Compatible: the status values, the counts, the collected set and the record keys are unchanged. Only an error entry with no done in its answer gains the existing hint key.
Removes nothing.

Tests

Red on unchanged origin/main 0a47021 (this test file copied into a detached checkout of it), pytest test/test_spawn_queued_reason.py -p no:cacheprovider -q -n 0, RC=1 in 3 of 3 runs:

FAILED test/test_spawn_queued_reason.py::TestSpawnSubAgentsHintsEveryUnreadChild::test_a_started_child_the_gateway_did_not_answer_for_gets_the_hint - KeyError: 'hint'
=================== 1 failed, 19 passed, 2 warnings in 2.37s ===================

The 19 passed include the control and the deferred-child tests. Green on this branch, rebased onto 0a47021, the same command, RC=0 in 3 of 3 runs:

======================== 20 passed, 2 warnings in 2.14s ========================

The 41 test files that import or name the mcp_tools.spawn module, spawn_sub_agents or _SubAgentsStep: 2790 passed, 4 skipped. mypy on spawn.py, flake8, isort and black on the changed files, scripts/check_black_formatting.py, scripts/docs-lint.sh, scripts/check_harness_parity.py and COMMENT_HISTORY_BASE_REF=origin/main scripts/check_comment_history.py exit 0.

Manual verification

None beyond the tests.

Related Issues

None found. Open #17684, #10175, #10171 and #12821 conflict in mcp_tools/spawn.py, but they conflict there with origin/main already: git merge-tree against this head lists the same conflicting files as against origin/main (#17684 is the one named in Not a goal). #18905 and #19274 have no conflict in mcp_tools/spawn.py.

Pattern harvest

Rule candidate: a reply that cannot say whether accepted work is still running tells the caller how to check before dispatching it again.

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

@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners October 11, 2026 01:26
@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 11, 2026
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

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

Revision d22c61436fc7d0da2bdbff5845e06ea6dbd03fe6 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 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

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

Design-Verdict: PASS

Check that a gateway 404 for an unknown child id, which also has no done, should get the "check spawn_status" hint too.

[DESIGN-REVIEWED] d22c614

Description read

[DESCRIPTION-READ] 4d5cd0d09194d3c99bd5a65126046599b307b318a0e363403ecfad42b4ee7a18

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 11, 2026 •

Copy link
Copy Markdown
Contributor

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

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

Before merge, check that the gateway never returns a no-done error for a child it knows is gone, such as a 404 for an unknown id. The new hint would mislabel it.

What this change ships

Inventory (2 items) — 2 justified

Intent: stop an agent from re-spawning a started sub-agent that may still be running just because its final status read failed. This is a FIX.

  1. A started (not gate-deferred) child whose final read gets no gateway answer now carries the existing "check spawn_status before re-spawning" hint on its error entry — justified
  2. A child that finished with an error keeps its text and gets no hint (control test; behaviour unchanged) — justified

[FIRST-PRINCIPLES-REVIEWED] d22c614

Description read

[DESCRIPTION-READ] c22c396566380c1ac99c9131d57ed7b9f9fa5a84291911e779a27b0442e2782c

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 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] d22c614

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d22c614

@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 11, 2026
@javenciu
javenciu force-pushed the fix/spawn-sub-agents-hint-for-every-unread-child branch from c421a33 to 654a647 Compare October 11, 2026 07:29
@github-actions github-actions Bot added readiness: checking Automated validation is still running 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: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 11, 2026
@javenciu
javenciu force-pushed the fix/spawn-sub-agents-hint-for-every-unread-child branch from 654a647 to ee2059d Compare October 12, 2026 08:35
@javenciu

Copy link
Copy Markdown
Contributor Author

Rebased onto origin/main 0a47021. #18841 moved the spawn_sub_agents collect loop into _SubAgentsStep._collect, which conflicted with the old hunk. I took main's mcp_tools/spawn.py whole and re-applied the same condition change at mcp_tools/spawn.py:1969-1973 (+5 -1), and the new tests now use the file's _settle and _ResumeHold.probe harness like their siblings (test/test_spawn_queued_reason.py:261-268). The conflict came from #18841, not from #17684, which is still open and now conflicts with origin/main in mcp_tools/spawn.py as well.

The new test still fails on origin/main (KeyError: 'hint', 3 of 3 runs, 1 failed and 19 passed) and passes on this head (20 passed, 3 of 3 runs). The 41 test files that import or name the spawn module pass: 2790 passed, 4 skipped.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Oct 12, 2026
@javenciu
javenciu force-pushed the fix/spawn-sub-agents-hint-for-every-unread-child branch from ee2059d to e940182 Compare October 12, 2026 10:02
@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 12, 2026
@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 12, 2026
…read

When spawn_sub_agents could not read a child at the end of its wait
(the gateway did not answer, so the read returned an error with no
done), it kept the error entry but added the hint to check
spawn_status before re-spawning only for a child the gate had deferred.
A child that had started got a bare error, so a caller could dispatch
the same work again while the first run kept going.

The hint now goes on any error entry whose answer carries no done at
all, as well as on a deferred child that is not done. The status, the
error text, the settle and collect behaviour and the record shape are
unchanged.
@javenciu
javenciu force-pushed the fix/spawn-sub-agents-hint-for-every-unread-child branch from e940182 to d22c614 Compare October 12, 2026 20:01
@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 12, 2026
@javenciu
javenciu enabled auto-merge (squash) October 12, 2026 22:49

@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 PR makes spawn_sub_agents put the existing "check spawn_status before re-spawning" hint on any error entry whose status read came back with no done key, not only on gate-deferred children, which fixes the root cause: the hint was gated on sa_deferred alone, so a started child whose final read hit a dead gateway got a bare error that invites a double dispatch. I read the whole condition in _SubAgentsStep._collect (src/kiro_crew/mcp_tools/spawn.py:1979-1983) at head d22c614, and traced mcp_core._get/_send: transport failures and HTTPError bodies both come back as {"error": ...} with no done, so those are exactly the rows that now get the hint, while a finished-with-error row (done: True) and a done: False + error row keep their old keys. The status, counts and settled set are unchanged, so nothing new is collected or skipped. The one edge the design lanes raised, a 404 for an id the gateway forgot, also gets the hint, and that is harmless because the hint only tells the caller to look before re-spawning and spawn_status will report the id as unknown. The new test fails on main with KeyError 'hint' and passes here, and the control test pins the finished-error path. Base is main, it is mergeable, checks and all AI lanes are green on the current head, and there is no open change request. — crew-pr-reviewer (deep re-check)

@javenciu
javenciu merged commit bfb9d53 into kirodotdev:main Oct 12, 2026
105 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 13, 2026
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.

2 participants