[blove]

Implements #736, following the accepted design in #738 and the decision comment on open question 1.

Off by default (approvals.grants: "off"). Nothing changes for an existing app unless it opts in.

What this adds

A grant: 32 CSPRNG bytes minted when B4.run parks a human-in-the-loop approval, bound to that one parked call, required back when the approval is answered, and consumable exactly once.

Package	Adds
@b4run/sdk	InterruptGrantStore / InterruptGrantRecord / InterruptGrantConsumption, ApprovalGrantMinter, ApprovalGrantMode, createApprovalGrant, hashApprovalGrant, timingSafeHexEqual, createMemoryInterruptGrantStore (WebCrypto only — the main entry is loaded by the edge targets)
@b4run/core	configureApprovalGrants / approvalGrantMode / mintGrantForPark / MissingApprovalGrantMinterError; approvals on B4Config; the park site mints
@b4run/langchain	approvalGrantMinter → config.configurable[APPROVAL_GRANT_MINTER_KEY]
@b4run/cli	minter construction, resume verification + consumption, void-on-supersede, resolveInterruptGrantStore
@b4run/ag-ui	grant on the interrupt and on B4ResumeRequest; B4AguiInterrupt
@b4run/postgres-storage	createPostgresInterruptGrantStore + INTERRUPT_GRANTS_MIGRATIONS
@b4run/sqlite-storage	createInterruptGrantStore (the b4 dev default)

Storage uses the existing versioned runMigrations under pg_advisory_xact_lock, with its own migration component so it versions independently. No column default anywhere, every INSERT names every column, and the frozen-migration rule is written on the migration where the next person to change the shape will read it. Pinned by test/interrupt-grants-ddl.test.ts.

How the minter is injected, and how it fails closed

Two facts have to reach emitPermissionInterrupt, and they arrive by deliberately different routes:

• The minter is per-run, closed over the thread whose resume endpoint will answer, so it can only come from the caller. It rides in config.configurable, following the threadId precedent at capabilities/types.ts, and the park site reads it with getConfig(). Nothing in core's call graph grows a storage parameter.
• The mode is a deployment fact, and it is what makes the minter's absence detectable. It deliberately does not travel the same way. configurable injection is optional by construction — legacy invokers omit it exactly as they omit threadId — so a mode carried in configurable would go missing from precisely the invokers whose missing minter it is meant to catch, and "no mode and no minter" would be indistinguishable from "grants are off". Instead it is a process-wide latch set from the resolved config by prepareRouteExecution and at runtime boot, and it ratchets up only: a second app root in one process cannot weaken a stricter mode already in force.

The fail-closed rule: mode "required" + no minter ⇒ MissingApprovalGrantMinterError, thrown before interrupt(), so the turn aborts and nothing is parked. Asserted loudly in packages/core/test/capabilities/approval-grants.test.ts, which drives a real compiled graph and then checks the checkpoint holds no pending interrupt — a refusal that still parked would be the bypass wearing a stack trace. The test carries a "do not relax this" note.

Resume ordering

thread-access gate → tryClaim → readPendingInterrupts → resolvePendingResume → verify grants → consume → deliver, on both POST /threads/:id/resume and the AG-UI resuming branch (one shared helper, so the two cannot drift). The gate-before-tryClaim ordering documented at runtime-fetch-core.ts is preserved unchanged and grant checks inherit it wholesale.

403 grant_invalid is the same status, code and message for wrong grant / no row / malformed / other thread, so the endpoint is not an oracle. 409 grant_consumed echoes consumedAt + consumedDecision and does not re-execute. Superseded checkpoints void outstanding grants when a turn settles, giving 409 stale_interrupt.

Decisions taken — please object to any of these

Open questions 2–7 in §8 are not settled. Where I had to choose, I took the design's stated recommendation and the narrowest version.

