Skip to content

feat: carry a crewmate's template policy onto its worker - #28501

Merged
buluoray merged 1 commit into
mainfrom
crew/slack/worker-kit-carry-restrictions
Nov 3, 2026
Merged

buluoray merged 1 commit into
mainfrom
crew/slack/worker-kit-carry-restrictions

Conversation

@buluoray

@buluoray buluoray commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A crewmate can take abilities from an agent that sets hooks, permission rules or tool settings, and its worker then runs under exactly those fields on KAS; the crewmate's own chat keeps the stock conductor.

Since #23010 split each crewmate into a conductor (its chat) and a worker, Add abilities refuses any agent that sets hooks, permissions or toolsSettings with "That agent sets permission rules, tool settings or hooks the worker can't keep. Choose another one." Crewmates the upgrade moved off such an agent lost its tools and cannot take them back (#26881).

Why it matters

Every user whose crewmate was built on an agent with hooks, deny rules, path or command limits is stuck: they cannot pick that agent again, so the crewmate stays without the tools it had, and the worker that runs those tools has none of the agent's limits.

Not a goal

  • Changing the crewmate's chat (the conductor). It runs the stock conductor spec, as on main: nothing from the crewmate's file reaches it (rfc-mate-owned-agent-config.md §5.1, unchanged).
  • Changing the upgrade migration: the file it writes still carries no hooks, permissions or tool settings, and its notice still names them. Adding the agent again now carries them onto the worker.
  • Applying these fields on kiro-cli, claude or any non-KAS worker backend. A crewmate there is refused, naming the field.

What changed (motivation → approach → change)

Symptom: the kit copy refuses a template through uncarried_restrictions, because merge_worker_spec dropped hooks, permissions and toolsSettings.

Change:

  • New mate_spec_policy.py. layer_policy adds each hook beside the base's, each permission rule beside the base's rules, and copies a toolsSettings entry whole for a tool the base sets nothing for. Anything that cannot land exactly (an entry for a tool the base sets differently, a permissions block KAS would refuse whole) raises SpecPolicyUncarried, a WorkerKitUnreadable, naming the field. Nothing is widened past what the template declares. toolsSettings is an allowlist (CARRIED_TOOLS_SETTINGS): only deniedCommands and allowedCommands on the shell tool (execute_bash / shell), deniedPaths on the read and write tools (fs_read / read / glob / grep, fs_write / write), and web_fetch.blocked are carried, each only when KAS's own translation keeps every entry (kas_tool_view.tools_settings_unenforced). Every other key or tool, in any form (allowedPaths, fallbackAction, denyByDefault, trusted, subagent.availableAgents even when empty), is refused by name. A second spelling of a tool the file already sets differently (shell beside execute_bash), or a hook past the 20 Crew fires, is refused too.
  • Worker: worker_additions keeps the file's policy and merge_worker_spec layers it.
  • Only what the template adds: mate_spec_policy.without_held drops every hook, permission rule and tool setting the worker base already holds (Crew's own audit hook, the user's kiro_hooks) before the kit copy layers and judges the rest, so those are not frozen into the crewmate's file and do not trip the non-KAS refusal.
  • An allow rule the worker would silently lose is refused by name (permissions rule N (allow <capability>)). It is refused only when all four hold: (1) the check runs on the merged worker spec (layer_policy(..., worker=True) from merge_worker_spec), never on the crewmate file alone; (2) the worker default does not already hold the rule; (3) KAS's projection would drop it, because an allowedTools list could express it (kas_tool_view.permission_allow_derivable); (4) the worker's own grants do not already cover it: its allowedTools plus each governed server autoApprove verb, the same input KAS's projection derives grants from (kas_tool_view.allow_granted_by_spec). A permissions block whose rules is not a list is refused as permissions. So a governed template's generated block, which mirrors its own allowedTools, is accepted, and scoped or excluded allows travel.
  • Live workers: an apply that changes the file's hooks, permissions or tool settings reloads the crewmate's running workers through the existing crewmate_worker_reload.schedule_reload_workers (a busy one at its turn end), since a live KAS session keeps the permission batch it registered.
  • Crew-fired hooks on KAS read the worker session's merged spec (spec_hooks._agent_spec with the session key, through mate_worker.mate_service_scope_spec, the path skill scope already uses), so carried hooks actually run on the worker. For the conductor that path still returns the stock spec.
  • Off KAS: resolve_worker_spec(refuse_spec_policy=True) (called from acp/session_mcp_crewmate._crewmate_worker_spec on the mirrored hosts) refuses a worker whose crewmate file sets these fields, naming them.
  • Kit copy (mate_worker_kit._carry_policy): copies the fields into the file, previews each as a hooks / permissions / toolsSettings row (one per entry, labelled plus a digest so two entries sharing a label each get a row), and refuses with a detail naming the field: template_restrictions_uncarried, template_policy_backend_unsupported. The dashboard sentence names the field (workerKitErrors.ts, 12 locales); the preview group reads "Hooks, permissions and tool settings (worker)".
  • _crewmate_worker_spec moved to acp/session_mcp_crewmate.py to keep session_mcp.py under the line cap; the old import path still works.
  • Owner decision recorded: docs/decisions/2026-11-02-a-crewmates-worker-carries-its-template-policy.md. Specs updated: crew-mode.md, agent-spec-fields.md.

