@rasensio/aidlc 1.86.0 → 1.88.0

package/dist/hooks/approval-guard.js

@@ -0,0 +1,293 @@
+/**
+ * The approval guard: a Claude Code `PreToolUse` hook that blocks an agent from
+ * running the commands only a person may run, or writing the autopilot
+ * approval record (agent-cannot-approve-itself/AC-8..AC-13).
+ *
+ * The opposite contract to the phase guard (`guard.ts`), on purpose, and the
+ * same one as the reviewer guard (`compile/reviewer-guard.ts`): this is a
+ * boundary, so every way it can fail is a block. The script exits 2 on anything
+ * it cannot read, and the hook command turns any other exit — a missing script,
+ * a missing `node`, a crash — into 2 as well.
+ *
+ * It is a standalone script rather than an `aidlc hook` subcommand because it
+ * runs before every agent shell and file-write call: starting the CLI each time
+ * is slow, and a broken build would block every call (design D1). The logic is
+ * written once, here, as `guardVerdict`, and embedded in the script with
+ * `Function.prototype.toString` — so it must stay self-contained.
+ *
+ * It is a denylist, and a shell denylist can be talked around (`sh -c`, a
+ * variable, a script file). The CLI's terminal check (`human-only.ts`) is the
+ * line; this is the early, logged layer (design D2).
+ *
+ * Design: design.md C3
+ *
+ * @module
+ */
+import { HUMAN_ONLY, SUBJECT_LIMIT } from './human-only.js';
+import { LIFECYCLE_HOOK_MARKER } from './install.js';
+export const APPROVAL_GUARD_PATH = '.claude/hooks/aidlc-approval-guard.mjs';
+export const APPROVAL_GUARD_MATCHER = 'Bash|Edit|Write|MultiEdit|NotebookEdit';
+/**
+ * The settings.json command. Exit 0 allows and 2 blocks with the script's own
+ * reason; any other status means the guard did not run, which blocks too, with a
+ * line saying so (AC-12). `$CLAUDE_PROJECT_DIR` because a hook runs in the
+ * session's working directory, which need not be the root.
+ */
+export function approvalGuardCommand() {
+    return (`node "$CLAUDE_PROJECT_DIR/${APPROVAL_GUARD_PATH}"; s=$?; [ "$s" = 0 ] && exit 0; ` +
+        `[ "$s" = 2 ] || echo 'AIDLC approval guard could not run, so the call is blocked; reinstall it with: aidlc hook install' >&2; ` +
+        `exit 2 ${LIFECYCLE_HOOK_MARKER}`);
+}
+/**
+ * Block or pass one `PreToolUse` payload. Self-contained: no imports and no
+ * outer references, because the rendered script carries its source text.
+ */
+export function guardVerdict(input, rules) {
+    const STATE_FILE = 'aidlc/autopilot/state.json';
+    const FILE_TOOLS = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
+    const unreadable = {
+        block: true,
+        rule: 'unreadable-input',
+        reason: 'the hook input could not be read as a tool call, so the approval guard blocks it',
+        subject: '',
+    };
+    if (typeof input !== 'object' || input === null)
+        return unreadable;
+    const toolName = input.tool_name;
+    const toolInput = input.tool_input;
+    if (typeof toolName !== 'string' || typeof toolInput !== 'object' || toolInput === null)
+        return unreadable;
+    if (FILE_TOOLS.includes(toolName)) {
+        const target = toolInput.file_path ?? toolInput.notebook_path;
+        if (typeof target !== 'string')
+            return unreadable;
+        if (!target.replace(/\\/g, '/').endsWith(STATE_FILE))
+            return { block: false };
+        return {
+            block: true,
+            rule: 'approval-record',
+            reason: 'autopilot approvals are recorded only by `aidlc autopilot approve`, run by a person in their own terminal',
+            subject: target,
+        };
+    }
+    if (toolName !== 'Bash')
+        return { block: false };
+    const command = toolInput.command;
+    if (typeof command !== 'string')
+        return unreadable;
+    // Words as a POSIX shell would split them, for this purpose only: quotes and
+    // backslashes join, so a quoted mention is one word that names no program
+    // (AC-9). Operators end a segment. A `$(…)` or backtick body inside double
+    // quotes still runs, so it is scanned as a command of its own.
+    function split(text) {
+        const segments = [];
+        const nested = [];
+        let words = [];
+        let word = '';
+        let inWord = false;
+        const endWord = () => {
+            if (inWord)
+                words.push(word);
+            word = '';
+            inWord = false;
+        };
+        const endSegment = () => {
+            endWord();
+            if (words.length > 0)
+                segments.push(words);
+            words = [];
+        };
+        const closingParen = (from) => {
+            let depth = 1;
+            for (let j = from; j < text.length; j++) {
+                if (text[j] === '(')
+                    depth++;
+                else if (text[j] === ')' && --depth === 0)
+                    return j;
+            }
+            return text.length;
+        };
+        for (let i = 0; i < text.length; i++) {
+            const c = text[i];
+            if (c === "'") {
+                const end = text.indexOf("'", i + 1);
+                const stop = end === -1 ? text.length : end;
+                word += text.slice(i + 1, stop);
+                inWord = true;
+                i = stop;
+            }
+            else if (c === '"') {
+                inWord = true;
+                let j = i + 1;
+                for (; j < text.length && text[j] !== '"'; j++) {
+                    const d = text[j];
+                    if (d === '\\' && j + 1 < text.length) {
+                        word += text[++j];
+                    }
+                    else if (d === '$' && text[j + 1] === '(') {
+                        const end = closingParen(j + 2);
+                        nested.push(text.slice(j + 2, end));
+                        word += text.slice(j, end + 1);
+                        j = end;
+                    }
+                    else if (d === '`') {
+                        const end = text.indexOf('`', j + 1);
+                        const stop = end === -1 ? text.length : end;
+                        nested.push(text.slice(j + 1, stop));
+                        word += text.slice(j, stop + 1);
+                        j = stop;
+                    }
+                    else {
+                        word += d;
+                    }
+                }
+                i = j;
+            }
+            else if (c === '\\') {
+                if (i + 1 < text.length && text[i + 1] !== '\n') {
+                    word += text[i + 1];
+                    inWord = true;
+                }
+                i++;
+            }
+            else if (c === ' ' || c === '\t' || c === '\r') {
+                endWord();
+            }
+            else if (c === '#' && !inWord) {
+                const nl = text.indexOf('\n', i);
+                i = nl === -1 ? text.length : nl - 1;
+            }
+            else if (';&|()\n`'.includes(c) || (c === '$' && text[i + 1] === '(')) {
+                endSegment();
+                if (c === '$')
+                    i++;
+            }
+            else if (c === '<' || c === '>') {
+                endWord();
+            }
+            else {
+                word += c;
+                inWord = true;
+            }
+        }
+        endSegment();
+        return { segments, nested };
+    }
+    function matchSegment(words) {
+        const at = words.findIndex((w) => w.split('/').pop() === 'aidlc' || w.endsWith('dist/cli.js'));
+        if (at === -1)
+            return null;
+        const args = words.slice(at + 1);
+        const positionals = args.filter((a) => !a.startsWith('-'));
+        for (const rule of rules) {
+            if (!rule.words.every((w, k) => positionals[k] === w))
+                continue;
+            const flag = rule.flag;
+            if (flag !== null && !args.some((a) => a === flag || a.startsWith(`${flag}=`)))
+                continue;
+            return rule;
+        }
+        return null;
+    }
+    function scan(text, depth) {
+        const { segments, nested } = split(text);
+        for (const words of segments) {
+            const hit = matchSegment(words);
+            if (hit !== null)
+                return hit;
+        }
+        if (depth >= 4)
+            return null;
+        for (const inner of nested) {
+            const hit = scan(inner, depth + 1);
+            if (hit !== null)
+                return hit;
+        }
+        return null;
+    }
+    const hit = scan(command, 0);
+    if (hit === null)
+        return { block: false };
+    return {
+        block: true,
+        rule: hit.rule,
+        reason: `${hit.label} needs a person: an agent may not approve, override or confirm its own gates. ` +
+            'Ask the person to run it in their own terminal',
+        subject: command,
+    };
+}
+/** The script `aidlc hook install` writes to `APPROVAL_GUARD_PATH`. */
+export function renderApprovalGuard() {
+    return `#!/usr/bin/env node
+// Generated by \`aidlc hook install\` — do not edit by hand; the next install overwrites it.
+//
+// AIDLC approval guard. Claude Code runs it before every Bash, Edit, Write,
+// MultiEdit and NotebookEdit call: exit 0 lets the call run, exit 2 blocks it and
+// shows stderr to the agent. The hook command blocks on any other exit as well.
+
+import { appendFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+const RULES = ${JSON.stringify(HUMAN_ONLY)};
+const SUBJECT_LIMIT = ${SUBJECT_LIMIT};
+
+${guardVerdict.toString()}
+
+// The refusal log: <git-common-dir>/aidlc/refusals.ndjson, found by reading
+// files rather than spawning git; .aidlc/refusals.ndjson outside a repository.
+function logPath(root) {
+  for (let dir = resolve(root); ; dir = dirname(dir)) {
+    const dotgit = join(dir, '.git');
+    try {
+      let gitdir = dotgit;
+      if (!statSync(dotgit).isDirectory()) {
+        const m = /^gitdir:\\s*(.+)$/m.exec(readFileSync(dotgit, 'utf8'));
+        if (m === null) break;
+        gitdir = resolve(dir, m[1].trim());
+      }
+      let common = gitdir;
+      try {
+        common = resolve(gitdir, readFileSync(join(gitdir, 'commondir'), 'utf8').trim());
+      } catch {
+        // a primary checkout has no commondir file
+      }
+      return join(common, 'aidlc', 'refusals.ndjson');
+    } catch {
+      // no .git here
+    }
+    if (dirname(dir) === dir) break;
+  }
+  return join(resolve(root), '.aidlc', 'refusals.ndjson');
+}
+
+let verdict;
+let session;
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  session = input?.session_id;
+  verdict = guardVerdict(input, RULES);
+} catch {
+  verdict = guardVerdict(null, RULES);
+}
+if (!verdict.block) process.exit(0);
+
+try {
+  const path = logPath(process.env.CLAUDE_PROJECT_DIR || process.cwd());
+  mkdirSync(dirname(path), { recursive: true });
+  const entry = {
+    at: new Date().toISOString(),
+    where: 'guard',
+    rule: verdict.rule,
+    reason: verdict.reason,
+    subject: String(verdict.subject).slice(0, SUBJECT_LIMIT),
+  };
+  if (typeof session === 'string') entry.session = session;
+  appendFileSync(path, JSON.stringify(entry) + '\\n');
+} catch {
+  // a refusal that cannot be logged is still a refusal
+}
+process.stderr.write('AIDLC: ' + verdict.reason + '.\\n');
+process.exit(2);
+`;
+}
+//# sourceMappingURL=approval-guard.js.map

