@agentwhy/cli 0.0.0-dev

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

@@ -0,0 +1,128 @@
+import { parseArgs } from 'node:util';
+import { parseSince } from '../../core/session-filter.js';
+import { isMarkResult, MARK_RESULTS } from '../../ports/mark-store.js';
+import { EXIT_CODE } from '../exit-codes.js';
+export const CHECK_USAGE = `Usage: agentwhy check [--since <span | date>] [--full] [--policy <file> | --settings <file>]
+                     [--share]
+       agentwhy check --mark rotated|not-secret|handled|not-private <path> [--note <text>]
+                     [--since <span | date>]
+       agentwhy check --unmark <path>
+
+Reads every session of the current directory's project active inside the range and says what to
+do about them: one line per file, the strongest thing known about it first. Writes nothing.
+
+  ROTATE     a value from this file was in an agent's context
+  CHECK      the same, for a file named as a template - is the value in it real?
+  UNKNOWN    a call named it and its outcome was not recorded
+  REACHED    a call opened it and nothing refused the call
+  IN RESULT  it was printed by a search; no call named it
+
+  --since <span|date> sessions last active since then: 7d, 12h, 2w, or 2026-09-01 (UTC). Default 7d
+  --full              every section, with what each one means and the rule that would close it
+  --policy <file>     the policy the sessions are read under, as for \`report\`
+  --settings <file>   a settings file whose deny rules stand in for a policy, as for \`report\`.
+                      Without either, the built-in default is used and the output says so
+  --share             paths relative to the project root, nothing above it
+  --mark <result> <path>
+                      record that you dealt with one line: rotated (any line), not-secret (a template
+                      line whose values are placeholders), handled (a file with no key in it, whose
+                      contents cannot be changed: you did what could be done), or not-private (a file
+                      with no key in it that holds nothing private). The file leaves the check until a session active
+                      after the mark reaches it again. Kept for you alone, outside the project:
+                      ~/.agentwhy/projects/<project>/marks.jsonl
+  --note <text>       with --mark: one line saying what was done, at most 200 characters
+  --unmark <path>     undo a standing mark; the history keeps both
+  -h, --help          this text
+
+Exit code 0 when the check ran, whatever it found, and when a mark was recorded; 2 for bad arguments, a refused
+policy or a mark that names no line; 3 when a mark could not be written.
+`;
+// A Record over the outcome union: a new outcome does not compile until it has an exit code.
+const EXIT_CODE_BY_OUTCOME = {
+    checked: EXIT_CODE.ok,
+    'no-sessions': EXIT_CODE.ok,
+    'policy-refused': EXIT_CODE.usage,
+    marked: EXIT_CODE.ok,
+    'mark-refused': EXIT_CODE.usage,
+    'mark-failed': EXIT_CODE.unexpected,
+};
+/** `agentwhy check` - what to do now (`specs/2026-09-16-worth-running-every-day.md` R11-R16). */
+export class CheckCliCommand {
+    name = 'check';
+    usage = CHECK_USAGE;
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async execute(args) {
+        let values;
+        let positionals;
+        try {
+            ({ values, positionals } = parseArgs({
+                args: [...args],
+                options: {
+                    since: { type: 'string', default: '7d' },
+                    full: { type: 'boolean', default: false },
+                    policy: { type: 'string' },
+                    settings: { type: 'string' },
+                    share: { type: 'boolean', default: false },
+                    mark: { type: 'string' },
+                    note: { type: 'string' },
+                    unmark: { type: 'string' },
+                    help: { type: 'boolean', short: 'h', default: false },
+                },
+                strict: true,
+                allowPositionals: true,
+            }));
+        }
+        catch (error) {
+            return { kind: 'usage-error', message: error instanceof Error ? error.message : String(error), usage: this.usage };
+        }
+        if (values.help)
+            return { kind: 'help', usage: this.usage };
+        const usageError = (message) => ({ kind: 'usage-error', message, usage: this.usage });
+        if (values.unmark !== undefined) {
+            if (values.mark !== undefined || values.note !== undefined || positionals.length > 0) {
+                return usageError('--unmark takes one path and nothing else');
+            }
+            const result = await this.#dependencies.check.unmark({ path: values.unmark });
+            return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
+        }
+        if (values.mark === undefined) {
+            if (positionals.length > 0)
+                return usageError(`unexpected argument: ${positionals[0]}`);
+            if (values.note !== undefined)
+                return usageError('--note is given with --mark');
+        }
+        else {
+            if (!isMarkResult(values.mark))
+                return usageError(`--mark is ${MARK_RESULTS.join(', ')}`);
+            if (positionals.length !== 1)
+                return usageError('--mark takes one path: agentwhy check --mark rotated <path>');
+            if (values.full || values.share)
+                return usageError('--mark is not given with --full or --share');
+        }
+        const since = parseSince(values.since, this.#dependencies.now);
+        if ('error' in since)
+            return usageError(since.error);
+        if (isMarkResult(values.mark)) {
+            const result = await this.#dependencies.check.mark({
+                since,
+                path: positionals[0] ?? '',
+                result: values.mark,
+                ...(values.note === undefined ? {} : { note: values.note }),
+                ...(values.policy === undefined ? {} : { policyPath: values.policy }),
+                ...(values.settings === undefined ? {} : { settingsPath: values.settings }),
+            });
+            return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
+        }
+        const result = await this.#dependencies.check.run({
+            since,
+            share: values.share,
+            full: values.full,
+            ...(values.policy === undefined ? {} : { policyPath: values.policy }),
+            ...(values.settings === undefined ? {} : { settingsPath: values.settings }),
+        });
+        return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
+    }
+}

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

