@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.10

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

@@ -1,2173 +0,0 @@
-import { editTool, globTool, grepTool, OperatorAbortedError, readTool, StaleReadError, writeTool, } from '../../tools/file-tools.js';
-import { bashToolSync } from '../../tools/bash.js';
-import { powerShellToolSync } from '../../tools/powershell.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 { dispatchTodoWrite, todoWriteJsonSchema, } from '../../tools/todo-write.js';
-// Tool gap pack : Brief/Sleep/SyntheticOutput/
-// EnterWorktree/ExitWorktree. Each tool exports a Zod-free hand-rolled
-// JSON-schema fragment + a sentinel-returning dispatcher, matching the
-// `todo_write` / `ask_user_question` conventions.
-import { briefJsonSchema, dispatchBrief } from '../../tools/brief.js';
-import { cronCreateJsonSchema, cronDeleteJsonSchema, cronListJsonSchema, dispatchCronCreate, dispatchCronDelete, dispatchCronList, } from '../../tools/cron.js';
-import { dispatchVerifyPlanExecution, verifyPlanExecutionJsonSchema, } from '../../tools/verify-plan-execution.js';
-import { dispatchSleep, sleepJsonSchema } from '../../tools/sleep.js';
-import { dispatchSyntheticOutput, syntheticOutputJsonSchema, } from '../../tools/synthetic-output.js';
-import { dispatchEnterWorktree, enterWorktreeJsonSchema, } from '../../tools/enter-worktree.js';
-import { dispatchExitWorktree, exitWorktreeJsonSchema, } from '../../tools/exit-worktree.js';
-import { webFetchTool } from '../../tools/web-fetch.js';
-import { webSearchTool } from '../../tools/web-search.js';
-// Phase 1 runtime evidence pack (PUGI-291..295): server_* + http_request
-// dispatchers + JSON schema fragments. Every primitive returns a
-// sentinel string on validation failure (sleep/brief convention) so
-// the engine adapter surfaces it as a recoverable tool result.
-import { dispatchHttpRequest, httpRequestJsonSchema, } from '../../tools/http-request.js';
-import { dispatchServerHealth, dispatchServerLogs, dispatchServerStart, dispatchServerStop, serverHealthJsonSchema, serverLogsJsonSchema, serverStartJsonSchema, serverStopJsonSchema, } from '../../tools/server-tools.js';
-import { agentTool } from '../../tools/agent-tool.js';
-import { multiEdit } from '../../tools/multi-edit.js';
-import { recordVerificationCall } from '../session.js';
-import { detectVerificationCommand, tailStderr } from './verification-patterns.js';
-import { buildMcpToolDefs, defaultNonInteractiveMcpPrompt, dispatchMcpTool, MCP_TOOL_PREFIX, } from '../../tools/mcp-tool.js';
-import { firePostToolUseFailureChain } from '../hook-chains.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';
-import { runPostEditDiagnostics, } from '../lsp/post-edit-diagnostics.js';
-// PUGI-78 Phase 1: symbols.* tool wrappers + LSP client cache. The
-// dispatcher resolves the LSP client by `lang` via `getOrStartLspClient`
-// (cold-start cost amortised across the session) and hands it to the
-// matching wrapper. The wrappers serialise the result for the engine
-// envelope.
-import { getOrStartLspClient } from '../lsp/cache.js';
-import { symbolsCallHierarchyTool, symbolsCodeActionsTool, symbolsDiagnosticsTool, symbolsFindDefinitionTool, symbolsFindReferencesTool, symbolsFormatTool, symbolsHoverTool, symbolsImplementationsTool, symbolsListInFileTool, symbolsRenameTool, symbolsSignatureTool, symbolsTypeDefinitionTool, symbolsWorkspaceSymbolsTool, } from '../../tools/lsp-tools.js';
-import { getGlobalSymbolCache } from '../lsp/symbol-cache.js';
-/**
- * Tool-bridge: turns the abstract tool registry into:
- *  1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
- *  2. A single executor callback that dispatches each tool_call to the
- *     concrete `file-tools.ts` handler under workspace permissions.
- *
- * The bridge enforces two CLI-side invariants that the runtime cannot:
- *  - Plan-mode refusal. When `kind === 'plan'`, the executor refuses
- *    write/edit/bash by throwing `PLAN_MODE_REFUSED:<tool>` (sentinel
- *    recognised by `runEngineLoop` to terminate with status
- *    `tool_refused`). The schema also omits the mutating tools so the
- *    model is unlikely to attempt them in the first place.
- *  - Argument validation. Each call's `arguments` string is JSON-parsed
- *    and shape-checked here; bad JSON or missing fields are surfaced
- *    to the model as a tool error string so it can correct itself.
- *
- * The bridge does NOT touch session.ts directly — `file-tools.ts`
- * already records every call. The engine adapter wires a hook layer on
- * top that surfaces tool events into the engine's status stream.
- */
-/**
- * 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',
-    'ask_user_question',
-    'skill',
-    'skills_list',
-    'task_create',
-    'task_get',
-    'task_list',
-    'task_update',
-    // `todo_write` writes to `.pugi/todos.json`
-    // — metadata, not source. From the workspace's perspective it is
-    // read-only (no source mutation), so plan-mode keeps the tool
-    // available: planning a refactor frequently means writing the
-    // todo board BEFORE picking which file to touch.
-    'todo_write',
-    // Tool gap pack : `brief` persists structured
-    // status notes to `.pugi/briefs/<session>.jsonl`. Like `todo_write`
-    // the writes land in metadata, not source, so plan mode keeps the
-    // tool available — planning frequently means emitting a "planning"
-    // brief first.
-    'brief',
-    // Backlog #5 P0 : verify_plan_execution reads session
-    // audit log (metadata, not source). Safe in plan mode — a planning
-    // loop needs to verify its plan-capture steps before any writes.
-    'verify_plan_execution',
-    // Backlog PUGI-7: cron_* tool family persists to `.pugi/cron/<name>.json`
-    // — metadata, not source. Plan mode keeps these available because
-    // planning a recurring workflow ("every Monday morning run the triple-
-    // review") is a configuration step the model should be able to take
-    // before any source mutation. The actual scheduler runner is gated by
-    // an explicit `pugi routines run` opt-in OUTSIDE the model surface, so
-    // even an aggressive plan-mode loop can only EDIT the routine registry
-    // here, never spawn a tick.
-    'cron_create',
-    'cron_delete',
-    'cron_list',
-    // Tool gap pack : `sleep` is a no-op as far as the
-    // workspace is concerned (wall-clock delay only). Plan mode keeps it
-    // available so a planning loop can throttle its own polling.
-    'sleep',
-    'web_fetch',
-    // β1b T4 : 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',
-    // PUGI-78 Phase 1: symbols.* namespace is read-only in Phase 1
-    // (rename / format / code_actions return PREVIEW edits, the
-    // dispatcher applies via apply_patch in Phase 2). Plan-mode KEEPS
-    // these tools available — navigation / outline / call-hierarchy
-    // questions are the bread-and-butter of a planning loop, and the
-    // surface explicitly never mutates source in this phase. When Phase
-    // 2 lifts to "apply on confirm", the apply path moves OUT of
-    // symbols.* and into apply_patch, which is already plan-mode-gated.
-    'symbols_call_hierarchy',
-    'symbols_code_actions',
-    'symbols_diagnostics',
-    'symbols_find_definition',
-    'symbols_find_references',
-    'symbols_format',
-    'symbols_hover',
-    'symbols_implementations',
-    'symbols_list_in_file',
-    'symbols_rename',
-    'symbols_signature',
-    'symbols_type_definition',
-    'symbols_workspace_symbols',
-]);
-/**
- * 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',
-    // PowerShell tool for Windows-first workflows.
-    // Same bash permission class — destructive-pattern classifier applies.
-    // Plan mode excludes shell tools by design (read-only); the planMode
-    // check on the schema side already handles that, so we just list it
-    // alongside 'bash' here.
-    'powershell',
-    'ask_user_question',
-    'skill',
-    'skills_list',
-    'task_create',
-    'task_get',
-    'task_list',
-    'task_update',
-    // see READ_ONLY_TOOLS above for the rationale.
-    'todo_write',
-    // Tool gap pack: see READ_ONLY_TOOLS above for `brief` / `sleep`.
-    'brief',
-    // Backlog #5 P0 : verify_plan_execution anti-fake-dispatch gate.
-    'verify_plan_execution',
-    // Backlog PUGI-7 : cron_* tool family (see READ_ONLY_TOOLS rationale).
-    'cron_create',
-    'cron_delete',
-    'cron_list',
-    'sleep',
-    // Tool gap pack: scratch-worktree primitives. Not in
-    // READ_ONLY_TOOLS — they mutate workspace state (a new git worktree
-    // is a workspace change even though the touched subtree is
-    // `.pugi`-scoped). Plan mode excludes them just like write/edit/bash.
-    'enter_worktree',
-    'exit_worktree',
-    // Tool gap pack: experimental engine-only echo helper. Gated
-    // behind allowSyntheticOutput; the schema layer omits it unless the
-    // caller opted in, but we list the name here so a deliberately-opted
-    // executor passes the WIRED_TOOLS guard.
-    'synthetic_output',
-    'web_fetch',
-    // β1b T4: see READ_ONLY_TOOLS above.
-    'web_search',
-    // β2 S3 : real subagent spawn primitive. Only advertised
-    // when buildToolsSchema is called with allowAgent=true (orchestrator
-    // / root Pugi context); plan-mode also excludes it because spawning
-    // a write-capable child violates plan-mode's read-only contract.
-    'agent',
-    // β7 L5+T11 : transactional multi-file edit. Routes
-    // through the same security gate as Layer A/B/C; not advertised in
-    // plan mode (mutation surface).
-    'multi_edit',
-    // PUGI-78 Phase 1: symbols.* namespace (13 LSP-bridged tools). All
-    // read-only in Phase 1 — `rename` / `format` / `code_actions`
-    // return PREVIEW edits; the dispatcher applies via apply_patch in
-    // Phase 2 (PUGI-134). The executor dispatch wires each name to the
-    // matching `symbols*Tool` wrapper in `src/tools/lsp-tools.ts`.
-    'symbols_call_hierarchy',
-    'symbols_code_actions',
-    'symbols_diagnostics',
-    'symbols_find_definition',
-    'symbols_find_references',
-    'symbols_format',
-    'symbols_hover',
-    'symbols_implementations',
-    'symbols_list_in_file',
-    'symbols_rename',
-    'symbols_signature',
-    'symbols_type_definition',
-    'symbols_workspace_symbols',
-    // Phase 1 runtime evidence pack (PUGI-291..295): server_* + http_request.
-    // Off by default in plan mode (mutation surface for start/stop; even
-    // health/logs/http_request cross the plan-mode read-only contract
-    // because they are runtime evidence primitives, not source reads).
-    'http_request',
-    'server_health',
-    'server_logs',
-    'server_start',
-    'server_stop',
-]);
-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',
-            description: 'Read the contents of a workspace file. Required before edit on a file. Returns the full UTF-8 text. Workspace-scoped: paths must be relative to the workspace root.',
-            parameters: {
-                type: 'object',
-                additionalProperties: false,
-                required: ['path'],
-                properties: {
-                    path: { type: 'string', description: 'Workspace-relative file path.' },
-                },
-            },
-        },
-        {
-            name: 'grep',
-            description: 'Substring-match every workspace file. Returns up to 200 matches with {path, line, text}. Canonical arg: `query`. Aliases accepted: text, pattern, q, search.',
-            parameters: {
-                type: 'object',
-                additionalProperties: true,
-                properties: {
-                    query: { type: 'string', description: 'Substring to search for (canonical).' },
-                    text: { type: 'string', description: 'Alias for query.' },
-                    pattern: { type: 'string', description: 'Alias for query.' },
-                    q: { type: 'string', description: 'Alias for query.' },
-                    search: { type: 'string', description: 'Alias for query.' },
-                },
-            },
-        },
-        {
-            name: 'glob',
-            description: 'List files matching a glob pattern (workspace-scoped, node_modules / dist / .git / .pugi excluded). Up to 500 paths.',
-            parameters: {
-                type: 'object',
-                additionalProperties: false,
-                required: ['pattern'],
-                properties: {
-                    pattern: { type: 'string', description: 'Glob pattern, e.g. "src/**/*.ts".' },
-                },
-            },
-        },
-    ];
-    // β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 the standard tool 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' },
-            },
-        },
-    });
-    // `todo_write` — batch TodoWrite mirror of
-    // the upstream tool's upstream tool. Whereas `task_*` above is granular
-    // (one mutation per call, JSONL append, session-scoped),
-    // `todo_write` snapshots the FULL board in one call, JSON snapshot
-    // at `.pugi/todos.json`, workspace-scoped. Enforces the single-
-    // in-progress invariant at dispatch time: a batch with >1
-    // `in_progress` rejects with `TODO_INVARIANT_VIOLATED` and the
-    // on-disk board is left unchanged.
-    toolDefs.push({
-        name: 'todo_write',
-        description: 'Replace the workspace todo board (batch snapshot, not incremental). Emit the FULL todo list every call. ' +
-            'At most ONE item may carry status="in_progress" — violations reject with TODO_INVARIANT_VIOLATED. ' +
-            'Persisted atomically to .pugi/todos.json. Mirrors the standard tool TodoWrite verbatim.',
-        parameters: todoWriteJsonSchema,
-    });
-    // Tool gap pack : `brief` — structured operator
-    // progress note. JSONL-append к `.pugi/briefs/<session>.jsonl` via
-    // the atomic tmp+rename pattern. Plan-mode safe (metadata only, no
-    // source mutation).
-    toolDefs.push({
-        name: 'brief',
-        description: 'Emit a short structured progress note to the operator. Use INSTEAD of narrating in prose ' +
-            'when you want to surface "what I am doing now". One JSON record per call, persisted к ' +
-            '.pugi/briefs/<session>.jsonl. Required: headline (<=120 chars), status (planning|working|blocked|done). ' +
-            'Optional: detail (<=2000 chars).',
-        parameters: briefJsonSchema,
-    });
-    // Backlog PUGI-7: cron_* tool family. Three tools that expose the
-    // local routine registry to the persona:
-    //   - cron_create — register a recurring routine. Writes one JSON
-    //     document per routine to `.pugi/cron/<name>.json` via atomic
-    //     tmp+rename. Replacing an existing name is intentional (the
-    //     name is the idempotency key).
-    //   - cron_delete — remove a routine by name. Idempotent.
-    //   - cron_list — list every registered routine, sorted by name.
-    // The scheduler runner (CronScheduler in core/cron/scheduler.ts) is
-    // OUT of this surface — these tools only EDIT the registry; ticking
-    // is gated by an explicit `pugi routines run` opt-in.
-    toolDefs.push({
-        name: 'cron_create',
-        description: 'Register a recurring routine. Required: name (slug), cronExpression (5-field), command (shell string). ' +
-            'Optional: args (string[]), description. Re-registering the same name REPLACES the prior routine. ' +
-            'Persisted atomically to .pugi/cron/<name>.json. Returns {ok, routine, replaced}.',
-        parameters: cronCreateJsonSchema,
-    }, {
-        name: 'cron_delete',
-        description: 'Remove a routine by name. Idempotent — deleting an unknown name returns ok:true with removed:false. ' +
-            'Returns {ok, removed, name}.',
-        parameters: cronDeleteJsonSchema,
-    }, {
-        name: 'cron_list',
-        description: 'List every registered routine, sorted by name. Zero routines returns {routines:[]} — never an error. ' +
-            'No arguments.',
-        parameters: cronListJsonSchema,
-    });
-    // Backlog #5 P0 : verify_plan_execution — anti-fake-dispatch gate.
-    // Reads the session audit log (metadata only, no source mutation). Plan-mode
-    // safe: a plan-loop frequently needs к verify its plan-capture steps before
-    // any write turn fires. Surface это as a tool the model can call right
-    // before emitting а "done" message on multi-step turns.
-    toolDefs.push({
-        name: 'verify_plan_execution',
-        description: 'Assert that every step in a previously-stated plan actually executed. ' +
-            'Reads the session audit log (tool calls + file mutations recorded this session) ' +
-            'and checks each step\'s declared requirements. Returns { status: "verified" | "gap", gaps: [...] }. ' +
-            'When status is "gap" the engine loop continues so the model can fill the missing ' +
-            'steps or explicitly explain why they were skipped. Call this BEFORE emitting а ' +
-            'final "done" message when you stated а multi-step plan at the start of the turn.',
-        parameters: verifyPlanExecutionJsonSchema,
-    });
-    // Tool gap pack : `sleep` — wall-clock pause primitive.
-    // Counts against --max-turns like any other dispatch; the model should
-    // prefer a real poll loop (read + grep + retry) over blind sleep.
-    toolDefs.push({
-        name: 'sleep',
-        description: 'Pause the engine loop for an integer number of seconds (1..600). ' +
-            'Counts against the turn budget. Prefer a real poll loop over blind sleep — ' +
-            'this tool exists only for fixed cooldowns the operator owns.',
-        parameters: sleepJsonSchema,
-    });
-    if (!planMode) {
-        // Tool gap pack : scratch-worktree primitives.
-        // `enter_worktree` materialises a fresh git worktree at
-        // `.pugi/worktrees/<taskId>/` so a long task can land its edits in
-        // isolation; `exit_worktree` is the cleanup primitive. Both are
-        // workspace mutations, so plan mode excludes them.
-        toolDefs.push({
-            name: 'enter_worktree',
-            description: 'Open a scratch git worktree at .pugi/worktrees/<taskId>/ for write-isolated work. ' +
-                'Required: taskId (lowercase slug). Optional: baseRef (defaults to main). ' +
-                'Returns { worktreePath, branchName }. Pair with exit_worktree for cleanup.',
-            parameters: enterWorktreeJsonSchema,
-        });
-        toolDefs.push({
-            name: 'exit_worktree',
-            description: 'Tear down a scratch worktree previously opened by enter_worktree. ' +
-                'The worktreePath MUST live under <workspaceRoot>/.pugi/worktrees/ — anything else refuses. ' +
-                'Runs `git worktree remove --force` then rmSync. Idempotent.',
-            parameters: exitWorktreeJsonSchema,
-        });
-    }
-    // Tool gap pack : experimental engine-only echo
-    // helper. Advertised only when the caller explicitly opted in via
-    // `allowSyntheticOutput: true`. Off-by-default mirrors the privacy
-    // posture used for `allowFetch` / `allowSearch` — every customer-side
-    // CLI omits this so the model cannot use it as a side-channel that
-    // bypasses the normal tool-result logging.
-    if (options.allowSyntheticOutput) {
-        toolDefs.push({
-            name: 'synthetic_output',
-            description: 'Engine-only echo helper. Writes verbatim text to the requested stream (stdout|stderr). ' +
-                `Capped at ${(16 * 1024).toString()} bytes per call. Test fixture, not for production agent flows.`,
-            parameters: syntheticOutputJsonSchema,
-        });
-    }
-    // β1 T2 → structured AskUserQuestion bridge.
-    // Schema upgraded to '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' } },
-        },
-    });
-    // PUGI-78 Phase 1: symbols.* namespace (13 tools). LSP-bridged
-    // symbol-aware operations that replace whole-file reads for
-    // navigation questions. Each tool returns 1-2 KB of shaped JSON
-    // vs 5-50 KB for the raw file read it replaces — 10-100x token
-    // savings per refactor turn. All read-only in Phase 1 — `rename`
-    // / `format` / `code_actions` return PREVIEW edits the dispatcher
-    // applies via apply_patch in a future ticket.
-    //
-    // Schemas use the same JSON-Schema shape as the rest of the
-    // toolbox: required positional args, additionalProperties: false.
-    // The `lang` field is a closed enum of the 5 supported language
-    // server slugs (ts/js/py/go/rust). The dispatcher resolves the
-    // LSP client by lang BEFORE calling the underlying primitive.
-    const symbolsLangEnum = { type: 'string', enum: ['ts', 'js', 'py', 'go', 'rust'], description: 'LSP language slug.' };
-    const symbolsPosArgs = {
-        lang: symbolsLangEnum,
-        file: { type: 'string', description: 'Workspace-relative file path.' },
-        line: { type: 'integer', minimum: 0, description: 'Zero-based line index.' },
-        col: { type: 'integer', minimum: 0, description: 'Zero-based character index.' },
-    };
-    toolDefs.push({
-        name: 'symbols_find_definition',
-        description: 'Locate the definition of the symbol at (line, col) in <file>. Returns {file, line, character}. PREFER over read for "where is X defined?" questions.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file', 'line', 'col'],
-            properties: symbolsPosArgs,
-        },
-    }, {
-        name: 'symbols_find_references',
-        description: 'List every reference to the symbol at (line, col). Returns {file, line, character}[]. PREFER over grep for "find callers of X" questions.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file', 'line', 'col'],
-            properties: symbolsPosArgs,
-        },
-    }, {
-        name: 'symbols_list_in_file',
-        description: 'Outline the symbols (functions, classes, methods) defined in <file>. Returns flat {name, kind, line, character, containerName}[]. PREFER over read for "outline" questions.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file'],
-            properties: { lang: symbolsLangEnum, file: { type: 'string' } },
-        },
-    }, {
-        name: 'symbols_rename',
-        description: 'Preview a rename refactor for the symbol at (line, col) to <newName>. Returns {files, edits}[]. PREVIEW ONLY in Phase 1 — operator confirms then dispatches apply_patch.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file', 'line', 'col', 'newName'],
-            properties: {
-                ...symbolsPosArgs,
-                newName: { type: 'string', minLength: 1, description: 'New symbol name.' },
-            },
-        },
-    }, {
-        name: 'symbols_hover',
-        description: 'Type info + docstring at (line, col). Returns {content, range?}. Body capped at 4 KB.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file', 'line', 'col'],
-            properties: symbolsPosArgs,
-        },
-    }, {
-        name: 'symbols_signature',
-        description: 'Function signature at a call site. Returns {label, parameters, activeParameter?}. NULL when cursor is not inside a call.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file', 'line', 'col'],
-            properties: symbolsPosArgs,
-        },
-    }, {
-        name: 'symbols_workspace_symbols',
-        description: 'Workspace-wide fuzzy symbol search. Server-defined match (substring / fuzzy / prefix). Returns {name, file, line, kind, containerName?}[].',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'query'],
-            properties: {
-                lang: symbolsLangEnum,
-                query: { type: 'string', minLength: 1, description: 'Symbol query.' },
-            },
-        },
-    }, {
-        name: 'symbols_call_hierarchy',
-        description: 'Incoming + outgoing callers for the symbol at (line, col). Returns {incoming, outgoing}[].',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file', 'line', 'col'],
-            properties: symbolsPosArgs,
-        },
-    }, {
-        name: 'symbols_implementations',
-        description: 'Concrete implementations of the interface / abstract method at (line, col). Returns flat references list.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file', 'line', 'col'],
-            properties: symbolsPosArgs,
-        },
-    }, {
-        name: 'symbols_type_definition',
-        description: 'Type definition (vs value definition) of the symbol at (line, col). Returns the type declaration location.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file', 'line', 'col'],
-            properties: symbolsPosArgs,
-        },
-    }, {
-        name: 'symbols_code_actions',
-        description: 'Quick-fix list at the given range. Returns {title, kind?, isPreferred?}[].',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file', 'startLine', 'startChar', 'endLine', 'endChar'],
-            properties: {
-                lang: symbolsLangEnum,
-                file: { type: 'string' },
-                startLine: { type: 'integer', minimum: 0 },
-                startChar: { type: 'integer', minimum: 0 },
-                endLine: { type: 'integer', minimum: 0 },
-                endChar: { type: 'integer', minimum: 0 },
-            },
-        },
-    }, {
-        name: 'symbols_format',
-        description: 'Formatter — returns the text edits the LSP server would apply. PREVIEW ONLY in Phase 1.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file'],
-            properties: {
-                lang: symbolsLangEnum,
-                file: { type: 'string' },
-                tabSize: { type: 'integer', minimum: 1 },
-                insertSpaces: { type: 'boolean' },
-            },
-        },
-    }, {
-        name: 'symbols_diagnostics',
-        description: 'Cached LSP diagnostics (error / warning / info / hint) for <file>. Returns up to ~50 entries.',
-        parameters: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['lang', 'file'],
-            properties: { lang: symbolsLangEnum, file: { type: 'string' } },
-        },
-    });
-    // β1 T5 → β1a r1 (gating fix): 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 : 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 : `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. 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,
-                required: ['path', 'content'],
-                properties: {
-                    path: { type: 'string', description: 'Workspace-relative file path.' },
-                    content: { type: 'string', description: 'Full new file contents (UTF-8).' },
-                },
-            },
-        }, {
-            name: 'edit',
-            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,
-                required: ['path', 'oldString', 'newString'],
-                properties: {
-                    path: { type: 'string' },
-                    oldString: { type: 'string' },
-                    newString: { type: 'string' },
-                },
-            },
-        }, {
-            name: 'bash',
-            description: 'Run a shell command inside the workspace root via /bin/sh -c. Inherits a sanitized env (PUGI_API_KEY/PUGI_LOGIN_TOKEN stripped). 60s timeout. Output capped at 32KB combined stdout+stderr. ' +
-                'Optional `redirect` opts the call into log-discipline mode: stdout+stderr are written to a file on disk (default `.pugi/runs/<sessionId>/bash-<hash>.log` or a workspace-relative override) and the response carries the path + last N lines (default 20, max 200) instead of the full output. Use redirect for long-running scripts (builds, training loops, agentic stdout dumps) where the trailing lines + a path to the full log saves thousands of tokens vs the truncated head. ' +
-                'Returns {exitCode, stdout, stderr, truncated} on the buffered path, or {exitCode, stdout:\'\', stderr:\'\', logPath, tail, truncated:false} when redirect is set.',
-            parameters: {
-                type: 'object',
-                additionalProperties: false,
-                required: ['command'],
-                properties: {
-                    command: { type: 'string', description: 'Single shell command to execute.' },
-                    redirect: {
-                        type: 'object',
-                        additionalProperties: false,
-                        description: 'When set, redirect stdout+stderr to a file instead of returning content. Use for long-running scripts that produce thousands of lines.',
-                        properties: {
-                            path: {
-                                type: 'string',
-                                description: 'Workspace-relative path to write the log file. Defaults to `.pugi/runs/<sessionId>/bash-<commandHash>.log`. Absolute paths or `..` traversal are rejected.',
-                            },
-                            tailLines: {
-                                type: 'number',
-                                description: 'Number of trailing lines to fold into the response tail. Default 20, max 200.',
-                            },
-                        },
-                    },
-                },
-            },
-        }, {
-            name: 'powershell',
-            description: 'Run a PowerShell command via `pwsh -NoProfile -Command` (or `powershell.exe` fallback on Windows). Same security posture as bash — destructive pattern gate applies. 30s default timeout, 120s max. Output capped at 64KB. Returns {exitCode, stdout, stderr, truncated, shellBinary}. Prefer the dedicated bash tool for /bin/sh scripts; use this when the operator needs native pwsh cmdlets or *.ps1 syntax.',
-            parameters: {
-                type: 'object',
-                additionalProperties: false,
-                required: ['command'],
-                properties: {
-                    command: { type: 'string', description: 'Single PowerShell command or script.' },
-                    cwd: { type: 'string', description: 'Optional cwd; defaults to workspace root.' },
-                    timeoutMs: { type: 'number', description: 'Hard timeout (default 30000, max 120000).' },
-                },
-            },
-        }, 
-        // β7 L5+T11 : 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.' },
-                            },
-                        },
-                    },
-                },
-            },
-        }, 
-        // Phase 1 runtime evidence pack (PUGI-291..295) - server lifecycle
-        // primitives + generic HTTP request. Off in plan mode because each
-        // tool produces side effects (a spawned process, an outbound HTTP
-        // call) the plan-mode read-only contract refuses.
-        {
-            name: 'server_start',
-            description: 'Spawn a server via /bin/sh -c <command> in the workspace and poll the health URL until it returns the expected status (default 200) or the timeout elapses. Persists pid + meta to `.pugi/runs/<runId>/server.json` and a stdout/stderr tail to `server.log`. Returns {ok, pid, port, healthStatus, logPath, durationMs, error?}. Use to materialise concrete pid + health 200 evidence rather than asserting a server is up in prose.',
-            parameters: serverStartJsonSchema,
-        }, {
-            name: 'server_stop',
-            description: 'Send SIGTERM to the supplied pid, wait graceMs (default 5000ms), then escalate to SIGKILL. Idempotent - a pid that already exited returns ok=true with signal=undefined. Returns {ok, pid, exitCode?, signal?, durationMs, error?}.',
-            parameters: serverStopJsonSchema,
-        }, {
-            name: 'server_health',
-            description: 'One-shot HTTP GET against the supplied URL with a short timeout (default 5000ms, max 60000ms). Returns {ok, status, durationMs, body?, error?} where ok=true only when the response status equals expectStatus (default 200). Body is capped at 1 KB so the envelope stays compact.',
-            parameters: serverHealthJsonSchema,
-        }, {
-            name: 'server_logs',
-            description: 'Read the trailing N lines of `.pugi/runs/<runId>/server.log`. Defaults to the most recent run when runId is omitted; pid-based lookup walks every run dir. Returns {ok, logPath, lines, totalLines, error?}.',
-            parameters: serverLogsJsonSchema,
-        }, {
-            name: 'http_request',
-            description: 'Issue an HTTP request (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS) against a URL. Loopback hosts (localhost / 127.0.0.0/8 / ::1) always pass; non-loopback hosts require allowExternal: true so the default posture stays private. Body objects/arrays are JSON-serialised. Returns {ok, status, headers, body, json?, durationMs, error?, truncated?}.',
-            parameters: httpRequestJsonSchema,
-        });
-    }
-    // β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,
-            });
-        }
-    }
-    // L3 : 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),
-    }));
-}
-/**
- * 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() === '')
-        return {};
-    try {
-        const parsed = JSON.parse(raw);
-        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            throw new Error('tool arguments must be a JSON object');
-        }
-        return parsed;
-    }
-    catch (error) {
-        throw new Error(`invalid JSON in tool arguments: ${error.message}`);
-    }
-}
-/**
- * Strict canonical-only argument coercion (leak P0 L2).
- *
- * 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 upstream reference (research memo
- * §1.1 — `z.strictObject` rejects aliased fields).
- *
- * The compensating change ships in the persona prompts: Pugi'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`);
-}
-/**
- * Accept `path` (canonical) or `filePath` (the upstream tool convention) for
- * write/edit/read tool arguments. Models trained on CC system prompts
- * emit `filePath`; insisting on `path` only forces 2-3 retry waste on
- * every file write (CEO live smoke: snake.html dispatch
- * burned 2 turns retrying `{filePath: ...}` payloads before falling
- * back к bash heredoc). Defense-in-depth alias keeps canonical name
- * (so persona prompts can still teach `path` as the right answer) AND
- * tolerates the CC-trained variant without operator-visible failure.
- */
-function requirePathArg(obj) {
-    if (typeof obj['path'] === 'string')
-        return obj['path'];
-    if (typeof obj['filePath'] === 'string')
-        return obj['filePath'];
-    throw new Error('tool argument "path" must be a string (alias "filePath" also accepted)');
-}
-export function buildExecutor(input) {
-    const { kind, ctx, hooks, mvpHooksConfig, sessionId, askUserBridge, interactive, allowFetch, allowSearch, allowSyntheticOutput, agentDispatch, mcpRegistry, permissionMode, permissionAlwaysCache, permissionAsk, } = input;
-    // 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;
-    // 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
-        // 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);
-        // 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}`);
-        }
-        // — 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 recordDenial(name, argsForTracking, `PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
-            }
-        }
-        // : refuse cancelled-token tool dispatch BEFORE PreToolUse
-        // hooks fire so a cancelled brief never reaches user-defined
-        // hook scripts. Sentinel `OPERATOR_ABORTED:<tool>` is recognised
-        // 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 recordDenial(name, argsForTracking, `OPERATOR_ABORTED: ${name} refused — operator cancelled the dispatch.`);
-        }
-        // — 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.
-        //
-        // — 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 = {
-                sessionId,
-                event: 'PreToolUse',
-                tool: name,
-                path,
-                payload: { tool: name, arguments: argsRaw },
-            };
-            // List the matching hooks BEFORE firing so we can correlate
-            // hook[i] with result[i] when checking onFailure: 'block'. The
-            // ordering of listMatching and fire is stable: fire iterates the
-            // same listMatching output internally.
-            const matchingPreHooks = hooks.listMatching(preCtx);
-            const preResults = await hooks.fire(preCtx);
-            for (let i = 0; i < matchingPreHooks.length; i += 1) {
-                const hook = matchingPreHooks[i];
-                const result = preResults[i];
-                if (hook && result && hook.onFailure === 'block' && !result.ok) {
-                    // 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})`);
-                }
-            }
-        }
-        // MVP: fire `hooks-mvp.json` PreToolUse hooks. Distinct
-        // config file from the legacy `hooks.json` system so operator
-        // configs do not collide. Same blocking semantics — a non-zero
-        // exit from a hook declared `blocking: true` refuses the dispatch
-        // with `HOOK_BLOCKED:` sentinel. Bypass mode skips this surface
-        // identically to the legacy hooks block above.
-        if (mvpHooksConfig && sessionId && !hooksBypassed && !mvpHooksConfig.isEmpty()) {
-            const { fireHooks } = await import('../hooks/index.js');
-            const outcome = await fireHooks({
-                config: mvpHooksConfig,
-                event: 'PreToolUse',
-                payload: {
-                    event: 'PreToolUse',
-                    sessionId,
-                    toolName: name,
-                    toolInputSummary: hashArgs(argsRaw),
-                },
-                toolName: name,
-                workspaceRoot: ctx.root,
-            });
-            if (outcome.anyBlocked) {
-                const blocking = outcome.results.find((r) => r.blocked);
-                const sentinel = blocking?.blockSentinel ??
-                    `HOOK_BLOCKED: PreToolUse MVP-hook refused ${name}`;
-                throw recordDenial(name, argsForTracking, sentinel);
-            }
-        }
-        // β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 === 'todo_write') {
-                // batch TodoWrite. The dispatcher delegates the
-                // Zod validation + atomic persist to the tool module — any
-                // ZodError or `TODO_INVARIANT_VIOLATED` sentinel surfaces here
-                // as a thrown Error and lands on the catch arm below, which
-                // re-emits it through the PostToolUseFailure hook.
-                return dispatchTodoWrite({ workspaceRoot }, args);
-            }
-            // Tool gap pack : brief / sleep / synthetic_output /
-            // enter_worktree / exit_worktree dispatchers. Each tool returns a
-            // sentinel string on recoverable validation failures (no throw)
-            // so the engine adapter surfaces them as plain tool results and
-            // the model can self-correct.
-            if (name === 'brief') {
-                return dispatchBrief({
-                    workspaceRoot,
-                    // Fallback when running outside an audit session (CI, smoke
-                    // tests, one-shot CLI commands) — keep the JSONL writes
-                    // grouped under a stable basename instead of dropping them.
-                    sessionId: sessionId ?? 'no-session',
-                }, args);
-            }
-            if (name === 'verify_plan_execution') {
-                // Backlog #5 P0 : anti-fake-dispatch gate. Reads
-                // the session audit log accumulated during this dispatch (and
-                // earlier turns in the same engine loop invocation).
-                return dispatchVerifyPlanExecution(ctx.session, args);
-            }
-            if (name === 'cron_create') {
-                // Backlog PUGI-7: ScheduleCronTool — register a routine. The
-                // dispatcher returns a JSON string envelope (success) or a
-                // CRON_INVALID_ARGS / CRON_PERSIST_FAILED sentinel (recoverable
-                // failures). Sentinels surface as plain tool results so the
-                // model can self-correct.
-                return dispatchCronCreate({ workspaceRoot }, args);
-            }
-            if (name === 'cron_delete') {
-                // Backlog PUGI-7: idempotent routine removal.
-                return dispatchCronDelete({ workspaceRoot }, args);
-            }
-            if (name === 'cron_list') {
-                // Backlog PUGI-7: routine registry snapshot. Read-only; safe
-                // for parallel dispatch.
-                return dispatchCronList({ workspaceRoot }, args);
-            }
-            if (name === 'sleep') {
-                return dispatchSleep({}, args);
-            }
-            if (name === 'synthetic_output') {
-                if (!allowSyntheticOutput) {
-                    // Mirrors the `web_fetch` / `agent` defense-in-depth posture:
-                    // a stale schema must never let the model invoke an opt-in
-                    // tool. Surface a clear refusal sentinel the dispatcher can
-                    // record for denial tracking.
-                    throw new Error('synthetic_output: tool not enabled in this executor. Engine-only fixture; opt in via allowSyntheticOutput.');
-                }
-                return dispatchSyntheticOutput({}, args);
-            }
-            if (name === 'enter_worktree') {
-                return dispatchEnterWorktree({ workspaceRoot }, args);
-            }
-            if (name === 'exit_worktree') {
-                return dispatchExitWorktree({ workspaceRoot }, args);
-            }
-            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,
-                });
-            }
-            // Phase 1 runtime evidence pack (PUGI-291..295). Each tool returns
-            // a JSON-string envelope or a sentinel string on validation
-            // failure - both paths are recoverable from the model's POV, so
-            // the engine adapter routes them as plain tool results and the
-            // model can self-correct.
-            if (name === 'server_start') {
-                return dispatchServerStart({ workspaceRoot }, args);
-            }
-            if (name === 'server_stop') {
-                return dispatchServerStop({ workspaceRoot }, args);
-            }
-            if (name === 'server_health') {
-                return dispatchServerHealth({ workspaceRoot }, args);
-            }
-            if (name === 'server_logs') {
-                return dispatchServerLogs({ workspaceRoot }, args);
-            }
-            if (name === 'http_request') {
-                return dispatchHttpRequest({}, args);
-            }
-            if (name === 'multi_edit') {
-                return dispatchMultiEdit(args, ctx);
-            }
-            if (name === 'agent') {
-                // β2a r1 (Backend Architect P1): 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);
-            }
-            // PUGI-78 Phase 1: symbols.* namespace dispatch. Every name in
-            // SYMBOLS_TOOL_NAMES routes through `dispatchSymbolsTool` which
-            // resolves the LSP client by `lang`, calls the matching
-            // `symbols*Tool` wrapper in `src/tools/lsp-tools.ts`, and
-            // serialises the result for the engine envelope. Read-only —
-            // matches the registry posture; the post-edit diagnostics hook
-            // below is the only mutation the symbols.* surface participates in.
-            if (SYMBOLS_TOOL_NAMES.has(name)) {
-                return dispatchSymbolsTool(name, args, ctx);
-            }
-            return dispatchTool(name, args, ctx);
-        };
-        try {
-            const result = await dispatch();
-            // post-edit LSP diagnostics. After a
-            // successful `edit` / `write` / `multi_edit`, ask the cached
-            // language server for diagnostics on the touched file(s) and
-            // append the result to the tool envelope so the model can
-            // self-correct in the same turn. Silent skip when the language
-            // is unsupported, no server is installed, or the request times
-            // out — agent throughput beats diagnostic recall.
-            const augmented = await appendPostEditDiagnostics(name, args, ctx, result);
-            if (hooks && sessionId && !hooksBypassed) {
-                const path = extractToolPath(name, argsRaw);
-                await hooks.fire({
-                    sessionId,
-                    event: 'PostToolUse',
-                    tool: name,
-                    path,
-                    payload: { tool: name, arguments: argsRaw, ok: true, result: augmented.slice(0, 1024) },
-                });
-            }
-            return augmented;
-        }
-        catch (error) {
-            // #24 (CEO P1) — hook chains. After the legacy
-            // PostToolUseFailure registry fire (per-error-class block below),
-            // ALSO fire the settings.json hook chain. Chains are best-effort:
-            // a chain command crash never propagates back here so the engine
-            // loop sees the original throw unchanged.
-            const fireFailureChain = async (errorMessage) => {
-                try {
-                    await firePostToolUseFailureChain(ctx.root, {
-                        toolName: name,
-                        args: argsForTracking,
-                        error: errorMessage,
-                        exitCode: 1,
-                    });
-                }
-                catch (chainError) {
-                    process.stderr.write(`[pugi hook-chains] PostToolUseFailure chain crashed: ${chainError.message}\n`);
-                }
-            };
-            // — 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(),
-                        },
-                    });
-                }
-                await fireFailureChain(error.toModelMessage());
-                throw new Error(error.toModelMessage());
-            }
-            // : re-shape OperatorAbortedError throws from the
-            // file-tools layer into the same `OPERATOR_ABORTED:` sentinel
-            // the upstream cancellation gate uses so `runEngineLoop` sees
-            // a consistent terminal-cancel signal regardless of whether
-            // the abort landed pre-dispatch or mid-tool (e.g. inside the
-            // grep file-loop).
-            if (error instanceof OperatorAbortedError) {
-                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: `OPERATOR_ABORTED: ${name}`,
-                        },
-                    });
-                }
-                await fireFailureChain(`OPERATOR_ABORTED: ${name}`);
-                throw recordDenial(name, argsForTracking, `OPERATOR_ABORTED: ${name} aborted mid-execution.`);
-            }
-            // 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}`,
-                        },
-                    });
-                }
-                await fireFailureChain(`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 && !hooksBypassed) {
-                const path = extractToolPath(name, argsRaw);
-                await hooks.fire({
-                    sessionId,
-                    event: 'PostToolUseFailure',
-                    tool: name,
-                    path,
-                    payload: {
-                        tool: name,
-                        arguments: argsRaw,
-                        ok: false,
-                        error: error instanceof Error ? error.message : String(error),
-                    },
-                });
-            }
-            await fireFailureChain(error instanceof Error ? error.message : String(error));
-            throw error;
-        }
-    };
-}
-/**
- * Best-effort extraction of the file path a tool targets. Returns
- * undefined when the tool does not take a path or the path cannot be
- * parsed cleanly — match rules with a `pathGlob` will then skip this
- * dispatch, which is the safe default.
- */
-function extractToolPath(name, argsRaw) {
-    if (name !== 'read' && name !== 'write' && name !== 'edit')
-        return undefined;
-    try {
-        const parsed = JSON.parse(argsRaw);
-        const path = parsed.path;
-        return typeof path === 'string' ? path : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function dispatchTool(name, args, ctx) {
-    switch (name) {
-        case 'read': {
-            const { path } = { path: requirePathArg(args) };
-            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
-            // and a truncation marker; if it needs more it can grep.
-            const CAP = 32 * 1024;
-            if (content.length > CAP) {
-                return `${content.slice(0, CAP)}\n(...truncated at ${CAP} bytes; use grep or glob to narrow the read)`;
-            }
-            return content;
-        }
-        case 'write': {
-            const wargs = {
-                path: requirePathArg(args),
-                content: requireString(args, 'content'),
-            };
-            writeTool(ctx, wargs.path, wargs.content);
-            return `wrote ${wargs.path} (${wargs.content.length} bytes)`;
-        }
-        case 'edit': {
-            const eargs = {
-                path: requirePathArg(args),
-                oldString: requireString(args, 'oldString'),
-                newString: requireString(args, 'newString'),
-            };
-            editTool(ctx, eargs.path, eargs.oldString, eargs.newString);
-            return `edited ${eargs.path}`;
-        }
-        case 'grep': {
-            const queryRaw = args.query ?? args.text ?? args.pattern ?? args.q ?? args.search;
-            if (typeof queryRaw !== 'string' || queryRaw.length === 0) {
-                throw new Error('tool argument "query" must be a non-empty string (aliases: text/pattern/q/search)');
-            }
-            const gargs = { query: queryRaw };
-            const matches = grepTool(ctx, gargs.query);
-            if (matches.length === 0)
-                return `no matches for ${gargs.query}`;
-            const head = matches.slice(0, 50);
-            const rendered = head.map((m) => `${m.path}:${m.line}: ${m.text}`).join('\n');
-            const more = matches.length > head.length ? `\n(... ${matches.length - head.length} more)` : '';
-            return `${matches.length} match(es):\n${rendered}${more}`;
-        }
-        case 'glob': {
-            const gargs = { pattern: requireString(args, 'pattern') };
-            const results = globTool(ctx, gargs.pattern);
-            if (results.length === 0)
-                return `no paths match ${gargs.pattern}`;
-            return `${results.length} path(s):\n${results.slice(0, 100).join('\n')}${results.length > 100 ? `\n(... ${results.length - 100} more)` : ''}`;
-        }
-        case 'bash': {
-            const command = requireString(args, 'command');
-            // Pugi backlog P2 — parse the optional redirect block. We
-            // accept either no field, an empty object (== "use defaults"),
-            // or `{path?, tailLines?}`. The bash tool's helper layer
-            // normalises both values; we only do the outer-shape parse
-            // here so a malformed arg surfaces as a model-readable error.
-            const rawRedirect = args['redirect'];
-            let redirect;
-            if (rawRedirect !== undefined && rawRedirect !== null) {
-                if (typeof rawRedirect !== 'object' || Array.isArray(rawRedirect)) {
-                    throw new Error('tool argument "redirect" must be an object when present');
-                }
-                const r = rawRedirect;
-                const pathArg = r['path'];
-                const tailArg = r['tailLines'];
-                if (pathArg !== undefined && typeof pathArg !== 'string') {
-                    throw new Error('redirect.path must be a string when present');
-                }
-                if (tailArg !== undefined && (typeof tailArg !== 'number' || !Number.isFinite(tailArg))) {
-                    throw new Error('redirect.tailLines must be a finite number when present');
-                }
-                redirect = {
-                    ...(pathArg !== undefined ? { path: pathArg } : {}),
-                    ...(tailArg !== undefined ? { tailLines: tailArg } : {}),
-                };
-            }
-            // The class-aware bash tool (sprint ) replaces the legacy
-            // file-tools entry point. We use the sync variant here because
-            // dispatchTool's signature is sync; the async tool is reserved
-            // for the REPL path (sprint ) where promises are first class.
-            const result = bashToolSync({ cmd: command, ...(redirect !== undefined ? { redirect } : {}) }, {
-                root: ctx.root,
-                settings: ctx.settings,
-                session: ctx.session,
-                source: 'agent',
-            });
-            // PUGI-VERIFY-GATE: tag verification commands and record them
-            // on the session ledger so the engine outcome assembler can
-            // gate the final `status` on test/lint/build pass. The check
-            // is pure — `detectVerificationCommand` matches the regex
-            // allowlist in `verification-patterns.ts`. Record BEFORE
-            // building the model-facing envelope so the ledger is durable
-            // even if the model stops the loop on this turn.
-            const detection = detectVerificationCommand(command);
-            const verificationFailed = detection.isVerification && result.exitCode !== 0;
-            if (detection.isVerification && detection.tool !== null) {
-                recordVerificationCall(ctx.session, {
-                    command,
-                    tool: detection.tool,
-                    exitCode: result.exitCode,
-                    tailStderr: tailStderr(
-                    // Prefer buffered stderr; fall back to redirect tail
-                    // when stdout/stderr lives on disk (`logPath` mode).
-                    result.stderr === '' && typeof result.tail === 'string'
-                        ? result.tail
-                        : result.stderr),
-                    timestamp: new Date().toISOString(),
-                });
-            }
-            const parts = [
-                `exit=${result.exitCode}`,
-                result.stdout ? `stdout:\n${result.stdout}` : '',
-                result.stderr ? `stderr:\n${result.stderr}` : '',
-            ];
-            if (result.artifactRef)
-                parts.push(`artifactRef=${result.artifactRef}`);
-            if (result.logPath)
-                parts.push(`logPath=${result.logPath}`);
-            if (result.tail)
-                parts.push(`tail:\n${result.tail}`);
-            if (result.truncated)
-                parts.push('truncated=true');
-            if (result.timedOut)
-                parts.push('timedOut=true');
-            // PUGI-VERIFY-GATE: when a verification command exited non-zero,
-            // tag the envelope so the model cannot honestly claim "tests
-            // pass" — and so the engine outcome assembler can scan the
-            // ledger and gate `done`. The stringified envelope keeps
-            // `exit=N` for legacy parsers; the new `verification.tool=` /
-            // `verification.ok=` lines surface the gate state explicitly.
-            if (detection.isVerification) {
-                parts.push(`verification.tool=${detection.tool}`);
-                parts.push(`verification.ok=${verificationFailed ? 'false' : 'true'}`);
-            }
-            const body = parts.filter(Boolean).join('\n');
-            return body || '(no output)';
-        }
-        case 'powershell': {
-            // pwsh dispatcher. Permission gate reuses the
-            // bash classifier so destructive patterns block the same way.
-            const command = requireString(args, 'command');
-            const cwd = optionalString(args, 'cwd');
-            const timeoutMs = optionalNumber(args, 'timeoutMs');
-            const psResult = powerShellToolSync({ cmd: command, ...(cwd !== undefined ? { cwd } : {}), ...(timeoutMs !== undefined ? { timeoutMs } : {}) }, {
-                root: ctx.root,
-                settings: ctx.settings,
-                session: ctx.session,
-                source: 'agent',
-            });
-            const parts = [
-                `exit=${psResult.exitCode}`,
-                `shell=${psResult.shellBinary}`,
-                psResult.stdout ? `stdout:\n${psResult.stdout}` : '',
-                psResult.stderr ? `stderr:\n${psResult.stderr}` : '',
-            ];
-            if (psResult.truncated)
-                parts.push('truncated=true');
-            if (psResult.timedOut)
-                parts.push('timedOut=true');
-            return parts.filter(Boolean).join('\n') || '(no output)';
-        }
-        default:
-            // Exhaustive; unreachable because of the WIRED_TOOLS guard above.
-            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');
-    }
-    // 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 : `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;
-}
-function optionalNumber(obj, key) {
-    const v = obj[key];
-    if (v === undefined || v === null)
-        return undefined;
-    if (typeof v !== 'number' || !Number.isFinite(v)) {
-        throw new Error(`tool argument "${key}" must be a finite number 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);
-}
-/* ---------------------------- hook ---------------------------- */
-/**
- * Tool names that mutate workspace files. After a successful dispatch
- * of any of these, the L15 post-edit diagnostics hook fires. The set
- * is intentionally tight — `task_*` / `todo_write` write to ledger
- * files (not workspace source) so they stay out, and `bash` is too
- * coarse (a `bash` call can write any path, and we'd need to parse
- * the command to know which — out of scope for L15).
- */
-const POST_EDIT_TOOLS = new Set(['edit', 'write', 'multi_edit']);
-/**
- * Append LSP diagnostics to the tool envelope after a successful
- * edit / write / multi_edit. Silent skip is the default — missing
- * binary, unsupported language, request timeout, and "no diagnostics"
- * all leave the envelope unchanged.
- *
- * Opt-in via `.pugi/settings.json::lsp.postEditDiagnostics = true`
- * OR `PUGI_LSP_POST_EDIT=1`. Off by default until dogfood validates
- * the cold-start cost vs the model-loop benefit ().
- */
-/**
- * PUGI-78 Phase 1: dispatched-name allowlist for the symbols.* router.
- * Sourced from the same list as the JSON-schema additions in
- * `buildToolsSchema` + the registry entries in `tools/registry.ts` — a
- * mismatch would surface as either an advertised-but-unrouted tool
- * (codex review P1 from this PR) or an unknown-tool denial.
- */
-const SYMBOLS_TOOL_NAMES = new Set([
-    'symbols_call_hierarchy',
-    'symbols_code_actions',
-    'symbols_diagnostics',
-    'symbols_find_definition',
-    'symbols_find_references',
-    'symbols_format',
-    'symbols_hover',
-    'symbols_implementations',
-    'symbols_list_in_file',
-    'symbols_rename',
-    'symbols_signature',
-    'symbols_type_definition',
-    'symbols_workspace_symbols',
-]);
-/**
- * PUGI-78 Phase 1: dispatch a symbols.* tool call. Common pre-flight
- * (validate `lang`, resolve / spawn the LSP client via the warm cache,
- * build an `LspToolContext` from the engine `ToolContext`) lives here so
- * each per-tool branch stays a thin shim around the matching wrapper.
- *
- * Failure shape: the wrappers return a structured `{ok, value, reason}`
- * record — we JSON-stringify it for the engine envelope. The engine
- * adapter treats a string return as the tool result text; the wrappers
- * never throw (errors are caught and folded into the structured
- * `ok: false` record), so the dispatch path is safe to call without a
- * try/catch wrapper here.
- */
-async function dispatchSymbolsTool(name, args, ctx) {
-    const langRaw = args['lang'];
-    const validLangs = ['ts', 'js', 'py', 'go', 'rust'];
-    if (typeof langRaw !== 'string' || !validLangs.includes(langRaw)) {
-        return JSON.stringify({
-            ok: false,
-            reason: 'invalid_argument',
-            detail: `${name}: 'lang' must be one of ts | js | py | go | rust (got: ${langRaw})`,
-        });
-    }
-    const lang = langRaw;
-    // Resolve (and lazily start) the LSP client. The cache holds the
-    // client across the session so the cold start is paid once.
-    const lspOpts = {
-        cwd: ctx.root,
-        ...(ctx.settings.lsp ? { lspSettings: ctx.settings.lsp } : {}),
-    };
-    const lspResult = await getOrStartLspClient(lang, lspOpts);
-    const lspToolCtx = {
-        ...ctx,
-        ...(lspResult.ok
-            ? { lspClients: new Map([[lang, lspResult.client]]) }
-            : {}),
-        symbolCache: getGlobalSymbolCache(),
-    };
-    // Validate required positional args per tool. Each tool that needs
-    // a position rejects missing / non-finite / negative coordinates
-    // with a structured `invalid_argument` envelope so the model sees
-    // a clear correction signal instead of a silent (0,0) coercion that
-    // would otherwise yield `lsp_not_found`.
-    const requiresFile = name !== 'symbols_workspace_symbols';
-    const requiresPosition = name === 'symbols_find_definition' ||
-        name === 'symbols_find_references' ||
-        name === 'symbols_hover' ||
-        name === 'symbols_signature' ||
-        name === 'symbols_implementations' ||
-        name === 'symbols_type_definition' ||
-        name === 'symbols_call_hierarchy' ||
-        name === 'symbols_rename';
-    const file = typeof args['file'] === 'string' ? args['file'] : '';
-    if (requiresFile && file.length === 0) {
-        return JSON.stringify({
-            ok: false,
-            reason: 'invalid_argument',
-            detail: `${name}: 'file' must be a non-empty workspace-relative path`,
-        });
-    }
-    const lineRaw = args['line'];
-    const colRaw = args['col'];
-    if (requiresPosition) {
-        if (typeof lineRaw !== 'number' || !Number.isFinite(lineRaw) || lineRaw < 0) {
-            return JSON.stringify({
-                ok: false,
-                reason: 'invalid_argument',
-                detail: `${name}: 'line' must be a non-negative integer`,
-            });
-        }
-        if (typeof colRaw !== 'number' || !Number.isFinite(colRaw) || colRaw < 0) {
-            return JSON.stringify({
-                ok: false,
-                reason: 'invalid_argument',
-                detail: `${name}: 'col' must be a non-negative integer`,
-            });
-        }
-    }
-    const line = typeof lineRaw === 'number' ? lineRaw : 0;
-    const col = typeof colRaw === 'number' ? colRaw : 0;
-    try {
-        switch (name) {
-            case 'symbols_find_definition': {
-                const result = await symbolsFindDefinitionTool(lspToolCtx, lang, file, line, col);
-                return JSON.stringify(result);
-            }
-            case 'symbols_find_references': {
-                const result = await symbolsFindReferencesTool(lspToolCtx, lang, file, line, col);
-                return JSON.stringify(result);
-            }
-            case 'symbols_list_in_file': {
-                const result = await symbolsListInFileTool(lspToolCtx, lang, file);
-                return JSON.stringify(result);
-            }
-            case 'symbols_rename': {
-                const newName = typeof args['newName'] === 'string' ? args['newName'] : '';
-                const result = await symbolsRenameTool(lspToolCtx, lang, file, line, col, newName);
-                return JSON.stringify(result);
-            }
-            case 'symbols_hover': {
-                const result = await symbolsHoverTool(lspToolCtx, lang, file, line, col);
-                return JSON.stringify(result);
-            }
-            case 'symbols_signature': {
-                const result = await symbolsSignatureTool(lspToolCtx, lang, file, line, col);
-                return JSON.stringify(result);
-            }
-            case 'symbols_workspace_symbols': {
-                const query = typeof args['query'] === 'string' ? args['query'] : '';
-                const result = await symbolsWorkspaceSymbolsTool(lspToolCtx, lang, query);
-                return JSON.stringify(result);
-            }
-            case 'symbols_call_hierarchy': {
-                const result = await symbolsCallHierarchyTool(lspToolCtx, lang, file, line, col);
-                return JSON.stringify(result);
-            }
-            case 'symbols_implementations': {
-                const result = await symbolsImplementationsTool(lspToolCtx, lang, file, line, col);
-                return JSON.stringify(result);
-            }
-            case 'symbols_type_definition': {
-                const result = await symbolsTypeDefinitionTool(lspToolCtx, lang, file, line, col);
-                return JSON.stringify(result);
-            }
-            case 'symbols_code_actions': {
-                // Validate every coordinate of the range. Same gate as the
-                // position-args check above — silent (0,0,0,0) coercion would
-                // hide schema-noncompliant calls and yield an empty action
-                // list instead of a clear correction signal.
-                const coords = ['startLine', 'startChar', 'endLine', 'endChar'];
-                for (const k of coords) {
-                    const v = args[k];
-                    if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) {
-                        return JSON.stringify({
-                            ok: false,
-                            reason: 'invalid_argument',
-                            detail: `symbols_code_actions: '${k}' must be a non-negative integer`,
-                        });
-                    }
-                }
-                const startLine = args['startLine'];
-                const startChar = args['startChar'];
-                const endLine = args['endLine'];
-                const endChar = args['endChar'];
-                const result = await symbolsCodeActionsTool(lspToolCtx, lang, file, startLine, startChar, endLine, endChar);
-                return JSON.stringify(result);
-            }
-            case 'symbols_format': {
-                const tabSize = typeof args['tabSize'] === 'number' ? args['tabSize'] : undefined;
-                const insertSpaces = typeof args['insertSpaces'] === 'boolean' ? args['insertSpaces'] : undefined;
-                const options = {};
-                if (typeof tabSize === 'number')
-                    options.tabSize = tabSize;
-                if (typeof insertSpaces === 'boolean')
-                    options.insertSpaces = insertSpaces;
-                const result = await symbolsFormatTool(lspToolCtx, lang, file, options);
-                return JSON.stringify(result);
-            }
-            case 'symbols_diagnostics': {
-                const result = await symbolsDiagnosticsTool(lspToolCtx, lang, file);
-                return JSON.stringify(result);
-            }
-            default:
-                return JSON.stringify({
-                    ok: false,
-                    reason: 'unknown_symbols_tool',
-                    detail: `${name} is not a recognised symbols.* tool`,
-                });
-        }
-    }
-    catch (error) {
-        // The wrappers fold errors into structured ok:false records, so
-        // this branch is defense-in-depth for a refactor regression. If
-        // any wrapper ever throws, we surface a stable shape to the model
-        // instead of leaking the raw exception type.
-        return JSON.stringify({
-            ok: false,
-            reason: 'symbols_dispatch_error',
-            detail: error instanceof Error ? error.message : String(error),
-        });
-    }
-}
-async function appendPostEditDiagnostics(name, args, ctx, result) {
-    if (!POST_EDIT_TOOLS.has(name))
-        return result;
-    // PUGI-78 Phase 1 (codex P2 fix): a successful edit / write / multi_edit
-    // invalidates the symbol cache for this workspace. Without this, a
-    // subsequent symbols.* query inside the same 5-minute TTL window could
-    // return stale line numbers / outlines / references / hover from
-    // before the edit. We invalidate BEFORE the post-edit diagnostics
-    // gate so the invalidation fires even when post-edit-diagnostics is
-    // disabled (the cache concern is independent of the diagnostics
-    // surface). The invalidation is process-global; subagents that share
-    // the same Node process share the cache, so the invalidation
-    // propagates without an additional hop.
-    try {
-        const cache = getGlobalSymbolCache();
-        cache.invalidateWorkspace(ctx.root);
-    }
-    catch {
-        // Defense-in-depth — cache invalidation must never block the
-        // engine's tool envelope. A throw here is a soft contract
-        // violation but recoverable.
-    }
-    if (!isPostEditEnabled(ctx))
-        return result;
-    const paths = extractEditedPaths(name, args);
-    if (paths.length === 0)
-        return result;
-    const tails = [];
-    for (const filePath of paths) {
-        const opts = {
-            cwd: ctx.root,
-            ...(ctx.settings.lsp ? { lspSettings: ctx.settings.lsp } : {}),
-        };
-        try {
-            const diag = await runPostEditDiagnostics(filePath, opts);
-            if (!diag.skip) {
-                tails.push(diag.tail);
-            }
-        }
-        catch {
-            // Belt-and-suspenders: any unexpected throw from the hook is
-            // swallowed. The model never blocks on LSP.
-        }
-    }
-    if (tails.length === 0)
-        return result;
-    return `${result}\n${tails.join('\n')}`;
-}
-function isPostEditEnabled(ctx) {
-    const envFlag = process.env.PUGI_LSP_POST_EDIT;
-    if (envFlag === '1' || envFlag === 'true')
-        return true;
-    if (envFlag === '0' || envFlag === 'false')
-        return false;
-    return ctx.settings.lsp?.postEditDiagnostics === true;
-}
-/**
- * Pull the workspace-relative file path(s) the tool just touched.
- * Each branch mirrors the args shape its `dispatch*` handler reads;
- * a deformed args object yields an empty list so the hook silently
- * skips instead of throwing inside the augmentation layer.
- */
-function extractEditedPaths(name, args) {
-    if (name === 'edit' || name === 'write') {
-        const path = args['path'];
-        return typeof path === 'string' && path.length > 0 ? [path] : [];
-    }
-    if (name === 'multi_edit') {
-        const edits = args['edits'];
-        if (!Array.isArray(edits))
-            return [];
-        const seen = new Set();
-        for (const entry of edits) {
-            if (!entry || typeof entry !== 'object')
-                continue;
-            const file = entry['file'];
-            if (typeof file === 'string' && file.length > 0)
-                seen.add(file);
-        }
-        return Array.from(seen);
-    }
-    return [];
-}
-//# sourceMappingURL=tool-bridge.js.map