@pugi/cli 0.1.0-beta.2 → 0.1.0-beta.20

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

@@ -1,5 +1,18 @@
-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';
+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';
+import { RetryBudget, RetryBudgetExhausted, hashArgs } from '../retry-budget/index.js';
 /**
  * Tool-bridge: turns the abstract tool registry into:
  *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
@@ -23,17 +36,72 @@ import { bashToolSync } from '../../tools/bash.js';
 /**
  * Read-only subset surfaced to plan-mode. Mutating tools (write, edit,
  * bash) are intentionally absent so the model rarely tries them.
+ *
+ * β1: task_* + skill + ask_user_question + web_fetch are all read-only
+ * from the workspace's perspective (no file writes), so they stay
+ * available in plan mode. The ledger writes for `task_*` land in
+ * `.pugi/sessions/<id>/tasks.jsonl` which is metadata, not source.
  */
-const READ_ONLY_TOOLS = new Set(['read', 'grep', 'glob']);
+const READ_ONLY_TOOLS = new Set([
+    'read',
+    'grep',
+    'glob',
+    'ask_user_question',
+    'skill',
+    'skills_list',
+    'task_create',
+    'task_get',
+    'task_list',
+    'task_update',
+    'web_fetch',
+    // β1b T4 (2026-05-26): web_search is read-only from the workspace's
+    // perspective (no file writes, no shell). Egress goes through the
+    // Anvil-proxied Brave Search API, gated by the same opt-in posture as
+    // web_fetch. Plan mode keeps the tool available because reading the
+    // web is part of how a plan is researched.
+    'web_search',
+]);
 /**
- * Tools we actually wire today. The registry has more entries
- * (task_*, skill, question) — those route through the runtime layer, not
- * the local filesystem, so they ship in a follow-up PR. M1 cornerstone is
- * the six core tools.
+ * Tools the engine loop dispatches. β1 expands the M1 cornerstone six
+ * (read/write/edit/grep/glob/bash) with task_* + ask_user_question +
+ * skill + skill list + web_fetch. The registry advertises these slots
+ * to the runtime; without dispatcher entries the model would call
+ * "unknown tool" errors.
  */
