granttap-mcp 0.7.0 → 0.7.6

package/README.md

@@ -45,19 +45,39 @@ 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 can read the compact `granttap://mesh/current` MCP resource and publish
-bounded progress, dependency, question, answer, claim, conflict, and completion
-events through the existing `notify` tool. 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.
+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.
+
+For Claude Code, Codex, and Cursor, the provider hook runs inside the agent's
+own session and sees the exact call. 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.
+Cursor uses the same provider-neutral schema and trusted caller attribution.
+Grok Build remains Experimental and observable where available, but does not
+yet expose a trusted caller hook, so agent-authored scoped Mesh events are not
+offered for it. 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
 
@@ -127,7 +147,8 @@ 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.
+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

package/SECURITY.md

@@ -20,6 +20,24 @@ credential used for authenticated WebSocket and APNs registration.
 Provider credentials remain in each provider's own local authentication flow.
 GrantTap does not send them to the relay.
 
+Installed Claude Code, Codex, and Cursor hooks deny direct agent tool calls
+that name GrantTap's local pairing, key, or policy files, including calls that
+would otherwise be auto-accepted or run in provider bypass mode. The denial
+covers the config directory itself, any glob over it, and every file not on a
+short access-mode list, so a file added later is protected the day it appears.
+Only helper logs and bounded runtime diagnostics are agent-readable, and they
+remain read-only. Raw Mesh state and hook-attribution records are never exposed
+to agent tools; `workspaces/` and `worktrees/` remain normal editable agent
+workspace. The guard denies only what it positively recognised as a path into
+that directory, and a fault inside the guard itself is printed and allowed
+through instead of blocking every tool call on the machine: an outage of every
+agent is a worse failure than the file it was watching. This is
+best-effort self-protection, not an operating-system security boundary: a
+process running as the same macOS user can use an unobserved tool, shell
+obfuscation, or direct filesystem access outside those hooks. Protect the user
+account and disk; use a trusted terminal for intentional maintenance. Moving
+remaining local secret material into Keychain is the stronger future boundary.
+
 ## Cryptographic boundary
 
 - Every computer pairing is generated locally with unique Curve25519 keys.
@@ -49,6 +67,16 @@ 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
@@ -57,6 +85,10 @@ 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.
 
+Repository remotes included in Project snapshots are reduced to lowercase
+host/path form. Userinfo, passwords or tokens, query strings, fragments, and
+local-path remotes are never persisted as `baseRemote`.
+
 ## Runtime controls
 
 Provider hooks enforce policy on the computer. Global provider deny always
@@ -77,5 +109,16 @@ 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.
 
+## Local helper installation
+
+The background helper is a user LaunchAgent, and `launchctl bootstrap` replaces
+whatever job already holds that label. GrantTap therefore refuses to load a
+LaunchAgent whose plist lives under the operating system's temporary directory:
+a test, probe, or agent run with a temporary `HOME` must never evict the
+installed helper and leave launchd restarting a program whose files were already
+cleaned up. Only `GRANTTAP_TEST_FAKE_LAUNCHCTL=1`, which states that `launchctl`
+on `PATH` is a stub, lifts that refusal.
+
+
 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

@@ -23,7 +23,9 @@ import {
   machineConfigPath,
   shouldAutoAcceptTool,
 } from "../config";
+import { recordAttributedCall } from "../mesh/call-scope";
 import { classifyAction } from "../policy";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -49,8 +51,30 @@ async function main(): Promise<void> {
     return;
   }
 
+  const protectedAccess = protectedGrantTapAccess(input.tool_name, input.tool_input);
+  if (protectedAccess) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: protectedAccess.reason,
+      },
+    }));
+    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,

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

@@ -23,7 +23,9 @@ import {
   machineConfigPath,
   shouldAutoAcceptTool,
 } from "../config";
+import { recordAttributedCall } from "../mesh/call-scope";
 import { classifyAction } from "../policy";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -50,8 +52,22 @@ async function main(): Promise<void> {
     return;
   }
 
