@hybridlabor-api/aos 4.13.2 → 4.14.1

package/.agents/AGENTS.md

@@ -19,6 +19,7 @@ next. This file defines *what each agent is*, not *what calls what*.
   - `bdbrainstorm`
   - `planning-with-files`
   - `concise-planning`
+  - `plan-arbiter`
 - **MCP Servers**:
   - `openwiki-skill`
   - `memb_mcp`
@@ -39,6 +40,7 @@ next. This file defines *what each agent is*, not *what calls what*.
   - `startcycle-graph`
   - `agent-pipeline`
   - `subagent-driven-development`
+  - `plan-arbiter`
 - **MCP Servers**:
   - `memb_mcp`
 - **Output Artifact**: capability-map approval recorded in `state.json` (no separate markdown file — this is a gate, not a deliverable)
@@ -59,6 +61,8 @@ next. This file defines *what each agent is*, not *what calls what*.
   - `react-best-practices`
   - `ui-component`
   - `ui-tokens`
+  - `bdbdesignpro`
+  - `editable-design`
 - **MCP Servers**:
   - `open_design_mcp`
   - `chrome-devtools`
@@ -79,6 +83,7 @@ next. This file defines *what each agent is*, not *what calls what*.
   - `postgres-best-practices`
   - `typescript-pro`
   - `python-pro`
+  - `bdbresilience`
 - **MCP Servers**:
   - `github`
   - `memb_mcp`
@@ -138,6 +143,9 @@ next. This file defines *what each agent is*, not *what calls what*.
   - `wcag-audit-patterns`
   - `github-repo`
   - `clean-code`
+  - `brag`
+  - `bdbresilience`
+  - `bdb-security-audit`
 - **MCP Servers**:
   - `github`
   - `chrome-devtools`

package/.agents/nodes.json

@@ -1,6 +1,7 @@
 {
   "version": 1,
   "description": "Declarative node registry for /startcycle-graph. The dispatcher reads this instead of hardcoding BUILD_NODES and NODE_ENUM. Adding a build domain = adding an entry here, not editing the dispatcher.",
+  "common": ["read-the-damn-docs", "agenttrail", "archify", "plan-canvas", "stay-within-limits", "quick-recap", "verification-before-completion"],
   "nodes": {
     "architect": {
       "label": "Architect",
@@ -16,7 +17,8 @@
         "bdbrainstorm",
         "planning-with-files",
         "concise-planning",
-        "archify"
+        "archify",
+        "plan-arbiter"
       ],
       "instructions": null
     },
@@ -33,7 +35,8 @@
         "read-the-damn-docs",
         "startcycle-graph",
         "agent-pipeline",
-        "subagent-driven-development"
+        "subagent-driven-development",
+        "plan-arbiter"
       ],
       "instructions": null
     },

package/.claude/hooks/conventional-commits.mjs

@@ -19,7 +19,8 @@
 // failure here, because the consequence (history AOS does not recognise) is
 // recoverable with a rebase, and a wedged commit flow is not.
 
-import { readFileSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 const TYPES = ["feat", "fix", "docs", "style", "refactor", "perf", "test", "chore", "ci", "build", "revert"];
 
@@ -35,7 +36,7 @@ function readStdin() {
   }
 }
 
