Repository navigation
docs(rfc): specify an owner grant for third-party app agent tools - #35966
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of 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
[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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
bolichen97
left a comment
There was a problem hiding this comment.
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.
1f15edb to
9c5706f
Compare
|
note (non-blocking): head 9c5706f records your three answers and sets the RFC status to 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 Answer 2. Phase 1 keeps to per-tool owner approval. The phase 2 PR chooses the allowlist mechanism. Answer 3. The digest now covers |
9c5706f to
05ab69f
Compare
Code change approver recommendation: ApproveWhy: 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 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 |
|
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 For the security review:
Optional:
|
bolichen97
left a comment
There was a problem hiding this comment.
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:
- 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 emptyagentToolsset, and approval goes throughenable_app(grants_consent=...)on the detail page. It also notes that this differs from the install rule forreachableByUserSessions, which is the right thing to say out loud. - The phase-2 allowlist mechanism is left to the phase-2 PR. §4 and the migration table name both candidates (
honourToolRefsrefs, or amanagedToolPolicyinclude list) and defer the choice. Phase 1 stays per-tool owner approval. - The digest includes
titleanddescription. §1 lists them in the digest fields beside route, schema,timeoutSeconds,result,strictSessionandmaxResultChars.
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).
05ab69f to
fbd9b23
Compare
|
note (non-blocking): head fbd9b23 applies the three suggestions.
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 |
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.
fbd9b23 to
83e3105
Compare
bolichen97
left a comment
There was a problem hiding this comment.
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:
- 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
agentToolsset, with the reason (an adopted former built-in keeps its stored set). That is the same answer applied to one more first-set writer. - The allow-list mechanism for a scoped app agent stays with the phase 2 PR (section 4, Open questions 2).
- The digest includes
titleanddescription(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
outputSchemavalidation, theeffectlabel 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/calland 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)
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
mcpServersthat 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.mdsays so. Issue #32727 option (c), "third-party apps keep shipping their ownmcpServersentry", 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-partyagentToolsand 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 ofrfc-app-contribution-points.mdasks 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
mcpServers. The RFC lists it as a rejected alternative.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 mountskirocrew-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.mdlinks to it. That pointer also says thatoutputSchemavalidation, theeffectlabel 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
titleanddescription, 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
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Fixes #35965