[3mdistal]

This PR adds the themed app review surface on top of #8016's approval flow, which has landed on main.

What changes

When an MCP client cannot show a person's approval prompt, #8016 returns a link to a plain review page. This PR opens the same review inside an opted-in app, using its name, logo, theme, and components. The person can inspect the call, approve or deny it, and return to the app.

• Signed-in readers are redirected to the app's home route with #mcpApproval=<id>. The fragment survives home-route redirects, and AppProviders shows the review in place of the app. Sign-in continues at the original review link.
• appApprovalPage is off by default. Apps opt in through the chat plugin or mountMCP only when their shell renders AppProviders. The 16 chat templates, Dispatch, and Builder Code starter opt in. Plan opts in on its separate MCP mount. The default scaffold remains off.
• The card identifies the requesting client and connection date, recipients, stored fields, times in the reader's zone, and any prior-run or shortened-storage warning. After a decision it retains a short description of the request so several open reviews remain distinguishable.
• The shared summary removes repeated recipient and time-zone rows while retaining separate to, cc, and bcc fields. Schema choice titles, including titled booleans, supply readable values. Identifier-style enums are split into words, and time zones use localized names. The plain page and client form share these improvements.
• Email addresses remain copyable unchanged and wrap only after @. Recipient text shrinks when needed on narrow screens. Approve uses the theme's foreground and background colors.
• Lost or unreadable decision responses trigger a state reread. At the deadline the server determines whether the review expired or the grant was used. Timing uses the server's servedAt value, so a fast or slow device clock does not change the decision window.
• The review appears only in the top-level private app, outside onboarding and the phone handoff. It stays out of frames, public pages, and session-bypassed surfaces. Custom authentication without the cookie-only browser hook gets a distinct sign-in-unavailable state.

The browser reads and decides through the new @agent-native/core/client/mcp-approval helpers. Decisions retain #8016's session, ownership, token, and same-origin checks. The app surface requires the standard framework route prefix; other MCP prefixes keep the plain page. New copy is translated into all 11 locales, and affected apps receive changelog entries.

Verification

• Restacked onto main after Let people approve MCP calls on a review page when their client can't ask #8016 squash-landed as 8254996c: merged main up to the commit before the squash, recorded the squash with -s ours since this branch already had its changes, and checked that the diff against main covers the same 56 files as before. The Toolkit review and AppProviders specs (62 tests) and the Core approval route, summary and review-helper specs (81 tests) pass on 04333606.
• The review gate reads the window while rendering, so it must never render on the server. AppProviders keeps it inside ClientOnly, and a new test server-renders AppProviders with window stubbed out. If the gate moves in front of ClientOnly, the test fails with Cannot read properties of undefined (reading 'top').
• Merged Let people approve MCP calls on a review page when their client can't ask #8016's head 97a75888, which now includes main through Ask a person before CLI calls run actions that need approval #8117, without conflicts. The earlier AppProviders.tsx conflict kept both main's lazy agent-run awareness component and this PR's review boundary, and main's strict lint flag on a dead ?? "" was fixed by finding the time placeholder by position.
• Main's strict compiler check flagged the review page passing an undefined abort signal where fetch takes null; it now passes null. On the merged tree Core typechecks, and the oracle-loosening, strict-lint and escape-hatch guards pass. The release test that pins Toolkit's Core floor passes.
• A lone cc or bcc now keeps its own row on the review page, so a copy doesn't read as sent to; a lone to or attendees list of addresses is still left to Reaches. The summary, route, Toolkit review and Calendar MCP write specs pass (77, 30 and 33 tests).
• The grant id and fragment helpers in shared/mcp-approval-review.ts now have their own spec beside them, which the changed-line mutation job needs to test that file.
• The review view now takes its servedAt time and state after its async reads (requester, prior run, decision token), so read latency no longer looks like clock skew to the page; a grant that expires during those reads comes back expired. A new route test covers it and fails on the previous code.
• On the previous merged tree (674b15fd), 385 of 386 Core approval, redaction and mount tests and 61 Toolkit review and AppProviders tests pass. The other Core test, the ChatGPT scan replay in server.spec.ts, hit its 60 s timeout with this machine's CPU at 99% from other work; it passed alone in 30 s on the previous head. strict-lint passes, and escape hatches show no growth across the 59 changed files.
• Restacked only this PR's ten commits onto the new Let people approve MCP calls on a review page when their client can't ask #8016 head. The grant-ID check retains both the routed-path helper and this PR's shared UUID validator.
• 430 focused tests pass across 13 suites: the route redirect, base/home paths, browser helpers, summaries, mounted routes, plugin options, template opt-ins, review rendering, AppProviders, Dispatch, and CRM catalog options.
• The inherited real-H3 mount regression checks differing raw and routed paths for review reads and decisions, with persisted grant state.
• Format check, oxlint, direct core typecheck, and Core and Toolkit builds pass. The direct typecheck avoids the known Windows workspace-launcher spawn EINVAL failure in aggregate pnpm lint.
• All 93 guards pass with Git's GNU utilities on PATH, including both localization guards and the Builder Code template-layer check.
• Earlier local Calendar browser acceptance is historical evidence: light and dark themes, desktop and 390 px screens, approval and retry, prior-run warnings, and seven recipients. This rebase reruns focused automated checks; it does not claim a new browser run.