Backwards compatibility

Compatible: every template that was accepted before is still accepted with the same file written; a template that was refused for hooks/permissions/tool settings is now accepted on KAS or refused with a narrower, named reason. Crewmate files with none of the three fields produce the same worker spec as before. The crewmate's chat is unchanged.

Behaviour that changes for existing crewmates: a crewmate whose file already holds hooks, permissions or toolsSettings (only possible by hand-editing it; the kit copy refused them and the migration never writes them) now has its worker run under them on KAS, and on a non-KAS worker backend the worker is refused at start, naming the fields, instead of running without them.

mate_config_migration.py changes how restrictions are compared (one toolsSettings entry per tool, and a policy field the worker now carries no longer counts as lost). Readers on origin/main:

Reader: src/kiro_crew/mate_worker_kit.py:_plan -- crew page -- calls uncarried_restrictions, which now returns only fields that cannot land exactly; test_mate_spec_policy.py::test_a_template_setting_the_worker_base_sets_differently_is_refused_by_name
Reader: src/kiro_crew/mate_config_migration.py:plan_move -- release -- startup migration via migrate_existing_crewmates; the file it writes carries no policy, so differences reports the same losses as before; test_mate_config_migration.py
Reader: src/kiro_crew/mate_config_migration.py:dry_run -- release -- default-template file path, same differences call; test_mate_config_migration.py
Reader: src/kiro_crew/mate_config_migration.py:dropped_restrictions -- release -- iterates toolsSettings keys, which per-tool entries still yield one by one; test_mate_upgrade_notice.py
Reader: src/kiro_crew/mate_config_migration.py:_fallback_keeping_limits -- release -- unreadable-agent fallback, same differences call; test_mate_migration_real_kirocrew.py

Tests

