@agentwhy/cli 0.1.0 → 0.2.1

package/dist/adapter/codex/events/codex-session-source.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { basename } from 'node:path';
 import { MAIN_AGENT_TYPE } from '../../../core/agent.js';
 import { correlate } from '../../../core/correlation/correlate.js';

package/dist/adapter/codex/events/hook-refusals.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { HOOK_REFUSAL } from '../contract/hook-refusals.js';
 /**
  * agentwhy's own reason (`refuse/render/refusal-words.ts` `refusalReason`), after Codex's words for a hook's refusal: "it

package/dist/adapter/codex/events/rollout-scan.js

@@ -492,7 +492,7 @@ class FileState {
                         },
                         result: {
                             callId: id, content: refusal.reason, stage: 'model', completeness: 'complete', evidence: output.evidence,
-                            denial: { kind: HOOK_REFUSAL.denialKind, recognised: true },
+                            denial: { kind: HOOK_REFUSAL.denialKind, recognised: true, source: 'rule' },
                         },
                     });
                 });

package/dist/adapter/codex/hooks/codex-conversation.js

@@ -0,0 +1,54 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { isJsonObject, parseJsonObject } from '../../../shared/json.js';
+import { THREAD_NAMES } from '../contract/session.js';
+/**
+ * The one conversation a Codex session belongs to (`codex-says-it-too` CXB5, CX8). Measured 2026-10-02: the Codex apps
+ * give one visible conversation a new session id as it goes on - four of five conversations of that day's test project
+ * held two ids each - so anything said "once a conversation" and keyed by the session id was said again, and a line
+ * already said in one app came again in the other. The only record joining them is Codex's own thread index: rows of
+ * `{id, thread_name, updated_at}`, one thread's sessions sharing its name. The conversation's key is the thread's
+ * earliest session id - an id, never the name, so nothing a person typed reaches a file name built from this.
+ *
+ * Where the index has no row for the session (an `exec` run, a build that keeps no index) or cannot be read, the
+ * session id stands, as before. Two conversations Codex happened to title alike are grouped as one - the cost is a
+ * once-line not repeated across the twins, never a finding lost.
+ */
+export async function codexConversationOf(files, indexPath, sessionId) {
+    const name = new Map();
+    const firstSeen = new Map();
+    try {
+        for await (const raw of files.readLines(indexPath)) {
+            const row = parseJsonObject(raw);
+            if (!isJsonObject(row))
+                continue;
+            const id = row[THREAD_NAMES.id];
+            const threadName = row[THREAD_NAMES.name];
+            const at = row[THREAD_NAMES.updatedAt];
+            if (typeof id !== 'string' || id === '' || typeof threadName !== 'string')
+                continue;
+            // A later line renames the thread: the name an id has is its last line's (as the titles reader reads it).
+            name.set(id, threadName);
+            if (!firstSeen.has(id) && typeof at === 'string')
+                firstSeen.set(id, at);
+        }
+    }
+    catch (error) {
+        if (error instanceof FileAccessError)
+            return sessionId;
+        throw error;
+    }
+    const thread = name.get(sessionId);
+    if (thread === undefined)
+        return sessionId;
+    let earliest = sessionId;
+    for (const [id, current] of name) {
+        if (current !== thread)
+            continue;
+        const order = (one) => `${firstSeen.get(one) ?? ''}\u0000${one}`;
+        if (order(id) < order(earliest))
+            earliest = id;
+    }
+    return earliest;
+}

package/dist/adapter/codex/hooks/pre-tool-use-input.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { PRE_TOOL_USE } from '../contract/hooks.js';
 import { isJsonObject, parseJsonObject } from '../../../shared/json.js';
 /**

package/dist/adapter/codex/hooks/reader.js

@@ -0,0 +1,38 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { isJsonObject, parseJsonObject } from '../../../shared/json.js';
+import { READER, SESSION } from '../contract/session.js';
+const NOBODY = { attended: false, quietSaidByAgent: false, foldsTurn: false };
+/**
+ * Read from the rollout's first line, the one line it is read for. A rollout that cannot be read, or a first line that
+ * is not Codex's, is nobody reading: the agent is then never asked to speak, and the line is said all the same.
+ */
+export async function codexReaderOf(files, rollout) {
+    if (rollout === undefined)
+        return NOBODY;
+    const lines = files.readLines(rollout)[Symbol.asyncIterator]();
+    try {
+        const first = await lines.next();
+        const line = first.done === true ? undefined : parseJsonObject(first.value);
+        if (line?.[SESSION.lineType] !== SESSION.metadataType)
+            return NOBODY;
+        const payload = line[SESSION.payload];
+        if (!isJsonObject(payload) || payload[SESSION.source] !== READER.personSource)
+            return NOBODY;
+        const originator = payload[SESSION.originator];
+        return {
+            attended: true,
+            quietSaidByAgent: originator !== READER.terminalOriginator,
+            foldsTurn: typeof originator === 'string' && READER.desktopOriginators.includes(originator),
+        };
+    }
+    catch (error) {
+        if (error instanceof FileAccessError)
+            return NOBODY;
+        throw error;
+    }
+    finally {
+        await lines.return?.();
+    }
+}

package/dist/adapter/codex/hooks/stop-input.js

@@ -0,0 +1,32 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { STOP } from '../contract/hooks.js';
+import { parseJsonObject } from '../../../shared/json.js';
+/** Codex's `Stop` input, read by the names Codex gives it. Never throws: what cannot be used is named. */
+export function parseCodexStopInput(text) {
+    const input = parseJsonObject(text);
+    if (input === undefined)
+        return { unusable: 'not-json' };
+    const { fields } = STOP;
+    if (input[fields.event] !== STOP.event)
+        return { unusable: 'another-event' };
+    const sessionId = input[fields.sessionId];
+    if (typeof sessionId !== 'string' || sessionId === '')
+        return { unusable: 'field-missing' };
+    const transcriptPath = input[fields.transcriptPath];
+    const lastMessage = input[fields.lastMessage];
+    return {
+        turn: {
+            sessionId,
+            // As for Claude Code: anything but `true` is no continuation, and the store refuses a second block anyway.
+            active: input[fields.active] === true,
+            ...(typeof transcriptPath === 'string' && transcriptPath !== '' ? { transcriptPath } : {}),
+            ...(typeof lastMessage === 'string' ? { lastMessage } : {}),
+        },
+    };
+}
+/** The folder a Codex hook ran in: where the project's rules are looked for (CK3). */
+export function codexStopFolder(text) {
+    const folder = parseJsonObject(text)?.[STOP.fields.workingDirectory];
+    return typeof folder === 'string' && folder !== '' ? folder : undefined;
+}

package/dist/adapter/codex/hooks/stop-refusals.js

