acbridge 0.0.1 → 1.0.0

package/plugin/plugins/alexa/hooks/hooks.json

@@ -0,0 +1,166 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/gate.mjs"
+          }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion|ExitPlanMode|Workflow",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "PermissionDenied": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/signal.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/plugins/alexa/scripts/codex-signal.mjs

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+// Session-state SIGNAL hook for OpenAI Codex CLI (Task A4 — the Codex sibling of `signal.mjs`, which
+// does the same job for Claude Code). Codex's hooks engine invokes ONE hook command per lifecycle event
+// with a single JSON object on stdin; this script classifies the event and POSTs a lightweight signal to
+// the LOCAL hub's loopback control API — POST /local/session/state for a state, POST
+// /local/session/context for a state-less context TICK (PostToolUse). The hub's RulesEngine fires the
+// matching Profile rule keyed by `agent:"codex"` (A3), so a repo-bound Profile reacts to Codex exactly
+// like it reacts to Claude, distinguished by the `~codex` id suffix (below).
+//
+//   hook               source/condition        state
+//   ─────────────────  ───────────────────────  ──────────────────────────────────────────────────────
+//   SessionStart        startup / clear / absent  started
+//   SessionStart        resume                    resumed
+//   SessionStart        compact                    SILENT — Pre/PostCompact own compaction
+//   UserPromptSubmit     —                         working
+//   Stop                 —                         finished
+//   PermissionRequest    —                         needs_permission (observe-and-abstain: NEVER stdout —
+//                                                   Codex's permission-shaped hooks read stdout as an
+//                                                   approve/deny decision; this script never writes one)
+//   PreCompact            —                         compacting
+//   PostCompact            —                         compactDone
+//   SubagentStart           —                         subagentStart
+//   SubagentStop             —                         subagentFinished
+//   PostToolUse                —                        a state-less context TICK (POST .../context)
+//   anything else                 —                        exit 0, nothing to report
+//
+// Unlike Claude Code, Codex's own hook payload carries `model` and `permission_mode` on EVERY event, so
+// the mode/model FERRY (feeding the hub's modePlan/modeAuto/.../modelChanged synthesis, same as
+// signal.mjs) is a straight field read here — no transcript walk needed for that part. The transcript
+// walk we DO still need is `readRolloutTail` below: Codex's rollout JSONL carries the session's live
+// token usage as `token_count` event rows, read the same defensive last-64KB-tail way signal.mjs reads
+// Claude's transcript, to feed the hub's SessionContextTracker (contextLow/contextCritical thresholds).
+//
+// ACTIVATION: resolve this run's hub coordinates from (1) the BRIDGE_* env (a launcher that exports
+// them), (2) the shared per-session handshake file `~/.claude-bridge/sessions/<session_id>.json`
+// (agent-agnostic: the same dir/shape signal.mjs and the channel use, keyed by whatever agent's own
+// session id), or (3) self-derive `${project}@${machine}~codex` when a hub token file exists on this
+// machine (no hub configured here ⇒ exit 0, POST nothing). UNLIKE signal.mjs — which skips writing at
+// SessionStart to dodge a race with the channel MCP server connecting — Codex has NO channel MCP to race,
+// so the self-derived handshake is written on EVERY event, SessionStart included (scope.mjs's write
+// helper is itself idempotent: an existing file, whoever wrote it, is always adopted, never overwritten).
+// Off-switch: BRIDGE_AUTO_PROFILES=0/false or `"autoProfiles": false` in config.json — mirrors signal.mjs
+// exactly, and likewise gates ONLY step (3): explicit env coords (1) and an existing handshake file (2)
+// still work with the off-switch set.
+//
+// Part-B ADAPTER SUPPRESSION: a future adapter (`ACB_CODEX_ADAPTER` env, inherited by Codex's child
+// processes) owns a session's states directly — if set (any non-empty value), this script is a silent
+// no-op, so the two paths never double-fire signals for the same session.
+//
+// FAIL-SAFE: any parse/IO/network error ⇒ exit 0 within ~2s. A hook must NEVER block Codex; a dead hub, a
+// missing token, or an unclassifiable event all degrade to silence. Zero npm dependencies (node: builtins
+// only); stdout is NEVER written to (Codex hook stdout can influence approve/deny — this script is
+// observe-only, on every path, always).
+
+import { closeSync, fstatSync, openSync, readFileSync, readSync, writeFileSync } from "node:fs";
+import { request } from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { readActiveUserSub, resolveBridgeHome, resolveHubTokenFile, writePlainSessionHandshakeIfAbsent } from "./scope.mjs";
+
+const DEFAULT_HUB_PORT = 8790; // mirrors @bridge/node-core HUB_PORT — the plugin can't import the workspace
+// XPLAT-HOME (2026-07-28 review): WHICH `.claude-bridge` home this run should read — exactly what the
+// Claude twins (signal.mjs / statusline.mjs) already resolve, and what this script used to skip. It
+// pinned the LOCAL home unconditionally, so a Codex session running in WSL while the hub runs on Windows
+// (or vice versa) read the wrong token / active-user / sessions dir: every signal silently no-opped and
+// Codex Profiles were dead across the boundary, with no breadcrumb to say why.
+const BRIDGE_HOME = resolveBridgeHome();
+const SECRET_DIR = BRIDGE_HOME.dir;
+/** THIS environment's own home — where a diagnostic breadcrumb belongs (a peer home is not ours). */
+const LOCAL_SECRET_DIR = process.env.BRIDGE_SECRET_DIR || path.join(os.homedir(), ".claude-bridge");
+
+/** Exit 0 no matter what — a hook that throws would block Codex; we only ever no-op or POST. */
+function done() {
+  process.exit(0);
+}
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, "utf8") || "{}");
+} catch {
+  done(); // unreadable/malformed event → no-op
+}
+if (event === null || typeof event !== "object") done(); // non-object JSON (e.g. `null`, `42`) → nothing to classify
+
+// Part-B: an adapter owns this session's states already — bail before touching the handshake or the hub.
+if (process.env.ACB_CODEX_ADAPTER) done();
+
+// ── Dormancy gate: resolve THIS run's hub coordinates, mirroring signal.mjs's resolution order. ──────
+const isPlaceholder = (v) => Boolean(v) && /^\$\{.*\}$/.test(v); // sanitized-env literal `${BRIDGE_*}`
+const envVar = (v) => (v && !isPlaceholder(v) ? v : undefined);
+
+function resolveHandshake(sessionId) {
+  // Dev / direct path: explicit BRIDGE_* env wins.
+  const envId = envVar(process.env.BRIDGE_SESSION_ID);
+  if (envId) {
+    return {
+      id: envId,
+      hubPort: Number(envVar(process.env.BRIDGE_HUB_PORT)) || DEFAULT_HUB_PORT,
+      hubTokenFile: resolveHubTokenFile(SECRET_DIR, envVar(process.env.BRIDGE_HUB_TOKEN_FILE)),
+    };
+  }
+  // Correlate via Codex's own session_id → the shared per-session handshake file (agent-agnostic dir).
+  if (!sessionId) return null;
+  try {
+    const h = JSON.parse(readFileSync(path.join(SECRET_DIR, "sessions", `${sessionId}.json`), "utf8"));
+    if (!h || !h.id) return null;
+    return {
+      id: h.id,
+      hubPort: Number(h.hubPort) || DEFAULT_HUB_PORT,
+      hubTokenFile: resolveHubTokenFile(SECRET_DIR, h.hubTokenFile),
+    };
+  } catch {
+    return null; // no handshake file yet ⇒ try self-derive below
+  }
+}
+
+// Mirror @bridge/node-core machineLabel() + cli loadConfig() inline — the plugin can't import the
+// workspace (same duplication signal.mjs/statusline.mjs already carry). `codexContextWindow` is the
+// readRolloutTail override (see below) — read from the SAME config.json, tolerant of its absence.
+function readCliConfig() {
+  let file = {};
+  try {
+    file = JSON.parse(readFileSync(path.join(SECRET_DIR, "config.json"), "utf8")) || {};
+  } catch {
+    /* no config file → env + hostname defaults */
+  }
+  return {
+    machine: envVar(process.env.BRIDGE_MACHINE) || file.machine || os.hostname().split(".")[0] || "node",
+    // BEACON BEFORE CONFIG (settled 2026-07-29). The beacon is the port the hub ACTUALLY bound; a
+    // config.json `hubPort` is only what it was asked to bind, and the two disagree whenever the hub
+    // fell back. The channel handshake, doctor and the app/CLI control planes all put the beacon first;
+    // the hooks were the odd ones out, so one box could answer this question two ways. An explicit
+    // BRIDGE_HUB_PORT still wins over both — that is a deliberate override, not a guess.
+    hubPort: Number(envVar(process.env.BRIDGE_HUB_PORT) || BRIDGE_HOME.beacon?.port || file.hubPort || DEFAULT_HUB_PORT),
+    codexContextWindow: typeof file.codexContextWindow === "number" && file.codexContextWindow > 0 ? file.codexContextWindow : undefined,
+    autoProfiles: file.autoProfiles,
+  };
+}
+
+// Auto-profiles is ON by default. Off-switch: BRIDGE_AUTO_PROFILES=0/false, or `"autoProfiles": false`
+// in config.json — mirrors signal.mjs's autoProfilesEnabled() exactly. Gates ONLY the self-derive path
+// below: explicit BRIDGE_* env coords and an existing per-session handshake file are unaffected.
+function autoProfilesEnabled(cfg) {
+  const env = process.env.BRIDGE_AUTO_PROFILES;
+  if (env === "0" || env === "false") return false;
+  return cfg.autoProfiles !== false;
+}
+
+/** id `${project}@${machine}~codex`, name `"${project} codex (${machine})"` — the `~codex` suffix keeps
+ *  a Claude and a Codex session in the SAME repo distinct in the hub's tracker/debounce (both key purely
+ *  on this opaque id string). `name` has no wire slot today (neither SessionStateRequest/
+ *  SessionContextRequest nor the shared handshake writer carries one) — computed for identity
+ *  completeness so a future consumer doesn't have to re-derive the format. */
+function selfDeriveIdentity(project, machine) {
+  return { id: `${project}@${machine}~codex`, name: `${project} codex (${machine})` };
+}
+
+// No per-session handshake, but this machine HAS a hub configured (a hub-token file exists). Derive the
+// project@machine~codex id and WRITE the handshake — on every event, SessionStart included (no channel
+// MCP here to race, unlike signal.mjs). Returns null when the bridge was never set up here (no token).
+function selfDeriveHandshake(ev, cfg) {
+  const hubTokenFile = resolveHubTokenFile(SECRET_DIR, undefined);
+  try {
+    if (!readFileSync(hubTokenFile, "utf8").trim()) return null;
+  } catch {
+    return null; // no hub token (scoped or machine-global) → bridge not set up on this machine → silent
+  }
+  const cwd = typeof ev.cwd === "string" && ev.cwd ? ev.cwd : process.cwd();
+  const project = path.basename(cwd) || "session";
+  const identity = selfDeriveIdentity(project, cfg.machine);
+  // No signed-in account (readActiveUserSub → null) ⇒ the write helper itself writes nothing — an
+  // unattributable session must never be adopted. An existing (any writer's) file is never overwritten.
+  writePlainSessionHandshakeIfAbsent({
+    secretDir: SECRET_DIR,
+    id: identity.id,
+    hubPort: cfg.hubPort,
+    hubTokenFile,
+    cwd,
+    claudeSessionId: typeof ev.session_id === "string" ? ev.session_id : undefined,
+    sub: readActiveUserSub(SECRET_DIR),
+  });
+  return { id: identity.id, hubPort: cfg.hubPort, hubTokenFile };
+}
+
+const cfg = readCliConfig();
+let handshake = resolveHandshake(typeof event.session_id === "string" ? event.session_id : undefined);
+if (!handshake && autoProfilesEnabled(cfg)) handshake = selfDeriveHandshake(event, cfg);
+if (!handshake) done(); // no bridge session AND no hub configured (or auto-profiles off) — stay silent
+
+// ── Classify table: hook_event_name (+ source) → one wire state, {tick:true}, or null. ────────────────
+function classify(ev) {
+  const name = String(ev.hook_event_name ?? "");
+  switch (name) {
+    case "SessionStart": {
+      const source = String(ev.source ?? "");
+      // A compact "restart" is the SAME session continuing — PostCompact owns compaction.
+      if (source === "compact") return null;
+      return { state: source === "resume" ? "resumed" : "started" };
+    }
+    case "UserPromptSubmit":
+      return { state: "working" };
+    case "Stop":
+      return { state: "finished" };
+    case "PermissionRequest":
+      // Observe-and-abstain: classify it for the device signal, but NEVER emit stdout (below, always).
+      return { state: "needs_permission" };
+    case "PreCompact":
+      return { state: "compacting" };
+    case "PostCompact":
+      return { state: "compactDone" };
+    case "SubagentStart":
+      return { state: "subagentStart" };
+    case "SubagentStop":
+      return { state: "subagentFinished" };
+    case "PostToolUse": {
+      // S2: legacy best-effort error detection — MIRRORS signal.mjs's exact tool_response check (the
+      // Claude sibling, same field names): fire only when the tool response explicitly signals a hard
+      // failure, biased to UNDER-fire (an unflagged failure stays silent) so a normal session never
+      // flashes the error scene.
+      const resp = ev.tool_response;
+      const isError =
+        resp &&
+        typeof resp === "object" &&
+        (resp.is_error === true ||
+          resp.isError === true ||
+          (typeof resp.error === "string" && resp.error.length > 0));
+      if (isError) return { state: "error" };
+      // The per-tool cadence that keeps the hub's context meter fresh during a long working stretch.
+      return { tick: true };
+    }
+    default:
+      return null; // an unregistered/future hook reached us → nothing to report
+  }
+}
+
+const mapped = classify(event);
+if (!mapped) done(); // this event carries no state and no tick → no-op
+
+// ── readRolloutTail: the context ferry. Positioned read of the last 64KB only — rollouts reach tens of
+// MB and this runs per tool call. Walk BACKWARD for the first (= latest) token_count row; cumulative
+// totals are interspersed frequently, so the latest one is the current reading. Field layout has drifted
+// across Codex versions (`info` wrapper sometimes absent; `model_context_window` sometimes absent/null),
+// so every field is read defensively — accept both `payload.info.total_token_usage` and
+// `payload.total_token_usage`. Any error → no context reading (never guess); the signal still POSTs. ────
+
+// Best-effort context-window sizes for named Codex model slugs (July 2026, approximate — Codex reports
+// the REAL value in `model_context_window` when its payload row has it, so this table is only a fallback
+// for rows/builds that omit it). A short honest table beats a fake-complete one; extend as OpenAI ships
+// new slugs. An unlisted slug falls to DEFAULT_WINDOW (itself overridable via config `codexContextWindow`).
+const MODEL_WINDOWS = {
+  "gpt-5-codex": 400_000,
+  "gpt-5": 400_000,
+  "o4-mini": 200_000,
+};
+const DEFAULT_WINDOW = 400_000;
+
+/** One token_count row's usage, or null when the row isn't a usable token_count row. */
+function extractUsage(rec) {
+  if (!rec || typeof rec !== "object" || rec.type !== "event_msg") return null;
+  const payload = rec.payload;
+  if (!payload || typeof payload !== "object" || payload.type !== "token_count") return null;
+  const info = payload.info && typeof payload.info === "object" ? payload.info : payload;
+  const usage = info.total_token_usage;
+  if (!usage || typeof usage !== "object") return null;
+  const inputTokens = usage.input_tokens;
+  if (typeof inputTokens !== "number" || !(inputTokens >= 0)) return null;
+  const windowRaw = info.model_context_window;
+  return {
+    // Deliberately NOT adding cached_input_tokens — flagging here: live-smoke calibration against
+    // Codex's own /status display may show that display sums input+cached, in which case this flips.
+    usedTokens: inputTokens,
+    windowTokens: typeof windowRaw === "number" && windowRaw > 0 ? windowRaw : undefined,
+  };
+}
+
+function readRolloutTail(transcriptPath, model, config) {
+  try {
+    if (typeof transcriptPath !== "string" || !transcriptPath) return null;
+    const fd = openSync(transcriptPath, "r");
+    let text, torn;
+    try {
+      const size = fstatSync(fd).size;
+      const len = Math.min(size, 65536);
+      if (len === 0) return null;
+      const buf = Buffer.alloc(len);
+      readSync(fd, buf, 0, len, size - len);
+      text = buf.toString("utf8");
+      torn = size > len; // the window may open mid-line → the first fragment isn't trustworthy JSON
+    } finally {
+      closeSync(fd);
+    }
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= (torn ? 1 : 0); i--) {
+      const line = lines[i];
+      if (!line || line.charCodeAt(0) !== 123 /* "{" */) continue;
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const usage = extractUsage(rec);
+      if (!usage) continue;
+      const windowTokens = usage.windowTokens ?? MODEL_WINDOWS[model] ?? config.codexContextWindow ?? DEFAULT_WINDOW;
+      return { pct: Math.min(100, Math.round((usage.usedTokens / windowTokens) * 1000) / 10), usedTokens: usage.usedTokens, windowTokens };
+    }
+    return null; // no token_count row in the tail → no reading, never guess
+  } catch {
+    return null; // unreadable/garbled rollout → no reading, never a failure
+  }
+}
+
+const context = readRolloutTail(
+  typeof event.transcript_path === "string" ? event.transcript_path : undefined,
+  typeof event.model === "string" ? event.model : undefined,
+  cfg,
+);
+
+// ── POST the signal to the local hub, behind the loopback token guard (no Origin ⇒ passes). ──────────
+let token;
+try {
+  token = readFileSync(handshake.hubTokenFile, "utf8").trim();
+} catch {
+  done(); // no token file (hub not up on this machine) → no-op
+}
+if (!token) done();
+
+const ids = {
+  sessionId: handshake.id, // the canonical bridge id (project@machine~codex) the hub keys on
+  claudeSessionId: typeof event.session_id === "string" ? event.session_id : undefined, // handshake-stem join key (agent-agnostic by convention)
+  ts: Date.now(),
+  ...(typeof event.cwd === "string" ? { cwd: event.cwd } : {}),
+};
+// A tick (PostToolUse) targets the state-less context route; everything else is a state signal.
+const apiPath = mapped.tick ? "/local/session/context" : "/local/session/state";
+// Straight from the payload — unlike Claude, Codex ships model + permission_mode on every hook event.
+const mode = typeof event.permission_mode === "string" && event.permission_mode ? event.permission_mode : undefined;
+const model = typeof event.model === "string" && event.model ? event.model : undefined;
+const ferry = { agent: "codex", ...(mode ? { mode } : {}), ...(model ? { model } : {}) };
+const payload = JSON.stringify(
+  mapped.tick
+    ? { ...ids, ...(context ? { context } : {}), ...ferry }
+    : {
+        ...ids,
+        state: mapped.state,
+        event: `codex:${String(event.hook_event_name ?? "")}`,
+        ...(context ? { context } : {}),
+        ...ferry,
+      },
+);
+
+/** One bounded breadcrumb for a REJECTED signal — the twin of signal.mjs's, which this script lacked, so
+ *  a dead cross-boundary Codex hook left no trace anywhere and `doctor` had nothing to report. Written to
+ *  the LOCAL home even when the hub lives in a peer one: doctor asks about THIS environment. Best-effort
+ *  and silent — a hook must never fail because it could not complain. */
+function recordHookRejection(status) {
+  try {
+    writeFileSync(
+      path.join(LOCAL_SECRET_DIR, "hooks-last-error.json"),
+      JSON.stringify({
+        ts: Date.now(),
+        status,
+        home: BRIDGE_HOME.dir,
+        homeSource: BRIDGE_HOME.source,
+        hubPort: handshake.hubPort,
+        agent: "codex",
+        hint:
+          status === 401
+            ? "the hub rejected this machine's hub-token — the Codex hook is reading a stale or foreign one"
+            : "the hub refused the signal",
+      }),
+      { mode: 0o600 },
+    );
+  } catch {
+    /* unwritable home → nothing to do; the signal already failed */
+  }
+}
+
+// node:http (not fetch) for zero deps + guaranteed NO Origin header (the guard 403s any Origin) + a hard
+// timeout. Observe-and-abstain: this response is drained and discarded — NOTHING from it (or anywhere
+// else in this script) is ever written to our own stdout.
+const req = request(
+  {
+    host: "127.0.0.1",
+    port: handshake.hubPort,
+    path: apiPath,
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "content-length": Buffer.byteLength(payload),
+      "x-bridge-hub-token": token,
+    },
+    timeout: 2000,
+  },
+  (res) => {
+    if (res.statusCode && res.statusCode >= 400) recordHookRejection(res.statusCode);
+    res.on("data", () => {}); // drain
+    res.on("end", done);
+  },
+);
+req.on("timeout", () => {
+  req.destroy();
+  done();
+});
+req.on("error", done); // hub down / connection refused → silent no-op
+req.end(payload);

