@staix/agent-hub 0.12.20 → 0.12.22

package/src/cli/help.ts

@@ -24,11 +24,11 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub doctor --orphans [--kill]", "list registrations whose project root is gone; --kill stops their daemons (SIGTERM, then SIGKILL) only after the process identity checks out"],
     ["ahub kill", "stop this project's hub"],
     ["ahub reset [--all] [--yes]", "list, then with --yes stop the hub and discard every queued and needs_review delivery, clear holds and pauses and drop session pointers; --all moves the state directory to .agenthub/archive instead"],
-    ["ahub restart [--dry-run] [--yes]", "recover this project's runtime"],
-    ["ahub upgrade --to <version> [--dry-run] [--yes]", "review and upgrade running projects"],
-    ["ahub recovery status|resume|abort <operation-id>", "inspect, resume or cancel a preflight; status names the next actions"],
-    ["ahub recovery dispose <operation-id> --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
-    ["ahub recovery dispose <operation-id> --stop-and-archive --reason <text>", "end a partial operation: stop its own targets, archive its snapshot and release the lock; the upgrade is abandoned, not completed"],
+    ["ahub restart [--dry-run] [--yes]", "recover this project's runtime; on a terminal without a flag it reviews the plan with you, follows the progress and offers the next steps"],
+    ["ahub upgrade [--to <version>] [--dry-run] [--yes]", "review and upgrade running projects; --to defaults to the latest release (--yes needs it), and a newer release's own coordinator takes over; on a terminal without --dry-run or --yes: review, end agents first if you choose, apply, follow, and resume, cancel, end or reset on the spot"],
+    ["ahub recovery [status|resume|abort] [<operation-id>]", "inspect, resume or cancel a preflight; status names the next actions; without an id, the operation that holds the lock, and with nothing else on a terminal its screen"],
+    ["ahub recovery dispose [<operation-id>] --fresh-session codex|claude --reason <text>", "end a partial operation by starting that peer as a new session, recording the lost conversation"],
+    ["ahub recovery dispose [<operation-id>] --stop-and-archive --reason <text>", "end a partial operation: stop its own targets, archive its snapshot and release the lock; the upgrade is abandoned, not completed"],
     ["ahub daemon [--unattended]", "internal: the detached hub process that ahub up or the dashboard manager starts"],
     ["ahub recovery-run <operation-id>", "internal: the detached runner of an upgrade, restart or recovery resume"],
   ]],
@@ -38,11 +38,13 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub kimi [--print-command] [--model <alias>]", "start Kimi headless under ACP"],
     ["ahub pi [--print-command] [--mode headless|tui] [--backend auto|dgx|mlx] [--session-id <id>] [--session-file <path>]", "start Pi"],
     ["ahub local [--route <id> | --model <id>]", "start the hub-native worker on the self-hosted models (routing.toml)"],
