Skip to content

docs(rfc): specify an owner grant for third-party app agent tools - #35966

Merged
Pearcekieser merged 1 commit into
mainfrom
pearcekieser/rfc-third-party-agent-tools-grant
Nov 13, 2026
Merged

Pearcekieser merged 1 commit into
mainfrom
pearcekieser/rfc-third-party-agent-tools-grant

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A maintainer can accept or change the design that lets a third-party app's agent call the app's own tools, before anyone builds it.

Since #34762, the stdio mcpServers that an app's agents declare get no secret and no app token, so they cannot call the app's own routes. docs/app-kit/api-reference.md says so. Issue #32727 option (c), "third-party apps keep shipping their own mcpServers entry", thus no longer works. A third-party app on main has no supported path from its agent to its own routes.

#17015 adds kirocrew-apps, an opt-in server that lists third-party agentTools and asks before each call. But the owner never approves the tool set, and an app that scopes its own agent loses the server. Section 7 of rfc-app-contribution-points.md asks for an owner grant, and its last line says that a separate RFC must specify the section before any of it is built.

Why it matters

Without an accepted design, the owner grant part of section 7 for third-party apps cannot start, and third-party apps keep no path from their agents to their own routes.

Not a goal

  • Code. This PR adds an accepted RFC, an index row, two README preamble sentences and three pointer sentences. Nothing is built.
  • Grants per crew, crewmate or session. The RFC grants per app first.
  • A credential for an app's own stdio mcpServers. The RFC lists it as a rejected alternative.
  • Any change to first-party app tools on kirocrew-core.

What changed (motivation → approach → change)

The new RFC, rfc-app-agent-tools-third-party-grant.md (accepted), makes a third-party tool reach an agent only when three checks all pass. The owner approved the tool, the agent mounts kirocrew-apps, and the person approves the call. This is section 7's rule: app grant AND caller authority AND per-call approval.

The grant is a new staged family, agentTools, with one entry per tool and a digest of its declaration, so an update that changes a tool needs a new approval. The gated reader runs in the gateway, and the server gets its listing from a new internal route, because the sandbox masks the grant store. An app's own scoped agent gets an allow list of its own tools. Each call's audit row names the grant entry.

The RFC index lists the new RFC, and section 7 of rfc-app-contribution-points.md links to it. That pointer also says that outputSchema validation, the effect label and the schema drift rule of section 7 still need an RFC before they are built.

Maintainer bolichen97 signed the direction in a review of this PR and answered the three open questions. The RFC records the answers, and the design follows them. The owner approves agent tools in a separate step after install, and installing approves no tool. The phase 2 PR chooses the allow-list mechanism for scoped app agents. The digest includes title and description, so a changed description needs a new approval.

Backwards compatibility

Compatible: the diff is docs only and changes no behavior.

Removes nothing: the diff adds one RFC, one index row, two README preamble sentences and three pointer sentences.

Tests

No test. The diff is docs only.

Manual verification

N/A. I compared each file and line that the RFC cites with main at 029b6db029.

Related Issues

Refs #32727

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

Fixes #35965

@Pearcekieser
Pearcekieser requested review from a team and KiroCrewCaptain as code owners November 12, 2026 17:42
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 83e3105bb569928cb0140c3d8a3dff7be39a2392 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 Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 83e3105bb569928cb0140c3d8a3dff7be39a2392 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: this is a docs-only RFC that a maintainer accepted, it builds nothing, and it states its own gaps.

Notes

  • The RFC itself says that any process in the sandbox can read the internal secret and post to prompted-list/prompted-call directly. That path skips the per-call prompt and the own-app limit, so against an injected agent shell only the owner grant holds. Phase 1 should treat the grant as the only real boundary, and the "AND of three checks" summary should not be read as defense in depth.
  • Phase 2 builds the allow list on top of cross_app checking. That check keys off a caller-supplied X-Session-Key, and an empty or unowned key skips it. Phase 2 should bind the own-app check to the session the gateway authenticated, not to that header.

[DESIGN-REVIEWED] 83e3105

Description read

[DESCRIPTION-READ] 5d7c0c9cdcef5afc7803a46ad263dbc938ffc7f048066afb9ad7ff7fcb42f45e

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 Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 83e3105

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 83e3105bb569928cb0140c3d8a3dff7be39a2392 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 83e3105

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 83e3105bb569928cb0140c3d8a3dff7be39a2392 false-positive: <reason, 20 to 500 characters>

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

