@pugi/cli 0.1.0-beta.17 → 0.1.0-beta.18

package/dist/core/diagnostics/probes/node.js

@@ -0,0 +1,59 @@
+/**
+ * NODE probe — verifies the running Node major version meets the
+ * `engines.node` floor declared in @pugi/cli's package.json.
+ *
+ * We bake the floor in as a constant rather than reading package.json
+ * at runtime because the published .tgz strips the file from a location
+ * the compiled bundle can reach (`--resolveJsonModule` is off for the
+ * CLI build). The lockstep is enforced by
+ * `scripts/check-version-lockstep.sh` in the publish pipeline.
+ */
+/**
+ * Minimum supported Node major. Mirrors `engines.node` in
+ * apps/pugi-cli/package.json (`">=22.5.0"`).
+ */
+export const MIN_NODE_MAJOR = 22;
+export const MIN_NODE_MINOR = 5;
+/**
+ * Parse a Node version string of the form `v<major>.<minor>.<patch>`.
+ * Returns null when the input doesn't match — the caller treats null
+ * as an error condition.
+ */
+export function parseNodeVersion(version) {
+    const match = /^v(\d+)\.(\d+)\./.exec(version);
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    if (!Number.isFinite(major) || !Number.isFinite(minor))
+        return null;
+    return { major, minor };
+}
+export function probeNode(input) {
+    const parsed = parseNodeVersion(input.version);
+    if (!parsed) {
+        return {
+            name: 'NODE',
+            status: 'error',
+            detail: `Unparseable Node version "${input.version}"`,
+            remediation: `Install Node >= ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}.0 (current binary returns a non-semver version string)`,
+        };
+    }
+    const { major, minor } = parsed;
+    const passes = major > MIN_NODE_MAJOR ||
+        (major === MIN_NODE_MAJOR && minor >= MIN_NODE_MINOR);
+    if (passes) {
+        return {
+            name: 'NODE',
+            status: 'ok',
+            detail: `${input.version} (>= ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}.0 required)`,
+        };
+    }
+    return {
+        name: 'NODE',
+        status: 'error',
+        detail: `${input.version} below floor >= ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}.0`,
+        remediation: `Upgrade Node: \`nvm install ${MIN_NODE_MAJOR}\` or download from nodejs.org`,
+    };
+}
+//# sourceMappingURL=node.js.map

package/dist/core/diagnostics/probes/pnpm.js

@@ -0,0 +1,36 @@
+/**
+ * PNPM probe — verifies pnpm is on PATH and reports its version. The
+ * customer-facing CLI doesn't strictly require pnpm at runtime
+ * (`@pugi/cli` is published as a regular npm package), but a missing
+ * pnpm means `pugi code` cannot run `pnpm test` / `pnpm typecheck`
+ * gates the agent loop emits. Surfacing this early prevents the
+ * agent from issuing a meaningless `command not found: pnpm` error
+ * three turns into a session.
+ */
+export function probePnpm(deps) {
+    try {
+        const version = deps.resolveVersion();
+        if (!version) {
+            return {
+                name: 'PNPM',
+                status: 'warn',
+                detail: 'pnpm reported empty version string',
+            };
+        }
+        return {
+            name: 'PNPM',
+            status: 'ok',
+            detail: `pnpm ${version}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'PNPM',
+            status: 'warn',
+            detail: 'pnpm not on PATH — agent quality gates will be skipped',
+            remediation: `Install pnpm: \`npm i -g pnpm\` (error: ${message})`,
+        };
+    }
+}
+//# sourceMappingURL=pnpm.js.map

package/dist/core/diagnostics/probes/session.js

