Skip to content

fix: rewrite the guest spec from its template before refusing a turn - #34253

Merged
bolichen97 merged 1 commit into
mainfrom
fix/33522-guest-spec-repair
Nov 11, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/33522-guest-spec-repair

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Non-operator channel turns keep running on a host where another tool writes its own MCP server into kirocrew-guest.json, and a guest turn still never starts on a spec that mounts anything.

A tool that writes its own MCP server into every agent spec under ~/.kiro/agents/ each time it launches leaves kirocrew-guest.json mounting that server. A deny_all_tools channel turn for a non-operator sender reads the guest spec before it starts a session and refuses when it mounts anything:

deny_all_tools turn refused before spawn: the kirocrew-guest spec mounts a tool, a grant, an MCP server or a hook

Nothing puts the file back until the next rebuild, so every such turn is refused until then, and the sender reads "This account cannot answer you on its current setup. Ask its owner."

Why it matters

Everyone who admits non-operator senders on a messaging channel and runs such a tool has every one of those senders refused, and editing the file by hand does not last because the tool writes it back on its next launch. The guest spec is the trust boundary for those turns, so the fix must never let a guest turn start on a spec that mounts a tool.

Not a goal

What changed (motivation → approach → change)

The refusal is right; what was missing is a way back. kirocrew-guest.json is Kiro Crew's own file and only a rebuild re-derives it, so once another tool writes into it every non-operator turn is refused until then. The knowledge spec already has the same kind of repair before each worker spawn; this gives the guest spec one before a guest turn would be refused.

Part What it does
repair_guest_agent_spec (agent_materialization/service_agents.py) Rewrites an existing kirocrew-guest.json that is not its template and says whether it did, through the same governed writer the installer uses, with a WARNING that names the differing keys and never their values. A missing file stays missing, and a data home that does not own the agents directory leaves the file alone. The installer and the repair build the spec from one _guest_agent_config(). Exported through the kiro_crew.agent facade (agent.py).
_repair_toolless_spec (messaging/dispatch_tools.py), called by ChannelTurns (messaging/dispatch.py) When the read before the spawn finds the guest spec mounting something, runs the repair, and after a rewrite resets every live session bound to the guest agent: a guest process can still mount the injected server after the file reads clean, because kiro-cli applies a reload only at a turn boundary and not on every version. Then it reads the spec again, and that read decides: a spec that still mounts something is refused before the spawn as before. A turn whose session starts while a repair runs, which the resets may not reach, is refused: _refuse_unless_toolless confirms a spawn only when no repair started since the read that vouched for it and none is still running. The repair outlives a cancelled turn, and each reset is bounded; a guest process a reset (the repair's or a refusal's) did not finish taking out stays refused until a reset of its session returns.
_spec_drift Takes the hardened reader's operation label from its caller, so the guest read is logged as guest_spec_repair.

docs/system-specs/modules/messaging.md and src/kiro_crew/docs/agent-spec-fields.md describe the repair.

Backwards compatibility

Compatible: a guest spec that mounts nothing is neither rewritten nor read a second time, and a spec the repair cannot restore is refused exactly as on main. While a repair runs, a guest turn that overlaps it is refused once, one running on a session the repair resets ends, and one on a process a reset could not take out is refused until a reset of its session returns.

Removes nothing: the rebuild already rewrites kirocrew-guest.json from this same template; this rewrites it once more, only when a non-operator turn would otherwise be refused.