Direction signed by maintainer (bolichen97). Answers to the open questions: (1) approval is a separate step after install, not implied by installing, matching other explicit-only grants; (2) phase-2 allowlist mechanism is left to the phase-2 PR, keep phase 1 to per-tool owner approval; (3) include title and description in the digest so a changed description needs re-approval.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 12, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-third-party-agent-tools-grant branch from 1f15edb to 9c5706f Compare November 12, 2026 20:27
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): head 9c5706f records your three answers and sets the RFC status to accepted.

Answer 1. The RFC makes approval a separate step after install. It does not cite the explicit-only precedent, because that precedent does not hold on main. On main, each writer of a first approved set stores the declared entries of every staged family, and explicit-only families such as reachableByUserSessions are included. These writers are the install at manager_install.py:468, _freeze_declared in manager_records.py, both first-manifest paths of an external registration at manager_external.py:320 and :328, and the built-in writer at manager_builtins.py:827 and :869. Thus the RFC states a new rule for phase 1. These writers store an empty agentTools set, and only an owner approval of a tool adds an entry. Open question 1 quotes your answer and records this difference from main.

Answer 2. Phase 1 keeps to per-tool owner approval. The phase 2 PR chooses the allowlist mechanism.

Answer 3. The digest now covers title and description, together with the route, inputSchema, timeoutSeconds, result, strictSession and maxResultChars. A phase 1 exit criterion requires that an update that changes only a description holds the tool back until the owner approves it again.

@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: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 12, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-third-party-agent-tools-grant branch from 9c5706f to 05ab69f Compare November 12, 2026 22:45
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/README.md over 30 commits (d9839ee -> 0feaa8b). This branch changes the same hunks as before, and the new head is 05ab69f.

@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: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 12, 2026
@Pearcekieser
Pearcekieser enabled auto-merge (squash) November 13, 2026 00:31
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates an 8% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

Docs-only PR adding an accepted RFC (owner grant family agentTools on top of the prompted kirocrew-apps server from #17015), an index row, and a pointer from rfc-app-contribution-points §7. Checked the RFC's claims about main against the repo: app_agent_tools reads first-party apps only, point_grants registers no agentTools family, grant_source reads only permissions/contributes, and the explicit_only mechanism and install behaviour are as described. sandbox_leaves.py does expose run/ and .local_secret, so the stated bypass of per-call approval is real, but it already exists on main and in #17015. The design adds a fail-closed owner grant read in the gateway and does not widen any trust boundary. No behaviour change, CI green, and the maintainer acceptance is recorded in the RFC.

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 05ab69f620 · 369 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

The design direction is signed off by a maintainer in a review on this PR. The PR now waits for a maintainer approval.

The review found no blocking issue on this head. It changes three Markdown files under docs/request-for-change/ and no code. We checked the RFC's code citations against main, and each one resolves where the RFC says. That includes _first_party_apps, STAGED_GRANT_FAMILIES, _freeze_declared, enable_app(grants_consent=...), app_token_path_allowed and APP_SDK_LEVEL. The list of first-set grant writers is complete. The three recorded answers match the maintainer's review. One thing done well: the RFC checks the "matching other explicit-only grants" premise against main and finds that install already stores reachableByUserSessions. So it states answer 1 as a new rule and names every writer that must change.

For the security review:

Optional:

  • In the Security considerations bullet near line 279, add one sentence that says the direct path also skips the section 4 own-app limit. You could also add a phase 2 exit criterion for it.
  • Line 263 says no released install loses a tool. That holds only if phase 1 ships in the same release as feat(apps): list a third-party app's agentTools on an opt-in prompted kirocrew-apps server #17015. Consider stating it as a condition, with the phase 1 PR listing the take-away otherwise.
  • The new pointer in rfc-app-contribution-points.md (line 636) says this RFC specifies section 7 in full. But section 7's outputSchema validation, effect label and schema drift rule are not addressed. A Non-goals line, or a pointer that says "the owner grant part of section 7", would make this clear.

bolichen97
bolichen97 previously approved these changes Nov 13, 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, docs only. I read the new RFC in full, the cross-link in rfc-app-contribution-points.md §7, and the index row. The document now records all three answers from my earlier review and follows them:

  1. Approval is a separate step after install. §2 makes every writer of a first approved set (install, _freeze_declared, both external first-manifest paths, the built-in writer) store an empty agentTools set, and approval goes through enable_app(grants_consent=...) on the detail page. It also notes that this differs from the install rule for reachableByUserSessions, which is the right thing to say out loud.
  2. The phase-2 allowlist mechanism is left to the phase-2 PR. §4 and the migration table name both candidates (honourToolRefs refs, or a managedToolPolicy include list) and defer the choice. Phase 1 stays per-tool owner approval.
  3. The digest includes title and description. §1 lists them in the digest fields beside route, schema, timeoutSeconds, result, strictSession and maxResultChars.

It adds no auto-approval (kirocrew-apps stays prompt-only), keeps the server opt-in, and names main's existing internal-secret gap without changing it. Main lists no third-party agentTools at all, so nothing main allows is refused.

Direction signed by maintainer (bolichen97).

@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: checking Automated validation is still running labels Nov 13, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-third-party-agent-tools-grant branch from 05ab69f to fbd9b23 Compare November 13, 2026 01:46
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): head fbd9b23 applies the three suggestions.

  • Security. The bullet now says that in feat(apps): list a third-party app's agentTools on an opt-in prompted kirocrew-apps server #17015 the token middleware takes the calling app from the X-Session-Key header that the caller sends. A key that no app owns, an empty one included, skips the cross_app check, and on that path only the owner grant still holds. The three-checks bullet also names the section 4 own-app limit.
  • Backward compatibility. The "no released install loses a tool" claim is now a condition. If a release ships feat(apps): list a third-party app's agentTools on an opt-in prompted kirocrew-apps server #17015 without phase 1, the phase 1 PR and its release note say that every third-party agent tool stops listing until the owner approves it.
  • Section 7 scope. The RFC header says that it specifies only the owner grant part of section 7, and that phase 1 builds only that part. A Non-goals line names outputSchema validation, the effect label and the schema drift rule. The pointer in rfc-app-contribution-points.md says that those three still need an RFC before they are built, so the existing rule in that file holds as written.