@@ -0,0 +1,74 @@
+/**
+ * SESSION probe — reports the active session id + age when the doctor
+ * runs from inside the REPL OR finds a recent NDJSON session log in
+ * the workspace.
+ *
+ * The CLI command path has no live session context (each `pugi <cmd>`
+ * invocation is a fresh process), so we read `.pugi/events.jsonl` if
+ * present and report the most-recent event's age + total line count.
+ * Inside the REPL we pass an explicit `sessionId` so the probe
+ * surfaces the live state without re-reading disk.
+ *
+ * Absence of `.pugi/events.jsonl` is `skipped`, not an error — the
+ * operator may simply be running `pugi doctor` in a workspace that
+ * has not yet seen a dispatch.
+ */
+export function probeSession(ctx, fs, deps) {
+    if (deps.liveSessionId) {
+        return {
+            name: 'SESSION',
+            status: 'ok',
+            detail: `session=${deps.liveSessionId} (live, REPL active)`,
+        };
+    }
+    const eventsPath = `${ctx.cwd}/.pugi/events.jsonl`;
+    if (!fs.existsSync(eventsPath)) {
+        return {
+            name: 'SESSION',
+            status: 'skipped',
+            detail: 'No prior dispatch logged in this workspace',
+        };
+    }
+    let stats;
+    try {
+        stats = fs.statSync(eventsPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'SESSION',
+            status: 'warn',
+            detail: `.pugi/events.jsonl present but unreadable`,
+            remediation: `Inspect: ${message}`,
+        };
+    }
+    const ageMs = Math.max(0, deps.now() - stats.mtimeMs);
+    const ageLabel = formatAge(ageMs);
+    // Counting lines is cheap on a small NDJSON file; a "huge" Pugi
+    // session is single-digit MB. We avoid loading binary blobs by
+    // simply walking the buffer count.
+    let lineCount = 0;
+    try {
+        const raw = fs.readFileSync(eventsPath, 'utf8');
+        lineCount = raw.split('\n').filter((line) => line.trim().length > 0).length;
+    }
+    catch {
+        lineCount = -1;
+    }
+    const linePart = lineCount >= 0 ? `, ${lineCount} event(s)` : '';
+    return {
+        name: 'SESSION',
+        status: 'ok',
+        detail: `last event ${ageLabel} ago${linePart}`,
+    };
+}
+export function formatAge(ms) {
+    if (ms < 60_000)
+        return `${Math.round(ms / 1000)}s`;
+    if (ms < 3_600_000)
+        return `${Math.round(ms / 60_000)}m`;
+    if (ms < 86_400_000)
+        return `${Math.round(ms / 3_600_000)}h`;
+    return `${Math.round(ms / 86_400_000)}d`;
+}
+//# sourceMappingURL=session.js.map

package/dist/core/diagnostics/probes/workspace.js

@@ -0,0 +1,63 @@
+/**
+ * WORKSPACE probe — verifies `.pugi/` exists, is writable, and is not
+ * littered with stale lock files. Optional NDJSON session log presence
+ * is reported as additional context but never the basis for a verdict
+ * change (it is created on first dispatch, not at init time).
+ *
+ * The probe owns its fs surface so the spec can run in a tmp sandbox.
+ */
+export function probeWorkspace(ctx, fs) {
+    const pugiDir = `${ctx.cwd}/.pugi`;
+    if (!fs.existsSync(pugiDir)) {
+        return {
+            name: 'WORKSPACE',
+            status: 'warn',
+            detail: `.pugi/ not initialised in ${ctx.cwd}`,
+            remediation: 'Run `pugi init` to scaffold the workspace',
+        };
+    }
+    let isDir = false;
+    try {
+        isDir = fs.statSync(pugiDir).isDirectory();
+    }
+    catch {
+        return {
+            name: 'WORKSPACE',
+            status: 'error',
+            detail: `.pugi/ stat failed in ${ctx.cwd}`,
+            remediation: 'Re-create the directory: `rm -rf .pugi && pugi init`',
+        };
+    }
+    if (!isDir) {
+        return {
+            name: 'WORKSPACE',
+            status: 'error',
+            detail: `${pugiDir} exists but is not a directory`,
+            remediation: 'Remove the file at .pugi and run `pugi init`',
+        };
+    }
+    try {
+        fs.accessSync(pugiDir, fs.W_OK);
+    }
+    catch {
+        return {
+            name: 'WORKSPACE',
+            status: 'error',
+            detail: `.pugi/ is not writable for the current user`,
+            remediation: `chown / chmod the directory so the current user can write it`,
+        };
+    }
+    // Best-effort: report session log presence as detail context. Absence
+    // is normal (events.jsonl is created lazily) so it never moves the
+    // verdict.
+    const eventLogPresent = fs.existsSync(`${pugiDir}/events.jsonl`);
+    const detail = eventLogPresent
+        ? `.pugi/ writable, events.jsonl present`
+        : `.pugi/ writable (events.jsonl created on first dispatch)`;
+    return {
+        name: 'WORKSPACE',
+        status: 'ok',
+        detail,
+    };
+}
+//# sourceMappingURL=workspace.js.map

