Skip to content

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

Closed
keyejia wants to merge 1 commit into
kirodotdev:mainfrom
keyejia:fix/subagent-alias-notice
Closed

keyejia wants to merge 1 commit into
kirodotdev:mainfrom
keyejia:fix/subagent-alias-notice

Conversation

@keyejia

@keyejia keyejia commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

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
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_tools_settings_notice.py::test_only_what_the_spawn_gate_does_not_read_is_named[settings9-named9], test/test_tools_settings_notice.py::test_only_what_the_spawn_gate_does_not_read_is_named[settings10-named10] (head 9dc2072)

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). python3 scripts/local-gate.py: 3445 passed, 7 skipped (backend related set).

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.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Nov 6, 2026
@keyejia
keyejia marked this pull request as ready for review November 6, 2026 21:50
@keyejia
keyejia requested review from a team and KiroCrewCaptain as code owners November 6, 2026 21:50
@keyejia
keyejia requested a review from tim-finnigan November 6, 2026 21:50
bolichen97
bolichen97 previously approved these changes Nov 6, 2026

@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.

Reviewed at 9dc2072bf2 (T1, closes #31663). Thanks, and welcome!

The fix is in the right place: as_authored(raw, path) maps a path from the folded toolsSettings back to the spelling the spec wrote. It uses _filed_under, the same rule canonical_tools_settings folds by, now pulled out so the two can't drift. So a spec that wrote use_subagent (or crew, or executeBash) is told about that key, not about subagent/shell. Each place that names an unapplied key goes through it: kas_agents.spec_keys_without_carrier, kas_tool_view.tools_settings_unenforced and tools_settings_reach. Dropped spellings are already named as written, and agent-spec-fields.md now lists every sub-agent spelling and which one wins. The new tests cover the alias round-trip and the notice text. One commit, no merge commits.

Approved on this head. It merges once fork CI and the AI review lanes on this head are green.

AI-assisted, sent by CommunityCrew

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 7, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Hi @keyejia, this PR had a merge conflict with main for more than 24 hours, so I took it over per the team's process in #32649. It is an in-repo PR from the latest main:

  • Your commit is unchanged. You stay the author, with a Co-authored-by trailer.
  • The only conflict was the toolsSettings row in src/kiro_crew/docs/agent-spec-fields.md. Main had reworded that row, so fix(agents): name toolsSettings aliases as the spec wrote them #32649 keeps main's wording and adds your paragraph on the five sub-agent spellings unchanged.

Your branch was not touched. If you'd rather keep going here, say so and I'll close #32649 instead. Otherwise this one can be closed once #32649 merges.

AI-assisted, sent by CommunityCrew

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.
@keyejia
keyejia force-pushed the fix/subagent-alias-notice branch from 9dc2072 to 390037b Compare November 8, 2026 00:26
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 8, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Closing: your change landed in #32649 (merged as 2f8cab5), with your commit and authorship kept. Thanks @keyejia!

AI-assisted, sent by CommunityCrew

@bolichen97 bolichen97 closed this Nov 8, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 8, 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) merge conflict Branch has merge conflicts with its base — author must resolve before merge

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'

2 participants