1. Q2 — deny/cancelled consumes the grant: YES (the design's recommendation). A denial is a decision, and a re-answerable denial is a replay surface of its own. Tested end to end.
2. Q3 — subagent grant ownership: the thread whose resume endpoint answers the interrupt. In practice the parent: a subagent materializes as a child graph inside the parent's run, so interrupt() in a subagent node reads the parent's ambient config and therefore the parent's minter. Stated explicitly on createApprovalGrantMinter so a future out-of-process subagent cannot silently mint against a thread with no resume endpoint.
3. Q4 — always is grantable, with no extra gate. Narrowest version. The design notes always writes a durable permission rather than making one decision and may warrant something stronger; I did not add it. Most likely of these to deserve a "no".
4. Q5 — resumeKey still crosses the wire. Unchanged. Removing it is a breaking change to AttachInterrupt and the design calls it "a strict improvement" without settling it.
5. Q6 — no default TTL (grantTtlMs omitted ⇒ no expiry; a human approval may sit overnight) and no deprecation schedule encoded. The default is "off", not the design's "optional": defaulting to "optional" would change behavior for every existing app in a minor.
6. Q7 — interruptId's Math.random is unchanged. Out of scope here; it is not a credential under this design.
7. "off" means "mint nothing", not the design's §6 "mint but never require." A mode called "off" that still opens a store and writes a row per park is not off. Cost, stated in the code: "off" → "required" strands prompts parked while it was off (409 grant_unavailable); step through "optional", which is the migration window.
8. Grant check at step 5, not the design's step 4 — after resolvePendingResume rather than before. Strictly less oracle surface, and a grant is never checked against a body whose shape has not been validated.
9. Both SQL backends declare the contract structurally rather than importing it from @b4run/sdk, matching each package's own ThreadsStore precedent and keeping the lockfile untouched. Say the word and both become type-only imports.
10. resolveInterruptGrantStore is optional on RuntimeBootFallbacks, like loadThreadAccess, because that interface is exported. Absence is not a silent ungating: the park site still fails closed and resume answers 409 grant_unavailable.

What did not survive contact with the code

1. Two of the four binding columns cannot exist at mint time. Inside the interrupt() throw, config.configurable.checkpoint_id is undefined (the parked checkpoint is not written yet) and resume_key does not exist either — it is LangGraph's XXH3-128 of the checkpoint namespace, computed when the write is persisted, by a hasher LangGraph does not export. Verified empirically. So the row stores checkpoint_ns, the graph position the park site does have and the preimage of resumeKey, and the other two halves are enforced against the live checkpoint at resume (the interrupt must still be pending) plus voidOutstanding when the thread moves on. That is strictly fresher than a copy of the checkpoint id would have been.
2. The grant is in the envelope, so its plaintext is at rest in writes. Design §1 argued for attaching it at projection time to avoid exactly this; the park site cannot, having no storage handle and no reach into the three disclosure paths, and attaching downstream is the CLI-minting shape Design proposal (no implementation): approval grants bound to the parked tool call #738's decision rejected. The hash-only store therefore protects the consumption ledger, not the checkpoint — anyone with read access to the checkpoint store can answer a still-parked prompt. Stated in the docs under its own heading, not buried.
3. AG-UI's Interrupt cannot carry a top-level grant alone. It is z.infer over a closed "strip"-mode InterruptSchema with no grant key, so a client that re-validates silently drops it — quietly unanswerable under "required". The grant is therefore emitted both top-level (on a widened B4AguiInterrupt) and in metadata, which survives the round trip. Read grant, fall back to metadata.grant.
4. The design assumed the mode could ride with the minter. It cannot, without destroying the fail-closed check — see above.
5. The resume pass mints one orphan grant. LangGraph re-executes the node on resume, interruptId is regenerated (it always has been), and a second row is written that is never disclosed and never presented. It is swept by voidOutstanding when the turn settles. Accepted and documented at the park site rather than traded for a dependency on LangGraph's unexported scratchpad.
6. @b4run/web's test suite does not catch an invalid Callout type — only the Next.js prerender does, at build. Cost me a build cycle; worth a cheap guard someday.

Test plan

From the worktree root, one clean sequential run:

• pnpm build → Tasks: 26 successful, 26 total
• pnpm typecheck → Tasks: 54 successful, 54 total
• pnpm lint → Tasks: 29 successful, 29 total (warnings only, all pre-existing — the two in execute-route-core.ts reproduce on the file at HEAD)
• pnpm test → Test Files 1 failed | 557 passed | 22 skipped (580), Tests 1 failed | 6718 passed | 253 skipped (6972)
• node scripts/check-docs.mjs → Docs completeness check passed.

The one failure is @b4run/workspace test/source-bundle.test.ts > "enforces 64 MiB total before encoding or decoding content" — the known memory-pressure flake #742 also hit, in a package this PR does not touch. Alone: pnpm --filter @b4run/workspace test → Test Files 9 passed (9), Tests 195 passed (195).

Real-Postgres lane (Testcontainers postgres:16): B4_TEST_PGSTORAGE=1 pnpm --filter @b4run/postgres-storage test → Test Files 11 passed (11), Tests 117 passed (117), zero skips — including 12 concurrent consumes of one grant yielding exactly one "consumed" and 11 "already_consumed" carrying the winner's decision, and both voidOutstanding shapes.

New coverage: 9 core park-site cases (minting, fail-closed, the ratchet), 3 adapter-injection cases (including that a route param cannot shadow the minter), 12 resume-endpoint cases (replay refused and not re-executed, oracle-indistinguishability asserted by comparing two whole response bodies, the "optional" bypass rule, cancelled-consumes, expiry, voiding, disclosure and re-readability), 7 AG-UI projection cases, 12 SQLite and 15 Postgres store cases.

Formatted only the touched files with pnpm exec biome check --write --config-path packages/config-biome/biome.json <files>. Changeset included. Not released, not merged.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
b4-run	Ignored	Preview	Sep 28, 2026 7:02pm UTC

[github-actions]

Automated approval: this PR received an intelligent (AI) code review. See the review comments on this PR.

[blove]

Rebased onto main at a683816e, which now includes #740, the createAgent migration (#820) and the 0.13.0 release prep.

Conflicts, 13 files:

• Runtime code. In agent-adapter.ts, agui-handler.ts, runtime-fetch-core.ts and execute-route-core.ts, every conflict was an import or option-list union. Main added responseFormat, SystemMessage, MiddlewareAfterHook, the bounded-body helpers and createThreadPermissionsStore. The grant logic itself applied unchanged.
• Docs registration. Main reorganized the nav, so "Approval Grants" now sits after Permissions in the Secure section. Every page-count pin is main's value plus one (journey 64, all docs 80, inventory 93). The count bump was checked against this PR's own +1 diff.
• lastmod. Regenerated for /docs/approval-grants and the reference pages this PR edits.
• Interplay with feat(cli): validate the AG-UI run envelope and close client tools by default #740. On AG-UI the grant travels in the resume entries, not forwardedProps, so feat(cli): validate the AG-UI run envelope and close client tools by default #740's closed default doesn't affect it.

Added:

• packages/cli/test/approval-grants-agent-route.test.ts. The endpoint test seeds grants against a stub graph, and the core test drives a bare graph. So nothing showed that the minter injected into config.configurable still reaches the permission gate inside the agent loop feat(langchain): run agent routes on createAgent; returnDirect ends only on success #820 rebuilt. The new test covers it:
  • A real agent() route parks an approve-gated tool through aimock.
  • pending_interrupts discloses the grant.
  • One resume runs the tool exactly once.
  • A replay gets 409 stale_interrupt and doesn't run it again. (The interrupt is no longer pending, so resolvePendingResume answers before the grant is read. grant_consumed applies only to a still-pending interrupt.)
  • A resume without the grant gets grant_required.
  • Both tests fail when the adapter stops injecting the minter.
• The changeset now uses patch instead of minor, per AGENTS.md's rule for the 0.x fixed group.

Checked on the rebased code:

• sdk 115, core 605, langchain 286, ag-ui 220, sqlite-storage 126, cli 2353, web 979.
• B4_TEST_PGSTORAGE=1 postgres-storage: 117/117 on a real Postgres, including the 12-way concurrent consume.
• Root lint and typecheck, check-docs, seo:lastmod:check.

The decisions listed in the description, Q4 (always is grantable) in particular, are still open for the owner.