Repository navigation
fix(acp): spell a Crew agent's tools in KAS ids so the kas backend can read files - #13375
billygerhard wants to merge 1 commit into
Conversation
|
Intent: A Crew agent spec written in kiro-cli's tool vocabulary mounts the equivalent read/list/search/edit tools when the session runs on the KAS backend, so |
f0a94bb to
85d5210
Compare
Design Review (Opus 5.5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS This one PR changes how governance is judged for every harness (alias groups in Watch
[DESIGN-REVIEWED] 733b688 Description read[DESCRIPTION-READ] 04007b91c4c35e408da69ae50bfcc86a3bff024b532d8345b86585493be062e3 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 |
First Principles Review (Opus 5.5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS A separate Not justified as shipped
What this change shipsInventory (8 items) — 6 justifiedIntent: let a Crew agent on the
[FIRST-PRINCIPLES-REVIEWED] 733b688 Description read[DESCRIPTION-READ] a4d4ee3fa706addd754e7f3e65b6f70202acd519a0c0262e9f33b14271163d39 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
Live KAS hands-test evidenceReal engine: main behaviour (spec names sent verbatim){
"mode": "verbatim",
"agent_tools_sent": [
"execute_bash",
"fs_read",
"fs_write",
"code",
"grep",
"glob",
"web_fetch",
"web_search",
"introspect",
"session",
"report",
"tool_search"
],
"available_modes_include_probe": true,
"builtin_tag_classes_mounted": [
"read",
"shell",
"web",
"write"
],
"read_turn_stop": "end_turn",
"read_turn_tool_calls": [],
"read_turn_reply": "I don't have a dedicated file-reading tool available in this environment. The tools I have are shell execution, file writing, web fetch, and skill activation. Reading the file would require the shell, which you asked me not to use.\n\nWant me to read it with the shell instead?"
}this PR (projected){
"mode": "fixed",
"agent_tools_sent": [
"execute_bash",
"fs_read",
"read_file",
"list_directory",
"fs_write",
"str_replace",
"fs_append",
"code",
"grep",
"grep_search",
"glob",
"file_search",
"web_fetch",
"web_search",
"introspect",
"session",
"report",
"tool_search"
],
"available_modes_include_probe": true,
"builtin_tag_classes_mounted": [
"read",
"shell",
"web",
"write"
],
"read_turn_stop": "end_turn",
"read_turn_tool_calls": [
{
"title": "Read File",
"kind": "read",
"rawInput": {
"path": "/local/home/wilgerh/.kiro/crew/scratch/runtime-46d1d8f2/probe/work-fixed/probe-note.txt",
"offset": null,
"limit": null
},
"toolCallId": "toolu_bdrk_016rhF3M4bxN1MsdrBWLkbyL"
}
],
"read_turn_reply": "hello-from-kas-probe",
"delete_turn_tool_calls": [],
"delete_permission_frames": [],
"delete_turn_stop": "end_turn",
"victim_still_exists": true
} |
85d5210 to
79f02c2
Compare
|
self-added: yes
|
|
|
|
Security Scope Review (fork) — 🟡 CONCERNSWhich legitimate operations does the reviewer's own judgement; no confirmed regression Scope-Verdict: CONCERNS TIGHTENING: write-plane routing now treats the ACP
ADJUDICATED: 15 candidates, 0 confirmed newly-refused PLATFORM COVERAGE:
UNADJUDICATED:
[SCOPE-REVIEWED] 733b688Security scope review -- adjudicated candidates
No candidate flipped from allowed to refused. |
79f02c2 to
c3d667e
Compare
|
self-added: yes
|
|
|
|
|
Reviewed, not approving (crew-pr-reviewer). Very large (+6202/-202), and it changes how agent tool permissions are spelled for the kas backend. It needs a maintainer and a security owner. |
|
Reviewed on the maintainers' behalf (sweep 2026-10-06): every src/ hunk read; kiro-cli/claude/codex/goose paths verified unchanged, the KAS-only tightens accepted as bypass-closing, and the PR's 17 test files pass on the merge tree. Because this fork PR touches |
|
Rebased onto main at What moved, and nothing else changed in behaviour:
Local: the PR's 17 test files + #17280 carries the pre-refactor head; this one is ready to be re-taken if that is still the route. |
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
|
Rebased |
|
Rebased |
|
Rebased |
|
Pushed
What stays is the fix itself: the KAS tool-id projection, the kiro-cli-name alias fold for denies and |
|
Pushed |
|
This maps a Crew agent's tool names to KAS built-in ids so the kas backend can read, list and search files. It also changes the governance and permission evaluation: |
|
Rebased |
|
This PR projects a Crew agent's tool names into KAS ids so the kas backend can read, list and search files. Along the way it changes governance composition, the deny tiers and permission resolution. I am holding for four reasons. The Sensitive Change Review check is red on the current head 636110d. The diff (~3,276 lines, ~950 production lines) touches security policy in platform/governance.py, hook_runtime/gate_tiers.py, decisions/points/tool_risk.py and llm_helpers._resolve_permission. Three current-head lanes are CONCERNS. And the Design lane notes the body's "kiro-cli path is untouched" is not true: the _AndRuleset.permits/resolve change, the new alias_groups composition (OR across spellings within a layer, then intersection across layers) and TARGET_PATH_KEYS += "targetFile" apply to every harness. The specific risk I would want a security owner to rule on: OR-ing alias spellings within one layer must never let a rule that allows the KAS id outvote a deny written against the kiro-cli name in that same layer. Alongside the explicit_deny provenance, that needs a direct test per layer. First Principles also asks to split the delete_file write-plane routing (WRITE_PLANE_KINDS delete, tool_kind_cache, _trusted_delete) into its own PR, since the shipped spec never mounts delete_file. I agree, because it makes both halves reviewable. — crew-pr-reviewer |
iamwhatever
left a comment
There was a problem hiding this comment.
Deep re-review of a held PR. Not yet: GitHub shows a merge conflict (CONFLICTING / DIRTY) on head 636110d, and the Sensitive Change Review check is red. The goal is real: on the kas backend the shipped agent can't read files and falls back to shell cat/grep, which also skips read-only auto-approve. But the fix changes shared governance (_AndRuleset.permits/resolve, the alias_groups composition, TARGET_PATH_KEYS += "targetFile"), and that code runs on every harness, so the "kiro-cli path is untouched" claim is not true. Attack to settle before approval: in one layer, an allow on the KAS id and a deny on the kiro-cli name. OR-ing spellings inside a layer must never let the allow outvote the deny, and I found no test that pins that per layer. Security Scope, Design and First Principles are all CONCERNS on the current head. The hold reason still stands. Requested change: Rebase onto main. Add one test per governance layer: deny "fs_read" plus allow "read_file" in the same layer means KAS read_file is DENIED. Rewrite the Backwards compatibility section to list the alias loosening of allow-mode ceilings as a change that affects every harness. Move the delete_file write-plane routing (WRITE_PLANE_KINDS delete, tool_kind_cache, _trusted_delete) into its own PR. On the owner decision: Split out delete_file, since the shipped spec never mounts it. Keep the read/list/search alias fix here, after the security owner rules on deny-beats-allow inside a layer. Risk: high. — crew-pr-reviewer
|
Pushed
Locally: 3050 green across this PR's test files plus |
|
Re-rolled |
|
Re-rolled |
|
Re-rolled |
|
Pushed
Identical change otherwise. 3056 passed locally on the PR's test files ( |
|
Pushed |
|
Pushed |
|
Pushed |
…n read files Crew's agent spec is written in kiro-cli's tool vocabulary (fs_read, grep, glob, fs_write). KAS matches an allowlist entry against a tool's exact id and translates nothing, and on KAS fs_read/fs_write are policy capabilities rather than tool ids, so a stock spec projected verbatim mounted only the names shared by both engines: no read, list or search tool at all. Every chat on agent.acp_backend=kas ran read-blind and shelled out for reads. platform/tool_names.py holds the two engines' vocabularies as one table read in both directions, pinned to a recorded registry of the engine's built-in ids (test/fixtures/kas_builtin_tool_ids.json) and a measured kiro-cli version kirocrew doctor warns past. The KAS projection carries each kiro-cli built-in with its KAS family beside it (read_file, list_directory, grep_search, file_search, str_replace, fs_append); a mount family stops at what the kiro-cli tool can do, so delete_file mounts only when a spec names it, while an excludedTools entry reaches everything governed under the name. The PreToolUse gate reads the table the other way: a KAS built-in (no MCP server) is evaluated under its kiro-cli name in the deny tier, the tools-scope ceiling, and the read-only auto-approve classifier, so auto_deny_tools ["fs_write"] binds str_replace and ["execute_bash"] binds the shell's run_command, and a KAS read auto-approves under --approval reads where fs_read does. An MCP server's own read_file is not touched: KAS names the server on the tool_call as _meta.kiro.serverName and the tool on the permission request as _meta.kiro.mcpTool.identity, both read by _dispatch; a built-in stamps only _meta.kiro.toolId, read as the tool name when the cache holds none. A delete is on the write plane (WRITE_PLANE_KINDS), so delete_file's targetFile reaches the sensitive-path keystone and the write-protected-config tier in both gate planes.
|
Re-rolled |
Problem / Motivation
Goal: An agent spec written in kiro-cli tool names gives the
kasbackend's agent the same file-reading, listing and searching tools it has on kiro-cli, governed by the same operator rules.Set
agent.acp_backendtokasand every new chat runs read-blind. The agent can run a shell command and write a file, but it has no tool to read a file, list a directory, or search — it shells out withcatandgrepfor every read. Asked to read a file without the shell, a live KAS session on the shipped spec answers: "I don't have a dedicated file-reading tool available in this environment."Why it matters
The
kasswitch is offered in Settings (Developer mode) and crew-member DM sessions default to it. On that engine the shipped agent loses most of its file surface silently: no error, no warning, just a model that cannot read. Reads through the shell also bypass the read-only auto-approve path, so a--approval readsgateway prompts for what should have been free.Not a goal
delete_filein the shipped agent spec; it mounts only when a spec names it, and this PR only makes a mounted one governable.ACP_BACKENDS_PERMISSION_KIND_FROM_TOOL_CALLmembership set (KAS only): the permission-frame kind carry-over; on a kiro-cli session a tool_call frame stays kindless -- pinned intest_tool_call_classification.py(test_the_membership_gate_is_what_keeps_a_kiro_cli_edit_kindless,test_a_kiro_cli_search_stays_kindless_and_read_only_proven). The other mechanisms are keyed on what the frame carries, not on the backend. The identity read takes_meta.kiro.toolId/_meta.kiro.mcpTool.identityoff a permission frame (and_meta.kiro.serverNameoff a tool_call); kiro-cli stampstoolName/mcpServerNameinstead, so its request still reads through the first identity channel (test_a_kiro_cli_frame_still_reads_through_the_first_channel). The alias fold (GateFacts.policy_alias_names, the governance alias group) and the read-only proof's alias step (_is_host_read_only_builtin) read the provenance-trusted stamped tool id with an empty server name, so any harness whose_metaidentity channel stamps a bare KAS id (read_file,run_command,delete_file) gets the fold. They are a no-op on kiro-cli because no name kiro-cli stamps on its own built-ins (fs_read,execute_bash, ..., or itsread/write/shellspellings) is a key of the policy table -- pinned intest_tool_names.py::TestPolicyAliases::test_no_name_kiro_cli_stamps_on_its_own_built_ins_is_a_policy_key.kirocrew doctorreports drift, and the fixture's note says how to re-measure.Backwards compatibility
Not a pure superset: the kas backend's gate changes in four user-visible ways. Three hunks are shared by every harness, not KAS-only:
_AndRuleset.permits/resolveinplatform/governance.pynow query the inner ruleset even when the outer one refuses, so a composed decision carriesexplicit_denyprovenance (an outer allow-miss no longer hides an inner explicit deny);gate_decisionresolves an alias group as OR across spellings within one layer and intersection across layers (any explicit deny on any spelling is final, pinned per layer byTestGateDecisionAliasGroups::test_an_allow_on_the_kas_id_never_outvotes_a_same_layer_deny_on_the_kiro_cli_name); and"targetFile"joinsTARGET_PATH_KEYSinplatform/tool_paths.py. On kiro-cli the alias groups are empty and no kiro-cli tool spells its target astargetFile, so these hunks change no kiro-cli decision; they are cross-harness code, and a reviewer should read them as such.New refusals on KAS
delete_fileof a write-protected config (config.json,cloud.json, the trust roots) is DENIED, where before thedeletekind routed through no gate at all. Only when a spec mountsdelete_file; the shipped spec does not.delete_filewhosetargetFileis still relative after~/env expansion (../config.json) is DENIED as unverifiable, because the sensitive-path resolvers would judge it against the gateway CWD rather than the file the engine deletes. Edits keep judging relative params paths as before. The engine spells its write paths absolute (measured), so this does not fire on a real KAS write.auto_deny_tools: ["fs_read"]denies a KASread_file/grep_search/list_directory,["fs_write"]deniesstr_replace/fs_append/delete_file,["execute_bash"]deniesrun_command. Before, a kiro-cli-spelled deny did not bind on KAS at all. An operator who relied on that gap sees new denies.New admissions on KAS
toolsceiling or governance profile written in kiro-cli names (fs_write) now admits the KAS spelling of the same work (str_replace,fs_append) through the alias group, where before the raw KAS id was refused for not being listed. This is the intended fix (the ceiling binds to the tool the operator meant), and it is the one place the change permits more.delete_fileis excluded from that admission (POLICY_ALIAS_DENY_ONLY_IDS): afs_writegrant never becomes a deletion grant.read_file/grep_search/list_directoryis auto-approved under--approval readsexactly where kiro-cli'sfs_readis, because the read-only proof now reads the KAS id under its kiro-cli name.Unchanged: the KAS
tools/excludedToolswire lists are supersets of what was sent before, every added id is refused auto-approval and prompts, edits are judged exactly as before on every backend, andgate_decision's other callers see noalias_groups.Per reader of the changed seams:
hooks.on_tool_callwrite-protected tier (is_edit_call) — a KASdelete_fileof a config file is now DENIED where before thedeletekind routed nowhere; an edit is judged exactly as before. Pinned:test_hooks_edit_gate_diff_path.py::TestADeleteIsOnTheWritePlane.platform.governance.classify_tool_args(is_edit_call) — a delete's target now joins thefilesystem.writeset an ALLOW-mode confinement judges, instead of reaching it pathless; edits unchanged. Pinned intest_governance_policy.py.decisions/points/tool_risk.py— moved tois_workspace_edit_callso thecaution-badge carve-out stays edit-only and a delete keeps its badge; an edit's badge behaviour is unchanged. Pinned intest_decisions_tool_risk.py.gate_decision— its three other callers (governance.pyMCP probe,cli_commands.py, and every profile resolution without aliases) pass noalias_groups/deny_aliasesand evaluate exactly as on main; onlyhooks._governance_denialpasses them, for a KAS built-in whose id has a kiro-cli policy spelling. An outer refusal on any harness reports the sameexplicit_denyit did; the inner half is now asked too, which only ADDS a reason, never flips a verdict (test_governance_policy.py::TestGateDecisionAliasGroups).agent_sdk/spec_hooks.pyviakas_tool_match_names/KAS_TOOL_MATCH_VOCABULARY) andwithhold_hook_gated_auto_approval—KAS_TOOL_IDS_BY_KIRO_TOOLis now DERIVED from the policy table plus the hook-only rows instead of hand-written; its rows are set-equal to main's (main already carriedexecute_bash → run_command; only thefs_writetuple's order differs, andkas_tool_match_namessorts), so every matcher meets the same calls. Pinned:test_spec_hook_kas_tool_names.py.cli_doctor— a new advisory row; no verdict changes.What changed (motivation → approach → change)
Crew writes one agent spec,
src/kiro_crew/config/defaults.json, in kiro-cli's tool vocabulary:fs_read,fs_write,grep,glob,code._project_toolsinsrc/kiro_crew/acp/kas_agents.pysent that list to KAS as written. KAS matches an allowlist entry against a tool's exact id or a tag and translates nothing. On KAS,fs_readandfs_writeare policy capabilities, not tool ids, andgrep/globare no tool at all. So only the names both engines share mounted:execute_bash,fs_write,code,web_fetch, plus the MCP refs.One table, both directions.
src/kiro_crew/platform/tool_names.pyholds the two vocabularies, pinned to a recorded registry of the engine's built-in ids (test/fixtures/kas_builtin_tool_ids.json: engine commit, kiro-cli version, the two id spaces KAS has, and the ACP kind each built-in stamps). It is the ONE kiro-cli <-> KAS table: the spec-hook matcher vocabulary insrc/kiro_crew/acp/kas_permissions.py(KAS_TOOL_IDS_BY_KIRO_TOOL), which used to hand-keep the same rows, is now derived from this module's policy table (its inverse grouped per kiro-cli name, plus the three hook-only rows --web_fetch,web_search,use_subagent-- and the sharedfs_writeid), with a test asserting the two agree pair for pair. The projection carries each kiro-cli built-in with its KAS family beside it:fs_read→read_file,list_directory;grep→grep_search;glob→file_search;fs_write→str_replace,fs_append. A mount family stops at what the kiro-cli tool can do, sodelete_filemounts only when a spec names it; anexcludedToolsentry has the opposite polarity and reaches everything governed under the name, so excludingfs_writealso excludesdelete_file. Nothing on the kiro-cli path changes.The gate reads the table the other way. An operator's
auto_deny_toolsor atools-scope ceiling is written in kiro-cli names, soon_tool_callinsrc/kiro_crew/hooks.pyevaluates a KAS built-in under its kiro-cli name too, in three places: the deny tier (both spellings, since a deny only denies), thetools-scope ceiling (the raw KAS id and its kiro-cli name travel as ONE identity with two spellings,gate_decision's newalias_groups: an explicit deny on either spelling binds -- read from a newDecision.explicit_denyprovenance flag thatScopedRuleset.permitssets on a deny-mode match and that_AndRuleset.permitsandresolvecarry through every fold, with an outer allow-mode miss still consulting the inner half so a composed central+local ceiling or a profileextendscannot hide a subordinate tier's deny behind an authority's allow -- otherwise the group is judged per level, a level permitting any spelling and the identity admitted when every governing level does, so a ceiling grantingstr_replacebeneath a profile grantingfs_writeadmits the one tool both granted -- governance profiles are written in kiro-cli vocabulary and an allow-mode profile requires every queried item to match, so asking the raw id beside the alias would refuse a permitted write for an entry no operator wrote, while asking the alias alone would let a deny-modedeny: [str_replace]stop binding), and the read-only auto-approve classifier (_is_host_read_only_builtin) so a KAS read is free under--approval readsexactly wherefs_readis. One alias may only deny (POLICY_ALIAS_DENY_ONLY_IDS, split bypolicy_alias_split):delete_filereads underfs_writeso a write deny reaches it, but kiro-cli'sfs_writecannot delete -- the same line the mount table draws -- so an allow-modetools: ["fs_write"]written for kiro-cli must not become a deletion grant on KAS; the delete is asked on its own name andfs_writetravels ingate_decision'sdeny_aliases, consulted for an explicit deny only, never a permit.fs_writebindsstr_replace/fs_append/delete_file,execute_bashbinds the shell's permission idrun_command. Only for built-ins: KAS names an MCP server on the tool_call as_meta.kiro.serverNameand the tool on the permission request as_meta.kiro.mcpTool.identity, both read bysrc/kiro_crew/acp/_dispatch.py, so an MCP server's ownread_fileis seen as a served call and left alone. The request'sidentity.serverNameis never adopted as the call's server: the trust flag records the tool_call's cache hit, and a built-in's tool_call writes that hit with an empty server, so a server taken from the request would carry trust into the server-keyed grants (the app-own MCP auto-approve) for a built-in -- agreement with the cached server is a no-op, and a server the tool_call did not name is ignored. A built-in stamps only_meta.kiro.toolId, read as the tool name when the preceding tool_call wrote the identity cache with an empty name (the id fills that blank, and is not read on a request no tool_call preceded, such as a sub-agent spawn, whose identity comes from the consent classifier alone); it adds a deny target and cannot satisfy a trust-gated grant. ThetoolIdpasses_harness_identifier, the one length-and-spelling bound (128 characters, identifier characters only) that_permission_tool_idalready applied, so an oversized or glob-shaped id is read as absent; themcpTool.identitypair is read as the strings the harness wrote, like every other identity channel. The fold reads that identity and nothing else: the display title is the model's owndescription, so a shell call described asstr_replacefolds toexecute_bash, notfs_write, and adeny fs_writenever refuses a command the operator did not name.src/kiro_crew/cli_doctor.pyadds a KAS-block row that reports ✅ only when the installed kiro-cli is one of the releases the tables were verified on (KAS_TOOL_IDS_VERIFIED_ON_KIRO_CLI, pinned equal to the fixture'sverified_kiro_cli_versions: 2.24.0, where the id tables were first read; 2.24.1, where the write-plane path shapes were measured and the ids re-checked; and 2.27.1, the current release and the first above this repo's 2.27.0 kiro-cli floor, where every table was re-read against the extracted KAS bundle), and warns (advisory) for a release newer than the latest, older than the earliest, or between two verified ones and itself never measured -- a list, not an exact pin, and the fixture's engine-bump note now ends with the step that maintains it (re-measure, then append the release toverified_kiro_cli_versions), which the doctor row names: the policy direction fails permissive on an id a newer engine may have renamed, and an older engine was never measured, so it is unverified rather than compatible. The.github/black-baseline.txtentries fortest/test_cli_doctor.pyandtest/test_governance_policy.pyare pruned: the added test classes made each file fully black-clean, so the ratchet graduates them.A delete is on the write plane.
WRITE_PLANE_KINDSinsrc/kiro_crew/platform/tool_paths.pyadds the ACPdeletekind besideeditin the routing predicate the hook gate, the always-enforced tier (src/kiro_crew/llm_helpers.py) and governance share, andtargetFilejoinsTARGET_PATH_KEYS, so adelete_fileof the crewconfig.jsonis refused by the same write-protected-config hard deny an edit is, and a delete of an SSH key by the sensitive-path keystone. KAS'stargetFileis workspace-relative in its schema's terms, and the sensitive-path resolvers anchor a relative input to the gateway process CWD, so{"targetFile": "../config.json"}judged there would be a verdict about a different file from the one the engine deletes;edit_target_candidatestherefore withholds a params path that is still relative after~/env expansion and marks the unionunanchored(the flag the diff-block path already set, which the hook gate, the always-enforced tier and governance each hard-deny as unverifiable) -- but ONLY for the kinds inPARAMS_ONLY_TARGET_KINDS(delete): a delete carries no diff block, so its one params spelling is the call's whole target, while an edit also names its file in the diff block and its params spellings are judged verbatim as they always were, so an ordinary relativefile_pathon an edit is not refused on any backend. The kind is read off the ACPkindthe consumer routed on (the hook gate'stool_kind, the always-enforced tier'sevent.tool_kind, governance'stool_kind), never off the backend. That rule is also moot in practice on the kas write plane because the engine spells its write paths absolute: measured live (kiro-cli 2.24.1, engine 076b7d57b) through this PR's projection of the shipped spec, afs_writecreate, astr_replaceedit and afs_appendall completed under the carry-over withrawInput.pathabsolute (<workspace>/<file>), and adelete_file(spec extended to name it) put an absolutetargetFileon its frame -- recorded per write tool astool_call_path_shapein the fixture, matching the tools' own schema text ("Absolute path to the file"). A trusted delete gains the target gate and keeps its scan (it has no document body to suppress). Thetool.riskcaution-badge carve-out (src/kiro_crew/decisions/points/tool_risk.py) read the same predicate and would have dropped the badge on every delete; it now readsis_workspace_edit_call, the edit-only sibling added besideis_edit_call, so adelete_filekeeps itscautionbadge on the auto-approving sessions where the badge is the only signal (docs/system-specs/modules/decisions.mdupdated). The route has to be reachable from the wire, and on KAS it was not: KAS'srequest_permissionnames nokind(itstoolCallis id, status and title), so every KAS call reached the gate's kind-keyed tiers as"".build_permission_eventnow takes the kind the preceding tool_call frame carried, from atool_kind_cachewritten by_build_tool_call_eventbeside the params/shell/identity/diff-path caches (src/kiro_crew/acp/_dispatch.py), owned and cleared per turn byAcpSessionHandlebeside its siblings -- and it retains only a WRITE-PLANE kind (edit/delete). The engine's kind map (mapActionTypeToToolKind) stampssearchongrep_search,file_searchandlist_directoryandotheroncode/tool_search, recorded per built-in astool_call_kindintest/fixtures/kas_builtin_tool_ids.json, and a carriedsearchwould veto the host read-only proof that auto-approves a KAS search by identity, so every other kind is not written and the event stays""as before. Real classifications only, and a kind the permission frame does state is never overridden; a non-stringkindon the frame (an unvalidated harness value) is read as absent rather than stamped, and both write-plane predicates and the always-enforced tier's delete route test membership only on a string, so an unhashablekindclassifies instead of raising and aborting the turn. The cache is handed to the wire parsers per frame (AcpSessionHandle._tool_kind_cache_for_wire) only for members of a new capability setACP_BACKENDS_PERMISSION_KIND_FROM_TOOL_CALL(src/kiro_crew/agent_sdk/backends.py, KAS only; re-exported viaacp/types.pyandacp_backends.py, classified off-card inbackend_cards.py); the handle's construction is identical for every harness, and a non-member is handedNone, which disables both writer and reader: kiro-cli's permission frames omitkindtoo, but it routes edits by the diff content block already and its kindless governance classification is additive, so a carriededitwould change what its gate sees. The kiro-cli path (AcpClientand the non-member handle) is unchanged. The owning specdocs/system-specs/modules/security.mdrecords the write-plane kinds, the delete route, and the carry-over.flowchart LR subgraph Before a1[spec: fs_read, grep, glob]:::ctx --> a2[KAS matcher: exact id or tag]:::ctx --> a3[nothing mounted]:::removed end subgraph After b1[spec: fs_read, grep, glob, fs_write]:::ctx --> b2[tool_names: expand]:::added --> b3[read_file, list_directory, grep_search, file_search, str_replace, fs_append]:::added --> b4[KAS mounts them]:::changed b4 --> b5[permission frame _meta.kiro.toolId]:::added --> b6[gate: policy_aliases]:::added --> b7[deny / ceiling evaluated under the kiro-cli name too]:::changed end classDef added fill:#DCFCE7,stroke:#16A34A classDef changed fill:#FEF3C7,stroke:#D97706 classDef removed fill:#FEE2E2,stroke:#DC2626,stroke-dasharray:4 3 classDef ctx fill:#E0F2FE,stroke:#0284C7🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged
The spec's kiro-cli names arrive at KAS with the ids KAS registers, and a rule written in kiro-cli names still binds to them.
The
toolsrow insrc/kiro_crew/docs/agent-spec-fields.mdrecords the expansion and the exclusion polarity.Tests
test/test_tool_names.py— the two tables agree;delete_fileis governed as a write but mounted by no family; the shell'srun_commandis governed asexecute_bash; the exclusion reading withholdsdelete_fileunderfs_writeand equals the gate's policy table per owner name (execute_bashincluded) less the permission-frame-onlyrun_command, which the engine's exclusion matcher cannot see and whose registered owner already withholds; every mounted id is in the recorded engine registry, every policy key is an id the gate can receive, and every registered filesystem/shell id has a policy spelling or is listed as shared; the runtime's measured-version constant equals the fixture's;policy_aliasesdedupes and never echoes an input;policy_alias_splitfiles a same-capability alias (str_replace,read_file,run_command) as admitting anddelete_file's as deny-only, and the deny-only set equals exactly the policy keys outside every mount family;expandis pure and order-preserving.test/test_hooks.py::TestClassifierOnlyHostTrustedProof— a trusted KAS read built-in is proven read-only under its kiro-cli name (auto-approved under--approval reads); a KAS write/shell alias is not; a KAS read of a sensitive path is still denied first; the fold still demands trust and no server.test/test_tool_call_classification.py::TestKasMcpServedIdentity— a KAS MCP-servedread_file(server on the tool_call asserverName, the pair on the permission request asmcpTool.identity) reads as a server call, so a built-infs_readdeny does not bind and the read-only proof does not fire, while a@probefs/read_filerule does bind; a kiro-climcpServerNameframe still reads through the first channel; a malformed (non-string)server/toolhalf reads as absent, and a 129/300/512-character MCP tool name keeps its exact@server/<name>deny binding against a title-keyedauto_approve_toolsgrant.test/test_cli_doctor.py::TestTheKasBlockReportsToolVocabularyDrift— the measured engine is reported matching; a newer one and an older one each warn and name both versions (advisory, no issue; older is unverified, not compatible); an unknown version is its own row.test/test_tool_call_classification.py::TestKasPermissionFrameTakesTheToolCallKind— a KAS permission frame (no kind,toolIdonly) carries the tool_call's kind foredit/deleteand NOT forread/search/execute/fetch/other; the carried set is exactly the write plane and the fixture's per-built-intool_call_kindmap agrees (searchon all three search-shaped reads,readonread_file); a KASgrep_search/file_search/list_directorywhose tool_call stampedsearchstill auto-approves under the read-only proof with the cache present; without the cache the kind is""(the pre-fix shape); a kind the frame states is not overridden; a non-string frame kind is read as absent (the cached kind fills it, or""without one); placeholders are not cached; the cache retains only the closed write-plane vocabulary (a 1 MiBkindand every non-write kind retain nothing; the stored values are theedit/deleteliterals); end to end from the wire, a KASdelete_fileof~/.kiro/crew/config.jsonis denied by the hook tier and the same frame without the carry-over is not, and adelete_filenaming../config.json,../.kiro/crew/config.jsonornotes/plan.mdis denied as a relative target (a delete carries no diff block, so its relative params path is the unverifiable whole target).TestTheKindCarryOverIsKasOnly— the KAS handle hands its cache to the wire and every other backend's handle (and a runtime double with no backend) handsNone, with the attribute constructed identically on all; a kiro-clisearchtool_call followed by a kindless permission frame stays kindless and read-only-proven both without the cache (the kiro path) and with it (the reader withholdssearch); a kiro-cliedittool_call is what the membership gate keeps kindless (the reader would carry it).test/test_decisions_tool_risk.py— adelete-kind call atcaution0.99 under a trust policy still records its badge (a deletion is not the workspace edit the carve-out describes).test/test_hooks_edit_gate_diff_path.py—is_edit_callandis_workspace_edit_calldiffer only ondeleteand agree on every other kind/diff-path pair;WRITE_PLANE_KINDS == {edit, delete}.test/test_kas_agents.py::TestTheSpecIsSpelledInKasToolIds— each kiro-cli read tool carries its KAS family; the write family stops atstr_replace,fs_appendand projects nofs_writeallow rule;delete_filemounts only when named; the spec's own name is kept; shared names and@refspass through unchanged; a spec already in KAS ids is not duplicated; excludingfs_writealso excludesdelete_file; the table names only registered ids (from the fixture).test/test_kas_agents.py—TestToolsFailClosedpins the mixed spec's projection to its exact list;TestAgainstTheRealBundledSpecpins the shippeddefaults.jsonprojection exactly toexpand_kiro_cli_tool_names(spec["tools"]), with the read family present anddelete_fileabsent.test/test_hooks.py::TestKasAliasesAreGovernedUnderTheirKiroCliName—auto_deny_tools: ["fs_write"]deniesstr_replace,fs_append,delete_fileby engine-stamped identity; a model-authored title spelling a KAS id never folds, and an identified shell call (run_command/execute_bash) titledstr_replaceis not refused by a write rule but is by a shell rule;fs_read/grep/globrules deny their KAS read aliases; the governancetoolsscope is askedstr_replaceandfs_writeas one alias group (also when the title is the raw id), and through the realgate_decisionan allow-mode profile of {title,fs_write} permits the KAS write, a deny-mode profile denying either spelling refuses it, and a raw-idauto_deny_toolsstill binds; a KASdelete_fileis asked on its own name withfs_writedeny-only (no alias group), and through the real gate an allow-mode {title,fs_write} refuses the delete while admittingstr_replace, namingdelete_fileadmits it, and a deny underfs_writerefuses it;test/test_governance_policy.py::TestGateDecisionAliasGroups— allow-mode in either vocabulary admits, neither spelling listed refuses naming the kiro-cli name, deny-mode on either spelling binds withrule1-deny, a ceiling deny on the raw id is final, a subordinate deny folded under an allow ceiling (either fold order) still binds and answers the same as a single-tier ceiling, a centraldelete_filedeny folded with a localfs_writeallow (either order) refuses the delete on its own name, an allow-modefs_writegrant does not admit the delete (an allow-set miss, not a written deny), an allow set namingdelete_fileadmits it without namingfs_write, a deny under the deny-only alias binds, a sibling verb's deny does not reach it, and a permitted deny-only alias never admits; deny provenance survives every fold while an allow-mode miss never gains it, a title equal to a group member is covered by the group, empty groups are ignored, each level granting a different spelling admits the one tool (either way round), a level granting neither spelling still refuses, and a profile deny is reported over a ceiling allow-miss; a shared name gains no alias and is not asked twice; an MCP-servedread_file/str_replacegains no alias at either tier while a@filesystem/read_filerule still binds.test/test_hooks.py— a sensitive path undertargetFileis denied like the other spellings; a KASdelete_fileon an AWS credentials path is denied; an ordinarytargetFileis still allowed.test/test_hooks_edit_gate_diff_path.py::TestADeleteIsOnTheWritePlane— a delete ofconfig.json/cloud.json/playwright-cli-config.jsonis denied by the write-protected tier; an ordinary delete passes; a delete naming no target is denied; the read allowance is untouched.TestADiffBlockRoutesOntoTheWritePlane— a non-stringkind(list, dict, number,None) classifies as "not on the plane by kind" in both readings instead of raising, and a diff block still routes it.TestARelativeParamsPathIsUnverifiableOnlyWhereItIsTheWholeTarget— a relativetargetFileon a delete, alone or beside a safe absolute one, is denied by the hook gate and the always-enforced tier as a relative target and an absolute one is judged on its merits; a relativepath/file_pathon an ordinary edit is NOT refused by either tier; a relative diff-block path is still denied whatever the params say; a~-spelled delete target stays anchored;edit_target_candidateswithholds the relative spelling and setsunanchoredfor thedeletekind only (PARAMS_ONLY_TARGET_KINDS == {"delete"}) and judges it verbatim foreditand for an unknown kind; governance emits the never-permittable marker for a delete and the verbatim path for an edit.test/test_cli.py::TestChatPermissionRequest— through the production direct-client parser and the CLI consumer, a trusted edit of an absolute path and a trusted edit of a relative one each reach the human and are approved (the relative edit is the routine shape on every backend); the cache-miss pin now names an absolute inline path so what it asserts is provenance (unverified_shell), not a target denial.test/test_spec_hook_kas_tool_names.py::test_the_hook_rows_are_the_gate_s_policy_table_inverted— every policy-table pair appears in the hook matcher rows and every row entry outside the hook-only tools is a policy-table pair (plus the sharedfs_writeid).test/test_llm_helpers_edit_gate.py::TestADeleteIsGatedOnItsTarget— the always-enforced tier refuses a trusted delete ofconfig.json, allows an ordinary one, does not target-gate an untrusted frame on its own word, and still runs the scan on a delete.test/test_llm_helpers_mcp_document_body_real_frames.py::TestKasReadsTheSameBarFromItsOwnFrames— on captured kiro-cli 2.27.1 KAS frames, a residentknowledge_add_documentcall reaches the document-body exemption on the pair the permission frame states and the tool_call's server confirms (approved; the pre-PR pin had this fail-closed because no KAS identity was parsed); a deferred call's nested body keeps the full scan (denied); a request naming a server the tool_call did not is denied; a benign body is approved in both modes.test/test_tool_call_classification.py::TestKasPermissionFrameCarriesTheBuiltinId— a KAS permission frame's_meta.kiro.toolIdbecomes the event's tool name; a cachedtoolNamewins over it; malformed ids are ignored (non-strings, blanks, one over the 128-character bound, a 100 KiB id, a glob, whitespace), the bound is exactly_permission_tool_id's, and a malformedmcpTool.identityfield reads as absent (the cached server and thetoolIdstand); a frame no tool_call preceded (a sub-agent spawn's synthetic toolCallId) is not named by its raw id -- the consent classifier's verified Crew name or nothing -- and a built-in id with no preceding tool_call is not named either; the frame id cannot satisfy the spawn rung or the identified-MCP-call reader; end to end,auto_deny_tools: ["fs_read"]denies a KASRead Filepermission from the frame alone.test/fixtures/acp_frames/kas/session.expected.jsonre-recorded for the same reason.test/test_kas_mode_binding.py— the injected agent's wiretoolslist carries the family besidefs_read.Mutation-probed: emptying the mount table fails 8; re-adding
delete_fileto thefs_writefamily fails 3; removing the deny-tier alias fold fails 8; feeding the title back into the fold fails 2 and also dropping its identity guard fails 5; removing the governance alias fold fails 1; appending the alias beside the raw id in the governance query (requiring every spelling) fails 4; dropping the explicit-deny short-circuit in the alias group (alias-only semantics) fails 4; hiding the inner half's deny behind an outer allow-miss fails 2; resolving each spelling through the intersection instead of per level fails 3; emptying the deny-only alias set (routingdelete_filethrough the admitting group) fails 4; letting the deny-only channel refuse on an allow-set miss fails 2; dropping themcpServerNameguard fails 2; using the mount reading forexcludedToolsfails 1; emitting permission-frame-only ids in exclusions fails 2; disabling the permission-frame id read fails 5; reading the frame id on a request no tool_call preceded fails 10; revertingWRITE_PLANE_KINDStoeditonly fails 5; droppingrun_commandfrom the policy table fails 2; removing the read-only classifier alias fold fails 5; removing the KASserverNameidentity channel fails 1; neutralizing themcpToolidentity read fails 1; disabling the doctor newer-engine warning fails 1; restoring<=in the doctor row fails 1; comparing drift against the single first-measured release instead of the verified list fails 3; disabling the permission-frame kind carry-over fails 5; caching theunknownplaceholder fails 1; handing the kind cache to every backend's wire fails 4; routing a delete into the caution-badge carve-out fails 1; stamping a non-string framekindon the event fails 5; testing write-plane membership without the string guard fails 3; appending a delete's relative params path to the target set instead of withholding it (emptyingPARAMS_ONLY_TARGET_KINDS) fails 5; retaining every non-placeholder kind in the cache instead of the write-plane vocabulary fails 8; droppingdelete_filefrom the derived hook rows fails 1; reading the frametoolIdwith a plain strip instead of the identifier bound fails 5.Manual verification
Live hands-test against the real engine (
kiro-cli acp --agent-engine v3 --auth-method cli, kiro-cli 2.24.0, the kas backend's own argv), driven over stdio with the shippeddefaults.jsonprojected throughto_client_custom_agent, injected as a client custom agent, activated, then prompted to read a file using a file-reading tool and not the shell:toolson the wireexecute_bash, fs_read, fs_write, code, grep, glob, …… fs_read, read_file, list_directory, fs_write, str_replace, fs_append, … grep, grep_search, glob, file_search, …tool_callframes on the read turnRead File, kindread,rawInput.path= the filehello-from-kas-probe(the file's contents)delete_filea path under.ssh/delete_fileis not mounted byfs_write)Both JSON reports are posted as a PR comment.
The per-built-in ACP kind recorded in the fixture was read from the engine source at the measured commit (
packages/kiro-agent/src/acp/session-update-utils.tsmapActionTypeToToolKind, keyed by each tool file'sactionType):list_directorystampssearch, notother, which is why the carry is confined to the write plane rather than to "everything butsearchon the two grep-shaped tools".Write-plane hands-test (kiro-cli 2.24.1, same argv, this PR's projection of the shipped spec, a fresh workspace, every permission answered allow): "create probe-created.txt" →
Write File(fs_write, kindedit,rawInput.pathabsolute) and the file exists; "replace alpha with alpha-edited in probe-note.txt" →Read FilethenReplace in File(str_replace, kindedit, absolutepath) and the line is edited; "append gamma" →Append to File(fs_append, kindedit, absolutepath) and the line is appended; "delete probe-victim.txt" with the spec as shipped → no tool call, file untouched (not mounted); withdelete_fileadded to the spec →Delete File(delete_file, kinddelete, absolutetargetFile) and the file is gone. Every permission frame carried_meta.kiro.toolIdand nokind. Recorded per write tool astool_call_path_shapein the fixture.Re-measured on kiro-cli 2.27.1 (the extracted KAS bundle kiro-cli runs,
@kiro/agent0.66.22, read directly rather than through a live model turn): everyregisteredid is present and none is renamed; the shell's static id is stillrun_command; theactionType→ ACP-kind switch is byte-identical to the 2.24.1 bundle's for every kind the fixture records; each built-in's permission request still stamps_meta.kiro.toolIdwith its own class id; and the path-parameter descriptions that produced the absolute shapes are unchanged. 2.27.1 is appended toverified_kiro_cli_versions(and the pinned constant), with the reading recorded under the fixture'sremeasuredkey. 2.27.0 was not measured and staysunverified.Related Issues
no linked issue: found while hands-testing the
kasbackend; no open issue reports it.Pattern harvest
Rule candidate: review-prompt
Pattern: a spec or policy written in one engine's tool vocabulary is applied to another engine's allowlist or name-keyed gate without translation; check the target engine's matcher when a backend switch is added, and translate in both directions (mount AND govern).
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)