Before merge

Toolkit's optional Core peer is now >=0.221.0. Both changesets bump Core as minor, so 0.221.0 is the first release that will carry client/mcp-approval; no published Core exports it yet. Main's Core is still 0.220.0. If a Core release goes out before this PR lands, the floor moves to the release after it.

Remaining scope

Calendar's sendUpdates schema can separately add option titles such as “All guests” to improve the generic labels.

🤖 Generated with Claude Code

[github-actions]

Visual recap — generation failed

The visual recap could not be generated for this pull request. This is informational only and does not block the PR.

Diagnostic:

No plan URL: Repair changed too much of targeted file plan.mdx; expected a localized parser fix.

Agent output: Repaired recap-source.json: escaped the Mermaid and diff code strings that contained parser-breaking literal newlines. JSON and required block IDs remain valid. --- ⠀ 🟢 Visual recap source repaired and ready for the hosted parser retry. stderr: Reading additional input from stdin...

[3mdistal]

On the low finding in the 133efc4 review (a 401 on Approve or Deny leaves no in-page way back): leaving this as is. The review link the agent gave is where sign-in happens. Opening that link again signs the reader in and brings them back to the same review. That works because the decision was never saved and the grant is still pending until its deadline. A session that ends inside the ten-minute review window, such as a sign-out in another tab, is rare. Adding a sign-in control to the review would be a new visual element, and this PR is closed to further visual changes. If it's wanted, it can be a follow-up shared with #8016's plain page, which says the same thing.

[3mdistal]

On the 🟡 LOW from the 382399b6 review (Dispatch's Core peer range): I'm keeping Dispatch's range as it is.

• Dispatch's own code still runs on Core 0.220.x. mcp.appApprovalPage is a server option, and 0.220.x's agent-chat plugin ignores mcp keys it doesn't know. That Core has no review-link fallback either, so the option would have nothing to route.
• The part that needs 0.221.0 is Toolkit's AppProviders, which imports @agent-native/core/client/mcp-approval. Toolkit's optional Core peer is now >=0.221.0, and Dispatch depends on Toolkit through workspace:*, which publishes as the same fixed-group version. An install that pairs this Dispatch with Core 0.220.x therefore already gets Toolkit's unmet-peer warning.
• Dispatch's >=0.220.1-0 || >=0.221.0-0 comes from Fix embedded Workspace app session handoff #8227, and package-release-workflow.test.ts pins it exactly so Dispatch accepts Core prerelease snapshots on both the 0.220.1 and 0.221.0 version lines. Raising it here would undo that for a requirement Toolkit already declares.

[builder-io-integration]

Builder reviewed your changes and has a few items to flag 🟡

Review Details

Incremental Review Summary

This update keeps the core MCP approval flow and themed in-app review surface intact, with the latest addition protecting the review boundary from server rendering through ClientOnly. I verified that the previous SSR browser-global issue is fixed: ProvidersInner (and thus McpApprovalReviewBoundary) is now rendered only after the client mounts, and a server-render test asserts the review stays out of markup when window is absent. Its prior thread has been resolved. The approval and grant-state paths otherwise appear sound in the current review.

Finding

• 🟡 Low — Schema labels can hide the actual argument value: describeFieldValue substitutes a schema-authored title/description for the literal value in the primary summary. A reviewer could see an inaccurate label while approving the actual argument; show the literal alongside the label or keep the label secondary. This may be filtered by review policy.

🧪 Browser testing: Skipped — dev server setup fails during Toolkit postinstall with 93 TS2883 React type errors; restart reproduced the failure.

[3mdistal]

On the 🟡 about schema labels hiding the literal value: the literal is always on the page. Both the in-app review and the plain page show the call's stored arguments, unchanged, under Details. A label replaces a value only when that value exactly matches a const (or a titled enum word) in the action's own input schema. The app that runs the action writes that schema, so neither the agent nor the MCP client can choose the label. A value with no matching option is shown as written. I'm leaving it as it is: the labels are there so a person can read a choice like externalOnly without knowing the action's code.