@@ -0,0 +1,27 @@
+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.
+`;
+export class CodexStopCliCommand {
+    name = 'codex-stop';
+    usage = USAGE;
+    #refusals;
+    #interactive;
+    constructor(refusals, interactive) {
+        this.#refusals = refusals;
+        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,
+        };
+    }
+}

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

@@ -0,0 +1,32 @@
+import { parseArgs } from 'node:util';
+/** Parses the arguments after `doctor`. Never throws: bad input is a usage error. */
+export function parseDoctorArguments(args) {
+    let values;
+    try {
+        values = parseValues(args);
+    }
+    catch (error) {
+        return usageError(error instanceof Error ? error.message : String(error));
+    }
+    if (values.help)
+        return { kind: 'help' };
+    if (values.input === undefined || values.input === '') {
+        return usageError('doctor needs --input <session-dir | session.jsonl>');
+    }
+    return { kind: 'options', options: { input: values.input, format: values.json ? 'json' : 'text' } };
+}
+function parseValues(args) {
+    return parseArgs({
+        args: [...args],
+        options: {
+            input: { type: 'string' },
+            json: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+        strict: true,
+        allowPositionals: false,
+    }).values;
+}
+function usageError(message) {
+    return { kind: 'usage-error', message };
+}

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

@@ -0,0 +1,31 @@
+import { EXIT_CODE } from '../exit-codes.js';
+import { parseDoctorArguments } from './doctor-arguments.js';
+import { DOCTOR_USAGE } from './doctor-usage.js';
+// A Record over the outcome union: a new outcome does not compile until it has an exit code.
+const EXIT_CODE_BY_OUTCOME = {
+    complete: EXIT_CODE.ok,
+    'main-transcript-missing': EXIT_CODE.mainTranscriptMissing,
+    // No session found, for the same reason a missing transcript is: nothing here is a report on a session.
+    'unknown-format': EXIT_CODE.mainTranscriptMissing,
+};
+export class DoctorCliCommand {
+    name = 'doctor';
+    usage = DOCTOR_USAGE;
+    #doctor;
+    constructor(doctor) {
+        this.#doctor = doctor;
+    }
+    async execute(args) {
+        const parsed = parseDoctorArguments(args);
+        switch (parsed.kind) {
+            case 'help':
+                return { kind: 'help', usage: this.usage };
+            case 'usage-error':
+                return { kind: 'usage-error', message: parsed.message, usage: this.usage };
+            case 'options': {
+                const result = await this.#doctor.run(parsed.options);
+                return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
+            }
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+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,
+denials and meta fields - or of Codex rollouts: their versions, history modes, record
+kinds, joins and what they can answer. The format is told by content, not by name.
+Prints counts and identifiers only, never transcript content.
+
+Exit codes:
+  0  report printed
+  1  no session found: the main transcript is missing, or the input is no Claude Code
+     or Codex session
+  2  usage error
+  3  unexpected error
+`;

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

