@pugi/cli 0.1.0-beta.88 → 0.1.0-beta.89

package/dist/core/auth/env-provider.js

@@ -1,7 +1,7 @@
 /**
  * `pugi login --provider env` — env-var auth path ().
  *
- * the upstream tool, Codex CLI, and gh CLI all ship a way to authenticate via
+ * the upstream tool, peer CLI, and gh CLI all ship a way to authenticate via
  * an environment variable so CI / container / scripted contexts can
  * skip the device flow entirely. This module backs that path:
  *

package/dist/core/context/markdown-traverse.js

@@ -2,7 +2,7 @@
  * Per-directory PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md traverse-up
  * loader — β5a R4+P5.
  *
- * the upstream tool, Codex CLI, and Gemini CLI all support a "walk up from
+ * the upstream tool, peer CLI, and Gemini CLI all support a "walk up from
  * cwd to the workspace root, pick up agent-context markdown at every
  * level" pattern. Without this, a `pugi explain` invoked from
  * `apps/admin-api/` cannot see project-local conventions encoded in

package/dist/core/credentials.js

@@ -6,7 +6,7 @@ import { z } from 'zod';
  * Local credentials store for the Pugi CLI.
  *
  * Stored at `~/.pugi/credentials.json` (mode 0o600). Mirrors the convention
- * Codex CLI uses (`~/.codex/auth.json`) and matches gh CLI's per-host
+ * peer CLI uses (`~/.codex/auth.json`) and matches gh CLI's per-host
  * token model. The store is intentionally file-based, not OS keychain —
  * adding the native `keytar` dep would force per-platform native builds
  * across npm distribution and complicate the install path. The 0600

package/dist/core/engine/anvil-client.js

@@ -257,6 +257,23 @@ export class AnvilEngineLoopClient {
                     message: 'runtime rate limit reached for this tenant',
                 };
             }
+            // PUGI-490 (2026-06-03): structured envelope for upstream-proxy
+            // static error pages. When the response body is HTML (the upstream
+            // proxy's static 5xx page rather than a NestJS JSON envelope), the
+            // raw truncated HTML is useless to operators — it cannot point at
+            // what failed. Parse the `cf-ray` request id so the operator can
+            // look the request up in the proxy dashboard, and surface a
+            // remediation hint pointing at the engine VM logs.
+            const cfDetails = detectUpstreamProxyError(res, text);
+            if (cfDetails) {
+                return {
+                    stop: 'error',
+                    code: 'failed',
+                    message: `runtime error (cf-ray: ${cfDetails.cfRay ?? 'unknown'}) — ` +
+                        `upstream proxy returned ${res.status} static page. ` +
+                        `Check engine VM logs for the correlating request id.`,
+                };
+            }
             return {
                 stop: 'error',
                 code: 'failed',
@@ -278,4 +295,50 @@ export class AnvilEngineLoopClient {
         }
     }
 }
+/**
+ * PUGI-490 (2026-06-03): detect when the response body is a static HTML
+ * error page emitted by the upstream proxy (rather than a JSON envelope
+ * produced by admin-api). Returns the cf-ray request id when matched, so
+ * the CLI can surface a meaningful runtime-error envelope instead of
+ * truncating raw HTML in front of the operator.
+ *
+ * Heuristic: the body starts with `<!DOCTYPE` or `<html`, or carries the
+ * `cf-ray` response header. We require BOTH conditions when the body is
+ * non-empty (defense against admin-api accidentally emitting an HTML
+ * fragment) and accept just the header when the body is empty (some
+ * proxy 5xx variants ship empty bodies). The function is intentionally
+ * permissive — false positives produce a clearer error than false
+ * negatives, and the message still includes "upstream proxy" so the
+ * operator knows the call did not reach a Pugi controller.
+ *
+ * Exported for unit testing; not for runtime callers.
+ */
+export function detectUpstreamProxyError(res, body) {
+    if (res.status < 500)
+        return null;
+    // Pull cf-ray via the same getter shim the version-interceptor uses;
+    // it tolerates both real `Response.headers.get` and fixture/stub
+    // headers represented as plain objects.
+    const h = res.headers;
+    const readHeader = (name) => {
+        if (h && typeof h.get === 'function') {
+            return h.get(name);
+        }
+        if (h && typeof h === 'object') {
+            const lowered = h[name.toLowerCase()];
+            return lowered ?? null;
+        }
+        return null;
+    };
+    const cfRay = readHeader('cf-ray');
+    const bodyTrimmed = (body ?? '').trimStart();
+    const looksHtml = bodyTrimmed.startsWith('<!DOCTYPE') ||
+        bodyTrimmed.startsWith('<!doctype') ||
+        bodyTrimmed.startsWith('<html');
+    if (looksHtml)
+        return { cfRay };
+    if (cfRay && bodyTrimmed.length === 0)
+        return { cfRay };
+    return null;
+}
 //# sourceMappingURL=anvil-client.js.map

package/dist/core/engine/native-pugi.js

@@ -1127,7 +1127,7 @@ function extractPathArg(raw) {
         const parsed = JSON.parse(raw);
         if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
             const obj = parsed;
-            // Accept canonical `path` OR the Claude-Code-trained `filePath`
+            // Accept canonical `path` OR the peer-CLI-trained `filePath`
             // alias so the filesChanged summary captures writes regardless of
             // which key the model emitted. Without the alias the operator
             // sees "Files modified: none" even when a write actually landed,

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

@@ -27,6 +27,14 @@ 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`.
@@ -94,6 +102,27 @@ const READ_ONLY_TOOLS = new Set([
     // 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
@@ -152,6 +181,24 @@ const WIRED_TOOLS = new Set([
     // 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',
 ]);
 export function buildToolsSchema(kind, options = { allowFetch: false, allowSearch: false }) {
     const planMode = kind === 'plan';
@@ -372,6 +419,162 @@ export function buildToolsSchema(kind, options = { allowFetch: false, allowSearc
             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
@@ -989,6 +1192,16 @@ export function buildExecutor(input) {
                 }
                 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 {
@@ -1514,9 +1727,232 @@ const POST_EDIT_TOOLS = new Set(['edit', 'write', 'multi_edit']);
  * 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);

package/dist/core/hooks/events.js

@@ -25,7 +25,7 @@
  *
  * Brand voice: ASCII only, no emoji, no em-dashes, no marketing prose.
  */
-/** Events the MVP actually fires. The 6 deferred events live in the */
+/** Events the MVP actually fires. The remaining events live in the */
 /** type but no integration point emits them yet. */
 export const MVP_HOOK_EVENTS = [
     'SessionStart',
@@ -40,5 +40,7 @@ export const ALL_HOOK_EVENTS_V2 = [
     'SubagentStop',
     'PreCompact',
     'Notification',
+    'WorktreeCreate',
+    'WorktreeRemove',
 ];
 //# sourceMappingURL=events.js.map

package/dist/core/hooks/registry.js

@@ -71,6 +71,9 @@ const hookEventEnum = z.enum([
     'SubagentStop',
     'PreCompact',
     'Notification',
+    // PUGI-487 - user-facing worktree lifecycle events.
+    'WorktreeCreate',
+    'WorktreeRemove',
 ]);
 const hooksFileSchema = z
     .object({