@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.87

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

@@ -1,20 +1,47 @@
-import { editTool, globTool, grepTool, OperatorAbortedError, readTool, writeTool, } from '../../tools/file-tools.js';
+import { editTool, globTool, grepTool, OperatorAbortedError, readTool, StaleReadError, writeTool, } from '../../tools/file-tools.js';
 import { bashToolSync } from '../../tools/bash.js';
+import { 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 { 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';
+import { agentTool } from '../../tools/agent-tool.js';
+import { multiEdit } from '../../tools/multi-edit.js';
+import { buildMcpToolDefs, defaultNonInteractiveMcpPrompt, dispatchMcpTool, MCP_TOOL_PREFIX, } from '../../tools/mcp-tool.js';
+import { 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';
 /**
  * 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.
+ *  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.
+ *  - 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
@@ -23,17 +50,116 @@ import { bashToolSync } from '../../tools/bash.js';
 /**
  * Read-only subset surfaced to plan-mode. Mutating tools (write, edit,
  * bash) are intentionally absent so the model rarely tries them.
+ *
+ * β1: task_* + skill + ask_user_question + web_fetch are all read-only
+ * from the workspace's perspective (no file writes), so they stay
+ * available in plan mode. The ledger writes for `task_*` land in
+ * `.pugi/sessions/<id>/tasks.jsonl` which is metadata, not source.
  */
-const READ_ONLY_TOOLS = new Set(['read', 'grep', 'glob']);
+const READ_ONLY_TOOLS = new Set([
+    'read',
+    'grep',
+    'glob',
+    'ask_user_question',
+    'skill',
+    'skills_list',
+    'task_create',
+    'task_get',
+    'task_list',
+    'task_update',
+    // `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',
+    // 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',
+]);
 /**
- * Tools we actually wire today. The registry has more entries
- * (task_*, skill, question) — those route through the runtime layer, not
- * the local filesystem, so they ship in a follow-up PR. M1 cornerstone is
- * the six core tools.
+ * Tools the engine loop dispatches. β1 expands the M1 cornerstone six
+ * (read/write/edit/grep/glob/bash) with task_* + ask_user_question +
+ * skill + skill list + web_fetch. The registry advertises these slots
+ * to the runtime; without dispatcher entries the model would call
+ * "unknown tool" errors.
  */
-const WIRED_TOOLS = new Set(['read', 'write', 'edit', 'grep', 'glob', 'bash']);
-export function buildToolsSchema(kind) {
+const WIRED_TOOLS = new Set([
+    'read',
+    'write',
+    'edit',
+    'grep',
+    'glob',
+    'bash',
+    // 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',
+    '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',
+]);
+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',
@@ -49,13 +175,16 @@ export function buildToolsSchema(kind) {
         },
         {
             name: 'grep',
-            description: 'Substring-match every workspace file. Returns up to 200 matches with {path, line, text}. Use this to locate code by symbol/keyword.',
+            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: false,
-                required: ['query'],
+                additionalProperties: true,
                 properties: {
-                    query: { type: 'string', description: 'Substring to search for.' },
+                    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.' },
                 },
             },
         },
@@ -72,10 +201,286 @@ export function buildToolsSchema(kind) {
             },
         },
     ];
+    // β1 T1/T6: TodoWrite (Pugi grammar = `task_*`). Append-only ledger
+    // at `.pugi/sessions/<id>/tasks.jsonl`.
+    toolDefs.push({
+        name: 'task_create',
+        description: 'Append a new task to the session todo ledger. Returns the assigned task id and full record. Mirrors 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 #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' } },
+        },
+    });
+    // β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. Use for new files only — prefer edit for existing files. Workspace-scoped.',
+            description: 'Create or overwrite a workspace file. Prefer edit for existing files. ' +
+                'For OVERWRITE of an existing file, you MUST read the file first in this session — ' +
+                'write refuses with STALE_READ if the file changed since your last read, or if you ' +
+                'never read it. New-file creation (path does not exist) skips that gate. Workspace-scoped.',
             parameters: {
                 type: 'object',
                 additionalProperties: false,
@@ -87,7 +492,10 @@ export function buildToolsSchema(kind) {
             },
         }, {
             name: 'edit',
-            description: 'Replace exactly one occurrence of oldString with newString inside an already-read file. Fails if the file changed since you read it or if oldString is missing/duplicate.',
+            description: 'Replace exactly one occurrence of oldString with newString inside an already-read file. ' +
+                'Refuses with STALE_READ if the file was never read this session or the on-disk contents ' +
+                'drifted since the read (mtime+sha gate). Recovery: re-read with the `read` tool, then ' +
+                'retry the edit. Also fails if oldString is missing or duplicate.',
             parameters: {
                 type: 'object',
                 additionalProperties: false,
@@ -100,18 +508,131 @@ export function buildToolsSchema(kind) {
             },
         }, {
             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). 30s timeout. Output capped at 64KB. Returns {exitCode, stdout, stderr, truncated}.',
+            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.' },
+                            },
+                        },
+                    },
                 },
             },
         });
     }
