Skip to content

fix(agents): name toolsSettings aliases as the spec wrote them - #32649

Merged
bolichen97 merged 1 commit into
mainfrom
crew/CommunityCrew/pr31742-takeover
Nov 8, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
crew/CommunityCrew/pr31742-takeover

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Supersedes #31742 (rebased onto latest main; resolved src/kiro_crew/docs/agent-spec-fields.md). Original author: @keyejia.

Problem / Motivation

Goal: A spec that writes a toolsSettings alias such as use_subagent gets an unapplied-settings notice naming that exact key, and the agent spec reference lists every sub-agent spelling Crew reads and which one wins.

Since #30193, canonical_tools_settings files every sub-agent spelling under subagent. The session-start notice builds its names from that folded copy, so a spec that wrote only toolsSettings.use_subagent.trustedAgents is told about toolsSettings.subagent.trustedAgents, a key the author cannot find in the file. agent-spec-fields.md also says only toolsSettings.subagent.availableAgents is read.

Why it matters

The notice exists so an author can find what goes unapplied. A name that is not in their spec sends them looking for a key they never wrote, and the reference page hides that four other spellings are read too, and that only one of them counts when several are set.

Not a goal

  • Changing which spelling wins, or what any gate enforces.
  • Renaming the sub-agent key in the spawn tool hints the model reads.

What changed (motivation → approach → change)

Every notice now names a kept alias the way the spec spelled it. Crew still reads the same one key per alias group.

Before After
use_subagent: {trustedAgents} → notice names toolsSettings.subagent.trustedAgents notice names toolsSettings.use_subagent.trustedAgents
crew / agentCrew / executeBash → named as subagent / shell named as written
subagent alone, or beside use_subagent unchanged: subagent wins whole, toolsSettings.use_subagent is named as dropped

