@open-everywhere/core 0.1.0

package/agent/tools/request_credential_grant.ts

@@ -0,0 +1,550 @@
+// The production ask path: the one way a model turn raises a credential-grant ask, and the only thing that writes a `credential_grant_ask` row outside a test. 🔴 The turn does NOT block on the owner — a tool call that waits on a human in another conversation is an unbounded stall — so this reports the ask as SENT and finishes. The owner's answer posts back into this conversation later, and the granted tool mounts on the room's NEXT turn.
+// 🔴 It grants NOTHING and takes no approval card of its own: what escapes the room is a DECISION REQUEST, not an act, and a requester-side card would put the owner's consent in front of colleagues one step removed. Factored and pre-registered at module load, with no `approval:` property.
+
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { getConfig } from "../access/config.js";
+import { credentialGrantRefusalNote, resolveGrantOwner } from "../access/credential-grant-ask.js";
+import type { GrantAskWorkerOrigin } from "../access/credential-grant-card.js";
+import { askForCredentialGrant, auditGrant, type GrantAuditStamps } from "../access/credential-grant-flow.js";
+import { resolveRequesterLabel } from "../access/credential-grant-notice.js";
+import { credentialGrantConnectors, domainsAdmitCredentialGrant } from "../access/credential-grant.js";
+import { grantDomainScopeKey } from "../access/credential-grant-scope.js";
+import { requesterThisTurn } from "../access/requester-identity.js";
+import { untrustedIngestedThisTurn } from "../access/taint-signal.js";
+import { preRegisterDynamicEntry } from "../access/window-gated.js";
+import { adoptedOwnAccountAsk } from "../connections/own-account-carriage.js";
+import { ownAccountVendorFor } from "../connections/own-account-vendors.js";
+import { resolveReplyTarget } from "../channels/reply-post.js";
+import { friendlyScopeLabel } from "../approvals/scope-label.js";
+import { grantActionPhrase } from "../access/credential-grant-copy.js";
+import { configuredAgentName } from "../identity/bot-name.js";
+import { currentSessionId, currentTurnId, delegatedBindingUnresolved, delegationRootSessionId, isSubagentChildContext, windowGrainOf, type BindableContext } from "../identity/binding.js";
+import { tryPrincipalKey } from "../identity/principal-key.js";
+import { resolvePartition } from "../memory/partition.js";
+import type { Domain } from "../memory/domain.js";
+
+/**
+ * THE VENDOR TOOL AN ASK NAMES WHEN THE CALLER CANNOT SEE ONE (OPE-1552) — one reviewed entry per
+ * connector in `CREDENTIAL_GRANT_ROLES`, and the thing that makes the ask composable at all.
+ *
+ * 🔴 THE ASK USED TO REQUIRE A NAME NOBODY IN THE ROOM COULD LEARN. `tool` was mandatory and had to
+ * be the vendor's own published name. The single in-agent route to that name is `connection_search`
+ * on the connector, and `assertConnectorGranted` (access/connector-scope.ts) refuses that call
+ * because the connector is ungranted to the surface — which is the exact state the ask exists to
+ * escape. So the ask could be composed by a guess and by nothing else, and the field's own text
+ * forbade the guess. Measured on deploy #177, 2026-09-08 00:13Z–00:18Z: three S-DISCORD-GRANT phase-1
+ * drives, three delegated workers, each one calling `connection_search`, reading the ungranted
+ * refusal, and reporting "the ask did not go out — refused" without ever entering this verb. Zero
+ * `grant.asked` rows and zero `grant.refused` rows for three drives that each raised nothing.
+ *
+ * WHAT THIS DOES AND DOES NOT DECIDE. It supplies a NAME, never a permission: the owner still reads
+ * the card and decides, the name is still checked against their live connection when they approve,
+ * and the borrow still spends their credential and nothing else. A caller that CAN see the vendor's
+ * tools still names one and wins — this is the floor under a caller that cannot.
+ *
+ * 🔴 EVERY ADMITTED CONNECTOR NEEDS A ROW HERE. `scripts/credential-grant-ask-test.ts` §9 reds when
+ * `credentialGrantConnectors()` names a connector this map does not, so a connector added to
+ * `CREDENTIAL_GRANT_ROLES` cannot bring the dead end back with it.
+ */
+const GRANT_DEFAULT_TOOLS: Readonly<Record<string, string>> = {
+  // Notion's page read on `mcp.notion.com`. 🔴 IT IS HUMAN-REVIEWED AND UNVERIFIABLE OFFLINE —
+  // nothing in this tree reads Notion's published catalogue, so no suite can tell you this name is
+  // still right. A name the owner's account does not publish is caught at APPROVAL, where
+  // `readApprovedToolSchema` answers `tool_absent` and the ask closes refused on their card. Two
+  // in-tree users drive the same spelling (scripts/grant-mcp-transport-test.ts,
+  // scripts/credential-grant-ask-test.ts), and one live ask carried it on 2026-09-07. A read is also
+  // the narrowest thing to default to: an owner who meant to lend more can still be asked for it by
+  // name, and an owner asked for this one is never asked for a write by accident.
+  notion: "notion-fetch",
+};
+
+/** The vendor tool an ask names for `connector` when the caller named none, or `undefined` when this
+ *  tree has no reviewed default. `undefined` refuses the ask — an invented name would put a string
+ *  the owner cannot judge on their card. */
+export function defaultGrantTool(connector: string): string | undefined {
+  return Object.prototype.hasOwnProperty.call(GRANT_DEFAULT_TOOLS, connector) ? GRANT_DEFAULT_TOOLS[connector] : undefined;
+}
+
+/** Domains, fail-soft — the shape every mount resolver takes. An empty list makes every gate below
+ *  fail closed, which is the honest direction: no readable domain means no provable declaration. */
+function safeDomains(): readonly Domain[] {
+  try {
+    return getConfig().loadDomains();
+  } catch {
+    return [];
+  }
+}
+
+/** The domains THIS surface resolves into, fail-soft. The grant role is a per-domain declaration, so
+ *  reading every domain in the deployment would admit a grant a different room's operator declared. */
+function domainsForCtx(ctx: BindableContext): readonly Domain[] {
+  try {
+    const p = resolvePartition(ctx);
+    const names = new Set(getConfig().domainsForSurface({ surface: p.surface ?? p.surfaceKey, workspaceKey: p.workspaceKey }));
+    return safeDomains().filter((d) => names.has(d.name));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Which seat may raise an ask: a DELEGATED WORKER, and the domain must declare at least one admissible connector on its own `credentialGrants` field. A conversational seat raises none — it hands the job to a worker (OPE-2023).
+ * 🔴 The GRANT is still the CONVERSATION'S — the scope key is the root seat's session (the room's DOMAIN for a `standing` answer, OPE-1950), never the worker's own one-shot session, which ends before the owner taps anything. So this decides WHO MAY ASK and nothing about which conversation may spend. A task-grain session that is nobody's child mounts nothing, and an unattended fire's delegated child names no verified requester, so its ask is refused before any row is written.
+ */
+export function requestCredentialGrantMount(ctx: BindableContext): boolean {
+  try {
+    if (!mayRaiseGrantAsk(ctx)) {
+      noteMountRefused(ctx, "grain");
+      return false;
+    }
+  } catch {
+    noteMountRefused(ctx, "grain");
+    return false;
+  }
+  const domains = domainsForCtx(ctx);
+  if (domains.length === 0) {
+    // A delegated child that cannot read its dispatch binding binds to the `subagent/…/unresolved`
+    // sentinel, which resolves no domain. The row names that class apart from a real config gap
+    // (OPE-2106). The label changes; the mount verdict does not.
+    const unresolved = delegatedBindingUnresolved(ctx);
+    if (unresolved !== undefined) noteMountRefused(ctx, "binding-unresolved", { slot: unresolved });
+    else noteMountRefused(ctx, "no-domain");
+    return false;
+  }
+  // 🔴 THE CONNECTOR LIST IS THE REVIEWED CONSTANT `CREDENTIAL_GRANT_ROLES` (OPE-1136). A grant needs
+  // nothing registered per operation — it lends whatever tool the owner's connection publishes — so
+  // the admissible set is the reviewed (connector, personal credential) list and nothing else.
+  for (const connector of credentialGrantConnectors()) if (domainsAdmitCredentialGrant(domains, connector)) return true;
+  noteMountRefused(ctx, "no-declaration");
+  return false;
+}
+
+/** Why the ask verb did not mount. One value per refusal cause in {@link requestCredentialGrantMount}. */
+type GrantMountRefusal = "grain" | "binding-unresolved" | "no-domain" | "no-declaration";
+
+/**
+ * One `grant.mount_refused` row per session per cause — the dedupe shape `auditGateOnce`
+ * (`access/window-gated.ts`) uses, for the same reason: a resolver can run more than once for one
+ * session, and an operator reading the log wants the fact, not a repeat per resolution.
+ *
+ * 🔴 IT IS A PER-PROCESS SET, so a session that survives a deploy files the row again under the new
+ * build. That is the honest direction — a new process knows nothing about what the old one wrote.
+ */
+const auditedMountRefusals = new Set<string>();
+
+/** TEST SEAM: reset the once-per-session dedupe (unit tests mint many synthetic sessions). */
+export function _resetGrantMountAuditForTest(): void {
+  auditedMountRefusals.clear();
+}
+
+/** The floated write, kept so a test can AWAIT the row instead of racing it. The mount itself never
+ *  reads this — it is a handle on work the mount deliberately does not wait for. */
+let lastMountAudit: Promise<void> = Promise.resolve();
+
+/** TEST SEAM: settles once the row this mount floated has been written (or has failed). */
+export function _grantMountAuditSettled(): Promise<void> {
+  return lastMountAudit;
+}
+
+/**
+ * THE NEGATIVE OBSERVABLE ON THE MOUNT (OPE-1916). The three early returns above used to leave
+ * NOTHING behind: a deployment whose ask verb never mounted read exactly like one whose model chose
+ * not to call it, and the two need different fixes. Best-effort by contract — the row is floated and
+ * every failure is swallowed, because the mount must never depend on the audit store being reachable.
+ */
+function noteMountRefused(ctx: BindableContext, reason: GrantMountRefusal, extra: Readonly<Record<string, string>> = {}): void {
+  try {
+    const p = safePartitionOf(ctx);
+    if (p === undefined) return;
+    const sessionId = ctx.session?.id ?? p.surfaceKey;
+    const key = `${sessionId}|${reason}`;
+    if (auditedMountRefusals.has(key)) return;
+    auditedMountRefusals.add(key);
+    let grain = "unknown";
+    try {
+      grain = windowGrainOf(ctx);
+    } catch {
+      // The grain is a LABEL on this row, never its trigger — an unreadable grain must not drop it.
+    }
+    lastMountAudit = auditGrant(stampsOf(p), "grant.mount_refused", undefined, { grain, reason, surfaceKey: p.surfaceKey, ...extra }).catch(() => {
+      // Best-effort: a lost row never throws into the mount it was recording.
+    });
+  } catch {
+    // Same contract: evidence is best-effort, and the withholding has already happened.
+  }
+}
+
+/** The partition, fail-soft. A partition that cannot be read leaves NO row rather than throwing into
+ *  the refusal it was recording. */
+function safePartitionOf(ctx: BindableContext): ReturnType<typeof resolvePartition> | undefined {
+  try {
+    return resolvePartition(ctx);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The four audit columns every row on this plane is stamped with. */
+function stampsOf(p: ReturnType<typeof resolvePartition>): GrantAuditStamps {
+  return { org: p.org, platform: p.platform, workspace: p.workspace, ...(p.surface === undefined ? {} : { surface: p.surface }) };
+}
+
+/** One `grant.refused` row for a refusal the VERB decides before the flow is ever entered. Best-effort
+ *  like every other row on this plane: the refusal the model reads never depends on it landing. */
+async function auditVerbRefusal(ctx: BindableContext, gate: string, detail: Readonly<Record<string, unknown>>, principalId?: string): Promise<void> {
+  const p = safePartitionOf(ctx);
+  if (p === undefined) return;
+  try {
+    await auditGrant(stampsOf(p), "grant.refused", principalId, { gate, ...detail });
+  } catch {
+    // Evidence is best-effort — a lost row must never turn a clean refusal into a thrown call.
+  }
+}
+
+/**
+ * The seat-shape half of the mount, and the same test the execute path runs. A DELEGATED WORKER, and nothing else.
+ * 🔴 THE CONVERSATIONAL SEAT IS NOT HERE (OPE-2023, Tommy's ruling of 2026-09-20). A seat asks a worker for access to Notion exactly as it asks a worker for any other job: it holds the talking verbs and it delegates. The worker has the full kit and a fresh context to decide how, so the one verb that reaches a person's own account belongs on the same side of the seam as the connector calls it exists to unblock.
+ * 🔴 It asks "is this a delegated worker", not "can it name its seat": `session.parent` reaches TOOL and HOOK contexts but NOT a dynamic-resolver context (eve's `buildResolveContext` builds `session` from the id and the auth bag alone), and the mount IS one — so a predicate demanding a nameable root here would refuse every worker at mount time. The nameable-root question is `grantScopeKey`'s, at execute.
+ */
+export function mayRaiseGrantAsk(ctx: BindableContext): boolean {
+  return isSubagentChildContext(ctx);
+}
+
+/**
+ * The SESSION a grant raised here is scoped to — the root SEAT's, never the worker's. It is what a `once` or `session` grant binds to; a `standing` one binds to `grantDomainScopeKey`'s domain key instead (OPE-1950), and the ask records both because the owner's card decides the mode. `currentSessionId` is this session's own durable id, so inside a one-shot worker it names a run that ends minutes before the owner taps anything, and their approval would mount into nothing.
+ * 🔴 A child never falls back to its own session id, and the test for "child" is the parent bag's PRESENCE rather than what it names: eve has renamed that field before, and presence is the one test that does not move with it. The `""` arm is a fail-closed guard against a shape eve does not currently produce, never a floor that fires.
+ */
+export function grantScopeKey(ctx: BindableContext): string {
+  const root = delegationRootSessionId(ctx);
+  if (root !== undefined) return root;
+  if (ctx.session?.parent !== undefined || isSubagentChildContext(ctx)) return "";
+  return currentSessionId(ctx) ?? "";
+}
+
+/** What the owner's card calls the agent when the deployment configures no `identity.name`. A GENERIC
+ *  NOUN PHRASE, never the shipped brand string: the card's first line is where the owner reads WHO is
+ *  asking, and `DEFAULT_AGENT_FULL_NAME` would put a lowercase product name where a name belongs. */
+export const UNNAMED_SEAT_LABEL = "the assistant";
+
+/** Exported for the test pack ALONE. The mount below is the only production reference — the entry is
+ *  pre-registered at module load, exactly like `dm_person`'s. */
+export const requestCredentialGrantEntry = defineTool({
+  description:
+    "Ask a named person to lend THIS conversation ONE tool from their own connector account — for " +
+    "example one Notion page-reading tool, fixed to one page. They get a card in their own direct " +
+    "messages and answer there; you get nothing back but confirmation that they were asked. Say in " +
+    "the room that the ask went out, then carry on with something else; do not wait for an answer and " +
+    "do not ask twice. When they approve, the grant lands on this conversation. The conversation " +
+    "reaches the tool through the next task it hands work to, and the answer is posted here. This " +
+    "grants nothing by itself. " +
+    "🔴 ONE THING NEEDS THIS ASK: a PERSON'S OWN ACCOUNT, and only when a person here asked for it to be lent. " +
+    "A connector NOBODY HAS BOUND HERE is a reason to SUGGEST this road, never to raise the ask yourself — name " +
+    "what the org's own road cannot reach, say they can lend their own access, once, and stop. " +
+    "Org work runs on the ORG'S OWN ROAD — the Notion REST skill on the team integration " +
+    "key, or a connector already bound to this conversation — and you reach either by delegating the work to a " +
+    "task, which is where those tools live. Never ask a person to lend their own access for work the org's own " +
+    "road already does. " +
+    "There is no TOOL NAME to look up first. A connector call that fails with " +
+    '"not granted to this surface" is a reason to SUGGEST this road too, on the same terms; it is not this ask being refused, and it never becomes one. Say an ask ' +
+    "went out, or was refused, only from what THIS tool hands back.",
+  inputSchema: z.object({
+    connector: z
+      .string()
+      .min(1)
+      .describe(`The vendor whose account would be spent. One of: ${credentialGrantConnectors().join(", ") || "(none — this deployment admits no credential grants)"}.`),
+    frozen_args: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe(
+        "The arguments to FIX for this grant, as a JSON object — normally the one thing to read, such " +
+          'as {"id": "<page id>"}. Anything you fix here you cannot change later: the granted tool shows ' +
+          "each fixed argument with its one allowed value, and a call that sends anything else is refused. " +
+          "Omit it only when the grant is genuinely meant to let this conversation choose every argument, " +
+          "which is a much wider ask and the owner will see it described that way.",
+      ),
+    owner: z
+      .string()
+      .min(1)
+      .describe(
+        "The person whose credential would be spent. Either their full principal key (for example " +
+          '"slack/T0AB1CD2E/U123ABC") or, for somebody on this same surface, their bare platform member id.',
+      ),
+    purpose: z
+      .string()
+      .min(1)
+      .describe("Why you need it, in one sentence. They read this to decide, so say what you will do with it, not what you want."),
+    requested_mode: z
+      .enum(["once", "session", "standing"])
+      .describe("What to ask for: one single call, this whole conversation, or a standing grant with an expiry. They choose the final answer."),
+    target_label: z
+      .string()
+      .min(1)
+      .describe(
+        'What the thing you want to reach is CALLED, in plain words — for example "Quarterly report". It ' +
+          "names the granted tool and it is what the owner reads on their card, so use the label a person " +
+          "would recognise, not an id.",
+      ),
+    tool: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "OPTIONAL, and normally OMIT IT. The vendor's own tool name, spelled exactly as their " +
+          "connection publishes it (for example `notion-fetch`). Name one only if you have already " +
+          "seen it. 🔴 Do NOT go looking for it first: this conversation is not granted the " +
+          "connector — that is why you are asking — so listing its tools is refused by design, and " +
+          "that refusal is about the LISTING, never about this ask. Omitted, the ask names the " +
+          "connector's default tool, which the owner sees on their card and can decline.",
+      ),
+  }),
+  outputSchema: z.object({
+    asked: z.boolean(),
+    askId: z.string().optional(),
+    owner: z.string().optional(),
+    message: z.string(),
+  }),
+  async execute(input, ctx) {
+    const c = ctx as BindableContext;
+    // Taint FIRST, ahead of every other check: a turn that has ingested external content must not compose a request for a person's credential, so this refuses before the ask is even shaped and before anything about the named owner is looked up.
+    // The refusal lives here rather than in the consequence registry because an `open` row has no card for the registry's `taint` column to floor it at.
+    if (untrustedIngestedThisTurn()) {
+      return {
+        asked: false,
+        message:
+          "Refused: this turn has already read external content, so it may not ask anyone for their credential. " +
+          "The purpose line is the one thing the owner reads to judge the ask, and fetched content must never author it. " +
+          "Ask again in a fresh turn that has read nothing external.",
+      };
+    }
+    // 🔴 THE CONNECTOR IS CHECKED AGAINST THE REVIEWED LIST BEFORE ANYTHING IS LOOKED UP. It decides
+    // which personal credential a borrow would spend, so a connector this tree admits no grant role
+    // for has no credential to lend and the refusal says so by name.
+    const known = credentialGrantConnectors();
+    if (!known.includes(input.connector)) {
+      return {
+        asked: false,
+        message:
+          `Refused: "${input.connector}" is not a connector this deployment lends credentials for. ` +
+          (known.length > 0 ? `It admits: ${known.join(", ")}.` : "It admits none, so nothing can be granted here."),
+      };
+    }
+    // THE NAME THE CARD CARRIES (OPE-1552). A caller that has seen the vendor's own tool name wins;
+    // one that has not gets the connector's default tool, because the only way to LOOK the name up
+    // is the connector this conversation is asking to borrow. A connector with no reviewed default
+    // refuses rather than inventing a string the owner cannot judge — unreachable for an admitted
+    // connector while the coverage leg in `credential-grant-ask-test.ts` §9 holds.
+    const mcpTool = input.tool?.trim() || defaultGrantTool(input.connector);
+    if (mcpTool === undefined) {
+      // 🔴 A ROW, NOT ONLY A SENTENCE (OPE-1916). The model reads the refusal; an operator reading the
+      // audit log used to see nothing at all, so a connector with no reviewed default was invisible.
+      await auditVerbRefusal(c, "no_default_tool", { connector: input.connector });
+      return {
+        asked: false,
+        message:
+          `Refused: this deployment has no default tool for "${input.connector}", so an ask must name ` +
+          "the vendor's own tool name in `tool`.",
+      };
+    }
+    // MODEL-AUTHORED, AND IT BECOMES THE FENCE'S PIN. It is refused here only for being unusable as
+    // JSON; whether the vendor tool actually takes these keys is decided against the LIVE connection
+    // when the owner approves, which is the only place that can answer it.
+    const frozenArgs = input.frozen_args ?? {};
+    const frozenProblem = jsonObjectProblem(frozenArgs);
+    if (frozenProblem !== undefined) {
+      return { asked: false, message: `Refused: the arguments to fix are not something a grant can hold — ${frozenProblem}. Send plain JSON values only.` };
+    }
+    // The execute-time copy of the mount's seat-shape floor, running before any partition or domain read because it needs nothing but the ctx.
+    // The mount resolves once at `session.started`; this runs on the call, so a replayed entry cannot raise an ask from a session no person is in.
+    if (!mayRaiseGrantAsk(c)) {
+      return {
+        asked: false,
+        message:
+          "Refused: only a task delegated from a conversation may raise this ask, and this session is not one. " +
+          "Hand the work to a task; it asks on the conversation's behalf, and the grant binds to the conversation rather than to the task.",
+      };
+    }
+    const p = resolvePartition(c);
+    const domains = domainsForCtx(c);
+    const scopeKey = grantScopeKey(c);
+    // OPE-1950: the room's domain-shaped seat key, recorded on the ask beside the session one. A
+    // STANDING answer binds to it; every other mode ignores it. `undefined` in a room whose domain
+    // does not window — and there the STANDING arm is not offered and is refused if tapped
+    // (`standing_unavailable`, OPE-2160); the exact-session rule governs only what the seat may READ.
+    const domainScopeKey = grantDomainScopeKey(c);
+    if (scopeKey.length === 0) {
+      await auditVerbRefusal(c, "no_scope_key", { connector: input.connector });
+      return { asked: false, message: "Refused: this conversation has no session id, so there is no chat for a grant to be scoped to." };
+    }
+    // THE ATTRIBUTION (OPE-1343). Present only inside a delegated worker, where "who is asking" must
+    // name the agent the owner knows rather than a shell they have never heard of. The name is the
+    // deployment's own, resolved here so the card renderer stays pure.
+    const rootSessionId = delegationRootSessionId(c);
+    const workerOrigin: GrantAskWorkerOrigin | undefined =
+      rootSessionId === undefined ? undefined : { seatLabel: configuredAgentName() ?? UNNAMED_SEAT_LABEL };
+    // The GRANTEE IS THE CHAT, and the requester is who gets recorded as having asked. The key is
+    // composed through the SAME composer the owner half uses — a second spelling would record a
+    // requester the audit row cannot join.
+    const verdict = requesterThisTurn(currentTurnId(c));
+    const requesterPrincipalId = verdict.kind === "requester" ? tryPrincipalKey(p.platform, p.workspace, verdict.principalId) : undefined;
+
+    const owner = await resolveGrantOwner(input.owner, p.platform, p.workspace);
+    if ("refusal" in owner) {
+      // 🔴 THE OWNER STRING STAYS OFF THE ROW. It is model-authored and unresolved, so writing it back
+      // would put an unverified person-shaped string in the audit log. The gate name is the fact.
+      // The session keys go on the row (OPE-2063), so a session wait and an operator can find it.
+      await auditVerbRefusal(
+        c,
+        "owner_unresolved",
+        { connector: input.connector, scopeKey, ...(domainScopeKey === undefined ? {} : { domainScopeKey }) },
+        requesterPrincipalId,
+      );
+      return { asked: false, message: owner.refusal };
+    }
+
+    // The card names the REQUESTER, so the owner can judge who is asking. It resolves through the
+    // same account-display-name plane every other notice reads, and it never invents a name.
+    // 🔴 NO PRINCIPAL-KEY FALLBACK (OPE-1589). The card used to print the key when no display name
+    // resolved, which is how an owner read "discord/9000000000000000003 asks to use your notion
+    // credential". An empty label makes `grantRequesterPhrase` say this deployment cannot name them;
+    // the `grant.asked` audit row still carries the key for anyone who has to join by it.
+    const requesterLabel = requesterPrincipalId === undefined ? "an unverified caller" : ((await resolveRequesterLabel(requesterPrincipalId).catch(() => undefined)) ?? "");
+    const requesterTarget = replyTargetJson(c);
+    // THE ROOM'S FRIENDLY NAME, for the card alone. Fail-open by contract (`friendlyScopeLabel` never
+    // throws and answers undefined on any lookup failure), so a card without one says "that
+    // conversation" and the ask is unaffected.
+    const conversationLabel = await grantConversationLabel(p.platform, p.workspace, p.surface);
+    // WHO IS READING A REFUSAL. The owner reads "you"; anybody else reads the owner's name. Decided
+    // from the two PRINCIPAL KEYS, never from prose — see `access/credential-grant-copy.ts`.
+    const audience = requesterPrincipalId !== undefined && requesterPrincipalId === owner.principalId ? "owner" : "seat";
+
+    // OPE-1978, MEASUREMENT ONLY. The prompt owns the rule (a seat raises an ask only on the person's
+    // word, and otherwise suggests the road once); this column is how an operator reads whether the
+    // prompt is holding. It branches nothing here — no card, no budget, no refusal turns on it.
+    // 🔴 ONE GRAMMAR, REUSED. `adoptedOwnAccountAsk` reads the stamp the own-account hook wrote at the
+    // SEAT from this person's delivery, so a DELEGATED WORKER answers from the same words the seat read
+    // rather than from its brief. A second grammar written here would be a second thing to keep true.
+    const explicit = adoptedOwnAccountAsk(c, [ownAccountVendorFor(input.connector)]) !== undefined;
+
+    const outcome = await askForCredentialGrant({
+      connector: input.connector,
+      domainGrantsConnector: domainsAdmitCredentialGrant(domains, input.connector),
+      explicit,
+      frozenArgs: frozenArgs,
+      mcpTool,
+      nowMs: Date.now(),
+      org: p.org,
+      ownerHandle: owner.handle,
+      ownerNativeId: owner.nativeId,
+      ownerPlatform: owner.platform,
+      ownerPrincipalId: owner.principalId,
+      platform: p.platform,
+      purpose: input.purpose,
+      requestedMode: input.requested_mode,
+      requesterLabel,
+      requesterPrincipalId,
+      // PINNED FROM THE SESSION BINDING, never from model input. This is the address the owner's
+      // answer comes back to; a model-supplied one would let a turn route another person's private
+      // decision into a room of its choosing. Absent on a surface with no mid-turn post arm.
+      ...(requesterTarget === undefined ? {} : { requesterTarget }),
+      ...(conversationLabel === undefined ? {} : { conversationLabel }),
+      scopeKey,
+      ...(domainScopeKey === undefined ? {} : { domainScopeKey }),
+      ...(p.surface === undefined ? {} : { surface: p.surface }),
+      targetLabel: input.target_label,
+      ...(workerOrigin === undefined ? {} : { workerOrigin }),
+      workspace: p.workspace,
+    });
+
+    if (!outcome.sent) {
+      return {
+        asked: false,
+        message: credentialGrantRefusalNote(input.connector, outcome.reason, {
+          audience,
+          conversationLabel,
+          expiresAt: outcome.liveGrant?.expiresAt,
+          mcpTool: outcome.liveGrant?.mcpTool,
+          nowMs: Date.now(),
+          ownerLabel: owner.displayName,
+        }),
+      };
+    }
+    // 🔴 IT NAMES NO MOUNTED TOOL (OPE-1589). The seat relays this sentence into the room, and
+    // `grant__<owner id>_…` is the string that put a person's own platform id on Tommy's screen. The
+    // NAME is unchanged on the row and the granted tool still mounts under it — a WORKER of this
+    // conversation meets it in its own tool list (OPE-2023, `tools/grant_tools.ts`
+    // `resolveGrantMount`), which is where a tool name belongs.
+    const who = owner.displayName ?? "them";
+    return {
+      askId: outcome.askId,
+      asked: true,
+      message:
+        `Asked ${who}. The card is in their direct messages and only they can answer it. ` +
+        `If they approve, this conversation reaches a tool that can ${grantActionPhrase(input.connector, mcpTool)} through the next task it hands work to. ` +
+        `Tell the room the ask went out and carry on — nothing is granted yet, you will not be told here the moment they answer, ` +
+        `and asking again for the same thing is refused.`,
+      owner: who,
+    };
+  },
+});
+preRegisterDynamicEntry("request_credential_grant", "_single", requestCredentialGrantEntry);
+
+/**
+ * Why `value` is not a set of arguments a grant can freeze, or undefined when it is fine. A JSON check, not a policy one — whether the vendor tool actually takes these keys is decided against the LIVE connection when the owner approves.
+ * The row canonicalises the arguments on the way to the store, so a value JSON cannot hold would throw inside the insert and read as a store error rather than a bad ask; refusing here turns the same fact into a sentence the model can act on.
+ */
+function jsonObjectProblem(value: unknown, path = "the fixed arguments", depth = 0): string | undefined {
+  if (depth > 32) return `${path} nests too deeply`;
+  if (value === null || typeof value === "string" || typeof value === "boolean") return undefined;
+  if (typeof value === "number") return Number.isFinite(value) ? undefined : `${path} is ${String(value)}, which JSON cannot hold`;
+  if (Array.isArray(value)) {
+    for (const [i, item] of value.entries()) {
+      const bad = jsonObjectProblem(item, `${path}[${String(i)}]`, depth + 1);
+      if (bad !== undefined) return bad;
+    }
+    return undefined;
+  }
+  if (typeof value !== "object") return `${path} is a ${typeof value}, which JSON cannot hold`;
+  const proto = Object.getPrototypeOf(value) as unknown;
+  if (proto !== Object.prototype && proto !== null) return `${path} is not a plain JSON object`;
+  for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+    // 🔴 AN `undefined` PROPERTY IS A LOST NARROWING, not a tidy-up. `JSON.stringify` drops the key
+    // silently, so `{ id: undefined }` would freeze `{}` — and `{}` freezes nothing.
+    if (v === undefined) return `${path}.${key} has no value`;
+    const bad = jsonObjectProblem(v, `${path}.${key}`, depth + 1);
+    if (bad !== undefined) return bad;
+  }
+  return undefined;
+}
+
+/**
+ * The requesting room's FRIENDLY LABEL for the owner's card (OPE-1589) — `#proj-chat`, or
+ * `#proj-chat · thread "Q3 planning"` — or `undefined` when this deployment cannot name it.
+ *
+ * It spends the approval plane's own resolver (`approvals/scope-label.ts`), which is where every
+ * per-platform name lookup already lives. A surface key is `<platform>/<workspace>/<surface>` and a
+ * key with any empty segment is malformed, so the three parts are checked before one is composed.
+ */
+async function grantConversationLabel(platform: string, workspace: string, surface: string | undefined): Promise<string | undefined> {
+  if (surface === undefined || surface.length === 0 || platform.length === 0 || workspace.length === 0) return undefined;
+  return await friendlyScopeLabel(`${platform}/${workspace}/${surface}`);
+}
+
+/** The requester's own reply target, as the JSON the ask row pins. `undefined` on a surface with no
+ *  mid-turn post arm — an honest "the answer cannot be reported back here", never a guessed room. */
+function replyTargetJson(ctx: BindableContext): string | undefined {
+  try {
+    const target = resolveReplyTarget(ctx);
+    return target === null ? undefined : JSON.stringify(target);
+  } catch {
+    return undefined;
+  }
+}
+
+export default defineDynamic({
+  events: {
+    // `session.started` ONLY: a session's domains and grain cannot change mid-session, so resolving once is correct and cheaper.
+    // The GRANTED tools are the ones that need a per-turn arm, because an owner's approval lands mid-session; this verb's own availability does not move.
+    "session.started": (_event, ctx) => (requestCredentialGrantMount(ctx as BindableContext) ? requestCredentialGrantEntry : null),
+  },
+});