package/dist/hooks/approval-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-guard.js","sourceRoot":"","sources":["../../src/hooks/approval-guard.ts"],"names":[],"mappings":"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"}

package/dist/hooks/human-only.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The commands only a person may run, and the check that refuses them to an
+ * agent (agent-cannot-approve-itself/AC-1..AC-6, AC-14, AC-15).
+ *
+ * Each command exists so that a person can say yes: carry a paused item on,
+ * pass the ownership gate, reopen from testing. An agent that runs one approves
+ * its own work, which empties "approved" of meaning.
+ *
+ * This check is the line; the approval guard (`approval-guard.ts`) is the early,
+ * logged layer in Claude Code (design D2). A shell denylist can always be talked
+ * around, but no agent harness gives its shell a terminal on stdin, so the
+ * terminal test catches every route the guard misses, in every harness.
+ *
+ * Design: design.md C1
+ *
+ * @module
+ */
+export type HumanRule = 'autopilot-approve' | 'transition-override' | 'amend-confirm';
+export interface HumanOnlyCommand {
+    rule: HumanRule;
+    /** How the command is named to whoever is refused. */
+    label: string;
+    /** The positional words after `aidlc` that name the command. */
+    words: string[];
+    /** The flag that makes it need a person, or null when the command always does. */
+    flag: string | null;
+}
+/** The one table. The approval guard embeds it, so both layers refuse the same set. */
+export declare const HUMAN_ONLY: readonly HumanOnlyCommand[];
+/** The longest command or path a log line keeps. */
+export declare const SUBJECT_LIMIT = 500;
+export interface RefusalEntry {
+    at: string;
+    where: 'cli' | 'guard';
+    rule: string;
+    reason: string;
+    subject: string;
+    session?: string;
+}
+/**
+ * Why no person is present, or null when one is. `AIDLC_UNATTENDED` comes first
+ * so the reason names it even at a terminal (AC-4). Only stdin is read: a person
+ * piping the output through `tee` is still a person.
+ */
+export declare function absenceReason(env: NodeJS.ProcessEnv, stdinIsTTY: boolean | undefined): string | null;
+export declare function refusalMessage(cmd: HumanOnlyCommand, why: string): string;
+/** Shared by every worktree, and never committed: it records what happened here. */
+export declare function refusalsPath(projectRoot: string): string;
+/** Append one line. Never throws: a refusal that cannot be logged is still a refusal (AC-15). */
+export declare function logRefusal(projectRoot: string, entry: RefusalEntry): void;
+/**
+ * Null when a person is present. Otherwise logs the refusal and returns the
+ * message, for the caller to print in its own way (`amend --json` wraps it).
+ */
+export declare function requireHuman(rule: HumanRule, opts: {
+    root: string;
+    env?: NodeJS.ProcessEnv;
+    stdinIsTTY?: boolean;
+    subject?: string;
+}): string | null;
+//# sourceMappingURL=human-only.d.ts.map

