Skip to content

fix(apps): run an app's own agent past a same-named checkout spec - #22915

Merged
bolichen97 merged 1 commit into
mainfrom
fix/app-agent-guard-retire-19323
Oct 22, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/app-agent-guard-retire-19323

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A palette-opened app agent runs its app's registered spec on KAS and Kiro even when the checkout has an agent of the same name, instead of being refused.

Today a turn on a session a palette command opened for its app's own agent is refused when the checkout (or a fallback folder) holds a spec of the agent's bare name. That per-turn guard existed because the bare name used to decide which spec ran. On kiro-cli the turn now launches a Crew-written copy from an empty folder, and KAS resolves a user-level name before any checkout spec. So the guard refuses turns that would run the right spec. On KAS, the skill scope and injected prompt still read the agent by name, checkout first.

Why it matters

A user who opens an app command in a repository with its own deploy agent cannot run the app's deploy agent at all. The maintainer ruling on #19323 kept the guard only until the launch copy was proven. That copy has merged, with the test that a checkout spec written between the check and the spawn is not the one launched.

Not a goal

What changed (motivation → approach → change)

Turn on an app's own agent Before After
Checkout has a spec of the bare name refused runs the app's registered spec
Registered spec missing, unverifiable, or a second user-level spec declares the name refused refused (same message)
Agent uses a reserved name refused refused
KAS spec, skill scope and injected prompt read by name, checkout first read from the registered file; refused if it is gone

The refusal only asked which spec the bare name resolves to, and neither allowed backend uses that answer any more. So app_command_agent_refusal keeps only the checks no checkout can fix: a reserved name, and the app's registered file being installed and the only user-level spec with that name. It takes no folders. The checkout scan, its fallback folder list and the helpers only that scan used are removed.

So that no checkout spec sets anything on KAS, an admitted app-owned turn binds its session to the app's agent before the claim (apps/agent_launch.py). Any other turn of that key removes the binding first, so a recreated or switched slot runs its own agent. The KAS projection of a bound session then reads the registered file by its path (acp/harness/kas.py). If that file is gone by then (the app was switched off after the check), the session is refused instead of falling back to the checkout's spec. The turn also pins its session's skill scope and injected prompt to that file on both backends (skill_scope_pin.py). Before, only kiro-cli turns did. The specs in app-kit-platform.md and acp-client.md describe the reduced check.

Backwards compatibility

Compatible: every turn that ran before still runs, with the same spec. A turn that a checkout's same-named spec refused now runs the app's own registered spec.

Reader: src/kiro_crew/dashboard/chat_turn/turn_admission.py:_check_owner -- chat -- the only caller of app_command_agent_refusal, updated to the two-argument form; test_app_command_agent_guard.py
Reader: src/kiro_crew/agent_sdk/init.py:project_claims_agent_name -- chat -- its only non-test caller was the removed checkout scan (grep of origin/main across src/, website/ and app bundles); removed with it
Reader: src/kiro_crew/acp/managed_agent_shadow.py:project_claims_agent_name -- chat -- only called through the SDK wrapper above; the reserved-name gate keeps its own scan (_project_agent_claim_refusal); test_managed_agent_shadow.py
Reader: src/kiro_crew/dashboard/chat_turn/app_agent_binding.py:_app_agent_start_dirs -- chat -- only the removed scan read it; test_chat_runner_base_surface.py pins the module surface
Reader: src/kiro_crew/apps/manager_lookup.py:_same_dir_key -- chat -- only the removed home-folder exemption read it; test_manager_facade.py pins the facade
Reader: src/kiro_crew/dashboard/slot_persistence/metadata_codec.py:_read_app_agent_owner -- chat -- unchanged; persisted app_agent_owner stays <app>/<agent>; test_slot_metadata_codec.py

Tests

  • test_a_checkout_spec_of_the_bare_name_neither_refuses_nor_scopes_the_turn[kiro|kas]: a checkout spec of the bare name, with its own grants and skills, sits in the session's project before the turn. The turn runs, the session is pinned to the registered file, and skill_search, dollar skills and the injected directory see only the app's skills. Red on origin/main (both cases are refused there), green here.
  • test_a_bound_session_whose_registered_file_is_gone_is_refused: the app's file is removed after the check, with a same-named checkout spec present. The KAS session is refused, and an unbound session still resolves the name. test_a_bound_session_projects_the_registered_file and test_a_binding_applies_only_to_the_agent_it_names pin the bound and other-agent cases. test_an_admitted_turn_binds_its_session_before_the_claim pins that an admitted turn binds before allocation and a refused one does not. test_a_turn_not_bound_to_the_app_drops_the_keys_binding pins that a turn not bound to the app drops its key's binding and leaves other keys alone.
  • test_a_checkout_spec_of_a_launch_name_does_not_refuse_the_turn: now runs the real check with the session in that checkout, instead of patching it.
  • test_the_registered_unique_agent_is_allowed, plus the existing user-level, reserved-name and unregistered tests, call the two-argument check.
  • Removed: the checkout and fallback-folder scan tests, the home-folder exemption tests and the start-folder test, which test the removed scan.