Tests

  • test/test_messaging_dispatch.py, TestToollessTurnReadsTheGuestSpecOnDisk:
    • test_an_injected_server_is_rewritten_away_and_the_guest_sessions_reset: the issue's injected tools, allowedTools, mcpServers and permissions are rewritten back to the template, the WARNING names mcpServers and not the server's env value, both live guest sessions are reset on the restored file and the operator's is not, and the turn passes the read after its start.
    • test_a_hung_reset_does_not_hold_the_repair: a reset that never returns is abandoned after its bound and the repair finishes.
    • test_a_session_whose_reset_failed_stays_unconfirmed: after a reset abandoned before it took the session out, that same process is refused and reset, and a fresh process for the key runs.
    • test_a_refusal_whose_reset_fails_keeps_the_process_refused: when a refusal's own reset raises, the next turn on that process is refused although the file and the counts read clean, until a reset returns.
    • test_a_cancelled_turn_still_finishes_its_repair: cancelling the turn that started a repair leaves the repair running until every guest session is reset.
    • test_the_read_after_the_rewrite_still_decides: a rewrite the file does not keep is refused before the spawn.
    • test_a_missing_guest_spec_is_not_created: another spec claiming the name with no kirocrew-guest.json is refused, no second claimant is written, and no session is reset.
  • test/test_channel_turns.py, TestAToolLessGuestTurn:
    • test_a_spec_the_repair_restores_runs_the_turn: a failed pre-spawn read goes to the repair, and the turn is answered when the repair's read passes.
    • test_a_spec_the_pre_spawn_read_refuses_never_starts_a_session: when the repair cannot restore the spec, no session starts.
    • test_a_repair_during_the_spawn_refuses_the_turn: a repair that starts while the session starts refuses the turn and resets its session.
    • test_a_repair_started_during_the_pre_spawn_read_refuses_the_turn: the repair count is read before the read that vouches for the spawn.
    • test_a_repair_still_running_refuses_the_turn: a repair that has not finished its resets refuses the turn and resets its session.
  • test/test_agent_spec_hardened_reads.py: the strict reader's call site in service_agents.py takes its operation label from its caller.

Determinism: the twelve new or changed tests passed 20 runs at -n0, 10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test/test_channel_turns_drive_turn.py and test/test_channel_turns_discord_leg.py, and one run in a shuffled order (seed 30966).

Proof: PROVEN test/test_agent_spec_hardened_reads.py::TestCallSiteLabelRatchet::test_every_call_site_carries_the_expected_label[read_agent_spec_strict], test/test_channel_turns.py::TestAToolLessGuestTurn::test_a_repair_during_the_spawn_refuses_the_turn (head a339bb7)

Manual verification

N/A — unit coverage sufficient: the rewrite and the second read run against a real spec file in an isolated agents directory, and the resets and the refusal of overlapping turns run through the channel pipeline with its session fakes.

Related Issues

Closes #33522

#33965 makes the same _spec_drift change for kirocrew-lite.json. The two land in either order; the second rebases to resolve one comment in test/test_agent_spec_hardened_reads.py and the sentence in src/kiro_crew/docs/agent-spec-fields.md that says the guest spec is not repaired.

Sibling sweep

Swept: git grep -nE "authored_spec_is_toolless|authored_spec_toolless_verdict|repair_[a-z]+_agent_spec" -- src/
Sibling: src/kiro_crew/messaging/dispatch_tools.py -- changed here
Sibling: src/kiro_crew/llm_helpers_parts/background_turns.py -- tracked in #33345
Sibling: src/kiro_crew/knowledge/llm_pool.py -- not affected -- it already rewrites kirocrew-knowledge.json before each worker spawn

Pattern harvest

Not generalizable: each of Kiro Crew's own tool-less specs has one pre-spawn reader, and the one not covered here is tracked in #33345.

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 10, 2026 01:01
@bolichen97
bolichen97 enabled auto-merge (squash) November 10, 2026 01:17
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 10, 2026
@bolichen97
bolichen97 force-pushed the fix/33522-guest-spec-repair branch from 203aa6d to 6cf6029 Compare November 10, 2026 13:24
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of a339bb749cfe412b787dc0b6e7c55b04ba5b9508 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a339bb7

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a339bb749cfe412b787dc0b6e7c55b04ba5b9508 false-positive: <reason, 20 to 500 characters>

@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 Nov 10, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision a339bb749cfe412b787dc0b6e7c55b04ba5b9508 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of a339bb749cfe412b787dc0b6e7c55b04ba5b9508 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the repair only fixes Kiro Crew's own file, and the second read still decides whether the turn runs, so the trust boundary holds.

Notes

  • If the injecting tool rewrites kirocrew-guest.json often, every refused guest turn rewrites the file and resets every live guest session, which can cut off other senders' turns while they are running. A short debounce, or logging how often the repair repeats, would make that churn visible. It can be reverted cleanly if it shows up.
  • The repair is coordinated across turns by five module-level counters and maps in dispatch_tools.py. Putting them behind one small state object would make the "confirmed only when no repair started or is running" rule easier to check later. That would be a follow-up, not something this PR needs.

[DESIGN-REVIEWED] a339bb7

Description read

[DESCRIPTION-READ] 72993d944c660fbb76e937a0ca56f5794565e47e84560076500af9197f0f9037

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 Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] a339bb7

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable a339bb749cfe412b787dc0b6e7c55b04ba5b9508 false-positive: <reason, 20 to 500 characters>

