Skip to content

fix: let a bot take an agent with many hooks and sub-agent or skill allows - #31241

Merged
bolichen97 merged 2 commits into
kirodotdev:mainfrom
leozhad:leozh/bot-agent-hooks-and-allows
Nov 11, 2026
Merged

bolichen97 merged 2 commits into
kirodotdev:mainfrom
leozhad:leozh/bot-agent-hooks-and-allows

Conversation

@leozhad

@leozhad leozhad commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An installed agent with more than 20 hooks, or with bare sub-agent and skill allows, can be added to a Bot, and its worker runs all of it.

Adding such an agent's abilities to a Bot is refused with template_restrictions_uncarried: hooks, permissions rule 5 (allow subagent), permissions rule 6 (allow skill), so the Bot's worker gets none of the agent's hooks or rules. The same agent run directly in a KAS chat also loses every hook past the 20th, with a warning.

Why it matters

An agent installed and kept up to date by an external package manager commonly ships more than 20 hooks (setup, guards, sync). Today that agent can't be given to a Bot at all, and a plain KAS chat on it silently skips part of its own guards and sync steps.

Not a goal

  • A Bot's worker following an installed agent live, and keeping the Bot's own directions beside the agent's. That needs a maintainer decision first, asked in Let a Bot's worker follow an installed agent live, keeping the Bot's own directions #31219.
  • Carrying a name-scoped built-in allow (subagent limited to named agents). It has no exact allowedTools spelling and is kept as a permission rule, as before.
  • Changing the caps on the Hooks page's own hooks (kiro_hooks._MAX_USER_HOOKS_PER_EVENT, _MAX_TOTAL_USER_HOOKS).
  • Changing the conductor, or what the governance ceiling allows.

What changed (motivation → approach → change)

Two causes, one commit each.

  1. Hook cap. agent_sdk/spec_hooks._MAX_SPEC_HOOKS was 20. spec_script_hooks read no more than that per spec, and mate_spec_policy._layer_hooks refused a merged worker spec past it. The bound exists so a runaway spec cannot spawn without limit on every turn. It is now 64: still a bound, high enough that an installed agent's ordinary set runs whole, as kiro-cli runs it. The standalone ~/.kiro/hooks files share the same bound and move with it.
  2. Built-in allows. With an allowedTools list present, KAS's projection drops a built-in allow the list could express, so _layer_permissions refused it as uncarried. fix(mate): carry template mcp allows for base-declared servers to workers #29893 carries an mcp allow as its allowedTools refs; this does the same for an unscoped built-in allow. kas_tool_view.builtin_allow_tool returns the one allowedTools name KAS derives the rule back from (kas_permissions.CAPABILITY_BY_TOOL: use_subagent for subagent, disclose_context for skill). mate_spec_policy._carry_builtin_allow adds it only when allow_granted_by_spec then proves the rule granted, never writes a tool the worker excludes, and leaves a rule with match or exclude alone, so nothing wider than the rule is written. The governance ceiling still filters the merged list.

The Add-abilities preview counts that grant too. #33033 made it count a carried mcp allow; mate_worker_kit._permission_refs now also lists a carried built-in name (use_subagent, disclose_context) as an allowedTools row, and _runs_unasked reports that the add lets it run without a prompt, so the preview shows every grant the merge writes. Tested by test_mate_spec_policy.py::test_a_builtin_allow_previews_as_the_tool_name_the_worker_gains.

This applies the 2026-11-02 decision (docs/decisions/2026-11-02-a-crewmates-worker-carries-its-template-policy.md, carry exactly or refuse) to rules it refused although they could be carried exactly. docs/system-specs/modules/crew-mode.md, src/kiro_crew/docs/crew-members.md and src/kiro_crew/docs/steering-and-hooks.md describe both.

Backwards compatibility

Compatible: every worker and chat that started before starts with the same grants and hooks. A spec with 21 to 64 hooks now runs all of them instead of the first 20, and an add that was refused for these rules now succeeds.

