@agentwhy/cli 0.3.0 → 0.3.1

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

@@ -23,16 +23,16 @@ export const ASSUMPTIONS = {
         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.',
+        rule: 'One event per action item, by item.id; a command line only from [shell, -lc|-c, line]; parsed_cmd never read. Where a record holds no command or change item, each command a cell wrote out as text is one event (X23a).',
+        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. The VS Code panel records no command item at all; 230 of 230 commands in 224 cells without items were written out as text (§2.11).',
     },
     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.',
+        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, and is the model\'s only where one cell return carries it whole and alone (§2.10).',
+        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. On 0.160.0 paginated, of 79 non-empty command outputs 15 reached a cell whole (13 of them uniquely), 36 left one long line, 11 a first token and 17 nothing.',
     },
     messages: {
         rule: 'Assistant response messages are canonical; AgentMessage items join them by id; task_complete joins the one final answer of its turn.',

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

@@ -19,6 +19,18 @@ export const CODE_CELL = {
     partText: 'text',
     textPart: 'input_text',
 };
+/**
+ * What a cell's code ran, read only where the record keeps no action item (XD4, amended 2026-10-05; §2.11): the VS Code
+ * panel's records hold none. The code calls `tools.exec_command({ cmd: "…" })`; its return to the model opens with one
+ * of two headers (the probe's vocabulary, measured on 0.157.0-0.160.0), the script's state, never the command's exit.
+ */
+export const CELL_COMMANDS = {
+    toolsObject: 'tools',
+    call: 'exec_command',
+    command: 'cmd',
+    completedHeader: 'Script completed',
+    failedHeader: 'Script failed',
+};
 export const FUNCTION_CALL = {
     name: 'name',
     callId: 'call_id',

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

@@ -29,14 +29,21 @@ export const ROLES = { assistant: 'assistant', user: 'user', developer: 'develop
 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). */
+/**
+ * Message items (§2.3): copies of response records, joined by `id` where one is (§2.8). A `HookPrompt` is what a hook
+ * asked of the model when it blocked a Stop: of 84, on 0.155-0.160 in the terminal, VS Code, the Codex app and the
+ * ChatGPT app, each came right after a `user` message with its `id` whose parts held its `fragments`' text (§2.12).
+ */
 export const MESSAGE_ITEMS = {
     agent: 'AgentMessage',
     user: 'UserMessage',
     reasoning: 'Reasoning',
     compaction: 'ContextCompaction',
     functionOutput: 'FunctionCallOutput',
+    hookPrompt: 'HookPrompt',
 };
+/** A `HookPrompt` item's words: one fragment per hook that asked, each with its `text` (§2.12). */
+export const HOOK_PROMPT = { fragments: 'fragments', text: 'text' };
 /** An `AgentMessage` or `UserMessage` item's content blocks: `Text` and `text` (§2.8). */
 export const ITEM_TEXT_BLOCKS = ['Text', 'text'];
 /**

package/dist/adapter/codex/events/cell-commands.js

@@ -0,0 +1,191 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { CELL_COMMANDS } from '../contract/deliveries.js';
+export function cellCommands(code) {
+    const commands = [];
+    let calls = 0;
+    let other = false;
+    for (const call of toolCalls(code)) {
+        if (call.name !== CELL_COMMANDS.call) {
+            other = true;
+            continue;
+        }
+        calls += 1;
+        const command = literalArgument(code, call.argumentsAt);
+        if (command !== undefined)
+            commands.push(command);
+    }
+    return { commands, unread: calls - commands.length, alone: calls === 1 && commands.length === 1 && !other };
+}
+/** Every `tools.<name>(` the code holds outside a string or a comment, with where its arguments start. */
+function toolCalls(code) {
+    const found = [];
+    const prefix = CELL_COMMANDS.toolsObject + '.';
+    for (let at = 0; at < code.length;) {
+        const skipped = skipQuoted(code, at);
+        if (skipped !== at) {
+            at = skipped;
+            continue;
+        }
+        if (code.startsWith(prefix, at) && !isWordCharacter(code[at - 1])) {
+            let end = at + prefix.length;
+            while (end < code.length && isWordCharacter(code[end]))
+                end += 1;
+            const name = code.slice(at + prefix.length, end);
+            let open = end;
+            while (open < code.length && /\s/.test(code[open] ?? ''))
+                open += 1;
+            if (name !== '' && code[open] === '(')
+                found.push({ name, argumentsAt: open + 1 });
+            at = end;
+            continue;
+        }
+        at += 1;
+    }
+    return found;
+}
+/**
+ * The command of `({ cmd: "…", … })` where it is written text: a quoted string, or a template with no `${`. Anything
+ * else - a variable, a call, a template that interpolates, an argument that is no object - is not read.
+ */
+function literalArgument(code, at) {
+    let position = skipSpace(code, at);
+    if (code[position] !== '{')
+        return undefined;
+    position += 1;
+    for (let depth = 1; position < code.length && depth > 0;) {
+        position = skipSpace(code, position);
+        const character = code[position];
+        if (character === '}') {
+            depth -= 1;
+            position += 1;
+            continue;
+        }
+        if (character === '{' || character === '[' || character === '(') {
+            depth += 1;
+            position += 1;
+            continue;
+        }
+        if (character === ']' || character === ')') {
+            depth -= 1;
+            position += 1;
+            continue;
+        }
+        if (depth === 1) {
+            const key = keyAt(code, position);
+            if (key !== undefined) {
+                const colon = skipSpace(code, key.end);
+                if (code[colon] === ':' && key.name === CELL_COMMANDS.command) {
+                    // The text must be the whole value: `"rg " + pattern` is built while the code runs.
+                    const value = skipSpace(code, colon + 1);
+                    const after = code[skipSpace(code, skipQuoted(code, value))];
+                    return after === ',' || after === '}' ? stringAt(code, value) : undefined;
+                }
+                position = key.end;
+                continue;
+            }
+        }
+        const skipped = skipQuoted(code, position);
+        position = skipped !== position ? skipped : position + 1;
+    }
+    return undefined;
+}
+/** A key of an object literal: a bare name, or a quoted one. */
+function keyAt(code, at) {
+    const quote = code[at];
+    if (quote === '"' || quote === "'") {
+        const end = skipQuoted(code, at);
+        const name = stringAt(code, at);
+        return name === undefined ? undefined : { name, end };
+    }
+    let end = at;
+    while (end < code.length && isWordCharacter(code[end]))
+        end += 1;
+    return end === at ? undefined : { name: code.slice(at, end), end };
+}
+/** The value of a string literal starting at `at`, or `undefined` where there is none, or it interpolates. */
+function stringAt(code, at) {
+    const quote = code[at];
+    if (quote !== '"' && quote !== "'" && quote !== '`')
+        return undefined;
+    let text = '';
+    for (let position = at + 1; position < code.length; position += 1) {
+        const character = code[position];
+        if (character === quote)
+            return text;
+        if (quote === '`' && character === '$' && code[position + 1] === '{')
+            return undefined;
+        if (quote !== '`' && character === '\n')
+            return undefined;
+        if (character !== '\\') {
+            text += character;
+            continue;
+        }
+        const escaped = escapeAt(code, position);
+        if (escaped === undefined)
+            return undefined;
+        text += escaped.text;
+        position = escaped.end - 1;
+    }
+    return undefined;
+}
+/** One escape of a JavaScript string, as the language reads it: `\n`, `é`, `\x41`, a line continuation, `\q` as `q`. */
+function escapeAt(code, at) {
+    const next = code[at + 1];
+    if (next === undefined)
+        return undefined;
+    const simple = { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', v: '\v', 0: '\0' };
+    if (next in simple && !(next === '0' && /\d/.test(code[at + 2] ?? '')))
+        return { text: simple[next], end: at + 2 };
+    if (next === '\n')
+        return { text: '', end: at + 2 };
+    if (next === 'x') {
+        const hex = code.slice(at + 2, at + 4);
+        return /^[0-9a-fA-F]{2}$/.test(hex) ? { text: String.fromCharCode(parseInt(hex, 16)), end: at + 4 } : undefined;
+    }
+    if (next === 'u') {
+        const braced = /^\{([0-9a-fA-F]{1,6})\}/.exec(code.slice(at + 2));
+        if (braced !== null) {
+            const point = parseInt(braced[1], 16);
+            return point > 0x10ffff ? undefined : { text: String.fromCodePoint(point), end: at + 2 + braced[0].length };
+        }
+        const hex = code.slice(at + 2, at + 6);
+        return /^[0-9a-fA-F]{4}$/.test(hex) ? { text: String.fromCharCode(parseInt(hex, 16)), end: at + 6 } : undefined;
+    }
+    // An octal escape is legacy and a strict module refuses it: not read.
+    if (/[1-9]/.test(next))
+        return undefined;
+    return { text: next, end: at + 2 };
+}
+/** Past a string, a template or a comment that starts at `at`; `at` itself where none does. */
+function skipQuoted(code, at) {
+    const character = code[at];
+    if (character === '/' && code[at + 1] === '/') {
+        const end = code.indexOf('\n', at);
+        return end === -1 ? code.length : end + 1;
+    }
+    if (character === '/' && code[at + 1] === '*') {
+        const end = code.indexOf('*/', at + 2);
+        return end === -1 ? code.length : end + 2;
+    }
+    if (character !== '"' && character !== "'" && character !== '`')
+        return at;
+    for (let position = at + 1; position < code.length; position += 1) {
+        if (code[position] === '\\') {
+            position += 1;
+            continue;
+        }
+        if (code[position] === character)
+            return position + 1;
+    }
+    return code.length;
+}
+function skipSpace(code, at) {
+    let position = at;
+    while (position < code.length && /\s/.test(code[position] ?? ''))
+        position += 1;
+    return position;
+}
+function isWordCharacter(character) {
+    return character !== undefined && /[A-Za-z0-9_$]/.test(character);
+}

package/dist/adapter/codex/events/delivered-output.js

@@ -0,0 +1,30 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Whether a command's recorded output is what the model was handed (XB5, `2026-09-27-what-codex-wrote.md` §7).
+ *
+ * In code mode the model never receives what a process printed: it receives the cell's return value, and the agent's
+ * own JavaScript stands between the two and may keep any part of it. Measured 2026-10-05 over the 79 non-empty
+ * `CommandExecution` outputs of Codex 0.160.0 `paginated`: 15 reached a cell whole, 36 left one long line in it, 11 only
+ * a first token, and 17 nothing at all. An action item is therefore no evidence of delivery, which is why the adapter
+ * records one at the execution stage.
+ *
+ * Where the output does occur whole in exactly one of the session's cell returns, that one return carried it, and the
+ * stage is the model's. Two returns holding the same text name neither: of the 15, 13 were unique and 2 were not. The
+ * join is by the text itself, not by an id - no id joins an item to a cell (§2.3) - so it is made only on an exact,
+ * unique occurrence, and never on an empty output, which every cell would hold.
+ */
+export function deliveredWhole(output, cellReturns) {
+    const text = output.trim();
+    if (text === '')
+        return false;
+    let found = 0;
+    for (const returned of cellReturns) {
+        if (!returned.includes(text))
+            continue;
+        found += 1;
+        if (found > 1)
+            return false;
+    }
+    return found === 1;
+}

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

@@ -1,10 +1,10 @@
 import { FileAccessError } from '../../../ports/file-access-error.js';
 import { isJsonObject, parseJsonObject } from '../../../shared/json.js';
-import { ITEM, ITEM_EVENT } from '../contract/actions.js';
+import { ACTION_ITEMS, ITEM, ITEM_EVENT } from '../contract/actions.js';
 import { ACTIVITY, AGENT_MESSAGE, DELEGATION_TOOLS, SPAWN_ARGUMENTS } from '../contract/delegations.js';
-import { CODE_CELL, FUNCTION_CALL } from '../contract/deliveries.js';
+import { CELL_COMMANDS, CODE_CELL, FUNCTION_CALL } from '../contract/deliveries.js';
 import { ENVELOPE, LINE_TYPES, PASSIVE_EVENTS, PASSIVE_LINE_TYPES } from '../contract/envelope.js';
-import { EVENT_MESSAGES, ITEM_TEXT_BLOCKS, MESSAGE, MESSAGE_ITEMS, PHASES, REASONING, REASONING_ITEM, RESPONSE_ITEMS, ROLES, TEXT_BLOCKS, } from '../contract/messages.js';
+import { EVENT_MESSAGES, HOOK_PROMPT, ITEM_TEXT_BLOCKS, MESSAGE, MESSAGE_ITEMS, PHASES, REASONING, REASONING_ITEM, RESPONSE_ITEMS, ROLES, TEXT_BLOCKS, } from '../contract/messages.js';
 import { VERDICT } from '../contract/reviews.js';
 import { SESSION } from '../contract/session.js';
 import { RESPONSE_TURN, TURN_CONTEXT, TURN_EVENTS } from '../contract/turns.js';
@@ -13,6 +13,8 @@ import { PRE_TOOL_USE } from '../contract/hooks.js';
 import { isActionItem, readAction } from './action-items.js';
 import { hookRefusalsIn } from './hook-refusals.js';
 import { capabilitiesOf } from './capability-records.js';
+import { cellCommands } from './cell-commands.js';
+import { deliveredWhole } from './delivered-output.js';
 import { permissionsOf } from './turn-permissions.js';
 /**
  * One rollout file, read line by line into the collection. Only top-level lines are records (X13); order is the line's
@@ -43,6 +45,8 @@ class FileState {
     #outputs = [];
     #itemIds = new Set();
     #actionCalls = [];
+    /** Items that record a command or a change: where there are none, a cell's code is all there is of what ran (XD4). */
+    #ranItems = 0;
     #said = [];
     #reasoning = new Map();
     #agentItems = [];
@@ -51,6 +55,8 @@ class FileState {
     #verdicts = [];
     #unrecognised = false;
     #interrupted = false;
+    /** The ids of `user` messages read so far: a `HookPrompt` with one of them is a copy of that message (§2.12). */
+    #givenIds = new Set();
     #hiddenReasoning = false;
     #permissionsRecorded = false;
     #permissionsIncomplete = false;
@@ -169,6 +175,9 @@ class FileState {
         const author = this.#role.kind === 'reviewer'
             ? (role === ROLES.assistant ? 'reviewer' : 'runtime')
             : role === ROLES.user ? 'person' : role === ROLES.developer ? 'developer' : 'unknown';
+        const id = payload[MESSAGE.id];
+        if (role === ROLES.user && typeof id === 'string' && id !== '')
+            this.#givenIds.add(id);
         this.#context('conversation', author, words.text, words.completeness, evidence, turnId);
     }
     /** X31: readable summary text is reasoning, never the whole of it; encrypted content is never read or guessed. */
@@ -228,6 +237,7 @@ class FileState {
             this.#reviewerActions = true;
         this.#calls.set(callId, {
             kind, id: callId, evidence, toolName: typeof name === 'string' ? name : 'unrecognised call', input, ...(turnId === undefined ? {} : { turnId }),
+            ...(cell && typeof code === 'string' ? { code } : {}),
         });
         if (this.#role.kind !== 'agent')
             return;
@@ -299,7 +309,9 @@ class FileState {
             if (typeof text !== 'string')
                 return;
             if (type === EVENT_MESSAGES.agent && this.#role.kind === 'agent') {
-                this.#collected.gaps.push({ kind: 'relation-unresolved', agentId: this.#role.agentId });
+                // A copy of what the agent said, joined to no utterance: the question it leaves open is its own words, never what
+                // it ran or reached - said so, so a page can tell it from an action left unjoined (found 2026-10-05).
+                this.#collected.gaps.push({ kind: 'relation-unresolved', question: 'own-words', agentId: this.#role.agentId });
                 this.#context('conversation', 'agent', text, 'complete', evidence, turnId);
             }
             else
@@ -339,6 +351,15 @@ class FileState {
         }
         if (type === MESSAGE_ITEMS.compaction || type === MESSAGE_ITEMS.functionOutput)
             return;
+        // §2.12: a hook's request to the model, never an action. The `user` message with its id holds its words already; one
+        // that joins none is kept as the runtime's words, so nothing it carried goes unread.
+        if (type === MESSAGE_ITEMS.hookPrompt) {
+            if (typeof id !== 'string' || !this.#givenIds.has(id)) {
+                const words = hookPromptText(item);
+                this.#context('conversation', 'runtime', words.text, words.completeness, evidence, turnId);
+            }
+            return;
+        }
         // X6: an action item; one the contract does not name is read as an unknown tool, with a gap.
         if (!isActionItem(type))
             this.#unrecognised = true;
@@ -354,6 +375,8 @@ class FileState {
             return;
         }
         this.#itemIds.add(id);
+        if (item[ITEM.type] === ACTION_ITEMS.command || item[ITEM.type] === ACTION_ITEMS.fileChange)
+            this.#ranItems += 1;
         const action = readAction(item);
         for (const question of action.unanswered) {
             this.#collected.gaps.push({ kind: 'capability-absent', question, agentId: this.#role.agentId });
@@ -365,11 +388,13 @@ class FileState {
                 commands: action.commands, resultShape: action.resultShape, toolKnown: action.toolKnown,
                 ...(action.written === undefined ? {} : { written: action.written }), ...(turnId === undefined ? {} : { turnId }), evidence,
             },
-            // The item is both the call and what came back (X6). What it printed is the execution stage: never delivered by itself.
+            // The item is both the call and what came back (X6). What it printed is the execution stage: never delivered by
+            // itself - `#finishAgent` raises it to the model's only where a cell is shown to have returned it (XB5).
             result: {
                 callId, stage: 'execution', completeness: action.output?.completeness ?? 'complete', execution: action.execution, evidence,
                 ...(action.output === undefined ? {} : { content: action.output.text }),
             },
+            command: item[ITEM.type] === ACTION_ITEMS.command,
         });
     }
     /** X16, X17: `started` names the agent a spawn started, `interacted` the agent a later call reached, by the call's id. */
@@ -455,9 +480,59 @@ class FileState {
             permissionsRecorded: this.#permissionsRecorded,
         }));
     }
