granttap-mcp 0.6.10 → 0.7.1

package/README.md

@@ -34,11 +34,65 @@ end-to-end encrypted.
 
 - Primary: Claude Code and Codex.
 - Beta: Cursor.
-- Experimental where available: GitHub Copilot CLI and Grok Build.
+- Experimental where available: Grok Build.
 
 GrantTap reports the depth each provider actually exposes. Visibility does not
 imply deterministic remote blocking or full mobile continuation.
 
+## Project Mesh and task handoff
+
+Project Mesh adds stable Project and Task identity above provider-native
+sessions. A Task can retain its `taskId` across multiple executions, agents,
+and computers while each native session remains intact.
+
+Agents publish bounded progress, dependency, question, answer, claim, conflict,
+and completion events through the existing `notify` tool, and read state from a
+Mesh resource. Full transcripts and hidden reasoning are never mesh payloads.
+Claims have TTLs; a colliding claim is rejected before it is recorded so agents
+can choose different work or contact the owner before escalating to Needs You.
+
+Both directions are scoped to the calling execution. The provider hook already
+runs inside the agent's own session and sees the exact call, so GrantTap
+attributes every `notify` to the session that really made it and publishes the
+event only for that execution — a model that learned another session's id
+cannot act in its name. `granttap://mesh/current` therefore carries no Project
+data: an attributed call returns this execution's opaque
+`granttap://mesh/<capability>` URI, and only that URI serves its Project, Task,
+owners, claims, dependencies, and relevant events. Ownership transfer stays out
+of the tool surface entirely: `HANDOFF_ACCEPTED` and `HANDOFF_REJECTED` are
+decided by the runtime after receipt verification.
+
+The first executable handoff path is Claude Code ↔ Codex across linked
+computers. GrantTap builds a bounded Task Capsule from explicit task/git facts,
+requires local phone authorization, creates a separate target branch/worktree,
+starts the target execution, and returns a receipt bound to the exact capsule.
+Cursor and Grok Build use the same provider-neutral schema and discovery model;
+unsupported remote-start paths fail closed instead of claiming parity.
+
+A capsule carries facts, not files. A handoff from a checkout with uncommitted
+changes is refused — "This task has uncommitted changes. Commit or checkpoint
+them before moving the task." — instead of silently continuing the Task from
+committed state and leaving that work behind. The destination is refused just
+as explicitly when the named commit is not on its computer, or when the
+capsule's own resource claims overlap another execution's; GrantTap never
+pushes or fetches on its own.
+
+### Grok Bot as a scoped Mesh participant
+
+Grok Bot is a persistent agent, not a coding-agent integration. The iPhone
+issues a one-time encrypted Mesh Invite scoped to the Projects you select, and
+the invite is redeemed on the trusted CLI:
+
+```bash
+granttap mesh connect <one-time-invite>
+```
+
+Grok Bot then runs `granttap internal mesh-mcp`, a separate scoped MCP server
+that exposes only the twelve task-scoped Mesh operations. It cannot create
+invites, change the relay, expand Project scope, or reach `setup`; revoking the
+endpoint from the iPhone stops new Mesh operations immediately while local Task
+history stays on the device.
+
 ## Install
 
 ```bash
@@ -58,6 +112,7 @@ granttap setup
 granttap status [--json]
 granttap connect [--relay <wss-url>]
 granttap reset [--yes]
+granttap mesh connect <one-time-invite>
 ```
 
 `connect` reuses a valid pairing. If none exists, it creates a one-time QR.
@@ -89,6 +144,10 @@ MCP `connect` accepts no custom routing, replacement, or key-rotation input.
 Setup is CLI-only because it changes provider configuration and must not be
 available to a model through prompt injection.
 
+`notify` may alternatively carry one bounded task-scoped Mesh event. This does
+not add a fifth MCP tool or grant any global setup capability, and it publishes
+only for the execution whose provider hook attributed the call.
+
 Provider-native approvals and mobile continuation require the matching local
 adapter. MCP registration alone is never reported as proof that an integration
 is ready.
@@ -141,10 +200,19 @@ npm install
 npm run typecheck
 npm test
 npm run package:allowlist