-const WIRED_TOOLS = new Set(['read', 'write', 'edit', 'grep', 'glob', 'bash']);
-export function buildToolsSchema(kind) {
+const WIRED_TOOLS = new Set([
+    'read',
+    'write',
+    'edit',
+    'grep',
+    'glob',
+    'bash',
+    'ask_user_question',
+    'skill',
+    'skills_list',
+    'task_create',
+    'task_get',
+    'task_list',
+    'task_update',
+    'web_fetch',
+    // β1b T4: see READ_ONLY_TOOLS above.
+    'web_search',
+    // β2 S3 (2026-05-26): real subagent spawn primitive. Only advertised
+    // when buildToolsSchema is called with allowAgent=true (orchestrator
+    // / root Mira context); plan-mode also excludes it because spawning
+    // a write-capable child violates plan-mode's read-only contract.
+    'agent',
+    // β7 L5+T11 (2026-05-26): transactional multi-file edit. Routes
+    // through the same security gate as Layer A/B/C; not advertised in
+    // plan mode (mutation surface).
+    'multi_edit',
+]);
+export function buildToolsSchema(kind, options = { allowFetch: false, allowSearch: false }) {
     const planMode = kind === 'plan';
+    // β4 M1/M3: splice MCP tools BEFORE the native list assembly so the
+    // engine-loop sees them in stable alphabetical order alongside native
+    // tools. We keep the entries appended after the native push so plan-
+    // mode can be filtered by namespace prefix in one place at the end.
+    const mcpDefs = buildMcpToolDefs(options.mcpRegistry);
     const toolDefs = [
         {
             name: 'read',
@@ -72,10 +140,199 @@ export function buildToolsSchema(kind) {
             },
         },
     ];
+    // β1 T1/T6: TodoWrite (Pugi grammar = `task_*`). Append-only ledger
+    // at `.pugi/sessions/<id>/tasks.jsonl`.
+    toolDefs.push({
+        name: 'task_create',
+        description: 'Append a new task to the session todo ledger. Returns the assigned task id and full record. Mirrors Claude Code TodoWrite/create.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['title'],
+            properties: {
+                title: { type: 'string', description: 'Short imperative summary, max 2000 chars.' },
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'in_progress', 'completed', 'cancelled'],
+                    description: 'Initial status. Default pending.',
+                },
+                notes: { type: 'string', description: 'Optional free-form context.' },
+            },
+        },
+    }, {
+        name: 'task_get',
+        description: 'Fetch a single task record by id. Returns null when absent.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id'],
+            properties: { id: { type: 'string' } },
+        },
+    }, {
+        name: 'task_list',
+        description: 'List all tasks for the current session ordered by createdAt ascending.',
+        parameters: { type: 'object', additionalProperties: false, properties: {} },
+    }, {
+        name: 'task_update',
+        description: 'Mutate status/title/notes on an existing task. Throws on unknown id. Append-only journal.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id'],
+            properties: {
+                id: { type: 'string' },
+                title: { type: 'string' },
+                status: {
+                    type: 'string',
+                    enum: ['pending', 'in_progress', 'completed', 'cancelled'],
+                },
+                notes: { type: 'string' },
+            },
+        },
+    });
+    // β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: '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({
+        name: 'skills_list',
+        description: 'List installed skills (global + workspace). Returns name+description+scope.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                scope: { type: 'string', enum: ['all', 'global', 'workspace'] },
+            },
+        },
+    }, {
+        name: 'skill',
+        description: 'Load a skill body by name. Workspace scope wins over global. Body capped at 32KB.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['name'],
+            properties: { name: { type: 'string' } },
+        },
+    });
+    // β1 T5 → β1a r1 (gating fix, 2026-05-26): WebFetch wire-in. Schema
+    // mirrors the existing tool surface in
+    // `apps/pugi-cli/src/tools/web-fetch.ts`. SSRF guard runs inside the
+    // tool itself, but advertising the tool to the model when the tenant
+    // has not opted in is itself a privacy leak — the model could infer
+    // URL patterns and try to exfiltrate via the refused call's argument
+    // bytes. Only push the schema entry when the operator has explicitly
+    // enabled fetch (either via `.pugi/settings.json::web.fetch.enabled`
+    // or via `--allow-fetch`).
+    if (options.allowFetch) {
+        toolDefs.push({
+            name: 'web_fetch',
+            description: 'One-shot HTTP GET against an operator-supplied URL. Response is parsed to Markdown and wrapped in <untrusted-content> sentinel. Gated off by default.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['url'],
+                properties: {
+                    url: { type: 'string', description: 'Fully-qualified http(s) URL.' },
+                },
+            },
+        });
+    }
+    // β1b T4 (2026-05-26): web_search advertisement. Same off-by-default
+    // privacy posture as web_fetch — the query string itself is an egress
+    // event that can leak operator intent to the upstream Brave Search
+    // backend. The tool dispatcher applies SSRF guards (no localhost via
+    // the Anvil proxy URL), rate-limits (5 req/min per session), and caps
+    // the result payload at 1 MiB. Sentinel-wrapped results so the model
+    // treats every snippet as data, not instructions.
+    if (options.allowSearch) {
+        toolDefs.push({
+            name: 'web_search',
+            description: 'Search the web via Brave Search (Anvil-proxied). Returns up to 10 sentinel-wrapped {title, url, snippet} results. Rate-limited to 5 calls/min per session. Gated off by default.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['query'],
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'Search query, max 256 chars. Plain text — no operators.',
+                    },
+                    count: {
+                        type: 'integer',
+                        description: 'Optional result count (1..10, default 10).',
+                    },
+                },
+            },
+        });
+    }
+    // β2 S3 (2026-05-26): `agent` tool — subagent spawn primitive.
+    // Off by default; surfaced only when the caller explicitly opts in
+    // (orchestrator parents pass allowAgent=true via the engine adapter).
+    // Plan mode FORCES the tool off regardless because a write-capable
+    // child would violate plan-mode's read-only contract.
+    if (options.allowAgent && !planMode) {
+        toolDefs.push({
+            name: 'agent',
+            description: 'Spawn a specialist subagent under a Cyber-Zoo brand persona. '
+                + 'Role selects the persona + isolation tier: '
+                + 'researcher/reviewer/architect are read-only, verifier reads + runs tests, '
+                + 'coder/release/devops/design_qa get write + bash. '
+                + 'The child runs a fresh Anvil engine loop with its own transcript and '
+                + 'returns a JSON envelope (filesChanged, toolCallCount, status, summary). '
+                + 'Use this when the work needs a specialist persona OR write isolation via a scratch worktree.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['role', 'brief'],
+                properties: {
+                    role: {
+                        type: 'string',
+                        enum: [
+                            'orchestrator',
+                            'architect',
+                            'coder',
+                            'verifier',
+                            'reviewer',
+                            'researcher',
+                            'release',
+                            'devops',
+                            'design_qa',
+                        ],
+                        description: 'SubagentRole — selects persona + isolation tier.',
+                    },
+                    brief: {
+                        type: 'string',
+                        maxLength: 8000,
+                        description: 'One-paragraph task description forwarded to the child as the user prompt. '
+                            + 'Be concrete: include filenames, expected behavior, and acceptance criteria.',
+                    },
+                    isolation: {
+                        type: 'string',
+                        enum: ['worktree', 'shared_fs', 'auto'],
+                        description: 'Optional override. `worktree` forces a scratch git worktree for write isolation; '
+                            + '`shared_fs` forces same-tree execution; `auto` (default) defers to the role tier.',
+                    },
+                },
+            },
+        });
+    }
     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,