+    /**
+     * XD4, amended 2026-10-05 by the maintainer (§2.11): where an agent's record keeps no item of what ran - every VS Code
+     * panel record, measured - the commands its cells' code wrote out as text are its actions. A command the code builds
+     * while it runs is not read, and leaves the action stream a gap. What a cell returned is given to its command only
+     * where the cell ran that one command and called no other tool; it is the model's input, and the cell's header says
+     * whether the script ran to its end - never the command's exit code, which is not recorded. A cell whose return holds
+     * a refusal by agentwhy's hook is read by `hookRefusalsIn` alone, so a stopped command is never also a run one.
+     */
+    #cellCommands() {
+        const agentId = this.#role.agentId;
+        const returned = new Map(this.#outputs.filter(({ kind }) => kind === 'cell').map(({ output }) => [output.callId, output]));
+        const found = [];
+        let unread = 0;
+        for (const cell of this.#calls.values()) {
+            if (cell.kind !== 'cell' || cell.code === undefined)
+                continue;
+            const output = returned.get(cell.id);
+            if (output !== undefined && hookRefusalsIn(output.text).length > 0)
+                continue;
+            const { commands, unread: notText, alone } = cellCommands(cell.code);
+            unread += notText;
+            const execution = output === undefined ? undefined : scriptState(output.text);
+            commands.forEach((command, at) => {
+                const id = `${this.#scoped(cell.id)}:command:${at + 1}`;
+                found.push({
+                    call: {
+                        id, agentId, toolName: CELL_COMMANDS.call, input: { command }, targets: [], commands: [command], resultShape: 'listing',
+                        toolKnown: true, evidence: cell.evidence, ...(cell.turnId === undefined ? {} : { turnId: cell.turnId }),
+                    },
+                    ...(output === undefined || execution === undefined ? {} : {
+                        result: {
+                            callId: id, stage: 'model', execution, evidence: output.evidence,
+                            // Only a cell that ran this one command returned what it printed; any other's return is no one command's.
+                            ...(alone ? { content: output.text, completeness: output.completeness } : { completeness: 'unknown' }),
+                        },
+                    }),
+                });
+            });
+        }
+        if (unread > 0)
+            this.#collected.capabilities.push({ question: 'actions', state: 'unmeasured', source: this.#role.source, agentId });
+        return found;
+    }
     #finishAgent() {
         const agentId = this.#role.agentId;
