Skip to content

docs(monitoring): record why a published tool name is not renamed - #10945

Merged
chenmingwei23 merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:feat/rename-monitor-start-to-patrol
Sep 15, 2026
Merged

chenmingwei23 merged 1 commit into
kirodotdev:mainfrom
chenmingwei23:feat/rename-monitor-start-to-patrol

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

monitor_start arms the in-session timer. monitor_watch arms the
observation-gated probe. Read cold, that is backwards. start is the generic
primary verb, so the older timer reads as the default way to arm a monitor while
the newer, cheaper, zero-token probe reads as a variant of it. A caller picking by
name picks the expensive one. patrol would say what the timer actually does, and
the shipped conductor prompts already use that word for it.

This PR started as that rename and no longer performs it. What it ships is the
reason the rename is not worth doing, because that reason generalizes to every
published tool name and had never been written down.

Why it matters

A published tool name is a key that other people's persisted records were written
against, and every one of those records is a decision that silently changes meaning
when the key changes.

Restrictions are the dangerous half. A persisted rule naming a tool that no longer
exists does not fail loudly -- it stops matching. The capability an operator
switched off comes back on, and nothing at the call site says so. A stale call
fails with Unknown tool; a stale deny fails open and stays quiet.

That is not hypothetical for this repo. Restrictions are resolved at several
name-keyed surfaces, at different lifecycle stages, in different shapes, and the
spec entry enumerates all of them with their files. Three are reachable from code
and could be migrated. Two are deliberately left raw. One cannot be reached at
all:
a hand-written block in an on-disk profile the backend reads itself, which
acp/kas_agents.py already documents as not Crew's to relay.

So the best achievable end state for renaming a published name is a known silent
fail-open that cannot be closed. Not a step toward a complete job -- the complete
job's residue.

What changed (motivation -> approach -> change)

The change that was proposed is gone in full: no rename, no tool_retirement
module, no widening at any call site, no grant-side edits, no renamed test file.

It was withdrawn because five consecutive review rounds each found a further
name-keyed surface where a persisted restriction would silently stop applying, and
the fifth one was unreachable from code. The final blocking finding was confirmed
rather than fenced, at UNBOUNDED harm with "recovery path: none -- the restriction
evaporates silently".

The argument that saved it in earlier rounds -- that the persisted entry is rare --
did not survive either. The entry is written by clicking a tool off in the
dashboard, which is an ordinary user action, so the correct question was never
whether such an entry exists on some particular install.

Against that cost: across six heads, nobody produced an instance of the mispick the
rename was meant to prevent.

The enumeration built while trying to make the rename safe is the thing worth
keeping, so it ships on its own and the code change does not. This PR is therefore
one spec entry in docs/system-specs/modules/monitor-architecture.md, recording:

  • the naming defect, stated plainly as a known and accepted wart rather than a
    future task
  • the general rule: renaming a published tool name silently changes what persisted
    operator restrictions mean
  • the enumeration table -- every surface where a restriction is resolved, its
    lifecycle stage, its shape, and whether code can reach it
  • that the unreachable surface makes the residue permanent, so such a rename is a
    policy migration with a remainder rather than a legibility change, and should be
    priced that way before approval instead of discovered one surface at a time
  • what remains available, because none of it is name-keyed: the tool descriptions,
    this spec, and the prompts that choose between the two tools

Tests

No code changes, so no new tests. Verified on the head:

  • docs_lint passes
  • brand-name, comment-history, feature-map, black and testpaths gates pass against
    base cdb1613f8
  • the diff is one file, +49 lines, and contains no occurrence of monitor_patrol,
    tool_retirement, widen_restriction or RETIRED_TOOL_NAMES
  • test/test_monitor_start_ack.py is present under its original name, so the
    rename left nothing behind

Manual verification

N/A -- docs-only change; the diff is a single spec file with no runtime surface.

Related Issues

The enumeration has a consumer the moment it lands: the next person who proposes
renaming any published tool name. It is the same shape of artifact as #10946, which
records what gates retiring irq.Probe.