@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 Nov 10, 2026
A tool that writes its own MCP server into every agent spec under the
kiro agents directory leaves kirocrew-guest.json mounting that server,
and a deny_all_tools channel turn refuses before its spawn on a guest
spec that mounts anything. Only a rebuild put the file back, so every
non-operator turn was refused until then.

When the pre-spawn read refuses, the channel pipeline now rewrites an
existing kirocrew-guest.json that is not its template through the same
governed writer the installer uses, resets every live session bound to
the guest agent, and reads the spec again; that second read decides.
A live guest process may still mount the injected server after the
file reads clean, since kiro-cli applies a reload only at a turn
boundary and not on every version. A turn whose
spawn overlaps a repair, which the resets may not reach, is refused:
the count of started repairs is read before the vouching read and the
read after the start confirms only when no repair started since and
none is running. Each reset is bounded so a hung teardown cannot keep
every guest turn refused. A missing file is not created. _spec_drift takes its
reader's operation label from the caller.

Closes #33522
@bolichen97
bolichen97 force-pushed the fix/33522-guest-spec-repair branch from 6cf6029 to a339bb7 Compare November 11, 2026 04:02
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: a guest provider whose reset did not return stays unconfirmed until a reset of its session returns

  • span=59154639fb99 Failed resets reauthorize contaminated guest runtimes

fixed in a339bb7: each guest reset, the repair's and a refusal's, records the provider before it starts and forgets it only when the reset returns, so a timed-out or raising reset leaves it recorded.
_refuse_unless_toolless refuses the recorded provider (is) and resets it again, so the restored file and the balanced repair counts no longer vouch for a process a reset did not take out; a fresh provider for the key is a different object and runs.
Tests: test_a_session_whose_reset_failed_stays_unconfirmed (repair reset abandoned at the bound) and test_a_refusal_whose_reset_fails_keeps_the_process_refused (refusal reset raising).
[operator: bolichen97]

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own.

The PR adds a repair of kirocrew-guest.json, run when the pre-spawn read would refuse a non-operator turn. It rewrites the file through the installer's governed writer and is modelled on the existing knowledge-spec repair. A missing file is not created and a shared agents home is left alone. The repair then resets every live guest session, and a second read still decides whether the turn runs. Turns that overlap a repair are refused rather than vouched for: the repair count is read before the vouching read, a repair still in flight refuses, and a provider whose reset did not finish stays refused (_guest_resets_failed). That tracking addresses the GPT lane's finding on an earlier head. _refuse_unless_toolless has one production caller, updated here, and SessionManager provides session_keys, get_provider and get_agent. Every new branch has a test, and the docs were updated in the same change. No regression or fail-open path found; the remaining edge cases are minor.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit a339bb749c · 546 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of a339bb749cfe412b787dc0b6e7c55b04ba5b9508 — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks. The repair sits at mechanism level for a cause outside the repo (another tool writing into every spec), and the lite-spec sibling is declared in #33965.

Notes

  • Item 4 — undeclared: ## Not a goal says "Changing the check after the session starts", yet _refuse_unless_toolless gains four new refusal conditions (_guest_spec_repairs_started != repairs_before_spawn … or _guest_resets_failed.get(session_key) is provider). They only tighten that check, and only because of the repair, but the stated Goal says that check is not touched.

What this change ships

Inventory (8 items) — 7 justified

Intent: non-operator channel senders keep getting answers after another tool injects an MCP server into kirocrew-guest.json, and the guest turn stays tool-less. This is a FIX.

  1. A guest turn refused because the guest spec drifted now rewrites the spec from its template, reads it again, and runs only if that second read passes — justified
  2. After a rewrite, every live guest session is reset, with each reset given up after 30s — justified
  3. A guest turn that overlaps a running repair is refused and its session is reset — justified
  4. A guest process whose reset failed (the repair's or a refusal's) stays refused until a reset returns — undeclared: contradicts "Not a goal: changing the check after start"
  5. A WARNING log names the top-level keys that differed, never their values — justified
  6. A missing guest spec is still not created — justified
  7. repair_guest_agent_spec is exported from the kiro_crew.agent facade (1 consumer: dispatch_tools.py) — justified
  8. The guest drift read is logged under its own guest_spec_repair operation label — justified

[FIRST-PRINCIPLES-REVIEWED] a339bb7

Description read

[DESCRIPTION-READ] eebc5ceae33266b541e8bf3d334a5ce36b3bf4d8a702356e5680c94853f885e7

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 added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 11, 2026

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

