@agentwhy/cli 0.1.0 → 0.2.1

package/dist/adapter/codex/settings/hook-approval.js

@@ -0,0 +1,374 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from 'node:crypto';
+import {} from '../../../shared/json.js';
+import { HOOK_HASH, USER_HOOKS } from '../contract/hooks.js';
+/**
+ * The entry's hash as Codex computes it (`2026-10-02-codex-approves-its-own-hook.md` AOB1): compact JSON, keys sorted at
+ * every depth, SHA-256. `undefined` where the entry holds something the recipe was not measured over - never a guess
+ * that Codex would agree (AO2).
+ */
+export function entryHash(placed) {
+    const { entry } = placed;
+    if (entry.type !== 'command' || typeof entry.command !== 'string')
+        return undefined;
+    if (HOOK_HASH.unmeasured.some((field) => field in entry))
+        return undefined;
+    const timeout = entry[HOOK_HASH.fields.timeout];
+    const asynchronous = entry[HOOK_HASH.fields.async];
+    const message = entry[HOOK_HASH.fields.statusMessage];
+    if (timeout !== undefined && (typeof timeout !== 'number' || !Number.isInteger(timeout)))
+        return undefined;
+    if (asynchronous !== undefined && typeof asynchronous !== 'boolean')
+        return undefined;
+    if (message !== undefined && typeof message !== 'string')
+        return undefined;
+    const handler = {
+        type: 'command',
+        command: entry.command,
+        [HOOK_HASH.fields.timeout]: Math.max(1, typeof timeout === 'number' ? timeout : HOOK_HASH.defaultTimeout),
+        [HOOK_HASH.fields.async]: asynchronous === true,
+        ...(message === undefined ? {} : { [HOOK_HASH.fields.statusMessage]: message }),
+    };
+    const identity = { event_name: HOOK_HASH.eventKeys[placed.event], hooks: [handler] };
+    // A Stop group's matcher is dropped before hashing; PreToolUse keeps its own (AOB1, `matcher_pattern_for_event`).
+    if (placed.event === 'PreToolUse' && placed.matcher !== undefined)
+        identity.matcher = placed.matcher;
+    return `${HOOK_HASH.prefix}${createHash('sha256').update(JSON.stringify(sorted(identity))).digest('hex')}`;
+}
+/** The key Codex files an approval under: the hooks file's absolute path, the event in snake case, the two indices. */
+export function approvalKey(hooksPath, placed) {
+    return `${hooksPath}:${HOOK_HASH.eventKeys[placed.event]}:${placed.group}:${placed.handler}`;
+}
+/** The approval filed under `key` in the one form this reads, or `undefined` where there is none. */
+export function approvalOf(toml, key) {
+    const table = scan(toml).tables.find((candidate) => candidate.key === key);
+    return table === undefined ? undefined : { ...(table.hash === undefined ? {} : { hash: table.hash }), disabled: table.disabled };
+}
+/**
+ * The config with agentwhy's own approvals in place (AO2, AO3): each wanted key's table holds the wanted hash - its
+ * `trusted_hash` line replaced, or added to the table, or a table appended at the end - and a stale table is removed:
+ * one under the same hooks file, at a key no longer wanted, holding one of the wanted hashes, which is agentwhy's own
+ * approval left behind when its entries' positions shifted. A person's `enabled = false` on such a table moves with it
+ * to the new key of the same event. Every other line stays as it was. `unsafe` where agentwhy's key, or `hooks`
+ * itself, is written in a form a line edit cannot extend without making the file invalid (AO11) - its own table
+ * holding a `trusted_hash`, or an `enabled` the carried choice would replace, in a form this does not read, included:
+ * a second line of the same key is invalid TOML, and Codex would not start on it.
+ */
+export function withOwnApprovals(toml, hooksPath, wanted) {
+    const keys = new Set(wanted.map((approval) => approval.key));
+    const hashes = new Set(wanted.map((approval) => approval.hash));
+    const scanned = scan(toml);
+    const stale = scanned.tables.filter((table) => table.key.startsWith(`${hooksPath}:`) && !keys.has(table.key) && table.hash !== undefined && hashes.has(table.hash));
+    const unsafe = unsafeFor(scanned, [...keys, ...stale.map((table) => table.key)]);
+    if (unsafe !== undefined)
+        return { kind: 'unsafe', reason: unsafe };
+    // A disabled stale table hands its choice to the wanted key of the same event.
+    const carried = new Set();
+    for (const table of stale) {
+        if (!table.disabled)
+            continue;
+        const event = eventOf(table.key, hooksPath);
+        const target = wanted.find((approval) => eventOf(approval.key, hooksPath) === event)?.key;
+        if (target !== undefined)
+            carried.add(target);
+    }
+    // A key written in a form the line regexes do not read is not absent: adding the line beside it duplicates the key.
+    for (const approval of wanted) {
+        const table = scanned.tables.find((candidate) => candidate.key === approval.key);
+        if (table === undefined)
+            continue;
+        if (table.otherHash)
+            return { kind: 'unsafe', reason: WRITTEN_OTHERWISE };
+        if (carried.has(approval.key) && !table.disabled && table.enabled)
+            return { kind: 'unsafe', reason: WRITTEN_OTHERWISE };
+    }
+    const lines = [...scanned.lines];
+    const removed = new Set();
+    for (const table of stale)
+        for (const at of rangeOf(scanned, table))
+            removed.add(at);
+    const inserted = new Map();
+    const appended = [];
+    for (const approval of wanted) {
+        const table = scanned.tables.find((candidate) => candidate.key === approval.key);
+        const hashLine = `${USER_HOOKS.trustedHash} = "${approval.hash}"`;
+        if (table === undefined) {
+            appended.push([headerFor(approval.key), OWN_COMMENT, ...(carried.has(approval.key) ? [`${USER_HOOKS.enabled} = false`] : []), hashLine].join('\n'));
+            continue;
+        }
+        if (table.hashLine !== undefined)
+            lines[table.hashLine] = hashLine;
+        else
+            inserted.set(table.start, [...(inserted.get(table.start) ?? []), hashLine]);
+        if (carried.has(approval.key) && !table.disabled)
+            inserted.set(table.start, [...(inserted.get(table.start) ?? []), `${USER_HOOKS.enabled} = false`]);
+    }
+    const out = [];
+    lines.forEach((line, at) => {
+        if (removed.has(at))
+            return;
+        out.push(line);
+        for (const extra of inserted.get(at) ?? [])
+            out.push(extra);
+    });
+    let text = out.join('\n');
+    if (appended.length > 0) {
+        const base = text === '' ? '' : text.endsWith('\n') ? text : `${text}\n`;
+        text = `${base}${base === '' ? '' : '\n'}${appended.join('\n\n')}\n`;
+    }
+    return { kind: 'edited', text };
+}
+/**
+ * The config without agentwhy's approvals (AO7): under the given hooks file, every table at one of `keys` or holding
+ * one of `hashes` goes whole - an `enabled = false` in it included, since it named agentwhy's entry and would otherwise
+ * apply to whatever lands at that position next. Every other line stays as it was.
+ */
+export function withoutOwnApprovals(toml, hooksPath, keys, hashes) {
+    const scanned = scan(toml);
+    const ours = scanned.tables.filter((table) => table.key.startsWith(`${hooksPath}:`) && (keys.has(table.key) || (table.hash !== undefined && hashes.has(table.hash))));
+    const unsafe = unsafeFor(scanned, [...keys, ...ours.map((table) => table.key)]);
+    if (unsafe !== undefined)
+        return { kind: 'unsafe', reason: unsafe };
+    const removed = new Set();
+    for (const table of ours)
+        for (const at of rangeOf(scanned, table))
+            removed.add(at);
+    return { kind: 'edited', text: scanned.lines.filter((_, at) => !removed.has(at)).join('\n') };
+}
+/**
+ * The lines a table's removal takes: its header through its last non-blank line - the blank lines after it stay, as
+ * the separator before whatever follows, or the file's last newline - and the blank line before it where agentwhy wrote
+ * that one with it.
+ */
+function rangeOf(scanned, table) {
+    let last = table.end - 1;
+    while (last > table.start && (scanned.lines[last] ?? '').trim() === '')
+        last -= 1;
+    const range = [];
+    for (let at = table.start; at <= last; at += 1)
+        range.push(at);
+    if (table.start > 0 && scanned.lines[table.start - 1] === '' && scanned.lines[table.start + 1] === OWN_COMMENT)
+        range.push(table.start - 1);
+    return range;
+}
+/**
+ * AO16: whether `config.toml` defines hooks of its own - a `[hooks.<Event>]` or `[[hooks.<Event>]]` table, a key of
+ * `[hooks]` other than `state`, or `hooks` written inline or dotted at the root with anything but `state`. Codex would
+ * then load hooks from both it and a `hooks.json` agentwhy created, and warn about it in every session.
+ */
+export function tomlDefinesHooks(toml) {
+    const scanned = scan(toml);
+    let context = 'root';
+    for (let at = 0; at < scanned.lines.length; at += 1) {
+        if (scanned.opaque[at])
+            continue;
+        const line = scanned.lines[at] ?? '';
+        if (HEADER.test(line)) {
+            const event = HOOKS_SUBTABLE.exec(line)?.[2];
+            if (event !== undefined && event !== 'state')
+                return true;
+            context = HOOKS_TABLE.test(line) ? 'hooks' : 'other';
+            continue;
+        }
+        if (context === 'root' && /^\s*hooks\s*=/.test(line))
+            return true;
+        const dotted = /^\s*hooks\s*\.\s*("?)(\w+)\1/.exec(line)?.[2];
+        if (context === 'root' && dotted !== undefined && dotted !== 'state')
+            return true;
+        const key = /^\s*("?)(\w+)\1\s*[=.]/.exec(line)?.[2];
+        if (context === 'hooks' && key !== undefined && key !== 'state')
+            return true;
+    }
+    return false;
+}
+const HOOKS_SUBTABLE = /^\s*\[\[?\s*hooks\s*\.\s*("?)(\w+)\1/;
+/** Why a line edit is refused where agentwhy's own approval is written in a form this does not read (AO11). */
+const WRITTEN_OTHERWISE = 'agentwhy\'s approval is written there in a form agentwhy does not edit';
+/** The comment agentwhy writes under its own header, so a person reading the file knows what it is and how to undo it. */
+const OWN_COMMENT = '# agentwhy approved its own check here; `agentwhy init --remove --codex` takes it out.';
+const HEADER = /^\s*\[/;
+const STATE_HEADER = /^\s*\[\s*hooks\s*\.\s*state\s*\.\s*"((?:[^"\\]|\\.)*)"\s*\]\s*(?:#.*)?$/;
+const HOOKS_TABLE = /^\s*\[\s*hooks\s*\]\s*(?:#.*)?$/;
+const STATE_TABLE = /^\s*\[\s*hooks\s*\.\s*state\s*\]\s*(?:#.*)?$/;
+const TRUSTED_HASH = new RegExp(`^\\s*${USER_HOOKS.trustedHash}\\s*=\\s*"([^"\\\\]*)"\\s*(?:#.*)?$`);
+const DISABLED = new RegExp(`^\\s*${USER_HOOKS.enabled}\\s*=\\s*false\\s*(?:#.*)?$`);
+/** The two keys as a line names one, whatever its value is written like: what a line edit would duplicate. */
+const HASH_KEY = new RegExp(`^\\s*("?)${USER_HOOKS.trustedHash}\\1\\s*=`);
+const ENABLED_KEY = new RegExp(`^\\s*("?)${USER_HOOKS.enabled}\\1\\s*=`);
+/** The file as lines, which of them are inside multi-line strings, and every `hooks.state` table in the form written. */
+function scan(toml) {
+    const lines = toml.split('\n');
+    const opaque = [];
+    let open;
+    for (const line of lines) {
+        opaque.push(open !== undefined);
+        open = afterLine(line, open);
+    }
+    const tables = [];
+    for (let at = 0; at < lines.length; at += 1) {
+        if (opaque[at])
+            continue;
+        const raw = STATE_HEADER.exec(lines[at] ?? '')?.[1];
+        if (raw === undefined)
+            continue;
+        let end = at + 1;
+        while (end < lines.length && (opaque[end] || !HEADER.test(lines[end] ?? '')))
+            end += 1;
+        let hash;
+        let hashLine;
+        let disabled = false;
+        let otherHash = false;
+        let enabled = false;
+        for (let inner = at + 1; inner < end; inner += 1) {
+            if (opaque[inner])
+                continue;
+            const line = lines[inner] ?? '';
+            const found = TRUSTED_HASH.exec(line)?.[1];
+            if (found !== undefined) {
+                hash = found;
+                hashLine = inner;
+            }
+            else if (HASH_KEY.test(line))
+                otherHash = true;
+            if (DISABLED.test(line))
+                disabled = true;
+            if (ENABLED_KEY.test(line))
+                enabled = true;
+        }
+        tables.push({
+            key: unescapeBasic(raw),
+            start: at,
+            end,
+            ...(hash === undefined ? {} : { hash }),
+            ...(hashLine === undefined ? {} : { hashLine }),
+            disabled,
+            otherHash,
+            enabled,
+        });
+    }
+    return { lines, opaque, tables };
+}
+/**
+ * The multi-line string still open at the end of `line`, given the one open at its start. The line is read the way
+ * TOML reads it, so a delimiter that is not one holds nothing open: `"""` after a `#` is a comment, `'''` inside a
+ * quoted Windows path is part of the path, and a backslash escapes the character after it in a basic string. Counting
+ * delimiters per line instead would let one odd occurrence mark the rest of the file opaque, hiding an existing
+ * approval and appending a second table under the same key (AO11).
+ */
+function afterLine(line, open) {
+    let inside = open;
+    let at = 0;
+    while (at < line.length) {
+        if (inside !== undefined) {
+            if (inside === '"""' && line[at] === '\\') {
+                at += 2;
+                continue;
+            }
+            if (line.startsWith(inside, at)) {
+                inside = undefined;
+                at += 3;
+                continue;
+            }
+            at += 1;
+            continue;
+        }
+        const char = line[at];
+        // Outside a string a `#` starts a comment, and nothing after it on the line is structure.
+        if (char === '#')
+            return undefined;
+        if (char === '"' || char === "'") {
+            const triple = char.repeat(3);
+            if (line.startsWith(triple, at)) {
+                inside = triple;
+                at += 3;
+                continue;
+            }
+            at = afterSingle(line, at + 1, char);
+            continue;
+        }
+        at += 1;
+    }
+    return inside;
+}
+/** The index just past a single-line string opened at `at` with `quote`, or the line's end where it is unterminated. */
+function afterSingle(line, at, quote) {
+    let index = at;
+    while (index < line.length) {
+        if (quote === '"' && line[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (line[index] === quote)
+            return index + 1;
+        index += 1;
+    }
+    return line.length;
+}
+/**
+ * AO11: why a line edit of these keys would make the file invalid, or `undefined` where it would not. `hooks` written
+ * inline or as a dotted key at the root, `state` defined inside `[hooks]`, one of the keys as a key of `[hooks.state]`
+ * or in any header but the plain `[hooks.state."<key>"]`, or that header twice.
+ */
+function unsafeFor(scanned, keys) {
+    const quoted = keys.flatMap((key) => [`"${escapeBasic(key)}"`, `'${key}'`]);
+    let context = 'root';
+    const seen = new Map();
+    for (let at = 0; at < scanned.lines.length; at += 1) {
+        if (scanned.opaque[at])
+            continue;
+        const line = scanned.lines[at] ?? '';
+        if (HEADER.test(line)) {
+            const state = STATE_HEADER.exec(line)?.[1];
+            if (state !== undefined) {
+                const key = unescapeBasic(state);
+                seen.set(key, (seen.get(key) ?? 0) + 1);
+                if ((seen.get(key) ?? 0) > 1 && keys.includes(key))
+                    return 'agentwhy\'s approval appears twice there';
+                context = 'other';
+                continue;
+            }
+            if (quoted.some((text) => line.includes(text)))
+                return WRITTEN_OTHERWISE;
+            context = HOOKS_TABLE.test(line) ? 'hooks' : STATE_TABLE.test(line) ? 'state' : 'other';
+            continue;
+        }
+        if (context === 'root' && /^\s*hooks\s*[=.]/.test(line))
+            return 'its hooks are written inline there';
+        if (context === 'hooks' && /^\s*state\s*[=.]/.test(line))
+            return 'its hooks are written inline there';
+        if (context === 'state' && quoted.some((text) => line.trimStart().startsWith(text)))
+            return WRITTEN_OTHERWISE;
+    }
+    return undefined;
+}
+function headerFor(key) {
+    return `[hooks.state."${escapeBasic(key)}"]`;
+}
+/** The event part of a key under `hooksPath`: `pre_tool_use` or `stop`. */
+function eventOf(key, hooksPath) {
+    return key.slice(hooksPath.length + 1).split(':')[0];
+}
+/** A TOML basic string's escapes for a path: backslashes and quotes. Other characters are written as they are. */
+function escapeBasic(key) {
+    return key.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+}
+function unescapeBasic(raw) {
+    return raw.replaceAll(/\\(u[0-9a-fA-F]{4}|U[0-9a-fA-F]{8}|.)/g, (_, escape) => {
+        if (escape.length > 1)
+            return String.fromCodePoint(Number.parseInt(escape.slice(1), 16));
+        return { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r' }[escape] ?? escape;
+    });
+}
+/** Object keys ordered at every depth, as the hash is taken over (AOB1). */
+function sorted(value) {
+    if (Array.isArray(value))
+        return value.map(sorted);
+    if (typeof value === 'object' && value !== null) {
+        const record = value;
+        return Object.fromEntries(Object.keys(record)
+            .sort()
+            .map((key) => [key, sorted(record[key])]));
+    }
+    return value;
+}

package/dist/cli/command-router.js

@@ -3,12 +3,16 @@ const HELP_FLAGS = ['--help', '-h'];
 export class CommandRouter {
     #commands;
     #withoutACommand;
+    #missingCommand;
     /**
      * `withoutACommand` answers `agentwhy` with nothing after it, and with arguments that begin with `-` (they are its
      * flags); without one, that stays a usage error. It may also be registered under its own name.
+     *
+     * `missingCommand` is said under that usage error alone, for whoever ran a bare `agentwhy` where nothing answers it.
      */
-    constructor(commands, withoutACommand) {
+    constructor(commands, withoutACommand, missingCommand) {
         this.#withoutACommand = withoutACommand;
+        this.#missingCommand = missingCommand;
         const byName = new Map();
         for (const command of commands) {
             if (byName.has(command.name))
@@ -27,7 +31,9 @@ export class CommandRouter {
         if (name !== undefined && HELP_FLAGS.includes(name))
             return { kind: 'help', usage: this.usage };
         if (name === undefined) {
-            return this.#withoutACommand === undefined ? this.#usageError('missing command') : this.#withoutACommand.execute([]);
+            if (this.#withoutACommand !== undefined)
+                return this.#withoutACommand.execute([]);
+            return { ...this.#usageError('missing command'), ...(this.#missingCommand === undefined ? {} : { hint: this.#missingCommand }) };
         }
         if (name.startsWith('-') && this.#withoutACommand !== undefined)
             return this.#withoutACommand.execute(argv);

package/dist/cli/commands/check-cli-command.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from 'node:util';
 import { parseSince } from '../../core/session-filter.js';
 import { isMarkResult, MARK_RESULTS } from '../../ports/mark-store.js';

package/dist/cli/commands/codex-stop-cli-command.js

@@ -1,27 +1,30 @@
-import { codexStopInstruction } from '../../refuse/render/codex-stop-words.js';
 import { EXIT_CODE } from '../exit-codes.js';
 const USAGE = `Usage: agentwhy codex-stop --codex
 
-Run by the Codex Stop hook. When agentwhy refused a shell command in this turn, asks Codex to
-explain the block in its reply. It reads the turn's local transcript and never sends it anywhere.
+Run by the Codex Stop hook. At the end of a Codex turn it says what agentwhy says at the end of a
+Claude Code one: a command it stopped, a key from a private file now in the chat, a private file
+you let the AI read, or that nothing private was opened. It reads the turn's local transcript and
+never sends it anywhere.
 `;
+/**
+ * Codex's Stop hook (`2026-10-02-codex-says-it-too.md` CX1). Its command is the one setup has always written and a
+ * person has approved in Codex (CK13), so what it says grew without asking anyone to approve it again: it runs `watch`
+ * for Codex, which says first a command agentwhy stopped (CX2), then what `watch` says at Claude Code's `Stop`.
+ */
 export class CodexStopCliCommand {
     name = 'codex-stop';
     usage = USAGE;
-    #refusals;
+    #watch;
     #interactive;
-    constructor(refusals, interactive) {
-        this.#refusals = refusals;
+    constructor(watch, interactive) {
+        this.#watch = watch;
         this.#interactive = interactive;
     }
     async execute(args) {
         if (args.length !== 1 || args[0] !== '--codex' || this.#interactive)
             return { kind: 'usage-error', message: 'codex-stop reads Codex hook input on standard input', usage: this.usage };
-        const refusals = await this.#refusals.find();
-        return {
-            kind: 'completed',
-            output: refusals.length === 0 ? '' : JSON.stringify({ decision: 'block', reason: codexStopInstruction(refusals) }),
-            exitCode: EXIT_CODE.ok,
-        };
+        // A hook never exits 2 and never fails loudly: whatever `watch` found to say is all it prints (R8).
+        const result = await this.#watch.run({});
+        return { kind: 'completed', output: result.output, exitCode: EXIT_CODE.ok };
     }
 }

package/dist/cli/commands/doctor-arguments.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from 'node:util';
 /** Parses the arguments after `doctor`. Never throws: bad input is a usage error. */
 export function parseDoctorArguments(args) {

package/dist/cli/commands/doctor-usage.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 export const DOCTOR_USAGE = `Usage: agentwhy doctor --input <session-dir | session.jsonl | rollout.jsonl | rollout-folder> [--json]
 
 Reports the structure of one Claude Code session - its sources, line types, tools,

package/dist/cli/commands/init-cli-command.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from 'node:util';
 import { EXIT_CODE } from '../exit-codes.js';
 export const INIT_USAGE = `Usage: agentwhy init [--watch] [--refuse] [--protect <pattern>] [--shared] [--codex]
@@ -7,9 +9,10 @@ export const INIT_USAGE = `Usage: agentwhy init [--watch] [--refuse] [--protect
 Sets up the current project, and undoes it. At a terminal it asks who it is for, what agentwhy
 should do here and what else to protect, then shows what it will write and asks. It writes to
 .claude/settings.local.json, the settings file that is yours alone and stays out of the repository,
-unless you say the change is for everyone. In a project that uses Codex, it writes refuse to
-.codex/hooks.json too, with the same rules, so a file blocked here is blocked in Codex as well -
-once you approve agentwhy's hook in Codex, which runs a new hook only after that.
+unless you say the change is for everyone. On a computer that uses Codex (~/.codex exists), it also
+writes refuse into your own ~/.codex/hooks.json and approves those entries - its own and nothing
+else, tried once first the way Codex runs them - so a file blocked here is blocked in Codex from
+the first message, in the terminal and in VS Code, with nothing to approve in Codex.
 
   --watch             agentwhy watch, when a delegated agent finishes: a notification when it
                       wrote a value from a protected file. Ticked in the list, and the one
@@ -22,8 +25,10 @@ once you approve agentwhy's hook in Codex, which runs a new hook only after that
                       for several. At a terminal you are asked for these as well
   --shared            write to .claude/settings.json, which is committed, so the hooks run for
                       everyone who clones. Default: .claude/settings.local.json, which is yours
-  --codex             write Codex's hook too, where nothing shows the project uses Codex yet. Alone,
-                      it writes only that, to match the refuse Claude Code already runs here
+  --codex             alone: write and approve Codex's check, to match the refuse Claude Code
+                      already runs here. With --remove: take agentwhy's entries and their
+                      approvals out of ~/.codex too, which a plain --remove leaves for the
+                      other projects that block files with them
   --remove            undo it. At a terminal it asks what to take out - each hook, and each deny
                       rule by the path it protects - and removes only what is ticked. With
                       --watch or --refuse, only that hook; deny rules then stay

package/dist/cli/commands/notify-cli-command.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from 'node:util';
 import { ALERT_THRESHOLDS, DEFAULT_THRESHOLD } from '../../report/watch/agent-alert.js';
 import { CLEAN_MODES, DEFAULT_CHANNELS, DEFAULT_CLEAN, DEFAULT_SAID_AS, NOTICE_CHANNELS, NOTICE_LANGS, SAID_AS, } from '../../report/watch/notice-choices.js';
@@ -132,7 +134,7 @@ function said(view) {
 const LEVEL = {
     value: ' - a value from a protected file is in the conversation',
     reached: ' - that, and a protected file reached',
-    refused: ' - that, and an attempt a rule refused',
+    refused: ' - that, and an attempt that was stopped',
 };
 const QUIET = {
     off: ' - nothing is said about a turn that found nothing',

package/dist/cli/commands/refuse-cli-command.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from 'node:util';
 import { notCheckedMessage, refusalReason } from '../../refuse/render/refusal-words.js';
 import { EXIT_CODE } from '../exit-codes.js';
@@ -11,8 +13,10 @@ can ask the user. Anything else runs as it would have.
 
   --policy <file>     the policy to apply, as for \`report\`
   --settings <file>   a settings file whose deny rules stand in for a policy, as for \`report\`
-  --codex             the input is Codex's; a relative --settings is read in the project, the
-                      nearest folder at or above the command's that holds .codex/hooks.json
+  --codex             the input is Codex's. The project is the nearest folder at or above the
+                      command's whose Claude Code settings run refuse, short of the home folder.
+                      Without --settings or --policy, the rules are the ones that project's refuse
+                      names; where no such folder is found, the command runs with no message
   -h, --help          this text
 
 It reads a command line, so it does NOT stop: a path held in a variable, reached after cd, or
@@ -22,8 +26,9 @@ those. When it cannot read its input or its policy, or a search reaches more fil
 look through, it lets the command run and warns the user, so a typo in a settings path cannot
 stop every command.
 
-Exit 2 refuses the command; 0 lets it run. agentwhy init --refuse installs the hook, and in a
-project that uses Codex, Codex's too - which Codex runs only once you approve it there.
+Exit 2 refuses the command; 0 lets it run. agentwhy init --refuse installs the hook, and on a
+computer that uses Codex, Codex's too - written into your own ~/.codex files and approved there
+by agentwhy itself, tried once first, so it runs from the first message.
 `;
 /** `agentwhy refuse` - the shell hook of `specs/2026-09-16-worth-running-every-day.md` R18-R22. */
 export class RefuseCliCommand {

package/dist/cli/commands/report-arguments.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from 'node:util';
 import { widthFor } from './report-usage.js';
 /**

package/dist/cli/commands/report-usage.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 export const DEFAULT_WIDTH = 100;
 /** Narrower than this the layout stops being a layout; wider, a line is too long to run an eye back along. */
 const WIDTH_BOUNDS = { least: 60, most: 120 };

package/dist/cli/commands/sessions-cli-command.js

@@ -1,11 +1,14 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from 'node:util';
 import { parseSince, splitBySince } from '../../core/session-filter.js';
-import { sessionKey } from '../../core/session-catalogue.js';
+import { noStoreAnywhere, sessionKey } from '../../core/session-catalogue.js';
 import { PROVIDER_NAMES } from '../../core/session-format.js';
 import { recogniseAll } from '../../core/session-titles.js';
 import { table } from '../../shared/text-table.js';
 import { EXIT_CODE } from '../exit-codes.js';
 import { EXIT_CODE_BY_OUTCOME } from './report-cli-command.js';
+import { nothingSavedHere } from '../../report/nothing-saved-here.js';
 export const SESSIONS_USAGE = `Usage: agentwhy sessions [--since <span | date>] [--no-interactive]
 
 Lists the sessions Claude Code has kept for the current directory's project, newest first,
@@ -65,6 +68,11 @@ export class SessionsCliCommand {
         const listing = await catalogue.list(workingDirectory);
         // "Nothing here" and "looked in the wrong place" are different answers, and the second is far more likely
         // to be the truth when a path encoding is involved.
+        if (!listing.found && noStoreAnywhere(listing)) {
+            const where = listing.searched.map((place) => place.directory).join(' and ');
+            const ways = 'use Claude Code or Codex here, then run agentwhy sessions again - or run agentwhy init now, to be protected in Claude Code before there is history to check.';
+            return { kind: 'completed', output: nothingSavedHere('Claude Code or Codex', where, ways), exitCode: EXIT_CODE.ok };
+        }
         if (!listing.found) {
             return {
                 kind: 'completed',