Skip to content

fix(kas): resolve a checkout's .kiro/agents spec nearest-first - #18911

Merged
chenmingwei23 merged 2 commits into
mainfrom
feat/kas-project-agents
Oct 11, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
feat/kas-project-agents

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A KAS session can run an agent that is declared only in the checkout's .kiro/agents/, as kiro-cli already can, without the checkout gaining any power to launch, approve or load anything.

kiro-cli resolves --agent against <project>/.kiro/agents/ before the user level. KAS gets its agent from Crew over _meta.kiro.customAgents, and that projection read paths.kiro_agents_dir() only. So an agent that exists only in the checkout ran on kiro-cli and was refused on KAS at session start:

AcpRuntimeError: cannot project agent 'probe-only' onto KAS: agent spec <home>/agents/probe-only.json is unreadable: [Errno 2] No such file or directory

Why it matters

A repository that ships its own agent works on kiro-cli and is refused on KAS. Users who move to KAS lose project agents, and picking that agent fails at session start with an error that names a file they never meant to create.

Not a goal

  • Full parity, meaning the checkout spec projected as-is. That was considered and declined; see below.
  • A workspace-trust consent that would let a checkout choose MCP servers, approvals or hooks (session_mcp._project_mcp_trusted stays False).
  • Any change to kiro-cli or to the mirrored hosts.

What changed (motivation → approach → change)

Symptom → root cause → change:

  • Symptom: a project-only agent is refused on KAS.
  • Root cause: KasHarness.session_extras and AcpRuntime._projected_spawn_spec both read the user-level directory alone.
  • Change: both now go through one resolver, acp.harness.kas.resolve_projected_spec.

Root-cause proof, run before the fix on origin/main 955c2cc (empty user-level dir, <checkout>/.kiro/agents/probe-only.json):

Resolver Result
agent_discovery.project_agent_files (kiro-cli dispatch list) ['probe-only.json']
acp.session_mcp._project_spec_path_for (mirrored hosts) found
KasHarness.session_extras refused (error above)

After the fix the same probe projects {"id": "probe-only", "prompt": "hello", "tools": ["fs_read"]}.

The resolver changes only what happened to a project-only name:

  • A name the user level declares resolves to the user-level spec exactly as on main, whatever the checkout holds. That includes an unreadable checkout spec.
  • Only a name the user level does not declare is looked up in the checkout, through the mirrored hosts' resolver (session_mcp.project_agent_spec, declared name beats the filename).
  • A derived agent still uses its freshness-gate snapshot.

A checkout spec is untrusted input, so a project-only agent gets an allow list:

Project-only spec key KAS session
name, description, prompt, tools, excludedTools, model honoured
mcpServers, allowedTools, permissions, hooks, includeMcpJson, includePowers, resources, any other key dropped
file:// prompt anchored to the checkout's .kiro/agents (paths.project_agents_dir); a rooted path (absolute, ~, or /x on Windows) is refused, and .. escapes are refused as before
unreadable spec refuses the session (there is no other spec of that name)

So the servers and hooks a KAS session runs are always user-level. Crew's spec hooks (which read the user level on KAS) and the projection's hook-gated approval filter see the same hooks.

A tool that the honoured tools list reveals still resolves to ask.

Considered and declined: projecting the checkout spec as-is. Full parity would mean sending the checkout spec unchanged, as kiro-cli does in a trusted workspace. Any cloned repository could then launch its own MCP commands at session/new, outside the sandbox and before any prompt. It could also auto-approve its own tools. Crew cannot read kiro-cli's workspace-trust verdict, so this PR does not ship that untrusted-input-to-execution path.

Blast radius. The servers a KAS session runs are still the user-level ones. So KAS stays in ACP_BACKENDS_USER_LEVEL_AGENT_SPECS_ONLY, now described as "servers come from the user level alone". overlay_project_scope still answers {} for KAS. The unscoped stub lookup in harness/kas.py is unchanged in behaviour (only its comment changed). The pinned test_kas_agents.py scope and subtraction tests pass unchanged. Docs that said KAS refuses project-only agents are updated (docs/architecture/mcp.md, agent-host-contract.md, providers.md).

Backwards compatibility

Compatible: every name the user level declares resolves exactly as on main. A project-only name used to be refused and now runs with its prompt and tools.