Approve on a339bb7. The GPT 6.1 security BLOCK from 6cf6029 (dispatch_tools.py:287, a timed-out guest reset still let the repaired file vouch for the old runtime) is fixed: a provider whose reset did not return stays refused and is reset again on its next turn; the guard is fail-closed and every new branch is mutation-tested. Decisive lines: src/kiro_crew/messaging/dispatch_tools.py:283-295 (repair reset records the provider before the reset, forgets it only when the reset returns); src/kiro_crew/messaging/dispatch_tools.py:401 (_guest_resets_failed.get(session_key) is provider refuses a process a reset did not take out); src/kiro_crew/messaging/dispatch_tools.py:410-420 (a refusal's own reset is recorded the same way)

@bolichen97
bolichen97 merged commit 387ea66 into main Nov 11, 2026
100 of 108 checks passed
@bolichen97
bolichen97 deleted the fix/33522-guest-spec-repair branch November 11, 2026 09:30
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 11, 2026
bolichen97 added a commit that referenced this pull request Nov 13, 2026
…ox tool (#33345) (#36777)

* fix: rewrite the guest spec from its template before refusing a turn (#34253)

A tool that writes its own MCP server into every agent spec under the
kiro agents directory leaves kirocrew-guest.json mounting that server,
and a deny_all_tools channel turn refuses before its spawn on a guest
spec that mounts anything. Only a rebuild put the file back, so every
non-operator turn was refused until then.

When the pre-spawn read refuses, the channel pipeline now rewrites an
existing kirocrew-guest.json that is not its template through the same
governed writer the installer uses, resets every live session bound to
the guest agent, and reads the spec again; that second read decides.
A live guest process may still mount the injected server after the
file reads clean, since kiro-cli applies a reload only at a turn
boundary and not on every version. A turn whose
spawn overlaps a repair, which the resets may not reach, is refused:
the count of started repairs is read before the vouching read and the
read after the start confirms only when no repair started since and
none is running. Each reset is bounded so a hung teardown cannot keep
every guest turn refused. A missing file is not created. _spec_drift takes its
reader's operation label from the caller.

Closes #33522

(cherry picked from commit 387ea66)

* fix: rewrite the lite spec from its template before refusing a turn (#33965)

A tool that writes its own MCP server into every agent spec under the
agents directory leaves kirocrew-lite.json mounting a server. The
background helper correctly refuses to start a session on such a spec,
but nothing put the file back before the next rebuild, so every
background turn, history consolidation included, was refused.

Before refusing, the helper now rewrites an existing kirocrew-lite.json
that is not its template, through the same governed writer the
installer uses, and reads the spec again. That second read still
decides; a spec that still mounts something is refused as before, and
a missing file is never created. The rewrite and the session resets
after it run through the same code the guest spec repair uses, so each
reset is bounded and one hung teardown cannot hold background turns.

A session that started before the rewrite may have loaded the old
file, so only the read before the rewrite vouches for a session, and
not while a rewrite runs. A rewrite resets the _bg and _consolidate
sessions, the two that outlive a turn and can start without the
pre-spawn read, the turn's own included, and those resets finish even
when the turn is cancelled. On a backend with no prepared projection,
which cannot tell such a session from a new one, the turn that rewrote
the file is refused and its own session reset, and so is a turn whose
pre-spawn read overlapped a rewrite. A _bg start still in flight when
the rewrite resets _bg is shut down instead of registered, so no later
turn can take a session that loaded the old file. The next turn starts
on the rewritten file.

Closes #33345

(cherry picked from commit ca95636)

* fix: release the stale consolidation backoff once a turn is answered (#36632)

A history consolidation that never reaches a provider (kiro-cli
missing, or the lite spec refused before its session starts, as in
#33345) arms the session's environment backoff, and that wait widens
to a day. Nothing released it when the host recovered, so after the
#33965 fix landed every session refused meanwhile still sat out up to
24 hours before consolidating.

The first consolidation turn a provider answers after a process start,
after the startup scan adds sessions, or after any environment failure
now releases the environment backoff of every tracked session. A turn
that raised releases nothing. Each session is released once until it
next consolidates and keeps its failure count, so a session whose
failure is its own resumes widening to the ceiling. A session with a
billed attempt on its current span keeps its wait, and nothing is
marked consolidated.

Part of #33345

(cherry picked from commit 0e5b203)
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.

Non-operator channel turns stay refused when another tool injects a server into kirocrew-guest.json

3 participants