Skip to content

fix(subagent): report MCP servers that failed to start at spawn - #12176

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/subagent-mcp-report-visibility
Sep 20, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/subagent-mcp-report-visibility

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A sub-agent whose MCP server never started is told nothing. The tools are simply
absent. It then hunts for the tool it was asked to use — shell probes, retries —
until its whole turn budget is gone, and the person reading the result sees a
timeout with no cause.

Why it matters

This is the slowest possible way to learn that a server is broken. One spawn can
spend its entire timeout on it, the parent session pays for those turns, and the
answer was available the moment the session started.

What changed (motivation → approach → change)

A spawn now says, once, which of its MCP servers it cannot use — to the log AND
to the run itself.

Bucket The line says What the reader does next
failed failed to start: <server> (<reason>) fix the server's startup
awaiting authorization awaiting authorization: <server> a person authorizes it
declared but not configured declared by the agent spec but not configured: <ref> the spec names a server nothing supplies
all clean nothing at all, anywhere nothing

The fact was already collected. src/kiro_crew/acp/mcp_session_report.py buckets
every registration frame a session receives, and a session that started without a
server has always known so. Every reader of it was a dashboard slot, which a
sub-agent spawn does not have.

So the report gains problem_summary(), one line built from those three buckets
and empty when the session is healthy. It is a method on the report, declared on
the SessionMcpReport protocol in src/kiro_crew/providers/base.py, because a
consumer must reach it through the object it already holds: the agent-SDK boundary
refuses application code an ACP import.

src/kiro_crew/subagent_manager/run.py reads it once, right after it captures the
new session's identity. That point is where both session arms converge — the
shared parent runtime and the dedicated process — so one call covers a spawn on
either transport. The line goes two places: a warning for the operator, and the
front of the run's own first prompt, saying those tools are not mounted and not to
search for them. A log alone cannot stop the hunting, because the run never reads
it.

The two copies are not the same text. Only the log gets the failure reasons: a
reason is the failing server's own startup output, which in the OAuth and network
cases can carry remote content, and the existing scrub (credentials, URLs, control
characters, length) does not disarm a plain-English instruction. The prompt gets
names only, fenced as untrusted data behind a tag carrying a per-spawn random
value, so a declared name cannot read as a directive or close the fence and keep
writing outside it.

The retry rule follows the bucket, because the buckets are not alike. A failed or
unconfigured server will not turn up later, so retrying it only spends turns. One
awaiting authorization can turn up the moment a person authorizes it — that is the
remedy the operator warning exists to trigger — so the notice keeps a single retry
of that one open.

A healthy spawn's prompt is byte-for-byte what it was, and a provider that keeps no
report stays silent too: no report is not evidence of a broken server. This is what
was known at session start — a frame that lands later is not re-read.

docs/system-specs/modules/acp-client.md gains the contract: what the one-line
renderer names, why it is empty when the session is healthy, and why the
model-facing call drops the reasons.

Left unfixed, deliberately: the four workflow spawn sites that prompt a model
unattended — src/kiro_crew/workflows/agent_exec.py,
src/kiro_crew/workflows/agent_pool.py (two) and
src/kiro_crew/workflows/service.py — still read no report and stay silent. They
compose their prompts separately, so covering them is its own change; this one is
the sub-agent spawn path only.

Backwards compatibility

Compatible: one new method on a report, one new line on the protocol that declares
it, and a warning plus a prompt prefix that appear only for a session that is
already broken. No payload, reader, or healthy-path prompt changes.

Tests

test/test_subagent_mcp_report_visibility.py. The summary: each bucket named with
its own wording, a ready server left out, a failure with no reason still named, a
long list counted rather than printed, reasons droppable while the names stay, a
hostile name unable to forge a second line, and the capability nameable on the
protocol. The operator warning: exactly one warning naming the sub-agent, the agent
and both servers; nothing at all for a clean report, a provider with no report, or
a report that raises. The prompt: the names arrive fenced and labelled as data, the
fence tag differs per spawn, a healthy session leaves the prompt untouched, and a
startup reason carrying a directive reaches the log and never the prompt. Two tests
pin the wiring at the converged seam and that the seam takes no ACP import.
Mutation-checked: returning the reason-carrying copy to the model, fixing the fence
tag, dropping the prompt prefix, dropping the empty-on-clean guard, or dropping the
unresolved-refs bucket each fails a test.