Removes nothing: the change only raises a bound and carries rules that were refused; no field, key, route or record is removed or narrowed.

Tests

  • test/test_crew_fired_spec_hooks.py: an agent spec with 26 hooks across three events runs all 26; the over-cap audit tests keep reading the cap from the constant.
  • test/test_kas_user_hook_files.py: the over-cap file fixture is built from the cap instead of a fixed 30.
  • test/test_mate_spec_policy.py:
    • a bare subagent, skill or web_fetch allow lands as use_subagent, disclose_context or web_fetch, and allow_granted_by_spec proves it
    • a name-scoped subagent allow is never widened to use_subagent
    • an excluded use_subagent gets no auto-approval back, and the worker starts
    • the ceiling still withholds a carried name
    • end to end: adding an agent with 26 hooks and both allows previews and applies, and the merged worker carries 27 hooks and both names

Proof: PROVEN test/test_crew_fired_spec_hooks.py::test_an_installed_agents_twenty_six_hooks_all_run (head 3d01799)

Run on head 3d01799: the line above is prove.py's output, which reverts the production hunks in a throwaway worktree. 458 tests pass across test_crew_fired_spec_hooks.py, test_kas_user_hook_files.py, test_mate_spec_policy.py and the ten Bot-worker test files. black, isort, flake8, mypy on the four changed modules, check_brand_name.py, check_comment_history.py, check_decisions_history.py, check_changelog_history.py, check_feature_map.py, check_testpaths_coverage.py, check_file_line_cap.py, check_subprocess_encoding.py, check_harness_parity.py and docs-lint.sh pass.

Of the other test files that import the worker kit, 304 tests pass and one fails: test_harness_parity.py::test_is_kiro_cli_is_positive. It fails the same way on plain main, because the test host has a Copilot CLI config file in its home directory. This change does not cause it.

Manual verification

On a real install, the add preview for an agent with 26 hooks and both allows was refused with the error above before this change. The fix is covered end to end by the unit test that previews and applies that shape; I have not re-run the live add on this branch.

Related Issues

Closes #31218

Sibling sweep

Swept: git grep -n "_MAX_SPEC_HOOKS|permission_allow_derivable|_carry_mcp_allow" -- src/
Sibling: src/kiro_crew/agent_sdk/spec_hooks.py -- changed here
Sibling: src/kiro_crew/mate_spec_policy.py -- changed here
Sibling: src/kiro_crew/agent_materialization/kiro_hooks.py -- not affected -- caps the Hooks page's own hooks merged into specs Crew renders, not a spec's own hooks

Pattern harvest

Not generalizable: two bounds and one carry table that predated agents of this size; no wider shape to lint for.

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; see the Licensing section of CONTRIBUTING.md.

@leozhad
leozhad requested review from a team and KiroCrewCaptain as code owners November 6, 2026 08:00
@leozhad
leozhad requested a review from Zedmor November 6, 2026 08:00
@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Nov 6, 2026
@leozhad

leozhad commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Hi maintainers, this is a fork PR, so its workflow runs are waiting for approval (action_required). Could someone approve them when you have a moment? Thank you.

The two red rows so far, Fork PR Description and PR Readiness, did not fail on content. Both hit API rate limit exceeded for installation while publishing. The description check itself reported success, and the template check passes locally. A re-run should clear them.

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 6, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 8, 2026
@leozhad
leozhad force-pushed the leozh/bot-agent-hooks-and-allows branch from a109dba to 16c6eb7 Compare November 8, 2026 05:01
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 8, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 8, 2026
Crew fires an agent spec's own hooks itself on KAS and the other
harnesses that carry no hooks field, and read only the first 20 of
them. An installed agent with 26 hooks lost six in a plain chat, and a
Bot whose merged worker spec passed 20 was refused when abilities were
added from that agent.