+npm run test:coverage   # macOS only — see below
 ```
 
+`npm test` runs everywhere. Both suites run with an isolated `HOME`, so a
+developer's own Claude/Codex/Cursor data can never inflate a local result: the
+numbers on this machine and in CI are the same. The coverage contract is
+measured on macOS because the background helper, the Cursor OAuth service, and
+the installer only execute there, so a Linux percentage understates real
+runtime coverage. CI runs the cross-platform suite on Linux and the coverage
+gate on macOS, and `npm publish` enforces the same gate through
+`prepublishOnly`.
+
 Do not publish from a dirty checkout or before the package allowlist, tests,
 typecheck, and release checks pass.
 
-GrantTap is not affiliated with Anthropic, OpenAI, Apple, Microsoft, Anysphere,
-GitHub, or xAI.
+GrantTap is not affiliated with Anthropic, OpenAI, Apple, Anysphere, or xAI.

package/SECURITY.md

@@ -27,6 +27,9 @@ GrantTap does not send them to the relay.
   transfer key. The relay receives the mailbox ID and ciphertext, not the key.
 - Each attached task has an independent 256-bit task key. One task key cannot
   decrypt another task.
+- Project Mesh snapshots have independent project keys. Cross-computer events
+  remain under their Task key, and a linked destination receives either key
+  only through an explicit phone-mediated route.
 - Task keys travel only inside the authenticated device channel and are stored
   in device-protected storage.
 - Native phone/watch payloads remain authenticated ciphertext across the
@@ -46,6 +49,24 @@ whose independent keys were granted to it. The protection is against relay,
 database/network compromise, other pairings, and disclosure of a different
 task key—not against an endpoint already authorized for that task.
 
+Project Mesh reads and writes are scoped to one execution. The MCP server
+cannot see which agent called it, so the provider hook — which runs inside the
+session and receives the exact arguments — records a single-use attribution for
+that call, and the runtime publishes the event for that session only. A model
+that learned another execution's session id, Project, or Task cannot publish in
+its name, and the unscoped `granttap://mesh/current` URI carries no Project
+data at all. The opaque capability returned to an attributed caller names one
+Project, Task, session and provider, expires, and never authorizes ownership
+transfer.
+
+Task Capsules are strict, bounded schemas containing goal, explicit status,
+repository/commit facts, changed-file names, tests, dependencies, claims,
+remaining work, and explicit decisions. Unknown fields are rejected; hidden
+reasoning and transcript replication are outside the contract. Handoff
+acceptance includes a SHA-256 receipt over a canonical capsule and the source,
+target, Task identity, and acceptance time. Stale claims expire, replayed event
+IDs are ignored, and destination routing is explicit.
+
 ## Runtime controls
 
 Provider hooks enforce policy on the computer. Global provider deny always
@@ -57,5 +78,14 @@ background services. The public MCP server can only connect an existing or new
 phone pairing, notify, and ask bounded questions; it cannot reconfigure the
 machine or select a custom relay.
 