@@ -87,7 +344,10 @@ export function buildToolsSchema(kind) {
             },
         }, {
             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,
@@ -109,9 +369,92 @@ export function buildToolsSchema(kind) {
                     command: { type: 'string', description: 'Single shell command to execute.' },
                 },
             },
+        }, 
+        // β7 L5+T11 (2026-05-26): transactional multi-file edit. Either
+        // all entries land or none do — failures roll the workspace back
+        // via the same journal + snapshot machinery the dispatcher uses.
+        // Cap is 50 entries; beyond that the operator (or model) should
+        // split the refactor or use Layer C rewrites.
+        {
+            name: 'multi_edit',
+            description: 'Apply an ordered batch of single-occurrence file edits as one transaction. ' +
+                'Each entry is {file, oldString, newString} like the `edit` tool. Either every ' +
+                'edit lands or none do — a failure rolls the workspace back to the pre-dispatch ' +
+                'state via journal + snapshot. Cap 50 edits per call. Use this for coordinated ' +
+                'refactors (rename across files, add an import to many modules).',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['edits'],
+                properties: {
+                    edits: {
+                        type: 'array',
+                        minItems: 1,
+                        maxItems: 50,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['file', 'oldString', 'newString'],
+                            properties: {
+                                file: { type: 'string', description: 'Workspace-relative file path.' },
+                                oldString: { type: 'string', description: 'Verbatim substring; must be unique in the pre-edit file.' },
+                                newString: { type: 'string', description: 'Replacement string. Empty string means delete.' },
+                            },
+                        },
+                    },
+                },
+            },
         });
     }
-    return toolDefs;
+    // β4 M1/M3: append MCP tools last. Plan mode skips them because every
+    // MCP tool is treated as medium-risk until per-tool annotations land
+    // in the MCP spec; treating MCP read-as-read would require server-
+    // side metadata we cannot trust today (a misconfigured server could
+    // claim `read` while running a destructive op).
+    if (!planMode) {
+        for (const def of mcpDefs) {
+            toolDefs.push({
+                name: def.name,
+                description: def.description,
+                parameters: def.parameters,
+            });
+        }
+    }
+    // α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() === '')
@@ -127,25 +470,139 @@ function parseArgs(raw) {
         throw new Error(`invalid JSON in tool arguments: ${error.message}`);
     }
 }