package/plugin/plugins/alexa/scripts/gate.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// PreToolUse hook for the Alexa voice-bridge plugin channel.
+//
+// POLICY (owner decision, 2026-07 security review): AC Bridge adds NO tool restrictions of its own.
+// Every tool call is approved here — ON A VOICE SESSION. Scoped to voice (docs/VOICE-FLAG.md); see
+// isVoiceSession() at the bottom for why, and for what a non-voice session does instead (defer).
+//
+// The reasoning, so nobody "fixes" this later by re-adding rules:
+//   • AC Bridge is a local home tool and an extension of the user's OWN Claude Code install. The user
+//     already granted Claude its permissions at setup; a bridge that silently second-guesses that is
+//     adding friction, not safety.
+//   • Anyone who wants restrictions configures them in their own Claude Code settings, which is where
+//     tool policy belongs — one place, under the user's control, not split across a plugin they did not
+//     write and cannot easily inspect.
+//   • The hands-free flow is the product. A permission prompt mid-session means Alexa has to relay a
+//     spoken yes/no for something the user already authorised at install time.
+//
+// WHAT THIS GIVES UP, stated plainly rather than buried:
+//   • A previous version denied reads of credential stores (~/.ssh, ~/.aws, .env, the bridge's own
+//     token dir) on a live voice session, because the `reply` tool is an outbound channel — anything a
+//     tool reads can be SPOKEN back. That guard is gone: on a voice session, a misheard or
+//     prompt-injected request can read a secret and read it aloud.
+//   • A small set of destructive Bash patterns (rm -rf, mkfs, dd if=, fork bombs, force-push) was also
+//     denied. That is gone too, along with the mirrored managed-settings deny list.
+//   • Because a PreToolUse "allow" SHORT-CIRCUITS Claude Code's permission system, this also overrides
+//     restrictions the user sets in their own config. That override now applies ONLY to voice sessions,
+//     where the hands-free rationale actually holds; a plain `claude` session — and every session on a
+//     voice-off build, where this plugin is still installed to feed device Profiles — defers to the
+//     user's own config instead.
+//
+// Physical-device safety is NOT handled here and is unaffected: security-sensitive smart-home commands
+// (locks, garages, valves, cameras) go through the hub's own fail-closed gate — see hub/src/device-gate.ts
+// and relay/src/device-confirm.ts. Reading a file and unlocking a front door are different risks, and
+// only the first one is being opened up.
+//
+// Contract (unchanged): read the PreToolUse event JSON on stdin, print a permissionDecision, exit 0.
+
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Emit a decision and exit. `null` ⇒ print nothing ⇒ defer to Claude Code's normal flow. */
+function emit(decision, reason) {
+  if (decision) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: decision, // "allow" | "deny"
+          permissionDecisionReason: reason ?? "",
+        },
+      }),
+    );
+  }
+  process.exit(0);
+}
+
+/**
+ * Is THIS session actually reachable by voice? The blanket allow above short-circuits Claude Code's
+ * permission system — including restrictions the user set in their own config — and the argument for doing
+ * that is entirely hands-free: a permission prompt mid-voice-session has to be relayed to Alexa as a spoken
+ * yes/no. On a session voice cannot reach, that argument doesn't exist, so we defer instead. This matters
+ * because the plugin stays installed when the voice feature flag is off (its hooks are how agent state
+ * reaches the hub, which is what device Profiles react to) — without this check, a voice-off build would
+ * still be overriding the user's permissions everywhere, for a feature it does not ship.
+ *
+ * The signal is the POSITIVE `voice:true` marker every voice writer stamps into the session handshake
+ * (channel self-bootstrap + env branch in channel/src/handshake.ts, `acbridge run`'s buildHandshakeRecord),
+ * and which the channel upgrades an unmarked file to at MCP init — before it connects, so before any
+ * `reply` egress can exist. Absence is never treated as presence: no marker, no file, no session id, or an
+ * unreadable file all DEFER. Deferring is strictly less permissive than allowing, so every uncertain case
+ * lands on the user's own configuration, which is the safe direction.
+ */
+function isVoiceSession() {
+  try {
+    const sid = process.env.CLAUDE_CODE_SESSION_ID;
+    if (!sid) return false; // a voice session always has this — it is how the channel identifies itself
+    const dir = process.env.BRIDGE_SECRET_DIR || path.join(os.homedir(), ".claude-bridge");
+    const file = path.join(dir, "sessions", `${sid}.json`);
+    if (!existsSync(file)) return false; // no handshake ⇒ no channel ⇒ nothing to be hands-free about
+    const h = JSON.parse(readFileSync(file, "utf8"));
+    return h?.voice === true;
+  } catch {
+    return false; // unreadable/corrupt ⇒ can't confirm voice ⇒ defer
+  }
+}
+
+// The event is read (and a malformed one still exits 0) purely to honour the hook contract — the
+// decision comes from the SESSION, not from the event.
+try {
+  readFileSync(0, "utf8");
+} catch {
+  /* an unreadable event changes nothing — the session is what decides */
+}
+
+if (isVoiceSession()) {
+  emit("allow", "acbridge adds no tool restrictions — permissions are the user's own Claude Code config");
+}
+emit(null); // not voice-reachable ⇒ defer to Claude Code's normal permission flow