+    ["ahub stop <peer>", "human only: stop a hub-owned headless peer; end TUI agents in their terminals"],
     ["ahub models setup|status|start|stop", "prepare or inspect local Ollama MLX (legacy stop is explicit)"],
   ]],
   ["Messages and approvals", [
     ["ahub say [@peer ...] <text>", "send as the console user (no @peer = broadcast); delivered at once, start the text with [STATUS] to let it batch or [FYI] for the record only"],
     ["ahub tail", "live stream of messages, states and permission requests"],
+    ["ahub permission [<peer> [ask|ask-when-needed|never-ask]] [--yes]", "human only: inspect or set a running peer mode; never-ask requires --yes; config never-ask waits for console y"],
     ["ahub permit <id> <option>", "answer a permission request shown by tail (\"deny\" cancels)"],
     ["ahub pause|resume <peer>", "hold a peer's deliveries in its queue / release them"],
     ["ahub queue list [--peer <id>] [--json]", "inspect durable deliveries"],
@@ -54,6 +56,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--detail <text>]", "put a task on the board; a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
     ["ahub task show|escalate <id>", "full task with history (PII text included) / hand it to the next peer in escalate_to"],
     ["ahub task assign <id> <peer>", "give a task to a peer yourself; a task that still waits is reserved for that peer instead"],
+    ["ahub task label <id> ok|regressed|reverted|incomplete|wrong|abandoned", "your later verdict on an approved task, kept in the research records (research must be on)"],
     ["ahub review <id> approved|changes_requested [note...] [--unmet <item>]...", "give a review verdict on a task"],
     ["ahub route explain <id>", "why a task went where it went, its reserved owner included"],
     ["ahub route explain --class <c> <title...>", "what would happen to such a task now"],
@@ -71,6 +74,14 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
     ["ahub undo <turn> [--yes] [--context]", "put back the files a turn changed; refuses files changed since. Without --yes it only lists them; --context also drops a Codex turn from its conversation"],
     ["ahub report [--since 7d|<iso>] [--by task] [--json]", "turns, tokens, messages, overlaps and task events per period"],
     ["ahub export [--since 7d|<iso>]", "structured events (events.jsonl) as JSON lines; never message bodies"],
+    ["ahub research [--since 30d] [--all] [--json]", "success, first-pass, rework and check-failure rates, tokens and wall time per approved task, from the opt-in research records"],
+    ["ahub research export [--format jsonl|csv] [--since 30d] [--all]", "the research records for outside analysis: ids, counts and tokens, never text"],
+    ["ahub research backfill", "build this project's research records once from events.jsonl"],
+    ["ahub bench run <suite.json> --arm <label> [--repeat N] [--tasks a,b]", "run a benchmark suite against the peers attached here, in a project kept for benchmarks (it resets the work tree)"],
+    ["ahub bench list|status", "benchmark runs on this machine / the one running now"],
+    ["ahub bench report <run> [--json]", "pass rate, first pass, rework, tokens and wall time per task and overall"],
+    ["ahub bench compare <run|arm>... [--suite <name>] [--mixed] [--json]", "compare arms of one suite with 95% bootstrap intervals; inconclusive below 5 counted attempts per arm"],
+    ["ahub bench export [--format jsonl|csv]", "benchmark records for outside analysis: ids, outcomes and counts, never suite text"],
     ["ahub check-path <file> [--peer <id>]", "other owners' open tasks that claim or changed a file"],
   ]],
   ["Hooks", [

package/src/cli/identity.ts

@@ -26,6 +26,7 @@ export type PeerCommandAccess = "allowed" | "conductor" | "console";
 
 /** A closed list: unknown commands cannot acquire console authority through an agent shell. */
 export function classifyPeerCommand(command: string, args: readonly string[]): PeerCommandAccess {
+  if (command === "permission" || command === "stop") return "console";
   if (args.some((arg) => arg === "--as-user" || arg.startsWith("--as-user="))) return "console";
   if (command === "task") {
     if (["propose", "show"].includes(args[0] ?? "")) return "allowed";
@@ -33,6 +34,11 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
     return "console";
   }
   if (command === "route") return args[0] === "explain" ? "allowed" : "console";
+  // #247: reading the research measures and records is harmless (ids and counts only); writing them is a person's.
+  if (command === "research") return args[0] === "backfill" ? "console" : "allowed";
+  // #251: a run resets the bench project's tree and proposes work; reading results is harmless.
+  // The subcommand is the first argument that is not --json, which the command accepts anywhere.
+  if (command === "bench") return args.find((arg) => arg !== "--json") === "run" ? "console" : "allowed";
   if (command === "budget") return !args.length || args.every((arg) => arg === "--json") ? "allowed" : "console";
   if (["claude", "codex", "kimi", "pi", "local", "pause", "resume"].includes(command)) return "conductor";
   if (["help", "version", "--version", "say", "status", "board", "report", "turns", "review", "remember", "facts", "check-path"].includes(command)) return "allowed";
@@ -41,10 +47,10 @@ export function classifyPeerCommand(command: string, args: readonly string[]): P
 
 /** No argument text is included: notices and refusal logs must not copy task text or credentials. */
 export function cliCommandLabel(command: string, args: readonly string[]): string {
-  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "status", "logs", "export", "report", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
-  if (["task", "queue", "budget", "route", "recovery", "models", "projects"].includes(command)) {
-    const sub = args[0];
-    if (sub && ["propose", "show", "assign", "escalate", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "setup", "start", "stop", "remove"].includes(sub)) return `${command} ${sub}`;
+  if (!["upgrade", "restart", "recovery", "recovery-run", "help", "--help", "--version", "version", "projects", "ui", "manager", "setup", "init", "daemon", "up", "console", "claude", "codex", "kimi", "pi", "local", "stop", "models", "say", "queue", "tail", "budget", "board", "task", "review", "remember", "ask", "route", "pause", "resume", "permit", "permission", "status", "logs", "export", "report", "research", "bench", "facts", "check-path", "turns", "undo", "kill", "reset", "doctor"].includes(command)) return "unknown";
+  if (["task", "queue", "budget", "route", "recovery", "models", "projects", "research", "bench"].includes(command)) {
+    const sub = command === "bench" ? args.find((arg) => arg !== "--json") : args[0];
+    if (sub && ["propose", "show", "assign", "escalate", "label", "list", "resolve", "resume", "set", "execution", "explain", "status", "abort", "dispose", "setup", "start", "stop", "remove", "export", "backfill", "run", "report", "compare"].includes(sub)) return `${command} ${sub}`;
   }
   return (/^[a-z][a-z0-9-]*$/.test(command) && !/\s/.test(command)) || ["--help", "--version"].includes(command) ? command : "unknown";
 }

package/src/cli/launch.ts

@@ -1,7 +1,11 @@
 // Launchers inject only the flags the hub owns and refuse user-supplied duplicates.
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { peerChildEnv } from "../hub/child-process.ts";
+import { mkdirSync, writeFileSync, renameSync, unlinkSync, lstatSync, readFileSync, openSync, closeSync, readSync, accessSync, constants, linkSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { randomUUID, createHash } from "node:crypto";
+import { resolve, join, basename, dirname, isAbsolute } from "node:path";
+import { processLiveness, processSignature } from "../pi/process-signature.ts";
+import { realPath } from "../hub/project.ts";
+import { peerChildEnv, processTable } from "../hub/child-process.ts";
 export const CLAUDE_CHANNEL = "plugin:agent-hub@agent-hub";
 
 /** Launch identity belongs to the native child, never to the agent that invoked the wrapper. */
@@ -40,6 +44,210 @@ export interface Launch {
   cmd: string;
   args: string[];
   warning?: string;
+  permissionHook?: boolean;
+  hookPurpose?: FactsHook["purpose"];
+  settingsFile?: string;
+  unattended?: boolean;
+}
+
+/** Retire only our prior private Claude settings file, after the replacement launch record is committed. */
+export function cleanupClaudeSettings(stateDir: string, previous: unknown): void {
+  if (typeof previous !== "string" || !isAbsolute(previous) || !/^claude-settings-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.json$/.test(basename(previous))) return;
+  try {
+    const root = realPath(stateDir);
+    if (realPath(dirname(previous)) !== root) return;
+    const stat = lstatSync(previous);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
+    if (realPath(previous) !== join(root, basename(previous))) return;
+    unlinkSync(previous);
+  } catch { /* Missing or unverifiable files remain untouched. */ }
+}
+
+/** Crash fallback only: an absent/unreadable owner identity never certifies that its native launch ended. */
+export function cleanupStaleClaudeSettings(stateDir: string, previous: unknown, identity = processSignature): void {
+  if (!previous || typeof previous !== "object" || Array.isArray(previous)) return;
+  const original = previous as Record<string, unknown>;
+  const record = readClaudeNative(stateDir, original as ClaudeLaunchRecord) ?? original;
+  if (typeof record.launcherSignature !== "string" || !record.launcherSignature) return;
+  if (processLiveness(record.launcherPid, record.launcherSignature, identity) !== "gone") return;
+  if (typeof record.nativePid !== "number" || !Number.isSafeInteger(record.nativePid) || record.nativePid <= 0 || record.nativePid === record.launcherPid || typeof record.nativeSignature !== "string" || !record.nativeSignature) return;
+  if (record.nativeIdentity === "direct-child") {
+    // A direct child may exec in place. A changed signature while its PID still runs cannot certify native exit.
+    // The shared table excludes exited zombies; an unavailable table certifies nothing.
+    const table = processTable();
+    if (!table || table.some(row => row.pid === record.nativePid)) return;
+  } else if (processLiveness(record.nativePid, record.nativeSignature, identity) !== "gone") return;
+  cleanupClaudeSettings(stateDir, record.settingsFile);
+  removeClaudeNative(stateDir, original as ClaudeLaunchRecord);
+}
+
+export interface ClaudeLaunchRecord extends Record<string, unknown> {
+  instanceId: string; launchId: string; settingsFile?: string; launcherPid: number; launcherSignature?: string;
+}
+
+export interface ClaudeLaunchPublication { recorded: boolean; warning?: string; }
+
+/** Native attestation alone is serialized; managed hook metadata never waits on this lock. */
+async function withClaudeLaunchRecord(stateDir: string, action: () => void): Promise<ClaudeLaunchPublication> {
+  const lock = join(stateDir, "claude-launch.lock"), temp = `${lock}.${randomUUID()}.tmp`;
+  const skipped = (reason = `${lock} is busy or unverified`): ClaudeLaunchPublication => ({ recorded: false, warning: `Native identity and crash cleanup disabled for this launch; managed hook record stays current. ${reason}; inspect ${lock} and verify its owner has ended before removing it.` });
+  const signature = processSignature(process.pid);
+  if (!signature) return skipped("launcher identity could not be verified");
+  let locked = false, tempCreated = false, own: { dev: number; ino: number } | undefined;
+  try {
+    const fd = openSync(temp, "wx", 0o600); tempCreated = true;
+    try { writeFileSync(fd, JSON.stringify({ pid: process.pid, signature })); } finally { closeSync(fd); }
+    const stat = lstatSync(temp); own = { dev: stat.dev, ino: stat.ino };
+    const deadline = performance.now() + 250;
+    for (;;) {
+      try { linkSync(temp, lock); break; }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") return skipped();
+        let before;
+        try { before = lstatSync(lock); } catch { if (performance.now() < deadline) continue; return skipped(); }
+        if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || (before.mode & 0o777) !== 0o600 || !process.getuid || before.uid !== process.getuid()) return skipped();
+        let owner: { pid?: unknown; signature?: unknown };
+        try { owner = JSON.parse(readFileSync(lock, "utf8")); } catch { return skipped(); }
+        if (!owner || typeof owner.signature !== "string" || !owner.signature) return skipped();
+        const alive = processLiveness(owner.pid, owner.signature);
+        if (alive === "unknown") return skipped();
+        if (alive === "live") {
+          if (performance.now() >= deadline) return skipped();
+          await new Promise(resolve => setTimeout(resolve, 25)); continue;
+        }
+        const current = lstatSync(lock);
+        if (current.dev !== before.dev || current.ino !== before.ino) return skipped();
+        unlinkSync(lock);
+      }
+    }
+    locked = true;
+    unlinkSync(temp);
+    try { action(); } catch { return skipped("native attestation publication failed"); }
+    return { recorded: true };
+  } catch { return skipped("native attestation lock could not be read or published"); }
+  finally {
+    if (locked && own) {
+      try { const current = lstatSync(lock); if (current.dev === own.dev && current.ino === own.ino) unlinkSync(lock); }
+      catch { /* only our verified lock may be removed */ }
+    }
+    if (tempCreated) { try { unlinkSync(temp); } catch { /* our populated temp may already be linked and consumed */ } }
+  }
+}
+
+function writeClaudeLaunchRecord(stateDir: string, record: Record<string, unknown>): void {
+  const file = join(stateDir, "claude-launch.json"), temp = `${file}.${randomUUID()}.tmp`;
+  try { writeFileSync(temp, JSON.stringify(record), { mode: 0o600 }); renameSync(temp, file); }
+  finally { try { unlinkSync(temp); } catch { /* the rename normally consumed it */ } }
+}
+
+export function recordClaudeLaunch(stateDir: string, record: ClaudeLaunchRecord): ClaudeLaunchPublication {
+  writeClaudeLaunchRecord(stateDir, record);
+  return { recorded: true };
+}
+
+function sameClaudeLaunch(left: ClaudeLaunchRecord, right: ClaudeLaunchRecord): boolean {
+  return left.instanceId === right.instanceId && left.launchId === right.launchId && left.settingsFile === right.settingsFile
+    && left.launcherPid === right.launcherPid && left.launcherSignature === right.launcherSignature;
+}
+function nativeAttestationPath(stateDir: string, launch: ClaudeLaunchRecord): string {
+  const hash = createHash("sha256").update(JSON.stringify([launch.instanceId, launch.launchId, launch.settingsFile, launch.launcherPid, launch.launcherSignature])).digest("hex");
+  return join(stateDir, `claude-native-${hash}.json`);
+}
+function privateClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): { file: string; stat: ReturnType<typeof lstatSync>; record: ClaudeLaunchRecord } | undefined {
+  const file = nativeAttestationPath(stateDir, launch);
+  try {
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
+    const record = JSON.parse(readFileSync(file, "utf8")) as ClaudeLaunchRecord;
+    if (!record || !sameClaudeLaunch(record, launch) || typeof record.nativePid !== "number" || !Number.isSafeInteger(record.nativePid) || record.nativePid <= 0 || typeof record.nativeSignature !== "string" || !record.nativeSignature || record.nativeIdentity !== "direct-child") return;
+    return { file, stat, record };
+  } catch { return; }
+}
+export function readClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): ClaudeLaunchRecord | undefined {
+  return privateClaudeNative(stateDir, launch)?.record;
+}
+function removeClaudeNative(stateDir: string, launch: ClaudeLaunchRecord): void {
+  const saved = privateClaudeNative(stateDir, launch); if (!saved?.stat) return;
+  try { const now = lstatSync(saved.file); if (now.dev === saved.stat.dev && now.ino === saved.stat.ino) unlinkSync(saved.file); }
+  catch { /* absent or replaced native proof remains untouched */ }
+}
+
+/** Never attach an old child's identity to a replacement launch, even when its spawn callback arrives later. */
+export async function recordClaudeNative(stateDir: string, launch: ClaudeLaunchRecord, pid: number, signature: string, report?: (warning: string) => void): Promise<boolean> {
+  let recorded = false;
+  const publication = await withClaudeLaunchRecord(stateDir, () => {
+    let current: ClaudeLaunchRecord;
+    try {
+      const file = join(stateDir, "claude-launch.json"), stat = lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || (stat.mode & 0o777) !== 0o600 || !process.getuid || stat.uid !== process.getuid()) return;
+      current = JSON.parse(readFileSync(file, "utf8"));
+    } catch { return; }
+    if (!sameClaudeLaunch(current, launch)) return;
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid === launch.launcherPid || !signature) return;
+    const file = nativeAttestationPath(stateDir, launch), temp = `${file}.${randomUUID()}.tmp`;
+    try {
+      lstatSync(file);
+      const saved = privateClaudeNative(stateDir, launch);
+      recorded = !!saved && saved.record.nativePid === pid && saved.record.nativeSignature === signature;
+      return; // a launch's first native proof is immutable; an unknown file is never overwritten
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") return; }
+    try {
+      writeFileSync(temp, JSON.stringify({ ...launch, nativePid: pid, nativeSignature: signature, nativeIdentity: "direct-child" }), { mode: 0o600, flag: "wx" });
+      renameSync(temp, file);
+    } finally { try { unlinkSync(temp); } catch { /* atomic rename consumed our private temporary file */ } }
+    try { recorded = sameClaudeLaunch(JSON.parse(readFileSync(join(stateDir, "claude-launch.json"), "utf8")), launch); } catch { /* replaced or unreadable managed record */ }
+  });
+  if (publication.warning) report?.(publication.warning);
+  return publication.recorded && recorded;
+}
+
+/** Scripts and interpreters can leave a different native owner behind: their crash cleanup remains disabled. */
+function directNativeExecutable(command: string, cwd: string, env: NodeJS.ProcessEnv): boolean {
+  const interpreter = /^(?:node|bun|deno|env|busybox|python(?:[0-9.]+)?|ruby|perl|bash|sh|zsh|fish|dash|ksh|csh|tcsh|ash)(?:\.exe)?$/;
+  if (interpreter.test(basename(command))) return false;
+  const paths = command.includes("/") ? [resolve(cwd, command)] : (env.PATH ?? "").split(":").filter(Boolean).map(path => resolve(cwd, path, command));
+  for (const path of paths) {
+    let fd: number | undefined;
+    try {
+      const target = realPath(path);
+      accessSync(target, constants.X_OK);
+      if (interpreter.test(basename(target))) return false;
+      fd = openSync(target, "r");
+      const bytes = Buffer.alloc(4); if (readSync(fd, bytes, 0, 4, 0) !== 4) return false;
+      return ["7f454c46", "feedface", "cefaedfe", "feedfacf", "cffaedfe", "cafebabe", "bebafeca", "cafebabf", "bfbafeca"].includes(bytes.toString("hex"));
+    } catch { /* resolve the next PATH entry */ }
+    finally { if (fd !== undefined) closeSync(fd); }
+  }
+  return false;
+}
+
+/** Same native stdio/environment and exit result as spawnSync, with a live child identity before it exits. */
+export async function runClaudeLaunch(launch: Launch, options: { cwd: string; env: NodeJS.ProcessEnv; stateDir: string; record?: ClaudeLaunchRecord }): Promise<{ status: number | null; signal: NodeJS.Signals | null; error?: Error }> {
+  const direct = directNativeExecutable(launch.cmd, options.cwd, options.env);
+  return new Promise(resolveResult => {
+    let attestation: Promise<unknown> | undefined;
+    let childSignature: string | undefined;
+    const child = spawn(launch.cmd, launch.args, { cwd: options.cwd, env: options.env, stdio: "inherit" });
+    child.once("spawn", () => {
+      if (!options.record || !child.pid) return;
+      const unavailable = (reason: string) => console.error(`Native identity and crash cleanup disabled for this launch; managed hook record stays current. ${reason}.`);
+      if (!direct) { unavailable("native executable is a script or an unverified interpreter"); return; }
+      if (!options.record.launcherSignature) { unavailable("launcher identity could not be verified"); return; }
+      const signature = processSignature(child.pid);
+      if (!signature) { unavailable("native process identity could not be verified"); return; }
+      childSignature = signature;
+      attestation = recordClaudeNative(options.stateDir, options.record, child.pid, signature, warning => console.error(warning)).catch(() => undefined);
+    });
+    child.once("error", error => resolveResult({ status: null, signal: null, error }));
+    child.once("exit", async (status, signal) => {
+      await attestation;
+      if (options.record) {
+        const saved = readClaudeNative(options.stateDir, options.record);
+        if (saved && typeof child.pid === "number" && saved.nativePid === child.pid && saved.nativeSignature === childSignature) removeClaudeNative(options.stateDir, options.record);
+      } // this child's observed exit, after its last bounded write
+      resolveResult({ status, signal });
+    });
+  });
 }
 
 export interface StatusLineTee {
@@ -61,22 +269,22 @@ export function statusLineSettings(tee: StatusLineTee): string {
   return JSON.stringify({ statusLine: { type: "command", command, refreshInterval: tee.original?.refreshInterval ?? 10, ...(tee.original?.padding !== undefined ? { padding: tee.original.padding } : {}) } });
 }
 
-/** The turn-free facts hook (issue #108): absolute path of src/cli/facts-hook.ts and the hub's state dir. */
+/** Shared facts, native observation and permission hook transport. */
 export interface FactsHook {
   script: string;
   stateDir: string;
   /** The same hook transport can observe native turns without injecting facts. */
-  purpose?: "facts" | "idle" | "facts-and-idle";
+  purpose?: "facts" | "idle" | "facts-and-idle" | "permission";
   /** Observe native sessions/turns for every enabled facts, idle or conductor hook configuration. */
   observeNative?: boolean;
 }
 
-/** Shared by actual launch and read-only preview; advisory facts remain disabled. */
-export function claudeObservationHooks(config: { coordination?: string; task_sweep?: { enabled: boolean }; roles?: Record<string, string[]> }, paths: Pick<FactsHook, "script" | "stateDir">): FactsHook | undefined {
+/** Shared by actual launch and preview; permissions are always enabled, advisory facts remain disabled. */
+export function claudeObservationHooks(config: { coordination?: string; task_sweep?: { enabled: boolean }; roles?: Record<string, string[]> }, paths: Pick<FactsHook, "script" | "stateDir">): FactsHook {
   const facts = config.coordination === "turn-free";
   const idle = config.task_sweep?.enabled === true;
   const observeNative = facts || idle || config.roles?.claude?.includes("conductor") === true;
-  return facts || idle || observeNative ? { ...paths, purpose: facts ? (idle ? "facts-and-idle" : "facts") : "idle", ...(observeNative ? { observeNative: true } : {}) } : undefined;
+  return { ...paths, purpose: facts ? (idle ? "facts-and-idle" : "facts") : idle || observeNative ? "idle" : "permission", ...(observeNative ? { observeNative: true } : {}) };
 }
 
 /**
@@ -84,11 +292,11 @@ export function claudeObservationHooks(config: { coordination?: string; task_swe
  * facts hook before and after every tool call and at the end of each turn (issue #108; the turn end is the quiescence
  * evidence of issue #107).
  */
-export function sessionSettings(tee: StatusLineTee, facts?: FactsHook): string {
-  const settings = JSON.parse(statusLineSettings(tee)) as Record<string, unknown>;
+export function sessionSettings(tee?: StatusLineTee, facts?: FactsHook): string {
+  const settings = (tee ? JSON.parse(statusLineSettings(tee)) : {}) as Record<string, unknown>;
   if (facts) {
-    const hooks = [{ type: "command", command: `AGENTHUB_STATE_DIR=${sh(facts.stateDir)} bun ${sh(facts.script)}`, timeout: 5 }];
-    settings.hooks = { PreToolUse: [{ matcher: "*", hooks }], PostToolUse: [{ matcher: "*", hooks }], Stop: [{ hooks }] };
+    const hooks = [{ type: "command", command: `AGENTHUB_STATE_DIR=${sh(facts.stateDir)} AGENTHUB_HOOK_PURPOSE=${sh(facts.purpose ?? "facts")} bun ${sh(facts.script)}`, timeout: 5 }];
+    settings.hooks = { PreToolUse: [{ matcher: "*", hooks }], ...(facts.purpose !== "permission" ? { PostToolUse: [{ matcher: "*", hooks }], Stop: [{ hooks }] } : {}) };
     if (facts.observeNative) Object.assign(settings.hooks as object, { SessionStart: [{ matcher: "*", hooks }], UserPromptSubmit: [{ hooks }] });
   }
   return JSON.stringify(settings);
@@ -97,7 +305,7 @@ export function sessionSettings(tee: StatusLineTee, facts?: FactsHook): string {
 export function buildLaunch(
   tool: "claude" | "codex",
   userArgs: string[],
-  ctx: { unattended: boolean; proxyUrl?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook },
+  ctx: { unattended: boolean; proxyUrl?: string; codexBin?: string; statusLine?: StatusLineTee; facts?: FactsHook; preview?: boolean },
 ): Launch {
   // Hub-level switches are consumed here; everything else passes through to the tool.
   const passthrough = userArgs.filter((a) => !["--unattended", "--safe", "--new"].includes(a));
@@ -109,17 +317,62 @@ export function buildLaunch(
   if (tool === "claude") {
     // `--settings` takes one value, so a user-supplied one wins and Claude has no quota source for that session.
     const own = passthrough.some((a) => a === "--settings" || a.startsWith("--settings="));
-    const tee = ctx.statusLine && !own ? ["--settings", sessionSettings(ctx.statusLine, ctx.facts)] : [];
+    let settingsArgs = ctx.statusLine && !own ? ["--settings", sessionSettings(ctx.statusLine, ctx.facts)] : [];
+    let nativeArgs = passthrough;
+    let settingsFile: string | undefined;
+    if (own) {
+      if (passthrough.filter(a => a === "--settings" || a.startsWith("--settings=")).length > 1) throw new Error("pass --settings only once so the hub permission hook stays installed");
+      const index = passthrough.findIndex(a => a === "--settings" || a.startsWith("--settings="));
+      const arg = passthrough[index]!;
+      const value = arg === "--settings" ? passthrough[index + 1] : arg.slice("--settings=".length);
+      if (!value) throw new Error("--settings requires a JSON object or readable file so the hub permission hook can be installed");
+      let caller: Record<string, unknown>;
+      try {
+        caller = JSON.parse(value.trim().startsWith("{") ? value : readFileSync(resolve(value), "utf8"));
+        if (!caller || typeof caller !== "object" || Array.isArray(caller)) throw new Error("not an object");
+      } catch { throw new Error("cannot read --settings as a JSON object; the hub permission hook must be installed"); }
+      if (ctx.facts && caller.disableAllHooks === true) throw new Error("--settings disableAllHooks prevents the required hub permission hook; enable hooks to launch");
+      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
+      const callerHooks = caller.hooks;
+      if (callerHooks !== undefined && (!callerHooks || typeof callerHooks !== "object" || Array.isArray(callerHooks))) throw new Error("--settings hooks must be an object");
+      const hooks = { ...(callerHooks as Record<string, unknown> | undefined) };
+      for (const [event, entries] of Object.entries(injected.hooks ?? {})) {
+        const existing = hooks[event];
+        if (existing !== undefined && !Array.isArray(existing)) throw new Error(`--settings ${event} hooks must be an array`);
+        hooks[event] = [...(existing as unknown[] | undefined ?? []), ...(entries as unknown[])];
+      }
+      settingsArgs = ["--settings", JSON.stringify({ ...caller, ...(ctx.facts ? { hooks } : {}) })];
+      nativeArgs = passthrough.filter((_, i) => i !== index && (arg !== "--settings" || i !== index + 1));
+    } else if (ctx.facts && !ctx.statusLine) {
+      const injected = JSON.parse(sessionSettings(undefined, ctx.facts));
+      settingsArgs = ["--settings", JSON.stringify({ hooks: injected.hooks })];
+    }
+    if (settingsArgs.length && !ctx.preview) {
+      const stateDir = ctx.facts?.stateDir ?? ctx.statusLine?.stateDir;
+      if (!stateDir) throw new Error("Claude session settings require the hub state directory");
+      const file = join(stateDir, `claude-settings-${randomUUID()}.json`);
+      try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(`${file}.tmp`, settingsArgs[1]!, { mode: 0o600, flag: "wx" });
+        renameSync(`${file}.tmp`, file);
+      } catch {
+        try { unlinkSync(`${file}.tmp`); } catch { /* no temp file was written */ }
+        throw new Error("cannot write private Claude session settings in the hub state directory");
+      }
+      settingsArgs[1] = file;
+      settingsFile = file;
+    }
     const notes = [
       unattended ? UNATTENDED_WARNING : "",
       ctx.statusLine && own ? "note: you passed --settings, so the hub's status line tee is off and the budget coordinator cannot see Claude's quota (ahub budget set claude <0..1> still works)." : "",
-      ctx.facts && own && ctx.facts.purpose !== "idle" ? "note: you passed --settings, so the hub's turn-free facts hooks are off for this session: Claude will not see the other agents' changes at its tool calls." : "",
-      ctx.facts && own && (ctx.facts.purpose === "idle" || ctx.facts.purpose === "facts-and-idle") ? "note: you passed --settings, so native idle observation hooks are off for this session: task idle sweeps cannot verify Claude between turns." : "",
-      ctx.facts?.observeNative && own ? "note: you passed --settings, so native session/turn observation hooks are off: completed turns and supervision tokens may be unavailable." : "",
     ].filter(Boolean);
     return {
       cmd: "claude",
-      args: ["--dangerously-load-development-channels", claudeChannel(passthrough), ...(unattended ? ["--dangerously-skip-permissions"] : []), ...tee, ...passthrough],
+      args: ["--dangerously-load-development-channels", claudeChannel(passthrough), ...(unattended ? ["--dangerously-skip-permissions"] : []), ...settingsArgs, ...nativeArgs],
+      ...(settingsFile ? { settingsFile } : {}),
+      permissionHook: !!ctx.facts,
+      ...(ctx.facts ? { hookPurpose: ctx.facts.purpose ?? "facts" } : {}),
+      unattended,
       ...(notes.length ? { warning: notes.join("\n") } : {}),
     };
   }
@@ -127,6 +380,7 @@ export function buildLaunch(
   return {
     cmd: ctx.codexBin ?? "codex",
     args: ["--enable", "tui_app_server", "--remote", ctx.proxyUrl, ...(unattended ? ["--dangerously-bypass-approvals-and-sandbox"] : []), ...passthrough],
+    unattended,
     ...warning,
   };
 }