pan-wizard 3.34.0 → 3.36.0

package/bin/install-lib.cjs

@@ -1160,11 +1160,16 @@ function stripThinkingFrontmatter(content, runtime) {
  */
 function buildCopilotHooksConfig(commands) {
   const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand,
-    stateReinjectMarkCommand, stateReinjectInjectCommand } = commands || {};
+    stateReinjectMarkCommand, stateReinjectInjectCommand, guardCommand } = commands || {};
   const config = { version: 1, hooks: {} };
   if (updateCheckCommand) {
     config.hooks.sessionStart = [{ type: 'command', command: updateCheckCommand }];
   }
+  // preToolUse: the PAN guard (A7). Copilot denies a call on the JSON
+  // `permissionDecision: "deny"` output, which pan-guard.js prints under `--host copilot`.
+  if (guardCommand) {
+    config.hooks.preToolUse = [{ type: 'command', command: guardCommand }];
+  }
   const postToolUse = [];
   if (contextMonitorCommand) postToolUse.push({ type: 'command', command: contextMonitorCommand });
   // State re-injection after a compaction (M33): preCompact leaves the marker, the
@@ -1238,10 +1243,10 @@ function buildCopilotHooksConfig(commands) {
  * 2026-10-03, and live on Copilot CLI 1.0.88 the same day).
  */
 const HOOK_EVENT_MAP = Object.freeze({
-  claude: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
-  gemini: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: null, subagentStop: null, stop: 'AfterAgent', compact: null, compactMark: 'PreCompress', compactInject: 'AfterTool' },
-  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
-  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', postToolUse: 'postToolUse', subagentStop: 'subagentStop', stop: 'agentStop', compact: null, compactMark: 'preCompact', compactInject: 'postToolUse' },
+  claude: { surface: 'settings.json', sessionStart: 'SessionStart', preToolUse: 'PreToolUse', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
+  gemini: { surface: 'settings.json', sessionStart: 'SessionStart', preToolUse: 'BeforeTool', postToolUse: null, subagentStop: null, stop: 'AfterAgent', compact: null, compactMark: 'PreCompress', compactInject: 'AfterTool' },
+  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', preToolUse: 'PreToolUse', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
+  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', preToolUse: 'preToolUse', postToolUse: 'postToolUse', subagentStop: 'subagentStop', stop: 'agentStop', compact: null, compactMark: 'preCompact', compactInject: 'postToolUse' },
   opencode: null,
 });
 