Raise the per-spec bound to 64. It still stops a runaway spec from
spawning without limit on every turn, and an installed agent's ordinary
set now runs whole, as kiro-cli runs it.
Adding an agent's abilities to a Bot carries its permission rules onto
the Bot's worker exactly, or refuses. With an allowedTools list present,
KAS's projection drops a built-in allow the list could express, so a
bare allow on subagent or skill was refused as uncarried, and the whole
add failed.

Carry such an allow as the one allowedTools name KAS derives it back
from (use_subagent for subagent, disclose_context for skill), the way an
mcp allow is carried as its refs. Only an unscoped allow on a capability
exactly one tool name stands for is carried; a name-scoped allow is
never widened to the whole tool. An excluded tool is not written back,
and the governance ceiling still filters the merged list.

The Add-abilities preview lists that tool name as an approval row and
says the add lets it run unasked, so it shows every grant the add
writes.
@leozhad
leozhad force-pushed the leozh/bot-agent-hooks-and-allows branch from 16c6eb7 to 3d01799 Compare November 8, 2026 10:26
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 8, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 3d01799bfde3387acf51f0cd2881a153c580d05a touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 3d01799bfde3387acf51f0cd2881a153c580d05a via the fork AI-review pipeline — 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: both causes are fixed where they start (the bound and the carry rule), issue #31218 is the provenance, and the preview change follows the base rule that a preview lists every grant the file will hold.

Notes

  • Item 3 — duplicate: builtin_allow_tool inverts CAPABILITY_BY_TOOL again with for tool, capability in kas_permissions.CAPABILITY_BY_TOOL.items() if capability == .... The base already ships that inversion as kas_permissions.CEILING_REFS_BY_CAPABILITY (kas_permissions.py:959). Subtraction: delete the list comprehension and read CEILING_REFS_BY_CAPABILITY.get(rule["capability"], ()), keeping the single-entry check.
  • Item 6 — inherited: user docs repeat the literal "up to 64" (steering-and-hooks.md) and crew-mode.md writes "_MAX_SPEC_HOOKS (64)", so the cap now lives in three places that can drift. Subtraction: drop "(64)" and refer to _MAX_SPEC_HOOKS by name, as agent-spec-fields.md:585 already does.

What this change ships

Inventory (6 items) — 4 justified

Intent: let an installed agent with many hooks and bare sub-agent/skill allows be added to a Bot and run whole. This is a FIX.

  1. An agent spec's hooks now run up to 64 instead of being cut after 20 — justified
  2. The standalone ~/.kiro/hooks files get the same higher bound — justified
  3. Adding an agent with a bare subagent/skill allow now succeeds, and the worker auto-approves use_subagent/disclose_context — duplicate of kas_permissions.CEILING_REFS_BY_CAPABILITY inversion
  4. A bare web_fetch/web_search allow is carried the same way — undeclared in the Goal; tests mention it
  5. The Add-abilities preview lists the carried tool names and reports that they run unasked — justified
  6. Docs restate the new cap value — inherited

[FIRST-PRINCIPLES-REVIEWED] 3d01799

Description read

[DESCRIPTION-READ] 8c46bd4ec1dae6a03b712002d32da553eed0f5d087994ba24a8cc79bb99c015b

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 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 3d01799bfde3387acf51f0cd2881a153c580d05a via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns. Both changes stay within the 2026-11-02 "carry exactly or refuse" decision: the carry only fires after allow_granted_by_spec proves the rule is granted, a name-scoped allow is never widened, and the hook limit is still a bound.

Notes

  • The removed test test_a_builtin_allow_the_workers_allowed_tools_would_override_is_refused pinned a refusal caused by a missing carry path, not a decision forbidding the carry, so replacing it is a gap fix.
  • _MAX_SPEC_HOOKS (now 64) and kiro_hooks._MAX_TOTAL_USER_HOOKS (still 20) used to be the same number and now differ. The old comment that tied them ("the same total the materialized spec is capped at") was rightly dropped.

[DESIGN-REVIEWED] 3d01799

Description read