@@ -0,0 +1,123 @@
+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]
+                    [--remove [--unprotect <pattern>]] [--yes] [--command <cmd>]
+       agentwhy init --update [--yes]
+
+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.
+
+  --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
+                      installed when nobody can be asked
+  --refuse            agentwhy refuse, before every shell command: refuses one that names a
+                      protected path or searches through one. It also refuses cat .env.example,
+                      and it matches the text of a command, so it is not a boundary
+  --protect <pattern> a path or pattern to protect, written as Read()/Edit() deny rules, with
+                      refuse installed too, so a shell command cannot print it either. Repeat
+                      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
+  --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
+  --unprotect <path>  with --remove, off a terminal: a protected path to take the deny rules of.
+                      Repeat for several. A rule is never removed unless it is named or ticked
+  --yes               write without asking, and without asking anything else either
+  --update            pin the hooks that run an older release of agentwhy through npx to this
+                      one's version, and change nothing else. agentwhy never updates by itself
+  --command <cmd>     how the hooks run agentwhy. Default: the way the hooks already here run it,
+                      else the way you ran this - agentwhy where that is the agentwhy on PATH,
+                      npx @agentwhy/cli@<this version> otherwise, pinned so that nothing updates
+                      until --update. Give the same --command to --remove when the command
+                      does not name agentwhy
+  -h, --help          this text
+
+A deny rule names a tool, not a file: Read(.env) stops the Read tool, while cat .env in a shell
+walks past it. refuse narrows that route by reading the command line. Neither is a boundary below the agent.
+
+Exit code 0 when the file was written, was already right, or nothing was asked to be written;
+2 for bad arguments or a settings file that is not a JSON object.
+`;
+// A Record over the outcome union: a new outcome does not compile until it has an exit code.
+const EXIT_CODE_BY_OUTCOME = {
+    written: EXIT_CODE.ok,
+    unchanged: EXIT_CODE.ok,
+    declined: EXIT_CODE.ok,
+    'not-confirmed': EXIT_CODE.ok,
+    refused: EXIT_CODE.usage,
+    unwritable: EXIT_CODE.usage,
+};
+/** `agentwhy init` - one command to set a project up (`specs/2026-09-16-worth-running-every-day.md` R4-R10). */
+export class InitCliCommand {
+    name = 'init';
+    usage = INIT_USAGE;
+    #setup;
+    constructor(setup) {
+        this.#setup = setup;
+    }
+    async execute(args) {
+        let values;
+        try {
+            ({ values } = parseArgs({
+                args: [...args],
+                options: {
+                    watch: { type: 'boolean', default: false },
+                    refuse: { type: 'boolean', default: false },
+                    protect: { type: 'string', multiple: true, default: [] },
+                    unprotect: { type: 'string', multiple: true, default: [] },
+                    shared: { type: 'boolean', default: false },
+                    remove: { type: 'boolean', default: false },
+                    yes: { type: 'boolean', short: 'y', default: false },
+                    command: { type: 'string' },
+                    update: { type: 'boolean', default: false },
+                    codex: { type: 'boolean', default: false },
+                    help: { type: 'boolean', short: 'h', default: false },
+                },
+                strict: true,
+                allowPositionals: false,
+            }));
+        }
+        catch (error) {
+            return { kind: 'usage-error', message: error instanceof Error ? error.message : String(error), usage: this.usage };
+        }
+        if (values.help)
+            return { kind: 'help', usage: this.usage };
+        // `nothing-updates-by-itself.md` U7: an update changes versions and nothing else, so no other flag means anything beside it.
+        if (values.update && (values.watch || values.refuse || values.protect.length > 0 || values.unprotect.length > 0 || values.shared || values.remove || values.codex || values.command !== undefined)) {
+            return { kind: 'usage-error', message: '--update takes no other flag but --yes', usage: this.usage };
+        }
+        if (values.update) {
+            const result = await this.#setup.run({ protect: [], remove: false, yes: values.yes, update: true });
+            return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
+        }
+        if (values.command?.trim() === '')
+            return { kind: 'usage-error', message: '--command is empty', usage: this.usage };
+        if (values.remove && values.protect.length > 0) {
+            return { kind: 'usage-error', message: '--remove undoes; to protect a path, run it without --remove', usage: this.usage };
+        }
+        if (!values.remove && values.unprotect.length > 0) {
+            return { kind: 'usage-error', message: '--unprotect takes rules out, so it belongs with --remove', usage: this.usage };
+        }
+        // Named hooks are the whole answer where they are given; with none, the list asks, or `watch` is installed.
+        const hooks = [...(values.watch ? ['watch'] : []), ...(values.refuse ? ['refuse'] : [])];
+        const result = await this.#setup.run({
+            ...(hooks.length === 0 ? {} : { hooks }),
+            ...(values.shared ? { target: 'shared' } : {}),
+            protect: values.protect,
+            ...(values.unprotect.length === 0 ? {} : { unprotect: values.unprotect }),
+            remove: values.remove,
+            yes: values.yes,
+            ...(values.codex ? { codex: true } : {}),
+            // Where none was given, the setup settles it (`a-hook-runs-what-you-ran.md` J1).
+            ...(values.command === undefined ? {} : { invoke: values.command.trim() }),
+        });
+        return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
+    }
+}

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

@@ -0,0 +1,58 @@
+import { EXIT_CODE } from '../exit-codes.js';
+export const MENU_USAGE = `Usage: agentwhy menu
+
+At a terminal: a list of the few things to do here. Pick one, it runs, you read what it said, and
+the list comes back so you can do the next thing. Leaving the list ends it, and so does Quit.
+Nothing is served by the list itself and nothing keeps running between those runs. It needs a
+terminal: piped or redirected, it prints this help and exits 2. \`agentwhy\` alone opens the page
+of sessions, the same as \`agentwhy start\`.
+`;
+/**
+ * `agentwhy menu` (`specs/2026-09-16-worth-running-every-day.md` R24, R74). A way on, and a way in for someone who
+ * does not know the commands: what is picked runs, what it said is printed, and the list comes back until the person
+ * leaves it. The list itself browses and serves nothing - each run is the same command it would have been from the
+ * shell - the same rule the rest of the tool follows (main spec §2).
+ */
+export class MenuCliCommand {
+    name = 'menu';
+    usage = MENU_USAGE;
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async execute(args) {
+        const { chooser, printer, entries, interactive } = this.#dependencies;
+        if (args.length > 0)
+            return { kind: 'usage-error', message: 'menu takes no arguments', usage: this.usage };
+        if (!interactive)
+            return { kind: 'usage-error', message: 'menu needs a terminal', usage: this.usage };
+        const rows = [...entries.map(({ label, detail }) => ({ label, detail })), { label: 'Quit', detail: 'leave agentwhy' }];
+        let exitCode = EXIT_CODE.ok;
+        for (let first = true;; first = false) {
+            const chosen = await chooser.choose(first ? 'What do you want to do?' : 'What now?', rows);
+            const entry = chosen === undefined ? undefined : entries[chosen];
+            // Leaving the list, or Quit, ends it: the exit code is that of the last thing that ran.
+            if (entry === undefined)
+                return { kind: 'completed', output: '', exitCode };
+            const result = await entry.command.execute([]);
+            // Written as it happens, because the list comes back afterwards and an answer held until the end is read last.
+            // The blank lines keep what a command said apart from the next question; on screen they run together otherwise.
+            printer.write(`\n${textOf(result).replace(/\n*$/, '\n')}\n`);
+            if (result.kind === 'completed')
+                exitCode = result.exitCode;
+        }
+    }
+}
+/** What a command said, whatever kind of answer it gave: a usage error is read the same way at a terminal. */
+function textOf(result) {
+    switch (result.kind) {
+        case 'completed':
+            return result.output;
+        case 'help':
+            return result.usage;
+        case 'usage-error':
+            return `agentwhy: ${result.message}\n\n${result.usage}`;
+        case 'hook-block':
+            return result.reason;
+    }
+}

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