@@ -1253,7 +1258,7 @@ const HOOK_EVENT_MAP = Object.freeze({
 const HOOK_SLOT_MATCHERS = Object.freeze({ compact: 'compact' });
 
 /** The hook scripts PAN registers in a Claude-shaped settings.json `hooks` block. */
-const PAN_SETTINGS_HOOKS = Object.freeze(['pan-check-update', 'pan-context-monitor', 'pan-cost-logger', 'pan-trace-logger', 'pan-stop-guard', 'pan-state-reinject']);
+const PAN_SETTINGS_HOOKS = Object.freeze(['pan-check-update', 'pan-guard', 'pan-context-monitor', 'pan-cost-logger', 'pan-trace-logger', 'pan-stop-guard', 'pan-state-reinject']);
 
 /**
  * Remove, from every event array of a Claude-shaped `hooks` object except
@@ -1384,10 +1389,78 @@ function mergeMcpRegistration(existing, runtime, entry, serverName = 'pan') {
   const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
   const key = spec.key;
   if (!config[key] || typeof config[key] !== 'object' || Array.isArray(config[key])) config[key] = {};
+  // OpenCode 2 nests servers under `mcp.servers` (R47). PAN keeps writing the v1
+  // shape, but in a file the user already converted it updates the native entry and
+  // never leaves a legacy `mcp.pan` beside it: the native one would win, stale.
+  if (runtime === 'opencode' && isOpencodeV2Servers(config[key].servers)) {
+    config[key].servers[serverName] = entry;
+    delete config[key][serverName];
+    return config;
+  }
   config[key][serverName] = entry;
   return config;
 }
 
+/** OpenCode 2's `mcp.servers` container: an object of server entries, not a v1 server named "servers". */
+function isOpencodeV2Servers(v) {
+  return !!v && typeof v === 'object' && !Array.isArray(v) && !('type' in v) && !('command' in v);
+}
+
+/**
+ * Add PAN's OpenCode read and external_directory allowances for `panPath`.
+ * v1 (or a new file): the `permission` object PAN has always written. v2 (the file
+ * already has an ordered `permissions[]` of {action, resource, effect}): PAN's rules
+ * go into that array, and no legacy `permission` object is added beside it (R47).
+ * @returns {{config: object, modified: boolean, shape: 'v1'|'v2'}}
+ */
+function addOpencodePermissions(existing, panPath) {
+  const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
+  let modified = false;
+  if (Array.isArray(config.permissions)) {
+    for (const action of ['read', 'external_directory']) {
+      const has = config.permissions.some((r) => r && r.action === action && r.resource === panPath && r.effect === 'allow');
+      if (!has) { config.permissions.push({ action, resource: panPath, effect: 'allow' }); modified = true; }
+    }
+    return { config, modified, shape: 'v2' };
+  }
+  if (!config.permission || typeof config.permission !== 'object' || Array.isArray(config.permission)) config.permission = {};
+  for (const type of ['read', 'external_directory']) {
+    if (!config.permission[type] || typeof config.permission[type] !== 'object') config.permission[type] = {};
+    if (config.permission[type][panPath] !== 'allow') { config.permission[type][panPath] = 'allow'; modified = true; }
+  }
+  return { config, modified, shape: 'v1' };
+}
+
+/**
+ * Remove every PAN allowance from an OpenCode config, in either shape: keys of the
+ * v1 `permission.read` / `permission.external_directory` objects and v2
+ * `permissions[]` rules whose path names `pan-wizard` (which also catches the
+ * malformed `~/.config/opencode/pan-wizard/*` key early versions wrote). Containers
+ * PAN emptied are removed.
+ * @returns {{config: object, modified: boolean}}
+ */
+function stripOpencodePermissions(existing) {
+  const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
+  let modified = false;
+  if (config.permission && typeof config.permission === 'object' && !Array.isArray(config.permission)) {
+    for (const type of ['read', 'external_directory']) {
+      const bag = config.permission[type];
+      if (!bag || typeof bag !== 'object') continue;
+      for (const key of Object.keys(bag)) if (key.includes('pan-wizard')) { delete bag[key]; modified = true; }
+      if (Object.keys(bag).length === 0) delete config.permission[type];
+    }
+    if (Object.keys(config.permission).length === 0) delete config.permission;
+  }
+  if (Array.isArray(config.permissions)) {
+    const kept = config.permissions.filter((r) => !(r && typeof r.resource === 'string' && r.resource.includes('pan-wizard')));
+    if (kept.length !== config.permissions.length) {
+      modified = true;
+      if (kept.length) config.permissions = kept; else delete config.permissions;
+    }
+  }
+  return { config, modified };
+}
+
 /**
  * Remove PAN's MCP server from a config object, preserving foreign entries.
  * Empties the container key when PAN was its only member, so uninstall does not
@@ -1400,10 +1473,17 @@ function stripMcpRegistration(existing, runtime, serverName = 'pan') {
   if (!spec) throw new Error(`stripMcpRegistration: unknown runtime "${runtime}"`);
   const config = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
   const bag = config[spec.key];
-  if (!bag || typeof bag !== 'object' || !(serverName in bag)) return { config, removed: false };
-  delete bag[serverName];
-  if (Object.keys(bag).length === 0) delete config[spec.key];
-  return { config, removed: true };
+  if (!bag || typeof bag !== 'object') return { config, removed: false };
+  let removed = false;
+  // OpenCode 2's `mcp.servers.pan` as well as the v1 `mcp.pan` (R47).
+  if (runtime === 'opencode' && isOpencodeV2Servers(bag.servers) && serverName in bag.servers) {
+    delete bag.servers[serverName];
+    if (Object.keys(bag.servers).length === 0) delete bag.servers;
+    removed = true;
+  }
+  if (serverName in bag) { delete bag[serverName]; removed = true; }
+  if (removed && Object.keys(bag).length === 0) delete config[spec.key];
+  return { config, removed };
 }
 
 /**
@@ -1439,7 +1519,7 @@ function buildCodexMcpSnippet(serverPath, panToolsPath, projectRoot, serverName
  * @returns {object} Merged config object to serialize back to hooks.json
  */
 function mergeCodexHooksConfig(existing, commands) {
-  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand } = commands || {};
+  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand, guardCommand } = commands || {};
   const config = (existing && typeof existing === 'object') ? existing : {};
   if (!config.hooks || typeof config.hooks !== 'object') config.hooks = {};
 
@@ -1461,6 +1541,8 @@ function mergeCodexHooksConfig(existing, commands) {
   // builders without reading their docs first.
   const wanted = [
     ['SessionStart', updateCheckCommand, 'pan-check-update', true],
+    // The guard decides whether a call may run, which an async handler cannot (A7).
+    ['PreToolUse', guardCommand, 'pan-guard', false],
     ['PostToolUse', contextMonitorCommand, 'pan-context-monitor', false],
     ['SubagentStop', costLoggerCommand, 'pan-cost-logger', true],
     ['SubagentStop', traceLoggerCommand, 'pan-trace-logger', true],
@@ -1504,7 +1586,7 @@ function removeCodexPanHooks(existing) {
   for (const event of Object.keys(existing.hooks)) {
     if (!Array.isArray(existing.hooks[event])) continue;
     existing.hooks[event] = existing.hooks[event].filter(group =>
-      !(Array.isArray(group.hooks) && group.hooks.some(h => h.command && /pan-(check-update|context-monitor|cost-logger|trace-logger|stop-guard|state-reinject)/.test(h.command))));
+      !(Array.isArray(group.hooks) && group.hooks.some(h => h.command && /pan-(check-update|guard|context-monitor|cost-logger|trace-logger|stop-guard|state-reinject)/.test(h.command))));
     if (existing.hooks[event].length === 0) delete existing.hooks[event];
   }
   if (Object.keys(existing.hooks).length === 0) delete existing.hooks;
@@ -1929,15 +2011,16 @@ function buildPluginManifest(pkg) {
  * @returns {object} hooks.json object
  */
 function buildPluginHooksConfig() {
-  const hook = (script, matcher) => ({
+  const hook = (script, matcher, args = '') => ({
     ...(matcher ? { matcher } : {}),
-    hooks: [{ type: 'command', command: `node "\${CLAUDE_PLUGIN_ROOT}/hooks/${script}"` }],
+    hooks: [{ type: 'command', command: `node "\${CLAUDE_PLUGIN_ROOT}/hooks/${script}"${args}` }],
   });
   const events = HOOK_EVENT_MAP.claude;
   return {
     hooks: {
       // compact shares SessionStart with the update check, narrowed by its matcher (M10).
       [events.sessionStart]: [hook('pan-check-update.js'), hook('pan-state-reinject.js', HOOK_SLOT_MATCHERS.compact)],
+      [events.preToolUse]: [hook('pan-guard.js', null, ' --host claude')],
       [events.postToolUse]: [hook('pan-context-monitor.js')],
       [events.subagentStop]: [hook('pan-cost-logger.js'), hook('pan-trace-logger.js')],
       [events.stop]: [hook('pan-stop-guard.js')],
@@ -2147,7 +2230,7 @@ const FINDINGS = {
         properties: {
           title: { type: 'string' },
           file: { type: 'string' },
-          severity: { type: 'string', enum: ['critical', 'major', 'minor', 'info'] },
+          severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'] }, // PAN's one ladder (verdict.cjs, review-deep.cjs)
           detail: { type: 'string' },
         },
         required: ['title', 'severity', 'detail'],
@@ -2256,6 +2339,7 @@ return { areas_mapped: maps.filter(Boolean).length, synthesis }
     { title: 'Index', detail: 'plan inventory with wave grouping, from the PAN engine' },
     { title: 'Execute', detail: 'one executor per plan; waves in order, plans within a wave in parallel' },
     { title: 'Verify', detail: 'the phase verifier over the completed plans' },
+    { title: 'Gate', detail: 'the PAN phase gate: stops when the phase may not be completed' },
   ],
 }
 // twin: pan-wizard-core/workflows/exec-phase.md
@@ -2377,7 +2461,24 @@ const verdict = await agent(
   'Verify phase ' + phaseArg + ' following the PAN verify-phase protocol (PAN core: workflows/verify-phase.md — ' + PAN_TOOLS + '). Check the phase goals against what the plans delivered, write the verification file the protocol prescribes, and report status (passed | gaps_found | human_needed | failed), the verification file path, any gaps, and a summary. Do not mark the phase complete or advance state — that decision stays with the user.',
   { agentType: 'pan-verifier', label: 'verify', phase: 'Verify', schema: VERIFY })
 
-return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: verdict, next: 'Review the verification, then continue with /pan:exec-phase ' + phaseArg + ' (transition) or /pan:plan-phase for the next phase' }
+phase('Gate')
+const GATE = {
+  type: 'object',
+  properties: {
+    ok: { type: 'boolean' },
+    mode: { type: 'string' },
+    reasons: { type: 'array', items: { type: 'object', properties: { code: { type: 'string' }, detail: { type: 'string' } }, required: ['code'] } },
+  },
+  required: ['ok', 'reasons'],
+}
+const gate = await agent(
+  'Run the PAN phase gate for phase ' + phaseArg + ' with the ' + PAN_TOOLS + ' Run exactly: phase gate ' + phaseArg + ' (it exits 1 when it refuses; that is a result, not an error). Return its JSON fields ok, mode and reasons (each code and detail) unchanged. Do not fix anything and do not mark the phase complete.',
+  { label: 'gate', phase: 'Gate', schema: GATE })
+const gateReasons = gate && Array.isArray(gate.reasons) ? gate.reasons : []
+if (!gate || gate.ok !== true) {
+  return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: verdict, gate, halted: 'phase_gate', next: 'The phase gate refused: ' + (gateReasons.map((r) => r.code).join(', ') || 'the gate step returned no verdict') + '. Fix each reason (or close the gaps with /pan:plan-phase ' + phaseArg + ' --gaps), then re-run /pan:exec-phase ' + phaseArg + '. Do not mark the phase complete until the gate passes.' }
+}
+return { phase: phaseArg, waves_run: waveNumbers.length, plans_complete: executed.length, verification: verdict, gate, next: 'The phase gate passes. Continue with /pan:exec-phase ' + phaseArg + ' (transition) or /pan:plan-phase for the next phase' }
 `;
 
   const diagnoseIssues = `export const meta = {
@@ -2559,6 +2660,8 @@ module.exports = {
   buildMcpServerEntry,
   mergeMcpRegistration,
   stripMcpRegistration,
+  addOpencodePermissions,
+  stripOpencodePermissions,
   buildCodexMcpSnippet,
   removeCodexPanHooks,
   buildNativeWorkflowScripts,

package/bin/install.js

@@ -369,13 +369,11 @@ function getCommitAttribution(runtime) {
     const settings = readSettings(path.join(getGlobalDir('claude', explicitConfigDir), 'settings.json')) || {}; // unusable file = no info (read-only probe)
     result = lib.commitAttributionFromSettings(settings);
   } else if (runtime === 'copilot') {
-    // Copilot CLI: user-editable settings live in settings.json; config.json is
-    // legacy (auto-migrated by the CLI, now internal state) — fall back for old installs
+    // Copilot CLI: user settings live in settings.json only. config.json is the CLI's
+    // internal state, and Copilot 1.0.93 ignores user settings there (R48), so a
+    // stale `attribution` left in it must not decide PAN's attribution.
     const copilotDir = getGlobalDir('copilot', explicitConfigDir);
-    let config = readSettings(path.join(copilotDir, 'settings.json')) || {}; // unusable file = no info (read-only probe)
-    if (!config.attribution) {
-      config = readSettings(path.join(copilotDir, 'config.json')) || {}; // unusable file = no info (read-only probe)
-    }
+    const config = readSettings(path.join(copilotDir, 'settings.json')) || {}; // unusable file = no info (read-only probe)
     if (!config.attribution || config.attribution.commit === undefined) {
       result = undefined;
     } else if (config.attribution.commit === '') {
@@ -1222,7 +1220,7 @@ function uninstall(isGlobal, runtime = 'claude') {
   // 4. Remove PAN hooks (scripts + Copilot CLI hooks config file)
   const hooksDir = path.join(targetDir, 'hooks');
   if (fs.existsSync(hooksDir)) {
-    const panHooks = ['pan-statusline.js', 'pan-check-update.js', 'pan-check-update.sh', 'pan-context-monitor.js', 'pan-cost-logger.js', 'pan-trace-logger.js', 'pan-stop-guard.js', 'pan-state-reinject.js', 'pan.json'];
+    const panHooks = ['pan-statusline.js', 'pan-check-update.js', 'pan-check-update.sh', 'pan-guard.js', 'pan-context-monitor.js', 'pan-cost-logger.js', 'pan-trace-logger.js', 'pan-stop-guard.js', 'pan-state-reinject.js', 'pan.json'];
     let hookCount = 0;
     for (const hook of panHooks) {
       const hookPath = path.join(hooksDir, hook);
@@ -1576,35 +1574,12 @@ function uninstall(isGlobal, runtime = 'claude') {
       // CodeQL js/file-system-race. Same idiom as the hooks' metrics read.
       try {
         const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-        let modified = false;
-
-        // Remove PAN permission entries
-        if (config.permission) {
-          for (const permType of ['read', 'external_directory']) {
-            if (config.permission[permType]) {
-              const keys = Object.keys(config.permission[permType]);
-              for (const key of keys) {
-                // Match `pan-wizard` rather than `pan-wizard-core` so the malformed
-                // key earlier versions wrote (`~/.config/opencode/pan-wizard/*`) is
-                // cleaned too. Without this, machines that ran any global OpenCode
-                // install before the glob was fixed keep that entry forever — the
-                // uninstaller could never match it, which is what made it residue
-                // rather than a cosmetic typo.
-                if (key.includes('pan-wizard')) {
-                  delete config.permission[permType][key];
-                  modified = true;
-                }
-              }
-              // Clean up empty objects
-              if (Object.keys(config.permission[permType]).length === 0) {
-                delete config.permission[permType];
-              }
-            }
-          }
-          if (Object.keys(config.permission).length === 0) {
-            delete config.permission;
-          }
-        }
+        let modified;
+
+        // Remove PAN permission entries, v1 `permission` keys and OpenCode 2
+        // `permissions[]` rules alike (R47). Keys matching `pan-wizard` rather than
+        // `pan-wizard-core` also clean the malformed key earlier versions wrote.
+        ({ modified } = lib.stripOpencodePermissions(config));
 
         if (modified) {
           // If stripping PAN permissions emptied the config, remove the file
@@ -1718,6 +1693,18 @@ function uninstall(isGlobal, runtime = 'claude') {
     console.log(`  ${yellow}⚠${reset} No PAN files found to remove.`);
   }
 
+  // A local install's runtime directory that the removal left empty goes too (X1).
+  // Never a global one (~/.claude and the like are the host's own homes), and never a
+  // directory that still holds anything: `.github` usually holds the project's files.
+  if (!isGlobal) {
+    try {
+      if (fs.readdirSync(targetDir).length === 0) {
+        fs.rmdirSync(targetDir);
+        console.log(`  ${green}✓${reset} Removed empty ${locationLabel}`);
+      }
+    } catch { /* already gone or unreadable: leave it */ }
+  }
+
   console.log(`
   ${green}Done!${reset} PAN has been uninstalled from ${runtimeLabel}.
   Your other files and settings have been preserved.
@@ -1760,10 +1747,6 @@ function configureOpencodePermissions(isGlobal = true) {
     }
   }
 
-  // Ensure permission structure exists
-  if (!config.permission) {
-    config.permission = {};
-  }
 
   // Build the PAN path using the actual config directory
   // Use ~ shorthand if it's in the default location, otherwise use full path
@@ -1780,25 +1763,9 @@ function configureOpencodePermissions(isGlobal = true) {
     ? '~/.config/opencode/pan-wizard-core/*'
     : `${opencodeConfigDir.replace(/\\/g, '/')}/pan-wizard-core/*`;
   
-  let modified = false;
-
-  // Configure read permission
-  if (!config.permission.read || typeof config.permission.read !== 'object') {
-    config.permission.read = {};
-  }
-  if (config.permission.read[panPath] !== 'allow') {
-    config.permission.read[panPath] = 'allow';
-    modified = true;
-  }
-
-  // Configure external_directory permission (the safety guard for paths outside project)
-  if (!config.permission.external_directory || typeof config.permission.external_directory !== 'object') {
-    config.permission.external_directory = {};
-  }
-  if (config.permission.external_directory[panPath] !== 'allow') {
-    config.permission.external_directory[panPath] = 'allow';
-    modified = true;
-  }
+  // v1 `permission` object in a new or v1 file; the native `permissions[]` array
+  // in a file the user already converted to OpenCode 2, never both (R47).
+  const { modified } = lib.addOpencodePermissions(config, panPath);
 
   if (!modified) {
     return; // Already configured
@@ -2785,6 +2752,10 @@ function install(isGlobal, runtime = 'claude') {
   const stateReinjectCommand = isGlobal
     ? buildHookCommand(targetDir, 'pan-state-reinject.js')
     : 'node ' + dirName + '/hooks/pan-state-reinject.js';
+  // The guard names its host: payloads and the way to deny differ per runtime (A7).
+  const guardCommand = (isGlobal
+    ? buildHookCommand(targetDir, 'pan-guard.js')
+    : 'node ' + dirName + '/hooks/pan-guard.js') + ` --host ${runtime}`;
   // Gemini and Copilot (M33): a marker before the compaction, the block on the next
   // tool result. The inject mode names the host, whose output shapes differ.
   const stateReinjectMarkCommand = `${stateReinjectCommand} --mark`;
@@ -2798,7 +2769,7 @@ function install(isGlobal, runtime = 'claude') {
   if (!isOpencode) {
     const entrypoints = lib.verifyHookEntrypoints([
       updateCheckCommand, contextMonitorCommand, statuslineCommand, costLoggerCommand,
-      traceLoggerCommand, stopGuardCommand, stateReinjectCommand, stateReinjectMarkCommand, stateReinjectInjectCommand,
+      traceLoggerCommand, stopGuardCommand, stateReinjectCommand, stateReinjectMarkCommand, stateReinjectInjectCommand, guardCommand,
     ], process.cwd());
     if (!entrypoints.ok) {
       console.error(`\n  ${red}✖ Hook verification FAILED — these hook commands would run a script that is not there:${reset}`);
@@ -2818,7 +2789,7 @@ function install(isGlobal, runtime = 'claude') {
       let existing = null;
       try { existing = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8')); } catch { /* absent or invalid — start fresh */ }
       const merged = lib.mergeCodexHooksConfig(existing, {
-        updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand,
+        updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectCommand, guardCommand,
       });
       fs.writeFileSync(hooksJsonPath, JSON.stringify(merged, null, 2) + '\n');
       // Print the path we actually wrote. The hardcoded '.codex/hooks.json' was
@@ -2836,7 +2807,7 @@ function install(isGlobal, runtime = 'claude') {
   // from any legacy config.json registration.
   if (isCopilot) {
     const hooksConfigPath = path.join(targetDir, 'hooks', 'pan.json');
-    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectMarkCommand, stateReinjectInjectCommand });
+    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectMarkCommand, stateReinjectInjectCommand, guardCommand });
     try {
       fs.mkdirSync(path.dirname(hooksConfigPath), { recursive: true });
       fs.writeFileSync(hooksConfigPath, JSON.stringify(hooksConfig, null, 2) + '\n');
@@ -2930,6 +2901,7 @@ function install(isGlobal, runtime = 'claude') {
     // unbuilt phases — fail-open and inert outside PAN projects.
     const registrations = [
       { slot: 'sessionStart', hook: 'pan-check-update', command: updateCheckCommand, label: 'update check hook' },
+      { slot: 'preToolUse', hook: 'pan-guard', command: guardCommand, label: 'pre-tool guard hook' },
       { slot: 'postToolUse', hook: 'pan-context-monitor', command: contextMonitorCommand, label: 'context window monitor hook' },
       { slot: 'subagentStop', hook: 'pan-cost-logger', command: costLoggerCommand, label: 'cost logger hook' },
       { slot: 'subagentStop', hook: 'pan-trace-logger', command: traceLoggerCommand, label: 'trace logger hook' },

package/commands/pan/cost.md

@@ -2,7 +2,7 @@
 name: pan:cost
 group: Observability
 description: Show token usage and estimated cost across PAN commands and agents
-argument-hint: "[report|append|clear|rebuild|limits] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [--no-main-thread]"
+argument-hint: "[report|append|clear|rebuild|limits|budget] [--format json|table|chart] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--apply] [--no-main-thread]"
 allowed-tools:
   - Read
   - Bash
@@ -16,10 +16,6 @@ Reads `.planning/metrics/tokens.jsonl` — an append-only log where each line is
 Default output is JSON for piping. Use `--format table` for human-readable tables or `--format chart` for an ASCII bar chart of daily spend; both print text, with or without `--raw`.
 </objective>
 
-<execution_context>
-@~/.claude/pan-wizard-core/bin/lib/cost.cjs
-</execution_context>
-
 <subcommands>
 
 ### `report` (default)
@@ -81,6 +77,26 @@ Delete the cost log. Useful at the start of a billing cycle.
 pan-tools cost clear
 ```
 
+### `budget`
+
+A phase's spend against its budget: `cost.phase_budget_usd` in `.planning/config.json`, **20 dollars per phase by default**, `0` to turn it off. Change it with `/pan:settings` or `pan-tools config-set cost.phase_budget_usd 50`. It only warns: `near` from 80% of the budget, `over` once spend reaches it; nothing ever stops on it. exec-phase reports it after each wave and plan-phase in its final status. On a subscription the dollars are API-equivalent (the tokens priced at the rate table).
+
+```
+pan-tools cost budget --phase <N> [--raw]
+```
+
+Prints `{phase, budget_usd, spent_usd, pct, status, mode, warn_at_pct, unpriced}`; `status` is `off`, `ok`, `near` or `over`, and `--raw` prints it. `unpriced` counts the phase's rows with no known rate (not added to the spend).
+
+### `usage` (census)
+
+Which of the installed PAN commands and agents this project has used, from its own files only: the cost ledger and the trace sessions. Nothing is sent anywhere.
+
+```
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs usage [--raw]
+```
+
+Prints `{local_only, commands: {used, never_used, unfinished, installed}, agents: {used, never_used, installed}, sources}`. Each used entry has `calls` and `last_used`, and a command also has `sessions` and `finished`. `unfinished` lists commands that were started but never finished: every trace session for them stopped without ending, the newest more than six hours ago. `--raw` prints a one-line summary. Use it to see which parts of PAN this project actually runs.
+
 ### `limits`
 
 `pan-tools cost limits` shows Claude Code's 5-hour and 7-day usage windows as the status line last saw them, and whether the 7-day one has reached `cost.weekly_limit_stop_pct` (default 90%), where `/pan:focus-auto` and `/pan:army` stop. Interactive Claude Code sessions on a subscription only: headless runs and other runtimes have no reading.

package/commands/pan/dashboard.md

@@ -20,6 +20,3 @@ pan-tools hud [--out <file>] [--open] [--stdout]
 See **`/pan:hud`** for the full panel list, flags, JSON result shape, and runtime compatibility. The two commands are interchangeable.
 </objective>
 
-<execution_context>
-@~/.claude/pan-wizard-core/bin/lib/hud.cjs
-</execution_context>

package/commands/pan/design-phase.md

@@ -53,7 +53,7 @@ ELSE (default):
 1. **Validate phase** — error if the phase number is missing or not in `roadmap.md`.
 2. **Prime context** — resolve the phase directory; gather `{phase}-context.md`, `{phase}-research.md`, and the phase boundary from `roadmap.md`.
 3. **Design** — spawn `pan-designer` with a `<files_to_read>` block (context, research, roadmap boundary, `CLAUDE.md`). It fills in `templates/design.md` at the `phase` tier (`spike` if `--spike`).
-4. **Verify (reflexion loop)** — spawn `pan-design-checker` with the drafted design + the boundary source:
+4. **Verify (reflexion loop)** — spawn `pan-design-checker` with the drafted design + the boundary source, plus an `<open_findings>` block holding `pan-tools findings list --phase {phase} --agent pan-design-checker --status open` (empty on the first check):
    - If it PASSES → done.
    - If it finds gaps (iteration 1) → `pan-designer` revises (address genuine gaps only), re-check.
    - If it finds gaps (iteration 2) → final revision, record remaining gaps as caveats.
@@ -62,7 +62,7 @@ ELSE (default):
      ```bash
      node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "{phase}" --agent pan-design-checker --file "{phase_dir}/{padded_phase}-design-check.md" --raw
      ```
-     A re-check is the next attempt and closes the gaps it no longer reports. When the final iteration still has gaps, record them as the caveats they are before writing the design:
+     A re-check is the next attempt. It answers each earlier gap in `resolutions`, and the record closes the ones answered `resolved` with evidence; a gap it neither reports nor answers stays open. When the final iteration still has gaps, record them as the caveats they are before writing the design:
      ```bash
      node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "{phase}" --agent pan-design-checker --open --as deferred --reason "design caveat after 2 revision iterations"
      ```

package/commands/pan/hud.md

@@ -16,10 +16,6 @@ It is a *view*, not a new source of truth: every panel aggregates state PAN alre
 Default output is `.planning/hud.html`. Open it in any browser. Re-run any time for a fresh snapshot.
 </objective>
 
-<execution_context>
-@~/.claude/pan-wizard-core/bin/lib/hud.cjs
-</execution_context>
-
 <usage>
 
 ```
@@ -62,7 +58,7 @@ Panels render only when they have data — a plain (non-army) project still gets
 | **Requirements & quality** | Requirements done/open + last verification artifacts | `requirements.md`, phase `*-verification.md` / `*-uat.md` |
 | **Recent activity** | Last commits (the army's committed output) | `git log` |
 
-*(army)* panels appear only when a campaign is scheduled or army worktrees exist — graceful degradation per ADR-0035. The *(fallback)* **Planning activity** panel appears only when there is no phase/roadmap layout, so it fills the gap for focus-auto and imported projects instead of leaving a bare page. Telemetry shows an honest advisory (never a fabricated `$0.00`) when the cost ledger is poisoned or every record is unpriced.
+*(army)* panels appear only when a campaign is scheduled or army worktrees exist — graceful degradation per ADR-0035. The *(fallback)* **Planning activity** panel appears only when there is no phase/roadmap layout, so it fills the gap for focus-auto and imported projects instead of leaving a bare page. Telemetry shows an honest advisory (never a fabricated zero-dollar total) when the cost ledger is poisoned or every record is unpriced.
 
 </panels>
 

package/commands/pan/knowledge.md

@@ -23,7 +23,6 @@ Consolidates Spec B v1's X-3 converse + X-6 teach + X-10 explain into one comman
 </objective>
 
 <execution_context>
-@~/.claude/pan-wizard-core/bin/lib/knowledge.cjs
 @~/.claude/agents/pan-knowledge.md
 @~/.claude/pan-wizard-core/templates/playbook.md
 </execution_context>

package/commands/pan/mcp-bridge.md

@@ -15,9 +15,7 @@ Surface Model Context Protocol (MCP) tools visible to the host runtime and recom
 Reduced scope from Spec B v1's X-7: **discovery and recommendation only**. Auto-injection of MCP tools into planner context and auto-invocation from executor agents are deliberately deferred and still unscheduled (the v3.5 target passed without them). This kept v3.3 narrow and avoids coupling PAN to Claude Code's MCP schema stability.
 </objective>
 
-<execution_context>
-@~/.claude/pan-wizard-core/bin/lib/bridge.cjs
-</execution_context>
+Each subcommand runs `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs bridge <list|recommend|cache> [flags]`. The CLI verb is `bridge`, not `mcp-bridge`: `pan-tools mcp-bridge` is an unknown command.
 
 <subcommands>
 

package/commands/pan/optimize.md

@@ -111,3 +111,5 @@ List all trace sessions, most recent first.
 Each iteration puts what the last run lacked where the next run's agents read it: fewer repeated errors and gaps.
 
 **See also:** `/pan:learn`, `/pan:exec-phase`
+
+Follow the workflow at `~/.claude/pan-wizard-core/workflows/optimize.md`. Each subcommand runs `node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize <subcommand> [flags]` — e.g. `optimize apply --report <path>`, `optimize revert --last`, `optimize trace init --description "..."`.

package/commands/pan/phase-tests.md

@@ -1,7 +1,7 @@
 ---
 name: pan:phase-tests
 group: Phase Management
-description: Generate tests for a completed phase based on UAT criteria and implementation
+description: Generate tests for a completed phase from its summaries, context decisions, verification report and implementation
 argument-hint: "<phase> [additional instructions]"
 allowed-tools:
   - Read

package/commands/pan/preview.md

@@ -19,7 +19,6 @@ Consolidates Spec B v1's architect + simulate + predict-milestone into one entry
 </objective>
 
 <execution_context>
-@~/.claude/pan-wizard-core/bin/lib/preview.cjs
 @~/.claude/pan-wizard-core/templates/preview-report.md
 </execution_context>
 
@@ -32,7 +31,7 @@ Consolidates Spec B v1's architect + simulate + predict-milestone into one entry
 ```
 
 **What it does:**
-1. `pan-tools preview phase <N>` returns `{files_mentioned, test_files_mentioned, risk_signals, risk_score, plans[], status}`.
+1. `pan-tools preview phase <N>` returns `{files_mentioned, test_files_mentioned, risk_signals, risk_score, plans[], status, cost_forecast}`. `cost_forecast` gives p10/p50/p90 dollars per plan (`per_plan`) and for the phase (`phase`) from this project's own cost ledger, or `status: insufficient` with `n` when fewer than five past runs back it.
 2. Spawn `pan-previewer` with the payload as `<preview_input>`.
 3. Agent writes `.planning/phases/<NN-slug>/preview.md` with files touched / tests at risk / migration steps / risk assessment / bottom line.
 
@@ -74,7 +73,7 @@ Consolidates Spec B v1's architect + simulate + predict-milestone into one entry
 
 **Before committing to a milestone date externally:** run `/pan:preview milestone`. Look at `confidence_pct` and `sample_size`. If sample is <3, don't promise a date.
 
-**Before running phases in parallel:** run `/pan:preview phases`. Parallel batches from the data layer are based on declared `depends_on` only; `hidden_coupling_count > 0` means there are cross-phase references the author should promote to explicit deps before parallelizing.
+**Before running phases in parallel:** run `/pan:preview phases`. Parallel batches from the data layer are based on declared dependencies only — the roadmap's `**Depends on:** Phase N` line and any `phase:N` entry in a plan's `depends_on`; `hidden_coupling_count > 0` means there are cross-phase references the author should promote to explicit deps (on the roadmap's Depends on line) before parallelizing.
 
 </workflow>
 

package/commands/pan/report.md

@@ -13,13 +13,9 @@ Render **self-contained HTML reports** — no server, no network, no external CS
 
 Like `pan:hud`, these are *views*, not a new source of truth: every value is read from what PAN already tracks on disk (the phase's `plan`/`summary`/`verification` artifacts and their frontmatter, `roadmap.md`, and the cost ledger). The command only writes the rendered file(s), so it can never corrupt planning data. Reports reuse the HUD's visual language, so they look like part of the same product.
 
-Reports are honest by construction: the `verify reconcile` verdict is shown beside the (rubber-stampable) self-reported verification status, status is framed as a current-disk snapshot, and any spend is gated so a poisoned or unpriced ledger never renders a fake `$0`.
+Reports are honest by construction: the `verify reconcile` verdict is shown beside the (rubber-stampable) self-reported verification status, status is framed as a current-disk snapshot, and any spend is gated so a poisoned or unpriced ledger never renders a fake zero-dollar spend.
 </objective>
 
-<execution_context>
-@~/.claude/pan-wizard-core/bin/lib/phase-report.cjs
-</execution_context>
-
 <usage>
 
 ```

package/commands/pan/research-phase.md

@@ -137,8 +137,8 @@ Write to: {phase_dir}/{padded_phase}-research.md
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-phase-researcher.md for your role and instructions.\n\n" + filled_prompt,
-  subagent_type="general-purpose",
+  prompt=filled_prompt,
+  subagent_type="pan-phase-researcher",
   model="{researcher_model}",
   description="Research Phase {phase}"
 )
@@ -171,8 +171,8 @@ Continue research for Phase {phase_number}: {phase_name}
 
 ```
 Task(
-  prompt="First, read ~/.claude/agents/pan-phase-researcher.md for your role and instructions.\n\n" + continuation_prompt,
-  subagent_type="general-purpose",
+  prompt=continuation_prompt,
+  subagent_type="pan-phase-researcher",
   model="{researcher_model}",
   description="Continue research Phase {phase}"
 )

package/commands/pan/review-deep.md

@@ -24,8 +24,6 @@ Consolidates Spec B v1's X-4 (self-review) + X-12 (harden) into a single command
 </objective>
 
 <execution_context>
-@~/.claude/pan-wizard-core/bin/lib/review-deep.cjs
-@~/.claude/pan-wizard-core/bin/lib/bus.cjs
 @~/.claude/agents/pan-hardener.md
 @~/.claude/agents/pan-meta-reviewer.md
 </execution_context>