-    return toolDefs;
+    // β4 M1/M3: append MCP tools last. Plan mode skips them because every
+    // MCP tool is treated as medium-risk until per-tool annotations land
+    // in the MCP spec; treating MCP read-as-read would require server-
+    // side metadata we cannot trust today (a misconfigured server could
+    // claim `read` while running a destructive op).
+    if (!planMode) {
+        for (const def of mcpDefs) {
+            toolDefs.push({
+                name: def.name,
+                description: def.description,
+                parameters: def.parameters,
+            });
+        }
+    }
+    // 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() === '')
@@ -127,39 +648,189 @@ function parseArgs(raw) {
         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') {
-        throw new Error(`tool argument "${key}" must be a string`);
-    }
-    return v;
+    if (typeof v === 'string')
+        return v;
+    throw new Error(`tool argument "${key}" must be a string`);
+}
+/**
+ * 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, sessionId } = 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 }) => {
-        if (!WIRED_TOOLS.has(name)) {
-            throw new Error(`unknown tool: ${name}`);
+        // β4 M1/M3: MCP tool names live outside WIRED_TOOLS. They are
+        // validated lazily by the dispatcher (the registry knows which
+        // names are actually exposed). The namespace check happens FIRST
+        // so a bad `mcp__bogus__foo` does not collide with the native
+        // unknown-tool branch.
+        const isMcpName = name.startsWith(MCP_TOOL_PREFIX);
+        // 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}`);
         }
-        if (planMode && !READ_ONLY_TOOLS.has(name)) {
-            // Sentinel recognised by `runEngineLoop` — terminates the loop
-            // with status `tool_refused`. The CLI surfaces this as a blocked
-            // outcome, not a failure, because plan mode is doing its job.
-            throw new Error(`PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
+        // — 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;
+            }
         }
-        // α6.9: refuse cancelled-token tool dispatch BEFORE PreToolUse
+        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 new Error(`OPERATOR_ABORTED: ${name} refused — operator cancelled the dispatch.`);
+            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.
-        if (hooks && sessionId) {
+        //
+        // — bypass mode skips the entire hook layer (PreToolUse +
+        // PostToolUse + PostToolUseFailure). The gate's allow decision
+        // carries the `hooksBypassed` flag; we honour it here so the
+        // executor stays single-pass.
+        if (hooks && sessionId && !hooksBypassed) {
             hooks.resetBatch();
             const path = extractToolPath(name, argsRaw);
             const preCtx = {
@@ -179,37 +850,218 @@ export function buildExecutor(input) {
                 const hook = matchingPreHooks[i];
                 const result = preResults[i];
                 if (hook && result && hook.onFailure === 'block' && !result.ok) {
-                    throw new Error(`HOOK_BLOCKED: PreToolUse hook (${hook.run.slice(0, 80)}) refused ${name} (exit=${result.exitCode})`);
+                    // L11: record the PreToolUse hook denial so the model
+                    // sees the pattern reminder on subsequent turns. Without
+                    // this the model would re-issue the same refused call and
+                    // burn a turn each time before noticing the loop.
+                    throw recordDenial(name, argsForTracking, `HOOK_BLOCKED: PreToolUse hook (${hook.run.slice(0, 80)}) refused ${name} (exit=${result.exitCode})`);
                 }
             }
         }
-        const args = parseArgs(argsRaw);
+        // 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 === '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,
+                });
+            }
+            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);
+            }
             return dispatchTool(name, args, ctx);
         };
         try {
             const result = await dispatch();
-            if (hooks && sessionId) {
+            // 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: result.slice(0, 1024) },
+                    payload: { tool: name, arguments: argsRaw, ok: true, result: augmented.slice(0, 1024) },
                 });
             }
-            return result;
+            return augmented;
         }
         catch (error) {
-            // α6.9: re-shape OperatorAbortedError throws from the
+            // #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) {
+                if (hooks && sessionId && !hooksBypassed) {
                     const path = extractToolPath(name, argsRaw);
                     await hooks.fire({
                         sessionId,
@@ -224,9 +1076,37 @@ export function buildExecutor(input) {
                         },
                     });
                 }
-                throw new Error(`OPERATOR_ABORTED: ${name} aborted mid-execution.`);
+                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) {
+            if (hooks && sessionId && !hooksBypassed) {
                 const path = extractToolPath(name, argsRaw);
                 await hooks.fire({
                     sessionId,
@@ -241,6 +1121,7 @@ export function buildExecutor(input) {
                     },
                 });
             }
+            await fireFailureChain(error instanceof Error ? error.message : String(error));
             throw error;
         }
     };
@@ -266,7 +1147,7 @@ function extractToolPath(name, argsRaw) {
 function dispatchTool(name, args, ctx) {
     switch (name) {
         case 'read': {
-            const { path } = { path: requireString(args, 'path') };
+            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
@@ -279,7 +1160,7 @@ function dispatchTool(name, args, ctx) {
         }
         case 'write': {
             const wargs = {
-                path: requireString(args, 'path'),
+                path: requirePathArg(args),
                 content: requireString(args, 'content'),
             };
             writeTool(ctx, wargs.path, wargs.content);
@@ -287,7 +1168,7 @@ function dispatchTool(name, args, ctx) {
         }
         case 'edit': {
             const eargs = {
-                path: requireString(args, 'path'),
+                path: requirePathArg(args),
                 oldString: requireString(args, 'oldString'),
                 newString: requireString(args, 'newString'),
             };
@@ -295,7 +1176,11 @@ function dispatchTool(name, args, ctx) {
             return `edited ${eargs.path}`;
         }
         case 'grep': {
-            const gargs = { query: requireString(args, 'query') };
+            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}`;
@@ -312,12 +1197,37 @@ function dispatchTool(name, args, ctx) {
             return `${results.length} path(s):\n${results.slice(0, 100).join('\n')}${results.length > 100 ? `\n(... ${results.length - 100} more)` : ''}`;
         }
         case 'bash': {
-            const bargs = { command: requireString(args, 'command') };
-            // The class-aware bash tool (sprint α5.2) replaces the legacy
+            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 α5.7) where promises are first class.
-            const result = bashToolSync({ cmd: bargs.command }, {
+            // 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,
@@ -330,6 +1240,10 @@ function dispatchTool(name, args, ctx) {
             ];
             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)
@@ -337,9 +1251,331 @@ function dispatchTool(name, args, ctx) {
             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 ().
+ */
+async function appendPostEditDiagnostics(name, args, ctx, result) {
+    if (!POST_EDIT_TOOLS.has(name))
+        return result;
+    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