@agentwhy/cli 0.0.0-dev

package/dist/adapter/claude-code/settings/hook-entries.js

@@ -0,0 +1,303 @@
+import { isJsonObject } from '../../../shared/json.js';
+import { PACKAGE } from '../../../shared/package-name.js';
+import { isPlainInvocation, NPX_BEFORE_NAME, VERSION } from '../../../shared/plain-invocation.js';
+import { isOlder, plainVersion } from '../../../shared/plain-version.js';
+import { HOOK_SETTINGS, SETTINGS_FILES } from '../contract/settings.js';
+import { PRE_TOOL_USE, STOP, SUBAGENT_STOP } from '../contract/hooks.js';
+/**
+ * A command that runs agentwhy's `watch` or `refuse` through a word naming agentwhy - `agentwhy`, `npx @agentwhy/cli@1`,
+ * `node /opt/agentwhy/dist/cli.js`. The word may be a path with agentwhy anywhere in it; the subcommand is the next word.
+ * An invocation that names agentwhy nowhere is found by `invoke` instead (see `runs`). Found by a review: a path
+ * after agentwhy was not matched, so a second `init` added every hook twice and `--remove` removed nothing. The
+ * package's scope, `@agentwhy/`, counts as a word's start too - that scope and no other: found by a review, any `@`
+ * did, so `--remove` took out `npx @agentwhy-labs/notifier watch`, a hook agentwhy never wrote. A path's separator is
+ * either slash: found by a second review, `node_modules\@agentwhy\cli` on Windows stopped being found by the first fix.
+ */
+const RUNS_AGENTWHY = /(?:(?:^|[\s/\\])agentwhy|@agentwhy[/\\])\S*\s+(watch|refuse)(?:\s|$)/;
+/** Which hook a command runs, if it runs one: through a word naming agentwhy, or through the invocation `init` was given. */
+function hookRun(command, invoke) {
+    const named = RUNS_AGENTWHY.exec(command)?.[1];
+    if (named === 'watch' || named === 'refuse')
+        return named;
+    if (invoke === undefined)
+        return undefined;
+    for (const hook of ['watch', 'refuse']) {
+        const run = `${invoke} ${hook}`;
+        if (command === run || command.startsWith(`${run} `))
+            return hook;
+    }
+    return undefined;
+}
+/**
+ * The entries to install, each with the command it runs (R6, R9).
+ *
+ * `watch` is two entries, not one (`the-agent-nobody-watches` R1): `SubagentStop` finds what a delegated agent did,
+ * and `Stop` says it and checks the session's own agent - the one agent that has no `SubagentStop` of its own. The
+ * command line is the same in both, because `watch` reads the event from its input. Installed on one event alone it
+ * is half a tool: with no `Stop`, nothing is ever said in the conversation and the main agent is never checked.
+ */
+export function hookEntries(hooks, invoke, rules) {
+    const settings = rules === undefined
+        ? ''
+        : ` --settings "${HOOK_SETTINGS.projectDirectory}/${SETTINGS_FILES.directory}/${SETTINGS_FILES[rules]}"`;
+    return hooks.flatMap((hook) => hook === 'watch'
+        ? [SUBAGENT_STOP.event, STOP.event].map((event) => ({ hook, event, command: `${invoke} watch${settings}` }))
+        : [{ hook, event: PRE_TOOL_USE.event, matcher: PRE_TOOL_USE.shellTool, command: `${invoke} refuse${settings}` }]);
+}
+/**
+ * The entries of `hooks` that this settings object does not run yet, event by event. A hook is not "installed"
+ * where only one of its events is: a file written by an older version runs `watch` on `SubagentStop` alone, and
+ * asking for `watch` again has to add the `Stop` it is missing rather than report that there is nothing to do.
+ */
+export function missingHookEntries(settings, hooks, invoke, rules) {
+    const running = runningEvents(settings, invoke);
+    return hookEntries(hooks, invoke, rules).filter((entry) => running.get(entry.hook)?.has(entry.event) !== true);
+}
+/** Which events already run each of agentwhy's hooks, by the same reading `installedHooks` uses. */
+function runningEvents(settings, invoke) {
+    const found = new Map();
+    const hooks = settings[HOOK_SETTINGS.hooks];
+    if (!isJsonObject(hooks))
+        return found;
+    for (const [event, list] of Object.entries(hooks)) {
+        for (const command of commandsInList(list)) {
+            const hook = hookRun(command, invoke);
+            if (hook === undefined)
+                continue;
+            const events = found.get(hook) ?? new Set();
+            events.add(event);
+            found.set(hook, events);
+        }
+    }
+    return found;
+}
+/**
+ * Which of agentwhy's hooks a settings object already runs (R8): through any command naming agentwhy, and through
+ * `invoke`, the invocation this run of `init` was given, however it is spelled.
+ */
+export function installedHooks(settings, invoke) {
+    const found = new Set();
+    for (const command of commandsIn(settings)) {
+        const hook = hookRun(command, invoke);
+        if (hook !== undefined)
+            found.add(hook);
+    }
+    return found;
+}
+/**
+ * How the `Stop` hook that runs `watch` runs agentwhy: its command up to the subcommand, `npx @agentwhy/cli` or
+ * `agentwhy`. A command that works as a hook is one that works for the agent in the same project, which a name
+ * chosen here would not be: `agentwhy` is on no path where only `npx` ever ran it. `undefined` where these settings
+ * run no such hook, or run it through anything but plain words.
+ */
+export function watchInvocation(settings) {
+    const hooks = settings[HOOK_SETTINGS.hooks];
+    if (!isJsonObject(hooks))
+        return undefined;
+    return firstPlain(commandsInList(hooks[STOP.event]), ['watch']);
+}
+/**
+ * How the agentwhy hooks these settings already run invoke it: the first one's command up to its subcommand, where it
+ * is in plain words (`a-hook-runs-what-you-ran.md` J1, J4). A hook written next repeats it (R42), so a project does
+ * not run `watch` one way and `refuse` another.
+ */
+export function runningInvocation(settings) {
+    return firstPlain(commandsIn(settings), ['watch', 'refuse']);
+}
+/** The first of these commands that runs one of `hooks` through agentwhy named in plain words: its invocation. */
+function firstPlain(commands, hooks) {
+    for (const command of commands) {
+        const plain = plainRun(command);
+        if (plain !== undefined && hooks.includes(plain.hook))
+            return plain.invocation;
+    }
+    return undefined;
+}
+/**
+ * Which hook a command runs and the invocation before it, where agentwhy is named in plain words (J4). The session's
+ * agent is asked to run what `watchInvocation` finds (`the-agent-tells-you.md` R18), and a hook agentwhy writes repeats
+ * what `runningInvocation` finds, so a settings file cannot hand either more than agentwhy through it.
+ */
+function plainRun(command) {
+    const hook = hookRun(command, undefined);
+    if (hook === undefined)
+        return undefined;
+    const invocation = BEFORE_HOOK[hook].exec(command)?.[1];
+    return invocation !== undefined && isPlainInvocation(invocation) ? { hook, invocation } : undefined;
+}
+/** The words before each hook's subcommand: the invocation `plainRun` reads, whether plain or not. */
+const BEFORE_HOOK = {
+    watch: /^\s*(.*?)\s+watch(?:\s|$)/,
+    refuse: /^\s*(.*?)\s+refuse(?:\s|$)/,
+};
+/**
+ * The published way with its version pinned, `npx @agentwhy/cli@0.2.0`, `--yes` allowed: what a hook written by a
+ * release runs (`nothing-updates-by-itself.md` U1), and the only form an update rewrites (U7). Built from the plain-words
+ * pattern's own parts, so the two cannot read `npx` differently. The package's name holds no character a pattern reads
+ * as more than itself.
+ */
+const PINNED = new RegExp(`^(${NPX_BEFORE_NAME}${PACKAGE}@)(${VERSION})$`);
+/** The release a plain invocation is pinned to, where it is the pinned published way (U2). */
+function pinnedOf(invocation) {
+    const version = PINNED.exec(invocation)?.[2];
+    return version !== undefined && plainVersion(version) !== undefined ? version : undefined;
+}
+/** The releases agentwhy's hooks in these settings are pinned to, one per command, in the order they are written (U2). */
+export function pinnedVersions(settings) {
+    return commandsIn(settings).flatMap((command) => {
+        const plain = plainRun(command);
+        const version = plain === undefined ? undefined : pinnedOf(plain.invocation);
+        return version === undefined ? [] : [version];
+    });
+}
+/**
+ * The settings with every agentwhy hook pinned to a release older than `version` pinned to `version` instead (U7): the
+ * version in its invocation replaced, everything after the subcommand kept. A newer pin, an unpinned hook, one in any
+ * other form and every other key are left as they are.
+ */
+export function withHooksPinnedTo(settings, version) {
+    const hooks = settings[HOOK_SETTINGS.hooks];
+    if (!isJsonObject(hooks) || plainVersion(version) === undefined)
+        return { settings, changed: [] };
+    const changed = [];
+    const next = withCommandsRewritten(hooks, (line, event) => {
+        const plain = plainRun(line);
+        const from = plain === undefined ? undefined : pinnedOf(plain.invocation);
+        if (plain === undefined || from === undefined || !isOlder(from, version))
+            return undefined;
+        changed.push({ hook: plain.hook, event, from });
+        const invocation = plain.invocation.replace(PINNED, (_whole, head) => head + version);
+        return invocation + line.slice(line.indexOf(plain.invocation) + plain.invocation.length);
+    });
+    return { settings: changed.length === 0 ? settings : { ...settings, [HOOK_SETTINGS.hooks]: next }, changed };
+}
+/**
+ * The hooks with each command line `rewrite` gives a new line for replaced, and every other command, entry and key as it
+ * was - whatever shape they are in. The walk `withHooksPinnedTo` and `withHooksReading` share; they differ in one line.
+ */
+function withCommandsRewritten(hooks, rewrite) {
+    const next = {};
+    for (const [event, list] of Object.entries(hooks)) {
+        next[event] = !Array.isArray(list) ? list : list.map((entry) => {
+            if (!isJsonObject(entry) || !Array.isArray(entry[HOOK_SETTINGS.commands]))
+                return entry;
+            return {
+                ...entry,
+                [HOOK_SETTINGS.commands]: entry[HOOK_SETTINGS.commands].map((command) => {
+                    if (!isJsonObject(command) || typeof command[HOOK_SETTINGS.command] !== 'string')
+                        return command;
+                    const line = rewrite(command[HOOK_SETTINGS.command], event);
+                    return line === undefined ? command : { ...command, [HOOK_SETTINGS.command]: line };
+                }),
+            };
+        });
+    }
+    return next;
+}
+/** The settings with the entries added, each as its own item of its event's list. Nothing else is touched. */
+export function withHookEntries(settings, entries) {
+    const hooks = isJsonObject(settings[HOOK_SETTINGS.hooks]) ? { ...settings[HOOK_SETTINGS.hooks] } : {};
+    for (const entry of entries) {
+        const list = Array.isArray(hooks[entry.event]) ? [...hooks[entry.event]] : [];
+        list.push({
+            ...(entry.matcher === undefined ? {} : { [HOOK_SETTINGS.matcher]: entry.matcher }),
+            [HOOK_SETTINGS.commands]: [{ [HOOK_SETTINGS.type]: HOOK_SETTINGS.commandType, [HOOK_SETTINGS.command]: entry.command }],
+        });
+        hooks[entry.event] = list;
+    }
+    return { ...settings, [HOOK_SETTINGS.hooks]: hooks };
+}
+/**
+ * The settings without the commands that run agentwhy's hooks - all of them, or only those named in `only` (R8, R4b). A matcher entry left with no command is dropped, an
+ * event left with no entry is dropped, and `hooks` left empty is dropped; every other key and hook stays as it was.
+ */
+export function withoutAgentwhyHooks(settings, invoke, only) {
+    const hooks = settings[HOOK_SETTINGS.hooks];
+    if (!isJsonObject(hooks))
+        return { settings, removed: 0 };
+    let removed = 0;
+    const kept = {};
+    for (const [event, list] of Object.entries(hooks)) {
+        if (!Array.isArray(list)) {
+            kept[event] = list;
+            continue;
+        }
+        const entries = list.flatMap((entry) => {
+            if (!isJsonObject(entry) || !Array.isArray(entry[HOOK_SETTINGS.commands]))
+                return [entry];
+            const commands = entry[HOOK_SETTINGS.commands].filter((command) => {
+                const hook = isJsonObject(command) && typeof command[HOOK_SETTINGS.command] === 'string'
+                    ? hookRun(command[HOOK_SETTINGS.command], invoke)
+                    : undefined;
+                // `--remove` with a hook named takes out that one; with none, every hook that runs agentwhy (R4b).
+                const runs = hook !== undefined && (only === undefined || only.includes(hook));
+                if (runs)
+                    removed += 1;
+                return !runs;
+            });
+            return commands.length === 0 ? [] : [{ ...entry, [HOOK_SETTINGS.commands]: commands }];
+        });
+        if (entries.length > 0)
+            kept[event] = entries;
+    }
+    const { [HOOK_SETTINGS.hooks]: _dropped, ...rest } = settings;
+    return { settings: Object.keys(kept).length === 0 ? rest : { ...rest, [HOOK_SETTINGS.hooks]: kept }, removed };
+}
+const SETTINGS_FLAG = /\s--settings(?:\s+|=)("[^"]*"|'[^']*'|\S+)/;
+export function rulesReadBy(command) {
+    if (/\s--policy(?:\s|=)/.test(command))
+        return 'policy';
+    const named = SETTINGS_FLAG.exec(command)?.[1]?.replace(/^["']|["']$/g, '');
+    if (named === undefined)
+        return 'default';
+    if (named.endsWith(`/${SETTINGS_FILES.directory}/${SETTINGS_FILES.local}`))
+        return 'local';
+    if (named.endsWith(`/${SETTINGS_FILES.directory}/${SETTINGS_FILES.shared}`))
+        return 'shared';
+    return 'other';
+}
+/** What each of agentwhy's hooks in this settings object reads; a hook it does not run is absent. */
+export function rulesReadByHooks(settings, invoke) {
+    const found = new Map();
+    for (const command of commandsIn(settings)) {
+        const hook = hookRun(command, invoke);
+        if (hook !== undefined && !found.has(hook))
+            found.set(hook, rulesReadBy(command));
+    }
+    return found;
+}
+/**
+ * The settings with every agentwhy hook command pointed at `rules` (R6, R4d): the `--settings` it had is replaced, or
+ * added where it had none. A command given a policy file is left alone - a policy is a choice somebody made on
+ * purpose, and `watch` takes one or the other, not both. Returns the hooks it changed; nothing else is touched.
+ */
+export function withHooksReading(settings, rules, invoke) {
+    const hooks = settings[HOOK_SETTINGS.hooks];
+    if (!isJsonObject(hooks))
+        return { settings, changed: [] };
+    const flag = ` --settings "${HOOK_SETTINGS.projectDirectory}/${SETTINGS_FILES.directory}/${SETTINGS_FILES[rules]}"`;
+    const changed = new Set();
+    const next = withCommandsRewritten(hooks, (line) => {
+        const hook = hookRun(line, invoke);
+        const reads = rulesReadBy(line);
+        if (hook === undefined || reads === rules || reads === 'policy')
+            return undefined;
+        changed.add(hook);
+        return line.replace(SETTINGS_FLAG, '') + flag;
+    });
+    return { settings: changed.size === 0 ? settings : { ...settings, [HOOK_SETTINGS.hooks]: next }, changed: [...changed] };
+}
+function commandsIn(settings) {
+    const hooks = settings[HOOK_SETTINGS.hooks];
+    if (!isJsonObject(hooks))
+        return [];
+    return Object.values(hooks).flatMap((list) => commandsInList(list));
+}
+/** Every command one event's list holds, whatever else is in the entries around it. */
+function commandsInList(list) {
+    return Array.isArray(list)
+        ? list.flatMap((entry) => isJsonObject(entry) && Array.isArray(entry[HOOK_SETTINGS.commands])
+            ? entry[HOOK_SETTINGS.commands].flatMap((command) => isJsonObject(command) && typeof command[HOOK_SETTINGS.command] === 'string' ? [command[HOOK_SETTINGS.command]] : [])
+            : [])
+        : [];
+}

package/dist/adapter/codex/contract/actions.js

@@ -0,0 +1,69 @@
+/**
+ * What an agent's code did, as `event_msg/item_completed` records it: one typed item per action, joined to its turn by
+ * `turn_id` and to its agent by `thread_id` in every measured item (§2.3, 2,344 items; §2.8, 33). An item holds both what
+ * was asked and what came back, so no join between a call and its result is made (X6). No id joins an item to the
+ * `exec` cell that ran it (§2.3, §2.8): an item is attributed to its turn and agent, never to a cell (X14).
+ */
+export const ITEM_EVENT = {
+    type: 'item_completed',
+    turnId: 'turn_id',
+    threadId: 'thread_id',
+    item: 'item',
+};
+export const ITEM = {
+    type: 'type',
+    id: 'id',
+    status: 'status',
+};
+/**
+ * `status` values: `completed` and `failed` (§2.3, every action item type; §2.8). An item recorded without one is
+ * recorded as completed by its event, `item_completed` - measured on `ImageView`, the one such action item (§2.8).
+ */
+export const ITEM_STATUSES = { completed: 'completed', failed: 'failed' };
+/** Action items the contract names (X6). `Extension` and `ImageView` are named and have no profile: unknown tools. */
+export const ACTION_ITEMS = {
+    command: 'CommandExecution',
+    fileChange: 'FileChange',
+    mcp: 'McpToolCall',
+    webSearch: 'WebSearch',
+    extension: 'Extension',
+    imageView: 'ImageView',
+};
+/**
+ * `CommandExecution` (§2.3, 206; §2.8, 8): `command` is `[shell, flag, line]` in all of them; `aggregated_output` is what
+ * the process printed, `stdout` included and `stderr` empty in every measured item. Recording it is not delivering it
+ * (X10): the model is handed only what the cell emits (§2.8).
+ */
+export const COMMAND = {
+    command: 'command',
+    workingDirectory: 'cwd',
+    exitCode: 'exit_code',
+    output: 'aggregated_output',
+};
+/** X7: `zsh` measured (206 of 206; 8 of 8); `bash` and `sh` expected and listed by the specification (XB8). */
+export const SHELLS = ['zsh', 'bash', 'sh'];
+/** `-lc` measured in every item; `-c` listed by X7. */
+export const SHELL_FLAGS = ['-lc', '-c'];
+/**
+ * Codex's own words where it cut the middle out of a recorded output (XB5, §2.8: 1 of 8, at 1,048,606 characters).
+ * Present, the output is `partial`. Absent, it is still not taken to be whole: one build at one cap was measured.
+ */
+export const OMISSION_NOTICE = /\.\.\. \d+ bytes omitted \.\.\./;
+/**
+ * `FileChange` (§2.3, 221; §2.8, 1): `changes` keyed by path, each with `type` `add` (and `content`), `update` (and
+ * `unified_diff`) or `delete`, and an optional `move_path`.
+ */
+export const FILE_CHANGE = {
+    changes: 'changes',
+    kind: 'type',
+    content: 'content',
+    diff: 'unified_diff',
+    movePath: 'move_path',
+};
+export const CHANGE_KINDS = { add: 'add', update: 'update', delete: 'delete' };
+/** `McpToolCall` (§2.3, 121): its result's text fields are not measured, so its output is read as raw text of unknown completeness. */
+export const MCP = { server: 'server', tool: 'tool', arguments: 'arguments', result: 'result' };
+/** `WebSearch` (§2.3, 59): `results[]` fields are not measured (X10); the action is kept as raw input. */
+export const WEB_SEARCH = { action: 'action', results: 'results' };
+/** `ImageView` (§2.8, 1): the image it opened. Written only when the view succeeded; a failed view writes no item. */
+export const IMAGE_VIEW = { path: 'path' };

package/dist/adapter/codex/contract/assumptions.js

@@ -0,0 +1,55 @@
+/** Evidence and limits of the contract; support for one subject never grants support for another. */
+export const ASSUMPTIONS = {
+    recognition: {
+        rule: 'The first line is session_meta with an object payload and string id.',
+        measured: '70 of 70 files on 2026-09-29 (spec §2.7) and 7 of 7 terminal sessions (§2.8); recognition is independent of the filename.',
+    },
+    identity: {
+        rule: 'Only the first metadata id owns the file. An id held by several files joins none.',
+        measured: '68 unique owners and one duplicate id held by two files on 2026-09-29.',
+    },
+    project: {
+        rule: 'Use the recorded cwd of session_meta and of every turn_context; several are ambiguous, missing data explicit.',
+        measured: 'One distinct cwd per file in all 70 measured files; no general invariant is inferred.',
+    },
+    tree: {
+        rule: 'Join recorded parent_thread_id only through unique owners; no timestamp or folder join.',
+        measured: '25 child files found their parents in the 2026-09-29 corpus; missing parents and cycles remain unresolved.',
+    },
+    history: {
+        rule: 'Recognise paginated and legacy; preserve unknown modes as a gap.',
+        measured: '65 paginated and 5 legacy files by first metadata on 2026-09-29; 7 paginated terminal sessions (§2.8).',
+    },
+    actions: {
+        rule: 'One event per action item, by item.id; a command line only from [shell, -lc|-c, line]; parsed_cmd never read.',
+        measured: 'Item joins to turn and thread in every item (§2.3, §2.8). Refused attempts and failed image views leave no item (XB7, XB1), so the action stream is never whole.',
+    },
+    access: {
+        rule: 'A status says a process ran, never what it reached: only a completed write, or one reader that exited 0, or a line of output naming the file.',
+        measured: 'A failed cat records its diagnostic in stdout with exit 1 (§2.8); exit codes of other programs are not profiled.',
+    },
+    delivery: {
+        rule: 'The model receives the cell output as a whole, joined to its cell by call_id and to no item; recorded execution output is not delivered by itself.',
+        measured: 'XB5 on 0.157.0: forwarded markers are in the cell output, withheld ones only in the item; outputs over 1 MiB are cut with a textual notice only.',
+    },
+    messages: {
+        rule: 'Assistant response messages are canonical; AgentMessage items join them by id; task_complete joins the one final answer of its turn.',
+        measured: 'XB10 on 0.157.0 paginated: 15 of 15 id joins, 6 of 6 completion copies, 2 identical texts under distinct ids. Other builds and legacy are unmeasured.',
+    },
+    delegations: {
+        rule: 'spawn_agent joins its agent through SubAgentActivity started by call_id; later words through interacted; reports by agent_path, a name.',
+        measured: 'One delegation in each corpus (§2.4, §2.7): provisional, XB4 open.',
+    },
+    reviews: {
+        rule: 'A guardian thread is a review of the parent turn its turns name by root_turn_id; its verdicts are JSON with outcome allow.',
+        measured: '52 root-turn references all present (§2.7); 141 of 141 verdicts allow (§2.4). No refusal seen (XB1), no reviewer action (XB9).',
+    },
+    permissions: {
+        rule: 'turn_context records approval, reviewer, sandbox and file-system scopes: recorded settings, not a policy and not a verdict.',
+        measured: '469 turns (§2.5), 7 (§2.8). Every entry allows; a granular approval policy is not read.',
+    },
+    capabilities: {
+        rule: 'Capabilities come from the measured matrix by build and history mode; a recognised header grants none.',
+        measured: 'XB2, XB5, XB7, XB10 answered for 0.157.0 terminal paginated only; XB1 in part; XB3, XB4, XB6, XB8, XB9 open.',
+    },
+};

package/dist/adapter/codex/contract/capabilities.js

@@ -0,0 +1,24 @@
+/**
+ * `codex exec` 0.157.0, `paginated` (§2.8): XB5 and XB10 answered; XB7 found actions and refused attempts that leave no
+ * item, so the action stream is never all of it; XB1 found no typed refusal.
+ */
+export const MEASURED_PROFILES = [
+    {
+        builds: ['0.157.0'],
+        historyModes: ['paginated'],
+        answers: { actions: 'absent', refusals: 'absent', 'own-words': 'supported', 'output-delivery': 'supported' },
+    },
+];
+/**
+ * Every other build of a known mode. `paginated`: items exist, but what escapes them and which message source is
+ * canonical are not measured for it. `legacy`: its cells are recorded and nothing they ran is (§2.3, XD4). No build has a
+ * typed refusal (§2.5, §2.8).
+ */
+export const UNMEASURED_PROFILES = {
+    paginated: { actions: 'absent', refusals: 'absent', 'own-words': 'unmeasured', 'output-delivery': 'unmeasured' },
+    legacy: { actions: 'absent', access: 'absent', refusals: 'absent', 'own-words': 'unmeasured', 'output-delivery': 'unmeasured' },
+};
+/** A history mode the contract does not list: nothing about it is known (X23, X24). */
+export const UNKNOWN_MODE_ANSWERS = {
+    actions: 'unmeasured', access: 'unmeasured', refusals: 'unmeasured', 'own-words': 'unmeasured', 'output-delivery': 'unmeasured',
+};

package/dist/adapter/codex/contract/delegations.js

@@ -0,0 +1,30 @@
+/**
+ * An agent the agent chose to start, and what it said to it later (X15-X18; §2.4). Measured on one delegation only
+ * (§2.4, §2.7): every join here is by id and leaves the relation unresolved where it breaks. XB4 remains open, so these
+ * joins are read and never advertised as measured beyond that sample.
+ */
+export const DELEGATION_TOOLS = { spawn: 'spawn_agent', send: 'send_message', followUp: 'followup_task' };
+/** `spawn_agent` arguments (a JSON string): `task_name` and `message` (§2.4). */
+export const SPAWN_ARGUMENTS = { name: 'task_name', message: 'message' };
+/** The `SubAgentActivity` item: `started` answers `spawn_agent`, `interacted` a later call, by `id` = `call_id` (§2.4). */
+export const ACTIVITY = {
+    type: 'SubAgentActivity',
+    kind: 'kind',
+    agentThreadId: 'agent_thread_id',
+    kinds: { started: 'started', interacted: 'interacted', completed: 'completed' },
+};
+/** A started agent's own first `session_meta`: `source.subagent.thread_spawn` (§2.4). */
+export const THREAD_SPAWN = {
+    source: 'source',
+    subagent: 'subagent',
+    threadSpawn: 'thread_spawn',
+    parentId: 'parent_thread_id',
+    depth: 'depth',
+    agentPath: 'agent_path',
+    role: 'agent_role',
+};
+/**
+ * `response_item/agent_message` between agents (§2.4): `author` is an `agent_path` - a name, never an id (X18) - and
+ * `content` the words.
+ */
+export const AGENT_MESSAGE = { author: 'author', recipient: 'recipient', content: 'content' };

package/dist/adapter/codex/contract/deliveries.js

@@ -0,0 +1,25 @@
+/**
+ * What the model is handed (XB5, §2.8). The model writes JavaScript into the `exec` tool; the cell's own output,
+ * `custom_tool_call_output.output`, is the one thing of it the model receives - a string, or parts whose text is under
+ * `input_text` - and it joins its cell by `call_id` (1,250 of 1,250; 17 of 17). No id joins it to the items the cell's
+ * code produced, so what it carries is attributed to no action (X10, X14).
+ *
+ * A direct call is a `function_call`, joined to its `function_call_output` by `call_id` (88 of 88, §2.3); where an item's
+ * `id` equals that `call_id` (59 `McpToolCall` items), the item is the action and the output its delivery.
+ */
+export const CODE_CELL = {
+    tool: 'exec',
+    name: 'name',
+    code: 'input',
+    callId: 'call_id',
+    output: 'output',
+    partType: 'type',
+    partText: 'text',
+    textPart: 'input_text',
+};
+export const FUNCTION_CALL = {
+    name: 'name',
+    callId: 'call_id',
+    arguments: 'arguments',
+    output: 'output',
+};

package/dist/adapter/codex/contract/envelope.js

@@ -0,0 +1,33 @@
+/**
+ * The line envelope: `{timestamp, type, payload}`, with `ordinal` on most lines (spec §2.1, 66 files; §2.7, 70; §2.8, 7).
+ * Only top-level lines are records (X13): a `compacted` line's nested copies are none.
+ */
+export const ENVELOPE = {
+    type: 'type',
+    payload: 'payload',
+    /** When the line was written: display only, never an order or a join (X12, architecture invariant 3). */
+    recordedAt: 'timestamp',
+    ordinal: 'ordinal',
+    /** The discriminator inside a `payload`. */
+    payloadType: 'type',
+};
+/** Line types, as `type` spells them (§2.2). */
+export const LINE_TYPES = {
+    sessionMeta: 'session_meta',
+    turnContext: 'turn_context',
+    responseItem: 'response_item',
+    event: 'event_msg',
+    /** Copies of earlier lines (X13): never records. */
+    compacted: 'compacted',
+    /** Instructions and environment given to the model; no action and no words of the agent. */
+    worldState: 'world_state',
+    /** Usage; its `root_turn_id` names a reviewed turn (§2.2). */
+    tokenUsage: 'token_usage_record',
+    interAgentMetadata: 'inter_agent_communication_metadata',
+};
+/** Line types that carry nothing the report reads: read as known, never as unknown. */
+export const PASSIVE_LINE_TYPES = [LINE_TYPES.compacted, LINE_TYPES.worldState, LINE_TYPES.interAgentMetadata];
+/** `event_msg` payload types that carry nothing the report reads (§2.2). */
+export const PASSIVE_EVENTS = ['token_count', 'thread_settings_applied', 'error'];
+/** `event_msg` payload types only `legacy` files wrote (§2.2: 6 and 9): known labels whose mapping is not measured. */
+export const LEGACY_EVENTS = ['patch_apply_end', 'web_search_end'];

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

@@ -0,0 +1,14 @@
+/**
+ * A command a `PreToolUse` hook refused (`codex-blocks-too` CKB3, CKB7, CKB11): it never runs, so no item records it, and
+ * the one trace is text in the code cell's output - "Script error:\nCommand blocked by PreToolUse hook: <reason>.
+ * Command: <line>". Measured on 0.159.2 (the terminal app and `codex exec`) and `codex exec` 0.155.0-alpha.16.3. No field
+ * types it (XB1): only a reason agentwhy wrote itself is read as a refusal, since its words are agentwhy's and not Codex's.
+ */
+export const HOOK_REFUSAL = {
+    /** Codex's words before a hook's reason. */
+    blocked: 'Command blocked by PreToolUse hook: ',
+    /** Codex's words between the reason and the refused line. */
+    command: '. Command: ',
+    /** The kind a refusal read from agentwhy's own reason is recorded with. */
+    denialKind: 'agentwhy refuse',
+};

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

@@ -0,0 +1,46 @@
+/**
+ * A project's Codex hooks (`specs/2026-09-30-codex-blocks-too.md` CKB4): `<project>/.codex/hooks.json`, in the shape
+ * `{"hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "…"}]}]}}`. Measured on 0.159.2:
+ * read only in a project Codex trusts, and a hook in it runs only once a person has approved it in Codex (CKB5).
+ */
+export const PROJECT_HOOKS = {
+    directory: '.codex',
+    file: 'hooks.json',
+    hooks: 'hooks',
+    matcher: 'matcher',
+    /** An entry's list of commands, under the same key as the file's top-level object. */
+    commands: 'hooks',
+    type: 'type',
+    commandType: 'command',
+    command: 'command',
+};
+/**
+ * What a `PreToolUse` hook is handed for a shell command (CKB2), measured on 0.159.2: `hook_event_name` `PreToolUse`,
+ * `tool_name` `Bash`, `tool_input` `{"command": "<line>"}` - the line alone, not the rollout's `[shell, flag, line]` - and
+ * `cwd`, the session's folder, which can lie below the project (CKB6). The input also holds `model`, `permission_mode`,
+ * `session_id`, `tool_use_id`, `transcript_path` and `turn_id`, none of which `refuse` reads. Exit 2 with a reason on
+ * standard error refuses the call (CKB3).
+ */
+export const PRE_TOOL_USE = {
+    event: 'PreToolUse',
+    fields: {
+        event: 'hook_event_name',
+        toolName: 'tool_name',
+        toolInput: 'tool_input',
+        /** Inside `tool_input` for the shell tool. */
+        command: 'command',
+        cwd: 'cwd',
+    },
+    /** The shell tool, and the matcher a hook for it is written with. */
+    shellTool: 'Bash',
+};
+/** A completed Codex turn, measured with `codex exec` 0.159.2. Its transcript path can be absent (ephemeral runs). */
+export const STOP = {
+    event: 'Stop',
+    fields: {
+        event: 'hook_event_name',
+        active: 'stop_hook_active',
+        turnId: 'turn_id',
+        transcriptPath: 'transcript_path',
+    },
+};

package/dist/adapter/codex/contract/messages.js

@@ -0,0 +1,47 @@
+/**
+ * The agent's own words and the words it was given (X31; XB10, §2.8). Measured for `codex exec` 0.157.0 `paginated`:
+ * assistant text is `response_item/message` with role `assistant`, content `output_text` and a `phase`; an `AgentMessage`
+ * item with the same `id` is a copy of it (15 of 15); `task_complete.last_agent_message` is a copy of the turn's final
+ * answer, with no id of its own (6 of 6). Two messages with identical text and different ids are two (2 pairs).
+ */
+export const RESPONSE_ITEMS = {
+    message: 'message',
+    reasoning: 'reasoning',
+    codeCell: 'custom_tool_call',
+    codeCellOutput: 'custom_tool_call_output',
+    functionCall: 'function_call',
+    functionOutput: 'function_call_output',
+    agentMessage: 'agent_message',
+    compaction: 'compaction',
+};
+export const MESSAGE = {
+    id: 'id',
+    role: 'role',
+    content: 'content',
+    phase: 'phase',
+    blockType: 'type',
+    blockText: 'text',
+};
+export const ROLES = { assistant: 'assistant', user: 'user', developer: 'developer' };
+/** Content block types: `output_text` on assistant messages, `input_text` on the others (§2.2, §2.8). */
+export const TEXT_BLOCKS = { said: 'output_text', given: 'input_text' };
+/** `phase` on assistant messages and `AgentMessage` items (§2.8): what the core calls a channel. */
+export const PHASES = { commentary: 'commentary', final_answer: 'final' };
+/** Message items (§2.3): copies of response records, joined by `id` where one is (§2.8). */
+export const MESSAGE_ITEMS = {
+    agent: 'AgentMessage',
+    user: 'UserMessage',
+    reasoning: 'Reasoning',
+    compaction: 'ContextCompaction',
+    functionOutput: 'FunctionCallOutput',
+};
+/** An `AgentMessage` or `UserMessage` item's content blocks: `Text` and `text` (§2.8). */
+export const ITEM_TEXT_BLOCKS = ['Text', 'text'];
+/**
+ * Reasoning: `encrypted_content` on every measured record, and readable `summary[].text` on some (§2.2: 163 parts); none
+ * readable in §2.8. A `Reasoning` item joins its record by `id` (1 of 1) with its own `summary_text` and `raw_content`.
+ */
+export const REASONING = { encrypted: 'encrypted_content', summary: 'summary', summaryText: 'text' };
+export const REASONING_ITEM = { summary: 'summary_text', raw: 'raw_content' };
+/** Event copies the editor builds of §2.2 wrote (22 and 34 lines); no source rule is measured for them. */
+export const EVENT_MESSAGES = { user: 'user_message', agent: 'agent_message', text: 'message' };