Removes nothing: no key, path, record or public function is taken away. kas_agents.load_agent_spec is unchanged and is still the user-level read.

Tests

test/test_kas_project_agents.py (new, 11 tests):

  • A project-only agent binds with its prompt (a relative file:// anchored to the checkout), tools, excludedTools and description.
  • A project spec carrying every grant key puts none of them on the wire.
  • A shadowing project spec changes nothing about the user agent: same prompt, tools and servers, nothing planted, nothing muted, nothing approved.
  • A shadowing project spec leaves the user-level hooks in place, and the projected hook matchers equal the ones the stale-batch check reads.
  • An unreadable shadowing spec still runs the user agent. An unreadable project-only spec refuses.
  • With no project spec, the user-level agent is projected.
  • Absolute, ~ and .. project prompt paths are refused.
  • The tool-search handshake judges the same resolved spec.

Mutation checks:

  • Projecting the checkout spec whole fails the two grant tests.
  • Reading the checkout before the user level fails all three shadow tests.

test_acp_tool_search_wire.py::TestProjectedSpawnSpecRead now patches kas_agents.load_agent_spec, the read the runtime reaches through the resolver.

Run: python3 -m pytest test/test_kas_project_agents.py test/test_kas_agents.py test/test_acp_harness_contract.py test/test_acp_tool_search_wire.py test/test_member_dispatch_mount.py test/test_worker_agent.py test/test_agent_sdk_capabilities.py test/test_agent_home_isolation.py: 824 passed, 7 skipped. black, isort, flake8 and mypy are clean on the changed files. The comment-history gate passes against origin/main.

Manual verification

The root-cause probe above was run before and after the fix, against the real harness session_extras and a temporary KIRO_HOME. A live KAS session against a real checkout was not run. Unit coverage drives the real resolver, reader and projection end to end up to the wire payload.

Related Issues

Closes #18909

Pattern harvest

Not generalizable: the class (an untrusted checkout spec granting on a host Crew projects for) is already stopped for mirrored hosts by _project_mcp_trusted. KAS reaches a checkout spec on one new path only, the project-only name, and that path takes an allow list of non-granting keys.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 10, 2026 19:15
@iamwhatever
iamwhatever requested a review from CrysisDeu October 10, 2026 19:15
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 10, 2026
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 006491187a9c6546c8067c262071bb5caa99a510 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 006491187a9c6546c8067c262071bb5caa99a510 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check the wording: the title and new docs say "nearest-first", but a name declared at both levels resolves to the user-level spec, the opposite of kiro-cli's order.

What this change ships

Inventory (7 items) — 7 justified

Intent: let a KAS session run an agent that only the checkout's .kiro/agents/ declares, as kiro-cli already can, without giving the checkout any power to launch, approve or load anything. This is a FIX (#18909).

  1. On KAS, an agent that only the checkout declares now starts instead of failing at session start. Its name, description, prompt, tools, excludedTools and model are honoured. — justified
  2. That agent's servers, approvals, hooks, resources and include flags are dropped, and the dropped keys are logged. — justified
  3. That agent's file:// prompt is read from the checkout's agents directory, and a rooted path is refused. — justified
  4. If that agent's spec exists but cannot be read, the session is refused with an error naming the checkout. — justified
  5. When the checkout's spec has the same name as a user-level agent, the user-level agent runs exactly as on main, even if the checkout's spec is unreadable. — justified
  6. The Tool Search on/off decision reads the same spec the session is sent. — justified
  7. Docs and comments that said KAS refuses project-only agents now describe the new behaviour. — justified

[FIRST-PRINCIPLES-REVIEWED] 0064911

Description read

[DESCRIPTION-READ] f58199c7ed1894329df76219281564b764328a6cee915a39d92dfaa37608c98c

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 006491187a9c6546c8067c262071bb5caa99a510 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Before merge, run one live KAS session with a project-only agent whose prompt is a relative file:// path. The description says this was never run.

[DESIGN-REVIEWED] 0064911

Description read

[DESCRIPTION-READ] f0e3528027772e6fee1c0aafbca17ecf006f5e737f3cf2cc2af3f2095133cccf

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 006491187a9c6546c8067c262071bb5caa99a510 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0064911

Verdict parsed from the review's SHA-scoped output markers for commit 006491187a9c6546c8067c262071bb5caa99a510.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 006491187a9c6546c8067c262071bb5caa99a510: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 006491187a9c6546c8067c262071bb5caa99a510 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0064911

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 006491187a9c6546c8067c262071bb5caa99a510: <one-sentence reason>

@iamwhatever

Copy link
Copy Markdown
Contributor Author

GPT 6.1 F1 on bcef80d (shadowed agent: the projection drops the user-level hooks the stale check reads). Fixed in 5f290f8. I checked this in the code: spec_hooks.hook_projection_stale reads _agent_spec(agent_id), which is the user level alone on KAS (spec_hooks.py:556). The projection had built pre_tool_hook_matchers from a spec with no hooks. resolve_projected_spec now carries the user-level spec's hooks when a checkout shadows the agent, and never the checkout's own. The new test test_a_shadowing_project_spec_keeps_the_user_level_hooks_the_stale_check_reads asserts that the two matcher sets are equal. Removing the carry fails that test.

PR Hygiene: the description has been rebuilt from the template.

@iamwhatever
iamwhatever force-pushed the feat/kas-project-agents branch from 5f290f8 to 9d116b4 Compare October 10, 2026 19:50
@iamwhatever

Copy link
Copy Markdown
Contributor Author

First Principles BLOCK on 5f290f8 (Item 2 is oversized: a shadowing checkout replaced the user agent's prompt and tools). Fixed in 9d116b4, using the lane's own subtraction. When the user level declares the name, resolve_projected_spec now returns _with_restrictions(user, _project_restrictions(project)). That is the mirrored hosts' rule for an untrusted checkout spec. PROJECT_SPEC_HONOURED_KEYS now applies to a project-only agent alone, and the explicit hooks carry-over branch (Item 5) is deleted, because the user-level spec already carries its own hooks. The agent_discovery.project_agent_files docstring keeps its original "may be projected at all is a governance question" wording. The description's "What changed", "Backwards compatibility" and "Tests" sections are updated; the Goal is unchanged. Tests now pin the shadow case to the user-level prompt, tools, servers and hooks. Reverting to the checkout spec fails both shadow tests.

Opus 5.5 on 5f290f8 failed on API rate limit exceeded for installation in its permissions step, before any review ran. That was infrastructure, not a finding, and this push re-runs it. Its earlier advisory on bcef80d (user-level hooks on a shadowed agent) is covered by the same change.

@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 Oct 10, 2026
@iamwhatever
iamwhatever force-pushed the feat/kas-project-agents branch from 9d116b4 to e4de293 Compare October 10, 2026 20:11
@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 Oct 10, 2026
@iamwhatever
iamwhatever force-pushed the feat/kas-project-agents branch from e4de293 to b973885 Compare October 10, 2026 20:28
@iamwhatever

Copy link
Copy Markdown
Contributor Author

First Principles BLOCK on e4de293. Both items were fixed in b973885, using the lane's subtractions:

  • Item 4 (unreadable checkout spec refused a shadowed name). The lane is right that the premise was wrong. agent_sdk/backends.py (overlay_project_scope) itself records that kiro-cli reports a malformed project spec as an error offering no such mode, and so runs the user-level agent. resolve_projected_spec now checks the user level first. A name the user level declares resolves to load_agent_spec(agents_dir, agent) exactly as on main, whatever the checkout holds. The raise remains only for a project-only name, where there is no other spec of that name to run. The new test test_an_unreadable_shadowing_spec_still_runs_the_user_agent pins the fallback.
  • Item 2 (switch-off keys on a shadowed name ride along). The _with_restrictions layering is deleted. A shadowed name is now unchanged from main, so the PR touches project-only names alone. test_a_shadowing_project_spec_changes_nothing_about_the_user_agent pins this, and the muted server is now asserted present.

Mutation check: reading the checkout before the user level fails all three shadow tests. The description's "What changed", "Backwards compatibility", "Tests" and "Pattern harvest" sections are updated. The Goal is unchanged.

@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 Oct 10, 2026
@iamwhatever
iamwhatever force-pushed the feat/kas-project-agents branch from b973885 to 274bfab Compare October 10, 2026 22:06
@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 Oct 10, 2026
@iamwhatever
iamwhatever force-pushed the feat/kas-project-agents branch from 274bfab to bad789f Compare October 11, 2026 00:02
@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 Oct 11, 2026
@iamwhatever
iamwhatever force-pushed the feat/kas-project-agents branch from bad789f to 906dca9 Compare October 11, 2026 00:59
@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 Oct 11, 2026
Joe Guo added 2 commits October 11, 2026 03:03
kiro-cli resolves --agent against <project>/.kiro/agents/ before the user
level; the KAS projection read paths.kiro_agents_dir() only, so an agent
declared only in the checkout was refused at session start.

KAS now resolves through acp.harness.kas.resolve_projected_spec: the
checkout's spec, matched by the mirrored hosts' resolver, wins for the
prompt and the visible tools (name, description, prompt, tools,
excludedTools, model). A checkout is untrusted input, so it grants
nothing: mcpServers is cut to switch-off keys over the user-level spec
of the same name, and allowedTools, permissions, hooks, includeMcpJson,
includePowers, resources and any other key are dropped. A file:// prompt
must stay inside the checkout's .kiro/agents. The tool-search handshake
judges the same resolved spec.

Servers stay user-level, so KAS stays in
ACP_BACKENDS_USER_LEVEL_AGENT_SPECS_ONLY and the broker-overlay lookup
stays unscoped.

Closes #18909
A name the user level declares resolves to the user-level spec exactly as
before, whatever the checkout holds, including an unreadable checkout
spec. Only a project-only name reads the checkout, through the
honoured-key allow list, so the servers and hooks a KAS session runs stay
user-level and the stale-batch check and the projection read the same
matchers. The project-only prompt check refuses any rooted path, which
on Windows includes /etc/x, and the checkout's agents dir comes from
paths.project_agents_dir.
@iamwhatever
iamwhatever force-pushed the feat/kas-project-agents branch from 906dca9 to 0064911 Compare October 11, 2026 03:04
@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 readiness: checking Automated validation is still running labels Oct 11, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Self-review (crew-pr-reviewer, read-only): RECOMMEND APPROVE

RECOMMEND APPROVE. The PR fixes KAS refusing an agent that only the checkout's .kiro/agents declares, and it fixes the root cause: KasHarness.session_extras and AcpRuntime._projected_spawn_spec both read only paths.kiro_agents_dir(), and now both go through one resolver, resolve_projected_spec (src/kiro_crew/acp/harness/kas.py:93). A name the user level declares still resolves exactly as on main, so there is no regression for existing agents. I read the full production diff and the new test/test_kas_project_agents.py. Base is main, every check is green, there is no open change request, and the Opus, GPT and Design lanes all passed on head 0064911 with no findings. I tried to get past the guard. A project-only spec keeps only name/description/prompt/tools/excludedTools/model, so mcpServers, hooks, allowedTools and resources cannot reach the wire. A rooted file:// prompt is refused through Path.anchor, which also catches /x and C:x on Windows. A prompt symlinked out of .kiro/agents is refused too, because resolve_prompt checks containment after resolve(), and _is_unsafe_prompt_path still applies. Before merge, answer the two unanswered PASS punchlines on the current head. First Principles is right that "nearest-first" is the wrong word: user level wins on a collision, the opposite of kiro-cli's order. Fix the title and the comments at kas.py:330, the runtime.py _handshake_client_capabilities docstring and the backends.py ACP_BACKENDS_USER_LEVEL_AGENT_SPECS_ONLY comment so a later edit does not "fix" the order in the unsafe direction. Design asks for one live KAS run with a relative file:// prompt. Reviewer note: the code owner should confirm that an honoured tools list (for example "*" or @server globs) on a project-only agent only shows tools and never auto-approves them. Also note that _projected_spawn_spec reads the runtime's _work_dir while the projection reads the session's work_dir; if they differ, it fails closed (Tool Search off), which is safe. — crew-pr-reviewer

@iamwhatever
iamwhatever enabled auto-merge (squash) October 11, 2026 05:16
@chenmingwei23
chenmingwei23 merged commit 355c74f into main Oct 11, 2026
102 of 103 checks passed
@chenmingwei23
chenmingwei23 deleted the feat/kas-project-agents branch October 11, 2026 05:45
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 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.

KAS refuses an agent declared only in the checkout's .kiro/agents

2 participants