+  const protectedAccess = protectedGrantTapAccess(input.tool_name, input.tool_input);
+  if (protectedAccess) {
+    process.stdout.write(denyOutput(protectedAccess.reason));
+    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

@@ -2,6 +2,7 @@
 /** Deny-only Codex PreToolUse policy for exact per-chat capability switches. */
 import type { HookInput } from "../adapters";
 import { blockedSessionCapability, isProviderEnabled } from "../config";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -10,13 +11,24 @@ 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;
   } catch {
     return;
   }
+  const protectedAccess = protectedGrantTapAccess(input.tool_name, input.tool_input);
+  if (protectedAccess) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: protectedAccess.reason,
+      },
+    }));
+    return;
+  }
+  if (!isProviderEnabled("codex")) return;
   const blocked = blockedSessionCapability(
     input.session_id,
     input.tool_name,

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

@@ -16,6 +16,7 @@ import {
   shouldAutoAcceptCursorShell,
 } from "../config";
 import { cursorRootSessionId } from "../sessions/cursor";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -31,6 +32,14 @@ function nativeAsk(message: string): void {
   }));
 }
 
+function deny(message: string): void {
+  process.stdout.write(JSON.stringify({
+    permission: "deny", continue: false,
+    user_message: message, agent_message: message,
+    userMessage: message, agentMessage: message,
+  }));
+}
+
 async function main(): Promise<void> {
   let input: CursorHookInput;
   try {
@@ -39,6 +48,13 @@ async function main(): Promise<void> {
     nativeAsk("GrantTap could not read this shell call; use Cursor approval.");
     return;
   }
+  const protectedAccess = protectedGrantTapAccess(
+    input.tool_name, input.tool_input, input.command,
+  );
+  if (protectedAccess) {
+    deny(protectedAccess.reason);
+    return;
+  }
   if (!isProviderEnabled("cursor")) {
     nativeAsk("GrantTap monitoring for Cursor is disabled; use Cursor approval.");
     return;
@@ -51,14 +67,7 @@ async function main(): Promise<void> {
     input.tool_input ?? { command: input.command },
   );
   if (blocked) {
-    process.stdout.write(JSON.stringify({
-      permission: "deny",
-      continue: false,
-      user_message: blocked.reason,
-      agent_message: blocked.reason,
-      userMessage: blocked.reason,
-      agentMessage: blocked.reason,
-    }));
+    deny(blocked.reason);
     return;
   }
   if (!sessionId || isGatingSkipped(sessionId)) {

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

@@ -17,7 +17,9 @@ import {
   resolveCursorMcpServer,
   type CursorMcpHookInput,
 } from "../cursor-mcp-policy";
+import { recordAttributedCall } from "../mesh/call-scope";
 import { cursorRootSessionId } from "../sessions/cursor";
+import { protectedGrantTapAccess } from "../self-protection";
 
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
@@ -41,12 +43,30 @@ async function main(): Promise<void> {
     nativeAsk("GrantTap could not correlate this MCP call; use Cursor approval.");
     return;
   }
+  const protectedAccess = protectedGrantTapAccess(
+    input.tool_name, input.tool_input, input.command,
+  );
+  if (protectedAccess) {
+    process.stdout.write(JSON.stringify({
+      permission: "deny",
+      user_message: protectedAccess.reason,
+      agent_message: protectedAccess.reason,
+    }));
+    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/install.ts

@@ -23,6 +23,7 @@ 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 { refusesLiveLaunchd } from "./launchd-safety";
 import { configDir } from "./config";
 
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
@@ -299,18 +300,15 @@ export function inspectMonitorHelper(): MonitorIntegrationStatus {
   return { configured: true, running: active.status === 0 };
 }
 
-/** Absolute pin for this machine — LaunchAgent must never drift to granttap-mcp + Cursor helpers. */
-export const DEFAULT_PINNED_MONITOR_BIN = "/Users/serhiirihgt/dev/nodvox/bin/granttap.mjs";
-export const DEFAULT_PINNED_MONITOR_ROOT = "/Users/serhiirihgt/dev/nodvox";
-
-export function pinnedMonitorBin(): string {
+/** Optional explicit development pin; public installs use this package by default. */
+export function pinnedMonitorBin(): string | undefined {
   const override = process.env.GRANTTAP_PINNED_MONITOR_BIN?.trim();
-  return override && override.length > 0 ? override : DEFAULT_PINNED_MONITOR_BIN;
+  return override && override.length > 0 ? override : undefined;
 }
 
-export function pinnedMonitorRoot(): string {
+export function pinnedMonitorRoot(): string | undefined {
   const override = process.env.GRANTTAP_PINNED_MONITOR_ROOT?.trim();
-  return override && override.length > 0 ? override : DEFAULT_PINNED_MONITOR_ROOT;
+  return override && override.length > 0 ? override : undefined;
 }
 
 function xml(value: string): string {
@@ -326,15 +324,12 @@ export function isCursorHelperNode(nodePath: string): boolean {
   return nodePath.includes("Cursor.app") || nodePath.includes("/helpers/node");
 }
 
-/** True when plist already runs the nodvox monitor without Cursor/mcp clobber. */
+/** True when a plist uses the caller's explicit development monitor pin. */
 export function isNodvoxPinnedPlist(contents: string): boolean {
   const pin = pinnedMonitorBin();
-  const hasNodvoxBin =
-    contents.includes(pin) ||
-    contents.includes("/dev/nodvox/bin/granttap.mjs") ||
-    contents.includes("/nodvox/bin/granttap.mjs");
+  if (!pin) return false;
   return (
-    hasNodvoxBin &&
+    contents.includes(pin) &&
     !contents.includes("granttap-mcp.mjs") &&
     !contents.includes("Cursor.app") &&
     !contents.includes("/helpers/node")
@@ -364,8 +359,8 @@ export function resolveMonitorNodeBin(): string | null {
  * Keep task/session sync alive without a terminal or a newly opened MCP chat.
  *
  * Hard rules:
- * - Never overwrite a healthy nodvox-pinned LaunchAgent with granttap-mcp / Cursor helpers.
- * - When `/Users/serhiirihgt/dev/nodvox/bin/granttap.mjs` exists, pin to it (not this package's bin).
+ * - Never overwrite a healthy explicitly pinned LaunchAgent with package / Cursor helpers.
+ * - Development pins are opt-in through `GRANTTAP_PINNED_MONITOR_BIN`.
  * - Never put Cursor.app helpers/node in ProgramArguments.
  */
 export function installMonitorHelper(): InstallResult {
@@ -383,11 +378,12 @@ export function installMonitorHelper(): InstallResult {
     }
   }
 
-  const pinBin = pinnedMonitorBin();
-  const usePin = existsSync(pinBin);
-  const executable = usePin ? pinBin : join(repoRoot, "bin", "granttap-mcp.mjs");
-  const workingDirectory = usePin
-    ? pinnedMonitorRoot()
+  const explicitPin = pinnedMonitorBin();
+  const pinBin = explicitPin && existsSync(explicitPin) ? explicitPin : undefined;
+  const usePin = pinBin != null;
+  const executable = pinBin ?? join(repoRoot, "bin", "granttap-mcp.mjs");
+  const workingDirectory = pinBin
+    ? (pinnedMonitorRoot() ?? dirname(pinBin))
     : (process.env.GRANTTAP_MONITOR_CWD ?? process.cwd());
   const nodeBin = resolveMonitorNodeBin();
   if (!nodeBin) {
@@ -473,6 +469,8 @@ export function installMonitorHelper(): InstallResult {
     return { status: already ? "already" : "installed", detail };
   }
 
+  const sandboxed = refusesLiveLaunchd(path);
+  if (sandboxed) return { status: "manual", detail: sandboxed };
   const uid = process.getuid?.();
   if (uid == null) return { status: "manual", detail: `${path}: could not determine user id` };
   const domain = `gui/${uid}`;

package/apps/bridge/src/launchd-safety.ts

@@ -0,0 +1,53 @@
+/**
+ * A LaunchAgent is user-global: `launchctl bootstrap` replaces whatever job
+ * already holds that label. A sandboxed run — a test, a probe, anything with a
+ * temporary `HOME` or config directory — therefore evicts the real GrantTap
+ * helper and installs a job whose plist, node modules, and log file vanish with
+ * the temporary directory. launchd then keeps restarting a program it can no
+ * longer load, which reads to the user as GrantTap crashing in a loop.
+ *
+ * A real installation always writes into the user's own Library. A plist under
+ * the operating system's temporary directory is a sandbox by definition, so it
+ * never reaches the live domain.
+ */
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve, sep } from "node:path";
+
+const TEMPORARY_ROOTS = ["/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
+
+function canonical(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+export function insideTemporaryDirectory(path: string): boolean {
+  if (process.env.GRANTTAP_TEST_FAKE_LAUNCHCTL === "1") return false;
+  const target = canonical(path);
+  const roots = new Set<string>();
+  for (const root of [tmpdir(), ...TEMPORARY_ROOTS]) {
+    roots.add(resolve(root));
+    roots.add(canonical(root));
+  }
+  return [...roots].some((root) => target === root || target.startsWith(root + sep));
+}
+
+export const SANDBOXED_LAUNCH_AGENT_DETAIL =
+  "refusing to load a LaunchAgent from a temporary directory; "
+  + "a sandboxed run must not replace the installed GrantTap helper";
+
+/**
+ * Whether this plist may be handed to `launchctl` in the live user domain.
+ *
+ * `GRANTTAP_TEST_FAKE_LAUNCHCTL=1` states that the `launchctl` on PATH is a
+ * stub, so the whole install path can be exercised without a live domain to
+ * damage. It is an explicit, greppable opt-in; nothing in the shipped product
+ * sets it.
+ */
+export function refusesLiveLaunchd(path: string): string | null {
+  if (process.env.GRANTTAP_TEST_FAKE_LAUNCHCTL === "1") return null;
+  return insideTemporaryDirectory(path) ? `${path}: ${SANDBOXED_LAUNCH_AGENT_DETAIL}` : null;
+}

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

@@ -9,14 +9,40 @@ 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.
+Codex is started. Cursor has trusted caller attribution but no phase-one remote
+start. Grok Build remains observable and Experimental; because it has no
+trusted caller hook, agent-authored scoped Mesh events are not offered for it.
+Unsupported paths fail closed.
 
-The read-only MCP resource `granttap://mesh/current` exposes compact local state
-to an agent. 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.
+`call-scope.ts` and `capability.ts` own caller identity. The MCP server cannot
+see which agent called it, so supported provider hooks record 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.
+"Uncommitted" is read from `git status` including untracked files, because an
+untracked file is work no commit would carry. A probe that cannot answer
+publishes `unknown`, and only an explicit `clean` releases the handoff.
+
+`convergence.ts` and `task-state.ts` keep one Task identity while snapshots and
+events arrive late, twice, and from several computers. Every writer raises the
+Task `revision`, a merge keeps the higher one, and a tie resolves the same way
+on every device. Ownership only moves forward: to an unowned Task, back to the
+session that already owns it, or through a receipt from the current owner —
+and a computer that already watched a session hand the Task on refuses that
+session's later receipt. Completed and failed Tasks absorb events instead of
+reopening, an execution closed by a receipt stays closed even while its native
+session keeps reporting itself, and the local catalog may refresh a Task's
+description but never take it back from the agent that owns it now.
 
 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

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 || tool === "connect" || !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];
+}