package/dist/core/diagnostics/types.js

@@ -0,0 +1,70 @@
+/**
+ * Leak L17 — `pugi doctor` diagnostics types.
+ *
+ * The doctor command probes the local environment + remote API +
+ * workspace state and produces a structured health report. Each probe
+ * runs independently; one probe's failure NEVER cascades to another.
+ *
+ * Status semantics:
+ *   - `ok`      : probe verified the expected state.
+ *   - `warn`    : non-blocking signal (stale CLI, low-but-not-empty disk,
+ *                 missing optional config, etc.). Overall verdict still
+ *                 passes the gate.
+ *   - `error`   : a real problem the operator must fix before Pugi will
+ *                 work end-to-end (auth missing, API unreachable, .pugi/
+ *                 unwritable, Node version below floor, disk full).
+ *   - `skipped` : prerequisite for the probe is absent (e.g. MCP probe
+ *                 when no mcp.json exists). Does NOT count against the
+ *                 overall verdict.
+ *
+ * Layered design: this module owns NO I/O. Individual probe files own
+ * their I/O surface. The runner orchestrates them in parallel with a
+ * timeout + fail-isolation wrapper. The doctor command formats the
+ * results for human + JSON consumers.
+ */
+/**
+ * Helper for the runner to compute the overall verdict from a probe
+ * set without leaking the algorithm into the doctor command. Any error
+ * → 'error'; any warn (no errors) → 'warning'; otherwise 'healthy'.
+ * Skipped probes do NOT influence the verdict.
+ */
+export function computeOverall(probes) {
+    let hasError = false;
+    let hasWarn = false;
+    for (const probe of probes) {
+        if (probe.status === 'error')
+            hasError = true;
+        else if (probe.status === 'warn')
+            hasWarn = true;
+    }
+    if (hasError)
+        return 'error';
+    if (hasWarn)
+        return 'warning';
+    return 'healthy';
+}
+/**
+ * Compute the per-status counts in a single pass so renderers do not
+ * have to re-iterate. Surfaces in both the trailer line and the JSON
+ * envelope so downstream consumers can render a one-line summary
+ * without re-walking the probe array.
+ */
+export function countProbes(probes) {
+    const counts = { ok: 0, warn: 0, error: 0, skipped: 0 };
+    for (const probe of probes)
+        counts[probe.status] += 1;
+    return counts;
+}
+/**
+ * Exit-code map. Exposed for both the CLI handler and the spec so the
+ * contract stays in one place.
+ *   0 — healthy OR warnings only.
+ *   1 — internal crash (unhandled throw in the runner itself).
+ *   2 — at least one probe reported `error`.
+ */
+export function exitCodeFor(overall) {
+    if (overall === 'error')
+        return 2;
+    return 0;
+}
+//# sourceMappingURL=types.js.map

package/dist/core/engine/strip-internal-fields.js