The pre-existing startup fail-open found while reviewing this change is filed
separately as #10982. It is not caused by a rename and is not addressed here: when
the policy cannot be resolved at all, an empty set is returned before the exclude
list is parsed, so every exclusion is withheld equally for that window.

Follow-up #10981 existed only to fix the third surface for the rename's sake and is
closed with the rename.

Pattern harvest

Not generalizable: this PR ships a single spec entry recording an accepted naming
wart; there is no defect to stop a class of, and the enumeration it lands is itself
the reusable artifact for the next such rename proposal.

@chenmingwei23
chenmingwei23 requested a review from a team September 15, 2026 01:55
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Sep 15, 2026
@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] fe9f3f5

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

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

Design-Verdict: PASS

Verify the rename-cost rule is findable by its stated consumer — a proposer renaming a non-monitoring tool never opens monitor-architecture.md.

Suggestions

  • The general rule ("a rename of a published name is a policy migration with a permanent remainder") outlives its monitoring trigger; add a one-line pointer from docs/architecture/mcp.md (the doc routed for changing tools) to this section.

[DESIGN-REVIEWED] fe9f3f5

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ⏭️ skipped

Revision fe9f3f5cb0467a5e0f3c6331812ed1111fd927c6 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] fe9f3f5

@chenmingwei23

chenmingwei23 commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor Author
  • needs-a-decision -- span=cc96493ca85f, retiring a published name on a deduced mispick

Both points conceded. The body argued from the name/description contradiction,
an inference about how the pair reads, not a report of any agent arming the
prompt loop where monitor_watch applied. I have no pointable instance and will
not manufacture one after the fact.
Also conceded: the rule I cited from monitor-architecture.md governs that
spec's own Observation rename, an internal type with in-repo callers, so it is
not precedent for retiring a PUBLISHED name. Citing it overstated provenance.
Neither clearing path is the author's to take: it needs the consolidated-monitor
RFC merged non-draft to base, or a maintainer push so an override is honoured
on this fork. Maintainer decides: ship, or take the Subtraction and defer.
Holding the diff as-is rather than self-reverting on a bot's word.

For a human reader, the shape of the decision:

The lane is right that this PR's justification is a deduction. What it cannot
see is that the rename was assigned as a work item, so a decision does exist --
it is just not recorded anywhere the lane can read, and the author cannot
self-certify it. That is why this is needs-a-decision rather than rebutted.

Three ways this clears, all of them a maintainer's to pick:

  1. Ship it. Record the decision in a form the lane accepts -- merge the
    consolidated-monitor RFC non-draft to base, or push this branch as a
    maintainer so an override is honoured on a fork PR.
  2. Point at a real instance. If an agent arming the prompt loop where
    monitor_watch applied is on record in an issue, a transcript, or a support
    report, citing it clears the item on the evidence path.
  3. Take the Subtraction. Defer the rename and close this PR; monitor_start
    keeps resolving and nothing regresses. The measured cost of doing that is
    only that the naming stays backwards.