Targeted runs: the app-agent and KAS test files plus related files (-n 2, 1993 passed). isort, flake8, mypy and semgrep (diff-scoped) are clean.

Manual verification

N/A - unit coverage sufficient: the turn harness runs the real admission path with a real checkout on disk, on both backends.

Related Issues

Refs #19323

Pattern harvest

Not generalizable: a guard retired after the mechanism it stood in for (the launch copy) merged with its proof test, as the ruling on #19323 planned.

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

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

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision c081dc6b43c280d46f86a67db494551db002c6a4 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 Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of c081dc6b43c280d46f86a67db494551db002c6a4 — 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. The guard's removal has a red-on-base test as provenance. The new KAS binding is a second session-keyed map that points at the same registered file the skill pin already holds.

Notes

  • Item 4 — second spelling of skill_scope_pin._PINNED: _KAS_BINDINGS: dict[str, tuple[str, str]] and _PINNED: dict[str, Path] map the same session key to the same registered_spec_path(owner_app, owner_agent), and each has its own lock, bind and unbind. Only the publish timing differs: the binding is set before the claim, the pin after the lease. Subtraction: delete _KAS_BINDINGS, bind_session_app_agent and unbind_session_app_agent, and have read_bound_app_spec read the one session-keyed path. Clears when: one map serves both readers, or the description says why the two publish times cannot share one map.

What this change ships

Inventory (6 items) — 5 justified

Intent: let a palette-opened app agent run its own registered spec when the checkout has a same-named agent. This is a FIX.

  1. An app-agent turn in a checkout that has a same-named spec now runs the app's spec instead of being refused (Kiro and KAS) — justified
  2. The "this session's folder has its own agent" fallback-folder refusal is gone — justified
  3. The home-folder exemption and the refusal on an unverifiable checkout scan are gone — justified
  4. A KAS session for an app-owned turn reads the registered file by path, and is refused if the file is gone — duplicate of src/kiro_crew/skill_scope_pin.py:_PINNED
  5. Skill scope and the injected prompt are now pinned to the registered file on KAS too, not only on kiro-cli — justified
  6. The public SDK export project_claims_agent_name is removed (0 remaining references, grepped) — justified

[FIRST-PRINCIPLES-REVIEWED] c081dc6

Description read

[DESCRIPTION-READ] 67fb73fe08a0e88155ef69409fc075e9226fa19a50ff8ecfba13b1f282c6cf4a

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the checkout scan is removed together with the bare-name resolution it guarded, and on KAS the turn's session is bound to the app's registered file before the session is claimed.

Notes

  • _KAS_BINDINGS is a process-local dict. It is only cleared by a later turn of the same key, so entries for deleted slots stay until the process exits. That is harmless today, but it is a second record of which agent owns a session, separate from the slot's app_agent_owner, and the two could drift if a future path claims a session without going through _turn_admit.
  • On KAS, require_fork_governance(agent, work_dir) still runs by name before the bound spec is read. The description doesn't say whether a checkout spec of the same name can still change that check's answer for a bound session.

[DESIGN-REVIEWED] c081dc6

Description read

[DESCRIPTION-READ] 840b9fb923ad0a91fd11aeabc6e35867b496d4ca8ddfef750f7283e8de825ab0

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] c081dc6

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

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

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c081dc6

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

@bolichen97
bolichen97 enabled auto-merge (squash) October 21, 2026 22:05
@bolichen97
bolichen97 force-pushed the fix/app-agent-guard-retire-19323 branch from e984e17 to 3fe2a1a Compare October 21, 2026 22:14
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

  • PASS punchline: the per-turn checkout scan was stale

Agreed, no change. Both allowed backends already run the registered user-level spec: kiro-cli runs the launch copy from an empty folder, and KAS's resolve_projected_spec checks the user level first.
The scan is gone. The registration and reserved-name checks stay, along with the KAS skill/prompt pin, so no checkout spec can set what the session reads.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

  • PASS punchline: each item removes the named refusal or code only it used

Agreed, no change. The only removals are the checkout scan and the helpers only it read: project_claims_agent_name (SDK wrapper and ACP function), _app_agent_start_dirs, _same_dir_key, and the _owner_project turn local. The Reader: lines in the body list each one.
The KAS premise stands. acp/harness/kas.py sends the user-level spec before it looks at a checkout, and test_kas_is_handed_the_namespaced_spec_over_a_same_named_project_spec pins that.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 21, 2026
@bolichen97
bolichen97 force-pushed the fix/app-agent-guard-retire-19323 branch from 3fe2a1a to 887e278 Compare October 21, 2026 23:52
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Rebased: main moved in docs/system-specs/modules/acp-client.md and app-kit-platform.md since this head went green (4533b1e -> dde25d8); CI re-running. The diff is unchanged (range-diff =).