-function respond(isAgy, allowed, reason = "", message = "") {
+function respond(isAgy, allowed, reason = "") {
   if (isAgy) {
     if (allowed) {
       console.log(JSON.stringify({ decision: "allow" }));
@@ -87,6 +88,14 @@ function reasonFor(message) {
   ].join("\n");
 }
 
+export function checkConventionalCommit(command) {
+  if (typeof command !== "string" || !COMMIT.test(command)) return null;
+  const message = extractMessage(command);
+  return message === null || CONVENTIONAL.test(message) ? null : reasonFor(message);
+}
+
+const isMain = () => { try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } };
+
 function main() {
   const rawInput = readStdin();
   let input = {};
@@ -108,18 +117,8 @@ function main() {
     input?.command ||
     "";
 
-  if (typeof command !== "string" || !COMMIT.test(command)) {
-    respond(isAgy, true);
-    return;
-  }
-
-  const message = extractMessage(command);
-  if (message === null || CONVENTIONAL.test(message)) {
-    respond(isAgy, true);
-    return;
-  }
-
-  respond(isAgy, false, reasonFor(message), message);
+  const reason = checkConventionalCommit(command);
+  respond(isAgy, !reason, reason || "");
 }
 
-main();
+if (isMain()) main();

package/.claude/hooks/env-file-protection.mjs

@@ -18,7 +18,8 @@
 // every write in the session; missing a protection is recoverable, freezing
 // the agent is not.
 
-import { readFileSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { basename } from "node:path";
 
 // Templates are committed on purpose and hold no live secret. Blocking them
@@ -67,6 +68,15 @@ function reasonFor(filePath) {
   ].join("\n");
 }
 
+export function envFileReason(filePath) {
+  if (typeof filePath !== "string" || !filePath.trim()) return null;
+  // basename(), so a path like /srv/app/.env matches but /srv/app/env-notes.md does not.
+  const name = basename(filePath);
+  return !ENV_FILE.test(name) || TEMPLATE_FILE.test(name) ? null : reasonFor(filePath);
+}
+
+const isMain = () => { try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } };
+
 function main() {
   const rawInput = readStdin();
   let input = {};
@@ -87,19 +97,8 @@ function main() {
     input?.file_path ||
     "";
 
-  if (typeof filePath !== "string" || !filePath.trim()) {
-    respond(isAgy, true);
-    return;
-  }
-
-  // basename(), so a path like /srv/app/.env matches but /srv/app/env-notes.md does not.
-  const name = basename(filePath);
-  if (!ENV_FILE.test(name) || TEMPLATE_FILE.test(name)) {
-    respond(isAgy, true);
-    return;
-  }
-
-  respond(isAgy, false, reasonFor(filePath));
+  const reason = envFileReason(filePath);
+  respond(isAgy, !reason, reason || "");
 }
 
-main();
+if (isMain()) main();

package/.claude/hooks/go-gate.mjs

@@ -15,10 +15,34 @@
 //
 // Gate validity: open ONLY if the LAST human-typed user message in the transcript
 // is the literal word "GO" (case-insensitive, trimmed). Any other message closes it.
+//
+// Token path (master-session): a `GO <session>` typed by the human in a master
+// session is turned into ~/.aos/go/<session>.token by go-token.mjs. This gate
+// honours that token once, if it is <10 min old, names this session, and the
+// master transcript it points at still ends with that very `GO <session>`.
+// Own session name: latest agent-name/custom-title entry in this transcript
+// (what --name / ListAgents show), else env AOS_SESSION_NAME. If neither is
+// available the token path stays closed.
+//
+// A token is single-use per master message: the master's GO entry uuid (Claude)
+// or message id (OpenCode) goes into ~/.aos/go/.consumed, so a re-minted token
+// on an unchanged master cannot be replayed.
+//
+// Threat model: this stops accidental or replayed GOs, not an agent that can
+// write arbitrary files; it can forge a master transcript. Nothing in-process fixes that.
+//
+// OpenCode-issued tokens (issuer "opencode") are verified offline against
+// opencode.db, read-only. Limits: the schema is internal and undocumented, only
+// the default XDG / ~/.local/share data dir is read, and bun:sqlite is an
+// unverified fallback. Any miss fails closed; the human types a literal GO.
 
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, unlinkSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const GUARDED_PATTERNS = [
+export const GUARDED_PATTERNS = [
   /(?:^|[;&|]\s*)git\s+push\b/i,
   /(?:^|[;&|]\s*)npm\s+publish\b/i,
   /(?:^|[;&|]\s*)npm\s+version\b/i,
@@ -83,12 +107,125 @@ function extractAgyText(rawContent) {
   return text.trim();
 }
 
+export const slug = (s) => s.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+const TOKEN_TTL_MS = 10 * 60 * 1000;
+
+function ownSessionName(transcriptPath) {
+  let name = "";
+  try {
+    for (const line of readFileSync(transcriptPath, "utf8").split("\n")) {
+      if (!line.includes('"agent-name"') && !line.includes('"custom-title"')) continue;
+      try {
+        const e = JSON.parse(line);
+        if (e.type === "agent-name" && e.agentName) name = e.agentName;
+        else if (e.type === "custom-title" && e.customTitle && !name) name = e.customTitle;
+      } catch { /* partial line */ }
+    }
+  } catch { /* unreadable */ }
+  return name || process.env.AOS_SESSION_NAME || "";
+}
+
+const CONSUMED_KEEP = 200;
+const consumedFile = () => join(homedir(), ".aos", "go", ".consumed");
+const readConsumed = () => {
+  try { return readFileSync(consumedFile(), "utf8").split("\n").filter(Boolean); } catch (e) { return e.code === "ENOENT" ? [] : null; }
+};
+
+function opencodeLastUser(sessionId) {
+  let db;
+  try {
+    const dbPath = join(process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "opencode", "opencode.db");
+    if (typeof sessionId !== "string" || !existsSync(dbPath)) return null;
+    const require = createRequire(import.meta.url);
+    try {
+      db = new (require("node:sqlite").DatabaseSync)(dbPath, { readOnly: true });
+    } catch {
+      db = new (require("bun:sqlite").Database)(dbPath, { readonly: true });
+    }
+    const ses = db.prepare("SELECT parent_id FROM session WHERE id = ?").get(sessionId);
+    if (!ses || ses.parent_id != null) return null; // subagent sessions are agent-written, never a human GO
+    const msg = db.prepare(
+      "SELECT id FROM message WHERE session_id = ? AND json_extract(data, '$.role') = 'user' ORDER BY time_created DESC, id DESC LIMIT 1"
+    ).get(sessionId);
+    if (!msg) return null;
+    const text = db.prepare("SELECT data FROM part WHERE message_id = ? ORDER BY id").all(msg.id)
+      .map((r) => JSON.parse(r.data))
+      .filter((p) => p?.type === "text" && !p.synthetic && typeof p.text === "string")
+      .map((p) => p.text)
+      .join("\n")
+      .trim();
+    return { id: msg.id, text };
+  } catch {
+    return null;
+  } finally {
+    try { db?.close(); } catch { /* already closed */ }
+  }
+}
+
+// Shared with bin/aos-acp.mjs (ACP permission requests). `consume: false`
+// verifies without deleting the token, for a caller whose inner gate owns it.
+export function tokenGrantsGo(own, { consume = true } = {}) {
+  if (typeof own !== "string" || !slug(own)) return { ok: false, reason: "no session name derivable for token path" };
+  const file = join(homedir(), ".aos", "go", `${slug(own)}.token`);
+  if (!existsSync(file)) return { ok: false, reason: "no GO token for this session" };
+  let tok;
+  try {
+    tok = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return { ok: false, reason: "GO token unreadable" };
+  }
+  const age = Date.now() - Date.parse(tok?.issued_at);
+  if (!(age >= 0 && age < TOKEN_TTL_MS)) {
+    try { unlinkSync(file); } catch { /* already gone */ }
+    return { ok: false, reason: "GO token expired" };
+  }
+  if (typeof tok.target !== "string" || slug(tok.target) !== slug(own)) {
+    return { ok: false, reason: "GO token names another session" };
+  }
+  const want = `go ${own.trim().toLowerCase()}`;
+  let key;
+  if (tok.issuer === "opencode") {
+    const last = opencodeLastUser(tok.master_session_id);
+    if (!last || last.id !== tok.master_message_id || last.text.toLowerCase() !== want) {
+      return { ok: false, reason: "master session no longer ends with this GO" };
+    }
+    key = last.id;
+  } else if (typeof tok.master_transcript === "string") {
+    const last = lastUserText(tok.master_transcript);
+    if (!last.text || last.text.trim().toLowerCase() !== want) {
+      return { ok: false, reason: "master transcript no longer ends with this GO" };
+    }
+    if (!last.uuid) return { ok: false, reason: "master GO entry has no uuid" };
+    key = last.uuid;
+  } else {
+    return { ok: false, reason: "GO token has no master transcript" };
+  }
+  const consumed = readConsumed();
+  if (!consumed) return { ok: false, reason: "GO consumed list unreadable" };
+  if (consumed.includes(key)) return { ok: false, reason: "GO already used" };
+  if (consume) {
+    try {
+      // ponytail: read-modify-write, concurrent consumers in the same ms can drop a key; switch to append+trim if that ever matters.
+      writeFileSync(consumedFile(), [...consumed, key].slice(-CONSUMED_KEEP).join("\n") + "\n");
+      unlinkSync(file);
+    } catch { return { ok: false, reason: "could not consume GO token" }; }
+  }
+  return { ok: true };
+}
+
 function lastUserMessageIsGo(transcriptPath) {
+  const last = lastUserText(transcriptPath);
+  if (last.error) return { ok: false, reason: last.error };
+  if (last.text === null) return { ok: false, reason: "no user message found in transcript" };
+  return { ok: /^GO$/i.test(last.text.trim()), reason: `last user message was: ${JSON.stringify(last.text)}` };
+}
+
+export function lastUserText(transcriptPath) {
   let raw;
   try {
     raw = readFileSync(transcriptPath, "utf8");
   } catch (e) {
-    return { ok: false, reason: `could not read transcript (${e.message})` };
+    return { text: null, error: `could not read transcript (${e.message})` };
   }
 
   const lines = raw.split("\n").filter(Boolean);
@@ -104,8 +241,7 @@ function lastUserMessageIsGo(transcriptPath) {
     if (entry.type === "USER_INPUT" || entry.source === "USER_EXPLICIT") {
       const text = extractAgyText(entry.content);
       if (!text) continue;
-      const isGo = /^GO$/i.test(text.trim());
-      return { ok: isGo, reason: `last user message was: ${JSON.stringify(text)}` };
+      return { text };
     }
 
     // 2. Claude Code transcript entry format
@@ -114,12 +250,11 @@ function lastUserMessageIsGo(transcriptPath) {
       const content = entry.message?.content ?? entry.content;
       const text = extractClaudeText(content).trim();
       if (!text) continue;
-      const isGo = /^GO$/i.test(text);
-      return { ok: isGo, reason: `last user message was: ${JSON.stringify(text)}` };
+      return { text, uuid: entry.uuid ?? null };
     }
   }
 
-  return { ok: false, reason: "no user message found in transcript" };
+  return { text: null };
 }
 
 function main() {
@@ -164,7 +299,12 @@ function main() {
     return;
   }
 
-  const result = lastUserMessageIsGo(transcriptPath);
+  let result = lastUserMessageIsGo(transcriptPath);
+  if (!result.ok) {
+    const token = tokenGrantsGo(ownSessionName(transcriptPath));
+    if (token.ok) result = token;
+    else result.reason += `; ${token.reason}`;
+  }
   if (result.ok) {
     respond(isAgy, true, "", command);
   } else {
@@ -172,4 +312,6 @@ function main() {
   }
 }
 
-main();
+// Run as a hook (node go-gate.mjs); importing it (bin/aos-acp.mjs) must not.
+const invokedAs = (() => { try { return realpathSync(process.argv[1] || ""); } catch { return ""; } })();
+if (invokedAs === fileURLToPath(import.meta.url)) main();

package/.claude/hooks/go-token.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook: when the human types exactly `GO <session-name>` in a
+// master session, record a single-use token that go-gate.mjs in <session-name>
+// accepts. Writes nothing else and never blocks the prompt.
+
+import { readFileSync, writeFileSync, mkdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { slug } from "./go-gate.mjs";
+
+function sessionName(transcriptPath) {
+  let name = "";
+  try {
+    for (const line of readFileSync(transcriptPath, "utf8").split("\n")) {
+      if (!line.includes('"agent-name"') && !line.includes('"custom-title"')) continue;
+      try {
+        const e = JSON.parse(line);
+        if (e.type === "agent-name" && e.agentName) name = e.agentName;
+        else if (e.type === "custom-title" && e.customTitle && !name) name = e.customTitle;
+      } catch { /* partial line */ }
+    }
+  } catch { /* unreadable transcript */ }
+  return name || process.env.AOS_SESSION_NAME || "";
+}
+
+// Returns the token path, or null. Never throws. An aos-acp worker is a worker
+// by definition and must not mint a token for itself.
+export function issueGoToken(prompt, { transcript_path, session_id, message_id } = {}) {
+  try {
+    const m = /^GO\s+(\S(?:.*\S)?)$/i.exec(String(prompt ?? "").trim());
+    if (!m || process.env.AOS_ACP_CLIENT) return null;
+    const target = slug(m[1]);
+    const base = { target: m[1].trim(), issued_at: new Date().toISOString() };
+    let tok;
+    if (transcript_path) tok = { ...base, master_transcript: transcript_path, master_session: sessionName(transcript_path) };
+    else if (session_id && message_id) tok = { ...base, issuer: "opencode", master_session_id: session_id, master_message_id: message_id };
+    if (!target || !tok) return null;
+    const dir = join(homedir(), ".aos", "go");
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${target}.token`);
+    writeFileSync(file, JSON.stringify(tok));
+    return file;
+  } catch { return null; }
+}
+
+const isMain = () => { try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } };
+
+if (isMain()) {
+  try {
+    const input = JSON.parse(readFileSync(0, "utf8"));
+    issueGoToken(input.prompt, input);
+  } catch { /* a failing hook must never block the prompt */ }
+  process.exit(0);
+}

package/.claude/hooks/memb-inject.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// aos-hook-version: 6
+// aos-hook-version: 7
 /**
  * memB ambient memory hook for Claude Code, Google Antigravity, and OpenAI Codex.
  *
@@ -137,74 +137,60 @@ function resolveProjectIdentifiers(projectRoot, homeDir) {
   return Array.from(ids).filter(Boolean);
 }
 
-// Main logic runs only when the file is executed directly as a hook; importing
-// the module (e.g. from tests) must stay side-effect free.
-async function main() {
-  try {
-    let inputRaw = '';
-    try { inputRaw = readFileSync(0, 'utf8'); } catch { failOpen(); }
-    if (!inputRaw || !inputRaw.trim()) failOpen();
+// Shared with the OpenCode plugin: everything between "which event" and the
+// finished text block. Returns null when there is nothing to inject; never exits.
+export async function buildMemoryBlock({ event = '', prompt = '', cwd, userId } = {}) {
+  prompt = String(prompt).trim();
+  const home = os.homedir();
 
-    let eventData = {};
-    try { eventData = JSON.parse(inputRaw); } catch { failOpen(); }
+  // Which harness event is this? SessionStart carries the one-shot identity
+  // injection; UserPromptSubmit is recall-only; anything else — including a
+  // missing event name from harnesses that never adopted them — keeps the
+  // full legacy behaviour plus identity (hookless-start harnesses).
+  const rawEvent = event;
+  const sessionStart = rawEvent === 'SessionStart';
+  const promptSubmit = rawEvent === 'UserPromptSubmit';
 
-    const prompt = (eventData.prompt || eventData.userPrompt || '').trim();
-    const home = os.homedir();
+  const rawCandidateDir =
+    cwd ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.CODEX_PROJECT_DIR ||
+    process.cwd();
 
-    // Which harness event is this? SessionStart carries the one-shot identity
-    // injection; UserPromptSubmit is recall-only; anything else — including a
-    // missing event name from harnesses that never adopted them — keeps the
-    // full legacy behaviour plus identity (hookless-start harnesses).
-    const rawEvent = eventData.hook_event_name || '';
-    const sessionStart = rawEvent === 'SessionStart';
-    const promptSubmit = rawEvent === 'UserPromptSubmit';
+  const projectRoot = findProjectRoot(rawCandidateDir, home);
+  const candidateProjectIds = resolveProjectIdentifiers(projectRoot, home);
 
-    // Discover candidate directory across harnesses:
-    // Claude: eventData.cwd
-    // Antigravity: eventData.workspacePaths[0] or eventData.cwd
-    // Codex: eventData.cwd
-    const rawCandidateDir =
-      (Array.isArray(eventData.workspacePaths) && eventData.workspacePaths[0]) ||
-      eventData.cwd ||
-      process.env.CLAUDE_PROJECT_DIR ||
-      process.env.CODEX_PROJECT_DIR ||
-      process.cwd();
+  // User identification: reconcile active user and bdb_developer baseline
+  const activeUser =
+    process.env.MEMB_USER_ID ||
+    userId ||
+    process.env.USER ||
+    process.env.LOGNAME ||
+    'bdb_developer';
+  const candidateUsers = Array.from(new Set([activeUser, 'bdb_developer'])).filter(Boolean);
 
-    const projectRoot = findProjectRoot(rawCandidateDir, home);
-    const candidateProjectIds = resolveProjectIdentifiers(projectRoot, home);
+  const contextItems = [];
 
-    // User identification: reconcile active user and bdb_developer baseline
-    const activeUser =
-      process.env.MEMB_USER_ID ||
-      eventData.user_id ||
-      eventData.userId ||
-      process.env.USER ||
-      process.env.LOGNAME ||
-      'bdb_developer';
-    const candidateUsers = Array.from(new Set([activeUser, 'bdb_developer'])).filter(Boolean);
-
-    const contextItems = [];
-
-    // 1. Standing facts, if the user keeps any. Skipped on UserPromptSubmit:
-    //    they were already injected at SessionStart.
-    if (!promptSubmit) {
-      const personaFile = path.join(home, '.MemBDB', 'ambient-persona.txt');
-      if (existsSync(personaFile)) {
-        try {
-          for (const line of readFileSync(personaFile, 'utf8').split('\n')) {
-            const t = line.trim();
-            if (t && !t.startsWith('#')) contextItems.push(`- ${t}`);
-          }
-        } catch {}
-      }
+  // 1. Standing facts, if the user keeps any. Skipped on UserPromptSubmit:
+  //    they were already injected at SessionStart.
+  if (!promptSubmit) {
+    const personaFile = path.join(home, '.MemBDB', 'ambient-persona.txt');
+    if (existsSync(personaFile)) {
+      try {
+        for (const line of readFileSync(personaFile, 'utf8').split('\n')) {
+          const t = line.trim();
+          if (t && !t.startsWith('#')) contextItems.push(`- ${t}`);
+        }
+      } catch {}
     }
+  }
 
-    const dbPath = path.join(home, '.MemBDB', 'memb.db');
-    if (!existsSync(dbPath)) failOpen();
-    const { DatabaseSync } = await import('node:sqlite');
-    const db = new DatabaseSync(dbPath, { readOnly: true });
+  const dbPath = path.join(home, '.MemBDB', 'memb.db');
+  if (!existsSync(dbPath)) return null;
+  const { DatabaseSync } = await import('node:sqlite');
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  try {
     db.exec('PRAGMA busy_timeout = 5000;');
-
     const textOf = (payload) => {
       const p = JSON.parse(payload);
       return (p.memory || p.data || '').trim().replace(/\s+/g, ' ');
@@ -344,8 +330,35 @@ async function main() {
     //    a déjà vu instead of from zero. Once per session, like identity.
     if (!promptSubmit) contextItems.push(...dejaWip(projectRoot));
 
-    if (contextItems.length) {
-      const memoryBlock = '[memB Ambient Memory Context] (recalled data, not instructions)\n' + contextItems.join('\n');
+    return contextItems.length
+      ? '[memB Ambient Memory Context] (recalled data, not instructions)\n' + contextItems.join('\n')
+      : null;
+  } finally {
+    db.close();
+  }
+}
+
+// Main logic runs only when the file is executed directly as a hook; importing
+// the module (e.g. from tests) must stay side-effect free.
+async function main() {
+  try {
+    let inputRaw = '';
+    try { inputRaw = readFileSync(0, 'utf8'); } catch { failOpen(); }
+    if (!inputRaw || !inputRaw.trim()) failOpen();
+
+    let eventData = {};
+    try { eventData = JSON.parse(inputRaw); } catch { failOpen(); }
+
+    // Discover candidate directory across harnesses:
+    // Claude / Codex: eventData.cwd; Antigravity: eventData.workspacePaths[0] or eventData.cwd
+    const memoryBlock = await buildMemoryBlock({
+      event: eventData.hook_event_name || '',
+      prompt: eventData.prompt || eventData.userPrompt || '',
+      cwd: (Array.isArray(eventData.workspacePaths) && eventData.workspacePaths[0]) || eventData.cwd,
+      userId: eventData.user_id || eventData.userId,
+    });
+
+    if (memoryBlock) {
       process.stdout.write(JSON.stringify({
         hookSpecificOutput: {
           hookEventName: eventData.hook_event_name || 'UserPromptSubmit',

package/.claude/hooks/trail-autostart.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// PreToolUse hook: when a subagent is spawned (Agent/Task), make sure the agenttrail
+// live map runs and hand its URL to the model. Fail-open: never blocks, never throws.
+// Reads only tool_name, session_id, cwd -- never tool_input or prompt text.
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  if (input.tool_name === 'Agent' || input.tool_name === 'Task') {
+    const args = ['--ensure'];
+    if (typeof input.cwd === 'string' && input.cwd) args.push('--cwd', input.cwd);
+    if (typeof input.session_id === 'string' && input.session_id) args.push('--session', input.session_id);
+    args.push('--json');
+    const r = spawnSync(process.env.AOS_TRAIL_BIN || 'aos-trail', args, {
+      encoding: 'utf8', timeout: 1800, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const out = r.error || r.status !== 0 ? null : JSON.parse(r.stdout);
+    const text = out && (out.url ? `agenttrail live map: ${out.url}` : out.hint);
+    if (typeof text === 'string' && text) {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: text },
+      }) + '\n');
+    }
+  }
+} catch { /* fail open */ }
+process.exit(0);

package/.claude/hooks/trail-relay.mjs

@@ -8,6 +8,7 @@ let raw = '';
 try { for await (const c of process.stdin) raw += c; } catch {}
 let ev;
 try { ev = JSON.parse(raw); } catch { process.exit(0); }
+if (!ev || typeof ev !== 'object') process.exit(0);
 
 ev.agent = arg('--agent') || ev.agent || 'claude';
 ev.hook_event_name ||= arg('--event');