-        const calls = [...this.#actionCalls];
+        // XB5: a command's output is the model's only where one cell return is shown to carry it, which is known once
+        // every record of this agent has been read. Measured on CommandExecution alone, so no other item type is raised.
+        const cellReturns = this.#outputs.filter(({ kind }) => kind === 'cell').map(({ output }) => output.text);
+        const calls = this.#actionCalls.map(({ call, result, command }) => (command && result.content !== undefined && deliveredWhole(result.content, cellReturns)
+            ? { call, result: { ...result, stage: 'model' } }
+            : { call, result }));
+        if (this.#ranItems === 0 && this.#role.kind === 'agent')
+            calls.push(...this.#cellCommands());
         for (const call of this.#calls.values()) {
             // A direct call its action item answers is that item: one action, never two (X6).
             if (call.kind === 'cell' || call.kind === 'follow-up' || (call.kind === 'direct' && this.#itemIds.has(call.id)))
@@ -546,7 +621,8 @@ class FileState {
     #uncertainCopy(text, evidence) {
         if (text === '')
             return;
-        this.#collected.gaps.push({ kind: 'relation-unresolved', agentId: this.#role.agentId });
+        // A copy of the agent's words that joins none of them: what it leaves open is its words, as with the editor's copies.
+        this.#collected.gaps.push({ kind: 'relation-unresolved', question: 'own-words', agentId: this.#role.agentId });
         this.#context('conversation', 'agent', text, 'complete', evidence);
     }
     /** X19, X20: every verdict with its own evidence, on the reviewed turn its reviewer's turn names, or on none. */
@@ -606,6 +682,22 @@ function textOf(content, types) {
     }
     return { text: texts.join('\n'), completeness: whole ? 'complete' : 'partial' };
 }
+/** The script's state, by the header its return opens with (XD4): never the exit code of a command it ran. */
+function scriptState(text) {
+    if (text.startsWith(CELL_COMMANDS.completedHeader))
+        return { status: 'completed' };
+    if (text.startsWith(CELL_COMMANDS.failedHeader))
+        return { status: 'failed' };
+    return { status: 'unrecognised' };
+}
+/** A `HookPrompt`'s words, one fragment after another (§2.12); a fragment of another shape makes them partial. */
+function hookPromptText(item) {
+    const fragments = item[HOOK_PROMPT.fragments];
+    if (!Array.isArray(fragments))
+        return { text: '', completeness: 'unknown' };
+    const texts = fragments.flatMap((fragment) => (isJsonObject(fragment) && typeof fragment[HOOK_PROMPT.text] === 'string' ? [fragment[HOOK_PROMPT.text]] : []));
+    return { text: texts.join('\n'), completeness: texts.length === fragments.length ? 'complete' : 'partial' };
+}
 /** A cell's or a call's output: a string, or parts whose text is under `input_text` (§2.8). */
 function outputText(output) {
     if (typeof output === 'string')

package/dist/core/access/command-line.js

@@ -50,6 +50,9 @@ const PRINTS_CONTENT = new Set([
     'strings',
     'xxd',
     'od',
+    // A filter of the lines it is given: `head customers.csv | cut -c1-80` prints the file's rows, cut short. Found on
+    // 2026-10-05 in a Codex session whose agent printed a tracked file's header and first row through it.
+    'cut',
 ]);
 /**
  * Programs that print nothing when they succeed (`said-where-the-person-is` SWO1): `cd apps && cat .env` prints the
@@ -63,7 +66,7 @@ const PRINTS_NOTHING = new Set(['cd']);
  * …` in one line read the key and traced nothing, so the person heard "no value found" over a value in the chat.
  * Not a search: a search prints a file's lines, and is read as one (`search-hits-are-reads`).
  */
-const LISTS_NAMES = new Set(['ls', 'find']);
+const LISTS_NAMES = new Set(['ls', 'find', 'file']);
 /** `NAME=value` before a program sets a variable; it runs nothing. */
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
 /** Unquoted, each of these ends a simple command. `&` directly before `>` redirects instead (`&>file`). */

package/dist/core/access/listing.js

@@ -38,7 +38,10 @@ export function listingPathCandidates(text) {
         // `grep -n` without a file name writes `49:matched text`, and that leading number is not part of a path.
         // Dropping it is what stops `49:packages/app/.env` from being reported as a file.
         const withoutLineNumber = trimmed.replace(/^\d+:/, '');
-        const colon = withoutLineNumber.indexOf(':');
+        // `ls -l` opens a line with a permission string nothing else begins with, and prints no search hit: the colon of
+        // its time of day (`Oct  5 12:26`) is no path's, so no field before it is offered.
+        const long = LONG_LISTING.test(withoutLineNumber);
+        const colon = long ? -1 : withoutLineNumber.indexOf(':');
         const fields = withoutLineNumber.split(/\s+/);
         // In order of preference. A whole grep line matches a pattern as readily as the path that starts it, so
         // the narrower candidate is offered first and only the first match of a line is taken: one line of a
@@ -51,8 +54,12 @@ export function listingPathCandidates(text) {
             { text: colon === -1 && PATH_START.test(withoutLineNumber) ? asWholeLine(withoutLineNumber) : '', positional: true },
             // A line that is one word is that word: `ls -1` and `git status --porcelain` write listings like that.
             { text: fields.length === 1 ? asWholeLine(withoutLineNumber) : '', positional: true },
-            // `ls -l` writes the name last, after a permission string that nothing else begins with.
-            { text: LONG_LISTING.test(withoutLineNumber) ? asField(fields[fields.length - 1] ?? '') : '', positional: false },
+            // `ls -l` writes the name last, after a permission string that nothing else begins with - a path by where it sits
+            // (`paths-not-fragments` R2), so every pattern of a policy may match it. Offered as not positional, it matched
+            // only a pattern naming one file: `ls -la` listed `demo.env` and `customers.csv`, and only the tracked
+            // `**/customers.csv` was found, never `**/*.env` (found 2026-10-05). A name holding a space is still cut to its
+            // last word, as it always was.
+            { text: long ? asField(fields[fields.length - 1] ?? '') : '', positional: true, ...(long ? { listed: withoutLineNumber.startsWith('d') ? 'directory' : 'file' } : {}) },
         ];
         return candidates.filter((candidate) => candidate.text !== '');
     })