Skip to content

feat(apps): list a third-party app's agentTools on an opt-in prompted kirocrew-apps server - #17015

Open
unstablebrainiac wants to merge 1 commit into
kirodotdev:mainfrom
unstablebrainiac:feat/app-agent-routes
Open

unstablebrainiac wants to merge 1 commit into
kirodotdev:mainfrom
unstablebrainiac:feat/app-agent-routes

Conversation

@unstablebrainiac

@unstablebrainiac unstablebrainiac commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let a third-party app's manifest agentTools reach agents, with the user approving each call.

The agentTools seam (#32660, #33542) lets an app declare MCP tools in app.json and serve them from its own route. Its tools are listed under kirocrew-core, and the default agent's allowedTools grants @kirocrew-core as a whole server, so every call there skips the permission prompt. That approval is right for first-party code and wrong for third-party code, so app_agent_tools.py reads first-party blocks only, and a registry app's block validates, installs and lists nothing. Section 30.1 of app-kit-platform.md names what was missing: "a path that asks before each call (a server of its own outside allowedTools, or a per-tool approval); that is a maintainer's decision, not this seam's."

This PR implements the first of those two options as an opt-in server, so no default agent changes and an agent reaches third-party app code only when its owner grants it.

Why it matters

Until now, a registry app that wants agents to drive it has to ship and run an MCP server of its own. The core already does all of that work for a first-party app's declaration: it validates the schema, forwards the call through the signed proxy, and redacts and caps the answer. This PR lets a third-party app use the same code, without giving it core's auto-approval.

Not a goal

  • Mounting third-party app tools on default agents. kirocrew-apps is opt-in; whether any agent should carry it by default is a separate decision.
  • strictSession for third-party apps. A third-party block that declares it lists nothing. Supporting a declaration that depends on a specific calling session still needs a separate ruling.
  • A per-tool approval inside kirocrew-core, which is the other option section 30.1 names.
  • Showing an app's declared tools on the install screen.

What changed (motivation → approach → change)

Piece What it does
kirocrew-apps server (mcp_apps.py) A new opt_in managed server, like kirocrew-secrets: no default or derived spec carries it, an agent has it only when its spec is granted @kirocrew-apps, and a worker that agent spawns does not inherit it. It has no autoApprove and no allowedTools entry, so kiro-cli asks before every call and the PreToolUse gate sees each one; kirocrew doctor never adds it to allowedTools. It lists the installed third-party apps' tools, minus a readably disabled app's, and each description starts with Served by the installed app '<name>', not by Kiro Crew.
app_agent_tools.third_party_tools Reads an installed app that is not first party, not adopted under pin trust, and not named by a shipped manifest, from its data-home app.json. It takes no block that states a namespace other than the app's own, and no block with a strictSession tool. A name any first-party app declares stays that app's, and a name two third-party apps declare is neither's.
POST /api/app-tools/prompted-call A strict internal route next to /api/app-tools/call, served by the same decision in dashboard/handlers/app_agent_tools.py. Each route resolves only its own set, so kirocrew-core cannot reach a third-party tool and kirocrew-apps cannot reach a first-party one. The audit row names the server that posted.
Cross-app refusal The call carries the strict calling-session key (mcp_apps.py is a reflexive module in mcp_core_parts/identity.py), so token_auth names the app that owns that exact session (request["app"]). The prompted route refuses (403 cross_app) a call from a session another app owns, on both dispatch paths.
Answers Redacted and capped by shape_answer in mcp_tools/app_tools.py, the code kirocrew-core already ran. A result: "text" answer's verbatim-credential shape stays first-party only; a third-party answer in that shape is redacted whole.
Scoped app agents An app agent whose manifest declares permissions.mcpTools has kirocrew-apps withheld whole (apps.permissions._OPEN_ENDED_MANAGED_SERVERS), because its tool names depend on what is installed at call time.
No auto-approval by pattern platform/governance.py adds PROMPT_ONLY_MCP_SERVERS, and may_skip_gate never skips the gate for a literal @kirocrew-apps ref. KAS withholds covering wildcard grants in its projection. Kiro CLI serves prompted calls only for a session whose launch-time record proves it started on a Crew-minted native skill view or app launch copy; an authored launch or missing strict session identity gets 403 approval_grants_undetermined, without re-reading a mutable spec. The launch fact is recorded in src/kiro_crew/acp and reaches the route through src/kiro_crew/providers as agent_sdk/prompted_calls.py PromptedCallLaunch. Native skill views withhold covering patterns when the server is mounted by the spec or by the global or workspace .kiro/settings/mcp.json, using the same native settings reader as session startup (agent_sdk/mcp_json_reach.py) and failing closed when a file is unreadable. An app launch copy serves every workspace, so its writer also withholds those patterns whenever tools: "*" could inherit a workspace entry it cannot inspect. Generic writers under src/kiro_crew/agent_materialization and src/kiro_crew/apps leave wildcard patterns alone.
Registrations _MANAGED_MCP_SERVERS in agent.py, mcp_discovery_managed.py, OPT_IN_BIN_MCP_SERVERS in mcp_cleanup.py, SLIM_SERVERS in mcp_entry.py, mcp_gateway/stub_register.py, MANAGED_STUB_FOLLOWERS, config/integration_sections.py, and cli.py (kirocrew mcp-apps).

This PR first carried the agentRoutes and app_request design from RFC #19676. The agentTools seam on main now covers first-party apps, and this PR extends it to third-party apps, so that design is dropped. The RFC and its index row now say that no implementation of it is open. The force-push replaces the whole diff.

Backwards compatibility

  • First-party tools are unchanged: same server, same route, same refusals.
  • No written agent spec changes: the server is opt-in, so no default, derived or existing spec gains it.

Removes nothing: no route, key, field or function main has is deleted or renamed.

Tests

  • test/test_app_agent_tools_third_party.py covers:
    • the reader: what lists, and what lists nothing (a first-party app, a record under a shipped name, a foreign namespace, a strictSession tool, a first-party or shipped name, a name two third-party apps declare);
    • the server: the listed description, the enablement gate, validation, the post with the strict identity, redact-then-cap, and a credential-shaped answer redacted whole;
    • the gateway: the prompted route serves a third-party tool; neither route reaches the other's tools; it refuses without the internal secret, for a disabled app, for arguments beyond the declaration, for a session another app owns, for an authored Kiro CLI launch, and when strict identity is unavailable; it serves the declaring app's own session, skill-view and app-launch-copy sessions, and a backend that does not read spec grants;
    • the grant: the server is opt-in, in no default spec and never auto-approved, and a scoped app agent has it withheld whole.
  • test/test_prompt_only_mcp_settings.py pins the inherited-entry check: a JSONC global file, a workspace-only entry, an enabled global entry alongside a disabled workspace entry, no workspace read without a work_dir, and an unreadable file that fails closed while an absent one declares nothing.
  • test/test_cli_mcp_doctor.py pins that doctor never adds a granted @kirocrew-apps to allowedTools; test/test_worker_agent.py that a worker does not inherit it.
  • Mutation checks confirmed the tests catch each guard: dropping opt_in, the strictSession refusal, the prompted route's own lookup, the cross-app refusal, the scoped-agent withhold, the credential redaction, the authored-launch refusal, the app-launch-copy serve branch, and the strict session-key requirement each failed its test.
  • The MCP route table in test/fixtures/dashboard_mcp_route_table.txt and the boot sequences in test/test_dashboard_server_composition_contract_reach.py gain the new route. The refactor shape pin gains the new registry row.
  • The focused suite covering every changed function and the required repair files ran: 4,296 passed and 1 skipped. The only failure, test_the_dashboard_boot_keeps_its_chain_hooks_and_order, depends on the development host's app-window discovery and fails the same way on the previous head.

Manual verification

python -m kiro_crew.mcp_apps was driven over stdio against a scratch KIROCREW_HOME that held one third-party app declaring demo_app_ping. initialize returned kirocrew-apps with the caller-identity capability. tools/list returned demo_app_ping with the description Served by the installed app 'demo-app', not by Kiro Crew.\n\nPing. A live gateway call through the signed proxy was not run. It goes through the same _decide path as /api/app-tools/call, which test_app_agent_tools.py exercises through the real proxy.

Related Issues

Part of #16910

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

@unstablebrainiac
unstablebrainiac requested a review from a team as a code owner October 5, 2026 11:29
@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 Oct 5, 2026
@github-actions

github-actions Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 105869466d5f38b56091cb5f560e3d969aae902b via the fork AI-review pipeline — 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 accepted base RFC rfc-app-agent-tools-third-party-grant.md names this PR's server, opt-in rule, PROMPT_ONLY_MCP_SERVERS, cross_app and withhold-whole rule. One mechanism goes beyond it and is oversized.

Notes

  • Item 8 — oversized: RFC §5 asks only that "may_skip_gate never skips the gate for a ref that names it". This PR also tracks each session's launch across 11 files (_prompted_call_launches, _prompted_call_launch_name, PromptedCallLaunch, prompted_call_launch() on three provider classes). It also adds a settings reader for wildcards. All of it defends against a */@kirocrew-* grant the operator wrote, in a spec they already opted into. Subtraction: drop the launch record and approval_grants_undetermined, and keep withhold_prompt_only_wildcards in the projection writers. Clears when: the mechanism is removed, or a human amends the Goal.
  • Item 8 — duplicate (2 writers counted): two places write _prompted_call_launches with their own launched_on_crew_copy expression: runtime_wire._record_prompted_call_launch and the inline block in runtime_mode_activation._activate_mode_bracketed. Subtraction: keep one writer.

What this change ships

Inventory (10 items) — 8 justified

Intent: let a third-party app's manifest agentTools reach agents, with every call prompted — ADDITION.

  1. New opt-in kirocrew-apps server lists third-party apps' declared tools — justified
  2. Each listed tool's description starts by naming the app that serves it — justified
  3. Third-party reader rejects a foreign namespace, strictSession, and names first-party apps hold or two apps share — justified
  4. New strict internal route POST /api/app-tools/prompted-call; each route resolves only its own set — justified
  5. A call from a session another app owns is refused (cross_app) — justified
  6. A third-party text answer's credential passthrough is redacted whole — justified
  7. Scoped app agents have kirocrew-apps withheld whole — justified
  8. Kiro CLI calls refused unless the session launched on a Crew copy; wildcard approvals stripped from views and launch copies — oversized: not in RFC §5, two writers
  9. A new audit/log line names the grants withheld for a prompt-only server — undeclared
  10. RFC rfc-app-agent-routes index row and implementation-prs mark feat(apps): list a third-party app's agentTools on an opt-in prompted kirocrew-apps server #17015 as repurposed — justified

[FIRST-PRINCIPLES-REVIEWED] 1058694

Description read

[DESCRIPTION-READ] c4b04946a148442365220c320da086cb74d15066718c880f84a09bfcc213a2cf

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 105869466d5f38b56091cb5f560e3d969aae902b via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design blocker: third-party tools go on their own opt-in server that never auto-approves, and the route-level refusals fail closed.

Notes

  • On Kiro CLI, every prompted call gets 403 approval_grants_undetermined when agent.native_skill_projection is off or the skill view couldn't be prepared. A user who granted @kirocrew-apps then sees calls refused with no setting that names the cause. Point the refusal text or kirocrew doctor at the exact switch to flip.
  • Three separate writers now strip wildcards (the KAS projection, native skill views and app launch copies), plus a per-session launch record. A future writer that misses that strip quietly brings back auto-approval. Pin each launch path to one test that asserts the server is "mounted ⇒ no covering grant", rather than one test per writer.

[DESIGN-REVIEWED] 1058694

Description read

[DESCRIPTION-READ] 933e7ccc6b6383c6ab0306c2812013e5658e9684b4eca5f7beaa232045e5503a

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 105869466d5f38b56091cb5f560e3d969aae902b via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 1058694

@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 5, 2026
@github-actions

github-actions Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — 🔴 changes requested (blocking)

Reviewed 105869466d5f38b56091cb5f560e3d969aae902b via the fork AI-review pipeline; updated in place on each push.

Adjudication upheld 2 of 2 blocking finding(s); those must be resolved before merging.

BLOCKING -- src/kiro_crew/dashboard/handlers/app_agent_tools.py:140 -- Codex sessions cannot execute prompted app tools

if launch is None:
Trigger: A Codex session explicitly granted @kirocrew-apps calls an installed app’s tool. AcpProvider wraps an AcpSessionProvider, but Codex’s session creation/loading skips agent-mode activation. Both new runtime launch-record writers require set_mode, so prompted_call_launch() returns None.
Outcome: Every such call receives 403 approval_grants_undetermined, before reaching the exemption for non-spec-file backends; the approved app operation never runs.
Anchor: defect
Fix: Record a backend-tagged launch fact during successful Codex session creation/loading without requiring agent-mode activation.

BLOCKING -- src/kiro_crew/dashboard/handlers/app_agent_tools.py:127 -- Launch lookup excludes explicitly granted shared subagents

provider = state.sessions.get_provider(key)
Trigger: With session sharing enabled and no model/effort overrides, spawn_run(agent=<template>) selects a template explicitly granted @kirocrew-apps. _create_shared_session_impl activates its projected view, but _bind_shared_handle_impl stores the provider only on the subagent record. The tool posts that child’s strict key, which SessionManager.get_provider() cannot resolve.
Outcome: An approved call from the correctly projected child receives 403 approval_grants_undetermined and never reaches the app.
Anchor: defect
Fix: Also resolve the exact live provider from the shared-subagent registry, preserving fail-closed behavior and never substituting the parent’s provider.

[BLOCK-MERGE] 1058694
[GPT-REVIEWED] 1058694

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 — MEDIUM. A Codex session explicitly granted @kirocrew-apps gets a 403 on every third-party app tool call, every time; it never recovers on retry, though it fails closed and visibly. The 403 comes from app_agent_tools.py:1170-1177 in the patch, and the only launch-record writers are set_mode (runtime_wire.py / runtime_mode_activation.py in the patch). The real fix is small: record a launch fact when a Codex session is created or loaded. That cost does not exceed the harm of a feature that is permanently broken on that path.

F2 — MEDIUM. The shared subagent's provider is stored only on info._shared_provider (src/kiro_crew/subagent_manager/run_start.py:573). SessionManager.get_provider (src/kiro_crew/session_parts/claims.py:120) only asks the allocation boundary, so the child's strict key resolves to nothing and every call gets 403 approval_grants_undetermined. That happens on every call and does not self-correct. The fix is one more registry lookup that still fails closed, which is cheap compared with the harm.

[ADJUDICATION] 105869466d5f38b56091cb5f560e3d969aae902b total=2 uphold=2 downgrade=0
UPHOLD F1 src/kiro_crew/dashboard/handlers/app_agent_tools.py:140 reason=harm-warrants-remedy
UPHOLD F2 src/kiro_crew/dashboard/handlers/app_agent_tools.py:127 reason=harm-warrants-remedy
[GPT-ADJUDICATED] 105869466d5f38b56091cb5f560e3d969aae902b

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 5, 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 Oct 5, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 5, 2026
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 5, 2026
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Replying to r112 at 5de324b. The current head is 8982c31: a rebase onto main plus the two code changes below.

Item 4, GET with body={}. Fixed here. _validate_app_request now treats an empty object as no body, so a GET may pass {}. A non-empty body on GET is still refused. test_app_request_schema_accepts_get_with_an_empty_body fails without the change.

First Principles item 7, three verb lists. Fixed here. APP_REQUEST_METHODS in validation_parts/app_schemas.py is the one definition. AGENT_ROUTE_METHODS in apps/manifest.py is bound to it, and the app_request tool schema's enum is sorted(APP_REQUEST_METHODS). The definition lives on the validation side because cron imports validation and manifest imports cron, so the other direction would be a cycle.

Item 5, re-implementing app_enabled_state. Kept. app_enabled_state opens installed.json without the protected-path screen, so a symlinked installed.json pointing at a credential file would be opened. An earlier GPT finding on this PR required that the tool-listing scan never open such a file, so it reads through _owner_json. Switching back would reintroduce that finding.

Item 6, the builtin snapshot copy of agentRoutes. Kept. main's field-parity test in test/test_app_bridges_agent_configs.py requires _manifest_to_builtin_dict to carry every manifest field. Deleting the block fails that test. Route admission does not read the copy, as its comment says.

Item 1, no in-repo consumer. Unchanged. The first consumer is the external Slack subscription app named in the description, which is not public yet. Whether that is enough is part of the #16910 / RFC #19676 decision.

Design punchline, kirocrew_agent_session is only a claim on TCP. Correct. app_request uses the gateway's unix socket first and TCP only as fallback. On either transport the internal secret is the credential and the session key is the caller's claim, the same trust every other internal-secret kirocrew-core tool has. Binding the session on TCP is a transport change outside this PR.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at a721b4c.

The r112 GET item is fixed: _validate_app_request treats body={} as no body and still refuses a non-empty GET body (app_schemas.py L188-L194). The verb lists now share one definition. All checks on this head are green, and the Opus, GPT and Design lanes have no findings. I found no concrete defect in the admission path.

What still blocks approval:

  1. Reserved for human review. token_auth.py L395-L430 adds an internal-secret admission arm on app catch-all routes, and route_registry.py L438 hands the caller's session key to app handlers.
  2. Product decision: Let installed apps declare agent-callable routes with verified caller session #16910 is still tier:T4 and needs-human, not triaged, and RFC docs(rfc): installed apps declare agent-callable routes #19676 is unmerged.
  3. The First Principles CONCERNS items 3 and 1 on this head were answered at 8982c31, before the push to a721b4c. Re-posting those dispositions for a721b4c would keep the record tied to the head under review.

To clear: a maintainer accepts the design and a human does the security review. Our earlier CHANGES_REQUESTED stays until then. No PR code was run locally.

— crew-pr-reviewer (r113)

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

On r113 item 3: a721b4c is a rebase of 8982c31 onto main with no patch change (range-diff identical), so the First Principles dispositions in #17015 (comment) apply to a721b4c as written.

  • Item 1 (listing gate re-implements app_enabled_state): kept. app_enabled_state follows a symlinked installed.json and opens its target; the gate reads through _owner_json so a protected file is never opened.
  • Item 3 (agentRoutes has no in-tree consumer): correct. The first consumer is the Secretary app tracked in Let installed apps declare agent-callable routes with verified caller session #16910; the builtin path exists only to refuse routes added to an edited saved manifest.

Items 1 and 2 of the hold stay with a maintainer.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at a721b4c.

The author has re-stated the First Principles dispositions for this head, so nothing is left for the author. CI is green, and I found no concrete defect in the admission path.

Two items need people, not code:

  1. Human security review. token_auth.py L395-L430 adds an internal-secret admission arm on app catch-all routes, and route_registry.py L438 hands the caller's claimed session key to app handlers. The user's rules reserve admission changes for a human.
  2. Product decision. Let installed apps declare agent-callable routes with verified caller session #16910 is still tier:T4 and needs-human, and RFC docs(rfc): installed apps declare agent-callable routes #19676 is unmerged. A maintainer accepting the design clears this.

Our earlier request for changes stays until both clear.

— crew-pr-reviewer (r116)

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at dedaa69.

This head is a rebase of a721b4c with one small hardening. The app_request advertisement scan reads enablement through the screened _owner_json reader and keeps the tool listed when that record cannot be parsed. Two tests cover it. We found no defect in that change. Every lane passes and CI is green.

Two items need people, not code:

  1. Human security review. token_auth.py#L395-L430 adds an internal-secret admission arm on app catch-all routes. route_registry.py#L438 hands the caller's claimed session key to app handlers. Admission changes are reserved for a human.
  2. Product decision. Let installed apps declare agent-callable routes with verified caller session #16910 is still tier:T4 and needs-human, and RFC docs(rfc): installed apps declare agent-callable routes #19676 is unmerged. A maintainer accepting the design clears this.

Our earlier request for changes stays until both clear.

— crew-pr-reviewer (r119)

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

Blocking security finding: an agent app request carries X-Internal-Secret into the same web.Request given to the installed app handler. App code can read and replay that core bearer secret against privileged internal routes.

Required fix: strip core credentials before app dispatch. Keep only scoped session metadata. Add tests proving handlers cannot read or replay the secret.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

@bolichen97 Fixed in 22ff443. On an agent-route call, RouteRegistry.dispatch now hands the app handler a clone of the request with X-Internal-Secret, X-Session-Token, X-Internal-Caller, Authorization and Cookie removed. The clone keeps the request state and the route match, so the handler still gets the calling session as request["kirocrew_agent_session"] (and the X-Session-Key header). Browser requests are unchanged.

Two tests in test/test_app_agent_routes.py cover it. One checks that none of those headers, and none of their values in the raw headers, reach the handler. The other replays the handler's headers through token_auth and checks the call is refused and not marked internal. Both fail with the strip removed.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD on 22ff443.

The new head answers bolichen97's blocking finding in the way they asked. On an agent-route call the app handler now gets a clone of the request without X-Internal-Secret, X-Session-Token, X-Internal-Caller, Authorization or Cookie (route_registry.py#L32-L53). Two tests check that the handler sees none of them and that replaying its headers is refused. I found no defect in that change. All AI lanes pass on this head and every check is green.

What still blocks, and what clears each:

  1. bolichen97's change request is still active. They need to re-review this head.
  2. The PR adds an internal-secret admission arm in token_auth.py and passes a caller-named session to app handlers. Admission changes are reserved for a human security review.
  3. Let installed apps declare agent-callable routes with verified caller session #16910 is tier:T4 with needs-human, and RFC docs(rfc): installed apps declare agent-callable routes #19676 is unmerged. A maintainer must accept the design.

Our earlier change request is superseded by this hold. No PR code was run locally.

Reviewed head: 22ff4430444e57dbc7531d1fa3005fe9f10cdd4c.

— crew-pr-reviewer (r123)

@bolichen97

Copy link
Copy Markdown
Contributor

[operator: bolichen97] Maintainer ruling: the design RFC #19676 must merge before this PR. Please drive #19676 to an agreed, merged state first; this PR then needs a re-check against the merged RFC and a human security review of the new internal-secret admission arm in token_auth.py.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

Understood. #19676 now records this ruling under open question 4 (head 54c21dd). Once #19676 merges, this PR gets re-checked against the merged RFC before the security review.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 22ff443.

The head is unchanged since our last review. RFC #19676 has now merged, which was the first step of the maintainer ruling, but the merged RFC still reads status: draft with "Acceptance: none recorded yet." The implementation matches the RFC's Phase 1 row (manifest field, admission arm, dispatch decision, app_request, docs). Every AI lane passes on this head and every check is green. I found no code defect.

What still blocks, and what clears each:

  1. bolichen97's change request (filed at ffebd68) is still their latest review. They need to re-review this head.
  2. Human security review of the new internal-secret admission arm in token_auth.py#L395-L430, and of the caller-claimed session handed to app handlers in route_registry.py. The maintainer ruling requires it, and admission changes are reserved for a human.
  3. The re-check against the merged RFC: a maintainer records acceptance in the RFC (it is still draft) and Let installed apps declare agent-callable routes with verified caller session #16910 (tier:T4, needs-human) is triaged.

No PR code was run locally.

— crew-pr-reviewer (r126)

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at e9c44c0.

This head is a pure rebase of 22ff443, which we reviewed in r126; the PR's own added and removed lines are identical. I still find no code defect. The credential strip before app dispatch is in place (route_registry.py#L32-L53), every AI lane passes, and every check is green.

What blocks, and what clears each:

  1. Merge conflict. The branch conflicts with main in src/kiro_crew/apps/manifest.py. Please rebase.
  2. bolichen97's change request (ffebd68) is still their latest review. They need to re-review a current head.
  3. Maintainer ruling not yet met. RFC docs(rfc): installed apps declare agent-callable routes #19676 merged, but docs/request-for-change/rfc-app-agent-routes.md still reads status: draft with "Acceptance: none recorded yet.", and Let installed apps declare agent-callable routes with verified caller session #16910 is tier:T4, needs-human and parked. A maintainer has to record acceptance.
  4. Human security review of the new internal-secret admission arm (token_auth.py#L470-L565), and of the caller-claimed session handed to app handlers.

AI findings judged non-blocking:

  • First Principles item 7: the builtin snapshot stores agentRoutes that nothing reads. It is dead data with no effect on behaviour.
  • First Principles item 8: extra_headers and the response cap widen five helpers for one caller. This is a style point, and you answered it on c3b53b3.
  • Design note 1: kirocrew_agent_session is only attested on the unix socket. On TCP the caller must already hold the internal secret, so this is not a bypass. It belongs in the security review in item 4.
  • Design note 2: an undeclared catch-all route now refuses an internal-secret call. That narrowing is intended, and no caller in this repository sends one.

I read the source and CI; I did not run any PR code.

— crew-pr-reviewer (r134)

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at eb98640.

This head rebases e9c44c0 (reviewed in r134) onto newer main. The PR's own added and removed lines are byte-identical, and the branch now merges cleanly with main, so the earlier manifest.py conflict is gone. I still find no code defect. Credential headers are stripped before app dispatch (route_registry.py#L33-L53). All four AI lanes pass on this head, and every check is green or skipped.

What blocks, and what clears each:

  1. Human security review. The PR adds an internal-secret admission arm on app catch-all routes (token_auth.py#L400-L445) and hands a caller-named session to app handlers. Changes to who is admitted are reserved for a human.
  2. @bolichen97's change request (on ffebd68) is still their latest review. The credential strip answers it, but they need to re-review a current head or dismiss it.
  3. Maintainer ruling not yet met. RFC docs(rfc): installed apps declare agent-callable routes #19676 has merged, but docs/request-for-change/rfc-app-agent-routes.md on main still says status: draft with "Acceptance: none recorded yet.". Let installed apps declare agent-callable routes with verified caller session #16910 is still labelled tier:T4, needs-human and parked. A maintainer needs to record acceptance.

AI findings judged non-blocking:

  • First Principles item 1: no in-repo app declares agentRoutes. The PR states that the consumer is an outside registry app, and that question belongs to the maintainer ruling in item 3.
  • First Principles item 7: the builtin snapshot stores agentRoutes, which nothing reads. This is dead data with no effect on behaviour.
  • Design note 1: an internal-secret call to an undeclared catch-all route now gets 403. This narrowing is intended, and the lane itself found no in-tree caller that breaks.
  • Design note 2: on TCP loopback, kirocrew_agent_session is only the caller's own claim. That caller must already hold the internal secret, so this is not a bypass. It is part of the security review in item 1.

I read the source and CI. I did not run any PR code.

— crew-pr-reviewer (r136)

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

On the First Principles BLOCK ("second enablement reader": _screened_installed_app and _owner_json_is_genuinely_absent in mcp_tools/apps.py): the separate reader is deliberate, and I am keeping it.

app_enabled_state reads installed.json with Path.stat() and then read_text(). Both follow symlinks, so an installed.json that links to a regular file elsewhere passes its S_ISREG check and gets opened and parsed. The GPT review blocked three earlier heads of this PR (c9bbb3d, 7dcab4b, 9a8f932) because app_request and its tool-listing scan reached that unscreened read. The fix was to read through _owner_json, which screens the path before following any link and refuses one that points into a protected location. _owner_json returns None both for "no record" and for "refused or unreadable", so _owner_json_is_genuinely_absent separates the two and keeps the listing fail-open only for a real read fault.

Calling app_enabled_state here would reopen that finding. Removing the duplication properly means making app_enabled_state itself screen links. It has 15 call sites in 8 files, including the backend paths that delete materialized resources on a False, so that change belongs in its own PR.

The same code drew a First Principles PASS on a1ce5b8 and b8662a8 and a BLOCK on 2282556 and 3c12bc1.

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Security Scope Review (fork) — 🔴 BLOCK (blocking)

Which legitimate operations does 4c03f1494592b879c6a01fda4668ef82bbeed2f8 newly refuse? Model proposes, scripts/deny_diff.py decides — updated in place on each push. A script-confirmed regression blocks PR readiness.

the review scope was never resolved: the generate job did not finish (it timed out, failed or was cancelled), so no leg ran; its log names the step that stopped

No [SCOPE-REVIEWED] marker for this head was produced, so the model's text is withheld: it cannot be shown to describe this revision. See the job logs.

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

Thanks: the point from my 10-23 review is fixed at 41965f7. The request an app handler gets is now cloned with scrubbed headers (route_registry.py), so the core secret no longer reaches app code.

Requesting changes for one point: this head adds three regexes in product code, and this repository asks new code to validate text without them.

  • apps/manifest.py: _AGENT_ROUTE_SEGMENT_RE checks each route segment with fullmatch. Instead, accept a segment that is non-empty and whose characters are all in a fixed set (ASCII letters, digits and ._~-). Or accept a {name} segment that starts with { and ends with }, where the inside is non-empty, starts with a letter or _, and has only letters, digits and _.
  • validation_parts/app_schemas.py: _APP_REQUEST_APP_RE checks the app name. Split on -, require every part to be non-empty, and require every character to be an ASCII lowercase letter or digit.
  • validation_parts/app_schemas.py: _APP_REQUEST_PATH_RE checks the request path. Require a leading /, split the rest on /, require every segment to be non-empty, and require every character to be in a fixed set (ASCII letters, digits and ._~:@+-).

The tests that cover these validators should pin the same accept and refuse cases. CI is green.

bolichen97
bolichen97 previously approved these changes Nov 7, 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.

Approving at b72712a. The point from my last review is fixed: _AGENT_ROUTE_SEGMENT_RE, _APP_REQUEST_APP_RE and _APP_REQUEST_PATH_RE are gone, and the diff adds no new regex in product code. The import re lines left in those files are existing ones from main. The core secret is still scrubbed from the request an app handler receives. All checks pass.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at b72712ae57e681ddd48cb5d37bc55a4b2a2ed7c7 for a human security reviewer.

I found no code defect. Since our r136 review at eb98640 the regex validators are replaced with character-set checks, and the agent socket can now reach a declared app route by capability instead of the secret (token_auth.py#L399-L408, #L612-L636). Dispatch still refuses an undeclared route before any handler runs, and the handler gets the request without core credential headers (route_registry.py#L481-L497). The capability header is not stripped on that arm, but it is bound to the caller's pid, so app code in the gateway cannot replay it.

What holds it:

  1. Admission change. The PR changes who token_auth admits, adds the agent-socket capability arm, and hands app handlers a caller-named session. Those changes are reserved for a human under our rules. @bolichen97's approval at this head is that human sign-off. We do not add a bot approval.
  2. Untracked follow-up. The description leaves making app_enabled_state screen links, and deleting the second reader, "for its own PR" (apps.py#L652-L690). Please open an issue for it and link it in the description.
  3. Maintainer ruling of 10-25. rfc-app-agent-routes.md on main still reads status: draft, and Let installed apps declare agent-callable routes with verified caller session #16910 is still parked. The approving maintainer can record acceptance or say the ruling is met.

The description's token_auth row mentions only the secret. Please also name the agent-socket capability path, which the spec already covers.

AI findings judged non-blocking: Design note 1 (the session is caller-claimed on TCP; the caller must already hold the secret, and the spec says so); Design note 2 (the tools/list scan cost, a latency suggestion); First Principles item 6 (the header strip is documented and tested); the Opus notes on manifest.py size and on the timeout wording (style and wording only).

Our earlier change request is superseded by this hold. All checks are green and the branch merges cleanly.

— crew-pr-reviewer (r149)

@KiroCrewCaptain

KiroCrewCaptain commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own.

The PR adds an opt-in, prompted kirocrew-apps MCP server for third-party apps' manifest agentTools. It matches the accepted RFC, which names this PR as the base that must merge before its phase 1. Checked in code: each gateway route resolves only its own set of tools, and the new path is strict internal. The cross_app refusal really runs, because request["app"] comes from the X-Session-Key header that _post sends. The signed proxy strips internal credentials. may_skip_gate refuses kirocrew-apps refs, which also closes the skill-view autoApprove path. Wildcards that would cover the server are dropped by every allowedTools writer. A scoped app agent has the server withheld through excludeServers, which the shared dispatch loop applies by server name. The launch-path reorder keeps the same refusals. Tests cover each guard and CI is green. The remaining gaps (direct authored-spec launch only warns, no owner grant yet, direct posts with the internal secret) are acknowledged, already exist on main, or are planned in the RFC's later phases.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 6178410ab8 · 2023 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

bolichen97
bolichen97 previously approved these changes Nov 12, 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.

Re-reviewed at f4b502f. I read the whole product diff and the list of tests, and checked the three things that matter for a third-party reach.

Default off. kirocrew-apps is opt_in: an agent reaches it only when its spec is granted @kirocrew-apps, so no default agent gains the surface. The managed-server list entries are additions for a server nobody mounts today, and with no such mount config_mounts_prompt_only_server is false, so final_ceiling_pass, sanitize_agent_config_governance, _ceiling_permitted and the bridge filters return what they returned before. test_a_match_all_grant_stands_on_an_agent_without_the_server and the "keeps wildcards without a prompt-only server" test pin this, so off behaves like main.

Every call still prompts the owner. The server entry has no autoApprove key and the comment says none may be added. may_skip_gate refuses any grant that names the server, and a match-all or @kirocrew-* pattern is withheld from allowedTools of any agent that mounts it, in the materializer, the template ceiling, the packaged bridge filter, the whole-config sanitizer and the KAS projection. Scoped app agents have the whole server withheld, because its tool names are not known when they are built. That only adds prompts, and only for the new server.

What a call can reach. third_party_tools lists only a non-first-party app's tools, in its own namespace, with no strictSession tool and no name a first-party or core tool has. /api/app-tools/prompted-call is strict internal, resolves only third-party declarations, validates the arguments again, refuses a disabled app, and refuses a session owned by another app (cross_app). The core route cannot reach a third-party tool and the prompted route cannot reach a first-party one, and both have tests. A third-party answer never takes the verbatim credential path and is redacted and cut like a core answer.

No regex added; the only new pattern matching is fnmatchcase on a server name. The docs and RFC updates match the code.

The change request that iamwhatever left on an earlier head still gates the merge.

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

Re-reviewed at 631f428. I compared this head with the one I approved earlier (f4b502f) by diffing the PR's own changes on both. Most of the delta is rebase and test counts. The new behavior is in agent_materialization/fork_refresh.py, and I need one change there. I have turned off the auto-merge I set on the earlier approval until it is fixed.

New launch refusal. _require_prompt_only_launch_grants_safe (called from require_shared_template_within_ceiling) raises SharedTemplateOverCeiling and ends the start with "The session was not started" for any authored spec that mounts kirocrew-apps and has an allowedTools entry covering it. It runs for every authored spec, including one no crew is bound to. On main nothing refuses that start, so this makes a session fail to start where it starts today, even though the aim (every call to that server must prompt) is a good one. The earlier head met the same aim without failing a start: the Kiro Crew copy of the spec drops the covering grants and the calls prompt.

Please keep a start working. Two ways that fit:

  1. Do not refuse. Log the warning and the audit line for the covering refs (the new report_prompt_only_withheld already does this for the view) and let the start go on, or
  2. Keep the refusal, but behind a setting that is off by default, so the strict check is opt in.

Everything else in the delta is fine to me: the audit line for withheld wildcards, _project_spec_for_launch skipping the scan when the checkout has no project agents directory, and the test updates. The access design I reviewed earlier is unchanged: the server is opt in, has no autoApprove, and every call still asks the owner. No regex added.

I will approve again once the start is no longer refused by default. iamwhatever's older change request also still gates the merge.

… kirocrew-apps server

A first-party app's manifest agentTools are listed under kirocrew-core,
which the default agent auto-approves as a whole server, so a
third-party app's block listed nothing. Section 30.1 named the missing
piece: a listing path that asks before each call, a server of its own
outside allowedTools.

kirocrew-apps is that server (mcp_apps.py). It is an opt_in managed
server like kirocrew-secrets: no default or derived spec carries it, so
an agent reaches third-party app code only when its spec is granted
@kirocrew-apps, and a worker it spawns does not inherit it. It has no
autoApprove and no allowedTools entry, so kiro-cli asks before every
call and the PreToolUse gate sees each one; kirocrew doctor never adds
it to allowedTools.

app_agent_tools.third_party_tools reads an installed app that is not
first party, not adopted under pin trust and not named by a shipped
manifest, from its data-home app.json. It takes no block that states a
namespace other than the app's own or declares a strictSession tool,
and drops any name a first-party app declares. Each listed description
is led by the name of the app that serves it.

A call is validated through the field engine and posted to the new
strict internal route POST /api/app-tools/prompted-call. Its handler
shares the decision of /api/app-tools/call; each route resolves only
its own set of declarations, so neither server can reach the other's
tools. The answer is redacted and capped by the code kirocrew-core
already uses (app_tools.shape_answer).

The post carries the lenient session key, so token_auth names the app
that owns the calling session, and the prompted route refuses (403
cross_app) a session one app owns calling another app's tool on both
dispatch paths (the signed proxy already refused it; the route registry
did not). A text answer's verbatim-credential shape stays first-party
only; a third-party answer in that shape is redacted whole. A scoped
app agent (permissions.mcpTools) has the server withheld whole, because
its tool names are those of the apps installed at call time.

This replaces the agentRoutes and app_request design this PR first
carried: the agentTools seam (kirodotdev#32660) now covers first-party apps, and
this extends it to third-party apps. The RFC for agentRoutes records
that no implementation of it is open.

Part of kirodotdev#16910

This branch has not been deployed

No deployments
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) readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants