granttap-mcp 0.7.0 → 0.7.1

package/README.md

@@ -45,12 +45,22 @@ 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.
+
+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,
@@ -59,6 +69,14 @@ 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
@@ -127,7 +145,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

@@ -49,6 +49,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

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

@@ -23,6 +23,7 @@ import {
   machineConfigPath,
   shouldAutoAcceptTool,
 } from "../config";
+import { recordAttributedCall } from "../mesh/call-scope";
 import { classifyAction } from "../policy";
 
 async function readStdin(): Promise<string> {
@@ -51,6 +52,16 @@ async function main(): Promise<void> {
 
   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,6 +23,7 @@ import {
   machineConfigPath,
   shouldAutoAcceptTool,
 } from "../config";
+import { recordAttributedCall } from "../mesh/call-scope";
 import { classifyAction } from "../policy";
 
 async function readStdin(): Promise<string> {
@@ -52,6 +53,14 @@ async function main(): Promise<void> {
 
   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/cursor-mcp-hook.ts

@@ -17,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> {
@@ -47,6 +48,13 @@ async function main(): Promise<void> {
   }
   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/mesh/README.md

@@ -13,10 +13,21 @@ 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.
 
-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 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

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];
+}

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

@@ -0,0 +1,135 @@
+/**
+ * Opaque per-execution Mesh capabilities.
+ *
+ * A capability names exactly one live execution: its Project, its Task, its
+ * provider and its native session. It is minted only for a call the provider
+ * hook already attributed to that session, and it is returned only into that
+ * session's own tool result, so one agent can never obtain another's scope.
+ */
+import { randomBytes } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import {
+  MeshEventType,
+  type ExecutionSessionLink,
+  type MeshSnapshot,
+} from "../../../../packages/protocol/schema";
+import { configDir } from "../config";
+import { isProviderEnabled } from "../config/runtime";
+import { localMeshStore } from "./local";
+
+const CAPABILITY_TTL_MS = 12 * 60 * 60_000;
+const MAX_CAPABILITIES = 64;
+
+/** Ownership transfer is decided by the runtime after receipt checks, never by a tool call. */
+const PUBLISHABLE_EVENT_TYPES = MeshEventType.options.filter((type) =>
+  type !== "HANDOFF_ACCEPTED" && type !== "HANDOFF_REJECTED");
+
+const ExecutionCapability = z.object({
+  token: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+  provider: z.enum(["claude", "codex", "cursor", "grok"]),
+  sessionId: z.string().trim().min(1).max(256),
+  projectId: z.string().trim().min(1).max(128),
+  taskId: z.string().trim().min(1).max(128),
+  allowedEventTypes: z.array(MeshEventType).min(1),
+  issuedAt: z.number().nonnegative(),
+  expiresAt: z.number().positive(),
+}).strict();
+export type ExecutionCapability = z.infer<typeof ExecutionCapability>;
+
+const CapabilityFile = z.object({
+  version: z.literal(1),
+  capabilities: z.array(ExecutionCapability).max(MAX_CAPABILITIES),
+}).strict();
+
+export function meshCapabilityPath(): string {
+  return join(configDir(), "mesh-capabilities.json");
+}
+
+function readCapabilities(now: number): ExecutionCapability[] {
+  try {
+    const parsed = CapabilityFile.safeParse(JSON.parse(readFileSync(meshCapabilityPath(), "utf8")));
+    if (!parsed.success) return [];
+    return parsed.data.capabilities.filter((item) => item.expiresAt > now);
+  } catch {
+    return [];
+  }
+}
+
+function writeCapabilities(capabilities: ExecutionCapability[]): void {
+  const path = meshCapabilityPath();
+  mkdirSync(configDir(), { recursive: true });
+  writeFileSync(
+    path,
+    `${JSON.stringify(
+      CapabilityFile.parse({ version: 1, capabilities: capabilities.slice(-MAX_CAPABILITIES) }),
+      null,
+      2,
+    )}\n`,
+    { mode: 0o600 },
+  );
+  chmodSync(path, 0o600);
+}
+
+export type ExecutionScope = {
+  execution: ExecutionSessionLink;
+  snapshot: MeshSnapshot;
+};
+
+/** The one live, enabled coding-agent execution that owns this native session. */
+export function liveExecutionScope(sessionId: string): ExecutionScope | undefined {
+  const store = localMeshStore();
+  for (const projectId of store.projectIds()) {
+    const snapshot = store.snapshot(projectId);
+    const execution = snapshot?.executions.find((item) =>
+      item.sessionId === sessionId && item.endedAt == null);
+    if (!snapshot || !execution) continue;
+    if (execution.provider === "grok_bot" || !isProviderEnabled(execution.provider)) return undefined;
+    return { execution, snapshot };
+  }
+  return undefined;
+}
+
+/** Mint or reuse the capability for one attributed session. */
+export function executionCapabilityFor(
+  sessionId: string,
+  now = Date.now(),
+): ExecutionCapability | undefined {
+  const scope = liveExecutionScope(sessionId);
+  if (!scope) return undefined;
+  const live = readCapabilities(now);
+  const existing = live.find((item) =>
+    item.sessionId === sessionId
+    && item.taskId === scope.execution.taskId
+    && item.projectId === scope.snapshot.projectId);
+  if (existing) return existing;
+  const capability = ExecutionCapability.parse({
+    token: randomBytes(32).toString("base64url"),
+    provider: scope.execution.provider,
+    sessionId,
+    projectId: scope.snapshot.projectId,
+    taskId: scope.execution.taskId,
+    allowedEventTypes: PUBLISHABLE_EVENT_TYPES,
+    issuedAt: now,
+    expiresAt: now + CAPABILITY_TTL_MS,
+  });
+  writeCapabilities([...live.filter((item) => item.sessionId !== sessionId), capability]);
+  return capability;
+}
+
+/** Resolve a presented capability; an ended or disabled execution resolves to nothing. */
+export function resolveExecutionCapability(
+  token: unknown,
+  now = Date.now(),
+): ExecutionCapability | undefined {
+  const value = String(token ?? "").trim();
+  if (!value) return undefined;
+  const capability = readCapabilities(now).find((item) => item.token === value);
+  if (!capability) return undefined;
+  const scope = liveExecutionScope(capability.sessionId);
+  if (!scope
+    || scope.snapshot.projectId !== capability.projectId
+    || scope.execution.taskId !== capability.taskId) return undefined;
+  return capability;
+}

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

@@ -29,6 +29,22 @@ function git(cwd: string, args: string[]): string | undefined {
   }
 }
 
+/**
+ * Whether this checkout has changes that a commit-based handoff would leave
+ * behind. `undefined` means the probe could not answer, which callers must not
+ * read as "clean".
+ */
+export function hasUncommittedWork(cwd: string): boolean | undefined {
+  try {
+    execFileSync("git", ["-C", cwd, "diff", "--quiet", "HEAD"], {
+      stdio: "ignore", timeout: 2_000,
+    });
+    return false;
+  } catch (error) {
+    return (error as { status?: number }).status === 1 ? true : undefined;
+  }
+}
+
 export function inspectRepository(cwd: string): RepositoryFacts {
   const cached = repositoryCache.get(cwd);
   if (cached) return cached;
@@ -98,6 +114,7 @@ export function linkSessionsToProjects(
       workspace: cwd,
       branch: session.branch,
       worktree: repository.worktree,
+      uncommitted: hasUncommittedWork(repository.worktree ?? cwd),
       startedAt: session.startedAt,
     });
     return { ...session, projectId, taskId, computerId, worktree: repository.worktree };

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

@@ -0,0 +1,72 @@
+/**
+ * Handoff readiness.
+ *
+ * A Task Capsule carries facts, not files: the destination starts a worktree
+ * from a commit. Anything still uncommitted stays on the source computer even
+ * though the Task visibly continues elsewhere, so a handoff that would lose it
+ * is refused instead of silently narrowing to committed state.
+ */
+import type { ResourceClaim, TaskCapsule } from "../../../../packages/protocol/schema";
+
+export const UNCOMMITTED_WORK_REASON =
+  "This task has uncommitted changes. Commit or checkpoint them before moving the task.";
+
+export type HandoffCheckId = "repository" | "workingTree" | "claims" | "targetAgent";
+
+export type HandoffCheck = {
+  id: HandoffCheckId;
+  ready: boolean;
+  detail: string;
+};
+
+export type HandoffReadiness = {
+  ready: boolean;
+  blockedReason?: string;
+  checks: HandoffCheck[];
+};
+
+export type HandoffReadinessInput = {
+  capsule?: TaskCapsule;
+  targetProviderEnabled: boolean;
+  conflicts: ResourceClaim[];
+};
+
+function check(id: HandoffCheckId, ready: boolean, detail: string): HandoffCheck {
+  return { id, ready, detail };
+}
+
+/** Every blocking condition the source computer can answer before publishing. */
+export function handoffReadiness(input: HandoffReadinessInput): HandoffReadiness {
+  const { capsule } = input;
+  const conflict = input.conflicts.at(0);
+  const checks: HandoffCheck[] = [
+    check(
+      "repository",
+      Boolean(capsule),
+      capsule
+        ? `Commit ${capsule.latestCommit ?? capsule.baseSha} in ${capsule.repository}`
+        : "No git repository, task, or commit was found for this execution.",
+    ),
+    check(
+      "workingTree",
+      Boolean(capsule) && capsule?.dirtyDiffHash == null,
+      capsule?.dirtyDiffHash == null ? "Clean" : UNCOMMITTED_WORK_REASON,
+    ),
+    check(
+      "claims",
+      !conflict,
+      conflict
+        ? `${conflict.ownerSessionId} currently claims ${conflict.resource}.`
+        : "No overlapping resource claims",
+    ),
+    check(
+      "targetAgent",
+      input.targetProviderEnabled,
+      input.targetProviderEnabled
+        ? "Ready"
+        : "The target agent is disabled in GrantTap Settings.",
+    ),
+  ];
+  const blocked = checks.find((item) => !item.ready);
+  return { ready: !blocked, blockedReason: blocked?.detail, checks };
+}

package/apps/bridge/src/mesh/runtime-dependencies.ts

@@ -0,0 +1,37 @@
+/** The seams the Mesh runtime needs from this computer: state, sessions, git, and transport. */
+import type { RelayClient } from "../../../../packages/core/relay-client";
+import type {
+  MeshEvent,
+  MeshProvider,
+  MeshSnapshot,
+  SessionInfo,
+} from "../../../../packages/protocol/schema";
+import type { createCodexSession, deliverToSession } from "../reply";
+import type { MeshStore } from "./store";
+import type { createHandoffWorktree } from "./worktree";
+
+type StartResult = Awaited<ReturnType<typeof createCodexSession>>;
+type WorktreeResult = NonNullable<ReturnType<typeof createHandoffWorktree>>;
+
+export type MeshRuntimeDependencies = {
+  store: () => MeshStore;
+  sessions: () => SessionInfo[];
+  computer: () => string;
+  now: () => number;
+  eventId: () => string;
+  providerEnabled: (provider: Exclude<MeshProvider, "grok_bot">) => boolean;
+  start: (provider: MeshProvider, prompt: string, cwd: string) => Promise<StartResult>;
+  deliver: typeof deliverToSession;
+  send: (
+    client: RelayClient,
+    payload: MeshEvent | MeshSnapshot,
+    options: { ttlMs: number; wake?: boolean },
+  ) => Promise<void>;
+  worktree: (
+    repository: string,
+    taskId: string,
+    provider: MeshProvider,
+    revision: string,
+  ) => WorktreeResult | undefined | null;
+  hasCommit: (repository: string, revision: string) => boolean;
+};