@@ -0,0 +1,124 @@
+/**
+ * α7 L3 (2026-05-27) — leak-parity: underscore-prefix internal-fields filter.
+ *
+ * The convention (observed in the leaked Claude Code BashTool surface and
+ * codified in `docs/research/2026-05-27-pugi-gap-analysis-3-repos.md` §1)
+ * is that tool-argument fields whose names start with a leading underscore
+ * are INTERNAL — populated by the dispatcher at call time (sessionId,
+ * tenantId, correlation handles, hook context, ask-modal bridge handles)
+ * but never advertised to the model. The model schema MUST omit them so:
+ *
+ *   1. No token cost — internal context never burns model budget.
+ *   2. No fabrication risk — the model cannot hallucinate values for
+ *      sessionId / tenantId / etc. because the field is invisible.
+ *   3. No leak surface — implementation detail stays implementation detail.
+ *
+ * The dispatcher (see `tool-bridge.ts::buildExecutor`) does NOT strip these
+ * fields at call time. It passes the full args record (including any
+ * `_internal*` keys an upstream layer injected) straight to the tool
+ * handler. Only the schema surface that the engine adapter ships to the
+ * model is filtered.
+ *
+ * This module is intentionally narrow: it accepts a JSON Schema fragment
+ * and returns a deep clone with `_`-prefixed keys removed from every
+ * `properties` map encountered while walking, and with `required` filtered
+ * to drop any references to those keys. It descends into nested object
+ * schemas and into the `items` schema of arrays. It is JSON-Schema-version
+ * agnostic (works on draft-07, 2019-09, 2020-12 alike) because it only
+ * inspects `properties`/`required`/`items` and leaves the rest of the
+ * fragment alone.
+ *
+ * Edge cases handled:
+ *   - `_` alone (single underscore) is treated as internal and stripped.
+ *   - Nested object schemas inside `properties` get the same treatment
+ *     (a sub-property whose name starts with `_` is removed too).
+ *   - Array `items` are walked. Tuple schemas (`items` as array) are
+ *     walked element-by-element.
+ *   - `oneOf`/`anyOf`/`allOf` branches are walked.
+ *   - Non-object inputs (null, primitives, arrays passed as the root)
+ *     are returned as-is — defensive no-op, never throws.
+ *
+ * Contract notes:
+ *   - Pure function. Input is never mutated.
+ *   - Output is a deep clone — every nested object/array is freshly
+ *     allocated so callers can mutate safely.
+ *   - JSON-only — does not preserve symbols, getters, or class instances
+ *     because JSON Schema is plain-data by spec.
+ */
+const INTERNAL_PREFIX = '_';
+/**
+ * Returns true when the field name should be stripped from the model-
+ * facing schema. Leading underscore is the contract — single `_` is also
+ * stripped (no escape hatch). Empty-string keys (which are technically
+ * valid JSON) are left alone so we do not silently drop them.
+ */
+export function isInternalFieldName(name) {
+    return name.length > 0 && name.startsWith(INTERNAL_PREFIX);
+}
+/**
+ * Strip `_`-prefixed properties from a JSON Schema fragment. Recursively
+ * walks nested object schemas and array `items`. Returns a deep clone;
+ * the input is never mutated.
+ *
+ * Pass-through behaviour:
+ *   - Non-object / null / array inputs round-trip unchanged (as deep
+ *     clones where applicable).
+ *   - Fragments with no `properties` key are returned as deep clones
+ *     after walking `items`/`oneOf`/`anyOf`/`allOf`.
+ */
+export function stripInternalFields(schema) {
+    if (schema === null || typeof schema !== 'object')
+        return schema;
+    if (Array.isArray(schema)) {
+        return schema.map((item) => stripInternalFields(item));
+    }
+    return walkObject(schema);
+}
+function walkObject(node) {
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'properties' && value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            out[key] = walkProperties(value);
+            continue;
+        }
+        if (key === 'required' && Array.isArray(value)) {
+            out[key] = value.filter((entry) => typeof entry === 'string' && !isInternalFieldName(entry));
+            continue;
+        }
+        if (key === 'items') {
+            out[key] = stripInternalFields(value);
+            continue;
+        }
+        if (key === 'oneOf' || key === 'anyOf' || key === 'allOf') {
+            if (Array.isArray(value)) {
+                out[key] = value.map((branch) => stripInternalFields(branch));
+                continue;
+            }
+        }
+        // Default: deep-clone any nested objects/arrays so the caller can
+        // mutate freely without touching the input. Primitives pass through.
+        out[key] = cloneJson(value);
+    }
+    return out;
+}
+function walkProperties(props) {
+    const out = {};
+    for (const [propName, propSchema] of Object.entries(props)) {
+        if (isInternalFieldName(propName))
+            continue;
+        out[propName] = stripInternalFields(propSchema);
+    }
+    return out;
+}
+function cloneJson(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => cloneJson(item));
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+        out[key] = cloneJson(val);
+    }
+    return out;
+}
+//# sourceMappingURL=strip-internal-fields.js.map

