@agentwhy/cli 0.0.0-dev

package/dist/report/watch/subagent-watch.js

@@ -0,0 +1,345 @@
+import { join } from 'node:path';
+import { HOME_PREFIX, HOOK_INPUT } from '../../adapter/claude-code/contract/hooks.js';
+import { SETTINGS_FILES } from '../../adapter/claude-code/contract/settings.js';
+import { watchInvocation } from '../../adapter/claude-code/settings/hook-entries.js';
+import { blockNotice, chatNotice, terminalNotice } from '../../adapter/claude-code/hooks/hook-output.js';
+import { parseJsonObject } from '../../shared/json.js';
+import { parseStopInput } from '../../adapter/claude-code/hooks/stop-input.js';
+import { parseSubagentStopInput } from '../../adapter/claude-code/hooks/subagent-stop-input.js';
+import { withLateMessage } from '../../core/late-message.js';
+import { buildReport } from '../build-report.js';
+import { choosePolicy } from '../choose-policy.js';
+import { alertOf, alerts, DEFAULT_THRESHOLD } from './agent-alert.js';
+import { DEFAULT_CHANNELS, DEFAULT_CLEAN, DEFAULT_LANG, DEFAULT_SAID_AS, langOfLocale, } from './notice-choices.js';
+import { instructionFor, reportCommand } from './render/instruction-words.js';
+import { preferencesFor, readPreferences } from './preferences.js';
+import { NOTICE_TITLE, withTitle } from './render/notice-words.js';
+// Where they live now: both the notice and the preferences that choose it name them, and neither owns the other.
+export { CLEAN_MODES, DEFAULT_CHANNELS, DEFAULT_CLEAN, NOTICE_CHANNELS } from './notice-choices.js';
+/**
+ * The most a hook input is read to. The documented input is a few paths and the agent's last message; a megabyte of
+ * message is already unusual, and past this the input is not held at all.
+ */
+const MAX_INPUT_BYTES = 16 * 1024 * 1024;
+/**
+ * What was last said about the session's own agent, kept under a name no agent has
+ * (`the-agent-nobody-watches.md` R6): `alertOf` reads the whole transcript, so a value read in one turn is still
+ * there in the next, and without this the same line would arrive after every turn for the rest of the session.
+ */
+const OWN_REACH_SAID = 'session:said';
+/**
+ * What the session has had said about it so far, kept under names no agent has, the way `OWN_REACH_SAID` is
+ * (`the-agent-tells-you.md` R6, R7). `take` clears a session's records, so both are written back after every read:
+ * a turn that finds nothing new still has to know what earlier turns found, or a clean line would say "nothing
+ * reached" over a session holding a value.
+ */
+const SESSION_COUNTS = 'session:counts';
+/** That a clean line has been said once already, for the mode that says it once (R4). */
+const CLEAN_SAID = 'session:clean';
+/** That an unreadable preferences file has been said already: once a session, never after every turn (R24). */
+const PREFERENCES_SAID = 'session:preferences';
+/**
+ * The ways into Claude Code that have a person reading, as `CLAUDE_CODE_ENTRYPOINT` names them - measured on the
+ * terminal and on the editor extension (B9e2). `sdk-cli`, which is `claude -p`, is left out on purpose, and so is
+ * any name this version has not seen.
+ */
+const ATTENDED = ['cli', 'claude-vscode'];
+/** The records the display keeps about the session itself. None of them is an agent, and none is ever counted as one. */
+const KEPT_NAMES = [OWN_REACH_SAID, SESSION_COUNTS, CLEAN_SAID, PREFERENCES_SAID];
+/** What the session had said about it before, plus what is being said now. Levels only, never what they were about. */
+function countedWith(before, saying) {
+    return {
+        values: (before?.values ?? 0) + saying.filter((alert) => alert.level === 'value').length,
+        reached: (before?.reached ?? 0) + saying.filter((alert) => alert.level === 'reached').length,
+    };
+}
+/**
+ * `agentwhy watch`: one finished agent, read the way `report` reads a session, and one notice about it
+ * (`specs/2026-09-16-when-an-agent-finishes.md`). Every way it can fail to look is a notice saying so - never an
+ * exception and never silence - because a hook that failed quietly reads exactly like an agent that did nothing.
+ */
+export class SubagentWatch {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    /**
+     * One hook run, whichever event it was. `Stop` says what the turn remembered; anything else is read as the
+     * `SubagentStop` this command began as. The event is read from the input rather than from a flag (R5), because
+     * the first attempt at measuring this put the probe on the wrong event and nothing ran at all.
+     */
+    async run(options) {
+        const text = await this.#dependencies.input.readAll(MAX_INPUT_BYTES);
+        if (text === undefined)
+            return this.announce({ kind: 'not-checked', reason: 'input' }, options.channels ?? DEFAULT_CHANNELS);
+        // Where the session runs decides which project's answers apply, and it is on every input this hook is given.
+        const settled = await this.#settle(options, directoryIn(text));
+        const stop = parseStopInput(text);
+        if (!('unusable' in stop))
+            return this.#sayWhatTheTurnFound(stop.turn, settled);
+        const { notice, agent } = await this.#noticeFor(text, settled);
+        await this.#remember(notice, agent, settled);
+        return this.announce(notice, settled.channels);
+    }
+    /**
+     * One question at a time, in the order R24 sets: the flag if it was written, then this project's answer, then this
+     * person's, then what this tool does when nobody has said anything. A file that cannot be read answers nothing and
+     * is remembered as unusable - the run still happens, on the built-in answers, because a hook that refused to work
+     * over a settings file is a hook that stops watching.
+     */
+    async #settle(options, directory) {
+        const { files, preferencesPath } = this.#dependencies;
+        const read = readPreferences(await textOf(files, preferencesPath));
+        const chosen = read.kind === 'read' ? preferencesFor(read.preferences, directory) : {};
+        return {
+            ...options,
+            on: options.on ?? chosen.on ?? DEFAULT_THRESHOLD,
+            clean: options.clean ?? chosen.clean ?? DEFAULT_CLEAN,
+            channels: options.channels ?? chosen.notify ?? DEFAULT_CHANNELS,
+            say: options.say ?? chosen.say ?? DEFAULT_SAID_AS,
+            // Chosen on the page or with `notify --lang`, then the system's, then English: never a flag, since no hook
+            // command line has one.
+            lang: chosen.lang ?? langOfLocale(this.#dependencies.locale) ?? DEFAULT_LANG,
+            preferencesUnusable: read.kind === 'unusable',
+        };
+    }
+    async announce(notice, channels) {
+        const words = this.#dependencies.renderer.render(notice);
+        // The system notification is shown by this process; whether it was accepted changes nothing a hook could act on.
+        if (words !== '' && channels.includes('os'))
+            await this.#dependencies.notifier.notify(NOTICE_TITLE, words);
+        return { notice, output: channels.includes('terminal') ? terminalNotice(NOTICE_TITLE, words) : '' };
+    }
+    /**
+     * At `Stop`: what the turn's delegated agents left behind, and what the session's own agent reached itself - the
+     * one agent with no `SubagentStop` of its own (`the-agent-nobody-watches.md` R2). Said once, and then not again
+     * unless it changes.
+     */
+    async #sayWhatTheTurnFound(turn, options) {
+        // Taking clears the store, so a run that cannot show the words must not take them.
+        if (!options.channels.includes('chat'))
+            return { notice: { kind: 'quiet' }, output: '' };
+        const { store } = this.#dependencies;
+        const remembered = await store.take(turn.sessionId);
+        const kept = new Map(remembered.map((alert) => [alert.agentId, alert]));
+        const said = kept.get(OWN_REACH_SAID);
+        const delegated = remembered.filter((alert) => !KEPT_NAMES.includes(alert.agentId));
+        const own = await this.#ownReach(turn, options);
+        const reach = own.kind === 'alert' ? own.alert : undefined;
+        if (reach !== undefined)
+            await store.remember(turn.sessionId, { ...reach, agentId: OWN_REACH_SAID });
+        // Written back because `take` cleared them. A turn nobody looked at changes nothing that was said: without this the
+        // turn after it took the same finding for a new one and blocked a second time (R10). An unusable preferences file
+        // is said once a session (R24), whatever this turn says. A clean line said once is let go on a turn with a finding,
+        // on purpose: the next quiet turn then says what the session holds (R4, R6).
+        const unchanged = own.kind === 'not-looked' ? [said, kept.get(CLEAN_SAID), kept.get(PREFERENCES_SAID)] : [kept.get(PREFERENCES_SAID)];
+        for (const record of unchanged)
+            if (record !== undefined)
+                await store.remember(turn.sessionId, record);
+        const fresh = reach !== undefined && reach.words !== said?.words ? [reach] : [];
+        const saying = [...fresh, ...delegated];
+        // What this session has had said about it, this turn included. Written back because `take` cleared it.
+        const counts = countedWith(kept.get(SESSION_COUNTS)?.counts, saying);
+        if (counts.values > 0 || counts.reached > 0) {
+            await store.remember(turn.sessionId, { agentId: SESSION_COUNTS, level: 'counts', words: '', counts });
+        }
+        /*
+         * A turn this run could not look at is not a quiet turn, and must never be said as one: every way of failing to
+         * look is silence on this event (`the-agent-nobody-watches` R9), and a clean line over a reading that did not
+         * happen is the one sentence this tool must never write.
+         */
+        const notice = saying.length > 0
+            ? { kind: 'turn', remembered: saying }
+            : own.kind === 'not-looked'
+                ? { kind: 'quiet' }
+                : (await this.#preferencesNotice(turn, options, kept.has(PREFERENCES_SAID))) ??
+                    (await this.#cleanNotice(turn, options, counts, kept.has(CLEAN_SAID)));
+        // The other two channels carry a title of their own; a line in the conversation has none, so it says who speaks.
+        const words = this.#dependencies.renderer.render(notice);
+        const files = own.kind === 'alert' ? own.files : [];
+        if (this.#agentSpeaks(turn, options, fresh)) {
+            const command = reportCommand(turn.sessionId, await this.#invocation());
+            return { notice, output: blockNotice(instructionFor(files, command), withTitle(words)) };
+        }
+        return { notice, output: chatNotice(withTitle(words)) };
+    }
+    /**
+     * Whether this turn's finding is said by the session's own agent rather than as a line (R9-R14). Every condition
+     * is a measurement or a reason written down beside it, and all of them must hold:
+     *
+     * - **a value is being said now, for the first time, by the session's own agent** - the only level the agent
+     *   speaks for (R8, R12b), and only where it is the one who found it. `fresh` holds the own-reach alert alone,
+     *   never a delegated agent's: the instruction tells the agent "you read this file in this conversation" (R12,
+     *   R12b), which is false, and checkable as false, of a file only a delegated subagent reached. A delegated
+     *   agent's finding still reaches the person, as the line `saying` renders - just never as a claim this agent is
+     *   asked to make about its own context. The finding was recorded as said before this is asked, because `Stop`
+     *   fires twice for one turn (B8a), so the same finding never blocks twice (R10);
+     * - **the person asked for it**, or asked for nothing and has the default (R8);
+     * - **this is not already a continuation a block caused** - `stop_hook_active` read `true` there (B9c, R13);
+     * - **a person is reading** - the entry point is one measured attended (B9e2, R14). One this version does not
+     *   know, or none at all, gets the line: a scripted run continued by a block prints an answer it never asked for.
+     */
+    #agentSpeaks(turn, options, fresh) {
+        const { entryPoint } = this.#dependencies;
+        return fresh.some((alert) => alert.level === 'value') &&
+            options.say === 'agent' &&
+            !turn.active &&
+            entryPoint !== undefined && ATTENDED.includes(entryPoint);
+    }
+    /**
+     * How the agent is to run agentwhy: the way the `Stop` hook running now does, read from the project's settings -
+     * the local file first, the one `init` writes. Found by a measurement (B9d): the offer named `agentwhy`, which was on
+     * no path in that project, and the command failed with exit 126. Where no settings say, or say it in anything but
+     * plain words, the way this hook's own process was started (`a-hook-runs-what-you-ran.md` J6).
+     */
+    async #invocation() {
+        const { files, projectDirectory, invocation } = this.#dependencies;
+        if (projectDirectory === undefined)
+            return invocation.find();
+        for (const name of [SETTINGS_FILES.local, SETTINGS_FILES.shared]) {
+            const settings = parseJsonObject((await textOf(files, join(projectDirectory, SETTINGS_FILES.directory, name))) ?? '');
+            const running = settings === undefined ? undefined : watchInvocation(settings);
+            if (running !== undefined)
+                return running;
+        }
+        return invocation.find();
+    }
+    /**
+     * That the person's choices could not be read (R24): said once a session, on a turn with nothing else to say, and
+     * never as a block. Without it a broken file reads exactly like choices that were honoured - the person who set
+     * `off` and still hears a line, or set `every-turn` and hears nothing, would have no way to know why.
+     */
+    async #preferencesNotice(turn, options, said) {
+        if (!options.preferencesUnusable)
+            return undefined;
+        // Written back whatever happens next, since `take` cleared it with everything else.
+        await this.#dependencies.store.remember(turn.sessionId, { agentId: PREFERENCES_SAID, level: 'preferences', words: '' });
+        return said ? undefined : { kind: 'preferences-unusable' };
+    }
+    /**
+     * A turn that found nothing, where that is worth saying (R4-R6). It is the one notice that reports no finding, so
+     * it is held to two things: it never speaks where the person asked for silence, and it never says a session is
+     * clean when an earlier turn of it was not - what the turn found and what the session holds are said apart.
+     */
+    async #cleanNotice(turn, options, counts, cleanSaid) {
+        const mode = options.clean;
+        if (mode === 'off')
+            return { kind: 'quiet' };
+        // Said once means once: the marker is written back, since `take` cleared it with everything else.
+        if (mode === 'once' && cleanSaid) {
+            await this.#dependencies.store.remember(turn.sessionId, { agentId: CLEAN_SAID, level: 'clean', words: '' });
+            return { kind: 'quiet' };
+        }
+        if (mode === 'once')
+            await this.#dependencies.store.remember(turn.sessionId, { agentId: CLEAN_SAID, level: 'clean', words: '' });
+        return { kind: 'clean', first: !cleanSaid && mode === 'once', counts, lang: options.lang };
+    }
+    /**
+     * What the session's own agent reached, read from the primary transcript the input names and nothing else (R3).
+     * Every way of failing to look is silence here, not a notice: at the end of every turn, a line saying it could
+     * not look would arrive for the rest of the session, and `check` finds the same thing without a hook.
+     */
+    async #ownReach(turn, options) {
+        const { source, files, createRedactor, home, renderer } = this.#dependencies;
+        if (turn.transcriptPath === undefined)
+            return { kind: 'not-looked' };
+        const policy = await choosePolicy(options, files, this.#dependencies.tell);
+        if ('errors' in policy)
+            return { kind: 'not-looked' };
+        const read = await source.read(expandHome(turn.transcriptPath, home));
+        if (read.gaps.some((gap) => gap.kind === 'session-missing'))
+            return { kind: 'not-looked' };
+        // B8b: the turn's last words are on the input, and B4c measured the same words missing from disk at hook time.
+        const model = turn.lastMessage === undefined ? read : withLateMessage(read, read.sessionId, turn.lastMessage);
+        const report = buildReport(model, policy.policy, createRedactor(model.projectRoot), { share: false, projectRoot: model.projectRoot });
+        const alert = alertOf(report, report.graph.main.index);
+        if (alert === undefined || !alerts(alert.level, options.on))
+            return { kind: 'nothing' };
+        return {
+            kind: 'alert',
+            alert: { agentId: OWN_REACH_SAID, level: alert.level, words: renderer.render({ kind: 'alert', alert }) },
+            files: readFrom(report, report.graph.main.index),
+        };
+    }
+    /**
+     * What `chat` does at `SubagentStop`: keep the words for the end of the turn, because this event discards a
+     * `systemMessage` (B4d, B4f) and the agent's last text is not on disk for anyone to read later (B4c).
+     */
+    async #remember(notice, agent, options) {
+        if (!options.channels.includes('chat'))
+            return;
+        if (notice.kind !== 'alert' && notice.kind !== 'not-checked')
+            return;
+        // Without a session there is no conversation to speak in; the immediate channels said it if they were asked to.
+        if (agent?.sessionId === undefined)
+            return;
+        const words = this.#dependencies.renderer.render(notice);
+        if (words === '')
+            return;
+        // A reason it could not look is remembered under the reason, so a hook that fires again says it once (R8).
+        const which = notice.kind === 'alert'
+            ? { agentId: agent.agentId, level: notice.alert.level }
+            : { agentId: `not-checked:${notice.reason}`, level: 'not-checked' };
+        await this.#dependencies.store.remember(agent.sessionId, { ...which, words });
+    }
+    async #noticeFor(text, options) {
+        const { source, files, createRedactor, home } = this.#dependencies;
+        const parsed = parseSubagentStopInput(text);
+        if ('unusable' in parsed)
+            return { notice: { kind: 'not-checked', reason: 'input' } };
+        const { agent } = parsed;
+        const policy = await choosePolicy(options, files, this.#dependencies.tell);
+        if ('errors' in policy)
+            return { notice: { kind: 'not-checked', reason: 'policy' }, agent };
+        const read = await source.read(expandHome(agent.transcriptPath, home));
+        if (read.gaps.some((gap) => gap.kind === 'session-missing'))
+            return { notice: { kind: 'not-checked', reason: 'session' }, agent };
+        // R9: the last words the hook was handed, which B4c measured as not yet on disk on 4 of 4 agents.
+        const model = agent.lastMessage === undefined ? read : withLateMessage(read, agent.agentId, agent.lastMessage);
+        // R3: by the id the hook names, and by nothing else.
+        const agentIndex = model.agents.findIndex((candidate) => candidate.id === agent.agentId);
+        if (agentIndex < 0 || model.agents[agentIndex]?.id === model.sessionId) {
+            return { notice: { kind: 'not-checked', reason: 'agent-not-found' }, agent };
+        }
+        const report = buildReport(model, policy.policy, createRedactor(model.projectRoot), { share: false, projectRoot: model.projectRoot });
+        const alert = alertOf(report, agentIndex);
+        if (alert === undefined)
+            return { notice: { kind: 'not-checked', reason: 'agent-not-found' }, agent };
+        return { notice: alerts(alert.level, options.on) ? { kind: 'alert', alert } : { kind: 'quiet' }, agent };
+    }
+}
+/**
+ * The protected files a value in this session was **read from** by one agent - not every file the session touched,
+ * and not every file another agent in the same session touched. The instruction tells the agent "you read these",
+ * and a session checks that against its own context and argues with a claim that does not hold (R12b): a file only
+ * a delegated subagent reached is a file this agent never read, naming it is the same false sentence as naming a
+ * file the session only wrote a value into. Found by the first test of this, on a session that read `.env` and
+ * wrote into `.env.production`.
+ */
+function readFrom(report, agentIndex) {
+    return [...new Set([
+            ...report.uses.filter((use) => use.agentIndex === agentIndex).flatMap((use) => use.files),
+            ...report.returns
+                .filter((statement) => statement.agentIndex === agentIndex)
+                .flatMap((statement) => [...(statement.strength === 'value' ? statement.paths : []), ...statement.writtenFrom]),
+        ])];
+}
+/** The working directory the hook input names, whichever event it was: what decides which project's answers apply. */
+function directoryIn(text) {
+    const input = parseJsonObject(text);
+    const directory = input?.[HOOK_INPUT.fields.workingDirectory];
+    return typeof directory === 'string' && directory !== '' ? directory : undefined;
+}
+/** A file that is not there is not a file that failed: both are `undefined`, and `readPreferences` tells them apart. */
+async function textOf(files, path) {
+    try {
+        return await files.readText(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A path the hooks reference writes with a leading `~/` in its examples: expanded, never read as relative. */
+function expandHome(path, home) {
+    return path.startsWith(HOME_PREFIX) ? join(home, path.slice(HOME_PREFIX.length)) : path;
+}

package/dist/report/watch/watch-notice.js

@@ -0,0 +1 @@
+export {};

package/dist/setup/behind.js

@@ -0,0 +1,18 @@
+import { pinnedVersions } from '../adapter/claude-code/settings/hook-entries.js';
+import { isOlder, plainVersion } from '../shared/plain-version.js';
+/**
+ * U2 over the project's two settings files, as parsed: behind where a hook runs the pinned published way at a release
+ * older than `serving`. A serving version that is not a release, and hooks in any other form, are never behind.
+ */
+export function behind(files, serving) {
+    if (serving === undefined || plainVersion(serving) === undefined)
+        return undefined;
+    const older = (settings) => pinnedVersions(settings ?? {}).filter((version) => isOlder(version, serving));
+    const local = older(files.local);
+    const shared = older(files.shared);
+    const [first, ...rest] = [...local, ...shared];
+    if (first === undefined)
+        return undefined;
+    const from = rest.reduce((lowest, version) => (isOlder(version, lowest) ? version : lowest), first);
+    return { from, to: serving, shared: shared.includes(from) };
+}

package/dist/setup/codex-mirror.js

@@ -0,0 +1,171 @@
+import { join } from 'node:path';
+import { SETTINGS_FILES } from '../adapter/claude-code/contract/settings.js';
+import { installedHooks, rulesReadByHooks, runningInvocation } from '../adapter/claude-code/settings/hook-entries.js';
+import { PROJECT_HOOKS } from '../adapter/codex/contract/hooks.js';
+import { codexRefuseCommand, codexRefuseIn, codexStopCommand, codexStopIn, withCodexRefuse, withoutCodexRefuse } from '../adapter/codex/settings/codex-hooks.js';
+import { FileAccessError } from '../ports/file-access-error.js';
+import { parseJsonObject } from '../shared/json.js';
+/** Where Codex's hook file is, as a person reads it. */
+const WHERE = `${PROJECT_HOOKS.directory}/${PROJECT_HOOKS.file}`;
+/** CK8: what holds until a person approves the hook in Codex, measured (CKB5) - said wherever the hook is written. */
+const UNTIL_APPROVED = 'Codex runs a new or changed hook only after you approve it in Codex: open Codex in this project and approve agentwhy\'s hook when it asks. Until then Codex skips it without a word, and does not block anything.';
+/**
+ * `codex-blocks-too` CK5-CK9: after the setup it wraps has written Claude Code's settings - or found nothing to change -
+ * Codex's hook file is made to match them. agentwhy's Codex hook runs `refuse` with the invocation and the rules Claude
+ * Code's `refuse` has, where either settings file runs `refuse`, and is not there where neither does. Only in a project
+ * that uses Codex (CK6); with its own part of the plan and the same consent (CK7); and never approved on anyone's
+ * behalf (CK8).
+ */
+export class CodexMirror {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async run(options) {
+        // `init --codex` with nothing else named: Codex's hook alone, to match what Claude Code's settings already run.
+        if (options.codex === true && onlyCodex(options))
+            return (await this.#mirror(options)) ?? { outcome: 'unchanged', output: nothingFor(await this.#running()) };
+        const result = await this.#dependencies.setup.run(options);
+        if (result.outcome !== 'written' && result.outcome !== 'unchanged')
+            return result;
+        const codex = await this.#mirror(options);
+        if (codex === undefined)
+            return result;
+        const outcome = result.outcome === 'unchanged' && codex.outcome === 'written' ? 'written' : result.outcome;
+        return { outcome, output: `${result.output}${result.output.endsWith('\n') || result.output === '' ? '' : '\n'}\n${codex.output}` };
+    }
+    /** The change to Codex's hook file, written with consent; `undefined` where there is none to make. */
+    async #mirror(options) {
+        const running = await this.#running();
+        const directory = join(this.#dependencies.workingDirectory, PROJECT_HOOKS.directory);
+        const path = join(directory, PROJECT_HOOKS.file);
+        const read = await this.#readJson(path);
+        const current = read.kind === 'object' ? codexRefuseIn(read.file) : undefined;
+        const currentStop = read.kind === 'object' ? codexStopIn(read.file) : undefined;
+        if (running.kind === 'elsewhere') {
+            return current === undefined && !(await this.#usesCodex(options, read)) ? undefined : { outcome: 'refused', output: `Codex: ${ELSEWHERE}\n` };
+        }
+        const invoke = running.kind === 'none' ? undefined : options.invoke ?? running.invoke ?? (await this.#dependencies.invocation.find());
+        const wanted = invoke === undefined ? undefined : codexRefuseCommand(invoke, running.kind === 'refuse' ? running.settings : undefined);
+        const stop = invoke === undefined ? undefined : codexStopCommand(invoke);
+        if (wanted === current && stop === currentStop)
+            return undefined;
+        if (wanted !== undefined && !(await this.#usesCodex(options, read)))
+            return undefined;
+        if (read.kind === 'broken' || read.kind === 'unreadable') {
+            return {
+                outcome: 'refused',
+                output: `Codex: ${WHERE} ${read.kind === 'broken' ? 'is not a JSON object' : 'could not be read'}, so agentwhy's hook was not ${wanted === undefined ? 'taken out of it' : 'written to it'}.\n`,
+            };
+        }
+        const before = read.kind === 'object' ? read.file : {};
+        const next = wanted === undefined || stop === undefined ? withoutCodexRefuse(before).file : withCodexRefuse(before, wanted, stop);
+        const plan = [
+            `And in Codex, agentwhy will change ${WHERE}:`,
+            '',
+            ...(wanted === undefined
+                ? ['  Stop running', '    agentwhy refuse and its Codex conversation message']
+                : ['  Run automatically', `    ${'before a shell command'.padEnd(24)}${wanted}`, `    ${'when a reply ends'.padEnd(24)}${stop}`]),
+            '',
+            ...(wanted === undefined ? [] : [`  ${UNTIL_APPROVED}`, '']),
+            '  Everything else in the file stays. It is rewritten as two-space JSON.',
+        ];
+        const consent = await this.#consent(options, plan);
+        if (typeof consent !== 'string')
+            return consent;
+        const said = consent === 'asked' ? '' : `${plan.join('\n')}\n\n`;
+        try {
+            await this.#dependencies.files.ensureDirectory(directory);
+            await this.#dependencies.files.writeText(path, `${JSON.stringify(next, null, 2)}\n`);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return { outcome: 'unwritable', output: `${said}Codex: ${WHERE} could not be written, so Codex does not block anything yet.\n` };
+        }
+        // CK8: said once. Where the plan was printed above - `--yes`, a page - it already said what Codex needs.
+        const until = said === '' ? ` ${UNTIL_APPROVED}` : '';
+        return {
+            outcome: 'written',
+            output: `${said}${wanted === undefined
+                ? `Codex: agentwhy's hook is out of ${WHERE}.\n`
+                : current === undefined
+                    ? `Codex: agentwhy's hook is in ${WHERE}. It blocks the same files there, once approved.${until}\n`
+                    : `Codex: agentwhy's hook in ${WHERE} changed, so Codex asks you to approve it again.${until}\n`}`,
+        };
+    }
+    /**
+     * How Claude Code's `refuse` runs here, read from the files as they are after the setup: the local file first, as
+     * `init` reads them. Its rules become Codex's (CK2), as a path in the project (CK3).
+     */
+    async #running() {
+        const directory = join(this.#dependencies.workingDirectory, SETTINGS_FILES.directory);
+        for (const file of [SETTINGS_FILES.local, SETTINGS_FILES.shared]) {
+            const read = await this.#readJson(join(directory, file));
+            if (read.kind !== 'object' || !installedHooks(read.file).has('refuse'))
+                continue;
+            const rules = rulesReadByHooks(read.file).get('refuse') ?? 'default';
+            const invoke = runningInvocation(read.file);
+            if (rules === 'policy' || rules === 'other')
+                return { kind: 'elsewhere' };
+            return {
+                kind: 'refuse',
+                ...(invoke === undefined ? {} : { invoke }),
+                ...(rules === 'default' ? {} : { settings: `${SETTINGS_FILES.directory}/${SETTINGS_FILES[rules]}` }),
+            };
+        }
+        return { kind: 'none' };
+    }
+    /** CK6: a Codex conversation listed for the project, a `.codex` folder in it, or `init --codex`. */
+    async #usesCodex(options, read) {
+        if (options.codex === true || read.kind !== 'absent')
+            return true;
+        try {
+            if ((await this.#dependencies.files.kindOf(join(this.#dependencies.workingDirectory, PROJECT_HOOKS.directory))) === 'directory')
+                return true;
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+        }
+        return this.#dependencies.codexConversations();
+    }
+    /** R7, as `ProjectSetup` asks it: `--yes`, a person at a terminal, or the plan printed and nothing written. */
+    async #consent(options, plan) {
+        if (options.yes)
+            return 'given';
+        if (!this.#dependencies.interactive) {
+            return { outcome: 'not-confirmed', output: `${plan.join('\n')}\n\nNothing was written for Codex. To write it: the same command with --yes\n` };
+        }
+        const chosen = await this.#dependencies.chooser.choose(`${plan.join('\n')}\n\nWrite it?`, [
+            { label: 'Yes', detail: `write ${WHERE}` },
+            { label: 'No', detail: 'leave Codex as it is' },
+        ]);
+        return chosen === 0 ? 'asked' : { outcome: 'declined', output: `Nothing was written for Codex.\n` };
+    }
+    async #readJson(path) {
+        let text;
+        try {
+            text = await this.#dependencies.files.readText(path);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return { kind: error.failure === 'not-found' ? 'absent' : 'unreadable' };
+        }
+        const file = parseJsonObject(text);
+        return file === undefined ? { kind: 'broken' } : { kind: 'object', file };
+    }
+}
+/** CK2: rules Codex's hook cannot be pointed at from the project - a policy file, or a settings file of another place. */
+const ELSEWHERE = "agentwhy's hook was not written: refuse here reads a policy or a settings file outside the project's two, which a hook in the project cannot be pointed at. Run agentwhy init --refuse to point it at this project's rules.";
+/** `init --codex` and nothing else: no hook named, nothing to protect or take out, no update. */
+function onlyCodex(options) {
+    return options.hooks === undefined && options.protect.length === 0 && !options.remove && (options.unprotect ?? []).length === 0 && options.update !== true;
+}
+/** What `init --codex` says where Codex's hook already matches, or there is nothing for it to follow. */
+function nothingFor(running) {
+    return running.kind === 'none'
+        ? "Codex: nothing to write. agentwhy blocks Codex with the same hook it blocks Claude Code with, and refuse doesn't run here yet: agentwhy init --refuse --codex\n"
+        : `Codex: ${WHERE} already runs agentwhy's hook. ${UNTIL_APPROVED}\n`;
+}

package/dist/setup/not-a-project.js

@@ -0,0 +1,19 @@
+import { parse, relative, resolve } from 'node:path';
+/**
+ * Why a working directory is not a project, or `undefined` where it may be one (`.ai/specs/2026-09-27-which-project.md`
+ * V6). The home directory is where a new terminal starts, and its `.claude/settings.json` is Claude Code's settings for
+ * every project; a root is nobody's project. Compared as resolved paths, and through `relative`, which compares a Windows
+ * path without regard to case, as its file system does. An empty home names no directory, so it matches none.
+ *
+ * `realHome` is the same directory with every link followed. Found by a review: the working directory a shell gives is
+ * the physical path, while `HOME` may reach it through a link - `/home` a link to `/data/home` - so the two named one
+ * directory and were compared as two, and the home directory was set up as a project.
+ */
+export function notAProject(directory, home, realHome = home) {
+    const resolved = resolve(directory);
+    if ([home, realHome].some((one) => one !== '' && relative(resolve(one), resolved) === ''))
+        return 'home';
+    if (parse(resolved).root === resolved)
+        return 'root';
+    return undefined;
+}