@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: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 21, 2026
@bolichen97
bolichen97 force-pushed the fix/app-agent-guard-retire-19323 branch from 887e278 to 3fbddba Compare October 22, 2026 00:54
@bolichen97

bolichen97 commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]
self-added: yes
mechanism: removing the checkout scan left KAS resolving the bare name at session start

  • Keep KAS projection bound to the admitted app spec span=4803882cd425

fixed in 3fbddba: an admitted turn binds its session to (app, agent) before the claim (apps/agent_launch.py bind_session_app_agent); the KAS projection of a bound session reads the registered <app>--<agent>.json by its path (acp/harness/kas.py), and a missing or unverifiable file raises AcpAgentUnavailable instead of falling back to the checkout.
any other turn of the key drops the binding first (unbind_session_app_agent), so a recreated or switched slot projects its own agent.
tests: test_a_bound_session_whose_registered_file_is_gone_is_refused (red without the bound branch), test_an_admitted_turn_binds_its_session_before_the_claim, test_a_turn_not_bound_to_the_app_drops_the_keys_binding.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Two reds on the previous head 887e278 are main's, not this PR's:

  • Backend Tests (Windows) (7): test/test_backend_cards_advertised.py::test_no_new_runtime_site_gates_a_field_backed_line_on_a_set (card ratchet on acp/client_mcp_array.py). The same node id is red on main in run 39693382736 (0144ea1). It is tracked in #22968 and #22970. This PR does not touch that file.
  • Real Adapter Contract Tests: test/test_pi_real_adapter.py raises SandboxUnavailableError. It is red on main in run 39697564876 (ba53277). The fix is in #22951.

The GPT security finding (span=4803882cd425) was fixed in code at 3fbddba, not overridden.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

  • PASS punchline: a second session-keyed map points at the same file as an existing one

Kept as two maps, because the two maps are set at different times for different readers. The skill-scope pin (skill_scope_pin) is set only AFTER the turn holds the session lease, so a sibling turn waiting for the lease cannot change the scope of the running turn.
The KAS binding (agent_launch._KAS_BINDINGS) must exist BEFORE the claim, because the session it governs is created during the claim. One map cannot serve both moments without reopening one of the two races.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

Agreed, no change. The removed symbols have no remaining reader (Reader: lines in the body).
A bound KAS session that finds the registered file gone is refused (AcpAgentUnavailable), never projected from the checkout.

@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 22, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Head 3fbddba: all four reds come from main, none from this PR.

  • Backend Tests (3.12, 7) and Backend Tests (Windows) (7) fail the same node, test/test_backend_cards_advertised.py::test_no_new_runtime_site_gates_a_field_backed_line_on_a_set (card ratchet on acp/client_mcp_array.py). That node is red on main in run 39693382736. It is still open in #22968 / #22970.
  • Coverage Gate only fails because backend-test=failure makes it fail closed. Its log shows ##[error]backend-test=failure -- failing closed.
  • Real Adapter Contract Tests (test_pi_real_adapter.py, SandboxUnavailableError) is also red on main in run 39704958002. Its fix #22951 merged at 398772f, after this head's base.

Plan: no push for these reds. Once the card ratchet fix is on main, I rebase onto it, which also brings in #22951, and re-run CI.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Rebased onto main 3d6cda4, which carries the red-main fix #22951 (card ratchet #22968 + real-adapter lane). The diff is unchanged (range-diff =) and CI is re-running on c081dc6.

@bolichen97
bolichen97 force-pushed the fix/app-agent-guard-retire-19323 branch from 3fbddba to c081dc6 Compare October 22, 2026 02:10
@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 22, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

  • PASS punchline: a second session-keyed map points at the same file as an existing one

Kept as two maps, because the two maps are set at different times for different readers. The skill-scope pin (skill_scope_pin) is set only AFTER the turn holds the session lease, so a sibling turn waiting for the lease cannot change the scope of the running turn.
The KAS binding (agent_launch._KAS_BINDINGS) must exist BEFORE the claim, because the session it governs is created during the claim. One map cannot serve both moments without reopening one of the two races.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

Agreed, no change. The removed symbols have no remaining reader (Reader: lines in the body).
A bound KAS session that finds the registered file gone is refused (AcpAgentUnavailable), never projected from the checkout.

@bolichen97
bolichen97 merged commit 88d73a8 into main Oct 22, 2026
106 checks passed
@bolichen97
bolichen97 deleted the fix/app-agent-guard-retire-19323 branch October 22, 2026 05:41
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 22, 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.

2 participants