What the rest of the review says, so the decision is made against the full
picture: the lane's own inventory marks 4 of the 5 shipped items justified, and
the one it disputes is the core move rather than any detail of how it was
carried out. Design Review is PASS, GPT and Opus have no line-level findings on
this head, UX is PASS, and there are zero unresolved threads. The only red check,
Frontend Lint & Type Check, is a pre-existing main failure owned by #10940
(issue #10938) that this diff cannot influence in either direction.


Superseded on this point (head 6292125): #10940 merged as cdb1613f8 and is
now an ancestor of this branch, so Frontend Lint & Type Check is no longer waiting
on anything external. The manifest-sync gate reports OK: 24 built-in manifests, 244 strings match locales/en.json exactly on the rebased head. The sentence above was
true when written and is kept rather than rewritten; this note is the correction.

@chenmingwei23
chenmingwei23 force-pushed the feat/rename-monitor-start-to-patrol branch from 071b583 to 8d2ab40 Compare September 15, 2026 02:42
@chenmingwei23 chenmingwei23 changed the title refactor(monitor): rename monitor_start to monitor_patrol refactor(monitor): rename monitor_start to monitor_patrol, keep it resolving Sep 15, 2026
@github-actions

github-actions Bot commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review (fork) — 🟡 CONCERNS

Which legitimate operations does 629212507af52092ae0a49d0221cfef2b9bdd931 newly refuse? Model proposes, scripts/deny_diff.py decides — updated in place on each push. A script-confirmed regression blocks PR readiness.

the reviewer's own judgement; no confirmed regression

Scope-Verdict: CONCERNS

TIGHTENING: tool_retirement.widen_restriction_for_retired_names, consulted at the two restriction-resolution points the diff wires in — mcp_shared._resolve_excluded_tools ("resolved = widen_restriction_for_retired_names(exclude)", replacing the plain "{t for t in exclude if isinstance(t, str)}") and acp/kas_agents.to_client_custom_agent ("entries = sorted(widen_restriction_for_retired_names(excluded))") -- the ONE threat it refuses is rename-induced fail-open: a persisted managedToolPolicy.exclude / excludedTools rule naming the retired monitor_start silently ceasing to match after the rename, so the capability the operator denied "would come back ungoverned with nothing saying so -- a fail-OPEN on an existing policy, produced by the rename itself" (the hunk's own comment). The widening makes such a rule also deny the current name monitor_patrol.

ADJUDICATED: 12 candidates, 0 confirmed newly-refused
The candidates are written to candidates.json; the deterministic classifier runs after this review is captured, and no confirmed rows were handed to this run, so there are no REGRESSION entries to report. The diff touches no file under src/kiro_crew/security/ (path fence, sensitive-command tier, exfiltration shapes, rule catalog are all textually unchanged between cdb1613 and 6292125), so the shell-adjudicated half of this change is expected to be a no-op; the rows probe the touched area's daily operations and the strings the rename introduces into ordinary argv (monitor_start, monitor_patrol, tool_retirement, the ~/.kiro/agents policy tree) in case any tier keys on them.

PLATFORM COVERAGE: Candidates were written in all three spellings: any for the platform-neutral git/gh/product-CLI strings (git grep sweeps, kirocrew doctor); posix for interpreter- and path-carrying operations (python3 invocation of monitor_armed.py, the env-stripped .venv/bin/python -m pytest proof run, grep -rn ... ~/.kiro/agents, ls -la ~/.kiro/agents, loopback curl of /api/session-tool-policy); and windows pairs for each of those (py -3 with backslash paths, .venv\Scripts\python.exe -m pytest, findstr /s over %USERPROFILE%\.kiro\agents, Invoke-RestMethod). The guard itself makes no path, separator, interpreter, or environment assumption — RETIRED_TOOL_NAMES is an exact string-key map over MCP tool names, which spell identically on every host — so no assumed platform went unprobed; the windows rows exist because the operator retirement-check operations around the guard spell differently per host. Per-leg verdicts are the deterministic fold's to report, not this section's.

UNADJUDICATED: The tightening lives entirely outside the shell tool-call deny composite, so the classifier can settle nothing about it, and no PASS can rest on the empty adjudicated set above.

  • Guard: widen_restriction_for_retired_names (src/kiro_crew/tool_retirement.py). Call path 1: the gateway serves a session's persisted managedToolPolicy.exclude → mcp_shared._resolve_excluded_tools widens the set per call (cached per session) → the per-call tool refusal. Call path 2: an agent spec's excludedTools list → acp/kas_agents.to_client_custom_agent widens and relays it to the agent host at session startup. Candidate legitimate inputs I would have submitted, had a verdict existed: (a) exclude: ["monitor_start"] with calls to monitor_update, monitor_watch, monitor_stop, monitor_inspect, autonudge_stop — the widening must add only the exact retired key's replacement, never the monitor_* family (by reading, the map is exact-key lookup, so these should stay allowed, but that is a reading, not a verdict); (b) exclude: ["monitor_patrol"] — the new name must not begin denying anything besides itself, and must not retro-deny under the old name in raw-rule consumers; (c) an exclude list containing empty or non-string entries — previously filtered, and the new function must keep dropping them rather than refusing the whole policy.
  • Approval tier, named as a designed loss: the module deliberately migrates no GRANT, so a user's persisted auto-approve/permissions entry naming @kirocrew-core/monitor_start stops matching after the rename. An unattended conductor whose patrol re-arm relied on that grant now stalls at an approval prompt with nobody at the keyboard — the "it just stopped working" shape, chosen fail-closed on purpose (the module's own docstring argues widening a grant would bypass the deny-list and the audit trail). No classifier verdict exists for the approval tier; the loss should be release-noted so operators re-key their grants.
  • Ride-along corpus edit: this change also renames the committed golden-path flow row monitor_start → monitor_patrol inside golden-paths.json. It is a rename tracking the tool, not a withdrawal, and flow rows are human-exercised rather than classified — but it is a corpus edit folded into the change under review, so it is named here rather than passed silently.

[SCOPE-REVIEWED] 6292125

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 8 classified, 0 newly refused, 8 still allowed.
  • ubuntu-latest (platform posix): 8 classified, 0 newly refused, 8 still allowed.
  • windows-latest (platform windows): 7 classified, 0 newly refused, 7 still allowed.

No candidate flipped from allowed to refused.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/rename-monitor-start-to-patrol branch from 8d2ab40 to 6e667c0 Compare September 15, 2026 03:15
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 15, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed -- span=7f31fe047729, alias bypasses managed tool exclusions (6e667c0)

Upheld and fixed as prescribed: canonicalize before the exclusion checks.
The alias no longer resolves in dispatch at all. mcp_core._call_tool maps an
old name to its canonical at the FRONT DOOR, ahead of _validate_args, the SEL
audit row, the governance vets and dispatch, so every name-keyed check sees one
name. dispatch now holds no alias vocabulary, and a test asserts
dispatch("monitor_start") returns "Unknown tool" so the post-gate path cannot
come back.
Two other surfaces read a CALLED name and now cover aliases:
channel._blocked_tool_named builds its containment regex from the alias map, and
_filter_auto_approve inserts an alias grant only beside a canonical the ceiling
already KEPT, so a withheld tool withholds its alias too.
On the adjudicator's note: the exclusion surfaces do exist --
CHANNEL_AGENT_BLOCKED_TOOLS with _blocked_tool_named, and the conductor grant
ceiling. No monitor tool is on the containment list today, so nothing was live;
the gap would have opened silently the first time one was added.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed -- span=3157b2d869d4, conductor grants dropped the alias name (6e667c0)

Correct, and it mattered more than a prompt: for an UNATTENDED conductor an
approval nobody answers is a failure, which is the case the alias exists for.
Not fixed the way the item suggested, because a flat alias entry in each grant
tuple re-opens the bypass GPT blocked on -- the entry would be filtered on its
OWN name, so a canonical the ceiling WITHHELD would still be auto-approved
under its alias. The repo's own ceiling test proved it: with monitor_patrol
denied, a flat grant left monitor_start granted.
Instead _filter_auto_approve derives the alias grant from what the ceiling
already kept, inserted beside its canonical. Both facts hold at once: a granted
tool carries its old spelling, a withheld one carries nothing. Tests pin both
directions plus the absence of a flat entry, and the KAS literal now asserts
that withholding the canonical drops the alias from the rules too.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • needs-a-decision -- span=3e797a6823b9, relabel bar unmet on a deduced mispick

The concession is deliberate and stands: there is no observed mispick and none
will be manufactured to clear this.
One thing has changed under the item since it was written. The hard retirement
is gone: monitor_start still resolves, unadvertised. So the shipped move is
ADDITIVE -- a better name beside a still-working one -- rather than a removal of
a published surface, and the second half of the original objection (no alias,
stale callers fail) is answered in code rather than argued.
That leaves only the legibility justification, which is what it says it is: the
pair reads backwards and the description opens by correcting its own name.
Whether that alone warrants the relabel is the maintainer's call, and the item
names the path -- a recorded decision. Not the author's to take, and not
self-authorizable on a fork PR.
Holding the diff rather than reverting: the Subtraction and shipping are both
live options for whoever rules.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed -- span=286816e4ba59, one consumer generalized in dispatch (6e667c0)

Right, and deleted. The per-domain ALIASES protocol
(getattr(module, "ALIASES", {}), implemented by 1 of 13 DOMAIN_MODULES) and the
one-entry control.ALIASES copy that existed only to feed it are both gone.
The subtraction turned out to be the same fix the GPT blocking finding wanted:
resolving at dispatch was ALSO after every name-keyed gate. Canonicalizing once
in mcp_core._call_tool removes the protocol and closes the bypass together, so
dispatch is back to its original shape plus a docstring saying only canonical
names arrive.
Net effect on this file: dispatch is now byte-identical to main except for that
docstring.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed -- span=1129d8cdb7be, operator_inputs re-spelled the store schema (6e667c0)

Right. The hand parser is gone; operator_inputs now reads loop messages through
AutoNudgeService.load_for_maintenance, the service's own locked parser, and the
dict-digging of document.get("loops")/get("message") is deleted.
That is the correct reader for the reason its own docstring gives -- it reuses
the startup schema and persistence protocol, and the absence of start() means
reading the store cannot fire a loop as a side effect. A second spelling of a
store schema is exactly the kind that drifts, and this check depends on that
shape being right.
The helper is async now, and its tests with it.

@chenmingwei23
chenmingwei23 force-pushed the feat/rename-monitor-start-to-patrol branch from 6e667c0 to e7877ee Compare September 15, 2026 03:25
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed -- span=7f31fe047729, alias bypasses managed tool exclusions (e7877ee)

The earlier fix canonicalized at the wrong front door. mcp_core._call_tool is
INSIDE the exclusion check, which lives upstream in mcp_shared's tools/call
branch: tool_name = params.get("name"), then if tool_name in excluded, on the
RAW requested name. So the hole was still open and the finding still correct.
Now: if tool_name in excluded or canonical_name in excluded. BOTH halves are
required. Canonical-only would trade this bypass for the opposite one, an older
policy naming the OLD tool going unenforced.
Mutation-verified rather than asserted: reverting to the raw name alone reddens
exactly one test and nothing else, so the pin is specific to the bypass instead
of incidentally passing. The rejection is audited identically
(rejected_excluded / managedToolPolicy.exclude) and the handler is proven not to
have run, since a different error would not be the same containment.
tools/list needed nothing, checked rather than assumed: it filters entries of
its own advertised list by their own names, and an alias is never in that list.
No import cycle -- mcp_shared already imports session_directive, which is a
pure stdlib leaf, so mcp_tools' laziness is untouched.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 15, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed -- the alias lost auto-approval on the conductor grants (6e667c0)

Correct and already fixed one head after the one this lane judged. The stamp
here is 8d2ab40; the fix landed in 6e667c0, and Design Review -- which
raised the same finding independently -- has since returned PASS stamped
6e667c0.
Fixed by DERIVING the grant, not by listing the alias in the tuples.
agent._filter_auto_approve inserts the alias beside its canonical only when that
canonical survives the governance ceiling. Verified on both conductors: the
tuples do not name the alias, the emitted allowedTools does, and denying the
canonical drops BOTH spellings.
A flat tuple entry was tried first and is wrong: it is filtered on its OWN name,
so a canonical the ceiling WITHHELD would still be auto-approved under the alias
-- the same class as GPT's blocking finding, in the other direction. The repo's
own ceiling test caught it.
A third item from this lane is recorded in the body rather than fixed: after the
rename no golden-paths row names the alias path, so a human exercising the
monitoring flow should exercise both spellings while the alias lives. Whether
the corpus carries the alias as its own row belongs to that file's owner.

@chenmingwei23
chenmingwei23 force-pushed the feat/rename-monitor-start-to-patrol branch from e7877ee to c971576 Compare September 15, 2026 03:40
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed -- span=3e797a6823b9, relabel bar unmet on a deduced mispick (c971576)

The alias is gone and the rename is now a hard retirement, and the maintainer's
ruling replaced the taste justification with a reachability one. That is a direct
answer to this item rather than a deferral of it.
Why an alias cannot be made safe: a name-keyed decision must give both spellings
one answer in BOTH directions. Where it restricts, an alias resolved later is a
way around it (the tools/call exclusion on the raw name). Where it permits, an
alias it does not name is a way to LOSE it (the conductor grants). Fixing the
second needs auto-approval, and acp/kas_agents.py records that an auto-approved
call never reaches Crew's permission callback, so the deny-list and audit are
skipped with it -- so one fix widens the other. The same block records that a
hand-written deny lives in an on-disk profile Crew never composes, so the gate
set is not closed from in here at all.
The trade is now the justification: a stale caller fails loudly, and that
population is enumerated in the body (five builtin skills the sync replaces,
three out-of-repo skills needing a human, two active loop messages nothing
rewrites). A loud failure on a listed set is recoverable; a ceiling bypass that
skips the audit is not, because nothing records it.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 15, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted -- span=residual/security, "Retired restrictions still fail open during startup" (84eb739)

Not a defect introduced or worsened by this change, and the remedy it
prescribes is already in the diff. Arguing not-applicable, not disproportion.

The prescribed fix is present. "Widen retired restrictions in the
agent-host policy projection before startup" is implemented at
acp/kas_agents.py:529 -- entries = sorted(widen_restriction_for_retired_names(excluded))
with the import at :63, pinned by
test_the_relayed_excluded_tools_block_is_widened. That projection is the path
the backend enforces from the spec, independent of the runtime resolution.

The residual is a property of the fail-open design, not of the rename.
_resolve_excluded_tools returns an empty set at three points BEFORE the
exclude list is parsed: mcp_shared.py:486 (tool_policy.no_session_key),
:521 (tool_policy.agent_not_resolved), :568 (gateway unreachable), each
audited outcome="fail_open". The list is not parsed until :525 and not
widened until :534. So no widening of any kind can run in that window, and
the window withholds EVERY exclusion equally -- a retired name is no more
exposed than any other tool. A rename cannot worsen a window in which nothing
is enforced.

This lane's own adjudication agrees. On this sha it returned
total=0 uphold=0 downgrade=0 with flagged=1: "a pre-existing property of
the fail-open design
, identical for every exclusion, not something the rename
created or can worsen", naming the 5s negative cache and kiro-cli's independent
disabledTools enforcement as recovery. FLAG, not UPHOLD.

Recorded rather than absorbed. Filed as #10982 on its own, because a
fail-open policy decision deserves its own review rather than being changed
inside a rename. Searched first; no existing issue covered it (#10429 and
#7547 are adjacent but neither is this).

The third resolution point this review surfaced is split, not dropped:
#10981, opened before this merges. Every restriction-resolution point is now
enumerated in the PR body and in the tool_retirement module docstring,
including the two that cannot be reached.

@chenmingwei23
chenmingwei23 force-pushed the feat/rename-monitor-start-to-patrol branch from 84eb739 to ba06c18 Compare September 15, 2026 05:19
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 15, 2026
chenmingwei23 added a commit to chenmingwei23/KiroCrew that referenced this pull request Sep 15, 2026
Third of the restriction-resolution points enumerated on kirodotdev#10945, split out
of it because it is a different change: `(server, tool)` PAIRS rather than
a flat name set, two sources rather than one, and consumers that compare
against a two-field identity.

`session_mcp_disabled_tools` unions the pairs a session has switched off
from the agent spec's `disabledTools` and from the global settings file the
dashboard writes on an ordinary tool-off action. Both are keyed by the tool
name as it was spelled at the time. Rename the tool and the pair matches
nothing, so the tool a human switched off in a UI is back on with nothing
saying so.

Widened at the single point the pairs are produced, so every consumer
inherits it: the Claude `permissions.deny` projection, the restricted-server
set, and the codex path that compares `rawInput.server` / `rawInput.tool`
without going through the lossy `mcp__server__tool` spelling.

The retired spelling is kept as well as expanded. A restriction can only
ever restrict, and dropping the old pair would narrow what the user asked
for. `autoApprove` is a GRANT and is not widened here or anywhere; a test
pins that so completing the symmetry reddens.

Tested through the real producer and its real projection for both sources,
not through the widening helper -- a helper test passes on code where
neither source is wired to it. Mutation-verified: removing the widening
reddens exactly the new pair test.

Stacked on kirodotdev#10945, which adds `tool_retirement`. Merge that first.
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/rename-monitor-start-to-patrol branch from ba06c18 to 6292125 Compare September 15, 2026 05:57
chenmingwei23 added a commit to chenmingwei23/KiroCrew that referenced this pull request Sep 15, 2026
Third of the restriction-resolution points enumerated on kirodotdev#10945, split out
of it because it is a different change: `(server, tool)` PAIRS rather than
a flat name set, two sources rather than one, and consumers that compare
against a two-field identity.

`session_mcp_disabled_tools` unions the pairs a session has switched off
from the agent spec's `disabledTools` and from the global settings file the
dashboard writes on an ordinary tool-off action. Both are keyed by the tool
name as it was spelled at the time. Rename the tool and the pair matches
nothing, so the tool a human switched off in a UI is back on with nothing
saying so.

Widened at the single point the pairs are produced, so every consumer
inherits it: the Claude `permissions.deny` projection, the restricted-server
set, and the codex path that compares `rawInput.server` / `rawInput.tool`
without going through the lossy `mcp__server__tool` spelling.

The retired spelling is kept as well as expanded. A restriction can only
ever restrict, and dropping the old pair would narrow what the user asked
for. `autoApprove` is a GRANT and is not widened here or anywhere; a test
pins that so completing the symmetry reddens.

Tested through the real producer and its real projection for both sources,
not through the widening helper -- a helper test passes on code where
neither source is wired to it. Mutation-verified: removing the widening
reddens exactly the new pair test.

Stacked on kirodotdev#10945, which adds `tool_retirement`. Merge that first.
`monitor_start` arms the in-session timer and `monitor_watch` arms the
observation-gated probe, which reads backwards: `start` is the generic
primary verb, so the older timer reads as the default and the newer,
cheaper, zero-token probe reads as a variant of it. `patrol` would say
what the timer does, and the shipped conductor prompts already use that
word for it.

The names stay, and this records why, because the reason generalizes past
these two tools.

A published tool name is a key that other people's persisted records were
written against, and every one of those records is a decision that
silently changes meaning when the key changes. Restrictions are the
dangerous half: a persisted rule naming a tool that no longer exists does
not fail loudly, it stops matching, and the capability an operator
switched off comes back on with nothing saying so.

The entry enumerates every name-keyed surface where a restriction is
resolved -- its file, its lifecycle stage, its shape, and whether code can
reach it. Three resolve at different stages and in different shapes: the
per-call exclusion set, the startup projection relayed to an agent host,
and the `(server, tool)` pairs a dashboard tool-off writes to the global
`mcp.json`. Two more are deliberately left raw, one because it copies a
persisted key rather than resolving it and one because an operator needs
to see a stale spelling in order to re-key it.

The last surface is a hand-written block in an on-disk profile the backend
reads itself, and `acp/kas_agents.py` already states that Crew does not
relay it. Nothing here can expand a retired name in that file or warn the
operator holding one. So the best achievable end state for renaming a
published name is a known silent fail-open that cannot be closed -- the
complete job's residue, not a step toward it.

That makes such a rename a policy migration with a permanent remainder
rather than a legibility change, and it should be priced that way before
approval instead of discovered one surface at a time. The mispick the
rename would have prevented has not been observed. The tool descriptions,
this spec and the choosing prompts are all still available, and none of
them is name-keyed.
@chenmingwei23 chenmingwei23 changed the title refactor(monitor): rename monitor_start to monitor_patrol, keep it resolving docs(monitoring): record why a published tool name is not renamed Sep 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/rename-monitor-start-to-patrol branch from 6292125 to fe9f3f5 Compare September 15, 2026 06:13
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 15, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • upheld -- span=backend-security-controls, "Renaming bypasses persisted per-tool disables" (withdrawn at fe9f3f5)

The block is correct and the answer is to stop, not to patch. The rename is
withdrawn in full rather than fixed: no rename, no tool_retirement module, no
widening at any call site, no grant edits, no renamed test. This PR is now one
docs entry.

The finding was right on the code. session_mcp_disabled_tools reads
disabledTools verbatim into the pair set with no expansion
(acp/session_mcp.py:479-485), control-plane tools are enforced by per-call
permission refusal against exactly those pairs (:505-516), so after the rename a
monitor_patrol call has no matching pair and is approved. UNBOUNDED, and
"recovery path: none -- the restriction evaporates silently".

The rarity argument I had been leaning on was wrong, and the adjudication says
why.
I split this surface into #10981 partly because disabledTools is empty on
the install I developed against. That was the wrong question. The entry is written
by clicking a tool off in the dashboard, which is an ordinary user action -- "an
ordinary, non-contradictory legacy artifact, not an extreme condition". Whether a
particular machine happens to hold one decides nothing.

What settles it is a surface widening cannot reach. Enumerating every
restriction-resolution point turned up a hand-written block in an on-disk profile
the backend reads itself, which acp/kas_agents.py:509-511 documents as not Crew's
to relay. No code here can expand a retired name in that file or warn the operator
holding one. So a complete, correct migration still ships a permanent silent
fail-open. That is the complete job's residue, not a step toward it -- which makes
this a policy migration with a remainder rather than the legibility change it was
approved as.

Against that: across six heads no instance of the mispick the rename was meant to
prevent was produced.

Credit where it belongs. This lane found a real fail-open on five consecutive
heads -- the exclusion set, the KAS projection, the grant asymmetry, the startup
window, and now the disabled-tool pairs. Each was correct. The fifth is what showed
the whole approach was mispriced. The enumeration built while trying to make the
rename safe now ships on its own in
docs/system-specs/modules/monitor-architecture.md, so the next person proposing a
tool rename reads the cost before paying it.

#10981 is closed with the rename. The pre-existing startup fail-open remains filed
as #10982; it is not caused by a rename and is not addressed here.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision labels Sep 15, 2026

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

Documentation-only addition explaining why monitor_start/monitor_watch are not being renamed despite the naming being suboptimal. Verified the cited code surfaces (mcp_shared._resolve_excluded_tools, acp/session_mcp.session_mcp_disabled_tools, agent._WORKER_MIRRORED_SHAPES) exist and are consistent with the described name-keyed persistence problem. Sound reasoning, no code behavior changed. Reviewed at head fe9f3f5.

@chenmingwei23
chenmingwei23 merged commit a21898c into kirodotdev:main Sep 15, 2026
94 of 100 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 15, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…rodotdev#10945)

`monitor_start` arms the in-session timer and `monitor_watch` arms the
observation-gated probe, which reads backwards: `start` is the generic
primary verb, so the older timer reads as the default and the newer,
cheaper, zero-token probe reads as a variant of it. `patrol` would say
what the timer does, and the shipped conductor prompts already use that
word for it.

The names stay, and this records why, because the reason generalizes past
these two tools.

A published tool name is a key that other people's persisted records were
written against, and every one of those records is a decision that
silently changes meaning when the key changes. Restrictions are the
dangerous half: a persisted rule naming a tool that no longer exists does
not fail loudly, it stops matching, and the capability an operator
switched off comes back on with nothing saying so.

The entry enumerates every name-keyed surface where a restriction is
resolved -- its file, its lifecycle stage, its shape, and whether code can
reach it. Three resolve at different stages and in different shapes: the
per-call exclusion set, the startup projection relayed to an agent host,
and the `(server, tool)` pairs a dashboard tool-off writes to the global
`mcp.json`. Two more are deliberately left raw, one because it copies a
persisted key rather than resolving it and one because an operator needs
to see a stale spelling in order to re-key it.

The last surface is a hand-written block in an on-disk profile the backend
reads itself, and `acp/kas_agents.py` already states that Crew does not
relay it. Nothing here can expand a retired name in that file or warn the
operator holding one. So the best achievable end state for renaming a
published name is a known silent fail-open that cannot be closed -- the
complete job's residue, not a step toward it.

That makes such a rename a policy migration with a permanent remainder
rather than a legibility change, and it should be priced that way before
approval instead of discovered one surface at a time. The mispick the
rename would have prevented has not been observed. The tool descriptions,
this spec and the choosing prompts are all still available, and none of
them is name-keyed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants