@entelligentsia/forgecli 0.15.0 → 0.20.0

package/dist/extensions/forgecli/fix-bug.js

@@ -13,58 +13,59 @@
 //
 // sendKickoff is NEVER called from this file.
 // Audit-grep: grep -n "sendKickoff(" fix-bug.ts must return empty.
+//
+// N-H-C — bugId dual-assignment lifecycle:
+//   Phase 1 (handler entry, ~line 1372): bugId = `PENDING-${Date.now()}`, isNewBug = true.
+//     A temporary placeholder; the timestamp is later used to find the real bug record.
+//   Phase 2 (pre-init, ~line 1495–1500): preCreateBug() writes a minimal bug record with a
+//     real FORGE-BUG-NNN ID so the triage subagent has a stable ID to reference.
+//     If preCreateBug fails, the PENDING- placeholder is kept for fallback capture.
+//   Phase 3 (post-triage, ~line 962–989): capture real ID from BugCreated events emitted by
+//     the triage subagent; fall back to listing the most-recent bug after pipelineStart if
+//     event capture fails. The PENDING- prefix is used throughout as a guard for
+//     state-write paths (see ~line 176 and CallerContextStore guards).
+//   Reference: PENDING- prefix semantics defined in CallerContextStore guards.
+//
+// N-H-H — Preflight gate design (closed by FORGE-S25-T17):
+//   Entry-level: runOrchestratorPreflight is called at runBugPipeline entry (~line 523).
+//     Validates persona/model config before any LLM dispatch (mirrors run-task.ts design).
+//   Per-phase: runPreflightGate (store-cli gate) is called per phase (~line 667).
+//     Evaluates declarative gate conditions from the workflow's gate block.
+//   This two-level design ensures both structural validity (model/persona config) and
+//   store-state validity (predecessor verdicts, status guards) are checked.
+//   Reference: lib/orchestrator-preflight.ts (N-H-H, FORGE-S25-T17).
+//
+// N-H-E tag: see inline comment at the materialization skip (~line 707 / checkMaterialization).
+import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawnSync } from "node:child_process";
+import { assertAudience, CallerContextStore } from "./audience-gate.js";
 // ModelRegistry/AuthStorage no longer instantiated here — use ctx.modelRegistry
 // so extension-registered providers (registered against the live session) are
 // visible to validateModelConfig. Creating a fresh registry here would miss
 // them and produce spurious MODEL_UNAVAILABLE warnings (FORGE-BUG-001).
 import { loadLayeredConfig } from "./config-layer.js";
-import { resolveModelForPhase } from "./model-resolver.js";
-import { validateModelConfig } from "./model-validator.js";
-import { assertAudience, CallerContextStore } from "./audience-gate.js";
-import { resolveToCanonicalId, resolveToolDir } from "./store-resolver.js";
-import { checkMaterialization } from "./plan.js";
 import { loadForgePersona, runForgeSubagent } from "./forge-subagent.js";
-import { discoverForgeConfig } from "./forge-root.js";
-import { loadWorkflow } from "./loaders/workflow-loader.js";
+import { getSubagentTools } from "./forge-tools.js";
+import { readPersonaDir as readPersonaDirBug, readPipelineNames as readPipelineNamesBug, } from "./lib/catalog-helpers.js";
+import { discoverForgeConfigCached } from "./lib/forge-config.js";
+import { checkMaterialization } from "./lib/manifest-checker.js";
+import { runOrchestratorPreflight } from "./lib/orchestrator-preflight.js";
+import { resolveModelForPhase } from "./model-resolver.js";
+import { loadWorkflow } from "./parsers/workflow-loader.js";
+import { buildPhaseEvent, drainFrictionFile, emitEvent, findPredecessorIndex, formatLocalTime, isNonInteractive, judgementFromSummary, runPreflightGate, validateId, } from "./run-task.js";
 import { getSessionRegistry } from "./session-registry.js";
+import { resolveToCanonicalId, resolveToolDir } from "./store-resolver.js";
 import { attachViewportObserver } from "./viewport-events.js";
 import { fmtPhaseSummary } from "./viewport-renderer.js";
-import { validateId, isNonInteractive, formatLocalTime, emitEvent, findPredecessorIndex, runPreflightGate, buildPhaseEvent, drainFrictionFile, judgementFromSummary, } from "./run-task.js";
 // ── Bug phase descriptor table ──────────────────────────────────────────────
 //
 // Decoded from .forge/workflows/fix_bug.md and the task prompt's BUG_PHASES.
 // triage / plan-fix / implement all read the same fix_bug.md body — the
 // workflow handles all three phases through prose.
-function readPersonaDirBug(dir) {
-    try {
-        return fs.readdirSync(dir)
-            .filter((f) => f.endsWith(".md") && !f.endsWith("-skills.md"))
-            .map((f) => f.replace(/\.md$/, ""));
-    }
-    catch {
-        return [];
-    }
-}
-function readPipelineNamesBug(forgeCfgPath) {
-    try {
-        const raw = fs.readFileSync(forgeCfgPath, "utf-8");
-        const cfg = JSON.parse(raw);
-        if (cfg && typeof cfg === "object" && "pipelines" in cfg) {
-            const pipelines = cfg.pipelines;
-            if (pipelines && typeof pipelines === "object")
-                return Object.keys(pipelines);
-            return [];
-        }
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
+// FORGE-S25-T16: readPersonaDirBug / readPipelineNamesBug extracted to
+// lib/catalog-helpers.ts and imported above with aliases (H-4, N-H-G).
 export const BUG_PHASES = [
     { role: "triage", workflowFile: "fix_bug", personaNoun: "bug-fixer", isReview: false, maxIterations: 1 },
     { role: "plan-fix", workflowFile: "fix_bug", personaNoun: "bug-fixer", isReview: false, maxIterations: 1 },
@@ -78,25 +79,25 @@ export const BUG_PHASES = [
 // Phases mapped to null use update-status bug instead of set-bug-summary
 // for verdict tracking (Option B).
 export const BUG_SUMMARY_KEY_BY_ROLE = {
-    "triage": "triage",
+    triage: "triage",
     "plan-fix": "plan",
     "review-plan": "review_plan",
-    "implement": "implementation",
+    implement: "implementation",
     "review-code": "code_review",
-    "approve": "approve", // read from bug.summaries.approve (set-bug-summary)
-    "commit": null, // commit transitions bug.status → fixed (terminal), no summaries entry
+    approve: "approve", // read from bug.summaries.approve (set-bug-summary)
+    commit: null, // commit transitions bug.status → fixed (terminal), no summaries entry
 };
 // Bug-event type tokens — explicit mapping per review finding #3.
 // Non-review phases always emit the pass token. Review phases select
 // pass or fail based on ec.judgement.verdict.
 export const BUG_TYPE_TOKENS = {
-    "triage": { pass: "bug-triaged", fail: "bug-triaged" },
+    triage: { pass: "bug-triaged", fail: "bug-triaged" },
     "plan-fix": { pass: "fix-planned", fail: "fix-planned" },
     "review-plan": { pass: "fix-review-passed", fail: "fix-review-failed" },
-    "implement": { pass: "fix-implemented", fail: "fix-implemented" },
+    implement: { pass: "fix-implemented", fail: "fix-implemented" },
     "review-code": { pass: "fix-code-review-passed", fail: "fix-code-review-failed" },
-    "approve": { pass: "fix-approved", fail: "fix-revision-requested" },
-    "commit": { pass: "bug-committed", fail: "bug-commit-failed" },
+    approve: { pass: "fix-approved", fail: "fix-revision-requested" },
+    commit: { pass: "bug-committed", fail: "bug-commit-failed" },
 };
 // ── Bug FSM transitions ────────────────────────────────────────────────────
 // Mirrors store-cli BUG_TRANSITIONS. Terminal: `fixed`.
@@ -143,9 +144,7 @@ export function readBugState(cwd, bugId, sessionId) {
                     bestFile = fp;
                 }
             }
-            catch {
-                continue;
-            }
+            catch { }
         }
     }
     catch {
@@ -182,7 +181,9 @@ export function deleteBugState(cwd, bugId) {
                 try {
                     fs.unlinkSync(path.join(cacheDir, entry));
                 }
-                catch { /* non-fatal */ }
+                catch {
+                    /* non-fatal */
+                }
             }
         }
     }
@@ -227,7 +228,9 @@ export function assignNextBugId(storeCli, cwd) {
                 }
             }
         }
-        catch { /* empty store — start from 1 */ }
+        catch {
+            /* empty store — start from 1 */
+        }
     }
     const next = maxNum + 1;
     return `FORGE-BUG-${String(next).padStart(3, "0")}`;
@@ -321,13 +324,13 @@ export function composeBugBody(subWorkflowMd, bugId, phaseRole, bugStatusBeforeP
         `  node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary ${bugId} approve <APPROVE-SUMMARY.json>`,
         `  The summary's "verdict" field MUST be "approved" or "revision". The downstream commit gate reads this, not bug.status.`,
         `- Commit phase: on successful git commit, run \`node "$FORGE_ROOT/tools/store-cli.cjs" update-status bug ${bugId} status fixed\` (terminal).`,
-        `- Do NOT write \"approved\" or \"verified\" to bug.status — those values were removed from the schema in forge v0.44.0.`,
-        `- Do NOT reference task-specific status values (e.g., \"committed\") or task entity kind.`,
+        `- Do NOT write "approved" or "verified" to bug.status — those values were removed from the schema in forge v0.44.0.`,
+        `- Do NOT reference task-specific status values (e.g., "committed") or task entity kind.`,
         "- CRITICAL: All `set-summary` calls must use `set-bug-summary` (not `set-summary`).",
         `  e.g. node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary ${bugId} review_plan <jsonFile>`,
         `- Preflight gate: use \`--bug\` flag (not \`--task\`). e.g. node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase review-plan --bug ${bugId}`,
         "- Skip re-running preflight-gate — the orchestrator already checked it. Proceed directly to the review.",
-        "Any workflow text that says \"task\" should be read as \"bug\" for this context.",
+        'Any workflow text that says "task" should be read as "bug" for this context.',
     ];
     // Phase-specific reinforcement when the orchestrator can name the current status.
     if (phaseRole === "approve" && bugStatusBeforePhase) {
@@ -337,7 +340,7 @@ export function composeBugBody(subWorkflowMd, bugId, phaseRole, bugStatusBeforeP
         entityKindLines.push(`- Commit phase: after the git commit lands, transition bug.status from '${bugStatusBeforePhase}' to 'fixed'.`);
     }
     if (phaseRole === "triage") {
-        entityKindLines.push("- Triage phase: in addition to writing TRIAGE.md and TRIAGE-SUMMARY.json, the summary MUST include a `route` field set to `\"A\"` or `\"B\"`.", "  Path A (short-circuit): severity == minor AND single-file fix ≤ ~20 lines AND no schema/API/migration AND regression test obvious from repro.", "  Path B (default): everything else. When in doubt, choose B.", "  The orchestrator reads bug.summaries.triage.route to select the downstream phase list.");
+        entityKindLines.push('- Triage phase: in addition to writing TRIAGE.md and TRIAGE-SUMMARY.json, the summary MUST include a `route` field set to `"A"` or `"B"`.', "  Path A (short-circuit): severity == minor AND single-file fix ≤ ~20 lines AND no schema/API/migration AND regression test obvious from repro.", "  Path B (default): everything else. When in doubt, choose B.", "  The orchestrator reads bug.summaries.triage.route to select the downstream phase list.");
     }
     return [
         `Read the workflow below and follow it. Bug ID: ${bugId}.`,
@@ -413,14 +416,14 @@ export function extractBugIdFromEvents(events) {
 const STATUS_KEY = "forge:fix-bug";
 const MESSAGE_KEY = "forge:fix-bug:message";
 export async function runBugPipeline(opts) {
-    const { bugId: initialBugId, originalArg, isNewBug, cwd, ctx, forgeRoot, storeCli, preflightGate, registry, resumeFromState } = opts;
+    const { bugId: initialBugId, originalArg, isNewBug, cwd, ctx, forgeRoot, storeCli, preflightGate, registry, resumeFromState, } = opts;
     // Mutable bugId — for new bugs, pre-assign a real FORGE-BUG-NNN ID
     // before triage so the subagent never needs to create or discover one.
     // This replaces the fragile PENDING→capture pattern where the subagent was
     // expected to create the bug record and we'd fish the ID from events.
     let bugId = initialBugId;
     let currentPhaseIndex = resumeFromState?.phaseIndex ?? 0;
-    let iterationCounts = resumeFromState?.iterationCounts ?? {};
+    const iterationCounts = resumeFromState?.iterationCounts ?? {};
     let lastModel;
     let lastProvider;
     // ── Per-persona model routing (Plan 16) ─────────────────────────────────
@@ -428,28 +431,42 @@ export async function runBugPipeline(opts) {
     // config produces inherit for every phase — no behaviour change. Pipeline
     // name "fix-bug" lets users configure per-phase overrides distinctly from
     // task pipelines under pipelines["fix-bug"] in their routing config.
-    const { merged: modelRoutingConfig } = loadLayeredConfig(cwd);
+    // N-B-E: surface schema errors to caller (Decision 9 — orchestrators fail-fast).
+    // See doc/decisions/layered-config-error-policy.md.
+    const { merged: modelRoutingConfig, errors: layeredConfigErrors } = loadLayeredConfig(cwd);
+    if (layeredConfigErrors.length > 0) {
+        for (const e of layeredConfigErrors) {
+            ctx.ui.notify(`× forge:fix-bug — forge-cli config schema error: ${e}`, "error");
+        }
+        return {
+            status: "failed",
+            lastPhaseIndex: currentPhaseIndex,
+            iterationCounts,
+            lastError: `forge-cli config schema errors: ${layeredConfigErrors.join("; ")}`,
+        };
+    }
     // Pre-flight validation — same shape as run-task / run-sprint.
+    // FORGE-S25-T17: delegated to lib/orchestrator-preflight.ts (H-13).
     {
         const personasDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "forge-payload", ".base-pack", "personas");
         const personaCatalogue = readPersonaDirBug(personasDir);
         const forgeCfgPath = path.join(cwd, ".forge", "config.json");
         const pipelineCatalogue = readPipelineNamesBug(forgeCfgPath);
         const availableModels = ctx.modelRegistry?.getAvailable?.() ?? [];
-        const strict = process.env.FORGE_STRICT_MODELS === "1";
-        const { errors, warnings } = validateModelConfig(personaCatalogue, pipelineCatalogue, modelRoutingConfig, availableModels.map((m) => ({ provider: m.provider, id: m.id })), strict);
-        for (const w of warnings) {
-            ctx.ui.notify(`⚠ forge:fix-bug — model routing: ${w.message}`, "warning");
-        }
-        if (errors.length > 0) {
-            for (const e of errors) {
-                ctx.ui.notify(`× forge:fix-bug — model routing: ${e.message}`, "error");
-            }
+        const preflightResult = runOrchestratorPreflight({
+            mode: "task",
+            ctx,
+            notifyPrefix: "forge:fix-bug",
+            personaCatalogue,
+            pipelineCatalogue,
+            modelRoutingConfig,
+            availableModels: availableModels.map((m) => ({ provider: m.provider, id: m.id })),
+        });
+        if (!preflightResult.proceed) {
             return {
-                status: "failed",
+                ...preflightResult.result,
                 lastPhaseIndex: currentPhaseIndex,
                 iterationCounts,
-                lastError: `model config validation failed: ${errors.map((e) => e.code).join(", ")}`,
             };
         }
     }
@@ -474,7 +491,12 @@ export async function runBugPipeline(opts) {
         const phase = BUG_PHASES[currentPhaseIndex];
         if (!phase) {
             ctx.ui.notify(`× forge:fix-bug — invalid phase index ${currentPhaseIndex}`, "error");
-            return { status: "failed", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `invalid phase index ${currentPhaseIndex}` };
+            return {
+                status: "failed",
+                lastPhaseIndex: currentPhaseIndex,
+                iterationCounts,
+                lastError: `invalid phase index ${currentPhaseIndex}`,
+            };
         }
         ctx.ui.setStatus?.(STATUS_KEY, `fix-bug ${bugId}: phase ${currentPhaseIndex + 1}/${BUG_PHASES.length} (${phase.role})`);
         ctx.ui.notify(`→ ${bugId}: ${phase.role} (phase ${currentPhaseIndex + 1}/${BUG_PHASES.length})`, "info");
@@ -498,7 +520,12 @@ export async function runBugPipeline(opts) {
                 lastError: `sub-workflow read failed: ${e.message ?? "unknown"}`,
                 savedAt: new Date().toISOString(),
             });
-            return { status: "failed", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `sub-workflow read failed: ${e.message ?? "unknown"}` };
+            return {
+                status: "failed",
+                lastPhaseIndex: currentPhaseIndex,
+                iterationCounts,
+                lastError: `sub-workflow read failed: ${e.message ?? "unknown"}`,
+            };
         }
         // ── 6a. Phase skip (state-aware, defense-in-depth) ─────────────
         // Belt-and-suspenders alongside the explicit summaries.triage.route
@@ -513,8 +540,8 @@ export async function runBugPipeline(opts) {
         // removed.
         const PHASE_SKIP_STATES = {
             "plan-fix": new Set(["fixed"]),
-            "implement": new Set(["fixed"]),
-            "commit": new Set(["fixed"]), // commit writes the terminal status; skip if already there
+            implement: new Set(["fixed"]),
+            commit: new Set(["fixed"]), // commit writes the terminal status; skip if already there
         };
         const bugNow = readBugRecord(bugId, storeCli, cwd);
         const skipStates = PHASE_SKIP_STATES[phase.role];
@@ -536,14 +563,19 @@ export async function runBugPipeline(opts) {
                 };
                 const synthFile = path.join(cwd, ".forge", "cache", `synthetic-summary-${bugId}-${summaryKey}.json`);
                 fs.writeFileSync(synthFile, JSON.stringify(synthSummary, null, 2), "utf8");
-                const synthResult = spawnSync("node", [storeCli, "set-bug-summary", bugId, summaryKey, synthFile], { cwd, encoding: "utf8" });
+                const synthResult = spawnSync("node", [storeCli, "set-bug-summary", bugId, summaryKey, synthFile], {
+                    cwd,
+                    encoding: "utf8",
+                });
                 if (synthResult.status !== 0) {
                     ctx.ui.notify(`⚠ forge:fix-bug — synthetic summary write failed for ${phase.role}: ${String(synthResult.stderr).trim()}`, "warning");
                 }
                 try {
                     fs.unlinkSync(synthFile);
                 }
-                catch { /* non-fatal */ }
+                catch {
+                    /* non-fatal */
+                }
             }
             currentPhaseIndex++;
             continue;
@@ -573,7 +605,12 @@ export async function runBugPipeline(opts) {
                     lastError: `preflight gate exit 1 for ${phase.role}`,
                     savedAt: new Date().toISOString(),
                 });
-                return { status: "halted", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `preflight gate exit 1 for ${phase.role}` };
+                return {
+                    status: "halted",
+                    lastPhaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    lastError: `preflight gate exit 1 for ${phase.role}`,
+                };
             }
             if (preflightResult === "escalate") {
                 ctx.ui.notify(`× forge:fix-bug — preflight gate escalated for phase ${phase.role} (exit 2); manual intervention required.`, "error");
@@ -585,11 +622,16 @@ export async function runBugPipeline(opts) {
                     lastError: `preflight gate exit 2 (escalate) for ${phase.role}`,
                     savedAt: new Date().toISOString(),
                 });
-                return { status: "escalated", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `preflight gate exit 2 (escalate) for ${phase.role}` };
+                return {
+                    status: "escalated",
+                    lastPhaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    lastError: `preflight gate exit 2 (escalate) for ${phase.role}`,
+                };
             }
         }
         // ── 6. Materialization-marker check ───────────────────────────
-        // Skip for the monolithic fix_bug.md — it is the orchestrator prose
+        // N-H-E: Skip for the monolithic fix_bug.md — it is the orchestrator prose
         // algorithm, not a sub-workflow that subagents run tool calls against.
         // Triage/plan-fix/implement phases reference fix_bug.md for their
         // prose body but the actual tool-use discipline (Store-Write Verification,
@@ -601,7 +643,12 @@ export async function runBugPipeline(opts) {
                 for (const marker of markerCheck.missing) {
                     ctx.ui.notify(`× workflow regression: ${marker} not found in ${subWorkflowPath}`, "error");
                 }
-                return { status: "failed", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `materialization markers missing: ${markerCheck.missing.join(", ")}` };
+                return {
+                    status: "failed",
+                    lastPhaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    lastError: `materialization markers missing: ${markerCheck.missing.join(", ")}`,
+                };
             }
         }
         // ── 5. Audience check ─────────────────────────────────────────
@@ -610,7 +657,8 @@ export async function runBugPipeline(opts) {
         // Skip the audience gate for the monolithic fix_bug.md; only check the
         // true sub-workflows (review_plan, review_code, architect_approve, commit_task)
         // which the subagent does run directly.
-        const audienceOk = phase.workflowFile === "fix_bug" || CallerContextStore.asSubagent(() => assertAudience({ workflowName: phase.workflowFile, audience: subWorkflowAudience }, ctx));
+        const audienceOk = phase.workflowFile === "fix_bug" ||
+            CallerContextStore.asSubagent(() => assertAudience({ workflowName: phase.workflowFile, audience: subWorkflowAudience }, ctx));
         if (!audienceOk) {
             writeBugState(cwd, {
                 bugId,
@@ -620,7 +668,12 @@ export async function runBugPipeline(opts) {
                 lastError: `audience check failed for ${phase.workflowFile}`,
                 savedAt: new Date().toISOString(),
             });
-            return { status: "failed", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `audience check failed for ${phase.workflowFile}` };
+            return {
+                status: "failed",
+                lastPhaseIndex: currentPhaseIndex,
+                iterationCounts,
+                lastError: `audience check failed for ${phase.workflowFile}`,
+            };
         }
         // ── Persona load ──────────────────────────────────────────────
         let persona;
@@ -639,7 +692,12 @@ export async function runBugPipeline(opts) {
                 lastError: `persona load failed: ${e.message ?? "unknown"}`,
                 savedAt: new Date().toISOString(),
             });
-            return { status: "failed", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `persona load failed: ${e.message ?? "unknown"}` };
+            return {
+                status: "failed",
+                lastPhaseIndex: currentPhaseIndex,
+                iterationCounts,
+                lastError: `persona load failed: ${e.message ?? "unknown"}`,
+            };
         }
         // ── Read bug record for current status ────────────────────────
         // Skip for PENDING bugIds (bug doesn't exist yet).
@@ -681,7 +739,9 @@ export async function runBugPipeline(opts) {
                             fs.writeFileSync(debugLogPath, lines.slice(-keep).join("\n"), "utf8");
                         }
                     }
-                    catch { /* file may not exist yet */ }
+                    catch {
+                        /* file may not exist yet */
+                    }
                     fs.appendFileSync(debugLogPath, `${JSON.stringify({ ts: new Date().toISOString(), phase: phase.role, ...rec })}\n`, "utf8");
                 }
                 catch {
@@ -749,11 +809,14 @@ export async function runBugPipeline(opts) {
                 // Keeps every phase of this bug-fix pipeline in a single cache
                 // namespace so the system-prompt + persona prefix stays warm
                 // across the ~10-minute phases.
-                cacheSessionId: typeof bugRecordBefore?.sprintId === "string" ? `forge:${bugRecordBefore.sprintId}` : `forge:bug:${bugId}`,
+                cacheSessionId: typeof bugRecordBefore?.sprintId === "string"
+                    ? `forge:${bugRecordBefore.sprintId}`
+                    : `forge:bug:${bugId}`,
                 onEvent: onSubagentEvent,
                 requestedModel: modelResolution.model,
                 modelRegistry: ctx.modelRegistry,
-                signal: opts.signal, // ← wire AbortSignal for cancellation
+                signal: opts.signal,
+                customTools: opts.forgeToolDefs ? getSubagentTools(opts.forgeToolDefs, persona.name) : undefined,
             });
         }
         catch (err) {
@@ -767,7 +830,12 @@ export async function runBugPipeline(opts) {
                 lastError: `runForgeSubagent threw: ${e.message ?? "unknown"}`,
                 savedAt: new Date().toISOString(),
             });
-            return { status: "failed", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `runForgeSubagent threw: ${e.message ?? "unknown"}` };
+            return {
+                status: "failed",
+                lastPhaseIndex: currentPhaseIndex,
+                iterationCounts,
+                lastError: `runForgeSubagent threw: ${e.message ?? "unknown"}`,
+            };
         }
         // ── Post-subagent abort detection ─────────────────────────────────
         if (result.stopReason === "aborted" || opts.signal?.aborted) {
@@ -799,7 +867,12 @@ export async function runBugPipeline(opts) {
                 lastError: result.errorMessage ?? result.stopReason ?? "subagent exit non-zero",
                 savedAt: new Date().toISOString(),
             });
-            return { status: "failed", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: result.errorMessage ?? result.stopReason ?? "subagent exit non-zero" };
+            return {
+                status: "failed",
+                lastPhaseIndex: currentPhaseIndex,
+                iterationCounts,
+                lastError: result.errorMessage ?? result.stopReason ?? "subagent exit non-zero",
+            };
         }
         // Capture model/provider from subagent result.
         if (result.model)
@@ -827,19 +900,29 @@ export async function runBugPipeline(opts) {
                             const recent = bugs
                                 .filter((b) => b.reportedAt && b.reportedAt >= pipelineStartIso)
                                 .sort((a, b) => String(b.reportedAt).localeCompare(String(a.reportedAt)))[0];
-                            if (recent && recent.bugId && typeof recent.bugId === "string" && recent.bugId.startsWith("FORGE-BUG-")) {
+                            if (recent &&
+                                recent.bugId &&
+                                typeof recent.bugId === "string" &&
+                                recent.bugId.startsWith("FORGE-BUG-")) {
                                 bugId = recent.bugId;
                                 ctx.ui.notify(`forge:fix-bug — captured bug ID via store fallback: ${bugId}`, "info");
                             }
                         }
                     }
-                    catch { /* parse failure — fall through to assertion */ }
+                    catch {
+                        /* parse failure — fall through to assertion */
+                    }
                 }
             }
             // Defensive guard: if bugId is still PENDING after triage, pipeline cannot proceed.
             if (bugId.startsWith("PENDING-")) {
                 ctx.ui.notify("× forge:fix-bug — failed to capture real bug ID after triage. Cannot proceed with PENDING placeholder.", "error");
-                return { status: "failed", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: "bugId still PENDING after triage" };
+                return {
+                    status: "failed",
+                    lastPhaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    lastError: "bugId still PENDING after triage",
+                };
             }
             // Re-initialize debug log now that real bugId is available.
             if (!debugLogDisabled) {
@@ -857,7 +940,9 @@ export async function runBugPipeline(opts) {
                                 fs.writeFileSync(debugLogPath, lines.slice(-keep).join("\n"), "utf8");
                             }
                         }
-                        catch { /* file may not exist yet */ }
+                        catch {
+                            /* file may not exist yet */
+                        }
                         fs.appendFileSync(debugLogPath, `${JSON.stringify({ ts: new Date().toISOString(), phase: phase.role, ...rec })}\n`, "utf8");
                     }
                     catch {
@@ -970,7 +1055,12 @@ export async function runBugPipeline(opts) {
                     lastError: `verdict missing for ${phase.role}`,
                     savedAt: new Date().toISOString(),
                 });
-                return { status: "failed", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `verdict missing for ${phase.role}` };
+                return {
+                    status: "failed",
+                    lastPhaseIndex: currentPhaseIndex,
+                    iterationCounts,
+                    lastError: `verdict missing for ${phase.role}`,
+                };
             }
             if (verdict === "revision") {
                 iterationCounts[phase.role] = (iterationCounts[phase.role] ?? 0) + 1;
@@ -985,7 +1075,12 @@ export async function runBugPipeline(opts) {
                         lastError: `revision cap reached for ${phase.role}`,
                         savedAt: new Date().toISOString(),
                     });
-                    return { status: "escalated", lastPhaseIndex: currentPhaseIndex, iterationCounts, lastError: `revision cap reached for ${phase.role}` };
+                    return {
+                        status: "escalated",
+                        lastPhaseIndex: currentPhaseIndex,
+                        iterationCounts,
+                        lastError: `revision cap reached for ${phase.role}`,
+                    };
                 }
                 // Transition bug back to in-progress before re-dispatching implement.
                 // This is required for review-code → implement and approve → implement loops.
@@ -1054,7 +1149,13 @@ export async function runBugPipeline(opts) {
     }
     // ── All phases complete ───────────────────────────────────────────
     deleteBugState(cwd, bugId);
-    return { status: "completed", lastPhaseIndex: BUG_PHASES.length - 1, iterationCounts, model: lastModel, provider: lastProvider };
+    return {
+        status: "completed",
+        lastPhaseIndex: BUG_PHASES.length - 1,
+        iterationCounts,
+        model: lastModel,
+        provider: lastProvider,
+    };
 }
 export function registerFixBug(pi, options = {}) {
     pi.registerCommand("forge:fix-bug", {
@@ -1070,7 +1171,7 @@ export function registerFixBug(pi, options = {}) {
             }
             ctx.ui.setStatus?.(STATUS_KEY, `fix-bug: initializing…`);
             // ── Discover forge config ────────────────────────────────────────
-            const forgeConfig = discoverForgeConfig(cwd);
+            const forgeConfig = discoverForgeConfigCached(cwd);
             if (!forgeConfig) {
                 ctx.ui.notify("× forge:fix-bug — no Forge project found at cwd. Run /forge:init first.", "error");
                 ctx.ui.setStatus?.(STATUS_KEY, undefined);
@@ -1086,8 +1187,7 @@ export function registerFixBug(pi, options = {}) {
             let isNewBug = false;
             // Check if arg looks like it could be a bug ID (prefixed or unprefixed).
             // Covers: FORGE-BUG-042, BUG-042, B042.
-            const looksLikeBugId = /^(?:[A-Z0-9]+-)?(?:BUG-?\d+|B\d+)$/i.test(rawArg) ||
-                /^BUG-\d+$/i.test(rawArg);
+            const looksLikeBugId = /^(?:[A-Z0-9]+-)?(?:BUG-?\d+|B\d+)$/i.test(rawArg) || /^BUG-\d+$/i.test(rawArg);
             if (/^FORGE-BUG-\d+$/.test(rawArg)) {
                 // Canonical bug ID — verify it exists
                 bugId = rawArg;
@@ -1108,7 +1208,10 @@ export function registerFixBug(pi, options = {}) {
                 // Unprefixed bug ID — resolve through the store cascade.
                 // Issue #20: unprefixed entity IDs silently poisoned substitutions.
                 const toolDir = resolveToolDir(forgeRoot);
-                const resolvedBugId = await resolveToCanonicalId(rawArg, toolDir, cwd, "bug", { ctx, commandLabel: "forge:fix-bug" });
+                const resolvedBugId = await resolveToCanonicalId(rawArg, toolDir, cwd, "bug", {
+                    ctx,
+                    commandLabel: "forge:fix-bug",
+                });
                 if (!resolvedBugId) {
                     // Error already emitted by resolver
                     ctx.ui.setStatus?.(STATUS_KEY, undefined);
@@ -1178,9 +1281,7 @@ export function registerFixBug(pi, options = {}) {
                     // (explicit failure), halted=false (cancelled/interrupted), and
                     // any state with existing.status set.
                     const stateStatus = existing.status ?? (existing.halted ? "halted" : "interrupted");
-                    const statusLabel = stateStatus === "cancelled" ? "cancelled"
-                        : stateStatus === "halted" ? "halted"
-                            : "interrupted";
+                    const statusLabel = stateStatus === "cancelled" ? "cancelled" : stateStatus === "halted" ? "halted" : "interrupted";
                     const phaseRole = BUG_PHASES[existing.phaseIndex]?.role ?? existing.phaseIndex;
                     if (!isNonInteractive()) {
                         const resume = await ctx.ui.confirm(`Resume ${bugId}?`, `Cached state — phase ${existing.phaseIndex} (${phaseRole}), ${statusLabel}, ` +
@@ -1236,7 +1337,7 @@ export function registerFixBug(pi, options = {}) {
             // needs the real ID before startSession is called.
             if (isNewBug && bugId.startsWith("PENDING-")) {
                 const realBugId = assignNextBugId(storeCli, cwd);
-                const title = (rawArg && !rawArg.startsWith("@")) ? rawArg.slice(0, 120) : "New bug (pending triage)";
+                const title = rawArg && !rawArg.startsWith("@") ? rawArg.slice(0, 120) : "New bug (pending triage)";
                 if (preCreateBug(realBugId, title, storeCli, cwd)) {
                     ctx.ui.notify(`forge:fix-bug — pre-assigned bug ID: ${realBugId}`, "info");
                     bugId = realBugId;
@@ -1261,7 +1362,8 @@ export function registerFixBug(pi, options = {}) {
                 preflightGate,
                 registry,
                 resumeFromState,
-                signal, // ← wire AbortSignal for cancellation
+                signal,
+                forgeToolDefs: options.forgeToolDefs,
             });
             // ── Handle result ────────────────────────────────────────────────
             if (pipelineResult.status === "completed") {