Repository navigation
fix(kas): resolve a checkout's .kiro/agents spec nearest-first - #18911
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of 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 shipsInventory (7 items) — 7 justifiedIntent: let a KAS session run an agent that only the checkout's
[FIRST-PRINCIPLES-REVIEWED] 0064911 Description read[DESCRIPTION-READ] f58199c7ed1894329df76219281564b764328a6cee915a39d92dfaa37608c98c That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Before merge, run one live KAS session with a project-only agent whose prompt is a relative [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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
|
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: PR Hygiene: the description has been rebuilt from the template. |
5f290f8 to
9d116b4
Compare
|
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, Opus 5.5 on 5f290f8 failed on |
9d116b4 to
e4de293
Compare
e4de293 to
b973885
Compare
|
First Principles BLOCK on e4de293. Both items were fixed in b973885, using the lane's subtractions:
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. |
b973885 to
274bfab
Compare
274bfab to
bad789f
Compare
bad789f to
906dca9
Compare
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.
906dca9 to
0064911
Compare
|
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 |
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
--agentagainst<project>/.kiro/agents/before the user level. KAS gets its agent from Crew over_meta.kiro.customAgents, and that projection readpaths.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: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
session_mcp._project_mcp_trustedstaysFalse).What changed (motivation → approach → change)
Symptom → root cause → change:
KasHarness.session_extrasandAcpRuntime._projected_spawn_specboth read the user-level directory alone.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):agent_discovery.project_agent_files(kiro-cli dispatch list)['probe-only.json']acp.session_mcp._project_spec_path_for(mirrored hosts)KasHarness.session_extrasAfter 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:
session_mcp.project_agent_spec, declared name beats the filename).A checkout spec is untrusted input, so a project-only agent gets an allow list:
name,description,prompt,tools,excludedTools,modelmcpServers,allowedTools,permissions,hooks,includeMcpJson,includePowers,resources, any other keyfile://prompt.kiro/agents(paths.project_agents_dir); a rooted path (absolute,~, or/xon Windows) is refused, and..escapes are refused as beforeSo 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
toolslist reveals still resolves toask.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_scopestill answers{}for KAS. The unscoped stub lookup inharness/kas.pyis unchanged in behaviour (only its comment changed). The pinnedtest_kas_agents.pyscope 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_specis unchanged and is still the user-level read.Tests
test/test_kas_project_agents.py(new, 11 tests):file://anchored to the checkout), tools, excludedTools and description.~and..project prompt paths are refused.Mutation checks:
test_acp_tool_search_wire.py::TestProjectedSpawnSpecReadnow patcheskas_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_extrasand a temporaryKIRO_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
Contribution License Agreement
Contributed under the project's Apache-2.0 license.