package/dist/hooks/human-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-only.d.ts","sourceRoot":"","sources":["../../src/hooks/human-only.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,MAAM,MAAM,SAAS,GAAG,mBAAmB,GAAG,qBAAqB,GAAG,eAAe,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kFAAkF;IAClF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,uFAAuF;AACvF,eAAO,MAAM,UAAU,EAAE,SAAS,gBAAgB,EAIjD,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAIpG;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CASzE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACtF,MAAM,GAAG,IAAI,CAaf"}

package/dist/hooks/human-only.js

@@ -0,0 +1,82 @@
+/**
+ * The commands only a person may run, and the check that refuses them to an
+ * agent (agent-cannot-approve-itself/AC-1..AC-6, AC-14, AC-15).
+ *
+ * Each command exists so that a person can say yes: carry a paused item on,
+ * pass the ownership gate, reopen from testing. An agent that runs one approves
+ * its own work, which empties "approved" of meaning.
+ *
+ * This check is the line; the approval guard (`approval-guard.ts`) is the early,
+ * logged layer in Claude Code (design D2). A shell denylist can always be talked
+ * around, but no agent harness gives its shell a terminal on stdin, so the
+ * terminal test catches every route the guard misses, in every harness.
+ *
+ * Design: design.md C1
+ *
+ * @module
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { gitCommonDir } from '../concurrency/common-dir.js';
+/** The one table. The approval guard embeds it, so both layers refuse the same set. */
+export const HUMAN_ONLY = [
+    { rule: 'autopilot-approve', label: 'aidlc autopilot approve', words: ['autopilot', 'approve'], flag: null },
+    { rule: 'transition-override', label: 'aidlc transition --override', words: ['transition'], flag: '--override' },
+    { rule: 'amend-confirm', label: 'aidlc amend --confirm', words: ['amend'], flag: '--confirm' },
+];
+/** The longest command or path a log line keeps. */
+export const SUBJECT_LIMIT = 500;
+/**
+ * Why no person is present, or null when one is. `AIDLC_UNATTENDED` comes first
+ * so the reason names it even at a terminal (AC-4). Only stdin is read: a person
+ * piping the output through `tee` is still a person.
+ */
+export function absenceReason(env, stdinIsTTY) {
+    if (env.AIDLC_UNATTENDED === '1')
+        return 'AIDLC_UNATTENDED=1 says no person is attending this run';
+    if (stdinIsTTY !== true)
+        return 'stdin is not a terminal, so no person is at the keyboard';
+    return null;
+}
+export function refusalMessage(cmd, why) {
+    return `${cmd.label} needs a person: ${why}. Run it yourself in your own terminal.`;
+}
+/** Shared by every worktree, and never committed: it records what happened here. */
+export function refusalsPath(projectRoot) {
+    const common = gitCommonDir(projectRoot);
+    return common === null
+        ? join(projectRoot, '.aidlc', 'refusals.ndjson')
+        : join(common, 'aidlc', 'refusals.ndjson');
+}
+/** Append one line. Never throws: a refusal that cannot be logged is still a refusal (AC-15). */
+export function logRefusal(projectRoot, entry) {
+    try {
+        const path = refusalsPath(projectRoot);
+        mkdirSync(dirname(path), { recursive: true });
+        const line = { ...entry, subject: entry.subject.slice(0, SUBJECT_LIMIT) };
+        appendFileSync(path, `${JSON.stringify(line)}\n`);
+    }
+    catch {
+        // nothing to do: the caller refuses either way
+    }
+}
+/**
+ * Null when a person is present. Otherwise logs the refusal and returns the
+ * message, for the caller to print in its own way (`amend --json` wraps it).
+ */
+export function requireHuman(rule, opts) {
+    const why = absenceReason(opts.env ?? process.env, 'stdinIsTTY' in opts ? opts.stdinIsTTY : process.stdin.isTTY);
+    if (why === null)
+        return null;
+    const cmd = HUMAN_ONLY.find((c) => c.rule === rule);
+    const message = refusalMessage(cmd, why);
+    logRefusal(opts.root, {
+        at: new Date().toISOString(),
+        where: 'cli',
+        rule,
+        reason: why,
+        subject: opts.subject ?? process.argv.slice(2).join(' '),
+    });
+    return message;
+}
+//# sourceMappingURL=human-only.js.map

