granttap-mcp 0.8.24 → 0.8.30

package/README.md

@@ -4,24 +4,26 @@
 [![CI](https://github.com/sergii-ziborov/granttap-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sergii-ziborov/granttap-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-GrantTap is a Personal live control center for local coding agents.
+GrantTap is a distributed Project control system for local coding agents.
 
 > See what your coding agents are doing. Step in when they need you.
 
 This repository is the canonical machine runtime: CLI, MCP server, provider
-hooks, local adapters, and TypeScript wire schemas. Agents and provider
-credentials stay on your computer. Native iPhone and Apple Watch traffic is
-end-to-end encrypted.
+hooks, local adapters, and TypeScript wire schemas. It connects the Mac,
+iPhone, iPad, and Apple Watch product surfaces to local agents, Project Mesh,
+Governance, auto-accept, and Engine-backed evidence. Agents and provider
+credentials stay on your computer. Native controller traffic is end-to-end
+encrypted.
 
-The MCP runtime, plugins, and CLI are open source under the MIT License. The
-iPhone and Apple Watch app is a separate, proprietary product; use of GrantTap's
-hosted service is governed by its own terms.
+The MCP runtime, plugins, and CLI are open source under the MIT License.
+The Apple apps, Engine, relay, and website are separately licensed commercial
+products or source. Their licenses do not change this repository's MIT grant.
 
 [Website](https://granttap.com) · [npm](https://www.npmjs.com/package/granttap-mcp) ·
 [Security model](SECURITY.md) ·
 [Relay source](https://github.com/sergii-ziborov/granttap-relay)
 
-## iPhone and Apple Watch
+## Mac, iPhone, iPad, and Apple Watch
 
 <p align="center">
   <img src="docs/images/iphone-command-center.png" width="230" alt="GrantTap Now with Needs You and at-risk tasks">
@@ -43,6 +45,22 @@ hosted service is governed by its own terms.
 GrantTap reports the depth each provider actually exposes. Visibility does not
 imply deterministic remote blocking or full mobile continuation.
 
+The Mac app checks this runtime's local health endpoint without account login
+or QR scanning. A Mac App Store sandbox build then asks for explicit local
+access using the runtime's bounded PKCE consent flow; development builds retain
+private Unix IPC. Mac Settings can configure encrypted address discovery or
+install/start/stop the pinned personal relay. Runtime code remains outside the
+Apple sandbox. Mac purchase terms, optional Personal subscriptions and required
+TLS/VPN reachability are documented in the Apple client repository.
+The local HTTP MCP OAuth flow can be approved with a fresh GrantTap account
+passkey on Mac. This authorizes the selected coding app to use this computer's
+MCP endpoint; it does not pair a phone. Direct QR pairing remains available
+without a GrantTap account.
+The iPhone and iPad app provides the mobile Project controller;
+Apple Watch carries the compact attention and reply flow through iPhone.
+The machine runtime and separately distributed Engine supply Project records,
+policy coverage, Invocation history, and the distributed evidence graph.
+
 Session catalogs report `lastMessageAt` only when a provider transcript has a
 timestamped user or assistant message. `lastActivityAt` remains the separate
 runtime activity timestamp and can include metadata or file updates. Clients
@@ -187,6 +205,17 @@ of a topic it produces, the caller of an API it changes), and the scoped
 
 A Project is shared from the phone that owns it, and that phone stays the
 hub: nothing a member does reaches a computer without passing through it.
+The owner manages **company accounts** and repository grants separately from
+Project Mesh membership. An account can cover selected repository IDs or all
+company repositories; it does not join a Mesh merely because it has repository
+access. A phone or tablet may pair to the account before any computer or
+Project exists, with zero Project permissions. The owner then grants selected
+Project IDs and a role to that device. Several devices may use the same account with different
+Mesh grants. Before the phone forwards a complete Project snapshot, its key,
+chats, or actions, the account must cover every repository ID in that Project.
+Linked sub-Mesh Projects still require separate selection. These owner-phone
+grants do not edit Git provider ACLs or give the MCP a company login.
+
 *Invite a person* makes a one-time code, good for fifteen minutes; the other
 phone scans it under *Projects → Join a Project*, and the Project arrives
 there with the role the owner chose — Viewer, Member, or Admin — and the four
@@ -198,13 +227,16 @@ a role takes effect at once; removing a member stops the forwarding at once,
 though nothing already seen can be recalled.
 
 <p align="center">
+  <img src="docs/images/iphone-company-accounts.png" width="200" alt="Company accounts separate from Mesh device links">
+  <img src="docs/images/iphone-company-repositories.png" width="200" alt="Selected repository IDs for one company account">
+  <img src="docs/images/iphone-company-device-invite.png" width="200" alt="Controller device code before any Mesh Project grant">
   <img src="docs/images/iphone-members.png" width="200" alt="Members and computers of a Project, seen by its owner">
   <img src="docs/images/iphone-invite.png" width="200" alt="Invite a person: name, role, and the four answers under it">
   <img src="docs/images/iphone-join-project.png" width="200" alt="Join a Project from another phone: scan the invite or paste it">
   <img src="docs/images/iphone-members-shared.png" width="200" alt="A shared Project on the member's phone, with a computer of their own to add">
 </p>
 
-<p align="center"><em>The owner's members and computers · an invite with its role · joining from another phone · the shared Project as the member sees it, with a computer of their own to add</em></p>
+<p align="center"><em>Company accounts and repository grants · separate Mesh members and device links · joining from another phone</em></p>
 
 A member works in the Project with computers of their own. Adding one hands
 it the Project's mesh key over the pairing the member's phone already trusts,
@@ -214,7 +246,12 @@ Task can be handed to it.
 
 A Project can pin new tasks to one confirmed computer. The endpoint id is
 the stored computer identity, not the display name. Models offered on the
-phone come from that host's catalog. If the pinned host is offline, the
+phone come from that host's catalog. Codex picker metadata is read from the
+installed provider's account-scoped model cache, refreshed on each catalog
+cycle. Visible models keep their descriptions, provider ordering and fetch
+timestamp; hidden review/internal models are excluded. Expired data stays
+unknown. Local Mac replies, like relay replies, pass the chosen model to the
+existing native session. If the pinned host is offline, the
 Project either refuses the create or queues it until a deadline — it does
 not silently start the task elsewhere. A command issued for a previous
 instance of the computer (a restore or clone that kept pairing keys) is
@@ -570,6 +607,9 @@ npm run package:allowlist
 npm run test:coverage   # macOS only — see below
 ```
 
+Set `GRANTTAP_TEST_CONCURRENCY=1` when running checks alongside heavy builds;
+the default is four test workers, and the same assertions and coverage gates apply.
+
 `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
@@ -585,8 +625,19 @@ typecheck, and release checks pass.
 ## License
 
 GrantTap MCP, its CLI, and bundled plugins are distributed under the
-[MIT License](LICENSE). The iPhone and Apple Watch app is licensed separately.
+[MIT License](LICENSE). The Mac, iPhone, iPad, and Apple Watch apps are licensed separately.
 Third-party dependencies retain their own terms; see
 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
 GrantTap is not affiliated with Anthropic, OpenAI, Apple, Anysphere, or xAI.
+
+## Repository facts and execution checkout
+
+Version 0.8.29 adds optional encrypted repository Git observations: canonical
+identity, branch/HEAD, dirty state, recent commits, contributors and branch
+totals. Both phone publication and the native Mac reader use the same bounded
+read-only Git source. Missing data is explicit. Claude and Codex can detect
+sustained structured work in a different checkout without interpreting chat
+titles. Task identity and its original coordination/access scope survive.
+
+See [repository observations](apps/bridge/src/mesh/repository-details/README.md).

package/THIRD_PARTY_NOTICES.md

@@ -21,3 +21,10 @@ The unpublished Rust workspace also depends on separately licensed components,
 including `mcport` (MIT), `blazingly-json` (MIT), `serde` (MIT OR Apache-2.0), and
 BlindPlane crates (MIT OR Apache-2.0). Binary distributions must retain the
 complete license texts required by the exact dependency versions they contain.
+
+## Optional SweepLoom integration
+
+Provider storage inspection may invoke a separately installed SweepLoom CLI
+([source](https://github.com/Weavatrix/sweeploom), MPL-2.0). No SweepLoom source or
+binary is included in this npm package. Its license remains independent; the
+GrantTap MIT license does not apply to SweepLoom.

package/apps/bridge/src/approvals/index.ts

@@ -20,6 +20,7 @@ import {
 } from "./state";
 import { primeSessionKeys, sendSessionPayload } from "../host/session-keys";
 import { controllerPeerGate } from "../pairing/controllers";
+import { applyNetworkRoute } from "../device-network/settings";
 
 /**
  * Nobody answered — relay unreachable, or the phone never responded before the
@@ -45,7 +46,7 @@ export async function requestApproval(
   opts: RequestApprovalOpts = {},
 ): Promise<ApprovalDecision> {
   const timeoutMs = opts.timeoutMs ?? 60_000;
-  const client = opts.client ?? new RelayClient(cfg, { peerAllowed: controllerPeerGate(cfg) });
+  const client = opts.client ?? new RelayClient(applyNetworkRoute(cfg), { peerAllowed: controllerPeerGate(cfg) });
   const ownsClient = !opts.client;
   let cancelDecisionWait = () => {};
   const registration = registerPendingApproval(req);

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

@@ -1,3 +1,4 @@
+import { refreshCodexHooks, codexHooksReady } from "../../codex-hook-trust";
 import QRCode from "qrcode";
 import {
   CODEX_TRUST_INSTRUCTION,
@@ -75,6 +76,7 @@ async function main(): Promise<void> {
       cursorConfig = removeCursorUserGrantTap();
     }
   }
+  const codexTrust = await refreshCodexHooks(true);
   const pairingResult = await pairIfNeeded();
   const paired = isMachineConfigured();
   const installed = new Set(before.agents.filter((item) => item.installed).map((item) => item.agent));
@@ -93,7 +95,7 @@ async function main(): Promise<void> {
         ? "Needs attention" : "Authorize in Claude Code" : "Not installed"}`,
     `Codex               ${installed.has("codex")
       ? codexHook.status === "manual" || httpService?.status === "manual"
-        ? "Needs attention" : !paired ? "Needs connection" : "Authorize in Codex; review hooks"
+        ? "Needs attention" : !paired ? "Needs connection" : codexHooksReady(codexTrust.hooks) ? "Hooks trusted and enabled" : "Authorize in Codex; review hooks"
       : "Not installed"}`,
     `Cursor              ${before.cursor.installed ? `Beta · ${cursorReady ? "Use GrantTap plugin" : "Needs repair"}` : "Not installed"}`,
     `Grok Build          ${installed.has("grok")
@@ -104,7 +106,8 @@ async function main(): Promise<void> {
     `Project Governance  ${engine ? "Ready" : "No engine found"}`,
     "",
     paired && installed.has("codex")
-      ? `Next: authorize GrantTap in Codex, then ${CODEX_TRUST_INSTRUCTION}`
+      ? codexHooksReady(codexTrust.hooks) ? "Codex confirmed both GrantTap hooks are trusted and enabled."
+        : `Next: review GrantTap hooks in GrantTap Settings → This Mac → Codex hooks, or ${CODEX_TRUST_INSTRUCTION}`
       : paired && before.cursor.installed
         ? "Next: keep the GrantTap plugin. Pair and change settings in the GrantTap app, not Cursor MCP settings."
         : !paired

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

@@ -10,6 +10,7 @@ import {
 import { isProviderEnabled, loadConfig, machineConfigPath } from "../../config";
 import { cursorRootSessionId } from "../../sessions/cursor";
 import { controllerPeerGate } from "../../pairing/controllers";
+import { applyNetworkRoute } from "../../device-network/settings";
 
 const SHELL_TOOLS = new Set([
   "bash",
@@ -77,7 +78,7 @@ async function main(): Promise<void> {
   if (cancelled.length > 0) {
     try {
       const config = loadConfig(machineConfigPath());
-      const client = new RelayClient(config, { peerAllowed: controllerPeerGate(config) });
+      const client = new RelayClient(applyNetworkRoute(config), { peerAllowed: controllerPeerGate(config) });
       await client.connect();
       try {
         for (const { request, accepted } of cancelled) {

package/apps/bridge/src/bin/runtime/monitor.ts

@@ -7,20 +7,24 @@ import { meshSnapshots } from "../../mesh/runtime";
 import { recoverLocalGraphBindings } from "../../mesh/runtime/graph/binding-sync";
 import { startSessionMonitor } from "../../monitor";
 import { controllerPeerGate } from "../../pairing/controllers";
+import { applyNetworkRoute } from "../../device-network/settings";
+import { startEndpointPublisher } from "../../device-network/directory";
 
 let client: RelayClient;
 let monitor: ReturnType<typeof startSessionMonitor>;
 const engine = new EngineSupervisor();
 let stopping = false;
+let stopEndpointPublisher = () => {};
 
 try {
-  const cfg = loadConfig(machineConfigPath());
+  const cfg = applyNetworkRoute(loadConfig(machineConfigPath()));
   client = new RelayClient(cfg, {
     autoReconnect: true,
     replayPath: join(configDir(), `replay-${cfg.room}.json`),
     peerAllowed: controllerPeerGate(cfg),
   });
   monitor = startSessionMonitor(client);
+  stopEndpointPublisher = startEndpointPublisher(cfg);
 } catch (error) {
   process.stderr.write(
     `[granttap-mcp] monitor is not paired: ${error instanceof Error ? error.message : String(error)}\n`,
@@ -32,6 +36,7 @@ const stop = (): void => {
   if (stopping) return;
   stopping = true;
   monitor.close();
+  stopEndpointPublisher();
   client.close();
   void engine.stop().finally(() => process.exit(0));
 };

package/apps/bridge/src/capabilities/skills.ts

@@ -184,6 +184,22 @@ function clipSkillText(value: string | undefined, max: number): string | undefin
   return trimmed.length > max ? trimmed.slice(0, max) : trimmed;
 }
 
+function skillDescription(header: string): string | undefined {
+  const lines = header.split("\n");
+  const index = lines.findIndex((line) => /^description:\s*/.test(line));
+  if (index < 0) return undefined;
+  const scalar = lines[index]!.replace(/^description:\s*/, "").trim();
+  if (!/^[>|][+-]?$/.test(scalar)) {
+    return clipSkillText(scalar.replace(/^["']|["']$/g, ""), 500);
+  }
+  const parts: string[] = [];
+  for (const line of lines.slice(index + 1)) {
+    if (line.trim() && !/^\s/.test(line)) break;
+    parts.push(line.trim());
+  }
+  return clipSkillText(parts.join(scalar.startsWith(">") ? " " : "\n"), 500);
+}
+
 function readSkillFile(path: string): {
   name: string;
   description?: string;
@@ -197,7 +213,7 @@ function readSkillFile(path: string): {
     const header = body.slice(3, end);
     const name = header.match(/^name:\s*["']?([^\n"']+)["']?\s*$/m)?.[1]?.trim();
     if (!name) return undefined;
-    const description = header.match(/^description:\s*["']?([^\n"']+)["']?\s*$/m)?.[1]?.trim();
+    const description = skillDescription(header);
     const version = header.match(/^version:\s*["']?([^\n"']+)["']?\s*$/m)?.[1]?.trim();
     return {
       name: name.slice(0, 160),

package/apps/bridge/src/codex-hook-trust/README.md

@@ -0,0 +1,34 @@
+# Codex hook review
+
+Public entry point: [`index.ts`](index.ts).
+
+GrantTap reads native Codex `hooks/list` metadata to distinguish configuration,
+current-definition trust, and enabled state. Only the two exact user hooks
+installed by this runtime (`PreToolUse` and `PermissionRequest`) can be reviewed.
+Project, plugin, managed, ambiguous, or unrelated commands are never approved.
+Unsupported native APIs report unknown; configured hooks alone do not establish
+readiness or computer enforcement.
+
+The monitor and desktop status endpoint share a bounded cache. Computers with no
+GrantTap hook definition do not start Codex. When a native status probe is needed,
+Codex may maintain its own runtime caches; GrantTap does not edit hook configuration
+or trust during inspection. The subprocess starts no threads or turns.
+
+A person approves one displayed definition on one computer. `trustCodexHook`
+checks the computer, five-minute request lifetime, native key, and current hash,
+then uses Codex's `config/batchWrite` API to save that hash and enabled state.
+Success requires a fresh native report confirming the same key and hash are
+trusted and enabled. Modified definitions require a new review. No bulk trust,
+sandbox bypass, or approval-policy change is performed.
+
+Remote requests require the paired controller and matching room. Results return
+only to that controller. Mac uses the existing private desktop Engine socket.
+Legacy clients retain their configuration status without claiming native trust.
+
+Tests live in `tests/`. The native integration test runs only when
+`GRANTTAP_CODEX_TEST_BIN` names a Codex binary and uses a temporary Codex home.
+It never trusts hooks in the user's configuration.
+
+## License
+
+This module is distributed under the MIT License. See the repository LICENSE.

package/apps/bridge/src/codex-hook-trust/config.ts

@@ -0,0 +1,79 @@
+import { ownedHookCommands } from "./projection";
+
+export function codexHookSet(config: string): { permission: boolean; policy: boolean } {
+  type Event = "PermissionRequest" | "PreToolUse";
+  let event: Event | null = null;
+  let matcherAll = false;
+  let inCommandHook = false;
+  let commandType = false;
+  let command: string | null = null;
+  let timeout: number | null = null;
+  let permission = false;
+  let policy = false;
+  const finishCommandHook = () => {
+    if (!event || !matcherAll || !inCommandHook || !commandType) return;
+    if (event === "PermissionRequest"
+      && timeout === 120
+      && command === ownedHookCommands().permission) {
+      permission = true;
+    }
+    if (event === "PreToolUse"
+      && timeout === 30
+      && command === ownedHookCommands().policy) {
+      policy = true;
+    }
+  };
+  for (const line of config.split(/\r?\n/)) {
+    const parent = line.match(/^\s*\[\[hooks\.(PermissionRequest|PreToolUse)\]\]\s*(?:#.*)?$/i);
+    if (parent) {
+      finishCommandHook();
+      event = parent[1]!.toLowerCase() === "permissionrequest"
+        ? "PermissionRequest"
+        : "PreToolUse";
+      matcherAll = false;
+      inCommandHook = false;
+      commandType = false;
+      command = null;
+      timeout = null;
+      continue;
+    }
+    const child = line.match(
+      /^\s*\[\[hooks\.(PermissionRequest|PreToolUse)\.hooks\]\]\s*(?:#.*)?$/i,
+    );
+    if (child) {
+      finishCommandHook();
+      const childEvent: Event = child[1]!.toLowerCase() === "permissionrequest"
+        ? "PermissionRequest"
+        : "PreToolUse";
+      inCommandHook = event === childEvent;
+      commandType = false;
+      command = null;
+      timeout = null;
+      continue;
+    }
+    if (/^\s*\[/.test(line)) {
+      finishCommandHook();
+      event = null;
+      matcherAll = false;
+      inCommandHook = false;
+      commandType = false;
+      command = null;
+      timeout = null;
+      continue;
+    }
+    if (event && !inCommandHook) {
+      const matcher = line.match(/^\s*matcher\s*=\s*["'](.*)["']\s*(?:#.*)?$/i)?.[1];
+      if (matcher != null) matcherAll = matcher.trim() === ".*";
+    } else if (inCommandHook) {
+      const type = line.match(/^\s*type\s*=\s*["'](.*)["']\s*(?:#.*)?$/i)?.[1];
+      if (type != null) commandType = type.trim().toLowerCase() === "command";
+      const value = line.match(/^\s*command\s*=\s*["'](.*)["']\s*(?:#.*)?$/i)?.[1];
+      if (value != null) command = value;
+      const rawTimeout = line.match(/^\s*timeout\s*=\s*(\d+)\s*(?:#.*)?$/i)?.[1];
+      if (rawTimeout != null) timeout = Number(rawTimeout);
+    }
+  }
+  finishCommandHook();
+  return { permission, policy };
+}
+

package/apps/bridge/src/codex-hook-trust/index.ts

@@ -0,0 +1,59 @@
+import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ProviderHook } from "../../../../packages/protocol/messages/provider-hooks";
+import { codexHookRpc, type HookRpc } from "./rpc";
+import { projectCodexHooks } from "./projection";
+import { codexHookSet } from "./config";
+
+export { codexHookRpc, type HookRpc, type HookRpcOptions } from "./rpc";
+export { projectCodexHooks, ownedHookCommands, codexPolicyReady, codexHooksReady } from "./projection";
+export { codexHookSet } from "./config";
+export { trustCodexHook } from "./trust";
+
+export type CodexHookReport = { hooks: ProviderHook[]; checkedAt: number };
+let report: CodexHookReport | undefined;
+let pending: Promise<CodexHookReport> | undefined;
+let cacheScope = "";
+
+function scope(): string {
+  return [process.env.GRANTTAP_CODEX_DIR, process.env.NODVOX_CODEX_DIR, process.env.CODEX_HOME,
+    process.env.GRANTTAP_CODEX_BIN, homedir()].join("\u001f");
+}
+
+function hasUserHook(): boolean {
+  const home = process.env.GRANTTAP_CODEX_DIR ?? process.env.NODVOX_CODEX_DIR ??
+    process.env.CODEX_HOME ?? join(homedir(), ".codex");
+  try {
+    const hooks = codexHookSet(readFileSync(join(home, "config.toml"), "utf8"));
+    return hooks.policy || hooks.permission;
+  } catch { return false; }
+}
+
+export async function readCodexHooks(rpc: HookRpc = codexHookRpc()): Promise<CodexHookReport> {
+  try {
+    return { hooks: projectCodexHooks(await rpc("hooks/list", { cwds: [homedir()] })), checkedAt: Date.now() };
+  } catch {
+    return { hooks: projectCodexHooks(null), checkedAt: Date.now() };
+  }
+}
+
+export function cachedCodexHooks(): CodexHookReport | undefined {
+  return cacheScope === scope() && report && Date.now() - report.checkedAt <= 45_000 ? report : undefined;
+}
+
+/** Bound subprocess work on both the monitor and loopback status poll. */
+export function refreshCodexHooks(force = false): Promise<CodexHookReport> {
+  const currentScope = scope();
+  if (currentScope !== cacheScope) { report = undefined; cacheScope = currentScope; }
+  if (pending) return pending;
+  if (!force && report && Date.now() - report.checkedAt < 15_000) return Promise.resolve(report);
+  // Do not initialize Codex or its cache on computers with no GrantTap hook definition.
+  pending = (hasUserHook() ? readCodexHooks() : Promise.resolve({
+    hooks: projectCodexHooks({ data: [{ hooks: [] }] }), checkedAt: Date.now(),
+  })).then(value => { if (currentScope === scope()) report = value; return value; })
+    .finally(() => { pending = undefined; });
+  return pending;
+}
+
+export { handleHookTrust } from "./relay";

package/apps/bridge/src/codex-hook-trust/projection.ts

@@ -0,0 +1,44 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ProviderHook, type ProviderHook as Hook } from "../../../../packages/protocol/messages/provider-hooks";
+
+export function ownedHookCommands() {
+  const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+  const base = `node "${join(root, "bin", "granttap-mcp.mjs")}" internal hook`;
+  return { policy: `${base} codex-policy`, permission: `${base} codex` };
+}
+
+/** Only the two exact user-config hooks installed by this runtime are reviewable. */
+export function projectCodexHooks(value: unknown): Hook[] {
+  const commands = ownedHookCommands();
+  const report = value as { data?: Array<{ hooks?: any[]; errors?: unknown[] }> } | null;
+  const data = Array.isArray(report?.data) ? report.data : [];
+  return (["PreToolUse", "PermissionRequest"] as const).map((event) => {
+    const missing: Hook = { event, trustStatus: data.length ? "missing" : "unknown", enabled: false };
+    if (data.length !== 1 || (data[0]?.errors?.length ?? 0) > 0) {
+      return { ...missing, trustStatus: "unknown" };
+    }
+    const rows = Array.isArray(data[0]?.hooks) ? data[0]!.hooks! : [];
+    const candidates = rows.filter((row) => row?.eventName === (event === "PreToolUse" ? "preToolUse" : "permissionRequest")
+      && row.handlerType === "command" && row.source === "user" && row.isManaged === false
+      && row.command === commands[event === "PreToolUse" ? "policy" : "permission"]
+      && row.matcher === ".*" && row.timeoutSec === (event === "PreToolUse" ? 30 : 120));
+    if (candidates.length !== 1) return missing;
+    const row = candidates[0];
+    const parsed = ProviderHook.safeParse({ event, enabled: row.enabled, trustStatus: row.trustStatus,
+      key: row.key, currentHash: row.currentHash, command: row.command });
+    if (!parsed.success || !parsed.data.key || !parsed.data.currentHash) {
+      return { ...missing, trustStatus: "unknown" };
+    }
+    return parsed.data;
+  });
+}
+
+export function codexPolicyReady(hooks?: Hook[]): boolean {
+  return hooks?.some(row => row.event === "PreToolUse" && row.enabled && row.trustStatus === "trusted") ?? false;
+}
+
+export function codexHooksReady(hooks?: Hook[]): boolean {
+  return hooks?.length === 2 && new Set(hooks.map(row => row.event)).size === 2
+    && hooks.every(row => row.enabled && row.trustStatus === "trusted");
+}

package/apps/bridge/src/codex-hook-trust/relay.ts

@@ -0,0 +1,24 @@
+import type { RelayClient } from "../../../../packages/core/relay-client";
+import type { ProviderHookTrust } from "../../../../packages/protocol/messages/provider-hooks";
+import { loadConfig, machineConfigPath } from "../config";
+import { observedComputerId } from "../mesh/identity/computer";
+import { trustCodexHook } from "./trust";
+import { refreshCodexHooks } from "./index";
+
+export async function handleHookTrust(
+  client: RelayClient, request: ProviderHookTrust, peerPublicKey: string | undefined,
+  publish: () => Promise<void>,
+): Promise<boolean> {
+  if (!peerPublicKey) return false;
+  try {
+    const machine = loadConfig(machineConfigPath());
+    if (machine.role !== "machine" || machine.room !== client.room
+      || (machine.peerPublicKey !== peerPublicKey && !machine.extraPeerPublicKeys?.includes(peerPublicKey))) return false;
+    const result = await trustCodexHook(request, observedComputerId());
+    if (!result) return false;
+    await client.sendToPeer(result, peerPublicKey);
+    if (result.ok) await refreshCodexHooks(true);
+    void publish().catch(() => {});
+    return true;
+  } catch { return false; }
+}

package/apps/bridge/src/codex-hook-trust/rpc.ts

@@ -0,0 +1,55 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { resolveCodexBinary } from "../providers/codex-bin";
+
+export type HookRpcOptions = { binary?: string; cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number };
+export type HookRpc = (method: string, params: unknown) => Promise<unknown>;
+
+/** No threads or turns are created, and no hook commands are executed. */
+export function codexHookRpc(options: HookRpcOptions = {}): HookRpc {
+  return (method, params) => new Promise((resolve, reject) => {
+    const env = options.env ?? process.env;
+    const codexHome = env.GRANTTAP_CODEX_DIR ?? env.NODVOX_CODEX_DIR ?? env.CODEX_HOME;
+    const child = spawn(options.binary ?? resolveCodexBinary(homedir(), env), ["app-server", "--listen", "stdio://"], {
+      cwd: options.cwd ?? homedir(), env: { ...env, ...(codexHome ? { CODEX_HOME: codexHome } : {}) },
+      stdio: ["pipe", "pipe", "ignore"],
+    });
+    const lines = createInterface({ input: child.stdout });
+    let bytes = 0;
+    let finished = false;
+    const finish = (value?: unknown, failed = false) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      lines.close();
+      child.stdin.destroy();
+      child.kill("SIGTERM");
+      if (failed) reject(new Error("Codex hook status is unavailable."));
+      else resolve(value);
+    };
+    const timer = setTimeout(() => finish(undefined, true), options.timeoutMs ?? 5_000);
+    const send = (message: unknown) => child.stdin.write(JSON.stringify(message) + "\n");
+    child.stdin.on("error", () => finish(undefined, true));
+    child.on("error", () => finish(undefined, true));
+    child.on("close", () => finish(undefined, true));
+    lines.on("line", (line) => {
+      bytes += Buffer.byteLength(line);
+      if (bytes > 2_000_000) return finish(undefined, true);
+      let message: any;
+      try { message = JSON.parse(line); } catch { return; }
+      if (!message || typeof message !== "object" || Array.isArray(message)) return;
+      if (message.id === 1) {
+        if (message.error) return finish(undefined, true);
+        send({ method: "initialized", params: {} });
+        send({ id: 2, method, params });
+      } else if (message.id === 2) {
+        finish(message.result, Boolean(message.error));
+      }
+    });
+    send({ id: 1, method: "initialize", params: {
+      clientInfo: { name: "granttap_hook_review", title: "GrantTap", version: "0.8.28" },
+      capabilities: { experimentalApi: true },
+    } });
+  });
+}

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

@@ -0,0 +1,42 @@
+import { homedir } from "node:os";
+import { ProviderHookTrust, type ProviderHookTrustResult } from "../../../../packages/protocol/messages/provider-hooks";
+import { codexHookRpc, type HookRpc } from "./rpc";
+import { projectCodexHooks } from "./projection";
+
+/** A person approves one displayed definition; no bulk trust or sandbox bypass. */
+export async function trustCodexHook(
+  input: unknown, endpointId: string, rpc: HookRpc = codexHookRpc(), now = Date.now(),
+): Promise<ProviderHookTrustResult | undefined> {
+  const parsed = ProviderHookTrust.safeParse(input);
+  if (!parsed.success) return undefined;
+  const request = parsed.data;
+  let hooks = projectCodexHooks(null);
+  const result = (ok: boolean, message: string): ProviderHookTrustResult => ({
+    type: "provider.hook.trust.result", agent: "codex", endpointId, requestId: request.requestId,
+    ok, message, hooks, checkedAt: Date.now(),
+  });
+  if (request.endpointId !== endpointId || Math.abs(now - request.createdAt) > 5 * 60_000) {
+    return result(false, "Hook approval expired or targets another computer. Refresh and review again.");
+  }
+  try {
+    hooks = projectCodexHooks(await rpc("hooks/list", { cwds: [homedir()] }));
+    const current = hooks.find(row => row.event === request.event);
+    if (!current?.command || current.key !== request.key || current.currentHash !== request.currentHash) {
+      return result(false, "The hook changed or is unavailable. Refresh and review the current definition.");
+    }
+    const keyPath = `hooks.state.${JSON.stringify(current.key)}`;
+    const write = await rpc("config/batchWrite", { edits: [
+      { keyPath: `${keyPath}.trusted_hash`, value: current.currentHash, mergeStrategy: "upsert" },
+      { keyPath: `${keyPath}.enabled`, value: true, mergeStrategy: "upsert" },
+    ], filePath: null, expectedVersion: null, reloadUserConfig: true }) as { status?: string };
+    if (write?.status !== "ok") return result(false, "Codex could not apply hook trust. Check its configuration layers.");
+    hooks = projectCodexHooks(await rpc("hooks/list", { cwds: [homedir()] }));
+    const applied = hooks.find(row => row.event === request.event);
+    return applied?.enabled && applied.trustStatus === "trusted" && applied.key === current.key
+      && applied.currentHash === current.currentHash
+      ? result(true, "Codex confirmed this GrantTap hook is trusted and enabled.")
+      : result(false, "Codex has not confirmed this hook is active. Refresh and review again.");
+  } catch {
+    return result(false, "Codex hook approval is unavailable. Retry or review the hook in Codex Settings → Hooks.");
+  }
+}