package/dist/core/engine/tool-bridge.js

@@ -1,6 +1,7 @@
-import { editTool, globTool, grepTool, OperatorAbortedError, readTool, writeTool, } from '../../tools/file-tools.js';
+import { editTool, globTool, grepTool, OperatorAbortedError, readTool, StaleReadError, writeTool, } from '../../tools/file-tools.js';
 import { bashToolSync } from '../../tools/bash.js';
 import { askUser } from '../../tools/ask-user.js';
+import { askUserQuestionJsonSchema, dispatchAskUserQuestion, } from '../../tools/ask-user-question.js';
 import { skillInvoke, skillList } from '../../tools/skill-tool.js';
 import { taskCreate, taskGet, taskList, taskUpdate, } from '../../tools/tasks.js';
 import { webFetchTool } from '../../tools/web-fetch.js';
@@ -8,6 +9,7 @@ import { webSearchTool } from '../../tools/web-search.js';
 import { agentTool } from '../../tools/agent-tool.js';
 import { multiEdit } from '../../tools/multi-edit.js';
 import { buildMcpToolDefs, defaultNonInteractiveMcpPrompt, dispatchMcpTool, MCP_TOOL_PREFIX, } from '../../tools/mcp-tool.js';
+import { stripInternalFields } from './strip-internal-fields.js';
 /**
  * Tool-bridge: turns the abstract tool registry into:
  *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
@@ -185,26 +187,18 @@ export function buildToolsSchema(kind, options = { allowFetch: false, allowSearc
             },
         },
     });
-    // β1 T2: AskUserQuestion bridge. Returns picked answer in interactive
-    // mode, `[user_input_required]` envelope otherwise.
+    // β1 T2 → leak L5 (2026-05-27): structured AskUserQuestion bridge.
+    // Schema upgraded to openclaude's multi-choice form: header chip +
+    // {label, description} per option. Dispatcher accepts the structured
+    // form (preferred) AND the legacy string-array form so existing
+    // callers / tests keep working until the next major bump.
+    //
+    // Interactive TTY → returns the picked label(s).
+    // Non-TTY / no bridge → `[user_input_required]` envelope.
     toolDefs.push({
         name: 'ask_user_question',
-        description: 'Surface a 2-4 option modal to the operator. Interactive TTY: returns the chosen label(s). Non-TTY: returns a [user_input_required] envelope.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['question', 'options'],
-            properties: {
-                question: { type: 'string', description: 'Short, scannable question. Max 1000 chars.' },
-                options: {
-                    type: 'array',
-                    items: { type: 'string', maxLength: 200 },
-                    minItems: 2,
-                    maxItems: 4,
-                },
-                multiSelect: { type: 'boolean' },
-            },
-        },
+        description: 'Clarifying multi-choice question to the operator. Use INSTEAD of asking in prose when one parameter is missing. Required: question (?-ended), header (≤12 chars), 2-4 options each with {label, description}. NEVER include "Other" — UI auto-adds. Budget: max 1 per turn.',
+        parameters: askUserQuestionJsonSchema,
     });
     // β1 T3: Skill tool — discover + invoke locally-installed skills.
     toolDefs.push({
@@ -332,7 +326,10 @@ export function buildToolsSchema(kind, options = { allowFetch: false, allowSearc
     if (!planMode) {
         toolDefs.push({
             name: 'write',
-            description: 'Create or overwrite a workspace file. Use for new files only — prefer edit for existing files. Workspace-scoped.',
+            description: 'Create or overwrite a workspace file. Prefer edit for existing files. ' +
+                'For OVERWRITE of an existing file, you MUST read the file first in this session — ' +
+                'write refuses with STALE_READ if the file changed since your last read, or if you ' +
+                'never read it. New-file creation (path does not exist) skips that gate. Workspace-scoped.',
             parameters: {
                 type: 'object',
                 additionalProperties: false,
@@ -344,7 +341,10 @@ export function buildToolsSchema(kind, options = { allowFetch: false, allowSearc
             },
         }, {
             name: 'edit',
-            description: 'Replace exactly one occurrence of oldString with newString inside an already-read file. Fails if the file changed since you read it or if oldString is missing/duplicate.',
+            description: 'Replace exactly one occurrence of oldString with newString inside an already-read file. ' +
+                'Refuses with STALE_READ if the file was never read this session or the on-disk contents ' +
+                'drifted since the read (mtime+sha gate). Recovery: re-read with the `read` tool, then ' +
+                'retry the edit. Also fails if oldString is missing or duplicate.',
             parameters: {
                 type: 'object',
                 additionalProperties: false,
@@ -417,7 +417,21 @@ export function buildToolsSchema(kind, options = { allowFetch: false, allowSearc
             });
         }
     }
-    return toolDefs;
+    // α7 L3 (2026-05-27): leak-parity underscore-prefix filter. Every
+    // tool's parameter schema is scrubbed of `_`-prefixed fields before
+    // the model ever sees it. Native tool schemas above currently declare
+    // no `_*` fields, but MCP tools surfaced through buildMcpToolDefs
+    // come from third-party servers whose authors may follow the same
+    // convention (an MCP tool can declare `_sessionId` knowing the CLI
+    // dispatcher will inject it before forwarding). The dispatcher
+    // (buildExecutor below) does NOT strip these from the args record at
+    // call time — `_internal*` keys still flow through to tool handlers
+    // when an upstream layer populates them.
+    return toolDefs.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: stripInternalFields(tool.parameters),
+    }));
 }
 function parseArgs(raw) {
     if (!raw || raw.trim() === '')
@@ -433,19 +447,27 @@ function parseArgs(raw) {
         throw new Error(`invalid JSON in tool arguments: ${error.message}`);
     }
 }
-function requireString(obj, key, aliases = []) {
-    // 2026-05-27 CEO live smoke: model passed `file: "index.html"` to write tool
-    // but spec required `path:`. Tool rejected → silent no-op → file не созданы.
-    // Accept common aliases so models trained на various tool schemas just work.
-    const tryKeys = [key, ...aliases];
-    for (const k of tryKeys) {
-        const v = obj[k];
-        if (typeof v === 'string')
-            return v;
-    }
+/**
+ * Strict canonical-only argument coercion (leak P0 L2, 2026-05-27).
+ *
+ * Reverts the beta.17 alias acceptance (`file` / `filename` / `filepath`
+ * / `file_path` → `path`). The alias shim was the wrong direction: it
+ * paved over a model-side prompt-drift bug at the runtime layer, weakened
+ * the strict JSON-Schema contract one layer up (`additionalProperties:
+ * false`), and drifted away from the openclaude reference (research memo
+ * §1.1 — `z.strictObject` rejects aliased fields).
+ *
+ * The compensating change ships in the persona prompts: Mira's system
+ * prompt and Hiroshi's persona body now declare canonical parameter
+ * names with few-shot wrong/right contrasts so the model learns the
+ * grammar upstream of the bridge.
+ */
+function requireString(obj, key) {
+    const v = obj[key];
+    if (typeof v === 'string')
+        return v;
     throw new Error(`tool argument "${key}" must be a string`);
 }
