pan-wizard 3.34.0 → 3.35.0

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

@@ -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)

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>
 
@@ -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>

package/commands/pan/what-if.md

@@ -20,7 +20,6 @@ Unchanged from Spec B v1's X-9. Already narrow enough to stand alone.
 </objective>
 
 <execution_context>
-@~/.claude/pan-wizard-core/bin/lib/whatif.cjs
 @~/.claude/agents/pan-counterfactual.md
 </execution_context>
 
@@ -80,7 +79,7 @@ This writes `.planning/counterfactuals/<phase>-<slug>.md`. The file belongs to t
 pan-tools whatif cleanup --worktree <path> --branch <name> --force
 ```
 
-Removes the worktree directory and deletes the counterfactual branch. Best-effort: warnings are surfaced but don't block.
+Removes the worktree directory and deletes the counterfactual branch. Pass the `worktree.worktree_path` and `worktree.branch` that `whatif prepare` returned, unchanged. Cleanup refuses (exit 1, nothing removed) a branch outside `pan-whatif/` and a worktree that is not checked out on that branch, so it can never delete your own work. Otherwise best-effort: warnings are surfaced but don't block.
 
 ### Stage 5 — Confirm
 

package/hooks/dist/pan-context-monitor.js

@@ -429,14 +429,23 @@ function buildContextWarning(metrics, warnState, nowSeconds, opts = {}) {
   };
 }
 
-/** Claude Code's settings for a project, highest precedence first: local, project, user. */
-function readClaudeSettings(projectDir, homeDir = os.homedir()) {
+/**
+ * Claude Code's settings for a project, highest precedence first: local, project, user.
+ * The user file lives in CLAUDE_CONFIG_DIR when that is set, as Claude Code reads it.
+ * A given homeDir is a test seam and ignores CLAUDE_CONFIG_DIR (as the statusline and
+ * hygiene do), unless configDir is passed too.
+ */
+function readClaudeSettings(projectDir, homeArg, configArg) {
+  const seam = homeArg !== undefined;
+  const homeDir = seam ? homeArg : os.homedir();
+  const configDir = configArg !== undefined ? configArg : (seam ? '' : (process.env.CLAUDE_CONFIG_DIR || ''));
   // Assembled, not a literal: the installer rewrites quoted .claude literals in hook
   // copies, and these are Claude Code's own settings (only it writes the bridge).
   const dir = ['.', 'claude'].join('');
   const files = [];
   if (typeof projectDir === 'string' && projectDir) files.push(path.join(projectDir, dir, 'settings.local.json'), path.join(projectDir, dir, 'settings.json'));
-  if (homeDir) files.push(path.join(homeDir, dir, 'settings.json'));
+  if (configDir) files.push(path.join(configDir, 'settings.json'));
+  else if (homeDir) files.push(path.join(homeDir, dir, 'settings.json'));
   const out = [];
   for (const f of files) {
     try { out.push(JSON.parse(fs.readFileSync(f, 'utf8'))); } catch { /* absent or unreadable */ }

package/hooks/dist/pan-guard.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+'use strict';
+// PAN guard — a pre-tool hook (program A7).
+//
+// Registered on the hosts with a pre-tool event that can deny a call: Claude Code
+// and Codex (`PreToolUse`), Gemini CLI (`BeforeTool`) and Copilot CLI (`preToolUse`).
+// OpenCode registers no hooks. The command carries `--host <runtime>`, because the
+// payload and the way to deny differ per host.
+//
+// Rules, over the files a tool call is about to write:
+//   secret_write          the written text holds a credential (known token shapes,
+//                         or a long key=value secret)
+//   state_write           a direct write to PAN's own state: state.md, findings.jsonl,
+//                         the token ledger (pan-tools owns those)
+//   undeclared_test_edit  a test file the phase in flight does not declare in any
+//                         unfinished plan's files_modified
+//
+// Mode, from the planning tree's config.json `hooks.guard`:
+//   off      nothing
+//   report   (default) every match is appended to <planning>/guard.jsonl, the call proceeds
+//   enforce  as report, and a secret_write is denied; the other rules still only report
+//            until the writers of PAN's state go through pan-tools verbs (A7b)
+//
+// Inert outside a PAN project. Fail-open on anything it cannot parse; never fail-open
+// on a matched deny. Never writes outside the planning tree.
+
+const fs = require('fs');
+const path = require('path');
+
+const TOKEN_RE = /\b(?:sk-ant-[A-Za-z0-9_-]{10,}|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[abprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{30,}|-----BEGIN (?:RSA |EC |OPENSSH |)PRIVATE KEY-----)/;
+const SECRET_KV_RE = /\b(api[_-]?key|access[_-]?token|auth[_-]?token|refresh[_-]?token|client[_-]?secret|secret[_-]?key|password|passwd)\b["']?\s*[:=]\s*["']([^"'\s]{12,})["']/i;
+const TEST_PATH_RE = /(^|\/)(tests?|__tests__|specs?)\//i;
+const TEST_FILE_RE = /(\.(test|spec)\.[a-z0-9]+|(^|\/)test_[^/]+\.py|_test\.(py|go)|Tests?\.(java|kt|cs))$/i;
+const MODES = ['off', 'report', 'enforce'];
+
+// ─── R39: one run per hook when Claude and Copilot share a project ───────────
+// Copilot CLI also runs the hooks in a repository's .claude/settings.json and
+// .claude/settings.local.json. Measured 2026-09-26 (Copilot CLI 1.0.88, repository
+// hooks loaded): in a project with both the Claude and the Copilot install, every
+// PAN hook ran twice under Copilot — once from .github/hooks/pan.json, once from the
+// Claude settings. The Copilot project copy (this file under .github/hooks) steps
+// aside whenever the project's Claude settings register the same script, so the hook
+// runs once, and runs again from here the moment the Claude registration is gone.
+// Both files are repository hooks to Copilot and load under the same trust rule, so
+// deferring never leaves zero. Only this copy defers: Claude Code never reads
+// .github/hooks, Gemini and Codex never read .claude/settings.json, and a global
+// Copilot copy loads where repository hooks may not. Identical in every hook
+// Copilot registers — tests/copilot-hook-dedupe.test.cjs pins the copies.
+function deferToClaudeRegistration(projectDir, hookFile = __filename) {
+  // Assembled, not written as a literal: the installer rewrites every quoted .claude
+  // literal in a hook copy to that runtime's own directory, and this one must stay Claude's.
+  const claudeDir = ['.', 'claude'].join('');
+  try {
+    const hooksDir = path.dirname(hookFile);
+    if (path.basename(hooksDir) !== 'hooks' || path.basename(path.dirname(hooksDir)) !== '.github') return false;
+    if (typeof projectDir !== 'string' || !projectDir) return false;
+    const script = path.basename(hookFile);
+    for (const name of ['settings.json', 'settings.local.json']) {
+      let settings;
+      try { settings = JSON.parse(fs.readFileSync(path.join(projectDir, claudeDir, name), 'utf8')); } catch { continue; }
+      const events = settings && typeof settings.hooks === 'object' ? settings.hooks : null;
+      if (!events) continue;
+      for (const groups of Object.values(events)) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+          const handlers = group && Array.isArray(group.hooks) ? group.hooks : [];
+          if (handlers.some((h) => h && typeof h.command === 'string' && h.command.includes(script))) return true;
+        }
+      }
+    }
+  } catch { /* fail open: run this copy */ }
+  return false;
+}
+
+
+function planningDirName() {
+  const raw = process.env.PAN_PLANNING_DIR || '';
+  if (raw.trim()) {
+    const rel = raw.trim().replace(/\\/g, '/');
+    const bad = rel.startsWith('/') || /^[A-Za-z]:/.test(rel) || rel.split('/').includes('..');
+    if (!bad) return rel;
+  }
+  const track = (process.env.PAN_TRACK || '').trim();
+  if (track && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(track)) return `.planning/tracks/${track}`;
+  return '.planning';
+}
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+/** A value that is a placeholder, not a credential. */
+function isPlaceholder(v) {
+  return /^(?:\$\{|\$[A-Z_]|process\.env|os\.environ|<|xxx|your[_-]|changeme|example|dummy|placeholder|redacted|\*+$)/i.test(v);
+}
+
+function hasSecret(text) {
+  if (typeof text !== 'string' || !text) return false;
+  if (TOKEN_RE.test(text)) return true;
+  const m = text.match(SECRET_KV_RE);
+  return !!(m && !isPlaceholder(m[2]) && /\d/.test(m[2]) && /[A-Za-z]/.test(m[2]));
+}
+
+/**
+ * The tool call as `{tool, writes: [{path, text}], command}`, whatever the host.
+ * Claude/Codex/Gemini send `tool_name` + `tool_input`; Copilot sends `toolName` +
+ * `toolArgs` (a JSON string).
+ */
+function normalise(payload) {
+  const p = payload && typeof payload === 'object' ? payload : {};
+  const tool = String(p.tool_name || p.toolName || p.tool || '');
+  let input = p.tool_input || p.toolArgs || p.input || {};
+  if (typeof input === 'string') { try { input = JSON.parse(input); } catch { input = { command: input }; } }
+  if (!input || typeof input !== 'object') input = {};
+  const writes = [];
+  const file = input.file_path || input.filePath || input.path || input.notebook_path || input.absolute_path;
+  const texts = [input.content, input.new_string, input.newString, input.new_source, input.file_text, input.text]
+    .concat(Array.isArray(input.edits) ? input.edits.map((e) => e && (e.new_string || e.newString)) : [])
+    .filter((t) => typeof t === 'string');
+  if (typeof file === 'string' && file && (texts.length || /write|edit|create|replace|notebook/i.test(tool))) {
+    writes.push({ path: file, text: texts.join('\n') });
+  }
+  const command = typeof input.command === 'string' ? input.command : (Array.isArray(input.command) ? input.command.join(' ') : '');
+  // Codex edits files through apply_patch: the patch names its files and carries the text.
+  if (/\*\*\* (?:Add|Update) File: /.test(command)) {
+    let cur = null;
+    for (const line of command.split(/\r?\n/)) {
+      const m = line.match(/^\*\*\* (?:Add|Update) File: (.+)$/);
+      if (m) { cur = { path: m[1].trim(), text: '' }; writes.push(cur); continue; }
+      if (cur && line.startsWith('+')) cur.text += line.slice(1) + '\n';
+    }
+  }
+  return { tool, writes, command };
+}
+
+/** Project-relative POSIX path, or null when the path is outside the project. */
+function rel(projectDir, p) {
+  const abs = path.resolve(projectDir, p);
+  const r = path.relative(projectDir, abs).replace(/\\/g, '/');
+  return r.startsWith('..') || path.isAbsolute(r) ? null : r;
+}
+
+function isTestFile(r) {
+  return TEST_PATH_RE.test(r) || TEST_FILE_RE.test(r);
+}
+
+/** files_modified of the unfinished plans of the phase state.md names, or null when none is in flight. */
+function declaredFiles(projectDir, planningRel) {
+  let state;
+  try { state = fs.readFileSync(path.join(projectDir, planningRel, 'state.md'), 'utf8'); } catch { return null; }
+  const m = state.match(/\*\*Current Phase:\*\*[ \t]*([0-9]+(?:\.[0-9]+)?)/i) || state.match(/^Phase:[ \t]*([0-9]+(?:\.[0-9]+)?)/m);
+  if (!m) return null;
+  const want = String(parseFloat(m[1]));
+  const phasesDir = path.join(projectDir, planningRel, 'phases');
+  let dir;
+  try { dir = fs.readdirSync(phasesDir).find((d) => { const n = d.match(/^(\d+(?:\.\d+)?)-/); return n && String(parseFloat(n[1])) === want; }); } catch { return null; }
+  if (!dir) return null;
+  const full = path.join(phasesDir, dir);
+  const names = fs.readdirSync(full);
+  const done = new Set(names.filter((n) => n.endsWith('-summary.md')).map((n) => n.replace(/-summary\.md$/, '')));
+  const out = new Set();
+  let plans = 0;
+  for (const n of names.filter((x) => x.endsWith('-plan.md'))) {
+    if (done.has(n.replace(/-plan\.md$/, ''))) continue;
+    plans++;
+    const text = fs.readFileSync(path.join(full, n), 'utf8').replace(/\r\n/g, '\n');
+    const fm = text.match(/^---\n([\s\S]*?)\n---/);
+    if (!fm) continue;
+    const inline = fm[1].match(/^files_modified:[ \t]*\[([^\]]*)\]/m);
+    if (inline) inline[1].split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean).forEach((f) => out.add(f.replace(/^\.\//, '')));
+    const block = fm[1].match(/^files_modified:[ \t]*\n((?:[ \t]+-.*\n?)+)/m);
+    if (block) block[1].split('\n').map((l) => l.replace(/^[ \t]+-[ \t]*/, '').trim().replace(/^["']|["']$/g, '')).filter(Boolean).forEach((f) => out.add(f.replace(/^\.\//, '')));
+  }
+  return plans ? out : null;
+}
+
+/** The rule matches for one normalised call. */
+function evaluate(call, projectDir, planningRel) {
+  const hits = [];
+  const declared = call.writes.length ? declaredFiles(projectDir, planningRel) : null;
+  const ownState = new Set([`${planningRel}/state.md`, `${planningRel}/findings.jsonl`, `${planningRel}/metrics/tokens.jsonl`]);
+  for (const w of call.writes) {
+    const r = rel(projectDir, w.path);
+    if (hasSecret(w.text)) hits.push({ rule: 'secret_write', path: r || w.path });
+    if (!r) continue;
+    if (ownState.has(r)) hits.push({ rule: 'state_write', path: r });
+    if (declared && isTestFile(r) && !declared.has(r)) hits.push({ rule: 'undeclared_test_edit', path: r });
+  }
+  return hits;
+}
+
+function decide(hits, mode) {
+  if (mode !== 'enforce') return null;
+  return hits.find((h) => h.rule === 'secret_write') || null;
+}
+
+/** The host whose deny format this call needs: Copilot by payload shape, else the --host flag. */
+function hostOf(payload, flagHost) {
+  const p = payload && typeof payload === 'object' ? payload : {};
+  if (typeof p.toolName === 'string' && p.tool_name === undefined) return 'copilot';
+  return flagHost;
+}
+
+function main() {
+  const flagHost = (process.argv[process.argv.indexOf('--host') + 1] || 'claude').toLowerCase();
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch { return; }
+  let payload;
+  try { payload = JSON.parse(raw); } catch { return; } // fail open
+  const projectDir = (payload && (payload.cwd || payload.workspace || payload.project_dir)) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  if (deferToClaudeRegistration(projectDir)) return; // the Claude registration covers this call under Copilot
+  // The payload names the host better than the registration does: Copilot sends its own
+  // camelCase payload (toolName, toolArgs) even to a hook registered in .claude/settings.json,
+  // and denies only on the JSON decision, so a Copilot payload gets Copilot's deny whatever
+  // --host says. The flag decides for the snake_case hosts (Claude Code, Codex, Gemini).
+  const host = hostOf(payload, flagHost);
+  const planningRel = planningDirName();
+  const planning = path.join(projectDir, planningRel);
+  if (!fs.existsSync(planning)) return; // not a PAN project
+  const cfg = readJson(path.join(planning, 'config.json')) || {};
+  const mode = MODES.includes(cfg.hooks && cfg.hooks.guard) ? cfg.hooks.guard : 'report';
+  if (mode === 'off') return;
+  let hits = [];
+  try { hits = evaluate(normalise(payload), projectDir, planningRel); } catch { return; } // fail open
+  if (!hits.length) return;
+  const deny = decide(hits, mode);
+  try {
+    const ts = new Date().toISOString();
+    const lines = hits.map((h) => JSON.stringify({ ts, host, mode, rule: h.rule, path: h.path, tool: normalise(payload).tool, action: deny && h === deny ? 'denied' : 'reported' }));
+    fs.appendFileSync(path.join(planning, 'guard.jsonl'), lines.join('\n') + '\n');
+  } catch { /* the log is best effort; a deny below still stands */ }
+  if (!deny) return;
+  const reason = `PAN guard: this write puts a credential into ${deny.path}. Keep secrets out of the repository (an environment variable or a local, ignored file), then retry. (hooks.guard: enforce)`;
+  if (host === 'copilot') {
+    process.stdout.write(JSON.stringify({ permissionDecision: 'deny', permissionDecisionReason: reason }) + '\n');
+    return;
+  }
+  process.stderr.write(reason + '\n');
+  process.exitCode = 2;
+}
+
+if (require.main === module) main();
+
+module.exports = { normalise, evaluate, decide, hasSecret, declaredFiles, isTestFile, hostOf, deferToClaudeRegistration };