Repository navigation
docs(monitoring): record why a published tool name is not renamed - #10945
chenmingwei23 merged 1 commit into
Conversation
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the rename-cost rule is findable by its stated consumer — a proposer renaming a non-monitoring tool never opens Suggestions
[DESIGN-REVIEWED] fe9f3f5 |
First Principles Review (Fable 5, fork) — ⏭️ skippedRevision |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed |
For a human reader, the shape of the decision: The lane is right that this PR's justification is a deduction. What it cannot Three ways this clears, all of them a maintainer's to pick:
What the rest of the review says, so the decision is made against the full Superseded on this point (head 6292125): #10940 merged as |
071b583 to
8d2ab40
Compare
Security Scope Review (fork) — 🟡 CONCERNSWhich legitimate operations does the reviewer's own judgement; no confirmed regression Scope-Verdict: CONCERNS TIGHTENING: ADJUDICATED: 12 candidates, 0 confirmed newly-refused PLATFORM COVERAGE: Candidates were written in all three spellings: 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.
[SCOPE-REVIEWED] 6292125Security scope review -- adjudicated candidates
No candidate flipped from allowed to refused. |
8d2ab40 to
6e667c0
Compare
|
|
|
|
|
6e667c0 to
e7877ee
Compare
|
|
e7877ee to
c971576
Compare
|
|
84eb739 to
ba06c18
Compare
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.
ba06c18 to
6292125
Compare
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.
6292125 to
fe9f3f5
Compare
|
cixuuz
left a comment
There was a problem hiding this comment.
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.
…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.
Problem / Motivation
monitor_startarms the in-session timer.monitor_watcharms theobservation-gated probe. Read cold, that is backwards.
startis the genericprimary 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.
patrolwould say what the timer actually does, andthe 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.pyalready 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_retirementmodule, 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:future task
operator restrictions mean
lifecycle stage, its shape, and whether code can reach it
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
this spec, and the prompts that choose between the two tools
Tests
No code changes, so no new tests. Verified on the head:
docs_lintpassesbase
cdb1613f8+49lines, and contains no occurrence ofmonitor_patrol,tool_retirement,widen_restrictionorRETIRED_TOOL_NAMEStest/test_monitor_start_ack.pyis present under its original name, so therename 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.