@@ -0,0 +1,158 @@
+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';
+import { EXIT_CODE } from '../exit-codes.js';
+export const NOTIFY_USAGE = `Usage: agentwhy notify [--on value | reached | refused] [--clean off | once | every-turn]
+                       [--say agent | line] [--notify chat,terminal,os] [--lang en | pl | de]
+                       [--everywhere] [--reset]
+
+What agentwhy tells you when a turn ends, and when. Run with nothing, it says what is set now and
+where it comes from; with a choice, it writes that choice and the next turn uses it - no session
+restarted, no settings file touched.
+
+  --on <level>        which findings are said: value (default), reached, or refused
+  --clean <when>      when a turn that found nothing says so: once (default), off, or every-turn
+  --say <how>         how a value in the conversation is said: agent (default) - your own agent
+                      says it and offers the report - or line, the grey line under the reply
+  --notify <channels> where a notice is shown, comma-separated: chat, terminal, os
+  --lang <language>   the language of the line in the conversation: en, pl or de. Unset, it is
+                      your system's where agentwhy has words for it, else en
+  --everywhere        your answer for every project, instead of this one
+  --reset             take out the answers for this project, or with --everywhere, yours
+  -h, --help          this text
+
+Answers are read in this order: a flag written into a hook's command line, then this project's
+answer, then yours, then agentwhy's own. They live in one file outside every project, so nothing
+here is ever written into a repository.
+`;
+/** `agentwhy notify` - the command line half of `specs/2026-09-21-the-agent-tells-you.md` R26. */
+export class NotifyCliCommand {
+    name = 'notify';
+    usage = NOTIFY_USAGE;
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async execute(args) {
+        let values;
+        try {
+            ({ values } = parseArgs({
+                args: [...args],
+                options: {
+                    on: { type: 'string' },
+                    clean: { type: 'string' },
+                    say: { type: 'string' },
+                    notify: { type: 'string' },
+                    lang: { type: 'string' },
+                    everywhere: { type: 'boolean', default: false },
+                    reset: { type: 'boolean', default: false },
+                    help: { type: 'boolean', short: 'h', default: false },
+                },
+                strict: true,
+                allowPositionals: false,
+            }));
+        }
+        catch (error) {
+            return { kind: 'usage-error', message: error instanceof Error ? error.message : 'that is not an option', usage: this.usage };
+        }
+        if (values.help)
+            return { kind: 'help', usage: this.usage };
+        const on = read(values.on, ALERT_THRESHOLDS);
+        const clean = read(values.clean, CLEAN_MODES);
+        const say = read(values.say, SAID_AS);
+        const notify = values.notify === undefined ? undefined : channelsIn(values.notify);
+        const lang = read(values.lang, NOTICE_LANGS);
+        if (on === 'unknown')
+            return this.#unknown('--on', values.on ?? '', ALERT_THRESHOLDS);
+        if (clean === 'unknown')
+            return this.#unknown('--clean', values.clean ?? '', CLEAN_MODES);
+        if (say === 'unknown')
+            return this.#unknown('--say', values.say ?? '', SAID_AS);
+        if (notify === 'unknown')
+            return this.#unknown('--notify', values.notify ?? '', NOTICE_CHANNELS);
+        if (lang === 'unknown')
+            return this.#unknown('--lang', values.lang ?? '', NOTICE_LANGS);
+        const choices = {
+            ...(on === undefined ? {} : { on }),
+            ...(clean === undefined ? {} : { clean }),
+            ...(say === undefined ? {} : { say }),
+            ...(notify === undefined ? {} : { notify }),
+            ...(lang === undefined ? {} : { lang }),
+        };
+        const asked = Object.keys(choices).length > 0;
+        if (!asked && !values.reset)
+            return this.#say();
+        // A flag and `--reset` in one run would be a choice written and taken out again: said, rather than guessed at.
+        if (asked && values.reset) {
+            return { kind: 'usage-error', message: '--reset takes answers out; it cannot be given alongside one', usage: this.usage };
+        }
+        const result = await this.#dependencies.settings.change({
+            scope: values.everywhere ? 'everywhere' : 'project',
+            choices,
+            ...(values.reset ? { reset: true } : {}),
+        });
+        const view = await this.#dependencies.settings.view();
+        return {
+            kind: 'completed',
+            output: `${result.said}\n\n${said(view)}`,
+            exitCode: result.written ? EXIT_CODE.ok : EXIT_CODE.unexpected,
+        };
+    }
+    async #say() {
+        return { kind: 'completed', output: said(await this.#dependencies.settings.view()), exitCode: EXIT_CODE.ok };
+    }
+    #unknown(flag, given, known) {
+        return { kind: 'usage-error', message: `${flag} does not take "${given}". It takes: ${known.join(', ')}`, usage: this.usage };
+    }
+}
+/**
+ * What is set, and where each answer comes from. A person changing this is deciding how much they hear, so the
+ * lines say which of the three levels answered rather than only what the answer is.
+ */
+function said(view) {
+    const from = (key) => view.forProject[key] !== undefined ? 'this project' : view.defaults[key] !== undefined ? 'you, everywhere' : "agentwhy's own";
+    const lines = [
+        'What agentwhy tells you when a turn ends',
+        '',
+        `  Findings said     ${view.effective.on ?? DEFAULT_THRESHOLD}${level(view.effective.on ?? DEFAULT_THRESHOLD)}   (${from('on')})`,
+        `  A quiet turn      ${view.effective.clean ?? DEFAULT_CLEAN}${quiet(view.effective.clean ?? DEFAULT_CLEAN)}   (${from('clean')})`,
+        `  A value is said   ${view.effective.say ?? DEFAULT_SAID_AS}${saidAs(view.effective.say ?? DEFAULT_SAID_AS)}   (${from('say')})`,
+        `  Shown in          ${(view.effective.notify ?? DEFAULT_CHANNELS).join(', ')}   (${from('notify')})`,
+        `  Written in        ${view.effective.lang ?? "your system's language, else en"}   (${from('lang')})`,
+        '',
+        `  This project      ${view.project}`,
+        `  Answers kept in   ${view.path}`,
+        ...(view.unusable ? ['', `  That file could not be read, so none of the above is an answer anybody gave.`] : []),
+        '',
+        '  Change it         agentwhy notify --on reached',
+        '  For every project agentwhy notify --everywhere --clean every-turn',
+    ];
+    return `${lines.join('\n')}\n`;
+}
+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',
+};
+const QUIET = {
+    off: ' - nothing is said about a turn that found nothing',
+    once: " - the first quiet turn says the session is watched",
+    'every-turn': ' - said after every reply',
+};
+const SAID = {
+    agent: ' - by your own agent, which offers to open the report',
+    line: ' - as the grey line under the reply',
+};
+const saidAs = (how) => SAID[how];
+const level = (threshold) => LEVEL[threshold];
+const quiet = (mode) => QUIET[mode];
+function read(value, known) {
+    if (value === undefined)
+        return undefined;
+    return known.find((candidate) => candidate === value) ?? 'unknown';
+}
+function channelsIn(list) {
+    const names = list.split(',').map((name) => name.trim()).filter((name) => name !== '');
+    const channels = names.map((name) => NOTICE_CHANNELS.find((channel) => channel === name));
+    return channels.length === 0 || channels.includes(undefined) ? 'unknown' : [...new Set(channels)];
+}

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

