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

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,9 @@ 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 { buildDenialContext, DENIAL_REMINDER_THRESHOLD, } from '../denial-tracking/state.js';
+import { stripInternalFields } from './strip-internal-fields.js';
+import { applyAskAnswer, gate as permissionGate, getToolClass, PermissionDenied, } from '../permissions/index.js';
 /**
  * Tool-bridge: turns the abstract tool registry into:
  *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
@@ -185,26 +189,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 +328,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 +343,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 +419,41 @@ 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),
+    }));
+}
+/**
+ * α7 L11: tolerant args-parse for the denial fingerprint. Unlike
+ * `parseArgs` (which throws on malformed JSON so the model sees a
+ * parse error), this swallows failures and returns `{}` — the denial
+ * tracker needs SOME key even when the raw payload is unparseable,
+ * because malformed-args spam is itself a pattern operators want to
+ * see in `/permissions denials`.
+ */
+function safeParseForTracking(raw) {
+    if (!raw || raw.trim() === '')
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Use the raw string as the fingerprint payload so repeated
+        // identical malformed dispatches still cluster.
+        return { _rawArgs: raw.slice(0, 512) };
+    }
 }
 function parseArgs(raw) {
     if (!raw || raw.trim() === '')
@@ -433,24 +469,70 @@ 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 { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch, allowSearch, agentDispatch, mcpRegistry, permissionMode, permissionAlwaysCache, permissionAsk, } = input;
     const mcpPrompt = input.mcpPrompt ?? defaultNonInteractiveMcpPrompt;
     const workspaceRoot = input.workspaceRoot ?? ctx.root;
     const planMode = kind === 'plan';
+    const denialTracking = input.denialTracking;
+    // α7 L11: helper that records a denial (when tracking is wired) and
+    // ALWAYS returns an Error whose message includes a compact
+    // `<denial-context>` reminder when the same (tool, args) pair has
+    // already been refused at least once before in this session.
+    //
+    // The reminder is appended to the THROWN message — the engine loop
+    // appends thrown messages to the transcript as tool-result strings,
+    // so the model sees the aggregate the next time it considers a
+    // dispatch. Without this every retry would only see the latest
+    // single-turn reason and could loop indefinitely.
+    //
+    // Best-effort: a hash/clone failure inside the tracker MUST NOT
+    // mask the original refusal. The catch path falls back to a bare
+    // Error with the reason text.
+    const recordDenial = (toolName, args, reason) => {
+        if (!denialTracking)
+            return new Error(reason);
+        try {
+            const record = denialTracking.recordDenial(toolName, args, reason);
+            // Only inject the reminder once the threshold is hit — the very
+            // first denial is the model's first chance to learn, no need to
+            // shout. From the 2nd repeat onwards the model has demonstrated
+            // it is not learning from the single-turn sentinel, so we splice
+            // the aggregate context.
+            if (record.count >= DENIAL_REMINDER_THRESHOLD) {
+                const reminder = buildDenialContext(denialTracking);
+                if (reminder.length > 0) {
+                    return new Error(`${reason}\n\n${reminder}`);
+                }
+            }
+        }
+        catch {
+            // Tracking is best-effort. Fall through to the bare Error so
+            // the refusal still propagates.
+        }
+        return new Error(reason);
+    };
     return async ({ name, arguments: argsRaw }) => {
         // β4 M1/M3: MCP tool names live outside WIRED_TOOLS. They are
         // validated lazily by the dispatcher (the registry knows which
@@ -458,15 +540,64 @@ export function buildExecutor(input) {
         // so a bad `mcp__bogus__foo` does not collide with the native
         // unknown-tool branch.
         const isMcpName = name.startsWith(MCP_TOOL_PREFIX);
+        // α7 L11: parse-or-empty args once up-front so every deny path
+        // below can fingerprint the call against the denial tracker. We
+        // tolerate parse failure — `{}` keys still produce a stable hash
+        // (the model may have sent malformed JSON, but the refusal is
+        // semantic, not parse-driven).
+        const argsForTracking = safeParseForTracking(argsRaw);
         if (!isMcpName && !WIRED_TOOLS.has(name)) {
-            throw new Error(`unknown tool: ${name}`);
+            throw recordDenial(name, argsForTracking, `unknown tool: ${name}`);
         }
-        if (planMode) {
+        // Leak L6 — canonical 4-mode permission gate. Routes the dispatch
+        // decision BEFORE the legacy plan-mode-only enforcement so the new
+        // surface is the source of truth when the caller opted in. Absent
+        // `permissionMode` falls through to the legacy plan-mode branch
+        // (existing semantics preserved for callsites that have not
+        // migrated yet).
+        let hooksBypassed = false;
+        if (permissionMode) {
+            const decision = permissionGate(name, argsRaw, {
+                permissionMode,
+                ...(permissionAlwaysCache ? { alwaysCache: permissionAlwaysCache } : {}),
+            });
+            if (decision.decision === 'deny') {
+                throw new PermissionDenied(name, getToolClass(name), permissionMode, decision.reason);
+            }
+            if (decision.decision === 'ask') {
+                if (!permissionAsk) {
+                    // Non-interactive caller (CI / pipes / agent-as-tool) cannot
+                    // surface a prompt. Collapse to deny so the loop receives a
+                    // deterministic refusal instead of hanging.
+                    throw new PermissionDenied(name, decision.toolClass, permissionMode, `Ask mode: no operator prompt available for ${name} (non-interactive caller)`);
+                }
+                const answer = await permissionAsk({
+                    toolName: name,
+                    toolClass: decision.toolClass,
+                    question: decision.question,
+                    options: decision.options,
+                });
+                const verdict = permissionAlwaysCache
+                    ? applyAskAnswer(permissionAlwaysCache, name, answer)
+                    : applyAskAnswer({ alwaysAllowed: new Set(), alwaysDenied: new Set() }, name, answer);
+                if (verdict.decision === 'deny') {
+                    throw new PermissionDenied(name, decision.toolClass, permissionMode, verdict.reason);
+                }
+                // verdict.decision === 'allow' falls through to dispatch.
+            }
+            else {
+                // allow — honour the bypass flag for the hook layer below.
+                hooksBypassed = decision.hooksBypassed === true;
+            }
+        }
+        else if (planMode) {
+            // Legacy plan-mode enforcement (kind === 'plan') stays in place
+            // for callers that have not opted into the canonical gate.
             // MCP tools are uniformly refused in plan mode (see schema-side
             // rationale in buildToolsSchema). Native tools split via
             // READ_ONLY_TOOLS as before.
             if (isMcpName || !READ_ONLY_TOOLS.has(name)) {
-                throw new Error(`PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
+                throw recordDenial(name, argsForTracking, `PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
             }
         }
         // α6.9: refuse cancelled-token tool dispatch BEFORE PreToolUse
@@ -475,13 +606,18 @@ export function buildExecutor(input) {
         // by `runEngineLoop` as a terminal-cancel signal so the loop
         // returns control to the caller rather than retrying the model.
         if (ctx.cancellation && ctx.cancellation.isAborted) {
-            throw new Error(`OPERATOR_ABORTED: ${name} refused — operator cancelled the dispatch.`);
+            throw recordDenial(name, argsForTracking, `OPERATOR_ABORTED: ${name} refused — operator cancelled the dispatch.`);
         }
         // Fire PreToolUse hooks. The match grammar takes the tool name and
         // (when extractable) the target path. Each new tool dispatch starts a
         // fresh dedup batch so a hook fires once per dispatch, not once per
         // session.
-        if (hooks && sessionId) {
+        //
+        // Leak L6 — bypass mode skips the entire hook layer (PreToolUse +
+        // PostToolUse + PostToolUseFailure). The gate's allow decision
+        // carries the `hooksBypassed` flag; we honour it here so the
+        // executor stays single-pass.
+        if (hooks && sessionId && !hooksBypassed) {
             hooks.resetBatch();
             const path = extractToolPath(name, argsRaw);
             const preCtx = {
@@ -501,7 +637,11 @@ export function buildExecutor(input) {
                 const hook = matchingPreHooks[i];
                 const result = preResults[i];
                 if (hook && result && hook.onFailure === 'block' && !result.ok) {
-                    throw new Error(`HOOK_BLOCKED: PreToolUse hook (${hook.run.slice(0, 80)}) refused ${name} (exit=${result.exitCode})`);
+                    // α7 L11: record the PreToolUse hook denial so the model
+                    // sees the pattern reminder on subsequent turns. Without
+                    // this the model would re-issue the same refused call and
+                    // burn a turn each time before noticing the loop.
+                    throw recordDenial(name, argsForTracking, `HOOK_BLOCKED: PreToolUse hook (${hook.run.slice(0, 80)}) refused ${name} (exit=${result.exitCode})`);
                 }
             }
         }
@@ -558,7 +698,7 @@ export function buildExecutor(input) {
                 // model spawn a write-capable child and break the read-only
                 // contract.
                 if (planMode) {
-                    throw new Error('PLAN_MODE_REFUSED: agent is not allowed in plan mode');
+                    throw recordDenial(name, argsForTracking, 'PLAN_MODE_REFUSED: agent is not allowed in plan mode');
                 }
                 return dispatchAgent(args, agentDispatch);
             }
@@ -566,7 +706,7 @@ export function buildExecutor(input) {
         };
         try {
             const result = await dispatch();
-            if (hooks && sessionId) {
+            if (hooks && sessionId && !hooksBypassed) {
                 const path = extractToolPath(name, argsRaw);
                 await hooks.fire({
                     sessionId,
@@ -579,6 +719,27 @@ export function buildExecutor(input) {
             return result;
         }
         catch (error) {
+            // Leak L6 — surface the PermissionDenied sentinel as a model-
+            // readable message instead of leaking the raw Error type. The
+            // string format is stable so the engine adapter / spec layer
+            // can pattern-match against it.
+            if (error instanceof PermissionDenied) {
+                // PostToolUseFailure fires for visibility unless bypass is on.
+                if (hooks && sessionId && !hooksBypassed) {
+                    await hooks.fire({
+                        sessionId,
+                        event: 'PostToolUseFailure',
+                        tool: name,
+                        payload: {
+                            tool: name,
+                            arguments: argsRaw,
+                            ok: false,
+                            error: error.toModelMessage(),
+                        },
+                    });
+                }
+                throw new Error(error.toModelMessage());
+            }
             // α6.9: re-shape OperatorAbortedError throws from the
             // file-tools layer into the same `OPERATOR_ABORTED:` sentinel
             // the upstream cancellation gate uses so `runEngineLoop` sees
@@ -586,7 +747,7 @@ export function buildExecutor(input) {
             // the abort landed pre-dispatch or mid-tool (e.g. inside the
             // grep file-loop).
             if (error instanceof OperatorAbortedError) {
-                if (hooks && sessionId) {
+                if (hooks && sessionId && !hooksBypassed) {
                     const path = extractToolPath(name, argsRaw);
                     await hooks.fire({
                         sessionId,
@@ -601,9 +762,35 @@ export function buildExecutor(input) {
                         },
                     });
                 }
-                throw new Error(`OPERATOR_ABORTED: ${name} aborted mid-execution.`);
+                throw recordDenial(name, argsForTracking, `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 && !hooksBypassed) {
+                    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 recordDenial(name, argsForTracking, `STALE_READ: ${name} on ${error.path} refused (${error.reason}). Re-read the file with the \`read\` tool, then retry the ${name}.`);
             }
-            if (hooks && sessionId) {
+            if (hooks && sessionId && !hooksBypassed) {
                 const path = extractToolPath(name, argsRaw);
                 await hooks.fire({
                     sessionId,
@@ -643,7 +830,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 +843,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 +851,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 +949,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`);