[DESCRIPTION-READ] 2f27e0f6b0c7eceadf6f5736128b5a4078ceacda9a610d28b0247c45323fe31f

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 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings (all downgraded on adjudication)

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

Opus 5.5 adjudication downgraded every blocking finding. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

Review details

BLOCKING -- src/kiro_crew/mate_worker_kit.py:221 -- Excluded built-ins are falsely previewed as new auto-approvals

carried = [name] if name else None
Trigger: Add an agent with a bare subagent allow to a Bot that excludes use_subagent; preview() reaches _permission_refs() through _approval_changes() and _runs_unasked().
Outcome: The dashboard lists use_subagent under Auto-approvals and promises it runs without asking, although _carry_builtin_allow() withholds the approval and the merged worker excludes the tool.
Anchor: defect
Fix: Filter built-in permission refs against the file’s and worker base’s exclusions before generating approval rows or calculating runs_unasked.

[BLOCK-MERGE-DOWNGRADED] 3d01799
[GPT-REVIEWED] 3d01799

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1: LOW. The defect only overstates the preview, and it errs toward caution. The diff (mate_spec_policy.py +200–201) writes nothing for an excluded tool, so the worker gains no permission. The only result is a spurious use_subagent row and runs_unasked=true in the preview (mate_worker_kit.py:798, :808). The other place the result is used, apply's regrant at :858 → mate_approval_revocations.py:68, can clear only a revocation of an approval the base grants. _permission_refs already drops those (:211-219), so no real revocation is lost.

Fixing it means copying the merge's exclusion model into the preview predicates: the file's excludedTools, joined with the base's excludedTools, with the base's per-server disabledTools mapped to refs (:412-413, :498-502). That second copy would have to keep tracking the merge. The mcp channel at :214-219 already goes without that filter on the base branch. That cost is larger than the harm of one cautious, visible extra warning.

[ADJUDICATION] 3d01799bfde3387acf51f0cd2881a153c580d05a total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/mate_worker_kit.py:221 reason=disproportionate-remedy
[GPT-ADJUDICATED] 3d01799bfde3387acf51f0cd2881a153c580d05a

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 3d01799

@bolichen97 bolichen97 closed this Nov 11, 2026
@bolichen97 bolichen97 reopened this Nov 11, 2026
@bolichen97 bolichen97 closed this Nov 11, 2026
@bolichen97 bolichen97 reopened this Nov 11, 2026
@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 11, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

Approve. The hook cap goes from 20 to 64 and every consumer reads the constant; it is still a bound and is shared with the ~/.kiro/hooks files. The new carry of bare built-in allows (subagent→use_subagent, skill→disclose_context) only fires on an exact unscoped allow, is proved by allow_granted_by_spec before it is written, never writes an excluded tool, and still passes through the governance ceiling. Revocations are stripped after the merge, so a revoked approval stays revoked. The preview lists the new row and sets runs_unasked, and apply's re-grant only touches approvals the file adds. Tests cover the new behaviour, and prove.py shows the hook test fails with the production change reverted.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 3d01799bfd · 258 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@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 head 3d01799bfd.

  • builtin_allow_tool maps only an unscoped allow (capability + effect alone) whose capability exactly one Crew tool name stands for. A name-scoped subagent allow stays a permission rule, so nothing is widened past the rule.
  • _carry_builtin_allow writes that one name only after allow_granted_by_spec proves it grants the same rule, and it respects excludedTools. The governance ceiling still runs over the merged spec.
  • Raising _MAX_SPEC_HOOKS from 20 to 64 keeps a bound, and the docs now say hooks past it are named in a warning.

On this head, test_crew_fired_spec_hooks.py + test_kas_user_hook_files.py + test_mate_spec_policy.py gave 198 passed. CI and every review lane pass. I'll merge it now.

AI-assisted, sent by CommunityCrew

@bolichen97
bolichen97 merged commit ea742a7 into kirodotdev:main Nov 11, 2026
185 of 202 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A Bot cannot take abilities from an agent with more than 20 hooks or sub-agent and skill allows

3 participants