+A Grok Bot endpoint is a separate scoped identity. Its one-time invite is
+created only on the iPhone, stored on the relay as ciphertext, redeemed only by
+the trusted `granttap mesh connect` CLI, and written to disk with `0600`
+permissions. Its MCP server exposes only task-scoped Mesh operations bound to
+one credential: every call re-checks endpoint, credential, policy revision,
+expiry, actor, Project scope, and operation, and a revoked or disabled endpoint
+fails closed. Invite creation, actor enablement, Project scope, and revocation
+stay in the iPhone UI and the trusted CLI, never in a model-callable tool.
+
 Relay vulnerabilities should be reported through the
 [GrantTap relay advisory form](https://github.com/sergii-ziborov/granttap-relay/security/advisories/new).

package/apps/bridge/src/bin/claude-hook.ts

@@ -18,10 +18,12 @@ import {
   autoAcceptLevelFor,
   blockedSessionCapability,
   isGatingSkipped,
+  isProviderEnabled,
   loadConfig,
   machineConfigPath,
   shouldAutoAcceptTool,
 } from "../config";
+import { recordAttributedCall } from "../mesh/call-scope";
 import { classifyAction } from "../policy";
 
 async function readStdin(): Promise<string> {
@@ -48,6 +50,18 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (!isProviderEnabled("claude")) return;
+
+  // Attribute this exact GrantTap call to the session that made it. The MCP
+  // server cannot see the caller, so without this a model could publish Mesh
+  // events in another execution's name.
+  recordAttributedCall({
+    provider: "claude",
+    sessionId: input.session_id,
+    toolName: input.tool_name,
+    args: input.tool_input,
+  });
+
   const blocked = blockedSessionCapability(
     input.session_id,
     input.tool_name,
@@ -69,19 +83,6 @@ async function main(): Promise<void> {
   // Claude already granted this chat unconditional tool access. GrantTap's
   // explicit MCP/skill/CLI blocks above still win, but phone approval must not
   // re-prompt a call Claude is intentionally running in bypass mode.
-  // TEMPORARY DIAGNOSTIC: record only permission-related metadata, never the
-  // tool input or any prompt text. Remove once the bypass field name is known.
-  try {
-    const { appendFileSync } = await import("node:fs");
-    appendFileSync("/tmp/granttap-hook-probe.log", JSON.stringify({
-      keys: Object.keys(input),
-      permission_mode: (input as Record<string, unknown>).permission_mode,
-      permissionMode: (input as Record<string, unknown>).permissionMode,
-      tool_name: (input as Record<string, unknown>).tool_name,
-      session_id: String((input as Record<string, unknown>).session_id ?? "").slice(0, 8),
-    }) + "\n");
-  } catch { /* diagnostics must never block a tool call */ }
-
   if (input.permission_mode === "bypassPermissions") return;
 
   // Gating paused, or this session is exempt → abstain (empty output = Claude

package/apps/bridge/src/bin/codex-hook.ts

@@ -18,10 +18,12 @@ import {
   autoAcceptLevelFor,
   blockedSessionCapability,
   isGatingSkipped,
+  isProviderEnabled,
   loadConfig,
   machineConfigPath,
   shouldAutoAcceptTool,
 } from "../config";
+import { recordAttributedCall } from "../mesh/call-scope";
 import { classifyAction } from "../policy";
 
 async function readStdin(): Promise<string> {
@@ -49,6 +51,16 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (!isProviderEnabled("codex")) return;
+
+  // See claude-hook.ts: the MCP server trusts this attribution, never the model.
+  recordAttributedCall({
+    provider: "codex",
+    sessionId: input.session_id,
+    toolName: input.tool_name,
+    args: input.tool_input,
+  });
+
   const blocked = blockedSessionCapability(
     input.session_id,
     input.tool_name,

package/apps/bridge/src/bin/codex-policy-hook.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env -S npx tsx
 /** Deny-only Codex PreToolUse policy for exact per-chat capability switches. */
 import type { HookInput } from "../adapters";
-import { blockedSessionCapability } from "../config";
+import { blockedSessionCapability, isProviderEnabled } from "../config";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -10,6 +10,7 @@ async function readStdin(): Promise<string> {
 }
 
 async function main(): Promise<void> {
+  if (!isProviderEnabled("codex")) return;
   let input: HookInput;
   try {
     input = JSON.parse(await readStdin()) as HookInput;

package/apps/bridge/src/bin/cursor-after-shell.ts

@@ -7,7 +7,7 @@ import {
   resolvedFromOutcome,
   sendApprovalResolved,
 } from "../approval-state";
-import { loadConfig, machineConfigPath } from "../config";
+import { isProviderEnabled, loadConfig, machineConfigPath } from "../config";
 import { cursorRootSessionId } from "../sessions/cursor";
 
 const SHELL_TOOLS = new Set([
@@ -32,6 +32,10 @@ async function readStdin(): Promise<string> {
 }
 
 async function main(): Promise<void> {
+  if (!isProviderEnabled("cursor")) {
+    process.stdout.write("{}\n");
+    return;
+  }
   const raw = await readStdin().catch(() => "");
   let input: {
     conversation_id?: string;

package/apps/bridge/src/bin/cursor-hook.ts

@@ -10,6 +10,7 @@ import {
   autoAcceptLevelFor,
   blockedSessionCapability,
   isGatingSkipped,
+  isProviderEnabled,
   loadConfig,
   machineConfigPath,
   shouldAutoAcceptCursorShell,
@@ -38,6 +39,10 @@ async function main(): Promise<void> {
     nativeAsk("GrantTap could not read this shell call; use Cursor approval.");
     return;
   }
+  if (!isProviderEnabled("cursor")) {
+    nativeAsk("GrantTap monitoring for Cursor is disabled; use Cursor approval.");
+    return;
+  }
   const rawSessionId = input.conversation_id ?? input.session_id;
   const sessionId = cursorRootSessionId(rawSessionId) ?? rawSessionId;
   const blocked = blockedSessionCapability(

package/apps/bridge/src/bin/cursor-mcp-hook.ts

@@ -7,6 +7,7 @@ import { isUnanswered, requestApproval } from "../approval";
 import {
   blockedSessionMcpServer,
   isGatingSkipped,
+  isProviderEnabled,
   loadConfig,
   machineConfigPath,
   shouldAutoAcceptTool,
@@ -16,6 +17,7 @@ import {
   resolveCursorMcpServer,
   type CursorMcpHookInput,
 } from "../cursor-mcp-policy";
+import { recordAttributedCall } from "../mesh/call-scope";
 import { cursorRootSessionId } from "../sessions/cursor";
 
 async function readStdin(): Promise<string> {
@@ -40,8 +42,19 @@ async function main(): Promise<void> {
     nativeAsk("GrantTap could not correlate this MCP call; use Cursor approval.");
     return;
   }
+  if (!isProviderEnabled("cursor")) {
+    nativeAsk("GrantTap monitoring for Cursor is disabled; use Cursor approval.");
+    return;
+  }
   const rawSessionId = cursorConversationId(input);
   const sessionId = cursorRootSessionId(rawSessionId) ?? rawSessionId;
+  // See claude-hook.ts: Mesh events are published only for the calling session.
+  recordAttributedCall({
+    provider: "cursor",
+    sessionId,
+    toolName: input.tool_name,
+    args: input.tool_input,
+  });
   const server = resolveCursorMcpServer(input);
   const blocked = blockedSessionMcpServer(sessionId, server);
   if (blocked) {

package/apps/bridge/src/bin/mesh-connect.ts

@@ -0,0 +1,27 @@
+import { connectGrokBotInvite } from "../mesh/endpoint";
+
+function inviteArgument(args: string[]): string {
+  if (args.length === 1 && !["--help", "-h"].includes(args[0]!)) return args[0]!;
+  process.stderr.write("Usage: granttap mesh connect <one-time-invite>\n");
+  process.exit(1);
+}
+
+const invite = inviteArgument(process.argv.slice(2));
+void connectGrokBotInvite(invite).then((bundle) => {
+  process.stdout.write([
+    "GrantTap Project Mesh",
+    "",
+    `Grok Bot endpoint  Connected (${bundle.endpoint.displayName})`,
+    `Actors             ${bundle.actors.length}`,
+    `Allowed projects   ${bundle.credential.projectIds.length}`,
+    "",
+    "Configure Grok Bot to run: granttap internal mesh-mcp",
+    "The scoped MCP server cannot create invites, change relay, or expand Project access.",
+    "",
+  ].join("\n"));
+}).catch((error: unknown) => {
+  process.stderr.write(`[granttap] Grok Bot connection failed: ${
+    error instanceof Error ? error.message : String(error)
+  }\n`);
+  process.exitCode = 1;
+});

package/apps/bridge/src/bin/setup.ts

@@ -79,6 +79,7 @@ async function main(): Promise<void> {
       ? codexHook.status === "manual" ? "Needs attention" : "Needs hook trust"
       : "Not installed"}`,
     `Cursor              ${before.cursor.installed ? `Beta · ${cursorReady ? "Authorize in Cursor" : "Needs repair"}` : "Not installed"}`,
+    `Grok Build          ${installed.has("grok") ? "Ready" : "Not installed"}`,
     "",
     paired && installed.has("codex")
       ? `Next: ${CODEX_TRUST_INSTRUCTION}`

package/apps/bridge/src/config/runtime.ts

@@ -1,5 +1,9 @@
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import type { AgentAccess } from "../../../../packages/protocol/schema";
+import type {
+  AgentAccess,
+  CodingAgent,
+  ProviderRuntimeSettings,
+} from "../../../../packages/protocol/schema";
 import {
   classifyAction,
   isAutoAcceptLevel,
@@ -19,6 +23,8 @@ export type RuntimeConfig = {
   sessionMcpDisabled: Record<string, string[]>;
   sessionSkillsDisabled: Record<string, string[]>;
   sessionShellDisabled: string[];
+  providerSettings: ProviderRuntimeSettings;
+  meshEnabled: boolean;
 };
 
 const DEFAULT_RUNTIME: RuntimeConfig = {
@@ -31,8 +37,23 @@ const DEFAULT_RUNTIME: RuntimeConfig = {
   sessionMcpDisabled: {},
   sessionSkillsDisabled: {},
   sessionShellDisabled: [],
+  providerSettings: { claude: true, codex: true, cursor: true, grok: true },
+  meshEnabled: true,
 };
 
+function parseProviderSettings(raw: unknown): ProviderRuntimeSettings {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ...DEFAULT_RUNTIME.providerSettings };
+  }
+  const value = raw as Record<string, unknown>;
+  return {
+    claude: value.claude !== false,
+    codex: value.codex !== false,
+    cursor: value.cursor !== false,
+    grok: value.grok !== false,
+  };
+}
+
 export function boundedIdentifier(raw: unknown, maxLength: number): string | null {
   if (typeof raw !== "string") return null;
   const value = raw.trim();
@@ -96,6 +117,8 @@ export function loadRuntimeConfig(): RuntimeConfig {
               .filter((sessionId): sessionId is string => sessionId != null),
           )]
         : [],
+      providerSettings: parseProviderSettings(raw.providerSettings),
+      meshEnabled: raw.meshEnabled !== false,
     };
   } catch {
     return {
@@ -105,10 +128,20 @@ export function loadRuntimeConfig(): RuntimeConfig {
       sessionMcpDisabled: {},
       sessionSkillsDisabled: {},
       sessionShellDisabled: [],
+      providerSettings: { ...DEFAULT_RUNTIME.providerSettings },
+      meshEnabled: true,
     };
   }
 }
 
+export function isProviderEnabled(provider: CodingAgent): boolean {
+  return loadRuntimeConfig().providerSettings[provider];
+}
+
+export function isMeshEnabled(): boolean {
+  return loadRuntimeConfig().meshEnabled;
+}
+
 export function saveRuntimeConfig(cfg: Partial<RuntimeConfig>): void {
   mkdirSync(configDir(), { recursive: true });
   const merged: RuntimeConfig = { ...loadRuntimeConfig(), ...cfg };

package/apps/bridge/src/install.ts

@@ -22,6 +22,7 @@ import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import type { CodingAgent } from "../../../packages/protocol/schema";
 import { configDir } from "./config";
 
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
@@ -54,7 +55,7 @@ export const CODEX_TRUST_INSTRUCTION =
   "Open /hooks in Codex, review and trust both GrantTap hooks, then restart Codex.";
 
 export type AgentIntegrationStatus = {
-  agent: "codex" | "claude";
+  agent: CodingAgent;
   installed: boolean;
   hookConfigured: boolean;
 };
@@ -242,9 +243,16 @@ export function inspectCursorIntegration(): CursorIntegrationStatus {
 export function inspectAgentIntegrations(): AgentIntegrationStatus[] {
   const codex = process.env.GRANTTAP_CODEX_BIN ?? process.env.NODVOX_CODEX_BIN ?? "codex";
   const claude = process.env.GRANTTAP_CLAUDE_BIN ?? process.env.NODVOX_CLAUDE_BIN ?? "claude";
+  const cursor = process.env.GRANTTAP_CURSOR_AGENT_BIN ?? "cursor-agent";
+  const grok = process.env.GRANTTAP_GROK_BIN ?? "grok";
+  const cursorStatus = inspectCursorIntegration();
   return [
     { agent: "codex", installed: executableAvailable(codex), hookConfigured: codexHookConfigured() },
     { agent: "claude", installed: executableAvailable(claude), hookConfigured: claudeHookConfigured() },
+    { agent: "cursor", installed: executableAvailable(cursor), hookConfigured: cursorStatus.hookConfigured },
+    // Grok Build's headless session contract is direct; GrantTap does not
+    // claim an approval hook exists when none has been installed.
+    { agent: "grok", installed: executableAvailable(grok), hookConfigured: false },
   ];
 }
 

package/apps/bridge/src/mesh/README.md

@@ -0,0 +1,36 @@
+# Project Mesh runtime
+
+This module links discovered native sessions to stable Project and Task
+identities, persists bounded structured events, tracks expiring resource
+claims and dependencies, and executes authorized task handoffs.
+
+`runtime.ts` is the public runtime entry point. `catalog.ts` derives repository
+identity without replacing provider-native session discovery. `store.ts`
+deduplicates replayed events and expires stale claims. `capsule.ts` reads only
+explicit git and task facts; transcripts and hidden reasoning are never copied.
+`worktree.ts` creates a separate target branch/worktree before Claude Code or
+Codex is started. The provider abstraction already admits Cursor and Grok Build
+without changing the core contract, while their unsupported phase-one start
+paths fail closed.
+
+`call-scope.ts` and `capability.ts` own caller identity. The MCP server cannot
+see which agent called it, so each provider hook records a single-use
+attribution for the exact call it observed inside its own session, and the
+runtime derives the publishing execution from that instead of from anything the
+model supplied. `capability.ts` mints the opaque per-execution token that
+`scoped-view.ts` answers with, so a read returns one Project rather than
+everything this computer knows. Structured events use the existing `notify`
+tool so the public MCP tool allowlist remains exactly `connect`, `notify`,
+`ask_yes_no`, and `ask`. Setup and global provider configuration remain
+CLI-only.
+
+`readiness.ts` decides whether a handoff may leave at all. A capsule transfers
+committed facts, so uncommitted work blocks the handoff instead of silently
+staying behind, and the destination refuses just as explicitly when it lacks the
+named commit or when the capsule's resource claims overlap another execution.
+
+Every event is schema-bounded and sent under an independent task key; snapshots
+use an independent project key. Resource claims are advisory, expire without a
+heartbeat, and a colliding claim is rejected before it is recorded. The agent
+may choose other work or ask the current owner; the conflict reaches the human
+only after explicit `needsUser` escalation.

package/apps/bridge/src/mesh/attention.ts

@@ -0,0 +1,19 @@
+import type { MeshEventType } from "../../../../packages/protocol/schema";
+
+type AttentionFacts = {
+  category?: unknown;
+  resolved?: unknown;
+  needsUser?: unknown;
+  failed?: unknown;
+};
+
+/** Only deterministic, product-approved reasons may enter the human inbox. */
+export function classifyHumanAttention(type: MeshEventType, facts: AttentionFacts): boolean {
+  if (type === "AGENT_QUESTION") {
+    return ["product", "business", "security", "destructive"].includes(String(facts.category));
+  }
+  if (type === "CONFLICT") return facts.resolved !== true && facts.needsUser === true;
+  if (type === "TASK_BLOCKED") return facts.needsUser === true;
+  if (type === "HANDOFF_REJECTED") return facts.failed === true;
+  return false;
+}

package/apps/bridge/src/mesh/call-scope.ts

@@ -0,0 +1,135 @@
+/**
+ * Trusted attribution for GrantTap MCP calls.
+ *
+ * The MCP server sees a tool call but not which agent session made it, so a
+ * model that learns another execution's session id could otherwise publish
+ * events in its name. Provider hooks do know the session: they run inside it
+ * and receive the exact arguments. Each hook records a single-use, short-lived
+ * attribution keyed by those arguments, and the MCP server consumes it instead
+ * of trusting anything the model claimed.
+ */
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { configDir } from "../config";
+
+const CALL_TTL_MS = 120_000;
+const MAX_RECORDS = 32;
+
+const AttributedCall = z.object({
+  key: z.string().regex(/^[0-9a-f]{64}$/),
+  provider: z.enum(["claude", "codex", "cursor", "grok"]),
+  sessionId: z.string().trim().min(1).max(256),
+  expiresAt: z.number().positive(),
+}).strict();
+export type AttributedCall = z.infer<typeof AttributedCall>;
+
+const CallFile = z.object({
+  version: z.literal(1),
+  calls: z.array(AttributedCall).max(MAX_RECORDS),
+}).strict();
+
+/** Normalize exactly like the wire schemas so hook and server agree byte for byte. */
+function canonical(value: unknown): unknown {
+  if (typeof value === "string") return value.trim();
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      const item = (value as Record<string, unknown>)[key];
+      if (item !== undefined && item !== null) out[key] = canonical(item);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** The GrantTap tool name as each provider spells it, reduced to one token. */
+export function grantTapToolName(rawToolName: unknown): string | undefined {
+  const raw = String(rawToolName ?? "").trim();
+  const tool = raw.includes("__") ? raw.split("__").at(-1)! : raw;
+  return ["notify", "connect", "ask", "ask_yes_no"].includes(tool) ? tool : undefined;
+}
+
+export function meshCallKey(tool: string, args: unknown): string {
+  return createHash("sha256")
+    .update(JSON.stringify({ tool, args: canonical(args) }))
+    .digest("hex");
+}
+
+function callFilePath(): string {
+  return join(configDir(), "mesh-tool-calls.json");
+}
+
+function readCalls(now: number): AttributedCall[] {
+  try {
+    const parsed = CallFile.safeParse(JSON.parse(readFileSync(callFilePath(), "utf8")));
+    if (!parsed.success) return [];
+    return parsed.data.calls.filter((call) => call.expiresAt > now);
+  } catch {
+    return [];
+  }
+}
+
+function writeCalls(calls: AttributedCall[]): void {
+  const path = callFilePath();
+  mkdirSync(configDir(), { recursive: true });
+  writeFileSync(
+    path,
+    `${JSON.stringify(CallFile.parse({ version: 1, calls: calls.slice(-MAX_RECORDS) }), null, 2)}\n`,
+    { mode: 0o600 },
+  );
+  chmodSync(path, 0o600);
+}
+
+/**
+ * Record that this provider session is about to make one GrantTap tool call.
+ * Hooks call this before returning their decision; it never blocks the hook.
+ */
+export function recordAttributedCall(input: {
+  provider: AttributedCall["provider"];
+  sessionId: unknown;
+  toolName: unknown;
+  args: unknown;
+  now?: number;
+}): void {
+  const tool = grantTapToolName(input.toolName);
+  const sessionId = String(input.sessionId ?? "").trim();
+  if (tool !== "notify" || !sessionId || sessionId.length > 256) return;
+  const now = input.now ?? Date.now();
+  try {
+    const call = AttributedCall.parse({
+      key: meshCallKey(tool, input.args),
+      provider: input.provider,
+      sessionId,
+      expiresAt: now + CALL_TTL_MS,
+    });
+    const kept = readCalls(now).filter((item) =>
+      item.key !== call.key || item.sessionId !== call.sessionId);
+    writeCalls([...kept, call]);
+  } catch {
+    // Attribution is best effort inside the hook; the MCP server fails closed.
+  }
+}
+
+/**
+ * Resolve the session that actually made this call, then retire the record.
+ * Two live sessions claiming the same arguments are ambiguous and rejected.
+ */
+export function consumeAttributedCall(
+  tool: string,
+  args: unknown,
+  now = Date.now(),
+): AttributedCall | undefined {
+  const key = meshCallKey(tool, args);
+  const live = readCalls(now);
+  const matches = live.filter((call) => call.key === key);
+  const sessions = new Set(matches.map((call) => call.sessionId));
+  if (matches.length === 0 || sessions.size !== 1) {
+    if (matches.length > 0) writeCalls(live.filter((call) => call.key !== key));
+    return undefined;
+  }
+  writeCalls(live.filter((call) => call.key !== key));
+  return matches[0];
+}