package/dist/hooks/human-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-only.js","sourceRoot":"","sources":["../../src/hooks/human-only.ts"],"names":[],"mappings":"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"}

package/dist/hooks/install.d.ts

@@ -23,7 +23,7 @@
  * @module
  */
 export type LifecyclePlatform = 'claude-code' | 'codex';
-export type LifecycleHook = 'session-start' | 'guard';
+export type LifecycleHook = 'session-start' | 'guard' | 'approval-guard';
 export declare const LIFECYCLE_PLATFORMS: readonly LifecyclePlatform[];
 export declare const LIFECYCLE_HOOK_MARKER = "#aidlc-lifecycle-hook";
 export declare const GUARD_MATCHER = "Edit|Write|MultiEdit|NotebookEdit";

package/dist/hooks/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/hooks/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,OAAO,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,OAAO,CAAC;AAEtD,eAAO,MAAM,mBAAmB,EAAE,SAAS,iBAAiB,EAA6B,CAAC;AAC1F,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,eAAO,MAAM,aAAa,sCAAsC,CAAC;AAuBjE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,iBAAiC,GAAG,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAM5G;AAkCD,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAErF;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAElE;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAElE;AAgED,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACrD,WAAW,CAUb;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GACzD,WAAW,CAoBb;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,aAAa,GACnB,OAAO,CAOT;AAED,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,EAAqC,MAAM,CAAC;AAEzE,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,QAA0B,CAAC"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/hooks/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AASH,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,OAAO,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,OAAO,GAAG,gBAAgB,CAAC;AAEzE,eAAO,MAAM,mBAAmB,EAAE,SAAS,iBAAiB,EAA6B,CAAC;AAC1F,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,eAAO,MAAM,aAAa,sCAAsC,CAAC;AA2BjE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,iBAAiC,GAAG,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAO5G;AAkCD,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAErF;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAElE;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAElE;AAsFD,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACrD,WAAW,CAmBb;AAYD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GACzD,WAAW,CAoBb;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,aAAa,GACnB,OAAO,CAOT;AAED,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,EAAqC,MAAM,CAAC;AAEzE,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,QAA0B,CAAC"}