I did not add the phase 2 exit criterion for the own-app bypass. Closing the internal-secret gap is outside the direction that bolichen97 signed, and main has the same gap today on /api/app-tools/call.

@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 13, 2026
Adds rfc-app-agent-tools-third-party-grant.md (draft). It specifies section 7 of rfc-app-contribution-points.md for third-party apps: a third-party app's agentTools reach an agent only when the owner approved the tool (a new agentTools staged grant family), the agent mounts the prompted kirocrew-apps server from #17015, and the person approves the call. It also lets an app's own scoped agent reach its own approved tools. Nothing is built.
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-third-party-agent-tools-grant branch from fbd9b23 to 83e3105 Compare November 13, 2026 03:30
@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 Nov 13, 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-review at 83e3105 (docs only, my approval at 05ab69f was dismissed by the push).

I read the whole new document and the README and rfc-app-contribution-points changes. It still matches my three answers:

  1. Install approves no tool. The owner approves agent tools in a separate step after install. Section 2 now also lists the built-in writer among the writers that store an empty agentTools set, with the reason (an adopted former built-in keeps its stored set). That is the same answer applied to one more first-set writer.
  2. The allow-list mechanism for a scoped app agent stays with the phase 2 PR (section 4, Open questions 2).
  3. The digest includes title and description (section 1, with the phase 1 exit test for a description-only change).

Changes since 05ab69f that I checked:

  • Scope is now explicit: this RFC specifies only the owner grant part of section 7. The outputSchema validation, the effect label and the schema drift rule are listed as non-goals and still need their own RFC. The pointer added to rfc-app-contribution-points.md says the same. Good, it keeps the acceptance from reading wider than what I signed.
  • Security considerations now names the direct path: a process that holds the gateway's internal secret can post the listing and call routes with no prompt and outside the own-app limit, and only the owner grant still holds there. It says main has the same gap for /api/app-tools/call and that this document does not close it. That is an honest statement of the existing gap, and it adds no new refusal.
  • Nothing here adds a refusal against main: nothing is built, and the reach phase 1 withholds is reach #17015 adds, which is not on main. Backward compatibility covers the release-note case.

Direction signed by maintainer (bolichen97)

@Pearcekieser
Pearcekieser merged commit 2151db2 into main Nov 13, 2026
98 of 101 checks passed
@Pearcekieser
Pearcekieser deleted the pearcekieser/rfc-third-party-agent-tools-grant branch November 13, 2026 06:12
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 13, 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.

Third-party app agents have no supported way to call their own app routes

3 participants