The root cause is one place: names were read off the folded copy. platform/tools_settings_aliases.py gains as_authored, which maps a folded key back to the spelling the spec kept, sharing the rename rule with canonical_tools_settings through _filed_under. It is applied wherever a notice names an entry read off the folded copy: tools_settings_reach.tools_settings_unapplied (every non-KAS backend), the KAS branch of kas_agents.spec_keys_without_carrier, and kas_tool_view.tools_settings_unenforced (the worker policy's refusal names). Dropped duplicates were already named as written.

Docs: src/kiro_crew/docs/agent-spec-fields.md (the toolsSettings row) and docs/system-specs/modules/subagent.md (§ Parent agent spec allowlist) list the five sub-agent spellings in kiro-cli's precedence, crew, agent_crew, agentCrew, subagent, use_subagent, and say the first one set wins whole.

Backwards compatibility

Compatible: only the wording of notices and worker-policy refusals changes, and only for a spec that uses an alias spelling; every gate reads the same key as before.

Removes nothing: no key, path, rule or function is removed; the notice names the same entries under the spec's own spelling.

Tests

Inputs that reach this code, and where each is covered:

Input Non-KAS notice KAS notice + worker tool view Session-start notice end to end
only subagent existing rows subagent.trustedAgents, subagent.x existing tests
only use_subagent use_subagent.trustedAgents (both branches) use_subagent.trustedAgents, use_subagent.x 6 backends, spec on disk
other alias (crew, agentCrew, executeBash) crew, executeBash agentCrew, executeBash.allowedCommands
fsWrite.allowedPaths with the write grant withheld fsWrite.allowedPaths
both, same value subagent.* + dropped use_subagent same
both, conflicting values same as above same
empty / absent existing rows (None, {}) existing test

Proof: PROVEN test/test_kas_tools_settings_aliases.py::TestNotice::test_a_kept_alias_is_named_as_the_spec_wrote_it[settings1-named1], test/test_kas_tools_settings_aliases.py::TestNotice::test_a_kept_alias_is_named_as_the_spec_wrote_it[settings2-named2], test/test_kas_tools_settings_aliases.py::TestNotice::test_a_kept_alias_is_named_as_the_spec_wrote_it[settings5-named5], test/test_kas_tools_settings_aliases.py::TestNotice::test_withheld_write_paths_are_named_as_the_spec_wrote_them, test/test_tools_settings_notice.py::test_only_what_the_spawn_gate_does_not_read_is_named[settings9-named9] (head 7cb18a5)

Reverting the source by hand fails 13 of the new cases: every alias-spelling row and all six end-to-end backends. The subagent-only and both-set rows pass before and after, as no-regression pins.

Determinism: the 33 new and changed node ids passed 20 runs at -n0, 10 runs at -n 4 --dist loadgroup beside test_kas_tools_settings.py and test_side_readonly_spec.py, and one shuffled order (seed 21604). Backend related set on this rebase (run_scoped_tests.py --surface backend): 6607 passed, 10 skipped, 1 failed: test_acp_harness_contract.py::test_a_missing_self_served_binary_names_its_install_command[copilot], which fails the same way on origin/main on this host.

Manual verification

N/A — unit coverage sufficient: the names come from pure functions, and the end-to-end test drives the real session-start path with a spec file on disk.

Screenshots / video

N/A — no frontend file changed; the notice is a text row the backend builds.

Related Issues

Closes #31663

Sibling sweep

Swept: git grep -nE 'toolsSettings.{|toolsSettings.subagent' -- src/
Sibling: src/kiro_crew/agent_sdk/tools_settings_reach.py -- changed here
Sibling: src/kiro_crew/acp/kas_agents.py -- changed here
Sibling: src/kiro_crew/agent_sdk/kas_tool_view.py -- changed here
Sibling: src/kiro_crew/mate_spec_policy.py -- not affected -- its own names iterate the template's keys as written; the folded names it reads come from tools_settings_unenforced, changed here
Sibling: src/kiro_crew/dashboard/side_readonly_spec.py -- not affected -- names a key of the derived spec it writes in folded form, so that key is in that file, and only the operator log shows it
Sibling: src/kiro_crew/mcp_tools/spawn_parts/schemas.py -- not affected -- a tool hint the model reads, not a notice an author searches the spec for
Sibling: src/kiro_crew/mcp_tools/spawn_parts/listing.py -- not affected -- the same model-facing hint

Pattern harvest

Rule candidate: review-prompt
Pattern: a user-facing message names a key from a normalized copy of the user's input instead of the spelling the user wrote

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

Contributed under the project's Apache-2.0 license.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 7, 2026 21:57
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 7cb18a51bf409d45ca453c0a644befbc01ba5aae 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 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the fix sits at the root cause (names read off the folded copy). It shares one rename rule with canonical_tools_settings, changes only the wording of notices and refusals, and every gate still reads the same keys.

Notes

  • mate_spec_policy._layer_tools_settings already names _outside_allowlist entries as the spec wrote them. Now that tools_settings_unenforced uses the same spelling, both can name the same alias path, so the worker refusal list may repeat an entry. Dedupe lost there if that shows up.

[DESIGN-REVIEWED] 7cb18a5

Description read

[DESCRIPTION-READ] dbc45f46989fbc2b0882495d5ab3907a448679120f2c329ce39f4b6fe004cb46

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 7cb18a51bf409d45ca453c0a644befbc01ba5aae — 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: this fixes linked issue #31663 where the names come from, the folded copy. Every site that builds a notice now uses one shared helper, and the docs are part of the stated Goal.

What this change ships

Inventory (6 items) — 6 justified

Intent: when a spec uses an alias spelling (such as use_subagent), its author sees notices that name the key exactly as written, and the reference page lists every sub-agent spelling Crew reads and which one wins. FIX.

  1. Non-KAS session-start notice names a kept alias as the spec wrote it (use_subagent.trustedAgents, crew, executeBash) — justified
  2. KAS session-start notice names kept aliases as written, including the withheld shell and write paths — justified
  3. Worker-policy refusal names use the spec's spelling — justified
  4. New as_authored helper puts the spec's spelling back; the rename rule moves into the shared _filed_under — justified
  5. agent-spec-fields.md toolsSettings row lists the five sub-agent spellings, their precedence and that the first one set wins whole — justified
  6. subagent.md § Parent agent spec allowlist states the same precedence — justified

[FIRST-PRINCIPLES-REVIEWED] 7cb18a5

Description read

[DESCRIPTION-READ] 68f3b62962ca0a2f9ae7ac41eadc1ea39f87cb9ab2ef4afc52a9280d86041182

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 7cb18a51bf409d45ca453c0a644befbc01ba5aae — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 7cb18a5

Verdict parsed from the review's SHA-scoped output markers for commit 7cb18a51bf409d45ca453c0a644befbc01ba5aae.

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

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 7cb18a51bf409d45ca453c0a644befbc01ba5aae and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7cb18a5

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 7, 2026 22:14
@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 7, 2026
@bolichen97 bolichen97 closed this Nov 8, 2026
auto-merge was automatically disabled November 8, 2026 00:32

Pull request was closed

@bolichen97 bolichen97 reopened this Nov 8, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 8, 2026
@bolichen97 bolichen97 closed this Nov 8, 2026
@bolichen97 bolichen97 reopened this Nov 8, 2026
@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 8, 2026
@bolichen97
bolichen97 force-pushed the crew/CommunityCrew/pr31742-takeover branch from 12829cd to ad01003 Compare November 8, 2026 03:55
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Rebased: main moved since this head ran; CI re-running. The Windows shard 2 red (test/test_crew_log_writer_lanes.py::test_a_rebuilt_writer_does_not_write_beside_a_retired_writers_stuck_lane, flush returned False on the old wait) ran on a merge base older than #32813, which fixed that test on main; the new base carries it and #32606. Same patch, no code change. Local scoped gate (flake8, isort, mypy, related tests including that file: 565 passed) and local GPT and Opus reviews passed with no findings.

@bolichen97
bolichen97 force-pushed the crew/CommunityCrew/pr31742-takeover branch from ad01003 to 8f4f006 Compare November 8, 2026 04:13
@bolichen97

bolichen97 commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the withheld write allowedPaths notice names the key through as_authored

  • span=6b6df01cc0c1: A withheld fsWrite.allowedPaths is reported under the folded key

fixed in 8f4f006: spec_keys_without_carrier in kas_agents.py builds the write allowedPaths name with as_authored(raw, key), as the allowedCommands branch does, so a spec that wrote fsWrite is told toolsSettings.fsWrite.allowedPaths.
Test: test_withheld_write_paths_are_named_as_the_spec_wrote_them fails on the old line and passes now (prove.py PROVEN); every other toolsSettings.{ name in that function was checked and already uses the spec's spelling.

@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 8, 2026
canonical_tools_settings files every sub-agent spelling under
`subagent`, and other unknown alias spellings under the key Crew
reads (`executeBash` under `shell`). The unapplied-settings notice
built its names from that folded form, so a spec that wrote only
`use_subagent` was told about `toolsSettings.subagent.*`, a key the
author cannot find in the file.

Add `as_authored`, which puts the kept spelling back on a name read
off the folded form, and use it wherever a notice names an entry:
the session-start notice on every backend (KAS included) and the KAS
tool view the worker policy reads. Dropped duplicates were already
named as written and are unchanged.

Document in agent-spec-fields.md and the subagent spec every
sub-agent spelling Crew reads and that the first one in kiro-cli's
order wins whole.

Co-authored-by: Kellen Jia <6888461+keyejia@users.noreply.github.com>
@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
@bolichen97
bolichen97 force-pushed the crew/CommunityCrew/pr31742-takeover branch from 8f4f006 to 7cb18a5 Compare November 8, 2026 04:26
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Rebased: main moved in src/kiro_crew/docs/agent-spec-fields.md (a new hooks-row sentence beside this PR's toolsSettings-row edit) and the PR went CONFLICTING; resolved keep-both (main's hooks row, this PR's toolsSettings row), CI re-running. Same patch otherwise; scoped gate and prove.py re-run on the new head.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 8, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 8, 2026 05:07

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved. On this head the review checked four things. The fold in canonical_tools_settings behaves exactly as before, so the spawn, side turn and allowlist gates that read it are unchanged. as_authored maps every alias group back to the one key the spec wrote. No caller parses these notice strings back into keys. Reverting each new call site, one at a time, makes 7 of the 9 fail a test.
Done well: the rename rule now lives in one helper, _filed_under, which both the fold and the reverse lookup use, so the two cannot drift apart.
Optional:

  • Two sites have no test: the withheld shell allowedCommands name (kas_agents.py:305) and the non-dict entry next to a gate-applied allowlist (tools_settings_reach.py:67). An executeBash.allowedCommands case and a fsRead: True row would pin them.
  • Whichever of this PR and #31892 merges second must also send the inexact paths from #31892 through as_authored. Otherwise shell.allowedCommands comes back in the worker refusal.
  • After this merges, close #31742 as superseded by this PR.

@bolichen97
bolichen97 merged commit 2f8cab5 into main Nov 8, 2026
99 checks passed
@bolichen97
bolichen97 deleted the crew/CommunityCrew/pr31742-takeover branch November 8, 2026 05:37
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 8, 2026
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.

Sub-agent toolsSettings alias: spec doc and unapplied notice still name only 'subagent'

3 participants