package/dist/hooks/install.js

@@ -25,13 +25,18 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { cliEntryPath } from '../cost/hooks/entry.js';
+import { APPROVAL_GUARD_MATCHER, APPROVAL_GUARD_PATH, approvalGuardCommand, renderApprovalGuard } from './approval-guard.js';
 import { shimInvocation, shimProblem, writeShim } from '../cost/hooks/shim.js';
 export const LIFECYCLE_PLATFORMS = ['claude-code', 'codex'];
 export const LIFECYCLE_HOOK_MARKER = '#aidlc-lifecycle-hook';
 export const GUARD_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
 /** A hook needs only to start the CLI and read a few files; ten seconds is generous. */
 const TIMEOUT_SECONDS = 10;
-const EVENT = { 'session-start': 'SessionStart', guard: 'PreToolUse' };
+const EVENT = {
+    'session-start': 'SessionStart',
+    guard: 'PreToolUse',
+    'approval-guard': 'PreToolUse',
+};
 /**
  * The two hook commands for a platform. Both run through the cost-capture shim,
  * which finds an absolute `node` and this project's CLI at run time and never
@@ -43,6 +48,7 @@ export function lifecycleCommands(platform = 'claude-code') {
     return {
         'session-start': `${base} hook session-start ${LIFECYCLE_HOOK_MARKER}`,
         guard: `${base} hook guard ${LIFECYCLE_HOOK_MARKER}`,
+        'approval-guard': approvalGuardCommand(),
     };
 }
 /** The one table mapping a platform to its lifecycle hooks (agent-portability/AC-41). */
