Skip to content

fix: keep user allowedTools entries when conductor specs regenerate - #15718

Merged
bolichen97 merged 1 commit into
mainfrom
fix/allowed-tools-survive-regeneration
Oct 6, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/allowed-tools-survive-regeneration

Conversation

@pepmach

@pepmach pepmach commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A tool you approved on a conductor agent stays approved after the gateway restarts, instead of prompting again.

Reporter (#15567): on spec regeneration the allowedTools list is overwritten and resets to the base entries, so every tool the user had approved starts prompting again; toolsSettings keys survive, allowedTools does not; the reset is silent. The maintainer's triage found that kirocrew.json keeps the user's list on an existing install and named the writers that replace the list as the candidates. Reading main (321fd996a2) confirms the first candidate: the four conductor spec installers (_conductor_spec for kirocrew-conductor and its kirocrew-ledger-conductor alias, _install_pipeline_conductor_agent, _install_security_conductor_agent) set allowedTools from their grant tuple and _atomic_json_write the file without reading it, and rebuild_agent_config runs them on every gateway start (slack/gateway.py boot), on a provider switch and on the background-model change (dashboard/server.py), on every dashboard MCP add/remove (handlers/mcp_custom.py), on onboarding import, on kirocrew doctor and on MCP launch resolution. toolsSettings survives on those specs because the installer starts from the template and never touches that key, which is exactly the asymmetry the reporter describes.

Why it matters

Anyone who approves tools on a conductor spec (by hand or through a prompt that writes the spec) loses every approval at the next gateway start, with nothing in the log saying so, and re-approves them one prompt at a time, or keeps a backup of the list and re-applies it after each start. For an unattended conductor, a tool that prompts is a patrol cycle that stalls.

Not a goal

  • Preserving a user's tools (mount list), mcpServers or any other field on a conductor spec. The conductor's mount list is its charter (no file-writing tool); this PR carries forward the auto-approve list only, which is what the report is about.
  • Changing which grants Crew ships on any conductor, or what the governance ceiling permits. The shipped tuples are untouched and every entry, shipped or the user's, still passes _filter_auto_approve.
  • The other generated specs (kirocrew-knowledge, -research, -heartbeat, -guest, -lite) and the worker mirror. Named in the pattern harvest below, not changed here.
  • Re-merging ~/.kiro/crew/agent.json overrides onto an existing spec, or any change to how kirocrew.json itself is rebuilt: its existing-config path already keeps the user's list.

What changed (motivation → approach → change)

Symptom: a user's allowedTools entry on a conductor spec is gone at the next start. Root cause: the installers build allowedTools from a grant tuple without reading the file.

Approach. An add-only merge would resurrect a grant the shipped set dropped (#8660 narrowed a bare @kirocrew-core to named verbs), since nothing on disk says whose an entry is. The provenance is the per-spec history of every grant any release shipped:

  • agent_materialization/conductor_agents.py: _SHIPPED_GRANT_HISTORY, a literal per-spec table (pinned by test; provenance below). _governed_grants reads the spec it replaces through read_agent_spec_strict (behind the link-shape fence): an entry the history names is Crew's, kept exactly when this release ships it; one no release shipped is the user's, carried after the shipped tuple, all through _filter_auto_approve; clean keeps nothing. Every drop is named in one WARNING; one the ceiling did not make is also a SEL mcp_auto_approve_revoked; a user's entry carried forward is a SEL mcp_auto_approve_retained. An unreadable spec follows the reader's two classes (_SpecUnusable): bytes that can never be a spec, a planted link, or a second hard link are written over — kiro-cli could not load the first two and WOULD load the third while the hardened reader refuses it for good; the write swaps the directory entry, the other name keeps its bytes. A transient read failure, or a failed metadata probe, is retried three times (50/100 ms) before the file is left in place and the installer returns False. A user's wildcard (*, fs_*, session_*, @*) is never carried: the gate judges exact names, so the pattern would pass it while kiro-cli expands it over every builtin and every mounted MCP verb — and a server's verbs cannot be enumerated at write time, so no expansion can judge it; dropped before the merge, the warning says to name tools exactly. A pattern is not an entry the user named, so the Goal stands as written.
  • agent.py: rebuild_agent_config passes clean through and reports a conductor hold — a spec left in place, or an installer whose write raised — through a private _held_out beside _wrote_out, which stays the guard's verdict the dashboard reads; the ceiling hook holds its memo on a refusal OR a hold, and prime_ceiling_projection seeds no baseline while the last rebuild held (_conductor_spec_held), so the first poll retries a spec held at boot; a host with no distribution poll retries it from the gateway's hourly maintenance wake (retry_held_conductor_specs, slack/gateway.py).
  • Docs, same commit: src/kiro_crew/docs/agent-spec-fields.md, docs/system-specs/modules/pipeline-conductor.md, governance.md.

Why the history and not a per-install record. A record in a second store can describe another release's file, be torn, or be hand-damaged (rounds 2-4 found one edge each); the history holds for any file at the spec's name. An in-spec stamp is impossible: kiro-cli validates with deny_unknown_fields. The one cost: a retired grant Crew once shipped, hand-re-added, reads as Crew's and is dropped at the next start — named, audited, the tool asks instead (fails closed). Residual: a NEWER release's grant reads as the user's after a downgrade.

Caveat: the reporter named kirocrew.json, which already keeps its list on main; if that is their file the trigger is a --clean rebuild or a moved ceiling, unchanged here.

Backwards compatibility

Compatible: nothing main accepts is rejected, renamed or removed. The four installers gain a keyword-only clean: bool = False and return bool instead of None (every existing call still works; rebuild_agent_config is their only caller). No sidecar change. A spec written before this change is read, not refused: on its first rebuild the user's entries on it survive and any grant that release shipped and this one does not is dropped. The spec bytes a rebuild writes are unchanged for a user who added nothing (test_agent_refactor_spec_bytes.py is untouched: every file, audit-event and sidecar state digest matches main). Two deliberate behaviour changes against main: a spec written by a release before this one keeps the user's entries on its first rebuild (main dropped them at every start), and a conductor spec on disk that cannot be read for a transient reason is left in place with the ceiling memo held (main rewrote it); a spec whose bytes can never be a spec, or one carrying a second hard link, is rewritten as on main, now with a warning naming the cause. rebuild_agent_config_reporting keeps its (path, wrote) shape and main's meaning of wrote (the shared-home guard's verdict); the _held_out keyword on it and on rebuild_agent_config is private and optional, read by the ceiling hook alone. One more against main: the ceiling baseline boot seeds stays unseeded when the boot rebuild held a conductor spec (main always seeded it), which costs one rebuild on the first poll; and the gateway's hourly maintenance wake (the existing scratch/work-root sweep loop) now also retries a conductor spec the last rebuild held, a no-op on a host whose specs are all written (main had no hold to retry). A transient read failure is retried three times, 50 ms and 100 ms apart, before the hold — at most 150 ms added to a boot whose spec cannot be read at all. A wildcard entry of the user's on a conductor spec is never carried forward (main carried nothing of the user's, so this changes nothing against main; against the round-7 to round-9 heads it drops the patterns those kept). _spec_path_is_safe keeps its signature and its answers; the reason-returning _spec_path_shape_refusal behind it is new and private.

Tests

New: test/test_conductor_allowed_tools_survive.py (157 tests, parametrized over the three installers plus the ledger alias and the real rebuild; the rig's ceiling stub is the real gate with no ceiling — may_skip_gate(ref, None) — so the always-on floor applies as on a real host, and the user's grant in the fixtures is web_fetch):

  • a user-added grant survives one and two regenerations; shipped grants stay, in shipped order, first; the installers return True when they wrote;
  • a shipped grant the user deleted comes back; a shipped grant the ceiling withheld returns when the ceiling allows it again, beside the user's entry;
  • a ceiling-forbidden user grant is removed, the tool stays mounted, and one warning names it;
  • a spec an earlier release wrote, carrying the grant that release shipped and this one does not — the bare @kirocrew-core on the goal conductor, @kirocrew-work/work_ledger_read on the pipeline conductor — loses it, named in the warning and SEL-audited as mcp_auto_approve_revoked, while the user's entry beside it stays; on the security conductor, which has retired nothing, the user's entry simply stays and nothing is logged;
  • every grant an installer writes is in _SHIPPED_GRANT_HISTORY, and so is every grant of the CURRENT shipped tuple as the installer hands it to _governed_grants, before the ceiling (current ⊆ history, the pin that keeps the literal history from falling behind and lets a retirement need no step); a third test proves the pin bites by taking one shipped grant out of the history and watching the subset check fail; the ledger alias is pinned under its own history entry;
  • the one cost, pinned: a hand-added grant Crew once shipped and has since retired is dropped, named and audited; the same grant on a spec that never shipped it is the user's and stays;
  • a user's wildcard is never carried forward, whatever it would reach — *, fs_*, execute_?ash, [ef]*, web_*, *fetch*, session_*, *_send, @*, @kirocrew-*, @other-server/do_* — on any of the three conductors: the shipped grants and a plain user entry beside it survive, one warning names the pattern and the remedy ("cannot be judged against the gate ... name tools exactly"), and the SEL feed records the revocation as a wildcard and never as retained; under a ceiling whose mcp rules withhold @kirocrew-dashboard/session_send by name (modelled as the gate's answer for every ref on that server), session_*, *_send, @* and *fetch* go while every exact @kirocrew-dashboard grant is withheld as before and the user's exact entry stays; an exact @other-server, @other-server/do_this or web_search is the user's and stays with nothing logged; and the module keeps no governed-builtin table and no expansion (_is_wildcard is the whole rule);
  • a read that fails once with a transient error is retried after one declared pause and the same install writes, carries the user's entry and warns about nothing; a read that keeps failing is held after exactly three attempts with the declared pauses, the bytes untouched, the warning naming "3 reads failed"; a hard-link shape is written over with no pause;
  • through the real rebuild on a host that polls no distribution (start_refresher() is False): a pipeline-conductor spec held at boot leaves the baseline unseeded, retry_held_conductor_specs() returns False and keeps the hold while the read still fails (warning "still unwritten"), rewrites the spec and clears the memo once it can be read, and runs no rebuild at all when nothing is held; the gateway source is pinned to call it first in the hourly maintenance wake, once, after the sleep and before the scratch sweep;
  • a work verb no release ever shipped on the spec — work_report on the goal and pipeline conductors (the worker's verb), work_brief on the pipeline conductor — is the user's and survives with nothing logged; and the history's residue beyond each spec's current tuple is pinned to exactly the verified retirements (@kirocrew-core on the goal conductor; work_ledger_read / work_ledger_record on the pipeline conductor; nothing on the ledger alias and the security conductor), so an entry can join the table only as a grant some release is shown to have shipped;
  • a retained user entry is audited once per regeneration as mcp_auto_approve_retained, naming the entry and the spec and never a shipped or retired grant; no event when the user added nothing; a SEL that raises costs the audit line, not the spec;
  • nothing is logged when nothing is dropped; clean=True resets the list; a non-string entry on disk is neither kept nor reported; the derived KAS permissions follow the merged list; deleting a shipped grant by hand brings it back and keeps the user's entry;
  • bytes that can never be a spec — malformed JSON, a non-object document, an allowedTools that is not a list, a file past the read cap — are written over with a loadable spec, the installer returns True, and one warning says "could not be read ... written afresh";
  • a read that may succeed later — a transient EIO from the pinned read — leaves the bytes on disk untouched, the installer returns False, one warning says "could not be read ... left in place" and names --clean as the way out, and once the read succeeds the user's entry on it is carried forward;
  • a metadata probe that fails before any byte is read — ESTALE from the no-follow os.stat the link-shape fence performs, for the spec path alone — leaves the bytes on disk identical, the installer returns False, one warning says the metadata could not be read and carries the error, and _spec_path_is_safe still answers False to the same failure; the next install carries the entry forward;
  • a second hard link on the spec's inode, carrying a user entry and a grant the ceiling now denies: the spec is written afresh, the installer returns True, the denied grant is gone from the file kiro-cli loads, the unreadable user entry is named as not carried, the managed path is a fresh single-link inode, the other name keeps its bytes byte-for-byte, and one warning names the hard link (skipped where hard links are unavailable);
  • clean=True still rebuilds a broken file; a symlink planted at the spec's name is replaced by a regular file, nothing behind it is carried, the warning says "written afresh", and the target is untouched (skipped where symlinks need a privilege);
  • the ledger alias keeps its own entries under its own name and leaves the goal conductor's file alone;
  • through the REAL rebuild_agent_config under a relocated home whose agents directory reads as shared: a pipeline-conductor spec left in place is reported as a hold (_held_out == [True]) while wrote stays True on the bare call the dashboard makes, the other specs are still rewritten, and the hold clears once the read does; a security-conductor installer whose write raises (_atomic_json_write → EACCES) leaves the previous bytes, reports the hold, and the real reproject_for_ceiling_change leaves its memo pending and logs the once-per-generation warning naming "read or written"; the hook advances only when the rebuild wrote AND held nothing (refusal, hold, then clean, through a reporting fake); a spec written over holds nothing.
  • the boot path, through the same real rebuild: a pipeline-conductor spec held at boot (carrying a grant the rewrite drops) leaves prime_ceiling_projection with an unseeded baseline and one warning; the first poll's hook rebuilds, still holds, and leaves the memo behind with the grant on disk; once the read clears the next poll rewrites the spec and the memo advances to the current generation; a boot whose rebuild held nothing seeds the baseline as before. test_governance_distribution.py's hook class gains an autouse reset of the hold memo so its seeded-baseline pins cannot inherit a hold from another test in the process.

Red-first on main 321fd996a2 (python3 -m pytest test/test_conductor_allowed_tools_survive.py -n0 -q), before any source change:

FAILED test/test_conductor_allowed_tools_survive.py::TestUserGrantsSurviveRegeneration::test_a_user_added_grant_survives_and_the_shipped_grants_stay[conductor] - AssertionError: assert ['session', '...ge_stop', ...] == ['session', '...ge...
FAILED test/test_conductor_allowed_tools_survive.py::TestUserGrantsSurviveRegeneration::test_a_user_added_grant_survives_and_the_shipped_grants_stay[pipeline] - AssertionError: assert ['session', '...ge_stop', ...] == ['session', '...ge...
FAILED test/test_conductor_allowed_tools_survive.py::TestUserGrantsSurviveRegeneration::test_a_user_added_grant_survives_and_the_shipped_grants_stay[security] - AssertionError: assert ['session', '...ge_stop', ...] == ['session', '...ge...
FAILED test/test_conductor_allowed_tools_survive.py::TestUserGrantsSurviveRegeneration::test_a_ceiling_forbidden_user_grant_is_removed_and_named[conductor] - AssertionError: expected ONE line naming the drop, got []
FAILED test/test_conductor_allowed_tools_survive.py::TestUserGrantsSurviveRegeneration::test_a_grant_a_release_stopped_shipping_is_dropped[conductor] - AttributeError: module 'kiro_crew.agent_state' has no attribute 'set_shippe...
FAILED test/test_conductor_allowed_tools_survive.py::TestUserGrantsSurviveRegeneration::test_a_clean_install_resets_the_list[conductor] - TypeError: _install_conductor_agent() got an unexpected keyword argument 'c...
=================== 33 failed, 6 passed, 2 warnings in 3.55s ===================

(The six that passed on main are the behaviours a wholesale rewrite already had: a deleted shipped grant comes back, and nothing is logged when nothing is dropped.)

Red-first for round 4 on this PR's previous head 10a258248e (the round-4 test file copied into a detached checkout of that commit), each red on its behaviour:

FAILED ...::test_a_user_entry_crew_once_shipped_reads_as_crews_and_goes[conductor] - AssertionError: assert True is ('@kirocrew-core' is None)
FAILED ...::test_a_user_entry_crew_once_shipped_reads_as_crews_and_goes[pipeline] - AssertionError: assert True is ('@kirocrew-work/work_report' is None)
FAILED ...::test_a_retained_user_entry_is_audited[conductor] - assert 0 == 1
FAILED ...::test_the_rebuild_reports_wrote_false_while_a_conductor_spec_is_left_in_place - AssertionError: a spec left unwritten must hold the ceiling memo
FAILED ...::test_a_spec_written_over_does_not_hold_the_memo - AssertionError: assert (False)   # the damaged allowedTools was left in place while the rebuild reported wrote=True
FAILED ...::test_bytes_that_can_never_be_a_spec_are_written_over_and_named[not-an-object-conductor] - TypeError: list indices must be integers or slices, not str
FAILED ...::test_bytes_that_can_never_be_a_spec_are_written_over_and_named[over-the-read-cap-conductor] - AssertionError: assert 'fs_read' not in ['session', 'report', ...

(Each case repeats for pipeline and security; the reds that were only the installers' new True/False return contract are omitted.) After the change: 79 passed.

Red-first for round 5 on this PR's previous head d80ed99504 (the round-5 test file in a detached checkout of that commit), each red on its behaviour:

FAILED ...::test_a_second_hard_link_is_written_afresh_and_the_ceiling_reaches_the_spec[conductor] - AssertionError: the ceiling did not reach the spec
FAILED ...::test_a_second_hard_link_is_written_afresh_and_the_ceiling_reaches_the_spec[pipeline] - AssertionError: the ceiling did not reach the spec
FAILED ...::test_a_second_hard_link_is_written_afresh_and_the_ceiling_reaches_the_spec[security] - AssertionError: the ceiling did not reach the spec
FAILED ...::test_a_conductor_spec_left_in_place_is_a_hold_and_not_a_refusal - TypeError: rebuild_agent_config_reporting() got an unexpected keyword argument '_held_out'
FAILED ...::test_an_installer_whose_write_raises_holds_the_memo - TypeError: rebuild_agent_config_reporting() got an unexpected keyword argument '_held_out'
FAILED ...::test_the_hook_advances_only_when_the_rebuild_wrote_and_held_nothing - KeyError: '_held_out'
# the memo tests above fail on the new keyword before their assertions; the same two behaviours probed with the old API alone, in the same checkout:
FAILED test_r5_probe.py::test_opus_a_held_spec_is_reported_as_a_refusal_to_the_dashboard - AssertionError: kirocrew.json was written; a held conductor spec was reported as a refusal
FAILED test_r5_probe.py::test_f2_an_installer_whose_write_raises_advances_the_memo - AssertionError: the memo advanced over a conductor spec whose write raised

After the change: 81 passed (the probe file is scratch only and is not in this PR).

Red-first for round 6 on this PR's previous head cfefc8fae4 (the round-6 test file in a detached checkout of that commit), each red on its behaviour:

FAILED ...::test_a_work_verb_no_release_shipped_on_this_spec_is_the_users[conductor-work_report] - AssertionError: a grant no release shipped here was read as Crew's and dropped
FAILED ...::test_a_work_verb_no_release_shipped_on_this_spec_is_the_users[pipeline-work_report] - AssertionError: a grant no release shipped here was read as Crew's and dropped
FAILED ...::test_a_work_verb_no_release_shipped_on_this_spec_is_the_users[pipeline-work_brief] - AssertionError: a grant no release shipped here was read as Crew's and dropped
FAILED ...::test_the_history_beyond_the_current_tuple_is_exactly_the_verified_retirements[conductor] - AssertionError: kirocrew-conductor: the history names ['@kirocrew-work/work_report'] beyond the current tuple without a verified retirement behind it
FAILED ...::test_the_history_beyond_the_current_tuple_is_exactly_the_verified_retirements[pipeline] - AssertionError: kirocrew-pipeline-conductor: the history names ['@kirocrew-work/work_brief', '@kirocrew-work/work_report'] beyond the current tuple without a verified retirement behind it

After the change: 88 passed.

Red-first for round 7 on this PR's previous head 18f7c3bf9e (the round-7 test file in a detached checkout of that commit): the twelve floor-reaching cases (star, fs-glob, single-char, char-class × conductor / pipeline / security) each red on AssertionError: a wildcard reaching the floor was carried forward; the nine no-floor cases pass on both heads, as they should.

FAILED ...::test_a_wildcard_reaching_a_floor_gated_tool_is_not_carried[star-conductor] - AssertionError: a wildcard reaching the floor was carried forward
FAILED ...::test_a_wildcard_reaching_a_floor_gated_tool_is_not_carried[fs-glob-conductor] - AssertionError: a wildcard reaching the floor was carried forward
FAILED ...::test_a_wildcard_reaching_a_floor_gated_tool_is_not_carried[single-char-conductor] - AssertionError: a wildcard reaching the floor was carried forward
FAILED ...::test_a_wildcard_reaching_a_floor_gated_tool_is_not_carried[char-class-conductor] - AssertionError: a wildcard reaching the floor was carried forward

After the change: 109 passed.

Red-first for round 8 on this PR's previous head 3b820f6172 (the round-8 test file in a detached checkout of that commit): seven reds, each on its behaviour — the web_* case under a network.egress ceiling on the three conductors, the failed-probe case on the three conductors, and the boot hold.

FAILED ...::test_a_wildcard_reaching_a_tool_the_ceiling_withholds_is_not_carried[conductor] - AssertionError: a wildcard reaching a ceiling-withheld tool was carried
E       assert 'web_*' not in ['session', 'report', 'tool_search', 'web_*']
FAILED ...::test_a_path_probe_that_fails_leaves_the_spec_in_place[conductor] - AssertionError: the spec was replaced on a failed path probe
FAILED ...::test_a_spec_held_at_boot_is_retried_by_the_first_poll - AssertionError: boot seeded the baseline over a conductor spec it never rewrote
E       assert 14 is None
E        +  where 14 = agent._projected_ceiling_generation

After the change: 116 passed.

Red-first for round 9 on this PR's previous head 8dd2827f64 (the round-9 test file in a detached checkout of that commit): eight reds, each on its behaviour — a read failing once held the spec on the three conductors, the hold came after one read on the three conductors, a spec held at boot on a host with no distribution poll was never retried, and the wake's wiring.

FAILED ...::test_a_read_that_fails_once_is_retried_and_the_spec_is_rewritten[conductor] - AssertionError: a read that failed once held the spec instead of retrying
FAILED ...::test_a_read_that_keeps_failing_is_held_after_the_bounded_attempts[conductor] - AssertionError: the read was attempted 1 time(s) before the hold
FAILED ...::test_a_spec_held_at_boot_is_rewritten_by_the_maintenance_wake_without_a_poll - AssertionError: nothing retries a conductor spec the boot rebuild held on a host that polls no distribution: its previous-ceiling allowedTools stand for the process lifetime
FAILED ...::test_the_hourly_maintenance_wake_retries_held_specs_before_its_sweeps - ValueError: substring not found

After the change: 124 passed.

Red-first for round 10 on this PR's previous head 5e61520293 (the round-10 test file in a detached checkout of that commit): 48 reds and 9 passes. Every pattern the round-7/8 expansion could not see was carried there (web_*, *fetch*, session_*, *_send, @*, @kirocrew-*, @other-server/do_*, on each of the three conductors), the four patterns under an MCP ceiling's effect were carried past it, the four floor patterns (*, fs_*, execute_?ash, [ef]*) were already dropped there and are red on the warning text alone, and the no-expansion pin found _GOVERNED_BUILTINS. The nine passes are the exact-entry cases, kept on both heads as intended.

FAILED ...::test_a_wildcard_is_never_carried_forward[mcp-verb-glob-conductor] - AssertionError: a wildcard was carried forward
FAILED ...::test_a_wildcard_is_never_carried_forward[every-server-conductor] - AssertionError: a wildcard was carried forward
FAILED ...::test_a_wildcard_is_never_carried_forward[network-glob-conductor] - AssertionError: a wildcard was carried forward
FAILED ...::test_a_wildcard_reaching_a_verb_the_mcp_ceiling_withholds_is_not_carried[mcp-verb-suffix-glob-conductor] - AssertionError: a wildcard was carried past the MCP ceiling
FAILED ...::test_a_wildcard_is_never_carried_forward[star-conductor] - AssertionError: assert ('*' in 'kirocrew-conductor.json: regeneration dropp...
FAILED ...::test_no_expansion_of_a_wildcard_is_attempted[conductor] - AssertionError: assert not True

After the change: 157 passed.

Updated: test/test_agent_refactor_contracts.py (the five pinned installer signatures gain clean, the four conductor installers are pinned returning bool; _conductor_spec is pinned returning dict[str, Any] | None; rebuild_agent_config and rebuild_agent_config_reporting are pinned with the _held_out keyword), test/test_agent_spec_hardened_reads.py (the strict reader's call-site ratchet registers conductor_agents.py under conductor_spec_regeneration / unknown), test/test_ledger_conductor_agent.py (the boot-installer source assertion reads the clean=clean call), test/test_governance_distribution.py (the autouse hold-memo reset above). test/test_agent_refactor_spec_bytes.py is untouched against main.

Gates run on this head, rebased onto main fa37aa54fd: check_black_formatting.py, isort, flake8, mypy on the two changed modules, scripts/docs-lint.sh, check_comment_history.py, check_harness_parity.py: all pass on this PR's lines. Targeted suites on the final tree: test_conductor_allowed_tools_survive.py, test_agent_refactor_contracts.py, test_agent_refactor_spec_bytes.py, test_agent_spec_hardened_reads.py, test_ledger_conductor_agent.py, test_agent_home_isolation.py, test_conductor_agent.py, test_pipeline_conductor_agent.py, test_security_conductor_agent.py, and the hook's and the dashboard applier's own suites test_governance_distribution.py, test_config_live.py, test_config_patch.py, and test_session_work_dir.py for the maintenance wake's wiring, run two files at a time with -n0: 1338 passed, 2 skipped. Round 1's local-gate.py related set (33,495 + 48,360 + 16,809 backend, 15,683 + 4,611 frontend, with the five host-only residuals named in round 1) stands for the unchanged files.

The seven red ci.yml jobs on the round-2 head (Backend Lint & Type Check, Backend Tests (3.12, 4/5/6) and (Windows) (4/5/6), Coverage Gate) were main d5bdff64e0's own breakage, not this diff's: src/kiro_crew/vector_memory_runtime/lessons.py:1206 named _row_stem_tokens_for_scan without importing it (from 600d4b9515, #15517) and test/test_fold_catalogue.py read a stale committed catalogue (from #15078); both were fixed on main by #15744 (d8fa6a527e). A rerun of those jobs re-executed the run's original merge commit and stayed red, which is why this head is rebased onto the healed tip instead. Backend Tests (Windows) (8) on that head was test_members_dm_thread.py::TestResumeGuards::test_concurrent_member_resume_does_not_duplicate_history, the open flake #15650, unrelated to this change. This PR touches none of those files.

Local review lanes (GPT, Opus, First Principles) were not run in either round: host memory headroom read 14.8 GB (round 1) and 14.2 GB (round 2) against the fleet's 16 GB hold line, so this pushes on the mechanical evidence above and the server lanes carry the review.

Manual verification

N/A — unit coverage sufficient: the installers are exercised end to end against a real agents directory in the new tests, including the upgrade path (an earlier release's file), the narrowing path (a retired grant on disk), the unreadable-spec paths, the ceiling, clean, and the real rebuild_agent_config for the ceiling-memo hold. No UI, no external service.

Rounds 2 and 3 (fbf6b38eaa → 084341bbc6 → 10a258248e) answered five review findings on a per-install sidecar record of the grants Crew wrote, bound to the spec by a digest of its installer-owned fields: GPT 5.6 on an unbound record restoring a retired @kirocrew-core (round 1), on a plain OSError classified as "write over" and on a lenient sidecar read folding a malformed record to "no record" (round 2); Opus 5 on an unreadable spec read as "no spec" (round 1). Each fix closed one edge of the record and the next round found another on the same span.

Round 4 (10a258248e → this head): the record is removed rather than patched a fourth time. GPT 5.6's three blocking findings on the round-3 head — a retained user entry leaving no SEL event (conductor_agents.py:417), a generation string that is not a digest read as a mismatch instead of as malformed (agent_state.py:545), and a sidecar write that failed after the spec write leaving a stale record (conductor_agents.py:476) — are answered by the shape: the history of every grant any release shipped is the provenance, there is no sidecar record, so the second and third have no code to occur in, and the first is the mcp_auto_approve_retained event. Opus 5's blocking finding (conductor_agents.py:374: the round-3 "leave it in place" rule kept a spec kiro-cli could not load either, so a conductor dispatched by name resolved to the default agent and a tightened ceiling was never re-filtered onto the list, while rebuild_agent_config still reported wrote=True and reproject_for_ceiling_change stopped retrying) is answered as it asked: bytes that can never be a spec are written over, a transient read failure leaves the file in place AND the installer reports that it did not write, and the rebuild reports that hold so the ceiling memo holds. The Design lane's watch on the same rule (a hardlink-based dotfile layout makes the hardened reader's refusal permanent, so such a spec never regenerates) was accepted in round 4 as a trade; round 5 reverses that.

Round 5 (d80ed99504 → this head). GPT 5.6's two blocking findings on the round-4 head were both real. (1) conductor_agents.py:350: a spec with a second hard link was left in place for good — the hardened reader refuses a multiply-linked inode (pinned_fs), kiro-cli does not, so the file kiro-cli loads kept auto-approvals a tightened ceiling now denies, and main's unconditional rewrite had reached it. The link count is now read from the inode's metadata before any byte and classified as a shape, like a planted link: written afresh, the user's unreadable entries named as not carried, the other name untouched because _atomic_json_write swaps the directory entry rather than writing through the inode. A transient EACCES/EIO still leaves the file in place (round 3's finding stands). (2) agent.py:3484: the four conductor installers' except Exception arms logged a raise and left the hold unset, so a failed WRITE (a read-only file, a refused os.replace) advanced the ceiling memo with no warning and no retry until the next generation; each arm now sets the hold. Opus 5's advisory on the same line was also real and is folded with it: round 4 had carried the hold in wrote=False, which dashboard/server.py reads as "the shared-home guard refused", so one persistently held conductor spec would have announced every default-model change as failed after it landed and had ConfigWatch retry it forever; the hold now travels in its own _held_out out-parameter, wrote is the guard verdict again, and only the ceiling hook reads both. Out of this PR's goal and left as it is: the knowledge, research, heartbeat and worker installers' except arms swallow a raise the same way on main today, and a raise there still advances the memo — open for a follow-up on those specs. The Design lane's watch that the history's completeness over past releases cannot be proven by test (the pin enforces current ⊆ history) is accepted as stated: the provenance table below is the human cross-check's input.

Round 6 (cfefc8fae4 → this head). GPT 5.6's one blocking finding on the round-5 head was real: the table named @kirocrew-work/work_report as Crew's on the goal and pipeline conductors, and no release has ever shipped it on a conductor — at #9152 it sat in the worker spec's tuple, which the round-2 reconstruction misread as a conductor's — so a user who hand-added it lost it at every start, the bug this change exists to fix for that one grant. Checking the rest of the table the same way (history minus each spec's current tuple, then git for what is left) found one more of the same kind: work_brief on the pipeline conductor, which only ever reached the goal conductor and the ledger alias. Both are removed; the residue beyond the current tuples is now the three verified retirements above, pinned by test so the table cannot grow a claim without a shown release behind it. The round-2 provenance paragraph is corrected in place.

Round 7 (18f7c3bf9e → this head). GPT 5.6's one blocking finding on the round-6 head was real and new: a hand-written allowedTools: ["*"] (or fs_*) on a conductor spec is in no history, so the merge this PR wrote read it as the user's and carried it, and the ceiling pass let it through — may_skip_gate refuses the floor-gated builtins (code, execute_bash, fs_read, fs_write, glob, grep) by their exact names, so a pattern misses the check and, on a host with no ceiling, is kept; kiro-cli then expands it to the tools themselves on the one path that skips the always-on PreToolUse floor. The fix is the worker installer's own rule applied here (worker_agent._glob_hits): a user's non-@ entry with glob metacharacters that reaches any floor-gated builtin is dropped before the merge and named, with the builtins it would have reached, in the warning and the SEL feed; exact names and @ refs are judged by the gate as before. Two things this does not touch, named open: main's kirocrew.json keeps the user's allowedTools untouched and never re-filters it, so the same * exposure exists on that spec today, outside this PR's goal; and the root cause — the exact-name floor check inside may_skip_gate, a shared control — would cover every writer if made glob-aware, which is the owner's call rather than this PR's.

Round 8 (3b820f6172 → this head). GPT 5.6's three blocking findings on the round-7 head were all real, and each completes a design an earlier round introduced rather than patching an instance. (1) agent.py:3438, the hold at boot: the boot rebuild is a bare rebuild_agent_config() that discards _held_out, and prime_ceiling_projection then records the current generation, so a conductor spec held at start — still carrying the previous ceiling's list — was never retried, because the hook skips an unchanged generation; the rebuild now records its installers' verdict in a module memo (_conductor_spec_held, written where the four arms settle, so a raise further down cannot leave a stale one) and prime_ceiling_projection seeds nothing while it is set, logging once, so the first poll rebuilds against the unseeded baseline and the memo advances only when every spec is rewritten. (2) conductor_agents.py:265: _spec_path_is_safe collapsed an OSError on its metadata probe to False, which _spec_to_replace read as a refused shape and wrote over — a stale NFS handle on the probe would have destroyed an intact spec, the exact loss round 3 closed for the read itself; the fence's one implementation is now _spec_path_shape_refusal, which returns the reason for a refused shape and lets a failed probe raise, so the installer holds on the probe's OSError (warning naming the error) while the bool wrapper, and its other callers, still fail closed. (3) conductor_agents.py:439: round 7 expanded a user's wildcard only against the floor-gated builtins, so web_* was kept under a ceiling with a network.egress rule — may_skip_gate("web_*", ceiling) is True while may_skip_gate("web_fetch", ceiling) is False, and kiro-cli would have auto-approved web_fetch past the ceiling; the pattern is now expanded against every builtin the gate has a rule for (BUILTIN_TOOL_SCOPES and BUILTIN_TOOL_CAPABILITIES, exactly the names where expansion can change the gate's answer, since the tools-scope check already applies to the pattern itself) and each hit is put to auto_approve._may_auto_approve, the predicate the exact names go through; one refused hit drops the pattern, the warning and the SEL reason say which hits the floor refused and which the ceiling did, and _FLOOR_GATED_BUILTINS / _floor_builtins_reached are deleted rather than kept beside a second set. The round-7 floor cases keep their red-first assertions under the one path; the rig's ceiling stub became the real gate with no ceiling so the floor bites in the tests as it does on a host. The two open items from round 7 stand as written.

Round 9 (8dd2827f64 → this head). GPT 5.6's one blocking finding on the round-8 head was real: the round-8 memo closed the hold for the polled half only. Verified in code before any edit — reproject_for_ceiling_change has one caller, policy_distribution._run_post_install_hooks (run on the distribution refresher thread after an install and on every confirming poll), and start_refresher starts no poller unless the active policy names a source and an interval; the ceiling is installed by bootstrap.set_context at boot and by policy_distribution.apply_ceiling alone, the one register_ceiling_install_hook consumer is the YOLO-verdict cache in safety_override, and nothing watches security_policy.json. So on a host with no central distribution a local tightening takes effect at the next boot, and a conductor spec that boot's rebuild held kept the previous ceiling's allowedTools for the process lifetime, with the hook never called. Two changes close it. The hold is reached only after a bounded retry of the reader's transient class (_spec_to_replace: three reads, 50 ms and 100 ms apart; a path shape or never-a-spec bytes are not retried; the warning names the attempts), since a second read a moment later is what clears an I/O error or a stale handle. And agent.retry_held_conductor_specs rides the gateway's existing hourly maintenance wake (_run_agent_scratch_sweep, the loop that already hosts the scratch, work-root and session-dir sweeps rather than a scheduler of its own — no new timer, no thread), first in the wake and off the event loop: a no-op unless _conductor_spec_held is set, otherwise one reporting rebuild, so the memo is rewritten where the four installers' verdicts settle and clears only when every spec was written; a persistent hold is retried every wake and warned about each time; the ceiling baseline is left as it stands (unread on a standalone host; on a distributed one the next confirming poll rebuilds once, the documented safe direction). The cost, stated plainly: a hold that outlasts the boot retry and later clears leaves the previous ceiling's list on disk for up to one wake (an hour) — bounded, where before it stood for the process lifetime — and any event-driven rebuild (a dashboard model change, an MCP install) clears it sooner. Inherited on the round-9 head, cited and untouched: main carried src/kiro_crew/autonudge.py:1797 F811 from #12781 (merged 22:40Z) until heal #16032 landed (fa37aa54fd), so Backend Lint & Type Check was red on that head for that line alone; this head is rebased onto the healed tip.

Round 10 (5e61520293 → this head). GPT 5.6 and Opus 5 printed the same blocking finding on the round-9 head, and both were real: rounds 7 and 8 judged a user's wildcard by expanding it over the builtins the gate has a rule for, so a pattern matching none of them — session_*, *_send, *session*, work_*, or any @-prefixed pattern such as @* — survived to the merge, passed may_skip_gate as an unmapped name (the non-@ branch consults only the tools scope; the @ branch probes a server name the pattern does not have), and was written while the same rebuild withheld the exact @kirocrew-dashboard grants a ceiling's mcp rules name — and kiro-cli expands such a pattern over the whole tool namespace in both spellings (worker_agent._grant_reaches_excluded is this repository's own record of that rule), auto-approving the withheld verb on the one path that never reaches PreToolUse. The conductor-spec span had now printed on three consecutive heads for the same shape, so the answer is the restructure rather than a wider expansion: a server's verbs are discovered when kiro-cli connects to it, not at spec-write time, so no expansion performed here can judge a pattern against them, and none is attempted. No entry carrying a glob metacharacter (*, ?, [) survives regeneration: it is dropped before the merge with the one warning ("wildcard entries cannot be judged against the gate ... name tools exactly") and the mcp_auto_approve_revoked record; exact builtin names keep the may_skip_gate judgement and exact @server / @server/tool refs keep their treatment. _GOVERNED_BUILTINS, _builtins_a_wildcard_may_not_skip_for, _wildcard_refusal and the _glob_hits use are deleted (the module shrinks by thirty-odd lines and drops the worker_agent and governance imports this PR had added); _is_wildcard is the whole rule. The round-7 and round-8 wildcard cases keep their red-first assertions under it, and the one case those rounds kept — web_* with no ceiling — flips to dropped, because the rule is no longer what a pattern reaches but that it is a pattern. The frozen Goal is unchanged by this: a pattern is not an entry the user named, and every named entry survives as before.

The history, reconstructed from every commit of the installers since the first conductor (the table's provenance; the code comments carry none of these numbers by the comment-history rule): session, report — #5652 goal, #7238 pipeline, #9273 security, #9277 ledger alias; tool_search — #6377 goal, then with each new conductor; the bare @kirocrew-core — #5652 goal, retired by #8660; the core verbs (monitor_start, monitor_update, autonudge_stop, wait, resource_status, list_sessions, session_ledger_read, session_ledger_record, skill_search, skill_fetch, send_message, send_notification, ask_question) — #8660 goal, #7238 pipeline, #9273 security, #9277 ledger, plus select_crew on the goal conductor and ledger alias only; the dashboard verbs chat_folder_tree, chat_folder_create, session_create, session_read_message — #6377 goal, #7238 pipeline, #9273 security, #9277 ledger; chat_folder_file_self — #10713 (goal, ledger, security; never the pipeline conductor); session_status — #14185 (all four); the work-ledger verbs work_ledger_read, work_ledger_record — #9152 goal and pipeline (_CONDUCTOR_WORK_GRANTS), retired on both by #9277, which left only the new ledger conductor consuming the tuple; work_brief — #9277 ledger alias, and the goal conductor from #10265, when _conductor_spec became the shared spec of both (never the pipeline conductor); work_ledger_rebuild — #12314 goal and ledger. work_report has never been a conductor's grant: since #9152 it is the WORKER spec's (_WORKER_WORK_GRANTS), and a hand-added work_report on any conductor is the user's. Retired today, and therefore dropped from any spec that carries them: @kirocrew-core (goal), work_ledger_read / work_ledger_record (pipeline). Those three are the whole of what the table holds beyond the current tuples, and a test pins that residue.

Checks on earlier heads that were not lanes: Publish readiness signal and Resolve desktop matrix failed on API rate limit exceeded for installation (the GitHub App quota, 04:42Z; the label POST and dorny/paths-filter's listFiles), plumbing that a new head re-runs. One commit, amended; rebased onto main fa37aa54fd (merge-tree clean; the per-file +/- of this commit is identical before and after each replay). test_agent_refactor_spec_bytes.py and agent_state.py are back to main's bytes: with no sidecar record the state digests no longer move with the conductor prompt.

Screenshots / video

N/A — no user-visible frontend surface is touched (a backend spec writer and docs).

Related Issues

Fixes #15567

Pattern harvest

Rule candidate: review-prompt
Pattern: a regeneration that replaces a user-owned list instead of merging it. Sibling writers with the same shape, not fixed here: service_agents._install_knowledge_agent, _install_research_agent, _install_guest_agent, _install_lite_agent_fallback and agent._install_heartbeat_agent all build from the template and _atomic_json_write without reading the file (their allowedTools come from the template, so a hand-added entry on those specs is lost the same way); worker_agent._write_worker_spec is a documented mirror and already names the missing provenance record in its docstring; apps/bridges.py regenerates an app agent's allowedTools deliberately (containment, framework-owned). A reviewer prompt that asks "does this writer read the file it replaces, and if it keeps nothing of the user's, does it say so?" catches the next one.

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

@pepmach
pepmach requested a review from a team as a code owner October 1, 2026 04:41
@pepmach
pepmach requested a review from kyleseaman October 1, 2026 04:41
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the release archaeology behind _SHIPPED_GRANT_HISTORY: tests pin it against today's tuples only, so a grant an old release shipped but the table omits survives as the user's.

[DESIGN-REVIEWED] 688113e

Description read

[DESCRIPTION-READ] bc5f3a27ba4283a6991f1a8d04a77f192e04bd6be4486cd5db73a48ef193a425

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

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 688113e06b4ec8684b001b0963847420b71fa29e — 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 _SHIPPED_GRANT_HISTORY against real release history: a grant it misses persists forever as "the user's"; one it wrongly names re-drops a user's entry every start.

That table is the one piece of this change whose correctness rests on archaeology no test can re-derive — the pins check current-tuple ⊆ history and pin the residue to the test's own _VERIFIED_RETIREMENTS literal, so both literals stand on the author's reading of the installers' commit log. Everything else is grounded: the defect has a linked issue (#15567) with maintainer triage; owner-written approvals surviving Crew's own writers is the recorded decision of rfc-owner-written-mcp-auto-approve (accepted on base), which also supplies the evidence for rewriting the old "hand-edit nothing" doc line; the hold/retry machinery follows the pre-existing governance.md invariant that the ceiling memo advances only after a confirmed write; the wildcard rule cites the gate mechanics already recorded at worker_agent._grant_reaches_excluded. The five sibling generated specs (guest, lite, knowledge, research, heartbeat — counted in service_agents.py + agent.py) share the root cause and are declared deferred in ## Not a goal, which the goal-freeze rule mandates.

What this change ships

Inventory (10 items) — 10 justified

Intent: FIX — a tool the user approved on a conductor agent stays approved after a gateway restart (#15567).

  1. A user's approved tool on a conductor spec survives every regeneration — justified
  2. A grant an earlier release shipped and this one retired is dropped from existing specs (_SHIPPED_GRANT_HISTORY) — justified
  3. A user's wildcard entry is never carried forward; the warning says to name tools exactly — justified
  4. Every drop or kept user entry is logged and SEL-audited (revoked/retained events) — justified
  5. A spec whose bytes can never be a spec, a planted link, or a second hard link is written over, named — justified
  6. A transiently unreadable spec is left in place after three bounded read attempts — justified
  7. The ceiling memo stays pending over a held spec or a failed installer write; boot baseline stays unseeded — justified
  8. The hourly maintenance wake now retries held conductor specs on hosts with no distribution poll — justified
  9. --clean now resets conductor user entries too — justified
  10. Docs now call a conductor spec's allowedTools safe to hand-edit — justified

[FIRST-PRINCIPLES-REVIEWED] 688113e

Description read

[DESCRIPTION-READ] e3b89d0d30900e2054ef288cd709e7c169cbd21ef178bbf4423dc6a27ed442d9

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

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ human override accepted

Human judgment by @pepmach overrides the GPT 5.6 finding for 688113e06b4ec8684b001b0963847420b71fa29e; the recorded reason is authoritative for this commit.

[GPT-OVERRIDE] 688113e

This comment is updated in place on each push.

The model was not re-run because an authorized human decision supersedes it.

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

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 688113e

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

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

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 1, 2026
@pepmach
pepmach force-pushed the fix/allowed-tools-survive-regeneration branch from fbf6b38 to 084341b Compare October 1, 2026 07:46
@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 Oct 1, 2026
@pepmach
pepmach force-pushed the fix/allowed-tools-survive-regeneration branch from 084341b to 10a2582 Compare October 1, 2026 10:46
@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 Oct 1, 2026
@pepmach
pepmach force-pushed the fix/allowed-tools-survive-regeneration branch from 10a2582 to d80ed99 Compare October 1, 2026 12:46
@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 Oct 1, 2026
@pepmach
pepmach force-pushed the fix/allowed-tools-survive-regeneration branch from d80ed99 to cfefc8f Compare October 1, 2026 14:46
@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 Oct 1, 2026
@pepmach
pepmach force-pushed the fix/allowed-tools-survive-regeneration branch from cfefc8f to 18f7c3b Compare October 1, 2026 16:46
@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 Oct 1, 2026
@pepmach
pepmach force-pushed the fix/allowed-tools-survive-regeneration branch from 3b820f6 to 8dd2827 Compare October 1, 2026 21:46
@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 Oct 1, 2026
@pepmach
pepmach force-pushed the fix/allowed-tools-survive-regeneration branch from 8dd2827 to 5e61520 Compare October 2, 2026 00:46
@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 Oct 2, 2026
The four conductor specs (kirocrew-conductor, its ledger alias, the
pipeline conductor and the security conductor) were rebuilt from their
grant tuples on every rebuild_agent_config -- every gateway start, a
provider switch, an MCP change -- and written without reading the file.
An entry the user had approved on one of them was gone at the next
start, silently, while toolsSettings carried over because nothing
rewrote it. kirocrew.json already keeps the user's list on an existing
install; the conductor specs now do the same.

The installers read the spec they replace and carry the user's entries
forward after the shipped grants, through the same governance ceiling,
so a forbidden entry is still removed and the ceiling is never widened.
What tells a user's entry from the installer's own is the history of
every grant any release has ever shipped on that spec, a literal table
in the code pinned to contain everything the installers write today: an
on-disk entry it names is Crew's and is kept exactly when this release
ships it (#8660 narrowed the goal conductor's bare @kirocrew-core to
named verbs; one release shipped the work-ledger verbs on the pipeline
conductor), and an entry no release ever shipped is the user's and stays.
The history is the provenance, kept in code rather than in a per-install
record, because it
holds for any file at the spec's name -- written by this release, by an
earlier one, by another install whose agents directory was copied here
-- with no second store to fall out of step with the spec, be torn by a
failed write, or be hand-damaged into a wrong answer. Its one cost: a
user who hand-adds a grant Crew once shipped and has since retired loses
it at the next start, named in the warning and audited, and the tool
asks instead -- the drop fails closed. Every dropped entry is named in
one warning; a drop the ceiling did not make is audited as a revoked
auto-approval, and a user's entry carried forward is audited as a
retained one, since keeping an auto-approval past a rebuild is a
permission decision. One shape of the user's is never carried: a
wildcard (a bare "*", "fs_*", "session_*", "@*"). The gate judges a
builtin or a server by its exact name, so the pattern itself would pass
it while kiro-cli expands it, on the one path that never reaches the
gate, over every builtin and every verb of every MCP server the spec
mounts -- and a server's verbs are discovered when kiro-cli connects, not
when the spec is written, so no expansion here can judge the pattern
against them. It is dropped before the merge, and the warning says to
name tools exactly. A clean rebuild keeps nothing, as for kirocrew.json.

A spec that is present but cannot be read is not "no spec", and what
happens to it follows the reader's own two failure classes. Bytes that
can never be a spec -- not JSON, not an object, an allowedTools that is
not a list, a planted link -- are written over: kiro-cli could not load
that file either, so leaving it would leave a conductor dispatched by
name resolving to the default agent and its file-writing tool set, and
would leave a tightened ceiling with nothing to re-filter onto. So is a
spec whose inode carries a second hard link, read from its metadata
before any byte: the hardened reader refuses a multiply-linked inode for
good while kiro-cli loads the same bytes without that fence, so a spec
left in place for that reason would be the one list a tightened ceiling
never reaches; the write swaps the directory entry, so the other name
keeps its bytes. A read that failed for a reason the reader calls
transient -- or a metadata probe that failed before any byte was read --
is tried again, three reads a fraction of a second apart, since the
pause costs less than the hold; one that outlasts them leaves the user's
file exactly where it is, and the installer reports that it wrote
nothing -- as the rebuild does when an installer's write raised -- so the
ceiling-reprojection memo stays pending and retries instead of being
marked projected onto a list that was never rewritten. That hold travels
apart from the shared-home guard's refusal: kirocrew.json was written,
and the dashboard's default-model applier reads a refusal as a change
that did not land. Boot carries it too: the rebuild records whether it
held, and the ceiling baseline seeded after the boot rebuild stays
unseeded while it did, so the first governance poll retries a spec held
at start instead of waiting for the ceiling to move again. A host with
no central distribution runs no poll, and its ceiling changes only at
boot, so a spec that boot held would have kept the previous ceiling's
list for the process lifetime: the gateway's hourly maintenance wake
retries it there, on every host, rewriting it once it can be read and
clearing the hold only when every conductor spec is written.

Fixes #15567
@pepmach
pepmach force-pushed the fix/allowed-tools-survive-regeneration branch from 5e61520 to 688113e Compare October 2, 2026 02:46
@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 Oct 2, 2026
@pepmach

pepmach commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author
  • Supported MCP wildcard approvals are deleted span=65d65eddff93 — rebutted

Outcome: rebutted. The code stays as it is: a wildcard entry on a conductor spec is dropped when the spec is regenerated, named in one warning with the remedy ("name tools exactly"), and recorded as a revoked auto-approval.
The previous finding on this same span, upheld by Opus, set the rule this round applies: a pattern's reach cannot be judged when the spec is written, because a server's tools are discovered when kiro-cli connects to it. So the installer carries no pattern at all and offers only exact names to the gate.
A literal-server glob such as @server/read_* is not a shape the gate can judge more finely than that rule allows. may_skip_gate reads only the server part of an @ entry and never the part after the slash, so it would judge @server/read_* exactly as it judges the whole-server grant @server. Anything the glob says, an exact entry already says: @server for the whole server, @server/read_a for one tool. Keeping the glob would add no approval the user cannot write exactly, and would reopen the shape-by-shape exceptions that the three previous rounds each found leaking.
The cost is one re-prompt for an entry the user can restate by exact name, never a widened grant, as the finding itself rates it (LOW: "the failure direction is MORE prompting, never a widened grant"). The entry can only come from a hand edit: the installer's own writer never emits a glob.

@pepmach

pepmach commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

/ai-review override gpt 688113e: round 10 carries no wildcard by design -- the previous print on this span, upheld by Opus, established that a pattern's reach cannot be judged when the spec is written; a literal-server glob is judged by may_skip_gate only as the whole-server grant @server is, which the user can write exactly, so the cost is a re-prompt and never a widened grant, as the finding itself rates it.

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@pepmach marked the gpt AI finding as false positive, not applicable, or explicitly accepted for 688113e06b4ec8684b001b0963847420b71fa29e.

round 10 carries no wildcard by design -- the previous print on this span, upheld by Opus, established that a pattern's reach cannot be judged when the spec is written; a literal-server glob is judged by may_skip_gate only as the whole-server grant @server is, which the user can write exactly, so the cost is a re-prompt and never a widened grant, as the finding itself rates it.

This decision applies only to this commit. A new push requires a new judgment.

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

Copy link
Copy Markdown
Contributor

Reviewed for merge triage, not approving from my side: ~2.4k added lines changing how user allowedTools entries survive conductor spec regeneration. allowedTools is a tool-permission list, and at this size it needs a maintainer and security owner review. CI is green.

@pepmach

pepmach commented Oct 5, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the triage. Agreed that allowedTools is a tool-permission list and that a change of this size needs a maintainer plus a security owner's review; requesting @bolichen97 for the security half. CI is green on 688113e and no further pushes are planned until that review lands.

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

Reviewed on behalf of the maintainers (sweep 2026-10-06): full diff read, callers verified against current main, readiness passed, required checks green, no blocking review threads. Security half, reviewed on the owner's behalf: a user's own exact-name allowedTools entries on the four conductor specs now survive a rebuild, but every carried entry still passes _filter_auto_approve under the governance ceiling, wildcards are never carried, and every drop/retain is warned and SEL-audited -- the merge never widens the ceiling. Note for maintainers: _SHIPPED_GRANT_HISTORY is a hand-kept table; a new conductor grant must be added there or the subset pin fails loudly. Approving and merging.

@bolichen97
bolichen97 merged commit dc4f8d0 into main Oct 6, 2026
97 of 98 checks passed
@bolichen97
bolichen97 deleted the fix/allowed-tools-survive-regeneration branch October 6, 2026 07:03
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 6, 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.

allowedTools list should persist across spec regeneration instead of resetting to base entries

3 participants