@@ -12,15 +12,12 @@ import { hookRefusalsIn } from '../events/hook-refusals.js';
  * outputs with the Stop input's turn id. It never returns any other transcript content.
  */
 export class CodexTurnRefusals {
-    #input;
     #files;
-    constructor(input, files) {
-        this.#input = input;
+    constructor(files) {
         this.#files = files;
     }
-    async find() {
-        const text = await this.#input.readAll(1024 * 1024);
-        const input = text === undefined ? undefined : parseJsonObject(text);
+    async find(text) {
+        const input = parseJsonObject(text);
         if (input === undefined || input[STOP.fields.event] !== STOP.event || input[STOP.fields.active] === true)
             return [];
         const turnId = input[STOP.fields.turnId];

package/dist/adapter/codex/probe/codex-probe.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { basename } from 'node:path';
 import { Counter } from '../../../shared/counter.js';
 import { FileAccessError } from '../../../ports/file-access-error.js';

package/dist/adapter/codex/settings/codex-check.js

@@ -0,0 +1,38 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { join } from 'node:path';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { parseJsonObject } from '../../../shared/json.js';
+import { USER_HOOKS } from '../contract/hooks.js';
+import { approvedCodexEntries } from './codex-hooks.js';
+import { approvalKey, approvalOf, entryHash } from './hook-approval.js';
+export async function codexCheckState(files, home) {
+    const userPath = join(home, USER_HOOKS.directory, USER_HOOKS.file);
+    const file = parseJsonObject((await textOf(files, userPath)) ?? '');
+    if (file === undefined)
+        return 'absent';
+    // The entries setup approves, not every entry of agentwhy's: one left sharing a group with another tool's (AO4) is
+    // never approved, so demanding an approval for it too would pin the state at `stale` with no repair to reach.
+    const placed = approvedCodexEntries(file);
+    if (placed.length === 0)
+        return 'absent';
+    const config = await textOf(files, join(home, USER_HOOKS.directory, USER_HOOKS.config));
+    if (config === undefined)
+        return 'stale';
+    const verified = placed.every((entry) => {
+        const hash = entryHash(entry);
+        const approval = approvalOf(config, approvalKey(userPath, entry));
+        return hash !== undefined && approval !== undefined && approval.hash === hash && !approval.disabled;
+    });
+    return verified ? 'on' : 'stale';
+}
+async function textOf(files, path) {
+    try {
+        return await files.readText(path);
+    }
+    catch (error) {
+        if (error instanceof FileAccessError)
+            return undefined;
+        throw error;
+    }
+}

package/dist/adapter/codex/settings/codex-hooks.js

@@ -1,5 +1,7 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { isJsonObject } from '../../../shared/json.js';
-import { PRE_TOOL_USE, PROJECT_HOOKS } from '../contract/hooks.js';
+import { HOOK_HASH, PRE_TOOL_USE, PROJECT_HOOKS, USER_HOOKS } from '../contract/hooks.js';
 /**
  * agentwhy's Codex hook, and no one else's: `refuse` with `--codex` straight after it. Nothing but agentwhy writes that
  * flag, so a command with it is taken out and replaced, and every other command in the file is left as it was (K13).
@@ -14,6 +16,16 @@ const RUNS_CODEX_STOP = /(?:^|\s)codex-stop\s+--codex(?:\s|$)/;
 export function codexRefuseCommand(invoke, settings) {
     return `${invoke} refuse --codex${settings === undefined ? '' : ` --settings "${settings}"`}`;
 }
+/** The `--settings` a command `codexRefuseCommand` wrote names, as written - relative to the project. */
+const SETTINGS_NAMED = /\s--settings\s+"([^"]*)"/;
+/**
+ * The settings file agentwhy's Codex `refuse` reads in this file, relative to the project, where it names one (CK2):
+ * the rules Codex's Stop hook reads too (`codex-says-it-too` CX5), so the two never read different lists.
+ */
+export function codexRefuseSettings(file) {
+    const command = codexRefuseIn(file);
+    return command === undefined ? undefined : SETTINGS_NAMED.exec(command)?.[1];
+}
 /** The companion Stop hook asks Codex to credit agentwhy for a blocked command in its reply. */
 export function codexStopCommand(invoke) {
     return `${invoke} codex-stop --codex`;
@@ -71,6 +83,161 @@ export function withoutCodexRefuse(file) {
     }
     return { file: removed === 0 ? file : { ...file, [PROJECT_HOOKS.hooks]: kept }, removed };
 }
+/** The two events agentwhy writes, each with the pattern that tells its command and the group it writes. */
+const OWN_EVENTS = [
+    { event: 'PreToolUse', runs: RUNS_CODEX_REFUSE, matcher: PRE_TOOL_USE.shellTool },
+    { event: 'Stop', runs: RUNS_CODEX_STOP },
+];
+/**
+ * agentwhy's entries where they stand in this file, with the indices Codex keys their approval by
+ * (`2026-10-02-codex-approves-its-own-hook.md` AOB1, AO3). Every array item counts toward an index, valid or not,
+ * because Codex enumerates them all.
+ */
+export function agentwhyCodexEntries(file) {
+    const hooks = file[PROJECT_HOOKS.hooks];
+    if (!isJsonObject(hooks))
+        return [];
+    const found = [];
+    for (const { event, runs } of OWN_EVENTS) {
+        const list = hooks[event];
+        if (!Array.isArray(list))
+            continue;
+        list.forEach((group, groupIndex) => {
+            if (!isJsonObject(group) || !Array.isArray(group[PROJECT_HOOKS.commands]))
+                return;
+            group[PROJECT_HOOKS.commands].forEach((item, handlerIndex) => {
+                if (!isJsonObject(item) || typeof item[PROJECT_HOOKS.command] !== 'string' || !runs.test(item[PROJECT_HOOKS.command]))
+                    return;
+                const matcher = group[PROJECT_HOOKS.matcher];
+                found.push({ event, group: groupIndex, handler: handlerIndex, ...(typeof matcher === 'string' ? { matcher } : {}), entry: item });
+            });
+        });
+    }
+    return found;
+}
+/**
+ * The entries agentwhy approves: the first of each event, which is the one `withOwnPair` keeps and setup files an
+ * approval for (AO3). A further entry of the same event is one that shares a group with another tool's and stays
+ * (AO4), unapproved and so skipped by Codex - never a reason to call the approved check anything but what it is.
+ */
+export function approvedCodexEntries(file) {
+    const seen = new Set();
+    return agentwhyCodexEntries(file).filter((entry) => {
+        if (seen.has(entry.event))
+            return false;
+        seen.add(entry.event);
+        return true;
+    });
+}
+/**
+ * The file holding exactly one agentwhy pair (AO1, AO4): of each event, the first agentwhy entry is rewritten **in
+ * place** to the wanted command - alone in its group, the group's matcher becomes agentwhy's own - and every other
+ * agentwhy entry of that event comes out; where there is none, a group is appended at the end of the event's list.
+ * Nothing else moves, so no other tool's approval key shifts (AOD3).
+ */
+export function withOwnPair(file, refuseCommand, stopCommand) {
+    const hooks = isJsonObject(file[PROJECT_HOOKS.hooks]) ? file[PROJECT_HOOKS.hooks] : {};
+    const next = { ...hooks };
+    let removed = 0;
+    let stuck = 0;
+    for (const { event, runs, matcher } of OWN_EVENTS) {
+        const command = event === 'PreToolUse' ? refuseCommand : stopCommand;
+        const list = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
+        const placed = positionsIn(list, runs);
+        const [first, ...duplicates] = placed;
+        if (first === undefined) {
+            list.push({ ...(matcher === undefined ? {} : { [PROJECT_HOOKS.matcher]: matcher }), [PROJECT_HOOKS.commands]: [ownEntry(command)] });
+        }
+        else {
+            const group = list[first.group];
+            const handlers = [...group[PROJECT_HOOKS.commands]];
+            handlers[first.handler] = ownEntry(command);
+            const alone = handlers.length === 1;
+            list[first.group] = { ...group, ...(alone && matcher !== undefined ? { [PROJECT_HOOKS.matcher]: matcher } : {}), [PROJECT_HOOKS.commands]: handlers };
+        }
+        const result = withoutPositions(list, duplicates);
+        removed += result.removed;
+        stuck += result.stuck;
+        next[event] = result.list;
+    }
+    return { file: { ...file, [PROJECT_HOOKS.hooks]: next }, removed, stuck };
+}
+/**
+ * The file without agentwhy's entries (AO4, AO7): each comes out of its group; a group left empty is dropped only when
+ * it is the last of its event's list - and then the next one before it, while it is agentwhy's emptied group too - and
+ * otherwise stays as an empty group, which Codex skips and still counts. An entry with another tool's entry after it in
+ * the same group stays, and is counted as `stuck`: taking it out would shift that entry's key.
+ */
+export function withoutOwnEntries(file) {
+    const hooks = file[PROJECT_HOOKS.hooks];
+    if (!isJsonObject(hooks))
+        return { file, removed: 0, stuck: 0 };
+    const next = { ...hooks };
+    let removed = 0;
+    let stuck = 0;
+    for (const { event, runs } of OWN_EVENTS) {
+        const list = hooks[event];
+        if (!Array.isArray(list))
+            continue;
+        const result = withoutPositions([...list], positionsIn(list, runs));
+        removed += result.removed;
+        stuck += result.stuck;
+        if (result.removed === 0)
+            continue;
+        if (result.list.length === 0)
+            delete next[event];
+        else
+            next[event] = result.list;
+    }
+    return { file: removed === 0 ? file : { ...file, [PROJECT_HOOKS.hooks]: next }, removed, stuck };
+}
+/**
+ * agentwhy's entry as written: the command and Codex's wait for it (AO14, AOD9), and nothing else, so its hash stays
+ * within what was measured (AO2, AOB10).
+ */
+function ownEntry(command) {
+    return { [PROJECT_HOOKS.type]: PROJECT_HOOKS.commandType, [PROJECT_HOOKS.command]: command, [HOOK_HASH.fields.timeout]: USER_HOOKS.timeoutSeconds };
+}
+function positionsIn(list, runs) {
+    const found = [];
+    list.forEach((group, groupIndex) => {
+        if (!isJsonObject(group) || !Array.isArray(group[PROJECT_HOOKS.commands]))
+            return;
+        group[PROJECT_HOOKS.commands].forEach((item, handlerIndex) => {
+            if (isJsonObject(item) && typeof item[PROJECT_HOOKS.command] === 'string' && runs.test(item[PROJECT_HOOKS.command])) {
+                found.push({ group: groupIndex, handler: handlerIndex });
+            }
+        });
+    });
+    return found;
+}
+/** The list with these entries out, under AO4's rule that no other entry's position moves. */
+function withoutPositions(list, positions) {
+    let removed = 0;
+    let stuck = 0;
+    const emptied = new Set();
+    const byGroup = new Map();
+    for (const { group, handler } of positions)
+        byGroup.set(group, [...(byGroup.get(group) ?? []), handler]);
+    for (const [groupIndex, handlers] of byGroup) {
+        const group = list[groupIndex];
+        const items = [...group[PROJECT_HOOKS.commands]];
+        const out = new Set(handlers);
+        // From the end: an entry comes out only while everything after it in the group comes out too.
+        let keepFrom = items.length;
+        while (keepFrom > 0 && out.has(keepFrom - 1))
+            keepFrom -= 1;
+        removed += items.length - keepFrom;
+        stuck += handlers.length - (items.length - keepFrom);
+        const kept = items.slice(0, keepFrom);
+        list[groupIndex] = { ...group, [PROJECT_HOOKS.commands]: kept };
+        if (kept.length === 0)
+            emptied.add(groupIndex);
+    }
+    while (list.length > 0 && emptied.has(list.length - 1))
+        list.pop();
+    return { list, removed, stuck };
+}
 function commandsOf(file, event) {
     const hooks = file[PROJECT_HOOKS.hooks];
     if (!isJsonObject(hooks))