@agentwhy/cli 0.1.0 → 0.2.1

package/dist/adapter/claude-code/events/delegation-index.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseJsonObject } from '../../../shared/json.js';
 import { META_FIELD } from '../contract/fields.js';
 export function readDelegationIndex(text) {

package/dist/adapter/claude-code/events/transcript-scan.js

@@ -1,5 +1,5 @@
 import { isJsonObject } from '../../../shared/json.js';
-import { isKnownDenialKind, RULE_REFUSED_READ, RULE_REFUSED_READ_KIND } from '../contract/denials.js';
+import { DENIAL_SOURCE, isKnownDenialKind, RULE_REFUSED_READ, RULE_REFUSED_READ_KIND } from '../contract/denials.js';
 import { AGENT_TOOL, HANDBACK_TOOL, FIELDS, TEXT_BLOCK_TYPE, THINKING_BLOCK_TYPE, TOOL_RESULT_BLOCK_TYPE } from '../contract/fields.js';
 import { ASSISTANT_LINE_TYPE, USER_LINE_TYPE } from '../contract/line-types.js';
 import { toolResultReferences } from '../contract/layout.js';
@@ -121,9 +121,10 @@ export function delegationTextIn(call) {
 export function resultsIn(record) {
     const payload = record[FIELDS.toolUseResult];
     const denialValue = record[FIELDS.denialKind];
-    const denial = typeof denialValue === 'string'
-        ? { kind: denialValue, recognised: isKnownDenialKind(denialValue) }
-        : undefined;
+    // A value the contract knows says who refused (WS1); any other names nobody, and stays unknown.
+    const denial = typeof denialValue !== 'string' ? undefined
+        : isKnownDenialKind(denialValue) ? { kind: denialValue, recognised: true, source: DENIAL_SOURCE[denialValue] }
+            : { kind: denialValue, recognised: false };
     const blocks = contentBlocks(record).filter((block) => block[FIELDS.blockType] === TOOL_RESULT_BLOCK_TYPE);
     // The marker sits on the record, not on a block, so it names a call only while the record holds exactly one.
     const attributable = blocks.length === 1;
@@ -143,7 +144,7 @@ export function resultsIn(record) {
                 ...(denial !== undefined && attributable
                     ? { denial }
                     : refusedByRule
-                        ? { denial: { kind: RULE_REFUSED_READ_KIND, recognised: true } }
+                        ? { denial: { kind: RULE_REFUSED_READ_KIND, recognised: true, source: DENIAL_SOURCE[RULE_REFUSED_READ_KIND] } }
                         : {}),
                 ...(launched && attributable ? { launchNotice: true } : {}),
                 spilledFiles: spilledFilesIn(block[FIELDS.blockContent], payload),

package/dist/adapter/claude-code/hooks/hook-output.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { HOOK_OUTPUT, TERMINAL } from '../contract/hooks.js';
 /** C0 and C1 control characters, and DEL: any of them in the words would take the sequence outside the allowlist. */
 const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;

package/dist/adapter/claude-code/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/claude-code/hooks/stop-input.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { STOP, SUBAGENT_STOP } from '../contract/hooks.js';
 import { parseJsonObject } from '../../../shared/json.js';
 export function parseStopInput(text) {

package/dist/adapter/claude-code/hooks/subagent-stop-input.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { SUBAGENT_STOP } from '../contract/hooks.js';
 import { parseJsonObject } from '../../../shared/json.js';
 /** Reads the text a hook was given on standard input. Never throws: an input it cannot use is a named answer. */
@@ -15,12 +17,14 @@ export function parseSubagentStopInput(text) {
     }
     const lastMessage = input[fields.lastMessage];
     const sessionId = input[fields.sessionId];
+    const agentTranscriptPath = input[fields.agentTranscriptPath];
     return {
         agent: {
             transcriptPath,
             agentId,
             ...(typeof lastMessage === 'string' ? { lastMessage } : {}),
             ...(typeof sessionId === 'string' && sessionId !== '' ? { sessionId } : {}),
+            ...(typeof agentTranscriptPath === 'string' && agentTranscriptPath !== '' ? { agentTranscriptPath } : {}),
         },
     };
 }

package/dist/adapter/claude-code/probe/claude-code-probe.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { FileAccessError } from '../../../ports/file-access-error.js';
 import { toLabel } from '../../../shared/label.js';
 import { CONTRACT_VERSION, VERIFIED_AGAINST } from '../contract/version.js';

package/dist/adapter/claude-code/probe/collectors/agent-tool-input-key-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { Counter } from '../../../../shared/counter.js';
 import { isJsonObject } from '../../../../shared/json.js';
 import { toLabel } from '../../../../shared/label.js';

package/dist/adapter/claude-code/probe/collectors/denial-kind-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { byString } from '../../../../shared/compare.js';
 import { Counter } from '../../../../shared/counter.js';
 import { toLabel } from '../../../../shared/label.js';

package/dist/adapter/claude-code/probe/collectors/denied-call-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { FIELDS } from '../../contract/fields.js';
 export class DeniedCallCollector {
     #deniedCalls = 0;

package/dist/adapter/claude-code/probe/collectors/identifier-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { identifierMatches } from '../../contract/identifiers.js';
 export class IdentifierCollector {
     #toolUseIds = new Set();

package/dist/adapter/claude-code/probe/collectors/line-type-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { byString } from '../../../../shared/compare.js';
 import { Counter } from '../../../../shared/counter.js';
 import { toLabel } from '../../../../shared/label.js';

package/dist/adapter/claude-code/probe/collectors/sidechain-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { FIELDS } from '../../contract/fields.js';
 export class SidechainCollector {
     #sidechain = { true: 0, false: 0, absent: 0, invalid: 0 };

package/dist/adapter/claude-code/probe/collectors/task-notification-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { AGENT_TOOL, FIELDS } from '../../contract/fields.js';
 import { USER_LINE_TYPE } from '../../contract/line-types.js';
 import { notificationsIn } from '../../contract/task-notifications.js';

package/dist/adapter/claude-code/probe/collectors/tool-result-reference-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { FIELDS, TOOL_RESULT_BLOCK_TYPE } from '../../contract/fields.js';
 import { toolResultReferences } from '../../contract/layout.js';
 import { contentBlocks } from '../transcript-line.js';

package/dist/adapter/claude-code/probe/collectors/tool-use-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { Counter } from '../../../../shared/counter.js';
 import { toLabel } from '../../../../shared/label.js';
 import { AGENT_TOOL, FIELDS } from '../../contract/fields.js';

package/dist/adapter/claude-code/probe/collectors/tool-version-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { Counter } from '../../../../shared/counter.js';
 import { toLabel } from '../../../../shared/label.js';
 import { FIELDS } from '../../contract/fields.js';

package/dist/adapter/claude-code/probe/collectors/top-level-key-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { Counter } from '../../../../shared/counter.js';
 import { toLabel } from '../../../../shared/label.js';
 export class TopLevelKeyCollector {

package/dist/adapter/claude-code/probe/collectors/unknown-line-type-key-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { byString } from '../../../../shared/compare.js';
 import { Counter } from '../../../../shared/counter.js';
 import { toLabel } from '../../../../shared/label.js';

package/dist/adapter/claude-code/probe/collectors/working-directory-collector.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { FIELDS } from '../../contract/fields.js';
 /**
  * How many different working directories a session's lines carry - the number, never the directories. A `cwd` is

package/dist/adapter/claude-code/probe/meta-tally.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { Counter } from '../../../shared/counter.js';
 import { parseJsonObject } from '../../../shared/json.js';
 import { toLabel } from '../../../shared/label.js';

package/dist/adapter/claude-code/probe/transcript-line.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { isJsonObject } from '../../../shared/json.js';
 import { FIELDS, TEXT_BLOCK_TYPE, TOOL_RESULT_BLOCK_TYPE, TOOL_USE_BLOCK_TYPE } from '../contract/fields.js';
 export function contentBlocks(line) {

package/dist/adapter/claude-code/probe/transcript-tally.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseJsonObject } from '../../../shared/json.js';
 import { DeniedCallCollector } from './collectors/denied-call-collector.js';
 import { IdentifierCollector } from './collectors/identifier-collector.js';

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { fileRulePathOf } from '../policy/deny-rules.js';
 import { isJsonObject } from '../../../shared/json.js';
 import { PERMISSIONS } from '../contract/settings.js';

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { isJsonObject } from '../../../shared/json.js';
 import { PACKAGE } from '../../../shared/package-name.js';
 import { isPlainInvocation, NPX_BEFORE_NAME, VERSION } from '../../../shared/plain-invocation.js';
@@ -75,6 +77,13 @@ function runningEvents(settings, invoke) {
  * 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.
  */
+/**
+ * The full command these settings run `refuse` with, whose own flags name the rules it reads
+ * (`2026-10-02-codex-approves-its-own-hook.md` AO5, AO6).
+ */
+export function refuseCommandIn(settings) {
+    return commandsIn(settings).find((command) => hookRun(command, undefined) === 'refuse');
+}
 export function installedHooks(settings, invoke) {
     const found = new Set();
     for (const command of commandsIn(settings)) {

package/dist/adapter/claude-code/settings/refuse-project.js

@@ -0,0 +1,99 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { dirname, isAbsolute, join } from 'node:path';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { parseJsonObject } from '../../../shared/json.js';
+import { SETTINGS_FILES } from '../contract/settings.js';
+import { refuseCommandIn } from './hook-entries.js';
+/** How far up from where a hook ran a project is looked for. */
+const MOST_FOLDERS_UP = 64;
+/**
+ * `2026-10-02-codex-approves-its-own-hook.md` AO5: the project for a Codex command or turn is the nearest folder, at or
+ * above `folder`, whose `.claude/settings.local.json` or `settings.json` runs agentwhy's `refuse` - the local file
+ * first, as `init` reads them. Codex runs agentwhy's check in the session's folder, which can lie below the project and
+ * names it nowhere (CKB6); the rules that block there are the project's own, so the project is the folder that holds
+ * them. A folder with a `.claude` of its own and no `refuse` does not stop the walk.
+ *
+ * The walk ends at the home directory, which is never a project (`which-project` V8; `codex-says-it-too` CXB6): a
+ * `refuse` in the person's own `~/.claude/settings.json` would otherwise make every folder under home a project. One
+ * lookup for `refuse --codex`, the turn's rules (CX5) and whether a turn is watched (CX9), so the three never disagree.
+ */
+export async function refuseProjectAbove(files, folder, home) {
+    for (let at = folder, depth = 0; depth < MOST_FOLDERS_UP; depth += 1) {
+        if (at === home)
+            return undefined;
+        for (const file of [SETTINGS_FILES.local, SETTINGS_FILES.shared]) {
+            const settingsPath = join(at, SETTINGS_FILES.directory, file);
+            const settings = parseJsonObject((await textOf(files, settingsPath)) ?? '');
+            const command = settings === undefined ? undefined : refuseCommandIn(settings);
+            if (command !== undefined)
+                return { project: at, settingsPath, command };
+        }
+        const up = dirname(at);
+        if (up === at)
+            return undefined;
+        at = up;
+    }
+    return undefined;
+}
+const PROJECT_DIR = /^\$(?:\{CLAUDE_PROJECT_DIR\}|CLAUDE_PROJECT_DIR)/;
+/**
+ * One whole shell word, as a shell reads the value of a flag: quoted parts, escapes and bare characters joined into a
+ * single path. A command quotes only the part it has to - `--settings "$CLAUDE_PROJECT_DIR"/.claude/settings.json` -
+ * and reading the first quoted part alone would name the project's folder as the file to read.
+ */
+const WORD = '(?:"(?:[^"\\\\]|\\\\.)*"|\'[^\']*\'|\\\\.|[^\\s"\'])+';
+const SETTINGS_FLAG = new RegExp(`\\s--settings(?:\\s+|=)(${WORD})`);
+const POLICY_FLAG = new RegExp(`\\s--policy(?:\\s+|=)(${WORD})`);
+/**
+ * AO6: the rules the project's `refuse` reads, as its own command names them - a policy file, else a settings file,
+ * `$CLAUDE_PROJECT_DIR` and a relative path resolved against the project - or neither, which is the built-in list.
+ */
+export function refuseRulesOf(found) {
+    const policy = flagValue(found, POLICY_FLAG);
+    if (policy !== undefined)
+        return { policyPath: policy };
+    const settings = flagValue(found, SETTINGS_FLAG);
+    return settings === undefined ? {} : { settingsPath: settings };
+}
+function flagValue(found, flag) {
+    const word = flag.exec(found.command)?.[1];
+    if (word === undefined)
+        return undefined;
+    const raw = unquoted(word);
+    const resolved = PROJECT_DIR.test(raw) ? join(found.project, raw.replace(PROJECT_DIR, '.')) : raw;
+    return isAbsolute(resolved) ? resolved : join(found.project, resolved);
+}
+/** The word as the shell hands it to `refuse`: its quotes taken off and its `\` escapes resolved. */
+function unquoted(word) {
+    let out = '';
+    let quote;
+    for (let at = 0; at < word.length; at += 1) {
+        const char = word[at];
+        if (quote !== '\'' && char === '\\' && at + 1 < word.length) {
+            out += word[at + 1];
+            at += 1;
+            continue;
+        }
+        if (quote === undefined && (char === '"' || char === '\'')) {
+            quote = char;
+            continue;
+        }
+        if (char === quote) {
+            quote = undefined;
+            continue;
+        }
+        out += char;
+    }
+    return out;
+}
+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/contract/actions.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /** Evidence and limits of the contract; support for one subject never grants support for another. */
 export const ASSUMPTIONS = {
     recognition: {

package/dist/adapter/codex/contract/chat-folders.js

@@ -0,0 +1,19 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { isAbsolute, join, relative, sep } from 'node:path';
+/**
+ * Where the ChatGPT desktop app runs a chat that has no project: a folder it makes under the home directory, named after
+ * the day and the chat (`.ai/specs/2026-09-30-run-from-another-app.md` OAB5). Measured 2026-10-01: the recorded `cwd` of
+ * 7 of 153 rollouts, written by `originator` `codex_work_desktop` with `thread_source` `chatgpt_handoff`, was
+ * `~/Documents/Codex/<YYYY-MM-DD>/<chat>`. Other systems, and other versions of the app, are not measured.
+ */
+const CHAT_ROOT = ['Documents', 'Codex'];
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+/** Whether a folder is one the ChatGPT app made for a chat with no project: no project of the person's (V10b). */
+export function inChatFolder(path, home) {
+    const between = relative(join(home, ...CHAT_ROOT), path);
+    if (between === '' || isAbsolute(between) || between.startsWith('..'))
+        return false;
+    const [day, chat] = between.split(sep);
+    return day !== undefined && DAY.test(day) && chat !== undefined && chat !== '';
+}

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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.

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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>.

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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:
@@ -34,7 +36,11 @@ export const PRE_TOOL_USE = {
     /** 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). */
+/**
+ * A completed Codex turn, measured with `codex exec` 0.159.2. Its transcript path can be absent (ephemeral runs).
+ * `session_id`, `cwd` and `last_assistant_message` are documented beside the measured ones (`the-agent-tells-you` D18)
+ * and read where present: what `watch` says at the end of a Codex turn (`2026-10-02-codex-says-it-too.md` CX1).
+ */
 export const STOP = {
     event: 'Stop',
     fields: {
@@ -42,5 +48,49 @@ export const STOP = {
         active: 'stop_hook_active',
         turnId: 'turn_id',
         transcriptPath: 'transcript_path',
+        sessionId: 'session_id',
+        workingDirectory: 'cwd',
+        lastMessage: 'last_assistant_message',
     },
 };
+/**
+ * The person's own Codex hooks and their approval (`2026-10-02-codex-approves-its-own-hook.md` AOB1, measured
+ * 2026-10-02 on 0.159.3 and the VS Code extension's bundled 0.159.2): `~/.codex/hooks.json` has the project file's
+ * shape and belongs to Codex's user layer, read in every folder, trusted or not. A hook in it runs only with a matching
+ * approval in `~/.codex/config.toml`: a table
+ * `[hooks.state."<absolute path of hooks.json>:<event in snake case>:<group index>:<handler index>"]` whose
+ * `trusted_hash` equals the entry's current hash. The key is positional: an entry added or removed above another's
+ * shifts the keys below it (AOD3).
+ */
+export const USER_HOOKS = {
+    /** Under the home directory, beside the sessions root (`session.ts` CODEX_FOLDER). */
+    directory: '.codex',
+    file: 'hooks.json',
+    config: 'config.toml',
+    /** The keys of the table agentwhy reads and writes, under `hooks.state`. */
+    trustedHash: 'trusted_hash',
+    enabled: 'enabled',
+    /**
+     * How long Codex waits for agentwhy's check, named in each entry (AOD9): Codex's own default is 600 seconds (AOB8),
+     * which a hanging `npx` would hold every command for. Hashed as AOB10 measured.
+     */
+    timeoutSeconds: 30,
+};
+/**
+ * The hash Codex checks an approval against (AOB1): `sha256:` + SHA-256, hex, over compact JSON with keys sorted at
+ * every depth, of `{"event_name": <snake case>, "matcher": <the group's, omitted when none>, "hooks": [entry]}`, where
+ * the entry is `{"type": "command", "command": <as written>, "timeout": <600 unless the file names one, and at least
+ * 1>, "async": <false unless named>}` - the defaults written in, `statusMessage` only where the file names it, and
+ * `commandWindows` never (Codex normalizes it away before hashing). A `Stop` group's matcher is dropped before
+ * hashing; `PreToolUse` keeps its own (`matcher_pattern_for_event`). Events in snake case: `PreToolUse` is
+ * `pre_tool_use`, `Stop` is `stop`.
+ */
+export const HOOK_HASH = {
+    prefix: 'sha256:',
+    defaultTimeout: 600,
+    eventKeys: { PreToolUse: 'pre_tool_use', Stop: 'stop' },
+    /** The entry fields the hash reads, by the names the file uses. */
+    fields: { timeout: 'timeout', async: 'async', statusMessage: 'statusMessage' },
+    /** A field Codex hashes on context-emitting events, which the recipe was not measured over (AO2). */
+    unmeasured: ['additionalContextLimit'],
+};

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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`

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * The runtime permissions a `turn_context` records for its turn (§2.5; §2.8): recorded settings, never agentwhy's policy
  * and never a verdict on a path (X21, X22). Values outside these lists are kept out of the model and said as unknown.

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Codex's own reviewer (X19, X20; §2.4): a child thread whose `source.subagent.other` is `guardian`, started by Codex and
  * never by the agent. Its turns name the reviewed turn by `root_turn_id` (§2.7: 52 references, all present); its

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /** First-line discovery (§2.1, §2.7). Measured 2026-09-29; action and message semantics have separate gates. */
 export const SESSION = {
     lineType: 'type',
@@ -11,11 +13,35 @@ export const SESSION = {
     version: 'cli_version',
     /** A string for a person's session (`exec` in §2.8); an object `{subagent: …}` for a thread another started (§2.4). */
     source: 'source',
+    /** Which Codex app wrote the file: `codex-tui`, `codex_vscode`, `Codex Desktop`, `codex_work_desktop`, `codex_exec` (CXB3). */
+    originator: 'originator',
     filePrefix: 'rollout-',
     fileSuffix: '.jsonl',
 };
+/**
+ * Codex's own folder, under the home directory: where its terminal app, its VS Code extension and the desktop app keep
+ * their conversations (X1; `run-from-another-app` OAB4, OAB5). There, Codex is used on this computer (`codex-blocks-too`
+ * CK6). `$CODEX_HOME` is not measured (XB6).
+ */
+export const CODEX_FOLDER = ['.codex'];
 /** Where Codex keeps its rollouts, under the home directory (X1, §2.1). `$CODEX_HOME` is not measured (XB6). */
-export const SESSIONS_ROOT = ['.codex', 'sessions'];
+export const SESSIONS_ROOT = [...CODEX_FOLDER, 'sessions'];
+/**
+ * Who is reading a conversation, by its first line (`2026-10-02-codex-says-it-too.md` CXB3). Over 175 rollouts of
+ * 2026-10-02: every conversation a person held - in the terminal, VS Code, the Codex app and the ChatGPT app - had the
+ * `source` `vscode` (139); a scripted run `exec` (32); a thread another started an object (32). The terminal app is the
+ * one whose `originator` is `codex-tui`.
+ */
+export const READER = {
+    personSource: 'vscode',
+    terminalOriginator: 'codex-tui',
+    /**
+     * The desktop app's names (its plain and work builds). Measured 2026-10-02 on the maintainer's conversations: with
+     * a Stop block, the desktop app folds everything before the bubble into its "Worked for ..." row - a control run
+     * without agentwhy showed the same answer in the open - while VS Code's Codex folds nothing (CXB5's display note).
+     */
+    desktopOriginators: ['Codex Desktop', 'codex_work_desktop'],
+};
 export const HISTORY_MODES = ['paginated', 'legacy'];
 /**
  * Codex's own list of thread names, under the home directory: one JSON object a line, `{"id", "thread_name",
@@ -28,4 +54,6 @@ export const THREAD_NAMES = {
     file: ['.codex', 'session_index.jsonl'],
     id: 'id',
     name: 'thread_name',
+    /** When the line was written, ISO: a thread's earliest line is its first session (CXB5). */
+    updatedAt: 'updated_at',
 };

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * A turn and its boundaries (§2.2): `turn_context` opens one per turn with its `turn_id`; `task_started`,
  * `task_complete` and `turn_aborted` name it by the same id. Every item and response record carries it (§2.2, §2.8).

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * v1 (2026-09-29): first-line recognition and identity only, X1-X5, measured on 70 frozen files (spec §2.7).
  * v2 (2026-09-29): the records a report reads - turns and their permissions, action items, messages, the cell's output

package/dist/adapter/codex/discovery/codex-on-this-computer.js

@@ -0,0 +1,13 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { join } from 'node:path';
+import { isDirectory } from '../../../ports/directory-reader.js';
+import { CODEX_FOLDER } from '../contract/session.js';
+/**
+ * `codex-blocks-too` CK6, amended 2026-10-01: Codex is used on this computer where its own folder is in the home
+ * directory. A project set up before its first conversation has none to tell which AI will work in it; the computer
+ * does. A folder that cannot be looked at is not taken as Codex.
+ */
+export async function codexOnThisComputer(directories, home) {
+    return isDirectory(directories, join(home, ...CODEX_FOLDER));
+}

package/dist/adapter/codex/discovery/codex-project-catalogue.js

@@ -1,4 +1,4 @@
-import { FileAccessError } from '../../../ports/file-access-error.js';
+import { isDirectory } from '../../../ports/directory-reader.js';
 import { conversationsIn } from './codex-conversations.js';
 /**
  * The projects Codex keeps conversations for (`which-project.md` V9; X4): one per recorded `cwd` of a conversation's
@@ -30,20 +30,10 @@ export class CodexProjectCatalogue {
         const projects = await Promise.all([...byFolder].map(async ([path, folder]) => ({
             id: projectId(path),
             path,
-            exists: await this.#isDirectory(path),
+            folder: this.#dependencies.leaveAlone?.(path) === true ? 'not-looked' : (await isDirectory(this.#dependencies.directories, path)) ? 'there' : 'gone',
             conversations: folder.conversations,
             newest: { modifiedAt: folder.newest },
         })));
         return { projects: projects.sort((a, b) => b.newest.modifiedAt - a.newest.modifiedAt), unreadable };
     }
-    async #isDirectory(path) {
-        try {
-            return (await this.#dependencies.directories.kindOf(path)) === 'directory';
-        }
-        catch (error) {
-            if (!(error instanceof FileAccessError))
-                throw error;
-            return false;
-        }
-    }
 }

package/dist/adapter/codex/discovery/codex-session-catalogue.js

@@ -23,6 +23,7 @@ export class CodexSessionCatalogue {
             provider: 'codex',
         }))
             .sort((a, b) => b.modifiedAt - a.modifiedAt);
-        return { directory: sessionsRoot, found, searched: [{ provider: 'codex', directory: sessionsRoot, found }], sessions };
+        // The place searched is Codex's whole store, so not finding it is the store missing (R28, amended 2026-10-01).
+        return { directory: sessionsRoot, found, searched: [{ provider: 'codex', directory: sessionsRoot, found, ...(found ? {} : { store: 'missing' }) }], sessions };
     }
 }

package/dist/adapter/codex/discovery/codex-session-discovery.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { dirname, join, relative, resolve } from 'node:path';
 import { FileAccessError } from '../../../ports/file-access-error.js';
 import { SESSION } from '../contract/session.js';

package/dist/adapter/codex/discovery/session-owners.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /** An id owned by multiple files must resolve to none, regardless of traversal order (X3). */
 export const AMBIGUOUS = Symbol('held by more than one file');
 /** Used by runtime discovery and the reconnaissance probe, so they cannot choose different owners. */

package/dist/adapter/codex/events/action-items.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { basename } from 'node:path';
 import { isJsonObject } from '../../../shared/json.js';
 import { ACTION_ITEMS, CHANGE_KINDS, COMMAND, FILE_CHANGE, IMAGE_VIEW, ITEM, ITEM_STATUSES, MCP, OMISSION_NOTICE, SHELL_FLAGS, SHELLS, WEB_SEARCH, } from '../contract/actions.js';