granttap-mcp 0.8.1 → 0.8.3

package/README.md

@@ -78,11 +78,34 @@ 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
+committed state and leaving that work behind. Asked to checkpoint from the
+phone, the source computer commits everything to `granttap/checkpoint/<task>`
+from a temporary index, so HEAD, the current branch, and the working tree stay
+exactly as the agent left them, and the capsule carries that commit. Nothing is
+pushed; the destination says so if the commit has not reached it.
+
+Claims do not wait for an agent to announce them. Every edit an agent makes is
+visible in its transcript, so the runtime derives an intent claim from each
+recent write — marked as seen rather than said, and expiring ten minutes after
+the writing stops. Overlap is judged twice: the same file is a conflict, and
+the same module is the warning that comes before it. A module is recognised
+from the path alone, so every computer and the phone reach the same answer,
+and the Task screen names who else is in this Task's files or modules while it
+can still be avoided. 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.
 
+A Project usually binds more than one repository, and a bound repository can
+say which of the others sit on the far side of its databases, topics, and APIs:
+commit a [`WEAVATRIX.md`](https://github.com/Weavatrix/weavatrix-md) next to the
+README and the runtime reads it — only the edges it states, nothing inferred —
+and publishes them with the Project. The Task screen then names another Task
+that is working on the other side of a contract this Task touches (the consumer
+of a topic it produces, the caller of an API it changes), and the scoped
+`granttap://mesh/{capability}` resource gives the agent the same `peers`,
+`otherSide`, and `neighbours` so it can coordinate before it commits.
+
 ### Grok Bot as a scoped Mesh participant
 
 Grok Bot is a persistent agent, not a coding-agent integration. The iPhone
@@ -182,6 +205,69 @@ The bounded encrypted protocol preserves:
 An optional bounded `errorClass` may describe an error category. Full tool
 error payloads are not copied into usage telemetry by default.
 
+A shell call is named by the command it ran — `npm`, `git`, `xcodebuild` —
+with the tool that ran it kept beside the name, so the usage screen can say
+which tool was slow or failing rather than listing every call as Bash.
+
+Machine load attributes to an agent everything the agent started — its
+shells, its node workers, the build a shell ran — found through the process
+tree, and names the heaviest kinds of process it runs (`node` ×19, `zsh` ×3)
+so the phone can say what an agent is doing, not only that it is. The
+executable path and the command line are read separately and joined by pid,
+because a path with a space in it (`~/Library/Application Support/Claude/…`)
+cannot be recovered from a command line split on whitespace.
+
+### One computer, whatever the network calls it
+
+The Mesh keys a computer by an identity written down once, on first use, in
+`computer.json` in the config directory — the hostname it had then — and
+keeps it. A Mac renamed by the network it joins ("Mac.lan" at home,
+"Serhiis-MacBook-Pro.local" elsewhere) used to become a second computer with
+its own open executions and repository bindings; now every later hostname is
+remembered as a former name of the same machine, its leftover executions are
+closed and its bindings marked unavailable, and the current hostname stays
+what people see. `GRANTTAP_COMPUTER_ID` overrides the stored id.
+
+### Run journal and prompt-time context
+
+A message from the phone is answered by a fresh `claude -p --resume` of the
+same chat. Its turns land in the transcript, but a session holding that chat
+open never sees them — its context was built before they happened. The runtime
+therefore journals every delivery: what was asked (without the attachment
+note), what came back, which files were written, how many tool calls it took,
+and whether the run was cut off by the ten-minute delivery limit. The Task
+carries the same digest as `TASK_PROGRESS`, so the phone's timeline and the
+Mesh show it. A `UserPromptSubmit` hook, installed beside the approval hook by
+`granttap setup`, adds the unread journal to the next prompt of the live
+session together with the Mesh brief — the other live Tasks in the Project,
+who is in the same file or module, the other side of the repository, and any
+question still unanswered — and names the MCP resource `granttap://mesh/map`,
+one page of markdown with the whole Project: Tasks, who edits which module,
+the other side of each repository, dependencies, and what just happened. That
+resource is listed, because Claude Code reads only listed resources, and it is
+scoped without a token: Claude Code starts one MCP server per chat and hands
+it the chat's id in `CLAUDE_CODE_SESSION_ID`, which nothing said over the
+connection can change. `granttap://mesh/current` serves the same chat's scoped
+state there. Other providers keep the tokened `granttap://mesh/{capability}`
+and `…/map` forms from an attributed `notify`. Background runs themselves
+receive nothing from the hook; the journal is kept for the session a person
+is in.
+
+### Tool versions and updates from the phone
+
+The status also names each provider's command-line tool as it answers on this
+computer — its version, how it is kept current, and, for Claude Code, whether a
+newer copy already sits on the disk (the Claude desktop app keeps its own; the
+runtime uses the newest one it finds). A tool that lags the rest of the
+environment fails in ways the phone can only report, so the phone can ask this
+computer to update one: the phone names only the tool, and the command is the
+runtime's, fixed by how the tool was installed — `claude update`, `agent
+update`, `grok update`, the npm that owns the tool's prefix, or Homebrew. The
+runtime never downloads a tool itself; a tool installed by an installer script
+is left to a trusted terminal, with the command spelled out in the answer. The
+result — version before and after, the updater's own output — comes back as
+`tool.update.result`.
+
 Cost is reported as attributed rather than measured, because that is what it
 is. A call is read back from the transcript once it has finished, so it can
 never be measured directly: an MCP server outlives its calls and is sampled
@@ -206,6 +292,34 @@ The user-facing approval modes map to the existing runtime policy:
 
 Legacy custom levels remain compatible but are not part of the primary flow.
 
+## Project Governance
+
+Capabilities are decided per Project, not per task. A policy names an effect —
+`allow`, `ask`, or `deny` — for each kind (skills, MCP servers, shell and
+scripts, file writes, deploy, network), and may name one capability alone: one
+MCP server can be forbidden without forbidding every server. A named rule wins
+over its kind, and a global deny always wins over a Project.
+
+The phone authors the policy and hands it to every Project computer through the
+relay, which holds the encrypted packet until each computer reads its mailbox;
+a computer that was asleep receives it when it returns. Each computer applies
+the policy through the GrantTap Engine, acknowledges the revision it enforces,
+and reports coverage — enforced, observed only, unsupported, or unknown — per
+capability kind, so the phone shows what is actually in force rather than what
+was sent. Revision zero is a Project with no policy yet, and it is reported so
+the first policy can be written.
+
+Evaluation happens in the provider hook before the action runs, with a deadline
+long enough for a busy machine to answer. A missed answer falls back to the
+legacy GrantTap gate rather than to a silent allow, and content never crosses
+to the engine: it receives a capability fingerprint, not the command or file.
+
+A refusal is said where the action was. Each one is written down for its chat,
+and the timeline carries it as a status row naming the rule and the reason,
+beside the call it stopped. On the phone a rule is written where the need for
+it appears: touch and hold a tool on the Project page, or use the Governance
+menu on a tool's call history, to allow, ask, or deny it for the Project.
+
 ## Relay boundary
 
 Pairing and task keys are generated locally. The relay receives opaque routing

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

@@ -12,6 +12,7 @@
  * Fails closed: any error or timeout denies the tool call rather than letting it
  * through unattended — unless GrantTap auto-accept allows it locally.
  */
+import { recordProjectDecision } from "../policy/decision-log";
 import { claudeToRequest, decisionToClaudeOutput, type HookInput } from "../adapters";
 import { isUnanswered, requestApproval } from "../approval";
 import {
@@ -82,6 +83,13 @@ async function handlePreToolUse(input: HookInput): Promise<void> {
     legacyDenyReason: blocked?.reason,
   });
   if (projectDecision.effect === "deny") {
+    // Say so where the action was, not only to the agent.
+    if (input.session_id) {
+      recordProjectDecision(input.session_id, {
+        at: Date.now(), toolName: input.tool_name ?? "tool", reason: projectDecision.reason,
+        ruleId: projectDecision.rule_id,
+      });
+    }
     writePermission("deny", projectDecision.reason);
     return;
   }

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Claude Code UserPromptSubmit hook entry point.
+ *
+ * Registered in ~/.claude/settings.json so that when a person submits a
+ * prompt, this program adds what the chat could not know by itself: the
+ * background runs that answered phone messages in it, and the Mesh brief for
+ * its Task. It never blocks a prompt — anything wrong, and it adds nothing.
+ *
+ *   Reads:  UserPromptSubmit JSON on stdin ({ session_id, prompt, cwd, ... })
+ *   Writes: { hookSpecificOutput: { hookEventName, additionalContext } } on stdout
+ */
+import { promptContext } from "../mesh/prompt-context";
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main(): Promise<void> {
+  // A background run answering the phone is itself a prompt submission; it is
+  // not the live session the journal is kept for.
+  if (process.env.GRANTTAP_DELIVERY) return;
+  const raw = await readStdin();
+  let input: { session_id?: unknown };
+  try {
+    input = JSON.parse(raw) as { session_id?: unknown };
+  } catch {
+    return;
+  }
+  const sessionId = typeof input.session_id === "string" ? input.session_id.trim() : "";
+  const text = promptContext(sessionId);
+  if (!text) return;
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: text },
+  }));
+}
+
+main().catch(() => undefined).finally(() => process.exit(0));

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env -S npx tsx
 /** Codex PreToolUse: deterministic deny or one-shot Project ASK handoff. */
+import { recordProjectDecision } from "../policy/decision-log";
 import type { HookInput } from "../adapters";
 import { blockedSessionCapability, isProviderEnabled } from "../config";
 import { recordCodexProjectAsk } from "../policy/codex-project-ask";
@@ -39,6 +40,11 @@ async function main(): Promise<void> {
     legacyDenyReason: blocked?.reason,
   });
   if (decision.effect === "deny") {
+    if (input.session_id) {
+      recordProjectDecision(input.session_id, {
+        at: Date.now(), toolName: input.tool_name ?? "tool", reason: decision.reason, ruleId: decision.rule_id,
+      });
+    }
     deny(decision.reason);
     return;
   }

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env -S npx tsx
 /** Cursor beforeShellExecution: exact chat block, otherwise phone/native approval. */
+import { recordProjectDecision } from "../policy/decision-log";
 import {
   cursorToRequest,
   decisionToCursorOutput,
@@ -83,6 +84,12 @@ async function handleShell(input: CursorHookInput): Promise<void> {
     legacyDenyReason: blocked?.reason,
   });
   if (projectDecision.effect === "deny") {
+    if (sessionId) {
+      recordProjectDecision(sessionId, {
+        at: Date.now(), toolName: input.tool_name ?? "Shell",
+        reason: projectDecision.reason, ruleId: projectDecision.rule_id,
+      });
+    }
     deny(projectDecision.reason);
     return;
   }

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env -S npx tsx
 /** Cursor beforeMCPExecution: exact server/chat block, otherwise phone/native approval. */
+import { recordProjectDecision } from "../policy/decision-log";
 import { randomId } from "../../../../packages/core/crypto";
 import type { ApprovalRequest } from "../../../../packages/protocol/schema";
 import { decisionToCursorOutput } from "../adapters";
@@ -97,6 +98,12 @@ async function handleMcp(input: CursorMcpHookInput): Promise<void> {
     legacyDenyReason: blocked?.reason,
   });
   if (projectDecision.effect === "deny") {
+    if (sessionId) {
+      recordProjectDecision(sessionId, {
+        at: Date.now(), toolName: server ? `mcp__${server}__${toolName}` : toolName,
+        reason: projectDecision.reason, ruleId: projectDecision.rule_id,
+      });
+    }
     deny(projectDecision.reason);
     return;
   }

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

@@ -0,0 +1,112 @@
+/**
+ * Which Claude Code answers the phone.
+ *
+ * A chat the user opened in the Claude desktop app was written by the Claude
+ * Code the app ships, and an older `claude` on PATH cannot resume it: the API
+ * refuses with "Claude Code X does not support model version Y". The app keeps
+ * its own copies of Claude Code on this Mac, and the native installer keeps
+ * every version it ever installed, so the newest one present is the one to
+ * use. Nothing is downloaded or updated here — the helper never changes the
+ * user's tools — only chosen. An explicit `GRANTTAP_CLAUDE_BIN` still wins.
+ */
+import { accessSync, constants, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { binaryVersion } from "./tools/version";
+
+export type ClaudeBinary = { path: string; version?: string };
+
+function executable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `2.1.260` from an installer's directory name such as `2.1.260`. */
+export function versionOf(segment: string): string | undefined {
+  return /^v?(\d+\.\d+\.\d+)$/.exec(segment.trim())?.[1];
+}
+
+export function compareVersions(left: string, right: string): number {
+  const a = left.split(".").map(Number);
+  const b = right.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    const delta = (a[index] ?? 0) - (b[index] ?? 0);
+    if (delta !== 0) return delta;
+  }
+  return 0;
+}
+
+export function executableOnPath(command: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    const candidate = join(dir, command);
+    if (executable(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function versioned(path: string): ClaudeBinary {
+  // The native installer and the app state the version in the path; any other
+  // install is asked once and remembered until the binary changes.
+  const version = binaryVersion(path);
+  return version ? { path, version } : { path };
+}
+
+function children(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/** Every Claude Code this Mac keeps, newest first; PATH's own `claude` included. */
+export function installedClaudeBinaries(
+  home = homedir(),
+  env: NodeJS.ProcessEnv = process.env,
+): ClaudeBinary[] {
+  const found: ClaudeBinary[] = [];
+  const fromPath = executableOnPath("claude", env);
+  if (fromPath) found.push(versioned(fromPath));
+  const installer = join(home, ".local", "share", "claude", "versions");
+  for (const name of children(installer)) {
+    const path = join(installer, name);
+    if (versionOf(name) && executable(path)) found.push({ path, version: versionOf(name) });
+  }
+  const app = join(home, "Library", "Application Support", "Claude", "claude-code");
+  for (const name of children(app)) {
+    const path = join(app, name, "claude.app", "Contents", "MacOS", "claude");
+    if (versionOf(name) && executable(path)) found.push({ path, version: versionOf(name) });
+  }
+  return found.sort((left, right) => {
+    if (left.version && right.version) return compareVersions(right.version, left.version);
+    return left.version ? -1 : right.version ? 1 : 0;
+  });
+}
+
+/**
+ * The Claude Code to run: the explicit override, else the newest installed,
+ * else plain `claude` for PATH to resolve.
+ */
+export function resolveClaudeBinary(
+  home = homedir(),
+  env: NodeJS.ProcessEnv = process.env,
+): ClaudeBinary {
+  const override = env.GRANTTAP_CLAUDE_BIN ?? env.NODVOX_CLAUDE_BIN;
+  if (override) return versioned(override);
+  return installedClaudeBinaries(home, env)[0] ?? { path: "claude" };
+}
+
+/**
+ * The failure a too-old Claude Code reports, with the way out attached: the
+ * version that answered, and the one command that replaces it.
+ */
+export function explainClaudeFailure(error: string, binary: ClaudeBinary): string {
+  if (!/does not support|not supported|outdated|update claude code|upgrade/i.test(error)) return error;
+  const which = binary.version ? `Claude Code ${binary.version}` : "This Claude Code";
+  return `${error.trim()} — ${which} at ${binary.path} is older than this chat needs. `
+    + "Run `claude update` on this Mac, or open the chat in the Claude app once so its newer Claude Code is present.";
+}

package/apps/bridge/src/install.ts

@@ -18,6 +18,8 @@ import {
   readFileSync,
   writeFileSync,
 } from "node:fs";
+import { resolveClaudeBinary } from "./claude-bin";
+import { describeCommand, inspectTools, updatingTools } from "./tools/updater";
 import { resolveCursorAgentBin } from "./reply/cursor-agent-bin";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
@@ -31,6 +33,7 @@ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..")
 
 export type HookRoute =
   | "claude"
+  | "claude-prompt"
   | "codex"
   | "codex-policy"
   | "cursor"
@@ -60,6 +63,10 @@ export type AgentIntegrationStatus = {
   agent: CodingAgent;
   installed: boolean;
   hookConfigured: boolean;
+  version?: string;
+  updateCommand?: string;
+  newerOnThisMac?: string;
+  updating?: boolean;
 };
 
 function executableAvailable(command: string): boolean {
@@ -244,17 +251,28 @@ export function inspectCursorIntegration(): CursorIntegrationStatus {
 /** Read-only capability check used by phone/watch connection states. */
 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 claude = resolveClaudeBinary().path;
   const cursor = process.env.GRANTTAP_CURSOR_AGENT_BIN ?? resolveCursorAgentBin();
   const grok = process.env.GRANTTAP_GROK_BIN ?? "grok";
   const cursorStatus = inspectCursorIntegration();
+  const tools = new Map(inspectTools().map((tool) => [tool.agent, tool]));
+  const updating = new Set(updatingTools());
+  const tool = (agent: CodingAgent): Partial<AgentIntegrationStatus> => {
+    const status = tools.get(agent);
+    const extra: Partial<AgentIntegrationStatus> = {};
+    if (status?.version) extra.version = status.version;
+    if (status?.update) extra.updateCommand = describeCommand(status.update);
+    if (status?.newerOnThisMac) extra.newerOnThisMac = status.newerOnThisMac;
+    if (updating.has(agent)) extra.updating = true;
+    return extra;
+  };
   return [
-    { agent: "codex", installed: executableAvailable(codex), hookConfigured: codexHookConfigured() },
-    { agent: "claude", installed: executableAvailable(claude), hookConfigured: claudeHookConfigured() },
-    { agent: "cursor", installed: executableAvailable(cursor), hookConfigured: cursorStatus.hookConfigured },
+    { agent: "codex", installed: executableAvailable(codex), hookConfigured: codexHookConfigured(), ...tool("codex") },
+    { agent: "claude", installed: executableAvailable(claude), hookConfigured: claudeHookConfigured(), ...tool("claude") },
+    { agent: "cursor", installed: executableAvailable(cursor), hookConfigured: cursorStatus.hookConfigured, ...tool("cursor") },
     // 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 },
+    { agent: "grok", installed: executableAvailable(grok), hookConfigured: false, ...tool("grok") },
   ];
 }
 
@@ -550,6 +568,10 @@ export function installClaudeHook(): InstallResult {
     }
   }
 
+  // The prompt hook rides along with the approval hook: what the chat could
+  // not know by itself — background runs in it, the Mesh around it — is added
+  // to each prompt. It never blocks; anything wrong, and it adds nothing.
+  const promptHookChanged = ensureClaudePromptHook(settings);
   const entries: any[] = (((settings.hooks ??= {}).PreToolUse ??= []) as any[]);
   const currentCommand = hookCommand("claude");
   const presentEntry = entries.find((entry) =>
@@ -563,11 +585,14 @@ export function installClaudeHook(): InstallResult {
   if (present && presentEntry) {
     const matcherChanged = repairClaudeMatcher(presentEntry);
     const commandChanged = present.command !== currentCommand;
-    if (!matcherChanged && !commandChanged) return { status: "already", detail: path };
+    if (!matcherChanged && !commandChanged && !promptHookChanged) return { status: "already", detail: path };
     backupOnce(path);
     present.command = currentCommand;
     writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
-    return { status: "installed", detail: `${path}, GrantTap hook and matcher repaired` };
+    const detail = !matcherChanged && !commandChanged
+      ? `${path}, GrantTap prompt hook added`
+      : `${path}, GrantTap hook and matcher repaired`;
+    return { status: "installed", detail };
   }
 
   const legacyEntry = entries.find((entry) =>
@@ -597,6 +622,22 @@ export function installClaudeHook(): InstallResult {
   return { status: "installed", detail: path };
 }
 
+/** Make sure the UserPromptSubmit hook is registered once, at the current command. */
+function ensureClaudePromptHook(settings: any): boolean {
+  const entries: any[] = (((settings.hooks ??= {}).UserPromptSubmit ??= []) as any[]);
+  const command = hookCommand("claude-prompt");
+  const present = entries
+    .flatMap((entry) => (Array.isArray(entry?.hooks) ? entry.hooks : []))
+    .find((hook: any) => commandHasRoute(hook?.command, "claude-prompt"));
+  if (present) {
+    if (present.command === command) return false;
+    present.command = command;
+    return true;
+  }
+  entries.push({ hooks: [{ type: "command", command, timeout: 10 }] });
+  return true;
+}
+
 // --------------------------------------------------------------------- Codex
 
 function rewriteDisabledCodexHooks(config: string): { config: string; changed: boolean } {

package/apps/bridge/src/machine-load/index.ts

@@ -84,6 +84,7 @@ export function buildMachineLoad(input: {
         processes: input.processes[agent]?.processes ?? 0,
         cpuPercent: input.processes[agent]?.cpuPercent ?? 0,
         memoryBytes: input.processes[agent]?.memoryBytes ?? 0,
+        topProcesses: input.processes[agent]?.groups ?? [],
         sessions: sessionsByAgent.get(agent) ?? 0,
         scanMs: scanCost[agent]?.durationMs ?? 0,
         tokensRecent: tokensByAgent.get(agent) ?? 0,