+/**
+ * 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') {
-        throw new Error(`tool argument "${key}" must be a string`);
-    }
-    return v;
+    if (typeof v === 'string')
+        return v;
+    throw new Error(`tool argument "${key}" must be a string`);
 }
 export function buildExecutor(input) {
-    const { kind, ctx, hooks, sessionId } = input;
+    const { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch, allowSearch, agentDispatch, mcpRegistry, permissionMode, permissionAlwaysCache, permissionAsk, } = input;
+    // Leak L31: per-cycle budget. Default to a fresh instance scoped to
+    // this executor's closure lifetime; tests pass their own.
+    const retryBudget = input.retryBudget ?? new RetryBudget();
+    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 }) => {
-        if (!WIRED_TOOLS.has(name)) {
-            throw new Error(`unknown tool: ${name}`);
+        // β4 M1/M3: MCP tool names live outside WIRED_TOOLS. They are
+        // validated lazily by the dispatcher (the registry knows which
+        // names are actually exposed). The namespace check happens FIRST
+        // 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 recordDenial(name, argsForTracking, `unknown tool: ${name}`);
+        }
+        // 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;
+            }
         }
-        if (planMode && !READ_ONLY_TOOLS.has(name)) {
-            // Sentinel recognised by `runEngineLoop` — terminates the loop
-            // with status `tool_refused`. The CLI surfaces this as a blocked
-            // outcome, not a failure, because plan mode is doing its job.
-            throw new Error(`PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
+        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 recordDenial(name, argsForTracking, `PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
+            }
         }
         // α6.9: refuse cancelled-token tool dispatch BEFORE PreToolUse
         // hooks fire so a cancelled brief never reaches user-defined
@@ -153,13 +610,32 @@ 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.`);
+        }
+        // Leak L31 — per-cycle tool retry budget. Same tool + same canonical
+        // args = same bucket. Once the cap is hit we throw a typed sentinel
+        // so the model is forced out of a repair loop. We gate AFTER
+        // permission (denied calls do not burn budget) and BEFORE PreToolUse
+        // hooks (hook-blocked retries DO count — the model still issued the
+        // same call). The `recordAttempt` fires unconditionally so warn-only
+        // mode (PUGI_RETRY_BUDGET_DISABLED=1) still tracks the pattern for
+        // diagnostics.
+        const argHash = hashArgs(argsRaw);
+        const budgetDecision = retryBudget.shouldAllow(name, argHash);
+        retryBudget.recordAttempt(name, argHash);
+        if (!budgetDecision.allowed) {
+            throw new RetryBudgetExhausted(name, budgetDecision.cap, argHash);
         }
         // 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 = {
@@ -179,17 +655,76 @@ 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})`);
                 }
             }
         }
-        const args = parseArgs(argsRaw);
+        // β4 M1/M3: MCP dispatch deferred to the `dispatch` closure below so
+        // PostToolUse / PostToolUseFailure hooks observe MCP calls just like
+        // native calls. The dispatcher does its own argument parsing — MCP
+        // arg errors surface as model-visible `[MCP dispatch error] ...`
+        // strings, not throws.
+        const args = isMcpName ? {} : parseArgs(argsRaw);
         const dispatch = async () => {
+            if (isMcpName) {
+                return dispatchMcpTool({
+                    name,
+                    argumentsRaw: argsRaw,
+                    registry: mcpRegistry,
+                    prompt: mcpPrompt,
+                });
+            }
+            // β1 T1/T2/T3/T5/T6: async-dispatch the new tool surface.
+            // task_*, skill, ask_user_question, web_fetch all live behind
+            // an async or async-compatible boundary.
+            if (name === 'task_create' || name === 'task_get' || name === 'task_list' || name === 'task_update') {
+                return dispatchTaskTool(name, args, { workspaceRoot, sessionId });
+            }
+            if (name === 'ask_user_question') {
+                return dispatchAskUser(args, { interactive: Boolean(interactive), bridge: askUserBridge });
+            }
+            if (name === 'skill' || name === 'skills_list') {
+                return dispatchSkillTool(name, args, { workspaceRoot });
+            }
+            if (name === 'web_fetch') {
+                return dispatchWebFetch(args, { ctx, allowFetch: Boolean(allowFetch) });
+            }
+            if (name === 'web_search') {
+                return dispatchWebSearch(args, {
+                    ctx,
+                    allowSearch: Boolean(allowSearch),
+                    sessionId,
+                });
+            }
+            if (name === 'multi_edit') {
+                return dispatchMultiEdit(args, ctx);
+            }
+            if (name === 'agent') {
+                // β2a r1 (Backend Architect P1, 2026-05-26): defense in depth.
+                // `WIRED_TOOLS` includes `agent`, so a plan-mode model that
+                // fabricates an `agent` tool call would otherwise be routed
+                // here. The plan-mode refusal at the top of the executor only
+                // fires for tools NOT in READ_ONLY_TOOLS; `agent` is
+                // intentionally absent from both sets, so we explicitly refuse
+                // it here. This pairs with `native-pugi.ts` hard-gating
+                // `agentDispatch` itself off in plan mode — without this
+                // defensive throw a future schema bug could let a plan-mode
+                // model spawn a write-capable child and break the read-only
+                // contract.
+                if (planMode) {
+                    throw recordDenial(name, argsForTracking, 'PLAN_MODE_REFUSED: agent is not allowed in plan mode');
+                }
+                return dispatchAgent(args, agentDispatch);
+            }
             return dispatchTool(name, args, ctx);
         };
         try {
             const result = await dispatch();
-            if (hooks && sessionId) {
+            if (hooks && sessionId && !hooksBypassed) {
                 const path = extractToolPath(name, argsRaw);
                 await hooks.fire({
                     sessionId,
@@ -202,6 +737,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
@@ -209,7 +765,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,
@@ -224,9 +780,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,
@@ -342,4 +924,209 @@ function dispatchTool(name, args, ctx) {
             throw new Error(`unhandled tool: ${name}`);
     }
 }
+/* ----------------------------- β1 dispatchers ----------------------------- */
+function dispatchTaskTool(name, args, opts) {
+    if (!opts.sessionId) {
+        throw new Error(`${name}: no sessionId in scope — task ledger requires a session`);
+    }
+    const tctx = { workspaceRoot: opts.workspaceRoot, sessionId: opts.sessionId };
+    switch (name) {
+        case 'task_create': {
+            const title = requireString(args, 'title');
+            const status = optionalString(args, 'status');
+            const notes = optionalString(args, 'notes');
+            const record = taskCreate(tctx, {
+                title,
+                ...(status !== undefined ? { status: status } : {}),
+                ...(notes !== undefined ? { notes } : {}),
+            });
+            return JSON.stringify(record);
+        }
+        case 'task_get': {
+            const id = requireString(args, 'id');
+            const record = taskGet(tctx, id);
+            return record ? JSON.stringify(record) : 'null';
+        }
+        case 'task_list': {
+            const list = taskList(tctx);
+            return JSON.stringify(list);
+        }
+        case 'task_update': {
+            const id = requireString(args, 'id');
+            const title = optionalString(args, 'title');
+            const status = optionalString(args, 'status');
+            const notes = optionalString(args, 'notes');
+            const record = taskUpdate(tctx, {
+                id,
+                ...(title !== undefined ? { title } : {}),
+                ...(status !== undefined ? { status: status } : {}),
+                ...(notes !== undefined ? { notes } : {}),
+            });
+            return JSON.stringify(record);
+        }
+    }
+}
+async function dispatchAskUser(args, opts) {
+    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`);
+        }
+        return o;
+    });
+    const multiSelect = args['multiSelect'] === true;
+    const result = await askUser({ interactive: opts.interactive, ...(opts.bridge ? { bridge: opts.bridge } : {}) }, { question, options, multiSelect });
+    return result.envelope;
+}
+async function dispatchSkillTool(name, args, opts) {
+    if (name === 'skills_list') {
+        const scopeArg = optionalString(args, 'scope');
+        const scope = scopeArg === 'global' || scopeArg === 'workspace' ? scopeArg : 'all';
+        const list = skillList({ workspaceRoot: opts.workspaceRoot }, { scope });
+        return JSON.stringify(list);
+    }
+    // name === 'skill' (invoke).
+    // β1a r1 (2026-05-26): `skillInvoke` is now async — it re-verifies
+    // the trust manifest sha256 against the on-disk body on every call.
+    // Bubble up `await` so a post-install tamper surfaces as a tool
+    // error the model sees, not a swallowed Promise<SkillInvokeResult>.
+    const skName = requireString(args, 'name');
+    const result = await skillInvoke({ workspaceRoot: opts.workspaceRoot }, { name: skName });
+    return JSON.stringify(result);
+}
+async function dispatchWebFetch(args, opts) {
+    const url = requireString(args, 'url');
+    const result = await webFetchTool({ url }, {
+        settings: opts.ctx.settings,
+        allowFetch: opts.allowFetch,
+    });
+    return JSON.stringify(result);
+}
+async function dispatchWebSearch(args, opts) {
+    const query = requireString(args, 'query');
+    // `count` is optional integer 1..10. Validate here so the tool layer
+    // gets a clean value (the tool clamps internally too — defense in
+    // depth, since the model can pass anything).
+    let count;
+    if (args['count'] !== undefined && args['count'] !== null) {
+        const n = args['count'];
+        if (typeof n !== 'number' || !Number.isInteger(n)) {
+            throw new Error('web_search: count must be an integer');
+        }
+        count = n;
+    }
+    const result = await webSearchTool({ query, ...(count !== undefined ? { count } : {}) }, {
+        settings: opts.ctx.settings,
+        allowSearch: opts.allowSearch,
+        sessionId: opts.sessionId,
+    });
+    return JSON.stringify(result);
+}
+/**
+ * β2 S3 dispatch — wire the model-emitted `agent` tool call to the
+ * real subagent spawn primitive. When the executor was built without
+ * `agentDispatch` (e.g. a child loop, or a parent that explicitly
+ * disabled subagent spawn), the call is refused with a structured
+ * envelope so the model can adapt instead of crashing the parent loop.
+ */
+async function dispatchAgent(args, opts) {
+    if (!opts) {
+        // No dispatch context — return a structured refusal envelope.
+        // This matches the agent-tool.ts no-engine-client path and lets
+        // the model decide whether to retry inline or abandon the
+        // delegation. Throwing here would terminate the parent on a tool
+        // error frame which is the wrong UX when the issue is config.
+        return JSON.stringify({
+            ok: false,
+            status: 'failed',
+            summary: 'agent tool refused: dispatch not wired in this engine adapter. '
+                + 'Re-run from a parent loop with agentDispatch configured.',
+        });
+    }
+    const parsed = parseAgentArgs(args);
+    const result = await agentTool(parsed, {
+        session: opts.parentSession,
+        engineClient: opts.engineClient,
+        ...(opts.parentBudgetRemaining
+            ? { parentBudgetRemaining: opts.parentBudgetRemaining }
+            : {}),
+    });
+    return JSON.stringify(result);
+}
+function parseAgentArgs(args) {
+    // Surface a clean error message to the model when the args don't
+    // match the schema. agentTool itself also validates via Zod; this
+    // pre-parse layer keeps the error stack short.
+    const role = requireString(args, 'role');
+    const brief = requireString(args, 'brief');
+    const isolationRaw = optionalString(args, 'isolation');
+    const out = {
+        role: role,
+        brief,
+        ...(isolationRaw ? { isolation: isolationRaw } : {}),
+    };
+    return out;
+}
+function optionalString(obj, key) {
+    const v = obj[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== 'string') {
+        throw new Error(`tool argument "${key}" must be a string when present`);
+    }
+    return v;
+}
+/**
+ * β7 L5+T11: dispatch the model-emitted `multi_edit` tool call. The
+ * tool returns a structured result envelope; we serialize it to JSON
+ * for the engine loop. A refused dispatch (security, no_match,
+ * ambiguous_match, etc.) surfaces as `ok: false` in the envelope —
+ * the model can re-strategise rather than crashing the loop.
+ */
+function dispatchMultiEdit(args, ctx) {
+    const raw = args['edits'];
+    if (!Array.isArray(raw)) {
+        throw new Error('multi_edit: edits must be an array');
+    }
+    const edits = raw.map((item, i) => {
+        if (!item || typeof item !== 'object') {
+            throw new Error(`multi_edit: edits[${i}] must be an object`);
+        }
+        const obj = item;
+        const file = obj['file'];
+        const oldString = obj['oldString'];
+        const newString = obj['newString'];
+        if (typeof file !== 'string') {
+            throw new Error(`multi_edit: edits[${i}].file must be a string`);
+        }
+        if (typeof oldString !== 'string') {
+            throw new Error(`multi_edit: edits[${i}].oldString must be a string`);
+        }
+        if (typeof newString !== 'string') {
+            throw new Error(`multi_edit: edits[${i}].newString must be a string`);
+        }
+        return { file, oldString, newString };
+    });
+    const result = multiEdit(ctx, edits);
+    return JSON.stringify(result);
+}
 //# sourceMappingURL=tool-bridge.js.map