Repository navigation
fix(subagent): report MCP servers that failed to start at spawn - #12176
Conversation
|
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. |
Design Review (Fable 5) — ✅ PASSDesign-level review of 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
[DESIGN-REVIEWED] af9876f |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of 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 shipsInventory (7 items) — 7 justifiedIntent: 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
The boundary-gate rationale for the protocol method is real ( [FIRST-PRINCIPLES-REVIEWED] af9876f |
7111cbb to
231e910
Compare
|
self-added: no
|
|
self-added: no
|
|
self-added: no
|
|
self-added: yes
|
231e910 to
0658ce1
Compare
|
self-added: yes
|
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
0658ce1 to
d117fa7
Compare
|
Rebased: main moved in |
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.
d117fa7 to
af9876f
Compare
GPT 5.6 Review —
|
GPT 5.6 Review —
|
|
self-added: no
|
bolichen97
left a comment
There was a problem hiding this comment.
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.
…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>
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.
failed to start: <server> (<reason>)awaiting authorization: <server>declared by the agent spec but not configured: <ref>The fact was already collected.
src/kiro_crew/acp/mcp_session_report.pybucketsevery 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 bucketsand empty when the session is healthy. It is a method on the report, declared on
the
SessionMcpReportprotocol insrc/kiro_crew/providers/base.py, because aconsumer 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.pyreads it once, right after it captures thenew 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.mdgains the contract: what the one-linerenderer 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) andsrc/kiro_crew/workflows/service.py— still read no report and stay silent. Theycompose 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 withits 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
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)