Manual verification

N/A — unit coverage sufficient. The summary is pure and both delivery paths are
covered through a provider double; reproducing the live case needs a backend that
starts a real MCP server, which the report's own accumulation tests already cover
at the transport.

Related Issues

no linked issue: reported downstream by an operator, no public issue filed.

Pattern harvest

Rule candidate: review-prompt
Pattern: a diagnostic the runtime already accumulates is delivered only to an
operator surface, so the code path that suffers the fault never learns of it — and
moving such a diagnostic to a model-facing surface turns its untrusted text into an
injection sink.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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

@iamwhatever
iamwhatever requested review from a team and CrysisDeu September 20, 2026 04:09
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Intent: A sub-agent spawn should say, at the moment its session starts, which of its MCP servers it cannot use — so a missing tool is learned in one line instead of by burning the run's turn budget searching for it.
Not a goal: A live view of a session's MCP servers, any change to how servers start or authorize, and any new surface beyond the one warning line.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 20, 2026
@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the one-time read at the convergence point actually follows the init-frame drain — a server failing after that read silently reverts to the old hunting behavior.

Suggestions

  • When the workflow spawn sites get their follow-up, hoist the notice/fence composition (_spawn_mcp_notice) somewhere both paths can share it, rather than re-authoring the fencing rules there.

[DESIGN-REVIEWED] af9876f

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] af9876f

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

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] af9876f

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

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

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of af9876f6a589f23eef54f9df7136a59442f03c38 — 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 on a live backend that authorizing a server mid-session really mounts its tools — the prompt's single-retry allowance rests on that double-tested premise.

What this change ships

Inventory (7 items) — 7 justified