@@ -79,10 +85,31 @@ export function installCommand(platform) {
 function isMarked(h) {
     return typeof h.command === 'string' && h.command.endsWith(LIFECYCLE_HOOK_MARKER);
 }
+/**
+ * Which lifecycle hook a marked command is, read from its text. The phase guard
+ * and the approval guard share `PreToolUse`, so identity by marker alone would
+ * have each install replace the other (agent-cannot-approve-itself, design C4).
+ */
+function kindOf(h) {
+    if (!isMarked(h))
+        return null;
+    if (h.command.includes(APPROVAL_GUARD_PATH))
+        return 'approval-guard';
+    if (h.command.includes(' hook guard '))
+        return 'guard';
+    return 'session-start';
+}
+function isKind(which) {
+    return which === null ? isMarked : (h) => kindOf(h) === which;
+}
 function groupFor(which, platform) {
     const hook = { type: 'command', command: lifecycleCommands(platform)[which], timeout: TIMEOUT_SECONDS };
     // No matcher on SessionStart, so it fires on startup, resume, clear and compact.
-    return which === 'guard' ? { matcher: GUARD_MATCHER, hooks: [hook] } : { hooks: [hook] };
+    if (which === 'guard')
+        return { matcher: GUARD_MATCHER, hooks: [hook] };
+    if (which === 'approval-guard')
+        return { matcher: APPROVAL_GUARD_MATCHER, hooks: [hook] };
+    return { hooks: [hook] };
 }
 function load(path) {
     if (!existsSync(path))
@@ -105,12 +132,13 @@ function save(path, raw, file) {
  * Only a group this takes a command from is dropped for being left empty; a
  * user's group is passed through as it was, empty or not.
  */
-function withoutMarked(groups) {
+function withoutMarked(groups, which = null) {
+    const matches = isKind(which);
     let removed = 0;
     const kept = [];
     for (const g of groups ?? []) {
         const hooks = Array.isArray(g.hooks) ? g.hooks : [];
-        const unmarked = hooks.filter((h) => !isMarked(h));
+        const unmarked = hooks.filter((h) => !matches(h));
         removed += hooks.length - unmarked.length;
         if (unmarked.length === hooks.length)
             kept.push(g);
@@ -122,7 +150,7 @@ function withoutMarked(groups) {
 /** Exactly one marked command under the event, in the group shape the installer writes. */
 function isCurrent(groups, which, platform) {
     const expected = groupFor(which, platform);
-    const marked = (groups ?? []).filter((g) => (g.hooks ?? []).some(isMarked));
+    const marked = (groups ?? []).filter((g) => (g.hooks ?? []).some(isKind(which)));
     return marked.length === 1 && JSON.stringify(marked[0]) === JSON.stringify(expected);
 }
 function ensure(file, which, platform) {
@@ -131,7 +159,7 @@ function ensure(file, which, platform) {
     // Left where it is when already current, so a re-install does not even reorder
     // the file (AC-16).
     if (!isCurrent(hooks[event], which, platform)) {
-        hooks[event] = [...withoutMarked(hooks[event]).groups, groupFor(which, platform)];
+        hooks[event] = [...withoutMarked(hooks[event], which).groups, groupFor(which, platform)];
     }
     file.hooks = hooks;
 }
@@ -154,7 +182,26 @@ export function installLifecycleHooks(projectRoot, opts) {
     ensure(file, 'session-start', opts.platform);
     if (opts.guard)
         ensure(file, 'guard', opts.platform);
-    return { written: save(path, raw, file), path };
+    // Not opt-in: an approval only means something when no agent can give it
+    // (agent-cannot-approve-itself/AC-16). Claude Code only; every harness gets the
+    // CLI's own terminal check.
+    let scriptWritten = false;
+    if (opts.platform === 'claude-code') {
+        ensure(file, 'approval-guard', opts.platform);
+        scriptWritten = writeApprovalGuard(projectRoot);
+    }
+    const settingsWritten = save(path, raw, file);
+    return { written: settingsWritten || scriptWritten, path };
+}
+/** Write the approval guard script when its text would change; true when written. */
+function writeApprovalGuard(projectRoot) {
+    const path = join(projectRoot, APPROVAL_GUARD_PATH);
+    const text = renderApprovalGuard();
+    if (existsSync(path) && readFileSync(path, 'utf8') === text)
+        return false;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+    return true;
 }
 /**
  * Remove the lifecycle hooks from one platform's file, or only the guard
@@ -173,7 +220,7 @@ export function removeLifecycleHooks(projectRoot, opts) {
     for (const event of events) {
         if (!(event in file.hooks))
             continue;
-        const result = withoutMarked(file.hooks[event]);
+        const result = withoutMarked(file.hooks[event], opts.guardOnly ? 'guard' : null);
         if (result.removed === 0)
             continue;
         removed += result.removed;
@@ -194,7 +241,7 @@ export function removeLifecycleHooks(projectRoot, opts) {
 export function lifecycleHookInstalled(projectRoot, platform, which) {
     try {
         const { file } = load(hookFilePath(projectRoot, platform));
-        return (file.hooks?.[EVENT[which]] ?? []).some((g) => (g.hooks ?? []).some(isMarked));
+        return (file.hooks?.[EVENT[which]] ?? []).some((g) => (g.hooks ?? []).some(isKind(which)));
     }
     catch {
         return false;