@@ -0,0 +1,79 @@
+import { parseArgs } from 'node:util';
+import { notCheckedMessage, refusalReason } from '../../refuse/render/refusal-words.js';
+import { EXIT_CODE } from '../exit-codes.js';
+export const REFUSE_USAGE = `Usage: agentwhy refuse [--codex] [--policy <file> | --settings <file>]
+
+Run by a Claude Code or Codex PreToolUse hook on Bash, never by hand: reads the hook input on standard
+input and refuses a shell command that would open a file the policy protects, before it runs:
+one that names it, one with a glob the shell expands to it (cat .env*), and a recursive search
+(grep -r, rg) whose own filters do not leave it out. The agent is told which path and that it
+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
+  -h, --help          this text
+
+It reads a command line, so it does NOT stop: a path held in a variable, reached after cd, or
+built while the command runs; a search it does not recognise (find -exec, xargs, a script); any
+tool other than Bash. Only a boundary below the agent - file permissions, a sandbox - closes
+those. When it cannot read its input or its policy, or a search reaches more files than it can
+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.
+`;
+/** `agentwhy refuse` - the shell hook of `specs/2026-09-16-worth-running-every-day.md` R18-R22. */
+export class RefuseCliCommand {
+    name = 'refuse';
+    usage = REFUSE_USAGE;
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async execute(args) {
+        let values;
+        try {
+            ({ values } = parseArgs({
+                args: [...args],
+                options: {
+                    policy: { type: 'string' },
+                    settings: { type: 'string' },
+                    codex: { type: 'boolean', default: false },
+                    help: { type: 'boolean', short: 'h', default: false },
+                },
+                strict: true,
+                allowPositionals: false,
+            }));
+        }
+        catch {
+            return notChecked('arguments');
+        }
+        if (values.help)
+            return { kind: 'help', usage: this.usage };
+        if (this.#dependencies.interactive) {
+            return { kind: 'usage-error', message: 'refuse reads a hook input on standard input, and this is a terminal', usage: this.usage };
+        }
+        const decision = await this.#dependencies.refusal.decide({
+            ...(values.codex === true ? { codex: true } : {}),
+            ...(values.policy === undefined ? {} : { policyPath: values.policy }),
+            ...(values.settings === undefined ? {} : { settingsPath: values.settings }),
+        });
+        return resultOf(decision);
+    }
+}
+function resultOf(decision) {
+    switch (decision.kind) {
+        case 'allow':
+            return { kind: 'completed', output: '', exitCode: EXIT_CODE.ok };
+        case 'not-checked':
+            return notChecked(decision.reason);
+        case 'refuse':
+            return { kind: 'hook-block', reason: refusalReason(decision.path, decision.pattern, decision.others, decision.route) };
+    }
+}
+function notChecked(reason) {
+    return { kind: 'completed', output: notCheckedMessage(reason), exitCode: EXIT_CODE.ok };
+}