test/test_mate_spec_policy.py: each allowed toolsSettings key is shown to take effect (the four denies become KAS deny rules through tools_settings_to_permissions; allowedCommands is answered by Crew's gate through crew_answered_commands), and every other key or tool is refused by name (allowedPaths, fallbackAction, denyByDefault, trusted, availableAgents empty or not, trustedAgents, an unknown tool, a non-object entry), as are an allowedCommands entry the gate cannot answer, a second spelling of a tool, and a hook past the cap; layering is otherwise exact or refused naming the field; the worker carries the fields and gains no allow the template lacks; an off-KAS worker is refused naming the fields; the kit copy previews and writes the fields and refuses off KAS and on a tool-setting conflict with the worker base; two entries sharing a label each get a preview row; KAS worker turns, sub-agent worker turns (shared and dedicated spawn_run(keep=True) providers) and stale-session checks read the worker session's merged spec.

New: test_a_crewmates_chat_runs_the_stock_conductor_whatever_its_file_sets installs the real stock conductor (service_agents._install_mate_conductor_agent) beside a crewmate file with hooks, permissions and tool settings, and asserts that mate_service_scope_spec, _crewmate_worker_spec (policy honoured or not) and spec_hooks._agent_spec all return the stock conductor unchanged. Mutation check: removing the base-held subtraction, removing the dropped-allow check or any of its already-held, already-granted and worker-only conditions, never reloading, or always reloading each turns a test red; removing the allowlist, removing the KAS-translation check, dropping the sub-agent turn's session key, or reading it only from the provider and not its _client each turns a test red. Routing the conductor through the worker merge in mate_service_scope_spec, or through _crewmate_worker_spec, each turns it red; restored green.

Blast radius: every test file that names a touched symbol plus test_harness_parity.py, test_kas_agents.py, test_flake_pattern_ratchet.py, test_chat_runner_composition_contract.py and test_error_code_contract.py: 2923 passed, 14 skipped. Frontend src/components/crew/ and src/i18n/: 1217 passed.

Proof: not provable -- other: the change is a new carrying mechanism, not a reverted hunk; the mutation checks above stand in for it.

Manual verification

Still required: add an agent with a preToolUse hook and a deny rule to a crewmate on KAS, then confirm the hook fires and the deny holds in a worker it opens, and that the crewmate's chat behaves as before.

Screenshots / video

Captured from this PR's built SPA (head d4e789e6, before the rebase onto main; no frontend change since), served on 127.0.0.1 with /api/** stubbed by website/scripts/lib/stub-dashboard-api.mjs. The worker-kit payloads are this PR's own mate_worker_kit.preview output for a sample template, not hand-written.

Add abilities preview: the new "Hooks, permissions and tool settings (worker)" group, one row per hook, rule and tool setting.

Add abilities preview with the hooks, permissions and tool settings group

The same template on a crewmate whose worker is off KAS is refused, and the message names the fields.

Refusal naming the fields a non-KAS worker cannot apply

The images live on the separate branch crew/slack/pr28501-screenshots, not on this PR's branch.

Related Issues

Closes #26881
Follows #23010

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 2, 2026 19:48
@buluoray
buluoray requested a review from bolichen97 November 2, 2026 19:48
@buluoray
buluoray enabled auto-merge (squash) November 2, 2026 19:49
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 2, 2026
@buluoray
buluoray force-pushed the crew/slack/worker-kit-carry-restrictions branch from 0cda84f to 81e945b Compare November 2, 2026 20:03

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commenting at 81e945b, on one design point, not a blocker on the rest.

Carrying a template's restrictions onto the chat looks right to me. Its permissions deny and ask rules, its excludedTools and its servers' disabledTools should reach the conductor. The decision doc's reason holds: the conductor reads the crewmate's input first, so a limit that narrows only the worker does not hold where it matters.

The grants are the part I would not carry. The decision doc says:

Granting the conductor the template's auto-approvals is a deliberate widening the owner accepted: the user already approved those tools when they wrote the template.

The chat reads untrusted channel input before any human sees it. A template's grants (toolsSettings entries such as allowedCommands and allowedPaths, and permissions allow rules) were approved for the worker, which acts on a task the conductor has already checked. In the chat they would auto-approve on input no one has looked at yet. I would keep the chat's grants at its own level. In apply_conductor_overlay, the overlay would carry only the narrowing parts: deny and ask rules, and excludedTools. The allow rules and the toolsSettings grants would stay with the worker.

A test would pin it: a crewmate whose template grants a tool by allowedCommands or an allow rule, where the worker runs it without asking but the chat still asks.

@buluoray
buluoray force-pushed the crew/slack/worker-kit-carry-restrictions branch from 81e945b to e6bf8d6 Compare November 2, 2026 20:19
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

UX-level review of 9b2fc7cb9c2bb8645762395e35136fdd6d3fe8f7 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

cannot evaluate: missing screenshots of the new "Hooks, permissions and tool settings (worker)" preview group and the two new refusal sentences. The blind read was not performed because the PR attaches no image.

Evidence gaps

  • Preview group and its rows. The Add abilities preview gets a new group, crewWorkerKit.group_policy ("Hooks, permissions and tool settings (worker)"), with one row per hooks / permissions / toolsSettings entry. No screenshot shows it. To close: a screenshot of the preview for a template that sets all three fields.
  • Refusal naming the field. The new sentence error_template_restrictions_uncarried_named ("That agent's {{fields}} can't be kept exactly by this crewmate…") appears in no screenshot. To close: a screenshot of the refusal as it renders, with a real detail value filled in.
  • Refusal on another backend. The new sentence error_template_policy_backend ("…Run the crewmate on Kiro Agent…") appears in no screenshot. To close: a screenshot of that refusal on a non-KAS crewmate.

Notes

  • Row labels are raw code. changeLabel has no case for the new sections, so each row shows the raw id, for example PreToolUse: * (3fa2c1d9) or permissions rule N (allow …). A user sees event names and a hash digest. Give these sections readable labels, as approvalLabel does for approvals.
  • Refusal text drops in identifiers. {{fields}} puts strings like toolsSettings.execute_bash into the sentence word for word. Map each known field to a plain-language name before it is inserted.

[UX-REVIEWED] 9b2fc7c

Description read

[DESCRIPTION-READ] 4f2093a89ca49850f7c178734e39eaf95a54cc04d02fbbcb4951bc7008787b83

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

Design-level review of 9b2fc7cb9c2bb8645762395e35136fdd6d3fe8f7 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

cannot evaluate: missing screenshot of the Add abilities preview showing the new "Hooks, permissions and tool settings (worker)" group and the field-naming refusal sentence. The backend design itself raises nothing that blocks.

Blockers

The reshaped worker-kit preview has no rendered evidence
Trigger: workerKitGroups.ts adds "{ key: 'policy', sections: ['hooks', 'permissions', 'toolsSettings'], heading: () => i18nT('crewWorkerKit.group_policy') }" and workerKitErrors.ts adds "error_template_policy_backend" / "_named" sentences that put the raw detail inside them; design-evidence.txt lists 0 images and 0 recordings.
Outcome: the preview panel gains a new group whose rows are "labelled plus a digest" → nobody can check whether a digest-suffixed row or a sentence with a raw field path such as "toolsSettings.execute_bash" makes sense to a user → the shape question can't be answered, so the review can't pass.
Fix: attach a screenshot of the preview for a template with hooks, permission rules and tool settings, plus one of a named refusal.
Clears when: the description carries a github.com/user-attachments image (or a committed one under temp-screenshots/) of this revision showing the policy group rows and a template_restrictions_uncarried / template_policy_backend_unsupported refusal.

Notes

  • The refusal sentence puts the backend's internal path (toolsSettings.execute_bash, permissions rule N (allow …)) into a localized string as it is. Check in the screenshot that this reads as something a user can act on.

[DESIGN-REVIEWED] 9b2fc7c

Description read

[DESCRIPTION-READ] bbda010ba09d11002f33c84a98ed05dd9c9fd2868d7c0d347a66ee53f9032781

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 9b2fc7cb9c2bb8645762395e35136fdd6d3fe8f7 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: the main change gives back what #26881 reports was lost, and each refusal it adds comes from what KAS actually enforces.

Notes

  • Item 10 — duplicate of mate_spec_policy.SpecPolicyUncarried: def uncarried(fields, why="") -> SpecPolicyUncarried: return SpecPolicyUncarried(fields, why) is a second way to spell the constructor. I grepped \buncarried\( in src/ and found 2 call sites (mate_worker.py:650, mate_spec_policy.py:278) plus the definition. Subtraction: delete uncarried and have both sites call raise SpecPolicyUncarried(...) directly.

What this change ships

Inventory (10 items) — 9 justified

Intent: a crewmate owner can add abilities from an agent that has hooks, permission rules or tool limits, and the worker keeps those limits. This is a FIX for #26881.

  1. Add abilities now accepts templates that carry hooks, permissions or toolsSettings when the worker is on KAS — justified
  2. The crewmate's worker runs under the carried hooks, rules and allowlisted tool settings — justified
  3. Crew-fired hooks on a KAS worker read the session's merged spec, so carried hooks fire — justified
  4. A refusal now names the field it is about (detail, 12 locales) — justified
  5. The preview shows one row per carried hook, rule and tool setting — justified
  6. Applying a policy change reloads the crewmate's live workers — justified
  7. A non-KAS worker is refused when its file sets policy, both at add and at start (template_policy_backend_unsupported) — justified
  8. The migration compares restrictions per tool and counts carried policy as kept — justified
  9. _crewmate_worker_spec moved to session_mcp_crewmate.py to stay under the line cap — justified
  10. uncarried() factory added beside the exception class — duplicate of SpecPolicyUncarried

There are more items than these 10. The rest are small, such as auto_approve_refs(audit=), which one caller uses.

[FIRST-PRINCIPLES-REVIEWED] 9b2fc7c

Description read

[DESCRIPTION-READ] 62d2fa17b4198712c178ad2a5319fa121e4f64893484e23df91c1591ab85f6d9

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

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

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 9b2fc7cb9c2bb8645762395e35136fdd6d3fe8f7 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9b2fc7c

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9b2fc7cb9c2bb8645762395e35136fdd6d3fe8f7 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 9b2fc7cb9c2bb8645762395e35136fdd6d3fe8f7 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9b2fc7c

Verdict parsed from the review's SHA-scoped output markers for commit 9b2fc7cb9c2bb8645762395e35136fdd6d3fe8f7.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 9b2fc7cb9c2bb8645762395e35136fdd6d3fe8f7 false-positive: <reason, 20 to 500 characters>

@buluoray
buluoray force-pushed the crew/slack/worker-kit-carry-restrictions branch from e6bf8d6 to 4e3a9ac Compare November 2, 2026 21:20
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 2, 2026
@buluoray
buluoray force-pushed the crew/slack/worker-kit-carry-restrictions branch from 4e3a9ac to cf6c726 Compare November 2, 2026 22:14
@buluoray

buluoray commented Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

Disposition for the Opus 5.5 review of e6bf8d685992a88df10234f5ef487083437e97d6 (fixes are in cf6c7260f128985709b10866624e29af16a8862c).

BLOCKING -- src/kiro_crew/mate_worker_kit.py preview rows collapse (fixed). _policy_ids now keys each hook and permission rule on its whole entry (label plus an 8-character digest of the canonical entry), the same identity mate_spec_policy dedupes on, so two hooks with the same matcher but different commands, or two rules that differ only in exclude, each get their own preview row. New test test_mate_spec_policy.py::test_an_entry_sharing_a_label_with_one_already_held_still_gets_a_row; mutation-checked: dropping the digest from the hook id, or from the rule id, turns it red.

BLOCKING -- decision entry's decider is not in MAINTAINERS.md (needs a maintainer). Not a code change: this needs a listed maintainer to restate the decision, including the conductor grant widening, on this PR. The entry's Evidence will then cite that comment. Since this review, docs/request-for-change/rfc-mate-owned-agent-config.md §5.1 is amended in this PR to record the same decision.

Also from First Principles: the mate_spec_policy._probe pass-through is removed; _layer_permissions calls agent_sdk.kas_tool_view.permissions_block_readable directly.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 2, 2026
buluoray added a commit that referenced this pull request Nov 2, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 2, 2026
@buluoray
buluoray force-pushed the crew/slack/worker-kit-carry-restrictions branch 2 times, most recently from d4e789e to 9108c7a Compare November 3, 2026 00:01
@buluoray buluoray changed the title feat: carry a crewmate's template policy onto its worker and chat feat: carry a crewmate's template policy onto its worker Nov 3, 2026
@buluoray

buluoray commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Scope narrowed at the owner's request (@buluoray): this PR now carries a template's hooks, permissions and toolsSettings onto the crewmate's worker only. The crewmate's chat runs the stock conductor spec, as on main.

Removed: the conductor projection (conductor_overlay, apply_conductor_overlay, conductor_session_spec, the hand-off-tool check and template_blocks_conductor_tool), the KAS conductor branch, and the conductor excludedTools merge. The RFC §5.1 amendment is reverted, so the RFC again says nothing from the file reaches the conductor. The decision entry is rewritten and renamed to 2026-11-02-a-crewmates-worker-carries-its-template-policy.md.

The owner asked for the **Goal:**, ## Why it matters and ## Not a goal sections to be updated to match, so they now describe the worker-only scope. Closes #26881 stays. The screenshots are retaken. A new test pins that a crewmate's chat spec equals the stock conductor even when its file sets these fields.

@github-actions github-actions Bot removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Nov 3, 2026
@buluoray

buluoray commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

@bolichen97 thanks for tracing it. All three findings on 676154c2 checked against the code first; all three held, and are fixed in 9bf878d9.

1. Live workers keep the old KAS batch (your point 2, GPT): confirmed as you traced it. Fixed by reusing the existing worker-reload path, crewmate_worker_reload.schedule_reload_workers, the one the capabilities route already uses. mate_worker_kit.apply_reporting returns whether the file's hooks, permissions or tool settings changed (a digest of policy_of before and after the write), and the worker-kit PUT schedules the reload only then.
I picked this over invalidate_stale_kas_session because it reuses more and covers more. That path re-checks at turn start and would need a new per-session policy digest threaded through the session handle and both provider classes to know a batch is stale. The reload path already finds the crewmate's live workers, reloads an idle one now and a busy one at its turn end, and works for both provider shapes.
Tests: test_adding_a_deny_reloads_the_crewmates_idle_worker (a deny added → the reload is scheduled for that crewmate and reloads its idle worker), test_an_add_without_a_policy_change_reloads_nothing (a server-only add → no reload). Never reloading, or always reloading, each turns one red.

2. Hooks the worker base already holds are copied (Opus): confirmed. On this host ~/.kiro/agents/kirocrew.json and the worker base carry the same bundled postToolUse audit hook. mate_spec_policy.without_held now drops every hook, permission rule and identical tool setting the worker base holds before _carry_policy layers and judges the rest, using the same canonical comparison _layer_hooks dedupes on. Tests: test_hooks_the_worker_base_already_holds_are_not_copied (only the template's own hook is previewed and written), test_a_template_holding_only_the_bases_hooks_is_added_off_kas (a non-KAS worker is no longer refused). Removing the subtraction turns both red.

3. An allow KAS drops beside allowedTools (GPT): confirmed. merge_worker_spec always sets allowedTools, and merge_user_permissions drops an allow _deriver_could_emit says that list could express. _layer_permissions now refuses such a rule by name (permissions rule N (allow <capability>)) when the target has an allowedTools list. A scoped or excluded allow still travels. Tests: refusal for allow mcp jira/search and a bare allow web_fetch, and test_a_carried_allow_survives_the_workers_kas_projection. Removing the check turns both refusal cases red.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, both points from my last review are fixed at 9bf878d, with tests:

  • _carry_policy now runs without_held(carried, base) first, so hooks, rules and tool settings the worker base already holds are no longer copied or judged against the backend (test_hooks_the_worker_base_already_holds_are_not_copied, test_a_template_holding_only_the_bases_hooks_is_added_off_kas).
  • apply_reporting returns whether the file's policy changed, and the handler then calls crewmate_worker_reload.schedule_reload_workers, so a live worker is reloaded onto the new restriction (test_adding_a_deny_reloads_the_crewmates_idle_worker).

One new problem, flagged by both Opus and GPT (GPT's adjudicator upheld it), and it holds against the code. I'm still requesting changes:

The new derivable-allow refusal rejects ordinary templates.
_layer_permissions (mate_spec_policy.py:184-192) adds every allow that permission_allow_derivable matches to lost whenever the target has allowedTools. But agent._write_derived_permissions writes a permissions block on governed specs, and its rules come from allowed_tools_to_permissions: bare web_fetch/web_search/subagent/skill and literal-server mcp allows, exactly those shapes. _plan calls uncarried_restrictions(source) at line 326 on the whole template, before _carry_policy subtracts what the base holds. So adding abilities from a forked, published or default-derived template fails with template_restrictions_uncarried. Those allows are already carried through the template's allowedTools.

Suggested fix: when allowedTools is present, drop derivable allows (that list already carries them) instead of refusing. At minimum, skip the rules allowed_tools_to_permissions(source["allowedTools"]) produces, and apply without_held before uncarried_restrictions judges the source. A test that adds a template built through build_agent_config (with its derived permissions block) would pin it.

CI note: Frontend Tests (2) failed in i18nAllLanguagesEntry.test.ts ("'./integration/setup.ts' reaches no catalog beyond English", 19 s). That doesn't look tied to this diff.

@buluoray
buluoray force-pushed the crew/slack/worker-kit-carry-restrictions branch from 9bf878d to 57baa14 Compare November 3, 2026 04:05
@buluoray

buluoray commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Disposition for the GPT 6.1 and Opus 5.5 findings on 9bf878d9, addressed in 57baa149. Both describe one regression in the dropped-allow check 9bf878d9 added, and both held.

  • Already-held or generated allows are refused (mate_spec_policy.py:184-190): fixed. The check now refuses an allow only when all four are true:

    • the target is the merged worker spec (layer_policy(..., worker=True), passed by merge_worker_spec; the file-side layering in _carry_policy no longer runs it, so the base's allowedTools is always in view);
    • the target does not already hold the rule;
    • _deriver_could_emit says KAS would drop it;
    • the worker's own allowedTools does not already grant it (kas_tool_view.allow_granted_by_allowed_tools, read from allowed_tools_to_permissions).

    A governed template's generated block, mirroring its own allowedTools, is therefore accepted. An authored allow the worker's list does not carry is still refused by name, because the worker would ask where the template does not.

  • Checked on this host's real files: merge_worker_spec(worker base, worker_additions(base, ~/.kiro/agents/kirocrew.json)) now succeeds; on 9bf878d9 it refused.

  • Tests:

    • test_an_allow_the_target_already_holds_is_not_refused
    • test_a_templates_generated_permissions_block_is_added
    • test_adding_a_governed_template_with_its_generated_block_succeeds
    • The two earlier refusal cases still pass.
  • Mutations: dropping the already-granted check, the already-held check, or the worker-only scope each turns a test red.

@buluoray
buluoray force-pushed the crew/slack/worker-kit-carry-restrictions branch from 57baa14 to 6779c29 Compare November 3, 2026 04:25
@buluoray

buluoray commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Disposition for the GPT 6.1 findings on 57baa149, addressed in 6779c291. Both held, and both are defects in this PR's own allow-rule check.

  • Count governed per-server auto-approvals before refusing an allow (mate_spec_policy.py:199): fixed. The check now reads the same input KAS's projection derives grants from: the allowedTools list plus each governed server autoApprove verb (kas_tool_view.allow_granted_by_spec, via kas_auto_approve.auto_approve_refs(spec, audit=False)). The new audit keyword defaults to True, so the projection is unchanged. A template mounting notes with autoApprove: ["read"] and allow mcp notes/read is now accepted. Test: test_an_allow_a_servers_auto_approve_grants_is_not_refused; reading allowedTools alone turns it red.
  • Validate the permissions rules shape before iterating (mate_spec_policy.py:179): fixed. _layer_permissions and without_held now refuse a rules that is not a list (SpecPolicyUncarried, field permissions) before iterating it. The kit preview therefore answers template_restrictions_uncarried instead of HTTP 500. Test: test_a_permissions_block_whose_rules_is_not_a_list_is_refused_not_crashed (1, a string, an object); dropping the guard crashes the 1 case.

@buluoray
buluoray force-pushed the crew/slack/worker-kit-carry-restrictions branch from 6779c29 to f0ef57c Compare November 3, 2026 04:32
@buluoray

buluoray commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

Owner decision (@buluoray, repo admin), reaffirmed for this PR:

  • Adding an agent's abilities carries its hooks, permissions and an allowlist of toolsSettings keys onto the crewmate's worker only, exactly as the agent declares them, on KAS. The crewmate's chat keeps the stock conductor spec.
  • Anything that cannot be shown to take effect on the worker is refused with its field named: a toolsSettings key outside the allowlist, a value KAS cannot apply, an allow rule the worker would silently lose, or a non-KAS worker backend.
  • When an add changes the crewmate's hooks, permissions or tool settings, its live workers are reloaded onto them.

Recorded in docs/decisions/2026-11-02-a-crewmates-worker-carries-its-template-policy.md.

@bolichen97

Copy link
Copy Markdown
Contributor

Checked at f0ef57c: the allow-rule regression from my last review is fixed, with tests. _layer_permissions now refuses a derivable allow only on the merged worker spec (worker=True). It skips allows the target already holds, and allows the spec's own allowedTools or governed autoApprove already grant (allow_granted_by_spec). test_adding_a_governed_template_with_its_generated_block_succeeds adds a template with its generated permissions block through preview and apply. The earlier fixes (without_held, the worker reload on a policy write, the shell alias and hook cap, the session key) are unchanged.

On the two lane findings for this head:

GPT F2 (a rule the parser drops passes permissions_block_readable) doesn't hold. kas_permissions._parse_rule returns None when a rule's match or exclude holds more than _MAX_PATTERNS_PER_RULE (64) patterns, and parse_user_permissions returns None for the whole block as soon as any rule's parse is None (if rule is None: return None). It never returns a shorter list. So a 65-name exclude makes permissions_block_readable return False, and _layer_permissions names permissions as uncarried. Nothing is dropped silently.

Opus (the decision record isn't backed by a maintainer). That's a fair process point under docs/decisions/README.md rule 4. I'll get the maintainer statement posted on this PR. Once it's there, please set Decided by: and cite that comment's URL under Evidence.

GPT F1 (glob-text coverage) was downgraded by its adjudicator. I'm not blocking on it.

@bolichen97

Copy link
Copy Markdown
Contributor

Maintainer decision: a crewmate's worker carries its template's policy (permissions, hooks, toolsSettings), net of what the worker already holds; the crewmate's chat stays on the stock conductor and gets none of it. Carrying limits to the chat is a possible follow-up, not part of this PR.

@bolichen97

Copy link
Copy Markdown
Contributor

/ai-review override fable f0ef57c owner-decision: agent: the maintainer recorded the policy-carry decision on this PR at #28501 (comment), so the decision entry is now backed by a maintainer statement.

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 recorded a owner-decision release (class owner-decision) for the fable AI finding on f0ef57c46303f2971ff2917013f28539767c3aba.

agent: the maintainer recorded the policy-carry decision on this PR at #28501 (comment), so the decision entry is now backed by a maintainer statement.

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

Adding an agent's abilities to a crewmate refused any agent that set
hooks, permissions or toolsSettings, because the worker kept none of
them. Crewmates the upgrade moved off such an agent could not get its
tools back.

The kit copy now layers the agent's hooks, permission rules and tool
settings into the crewmate's file exactly, and the worker merge carries
them, never wider than the agent declares. Crew fires the worker
session's merged hooks on KAS. A field that cannot land exactly, or a
crewmate whose worker is off KAS, is refused with an error naming the
field. The crewmate's chat keeps running the stock conductor spec.

Closes #26881
@bolichen97

Copy link
Copy Markdown
Contributor

/ai-review override gpt f0ef57c false-positive: agent: F2 does not hold. parse_user_permissions returns None for the whole block when any rule has more than 64 patterns, so permissions_block_readable is False and layer_policy names permissions as uncarried: it fails closed. Code path: #28501 (comment)

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@bolichen97 recorded a false-positive release (class false-positive) for the gpt AI finding on f0ef57c46303f2971ff2917013f28539767c3aba.

agent: F2 does not hold. parse_user_permissions returns None for the whole block when any rule has more than 64 patterns, so permissions_block_readable is False and layer_policy names permissions as uncarried: it fails closed. Code path: #28501 (comment)

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

@buluoray
buluoray force-pushed the crew/slack/worker-kit-carry-restrictions branch from f0ef57c to 9b2fc7c Compare November 3, 2026 04:57
@buluoray

buluoray commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Disposition for the GPT 6.1 findings on f0ef57c4; F1 fixed in 9b2fc7cb, F2 rebutted.

  • Matching glob text does not establish grant coverage (kas_tool_view.py:143): fixed in 9b2fc7cb.

fixed in 9b2fc7c: _pattern_contains counts an MCP allow as granted only when the grant is the same pattern or a whole-server server/* grant over that server; @notes/read_? no longer counts as covering notes/read_* (or the reverse), so such an allow is refused by name. Test test_an_mcp_allow_counts_as_granted_only_when_coverage_is_proved; restoring the text match turns both cases red.

  • A permissions block with a dropped rule passes exact-carriage validation (kas_tool_view.py:115): rebutted.

Rebutted: parse_user_permissions never returns a shorter list. _parse_rule returns None for a rule over _MAX_PATTERNS_PER_RULE, and the loop answers None for the whole block at the first such rule (if rule is None: return None, kas_permissions.py ~994). So a 65-name exclude makes permissions_block_readable False and _layer_permissions names permissions as uncarried. Nothing is dropped silently; @bolichen97 traced the same path in #28501 (comment).

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at 9b2fc7c. I re-read each round's delta, and the earlier fixes all hold:

  • Carried hooks fire on chat, sub-agent and dedicated worker turns (provider_session_key).
  • Restrictions KAS can't enforce are refused by name (tools_settings_unenforced, the CARRIED_TOOLS_SETTINGS allowlist, availableAgents in any form).
  • The shell alias and the hook cap are enforced.
  • Only what the template adds is carried (without_held).
  • A policy write reloads the crewmate's live workers (schedule_reload_workers).

The allow-rule regression is fixed: test_adding_a_governed_template_with_its_generated_block_succeeds adds an ordinary template through preview and apply.

This head:

  • Replaces glob-text matching with _pattern_contains. That function proves coverage only for the same pattern or a whole-server grant, and refuses everything else. A parametrized test covers it.
  • Cites the maintainer decision comment in the decision record.

It stays worker-only: the crewmate's chat runs the stock conductor spec, per the decision.

CI at this head: 85 ok, and the only red is PR Readiness. Every AI lane passes, as do E2E, Integration, CodeQL and the other non-shard jobs.

Suggested follow-ups, not blockers:

  • A test that a template whose permissions rule carries more than _MAX_PATTERNS_PER_RULE patterns is refused as permissions by layer_policy. test_governed_spec_tail.py covers the cap for govern_spec, but not this path.
  • Carrying limits (not grants) to the crewmate's chat.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 3, 2026
@buluoray
buluoray merged commit 0354d5f into main Nov 3, 2026
96 checks passed
@buluoray
buluoray deleted the crew/slack/worker-kit-carry-restrictions branch November 3, 2026 05:46
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 3, 2026
buluoray added a commit that referenced this pull request Nov 3, 2026
Add abilities refused a template whose hooks, permission rules or tool
settings equal ones the crewmate's worker base already holds, with
template_restrictions_uncarried. The preflight layered the template's
whole policy before anything removed what the base holds, so a held
fs_write allowedPaths/fallbackAction entry hit the allowlist.

The preflight now drops held policy with without_held before layering,
as the kit copy already does, and still compares the full template's
restrictions with the merged worker. An unreadable base still refuses.

Mirrors #29392 on main (same diff). Refs #28501
buluoray added a commit that referenced this pull request Nov 4, 2026
…9378)

Adding an agent's abilities to a crewmate refused any agent that set
hooks, permissions or toolsSettings, because the worker kept none of
them. Crewmates the upgrade moved off such an agent could not get its
tools back.

The kit copy now layers the agent's hooks, permission rules and tool
settings into the crewmate's file exactly, and the worker merge carries
them, never wider than the agent declares. Crew fires the worker
session's merged hooks on KAS. A field that cannot land exactly, or a
crewmate whose worker is off KAS, is refused with an error naming the
field. The crewmate's chat keeps running the stock conductor spec.

Closes #26881

(cherry picked from commit 0354d5f)

Conflict: src/kiro_crew/docs/agent-spec-fields.md (hooks row). Kept
the release text and added only this change's crewmate sentence.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Let a crewmate's tool restrictions also narrow its conductor

2 participants