Intent: stop a sub-agent from spending its turn budget hunting for tools its failed MCP server never mounted — a FIX (the diagnostic already existed; before this, its only readers were session_capabilities.py and dashboard/chat_runner.py, zero model-facing — counted via mcp_session_report( grep).

  1. A broken spawn's first prompt opens with a nonce-fenced notice naming its unusable servers — justified
  2. The notice sets a per-bucket retry rule: never for failed/unconfigured, one retry for auth-pending — justified
  3. The operator log gains one warning per broken spawn, failure reasons included — justified
  4. New problem_summary(include_reasons) on the report and SessionMcpReport protocol — justified
  5. A long problem list prints eight names then counts the tail — justified
  6. An unreadable report is swallowed and the run proceeds noticeless — justified
  7. acp-client.md documents the renderer contract — justified

The boundary-gate rationale for the protocol method is real (scripts/check_agent_sdk_boundary.py blocks new ACP imports from application code). The four deferred workflow spawn sites verify: 0 report readers under workflows/.

[FIRST-PRINCIPLES-REVIEWED] af9876f

@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 20, 2026
@iamwhatever
iamwhatever force-pushed the fix/subagent-mcp-report-visibility branch from 7111cbb to 231e910 Compare September 20, 2026 04:49
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the spawn-time summary is now prefixed to the run's own first prompt, not only logged

  • span=3a36bff75de2 — fixed

Correct: the log reached the operator, and the operator is not the one hunting.
The second victim in the problem statement is the run itself, and log.warning
cannot reach it.
Taken your Clears-when first branch, and the SUGGESTIONS branch of the same
reading (span=de8bca49c769): _warn_unusable_mcp_servers now RETURNS the same
line, and _run_inner_impl puts it in front of the task at the seam that
already composes the message — message = self._spawn_mcp_notice(mcp_problems) + message, one line after the existing _CANCEL_RESUME_PREFIX prefix, so no new
seam and no new delivery path.
The notice names the servers and tells the run they are not mounted and not to
retry them, which is the half that stops the turn-budget burn.
Empty in, empty out: a healthy spawn's prompt is byte-for-byte unchanged, pinned
by test_a_healthy_session_leaves_the_prompt_byte_for_byte and mutation-checked
(removing the prefix line fails the seam test).
Fixed in 231e910.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: prompt-side delivery reuses the existing message composition, adding no seam

  • span=de8bca49c769 — fixed

Adopted as written. problem_summary() was already pure and empty-on-clean, so
prepending its non-empty output to the spawn's prompt needed no new seam: the
converged identity-capture point returns the line, and the existing
message = raw_task if named_agent else (_SYSTEM_PREFIX + raw_task) composition
a few lines below prefixes it.
_spawn_mcp_notice is the only new code — it returns "" for an empty summary,
so the caller concatenates unconditionally and no branch is added to the hot
path.
Fixed in 231e910.

@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 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the summary is delivered to the run's own context, so the named harm is addressed rather than only observed

  • span=d98ddf887800 — fixed

Item 1 holds as written: the description's defect was the sub-agent's behaviour,
and the remedy reached only RunEventCoordinator's logger — a surface the run
never reads. Operator diagnosis is not the harm the problem statement names.
Rather than narrow the claim, the delivery moved: the same line the warning
carries is returned and prefixed to the run's first prompt at the converged
seam, telling it the servers are not mounted and not to retry them. That is the
consumer's own surface, so the turn-budget harm is addressed, not left.
The description now states both deliveries and states the boundary honestly: it
is what was known at session start, and a frame arriving after the init drain is
not re-read.
Fixed in 231e910.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: none added; the method-local import is gone and the renderer moved onto the report object

  • span=10162e9148b0 — fixed

Legitimate, and it was the same root cause as the red agent-sdk-boundary gate:
the method-local from kiro_crew.acp.mcp_session_report import problem_summary
broke top-level-imports AND gave application code a new ACP edge, which that
gate refuses outright.
Moving the import to module scope would have fixed only the style half and kept
the boundary red, so the renderer became a METHOD on McpSessionReport,
declared on the SessionMcpReport protocol beside payload. The seam already
holds the report via client.mcp_session_report(), so it now calls
report.problem_summary() and imports nothing at all.
agent-sdk-boundary passes, and a test asserts the seam's source carries no
kiro_crew.acp string so the edge cannot come back.
Fixed in 231e910.

@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 20, 2026
@iamwhatever
iamwhatever force-pushed the fix/subagent-mcp-report-visibility branch from 231e910 to 0658ce1 Compare September 20, 2026 05:26
@iamwhatever

iamwhatever commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the model-facing copy drops server-authored reasons, and the names it keeps are fenced behind a per-spawn random tag

  • Untrusted MCP errors are injected as host instructions — fixed

Legitimate, and the adjudication's reading is correct: _failures[name] is the
failing server's own startup text, sanitize_sink_text scrubs credentials,
exfil URLs, control characters and length, and none of those neutralizes a
plain-English directive. Prepending it to the first prompt made a log-safe
string a model-facing one, which is a sink the previous revision did not have.
Two changes, not a screen. First, the reason never reaches the model at all:
problem_summary(include_reasons=False) keeps the names and drops the text, and
that is the value _warn_unusable_mcp_servers returns; the reasons stay in the
operator's warning, where a person fixing a startup needs them.
Second, the names themselves are config-authored, so they are fenced as
UNTRUSTED DATA inside <<<BEGIN_UNTRUSTED_MCP_<nonce>>>> / <<<END_..._<nonce>>>>
with secrets.token_hex(4) per spawn. A fixed tag would let fenced text close
the fence and keep writing outside it; an unpredictable one takes that away.
Pinned by tests: a startup reason carrying a directive appears in the log and in
neither the returned string nor the notice; the fenced region contains exactly
the names; the tag varies across calls. Mutation-checked — returning the
reason-carrying copy and fixing the tag each fail a test.
Fixed in 0658ce1.

@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 Sep 20, 2026
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0658ce1

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

@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 20, 2026
@iamwhatever
iamwhatever force-pushed the fix/subagent-mcp-report-visibility branch from 0658ce1 to d117fa7 Compare September 20, 2026 05:47
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in test/test_vector_memory.py since this head went green (2b7d378 -> 7e8f2c4); CI re-running. No diff change — the two reds on the previous head were main's own, both already fixed upstream: the sandbox.py delegated-overlap assert (#12193) and the _retire_stale_episodic stub signature (7e8f2c4).

@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 Sep 20, 2026
A sub-agent whose declared MCP server failed to start, was waiting to be
authorized, or was never configured saw neither the tools nor a reason. The
session already accumulated that answer in McpSessionReport, but every reader
was a dashboard slot, which a spawn does not have, so the run learned the tool
was missing the slow way: by searching for it until its turn budget was spent.

McpSessionReport gains problem_summary(), one line rendering the failed /
awaiting-auth / unresolved-ref buckets and empty when the session is healthy,
declared on the SessionMcpReport protocol so a consumer reaches it without an
ACP import. subagent_manager/run.py reads it once where the shared and
dedicated session arms converge, logs it for the operator, and states it in the
run's own first prompt so the run does not spend turns discovering the absence.

The prompt copy carries names only: a failure reason is the failing server's own
startup output, and no scrubber neutralizes a natural-language instruction. The
names are fenced as untrusted data behind a per-spawn random tag, so a declared
name cannot read as a directive or close the fence. Silent everywhere when the
report is clean or the provider keeps none.
@iamwhatever
iamwhatever force-pushed the fix/subagent-mcp-report-visibility branch from d117fa7 to af9876f Compare September 20, 2026 06:20
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for d117fa7f6db45c4b0e99b36c23e582a5a1838cae; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

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

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for af9876f6a589f23eef54f9df7136a59442f03c38; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: none added; the suggestion is recorded for the workflow-sites follow-up, not built here

  • span=825b7ad03104 — accepted-and-deferred

Agreed, and recorded for the follow-up rather than done now. There is exactly one
caller today, so hoisting _spawn_mcp_notice in this PR would create a shared
home with a single occupant and no second shape to test it against -- the wrong
moment to fix an interface.
The rule that must not be re-authored is written down where the second author
will look: docs/system-specs/modules/acp-client.md now states why the
model-facing call drops the reasons and fences the names, so the follow-up
inherits the contract even before it inherits the code.
No issue filed: the deferral this belongs to is the workflow-sites one, already
named in the PR description (workflows/agent_exec.py,
workflows/agent_pool.py twice, workflows/service.py), and a second tracker
for the refactor that lands with it would be an issue about how to write a change
nobody has started.

@chenmingwei23
chenmingwei23 merged commit c20afd9 into main Sep 20, 2026
96 of 104 checks passed
@chenmingwei23
chenmingwei23 deleted the fix/subagent-mcp-report-visibility branch September 20, 2026 08:25
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 20, 2026

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

Approved: fix-class. The thing I checked hardest is the prompt-injection surface, because this PR puts config-derived text into a model prompt — and it is handled correctly: the failure REASONS (which can carry remote content in the OAuth/network cases) go to the log only, while the prompt gets names only, fenced behind a per-spawn secrets.token_hex tag with an explicit untrusted-data instruction, so a declared name can neither read as a directive nor close a predictable fence. Tests cover a hostile name and a reason carrying a directive. Verified a healthy spawn's prompt is byte-identical: _spawn_mcp_notice("") returns "" and the caller concatenates unconditionally.

One non-blocking nit for a follow-up: in _warn_unusable_mcp_servers, summary guards with report is not None while the adjacent names_only guards with truthiness (if report). Harmless today — neither McpSessionReport nor KasMcpReadiness defines __bool__/__len__, so both are always truthy — but if either ever gains a __len__, the log would fire while the prompt silently got nothing. Worth making the two spellings agree.

amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…dotdev#12176)

A sub-agent whose declared MCP server failed to start, was waiting to be
authorized, or was never configured saw neither the tools nor a reason. The
session already accumulated that answer in McpSessionReport, but every reader
was a dashboard slot, which a spawn does not have, so the run learned the tool
was missing the slow way: by searching for it until its turn budget was spent.

McpSessionReport gains problem_summary(), one line rendering the failed /
awaiting-auth / unresolved-ref buckets and empty when the session is healthy,
declared on the SessionMcpReport protocol so a consumer reaches it without an
ACP import. subagent_manager/run.py reads it once where the shared and
dedicated session arms converge, logs it for the operator, and states it in the
run's own first prompt so the run does not spend turns discovering the absence.

The prompt copy carries names only: a failure reason is the failing server's own
startup output, and no scrubber neutralizes a natural-language instruction. The
names are fenced as untrusted data behind a per-spawn random tag, so a declared
name cannot read as a directive or close the fence. Silent everywhere when the
report is clean or the provider keeps none.

Co-authored-by: Zejiang Guo <zejiangg@amazon.com>
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