-const PATH_ALIASES = ['file', 'filename', 'filepath', 'file_path'];
 export function buildExecutor(input) {
     const { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch, allowSearch, agentDispatch, mcpRegistry } = input;
     const mcpPrompt = input.mcpPrompt ?? defaultNonInteractiveMcpPrompt;
@@ -603,6 +625,32 @@ export function buildExecutor(input) {
                 }
                 throw new Error(`OPERATOR_ABORTED: ${name} aborted mid-execution.`);
             }
+            // Leak L1 (2026-05-27): re-shape StaleReadError into a
+            // deterministic STALE_READ:<reason> sentinel so the model's
+            // retry policy can pattern-match on a stable prefix instead of
+            // free-form prose. The model is expected to re-read the file and
+            // retry the edit — the message points it at exactly that recovery
+            // path. PostToolUseFailure hooks observe the typed error so an
+            // operator can build a "warn me when stale edits keep happening"
+            // hook (likely a concurrency / multi-agent indicator).
+            if (error instanceof StaleReadError) {
+                if (hooks && sessionId) {
+                    const path = extractToolPath(name, argsRaw);
+                    await hooks.fire({
+                        sessionId,
+                        event: 'PostToolUseFailure',
+                        tool: name,
+                        path,
+                        payload: {
+                            tool: name,
+                            arguments: argsRaw,
+                            ok: false,
+                            error: `STALE_READ: ${error.reason} on ${error.path}`,
+                        },
+                    });
+                }
+                throw new Error(`STALE_READ: ${name} on ${error.path} refused (${error.reason}). Re-read the file with the \`read\` tool, then retry the ${name}.`);
+            }
             if (hooks && sessionId) {
                 const path = extractToolPath(name, argsRaw);
                 await hooks.fire({
@@ -643,7 +691,7 @@ function extractToolPath(name, argsRaw) {
 function dispatchTool(name, args, ctx) {
     switch (name) {
         case 'read': {
-            const { path } = { path: requireString(args, 'path', PATH_ALIASES) };
+            const { path } = { path: requireString(args, 'path') };
             const content = readTool(ctx, path);
             // Cap the content surfaced back to the model so a 10MB file
             // does not blow the context window. The model sees the head
@@ -656,7 +704,7 @@ function dispatchTool(name, args, ctx) {
         }
         case 'write': {
             const wargs = {
-                path: requireString(args, 'path', PATH_ALIASES),
+                path: requireString(args, 'path'),
                 content: requireString(args, 'content'),
             };
             writeTool(ctx, wargs.path, wargs.content);
@@ -664,7 +712,7 @@ function dispatchTool(name, args, ctx) {
         }
         case 'edit': {
             const eargs = {
-                path: requireString(args, 'path', PATH_ALIASES),
+                path: requireString(args, 'path'),
                 oldString: requireString(args, 'oldString'),
                 newString: requireString(args, 'newString'),
             };
@@ -762,11 +810,26 @@ function dispatchTaskTool(name, args, opts) {
     }
 }
 async function dispatchAskUser(args, opts) {
-    const question = requireString(args, 'question');
     const rawOptions = args['options'];
     if (!Array.isArray(rawOptions)) {
         throw new Error('ask_user_question: options must be an array');
     }
+    // Leak L5 (2026-05-27): detect structured vs legacy form. Structured
+    // entries are objects with {label, description}; legacy entries are
+    // plain strings. The structured path validates via Zod and emits the
+    // [ask_user_question:answered|cancelled|timeout] envelope. The legacy
+    // path stays for back-compat with the existing β1 T2 tests + the
+    // <pugi-ask> prompt envelope (which still feeds string options).
+    const looksStructured = rawOptions.length > 0
+        && typeof rawOptions[0] === 'object'
+        && rawOptions[0] !== null
+        && !Array.isArray(rawOptions[0]);
+    if (looksStructured) {
+        const result = await dispatchAskUserQuestion({ interactive: opts.interactive, ...(opts.bridge ? { bridge: opts.bridge } : {}) }, args);
+        return result.envelope;
+    }
+    // Legacy string-array form.
+    const question = requireString(args, 'question');
     const options = rawOptions.map((o, i) => {
         if (typeof o !== 'string') {
             throw new Error(`ask_user_question: options[${i}] must be a string`);