diff --git a/docs/system-specs/modules/subagent.md b/docs/system-specs/modules/subagent.md index f4da69852b8b..ef33d2b03d5e 100644 --- a/docs/system-specs/modules/subagent.md +++ b/docs/system-specs/modules/subagent.md @@ -1539,7 +1539,10 @@ made; no gate reads it back. Two consumers: kiro-cli defines `toolsSettings.subagent.availableAgents` for its own built-in `subagent` tool: a glob list of the agents an agent may spawn, and **omitting it -allows all**. Kiro Crew's sub-agents come through `spawn_run` / +allows all**. It is read under every sub-agent spelling kiro-cli accepts +(`crew`, `agent_crew`, `agentCrew`, `subagent`, `use_subagent`); as in +kiro-cli, the first one the spec sets wins whole and the rest are ignored +(`spawn_allowlist`, through `canonical_tools_settings`). Kiro Crew's sub-agents come through `spawn_run` / `spawn_sub_agents` rather than that tool, so the gate honours the same declaration itself (`subagent._vet_parent_available_agents`, called from `spawn_impl` right after `_vet_spawn_governance`): diff --git a/src/kiro_crew/acp/kas_agents.py b/src/kiro_crew/acp/kas_agents.py index 8712e7bae6b5..49beddb351a4 100644 --- a/src/kiro_crew/acp/kas_agents.py +++ b/src/kiro_crew/acp/kas_agents.py @@ -180,6 +180,7 @@ expand_kiro_cli_tool_exclusions, expand_kiro_cli_tool_names, ) +from kiro_crew.platform.tools_settings_aliases import as_authored from kiro_crew.sel import sel from kiro_crew.user_json import copy_json_document @@ -277,19 +278,19 @@ def spec_keys_without_carrier( lost.append("toolAliases") if discards_mcp_oauth: lost.extend(oauth_lost_keys(servers_with_discarded_oauth(spec, _registry_governed))) - tools_settings = spec.get("toolsSettings") + raw = spec.get("toolsSettings") if not translates_tools_settings: - lost.extend(tools_settings_unapplied(tools_settings)) + lost.extend(tools_settings_unapplied(raw)) return sorted(lost) - # kiro-cli reads one spelling per alias group; the dropped ones are named. - tools_settings, dropped = canonical_tools_settings(tools_settings) + # kiro-cli reads one spelling per alias group; each name is the one the spec wrote. + tools_settings, dropped = canonical_tools_settings(raw) lost.extend(f"toolsSettings.{key}" for key in dropped) _, not_carried = tools_settings_to_permissions(tools_settings) - lost.extend(f"toolsSettings.{path}" for path in not_carried) + lost.extend(f"toolsSettings.{as_authored(raw, path)}" for path in not_carried) if spec.get("permissions") is not None and not projection_accepts(spec["permissions"]): lost.append("permissions") lost.extend( - f"toolsSettings.{path}" + f"toolsSettings.{as_authored(raw, path)}" for path in trusted_agents_withheld(tools_settings, may_skip_gate_now) ) if ( @@ -301,7 +302,7 @@ def spec_keys_without_carrier( # Every entry is usable, but the session answers none of them: name each # shell key that carries one, so the operator learns why they prompt. lost.extend( - f"toolsSettings.{key}.allowedCommands" + f"toolsSettings.{as_authored(raw, key)}.allowedCommands" for key in ("execute_bash", "shell") if isinstance(tools_settings.get(key), dict) and tools_settings[key].get("allowedCommands") @@ -312,7 +313,7 @@ def spec_keys_without_carrier( and _allowed_commands_withheld(spec, None, tools_settings, "fs_write") ): lost.extend( - f"toolsSettings.{key}.allowedPaths" + f"toolsSettings.{as_authored(raw, key)}.allowedPaths" for key in ("fs_write", "write") if isinstance(tools_settings.get(key), dict) and tools_settings[key].get("allowedPaths") ) diff --git a/src/kiro_crew/agent_sdk/kas_tool_view.py b/src/kiro_crew/agent_sdk/kas_tool_view.py index 7a71473d821e..5b3909f51ce2 100644 --- a/src/kiro_crew/agent_sdk/kas_tool_view.py +++ b/src/kiro_crew/agent_sdk/kas_tool_view.py @@ -184,9 +184,11 @@ def tools_settings_unenforced(raw: Any) -> list[str]: cannot turn into a rule (a regex with no glob form, a URL pattern naming a path) and an ``allowedCommands`` entry Crew's gate cannot answer are named, and so is a duplicate alias key kiro-cli drops (``canonical_tools_settings``). + Each entry is named under the spelling *raw* wrote (``aliases.as_authored``). """ from kiro_crew.acp import kas_permissions + from kiro_crew.platform import tools_settings_aliases as aliases settings, dropped = kas_permissions.canonical_tools_settings(raw) _block, not_carried = kas_permissions.tools_settings_to_permissions(settings) - return sorted(set(not_carried) | set(dropped)) + return sorted({aliases.as_authored(raw, path) for path in not_carried} | set(dropped)) diff --git a/src/kiro_crew/agent_sdk/tools_settings_reach.py b/src/kiro_crew/agent_sdk/tools_settings_reach.py index 0dc8b0694d62..e8d1c219d671 100644 --- a/src/kiro_crew/agent_sdk/tools_settings_reach.py +++ b/src/kiro_crew/agent_sdk/tools_settings_reach.py @@ -16,7 +16,7 @@ from typing import Any -from kiro_crew.platform.tools_settings_aliases import canonical_tools_settings +from kiro_crew.platform.tools_settings_aliases import as_authored, canonical_tools_settings #: The ``toolsSettings`` tool key whose ``availableAgents`` Crew's spawn gate reads. _SPAWN_GATE_TOOL = "subagent" @@ -52,18 +52,22 @@ def _gate_applied_keys(tools_settings: dict[str, Any]) -> set[tuple[str, str]]: def _unapplied_beside_gate( - tools_settings: dict[str, Any], applied: set[tuple[str, str]] + tools_settings: dict[str, Any], applied: set[tuple[str, str]], raw: dict[str, Any] ) -> list[str]: - """Each set ``toolsSettings`` entry but the *applied* allowlist keys.""" + """Each set ``toolsSettings`` entry but the *applied* allowlist keys. + + *tools_settings* is the folded form of the spec's *raw* field; each name uses + the spelling *raw* wrote. + """ lost: list[str] = [] for tool, entry in tools_settings.items(): if not entry: continue if not isinstance(entry, dict): - lost.append(f"toolsSettings.{tool}") + lost.append(f"toolsSettings.{as_authored(raw, tool)}") continue lost.extend( - f"toolsSettings.{tool}.{key}" + f"toolsSettings.{as_authored(raw, tool)}.{key}" for key, value in entry.items() if value and not (tool == _SPAWN_GATE_TOOL and key == _SPAWN_GATE_KEY) @@ -89,28 +93,31 @@ def tools_settings_unapplied(tools_settings: Any, *, gate_allowlists: bool = Fal Read with one key per kiro-cli alias group, as the gates read it (:func:`~kiro_crew.platform.tools_settings_aliases.canonical_tools_settings`); - each dropped spelling is named as ``toolsSettings.``. + each dropped spelling is named as ``toolsSettings.``, and a kept one + under the spelling the spec wrote (``toolsSettings.use_subagent.``, not + the ``subagent`` it is read as). """ if not tools_settings: return [] if not isinstance(tools_settings, dict): return ["toolsSettings"] - tools_settings, dropped = canonical_tools_settings(tools_settings) + raw = tools_settings + tools_settings, dropped = canonical_tools_settings(raw) applied = _gate_applied_keys(tools_settings) if gate_allowlists else set() if applied: - lost = _unapplied_beside_gate(tools_settings, applied) + lost = _unapplied_beside_gate(tools_settings, applied, raw) return sorted({*lost, *(f"toolsSettings.{key}" for key in dropped)}) gated = tools_settings.get(_SPAWN_GATE_TOOL) if not isinstance(gated, dict) or _SPAWN_GATE_KEY not in gated: return ["toolsSettings"] lost = [f"toolsSettings.{key}" for key in dropped] lost += [ - f"toolsSettings.{tool}" + f"toolsSettings.{as_authored(raw, tool)}" for tool, entry in tools_settings.items() if entry and tool != _SPAWN_GATE_TOOL ] lost.extend( - f"toolsSettings.{_SPAWN_GATE_TOOL}.{key}" + f"toolsSettings.{as_authored(raw, _SPAWN_GATE_TOOL)}.{key}" for key, value in gated.items() if value and key != _SPAWN_GATE_KEY ) diff --git a/src/kiro_crew/docs/agent-spec-fields.md b/src/kiro_crew/docs/agent-spec-fields.md index b27d3c912ed0..bcfe43364cdd 100644 --- a/src/kiro_crew/docs/agent-spec-fields.md +++ b/src/kiro_crew/docs/agent-spec-fields.md @@ -534,7 +534,7 @@ unconfirmed. | `allowedTools` | list | What is AUTO-APPROVED. Entries are globs, not names: `@srv`, `@srv/`, `@srv/*` all match the whole server (`_canonical_grant_pattern`). This is the ONE path that never reaches Crew's PreToolUse gate, so every writer filters it through the governance ceiling (`_apply_allowed_tools_ceiling`) and the KAS projection re-filters on read (`_ceiling_permitted`), because a file can predate the ceiling that now governs it. The file-tool built-ins `grep`, `glob`, `code`, `fs_read`, `fs_write` and `execute_bash` are withheld even on a host with no ceiling, because a grant here would skip the sensitive-path and denied-command checks. Crew's own gate approves the read-only `grep` and `glob` calls, and the tree-sitter lookups of `code`, without a prompt once those checks pass, when every path they name is absolute and holds no credential store. | | `excludedTools` | list | A RESTRICTION, subtracted after `tools`. `spec_grants_tool_search` reads it: a spec that grants `"*"` then excludes `tool_search` grants no loader. Mirrored onto the worker spec alongside the grants, so "superset of what the default grants" cannot quietly become "superset of what it permits". | | `permissions` | object | KAS's own currency: `{"rules": [{"capability", "match", "effect"}]}`. Crew WRITES this derived from `allowedTools` (`derived_agent_permissions`) **only when the program that reads the spec accepts the field** (`auto_approve._spec_permissions_accepted`). On the relay route (`agent.kas_bundle` off) that is the installed kiro-cli: `spec_permissions_supported(installed_kiro_cli_version())`, floor `SPEC_PERMISSIONS_MIN_VERSION` (2.23.0) in `kiro_cli.py`. kiro-cli validates specs with `deny_unknown_fields`, so a release below the floor refuses the WHOLE file and drops every Crew MCP server; an unknown version (no pinned binary, refused or unparseable `--version`) withholds too. With `agent.kas_bundle` on, Crew's own installed engine bundle reads the spec too, so the engine's version must also pass: `installed_bundle().version` against `KAS_SPEC_PERMISSIONS_MIN_ENGINE_VERSION` (0.66.33, the pinned engine) through `kas_pin.engine_spec_permissions_supported`; no engine installed or one below the floor withholds. kiro-cli's gate still applies whenever kiro-cli is installed, since it reads the same files for every other backend; a host with no kiro-cli is not probed and gets the block from the engine alone. The default spec's seed (`_seed_kas_permissions`) preserves an existing block before calling the shared gate (`_write_derived_permissions`), so a block already on disk is never removed by seeding; `kirocrew setup --agent-only --clean` repairs a default spec an older release already refuses. Generated conductor and worker writers use the same gate to replace an inherited value on an accepting release and remove it on an older or unknown one. Fork and publish (`_align_permissions` in `agent_capabilities.py`) route the TARGET block through the same `_write_derived_permissions`, so the published spec carries it only when every reader accepts it (kiro-cli on the relay route; the installed engine, plus kiro-cli when installed, with `agent.kas_bundle` on) and has it removed otherwise; the review of the SOURCE block described below runs whatever the version. `kirocrew doctor` prints the verdict as the KAS block's `auto-approve:` row. A block in the file is not an input to DERIVATION, which reads `allowedTools` and nothing else — but on the wire it is a second input, merged by `merge_user_permissions`: parsed against KAS's own shape and refused whole when it does not fit (a `match` over `_MAX_PATTERNS_PER_RULE` patterns is sent as several rules with the same capability, effect and `exclude` instead, and an `allow` whose `exclude` is over it is left out alone), `deny`/`ask` relayed unconditionally, `allow` relayed only where the same ceiling permits that capability and that resource, the shell and filesystem families never relayed as an `allow` (Crew's gate answers an unscoped one, and a `shell` allow's `match` globs, itself after its own checks: `docs/system-specs/modules/security.md` § KAS spec built-in grant), and an `allow` the `allowedTools` derivation could have emitted itself not relayed at all when the spec carries such a list — that list is the governed input and is re-derived every projection, so a block that has gone stale against it (including one the seeder wrote and preserved) cannot put a revoked grant back. Every decision, relay and withhold alike, is recorded in the security event log. Without that merge a pure-KAS agent — `permissions` authored, no `allowedTools` — reaches the backend with the field absent, and absent resolves every request to `ask`. On disk the block is left untouched and the backend reads it. One path does read it: fork and publish (`agent_capabilities.py`, `_align_permissions`) compares it against a fresh derivation and refuses with `alternate_permissions_require_review` when the two disagree, so a hand-edited block blocks forking that template. `src/kiro_crew/acp/kas_permissions.py` owns the translation, and refuses the shell and filesystem families outright: a tool-name allowlist carries no resource pattern, so the rule it would produce is unscoped. | -| `toolsSettings` | object | Per-tool settings kiro-cli reads. Crew strips exactly two retired keys on every refresh — `execute_bash`/`shell` `deniedCommands` and `autoAllowReadonly` — because denied commands are enforced only at Crew's PreToolUse gate now, and a stale copy in the spec would keep blocking a built-in the user just re-enabled (`_strip_legacy_denied_commands`). Your other keys are preserved. One key Crew READS: `subagent.availableAgents`, kiro-cli's glob allowlist of what this agent may spawn, is honoured at Crew's own `spawn_run` / `spawn_sub_agents` gate too (those bypass kiro-cli's built-in `subagent` tool) — declared, the target must match a glob; omitted, everything is allowed, as upstream. The gate reads the spec in `~/.kiro/agents` AND, when it knows the parent session's project directory (the live session's cwd and the chat slot's project, or a sub-agent's cwd), in `/.kiro/agents`; a declaration in any scope applies, so a project spec can only narrow what the user-level one allows. When the project directory is unknown and no user-level spec names the parent, a project-scope declaration is not honoured: Crew logs a warning and writes a `parent_spec_unresolved` security event instead of refusing. `subagent.trustedAgents` is a trust grant ("no permission prompts"), not an allowlist, and is not read as one. Details: `docs/system-specs/modules/subagent.md` § Parent agent spec allowlist. No KAS wire slot, so on KAS Crew translates it into `permissions` rules (`kas_permissions.tools_settings_to_permissions`, following KAS's own migration mapping) and merges them like an authored block: `deniedPaths` (read/glob/grep → `fs_read`, write → `fs_write`), `deniedCommands` and `web_fetch.blocked` become `deny` rules. `subagent.availableAgents` becomes a `subagent` `deny` over `"*"` with the listed names in `exclude` (`[]` denies every sub-agent), and `subagent.trustedAgents` a name-scoped `subagent` `allow` that the governance ceiling must permit, both run live on KAS (#25320); a name pattern travels when it is an agent id with `*` as its only wildcard. `write.fallbackAction: "deny"` travels as no rule: Crew's own gate refuses every file write of that agent whose target none of its `allowedPaths` covers, on every approval mode (a scheduled job with `approval_mode: auto` included). Entries are read like kiro-cli's globs (`*` and `**` cross `/`, `?`, a leading `~`, a relative entry anchored at the session's directory, a directory covering what is inside it); an entry with `[`, `{`, `\`, `$` or a `~user` covers nothing, and a write through a symlink must be covered at its real path too. A covered write runs without a prompt, as on kiro-cli (below). `shell.denyByDefault` travels as no rule either: Crew's own gate refuses every shell command of that agent that none of its `allowedCommands` matches whole, on every approval mode (a scheduled job with `approval_mode: auto` included), unless the agent's `allowedTools` names the shell by its exact name (`execute_bash`, `shell`, `@builtin`, `@builtin/*`, or `@builtin/` followed by one of the two names; a `*` or `?` pattern grants nothing): as on kiro-cli, such an agent runs any command its `deniedCommands` do not deny, prompting as usual. That holds only while every `deniedCommands` entry travels as a KAS deny rule; one that cannot (a regex with groups or alternation, a redirect) keeps the refusal. Without that entry, a command that redirects or substitutes counts as unmatched, and a chain split at `&&`, `||`, `;` and `|` matches only when an entry matches every part whole and the chain holds no quote, backslash, non-ASCII character or PowerShell `--%`. An `allowedCommands` entry outside the syntax Crew reads like kiro-cli allows nothing under `denyByDefault`, so its commands are refused, and the notice names it. Crew reads literals, escaped ASCII punctuation, `.`, bracket classes (`[A-Za-z0-9_./-]`, `[^;]`), groups `( )` / `(?: )`, alternation `\|` and the repeats `*`, `+`, `?`, with optional `^`/`$` at the two ends; it refuses POSIX classes (`[[:alpha:]]`), `\d`/`\w`/`\b`, counted repeats (`{1,3}`) and flags (`(?i)`). A command's `( )` and `{ }` count only inside a single- or double-quoted argument of an all-ASCII command with no backslash (`git commit -m "fix(x): y"`); `; & \| < > $` and backticks are refused even inside quotes. A regex becomes a glob only when it is a literal plus `.*` with no character KAS reads as glob syntax, and a pattern over the merge's length bound is dropped rather than refusing the whole block. KAS matches a shell rule against the command's words, and a redirect and its target are not among them, so a `deniedCommands` glob holding `<` or `>` still travels as a deny (it stops that character inside a word) but is also named in the notice: it does not stop `cmd > file`. The same holds for an authored `permissions` shell deny. `shell.allowedCommands` travels as no rule: Crew answers a matching command's permission request itself, after its deny floor and governance, never for a command that redirects or substitutes, and for a chain only when an entry matches every part whole and the chain holds no quote, backslash, non-ASCII character or PowerShell `--%` (`docs/system-specs/modules/security.md` § KAS spec built-in grant). A `deniedCommands` or write `deniedPaths` beside a grant keeps it prompting only when Crew cannot read every entry itself; otherwise Crew's gate refuses what a deny names and answers the rest of the grant without a prompt, as kiro-cli does. Such a command still asks, and the card says why: run the script alone, or move the pipeline into the script. `denyByDefault` and `autoAllowReadonly` beside `allowedCommands` keep the grant, as on kiro-cli; any other key beside it keeps those commands asking, and a `deniedCommands` is read as said above. `autoAllowReadonly: true` is carried by Crew's own read-only auto-approve, and beside `denyByDefault` a read-only command is let through instead of refused, as kiro-cli runs it. A write `allowedPaths` travels as no rule either: Crew answers a write whose every target an entry covers itself, whether or not `allowedTools` lists the write tool, unless a `deniedPaths` or another key on the write tool restricts it. The other allow lists (`read.allowedPaths`, `web_fetch.trusted`), `allowReadOnly`, `use_aws` and any pattern that does not translate are not carried, so those calls keep prompting; the KAS chat shows one notice at session start naming exactly those entries. goose and opencode never receive the rules, so their notice still names `toolsSettings` whole. No other mirrored harness applies the field: a new chat session on codex, copilot or deepseek whose spec sets it gets the same one-row notice naming `toolsSettings` whole (`spec_hooks.spec_tools_settings_applied_nowhere`; see the per-harness rulings, note 11). On `claude` the same two gate rows refuse what `shell.denyByDefault` and `fallbackAction: "deny"` do not allow, on every approval mode: the client reads both allowlists from the spec it projects and stamps them on its session's requests, a native sub-agent's included, and the settings seed adds `permissions.ask` rules for `Bash` and the file-write tools while either is set, so claude asks about those calls. With no KAS policy there, an `allowedTools` naming the shell lifts `denyByDefault` only when the spec has no `deniedCommands`. A session in `bypassPermissions` skips the ask. `deniedPaths`, `web_fetch.blocked` and the other entries are not carried on `claude` (`docs/system-specs/modules/security.md` § claude spec allowlists). A new claude chat session's notice therefore names only what of the field it still does not apply, never a `shell.denyByDefault` or `fallbackAction: "deny"` allowlist it enforces (`tools_settings_reach.tools_settings_unapplied`). | +| `toolsSettings` | object | Per-tool settings kiro-cli reads. Crew strips exactly two retired keys on every refresh — `execute_bash`/`shell` `deniedCommands` and `autoAllowReadonly` — because denied commands are enforced only at Crew's PreToolUse gate now, and a stale copy in the spec would keep blocking a built-in the user just re-enabled (`_strip_legacy_denied_commands`). Your other keys are preserved. One key Crew READS: `subagent.availableAgents`, kiro-cli's glob allowlist of what this agent may spawn, is honoured at Crew's own `spawn_run` / `spawn_sub_agents` gate too (those bypass kiro-cli's built-in `subagent` tool) — declared, the target must match a glob; omitted, everything is allowed, as upstream. Crew reads every sub-agent spelling kiro-cli accepts, with kiro-cli's precedence: `crew`, `agent_crew`, `agentCrew`, `subagent`, `use_subagent`. The first one the spec sets is read whole and the later ones are ignored, so `use_subagent.availableAgents` is honoured when `use_subagent` is the only spelling, while beside `subagent` (with the same value or another) only `subagent` counts, and a session-start notice that lists entries names `toolsSettings.use_subagent` among them (`tools_settings_aliases.canonical_tools_settings`). The other kiro-cli alias groups (`shell`/`execute_bash`/`executeBash`, `read`/`fsRead`/`fs_read`, …) fold the same way, and every notice names a key as the spec spells it, never as the key Crew reads it under. The gate reads the spec in `~/.kiro/agents` AND, when it knows the parent session's project directory (the live session's cwd and the chat slot's project, or a sub-agent's cwd), in `/.kiro/agents`; a declaration in any scope applies, so a project spec can only narrow what the user-level one allows. When the project directory is unknown and no user-level spec names the parent, a project-scope declaration is not honoured: Crew logs a warning and writes a `parent_spec_unresolved` security event instead of refusing. `subagent.trustedAgents` is a trust grant ("no permission prompts"), not an allowlist, and is not read as one. Details: `docs/system-specs/modules/subagent.md` § Parent agent spec allowlist. No KAS wire slot, so on KAS Crew translates it into `permissions` rules (`kas_permissions.tools_settings_to_permissions`, following KAS's own migration mapping) and merges them like an authored block: `deniedPaths` (read/glob/grep → `fs_read`, write → `fs_write`), `deniedCommands` and `web_fetch.blocked` become `deny` rules. `subagent.availableAgents` becomes a `subagent` `deny` over `"*"` with the listed names in `exclude` (`[]` denies every sub-agent), and `subagent.trustedAgents` a name-scoped `subagent` `allow` that the governance ceiling must permit, both run live on KAS (#25320); a name pattern travels when it is an agent id with `*` as its only wildcard. `write.fallbackAction: "deny"` travels as no rule: Crew's own gate refuses every file write of that agent whose target none of its `allowedPaths` covers, on every approval mode (a scheduled job with `approval_mode: auto` included). Entries are read like kiro-cli's globs (`*` and `**` cross `/`, `?`, a leading `~`, a relative entry anchored at the session's directory, a directory covering what is inside it); an entry with `[`, `{`, `\`, `$` or a `~user` covers nothing, and a write through a symlink must be covered at its real path too. A covered write runs without a prompt, as on kiro-cli (below). `shell.denyByDefault` travels as no rule either: Crew's own gate refuses every shell command of that agent that none of its `allowedCommands` matches whole, on every approval mode (a scheduled job with `approval_mode: auto` included), unless the agent's `allowedTools` names the shell by its exact name (`execute_bash`, `shell`, `@builtin`, `@builtin/*`, or `@builtin/` followed by one of the two names; a `*` or `?` pattern grants nothing): as on kiro-cli, such an agent runs any command its `deniedCommands` do not deny, prompting as usual. That holds only while every `deniedCommands` entry travels as a KAS deny rule; one that cannot (a regex with groups or alternation, a redirect) keeps the refusal. Without that entry, a command that redirects or substitutes counts as unmatched, and a chain split at `&&`, `||`, `;` and `|` matches only when an entry matches every part whole and the chain holds no quote, backslash, non-ASCII character or PowerShell `--%`. An `allowedCommands` entry outside the syntax Crew reads like kiro-cli allows nothing under `denyByDefault`, so its commands are refused, and the notice names it. Crew reads literals, escaped ASCII punctuation, `.`, bracket classes (`[A-Za-z0-9_./-]`, `[^;]`), groups `( )` / `(?: )`, alternation `\|` and the repeats `*`, `+`, `?`, with optional `^`/`$` at the two ends; it refuses POSIX classes (`[[:alpha:]]`), `\d`/`\w`/`\b`, counted repeats (`{1,3}`) and flags (`(?i)`). A command's `( )` and `{ }` count only inside a single- or double-quoted argument of an all-ASCII command with no backslash (`git commit -m "fix(x): y"`); `; & \| < > $` and backticks are refused even inside quotes. A regex becomes a glob only when it is a literal plus `.*` with no character KAS reads as glob syntax, and a pattern over the merge's length bound is dropped rather than refusing the whole block. KAS matches a shell rule against the command's words, and a redirect and its target are not among them, so a `deniedCommands` glob holding `<` or `>` still travels as a deny (it stops that character inside a word) but is also named in the notice: it does not stop `cmd > file`. The same holds for an authored `permissions` shell deny. `shell.allowedCommands` travels as no rule: Crew answers a matching command's permission request itself, after its deny floor and governance, never for a command that redirects or substitutes, and for a chain only when an entry matches every part whole and the chain holds no quote, backslash, non-ASCII character or PowerShell `--%` (`docs/system-specs/modules/security.md` § KAS spec built-in grant). A `deniedCommands` or write `deniedPaths` beside a grant keeps it prompting only when Crew cannot read every entry itself; otherwise Crew's gate refuses what a deny names and answers the rest of the grant without a prompt, as kiro-cli does. Such a command still asks, and the card says why: run the script alone, or move the pipeline into the script. `denyByDefault` and `autoAllowReadonly` beside `allowedCommands` keep the grant, as on kiro-cli; any other key beside it keeps those commands asking, and a `deniedCommands` is read as said above. `autoAllowReadonly: true` is carried by Crew's own read-only auto-approve, and beside `denyByDefault` a read-only command is let through instead of refused, as kiro-cli runs it. A write `allowedPaths` travels as no rule either: Crew answers a write whose every target an entry covers itself, whether or not `allowedTools` lists the write tool, unless a `deniedPaths` or another key on the write tool restricts it. The other allow lists (`read.allowedPaths`, `web_fetch.trusted`), `allowReadOnly`, `use_aws` and any pattern that does not translate are not carried, so those calls keep prompting; the KAS chat shows one notice at session start naming exactly those entries. goose and opencode never receive the rules, so their notice still names `toolsSettings` whole. No other mirrored harness applies the field: a new chat session on codex, copilot or deepseek whose spec sets it gets the same one-row notice naming `toolsSettings` whole (`spec_hooks.spec_tools_settings_applied_nowhere`; see the per-harness rulings, note 11). On `claude` the same two gate rows refuse what `shell.denyByDefault` and `fallbackAction: "deny"` do not allow, on every approval mode: the client reads both allowlists from the spec it projects and stamps them on its session's requests, a native sub-agent's included, and the settings seed adds `permissions.ask` rules for `Bash` and the file-write tools while either is set, so claude asks about those calls. With no KAS policy there, an `allowedTools` naming the shell lifts `denyByDefault` only when the spec has no `deniedCommands`. A session in `bypassPermissions` skips the ask. `deniedPaths`, `web_fetch.blocked` and the other entries are not carried on `claude` (`docs/system-specs/modules/security.md` § claude spec allowlists). A new claude chat session's notice therefore names only what of the field it still does not apply, never a `shell.denyByDefault` or `fallbackAction: "deny"` allowlist it enforces (`tools_settings_reach.tools_settings_unapplied`). | | `hooks` | object | Event-keyed hook lists, stored camelCase (`preToolUse`, `postToolUse`, `userPromptSubmit`, `agentSpawn`, `stop`). Crew merges your `kiro_hooks` config and, when autoimport is on, scripts discovered under `~/.kiro/hooks`, capped per event by `_MAX_USER_HOOKS_PER_EVENT` and in total by `_MAX_TOTAL_USER_HOOKS`. This field is the object form only, which is kiro-cli's own schema. The SOURCE that feeds it, `agent.kiro_hooks` in `~/.kiro/crew/config.json`, additionally accepts a kiro-agent hooks ARRAY — `{name, description?, trigger, matcher?, action, timeout?, enabled?, confirm?}` documents, on the twelve trigger names of kiro-agent's alias table in any of its spellings — and projects it onto this object: only a `command` action on the five triggers kiro-cli names is emitted, so an `agent` action, the other seven triggers and the per-hook `name`/`description`/`timeout` stay in your config without running there, and `enabled: false` or `confirm: true` keeps the hook out of the emission entirely (and out of the autoimport scan). See `steering-and-hooks.md` for that field. No KAS wire slot, so `UNSUPPORTED_SPEC_KEYS` drops the key from the agent Crew injects over the wire. On KAS, Crew's own turn loop fires this field instead (`agent_sdk/spec_hooks.py`, gated on `SessionCapabilities.crew_fires_spec_hooks`), through the same hook-store path as a Hooks-page hook: the `capabilities.script_hooks` gate, the sandboxed spawn, the timeout, a PreToolUse exit 2 that blocks the tool, and a hook a policy refused to run, which blocks it too with the refusal as the reason (a crash or timeout warns and the tool runs, as on kiro-cli). A PreToolUse hook runs only on a call that reaches Crew as a permission request, so the KAS projection adds an `ask` rule for every capability that such a hook's matcher covers, this spec's or a Hooks-page one's (`kas_permissions.withhold_hook_gated_auto_approval`). That includes the shell and filesystem, and a spec with no `permissions` at all: a session answer Crew saved, a KAS default or a user-scope rule can otherwise decide the call without a request, and an explicit `ask` outranks all three. A shell `ask` comes with a `deny` naming a command nobody runs (`kas_permissions.UNPARSEABLE_SHELL_GUARD`), so a command KAS cannot parse stays denied. Crew's own answers for what `allowedTools` granted read the policy before these asks, so a hook does not make a granted tool prompt. A matcher written in an MCP form with no wildcard (`@server/tool`, `mcp__server__tool`) is matched, with the hook store's own matcher, against each real tool of each server the policy auto-approves, named as the gate names an MCP call (`@server/tool`, `mcp__server__tool`); the tool names come from the MCP probe cache (`kas_permissions.cached_mcp_tool_names`). A matcher that meets exactly one real tool gets an `ask` on that exact `/` resource, so the other MCP tools keep their auto-approval and a matcher written in another case, or against a server named `srv_`, still holds the real tool. An `@server` matcher, a wildcard one (`@server/get_*`), which can meet a tool the cache does not list yet, and one whose server's tools are not cached withhold that server (`/*`) when it is one of the servers the policy allows. A `mcp__` title wildcard (`mcp__server__*`), a matcher whose server the policy does not allow, or whose allowed servers cannot be listed, withholds all of MCP. Any other matcher that can reach an MCP call still withholds all of MCP. KAS lets `ask` outrank `allow`, so the call comes back as a permission request and the hook sees it. A live session keeps the batch it registered, so when a hook added later covers a capability that batch auto-approves, the next turn resets the session and the claim registers a fresh batch (`spec_hooks.invalidate_stale_kas_session` before the claim, and `spec_hooks.reproject_claimed_session` again under the claimed lease, so a turn that waited behind a busy session is not run on its stale batch). A mode switch mid-turn activates a batch KAS already holds, so when the agent it moves to auto-approves what its PreToolUse hooks cover, the turn is stopped and the next one starts a fresh session projected for that agent (`spec_hooks.refuse_stale_switch`). A switch to one of KAS's own built-in modes, which has no spec on disk, carries no spec hooks: only the Hooks page's hooks are checked, and the refusal runs before the switch is recorded on the chat slot. A process that registers no hook store (the standalone `kirocrew run` task runner) reads the Hooks page's saved hooks from disk for both the projection and the gate (`hooks.persisted_hook_store`), so they still apply there. A `confirm: true` document does not run, since Crew cannot ask for the confirmation, and a new session gets one notice naming how many were skipped. Only the first `_MAX_SPEC_HOOKS` hooks are read; the rest are named in one warning. When its own backend is KAS, a subagent or task-runner turn runs its PreToolUse hooks (the Hooks page's and its own agent's spec hooks) on each permission request and refuses the call on a deny, and does not fire them again on the tool-call event (KAS sends that frame first); a subagent passes the spec hooks to PostToolUse too. A tool `matcher` keeps kiro-cli's tool names (`execute_bash`, `fs_write`, and the `shell`/`read`/`write` aliases): on a PreToolUse Crew compares it with the id KAS states for the call and the kiro-cli names that id stands for (`acp/kas_permissions.KAS_TOOL_IDS_BY_KIRO_TOOL`, so `execute_bash` meets KAS's `run_command`), never with the call's title, and the hook's stdin reports that kiro-cli name as `tool_name`. A PreToolUse matcher the table does not know (`use_aws`, `disclose_context`) is kept and warned about: it meets a KAS id it matches as written. A call KAS names no tool for is matched on its title, as a Hooks-page hook is. A PostToolUse matches the same way, on the finished call's id: KAS's tool-call frames name no built-in tool, so it is the id the call's permission request stated, or KAS's shell tool for a call classified as a shell command; a call neither names keeps title matching. A PostToolUse fires once per call, on its terminal result. goose and opencode get the same treatment: their session carries no hooks field either, and every tool call arrives as a permission request, so Crew fires the field there too. A tool matcher meets the tool name the harness states on the call's first `tool_call` frame (goose's `_meta.goose.toolCall.toolName`, opencode's `title`), mapped back to kiro-cli's names (`acp/harness_tool_names.py`, so `execute_bash` meets goose's `shell` and opencode's `bash`). An `mcp__server__tool` matcher meets an MCP call too: goose names the server itself, and opencode's fused `_` title is split against the servers Crew placed on the session and the ones opencode's own config mounts (which Crew reads back when the session starts, so `mcp__docs.server__lookup` meets a `docs.server` tool even though opencode writes it `docs_server_lookup`; a config with more than 256 such rewritten names, or a name over 256 characters, refuses the session rather than leave one out), and also at every `_` for a server neither names; every split is kept. When the fused title is also one of opencode's own tools (`apply_patch`), that tool's names are kept too and its kiro-cli name stays first, so the hook's stdin still reports `fs_write` as `tool_name`. On these backends and KAS a matcher may also be written in kiro-cli's other kinds: `@server/tool`, the form Crew builds for an MCP call from the server name the harness states, with one literal server name (no glob, so `@*/tool` is refused) and a tool part of the matcher's own characters plus `?` (`@server/*`); `@server`, every tool of that server; `@mcp`, every MCP tool; `@builtin` and `@builtin/`, built-in tools only; a glob with `?`; and kiro-cli's tags `read` (`fs_read`, `grep`, `glob`, `code`), `write`, `shell`, `web` and `subagent`. The gate gives each call the names these meet (`spec_hooks.spec_hook_kind_names`), for spec hooks only. Only this conversion accepts them, in either hook shape (`spec_hooks._SPEC_MATCHER_RE`); the merge that writes kiro-cli's materialized spec keeps its own rule. On those two backends the spec is read from the checkout's `.kiro/agents` first, then the user level, the same order their MCP projection resolves it in, but a project agent's hooks run only when that checkout is trusted to choose its MCP servers (`acp/session_mcp.py`, `_project_mcp_trusted`), and otherwise the user-level spec of that name supplies the hooks; a project spec that cannot be read blocks every tool call. KAS reads the user level alone. A Bot's worker is read as its session's merged spec (`mate_worker.mate_service_scope_spec`), so the hooks the Bot's file carries fire there (`mate_spec_policy`); the Bot's own chat runs the stock conductor spec. As on KAS, this is the chat, subagent and task-runner turn loops: a channel-agent turn (`channel.py`) runs no script hooks on any backend. claude and codex do not run the whole field yet: each approves some calls inside the harness without asking, and a PreToolUse hook would be skipped on those. A Hooks-page PreToolUse hook does run on a claude permission request, and its kiro-cli matcher meets claude's built-ins by the name the adapter stamps on the call (`acp/harness_tool_names.CLAUDE_TOOL_IDS_BY_KIRO_TOOL`, so `execute_bash` meets `Bash` and `fs_write` meets `Write` and `Edit`). On claude Crew fires the other four events (`postToolUse`, `userPromptSubmit`, `agentSpawn`, `stop`) on the chat and subagent turn loops, so the default agent's `execute_bash` audit hook runs there: a claude call that asked permission is named through the same table (`Edit` meets `fs_write`), and one of kind `execute` that did not is named `execute_bash`, for a matcher and on the hook's stdin. Its `preToolUse` hooks do not run, and a new chat session whose agent has one gets a notice; nothing gates on the spec there, so one that cannot be read runs no hooks rather than blocking a call. pi does not run the field either: it is handed no agent spec, and Crew does not fire the field there, so a new pi chat session whose agent has hooks gets a session-start notice, as on claude and codex, and the backend card lists `hooks` as not applied. On the dashboard, the notice for a backend where nothing runs the field ends in a Dismiss link: one click hides it in every later session for every agent, and the choice is backed up with the other dismissed tips. A notice that names a `preToolUse` hook has no link and always shows, because such a hook is there to refuse calls. It changes what the dashboard draws, not which hooks run, and the backend card still lists `hooks`. kiro-cli runs the field itself, so Crew never fires it there. | | `hooks` | honoured | dropped from the wire projection; fired by Crew's turn loop | Crew's gate, renamed events | | `slashCommand` | any | No KAS wire slot: a KAS session runs without it, and the chat shows one notice at session start saying so. Nothing else in this tree reads it. | | `toolAliases` | object | Maps a Connections-exposed MCP tool to the short name a `@alias` reference in `tools` / `allowedTools` resolves through. On the default spec's rebuild Crew recomputes it from the connector registry, dropping the pairs its own record proves it wrote and keeping the rest, whose authorship is unproven and therefore yours (`agent_materialization/mcp_aliases.py`, `_reconcile_tool_aliases_from_disk`). It reconciles the path it is given, so a spec that rebuild does not touch keeps whatever it holds. A non-dict value there is replaced rather than merged. | diff --git a/src/kiro_crew/platform/tools_settings_aliases.py b/src/kiro_crew/platform/tools_settings_aliases.py index 0310fa9c3430..3187bb5b6e87 100644 --- a/src/kiro_crew/platform/tools_settings_aliases.py +++ b/src/kiro_crew/platform/tools_settings_aliases.py @@ -44,8 +44,9 @@ ) #: The spelling a kept alias is filed under when Crew's readers do not know the -#: one the spec used (``executeBash`` -> ``shell``), so a notice names that -#: spelling. A spelling Crew already reads keeps its own name. +#: one the spec used (``executeBash`` -> ``shell``). A spelling Crew already +#: reads keeps its own name. A notice puts the spec's spelling back +#: (:func:`as_authored`). _TOOLS_SETTINGS_CANONICAL: dict[str, str] = { alias: ("subagent" if group[0] == "crew" else group[0]) for group in _TOOLS_SETTINGS_ALIAS_GROUPS @@ -53,6 +54,16 @@ } +def _filed_under(winner: str) -> str: + """The key :func:`canonical_tools_settings` files a group's kept *winner* under.""" + target = _TOOLS_SETTINGS_CANONICAL[winner] + # The sub-agent group is always filed under `subagent`, the one key the + # spawn gate and the unapplied-settings notice both read, so the two can + # never disagree about a `use_subagent` spelling. + renamed = winner not in _TOOLS_SETTINGS_FAMILY and winner != "use_aws" + return target if renamed or target == "subagent" else winner + + def canonical_tools_settings(tools_settings: Any) -> tuple[Any, list[str]]: """*tools_settings* with each kiro-cli alias group folded to one key. @@ -75,12 +86,8 @@ def canonical_tools_settings(tools_settings: Any) -> tuple[Any, list[str]]: for key in rest: del out[key] dropped.append(key) - target = _TOOLS_SETTINGS_CANONICAL[winner] - # The sub-agent group is always filed under `subagent`, the one key the - # spawn gate and the unapplied-settings notice both read, so the two can - # never disagree about a `use_subagent` spelling. - renamed = winner not in _TOOLS_SETTINGS_FAMILY and winner != "use_aws" - if winner != target and (renamed or target == "subagent"): + target = _filed_under(winner) + if target != winner: out[target] = out.pop(winner) if dropped: logger.info( @@ -89,3 +96,23 @@ def canonical_tools_settings(tools_settings: Any) -> tuple[Any, list[str]]: ", ".join(sorted(dropped)), ) return out, sorted(dropped) + + +def as_authored(tools_settings: Any, path: str) -> str: + """*path*, read off the folded *tools_settings*, under the spelling the spec wrote. + + *path* is ```` or ``.`` of :func:`canonical_tools_settings`'s + result. When the fold filed ```` under another name (``use_subagent`` + or ``crew`` under ``subagent``, ``executeBash`` under ``shell``), the kept + spelling from *tools_settings* is put back, so a notice names a key the author + can find in the spec. Any other path is returned unchanged. A dropped + spelling is already named as written, so it is never passed here. + """ + if not isinstance(tools_settings, dict): + return path + tool, dot, rest = path.partition(".") + for group in _TOOLS_SETTINGS_ALIAS_GROUPS: + winner = next((key for key in group if key in tools_settings), None) + if winner is not None and _filed_under(winner) == tool: + return winner + dot + rest + return path diff --git a/test/test_kas_tools_settings_aliases.py b/test/test_kas_tools_settings_aliases.py index 04a297cb3adf..b8a89c145ced 100644 --- a/test/test_kas_tools_settings_aliases.py +++ b/test/test_kas_tools_settings_aliases.py @@ -164,6 +164,47 @@ def test_trusted_agents_dropped_by_the_ceiling_are_named(self, monkeypatch): monkeypatch.setattr(kas_agents, "may_skip_gate_now", lambda ref: True) assert spec_keys_without_carrier(spec, translates_tools_settings=True) == [] + @pytest.mark.parametrize( + ("settings", "named"), + [ + ( + {"subagent": {"trustedAgents": ["r"], "x": 1}}, + ["subagent.trustedAgents", "subagent.x"], + ), + ( + {"use_subagent": {"trustedAgents": ["r"], "x": 1}}, + ["use_subagent.trustedAgents", "use_subagent.x"], + ), + ({"agentCrew": {"trustedAgents": ["r"]}}, ["agentCrew.trustedAgents"]), + # kiro-cli keeps `subagent` whole, so only its keys are read. + ( + {"subagent": {"trustedAgents": ["r"]}, "use_subagent": {"trustedAgents": ["r"]}}, + ["subagent.trustedAgents", "use_subagent"], + ), + ( + {"subagent": {"trustedAgents": ["r"]}, "use_subagent": {"x": 1}}, + ["subagent.trustedAgents", "use_subagent"], + ), + # `\d` is outside the regex syntax Crew reads, so the entry is unusable. + ({"executeBash": {"allowedCommands": [r"ls \d"]}}, ["executeBash.allowedCommands"]), + ], + ) + def test_a_kept_alias_is_named_as_the_spec_wrote_it(self, monkeypatch, settings, named): + monkeypatch.setattr(kas_agents, "may_skip_gate_now", lambda ref: False) + spec = _spec(toolsSettings=settings) + got = spec_keys_without_carrier(spec, translates_tools_settings=True) + assert got == [f"toolsSettings.{path}" for path in named] + # The worker policy's tool view names the same spellings. + unenforced = [p for p in named if not p.endswith(".trustedAgents")] + assert tools_settings_unenforced(settings) == unenforced + + def test_withheld_write_paths_are_named_as_the_spec_wrote_them(self, monkeypatch): + # The ceiling withholds the write grant, so `allowedPaths` go unanswered. + monkeypatch.setattr(kas_agents, "may_grant_builtin_at_gate_now", lambda tool: False) + spec = _spec(toolsSettings={"fsWrite": {"allowedPaths": ["/tmp/x"]}}) + got = spec_keys_without_carrier(spec, translates_tools_settings=True) + assert got == ["toolsSettings.fsWrite.allowedPaths"] + def test_an_untranslatable_trusted_agents_entry_is_not_named_twice(self): # `?` has no shared reading, so the translation already names it. assert ( diff --git a/test/test_tools_settings_notice.py b/test/test_tools_settings_notice.py index 6cbf83e099ce..e524d5f363f7 100644 --- a/test/test_tools_settings_notice.py +++ b/test/test_tools_settings_notice.py @@ -180,6 +180,35 @@ def _boom(_backend): {**_SHELL_ALLOWLIST, "subagent": {"availableAgents": [], "trustedAgents": ["x"]}}, ["toolsSettings.shell", "toolsSettings.subagent.trustedAgents"], ), + # A kept alias is named as the spec wrote it, not as the key it is read as. + ( + {"use_subagent": {"availableAgents": [], "trustedAgents": ["x"]}}, + ["toolsSettings.use_subagent.trustedAgents"], + ), + ( + {"crew": {"availableAgents": [], "trustedAgents": ["x"]}}, + ["toolsSettings.crew.trustedAgents"], + ), + ( + {"executeBash": {"deniedCommands": ["rm"]}, "use_subagent": {"availableAgents": []}}, + ["toolsSettings.executeBash"], + ), + # Both spellings: kiro-cli keeps `subagent` whole and drops `use_subagent`, + # with the same value or a different one. + ( + { + "subagent": {"availableAgents": [], "trustedAgents": ["x"]}, + "use_subagent": {"availableAgents": [], "trustedAgents": ["x"]}, + }, + ["toolsSettings.subagent.trustedAgents", "toolsSettings.use_subagent"], + ), + ( + { + "subagent": {"availableAgents": [], "trustedAgents": ["x"]}, + "use_subagent": {"availableAgents": ["*"]}, + }, + ["toolsSettings.subagent.trustedAgents", "toolsSettings.use_subagent"], + ), ], ) def test_only_what_the_spawn_gate_does_not_read_is_named(settings, named): @@ -206,6 +235,18 @@ def test_beside_a_spawn_allowlist_only_the_rest_is_named(backend, agents_dir, no assert "availableAgents" not in rows[0] +@pytest.mark.parametrize("backend", _ALLOWLIST_UNAPPLIED + _CREW_FIRED) +def test_the_notice_names_the_use_subagent_spelling_the_spec_wrote(backend, agents_dir, notices): + """An author searching the spec for the printed key must find it.""" + only = {"use_subagent": {"availableAgents": ["helper-*"], "trustedAgents": ["helper-*"]}} + _write_spec(agents_dir, "a1", toolsSettings=only) + _prepare(backend, "a1", is_new=True) + rows = _tools_settings_rows(notices) + assert len(rows) == 1 + assert "sets toolsSettings.use_subagent.trustedAgents, which" in rows[0] + assert "toolsSettings.subagent" not in rows[0] + + def test_claude_names_no_allowlist_its_gate_applies(agents_dir, notices): """claude's gate refuses what a ``denyByDefault`` or ``fallbackAction: "deny"`` allowlist does not cover, so the notice never says those go unapplied.""" @@ -244,6 +285,10 @@ def test_claude_names_only_what_its_gate_does_not_apply(agents_dir, notices): {**_SHELL_ALLOWLIST, "web_fetch": {"blocked": ["x"]}, "read": {"deniedPaths": ["y"]}}, ["toolsSettings.read.deniedPaths", "toolsSettings.web_fetch.blocked"], ), + ( + {**_SHELL_ALLOWLIST, "use_subagent": {"trustedAgents": ["x"]}}, + ["toolsSettings.use_subagent.trustedAgents"], + ), ], ) def test_the_gate_applied_allowlists_are_left_out(settings, named):