pan-wizard 3.31.0 → 3.33.0

package/commands/pan/map-codebase.md

@@ -17,7 +17,7 @@ Analyze existing codebase using parallel pan-document_code agents to produce str
 
 Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
 
-Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+Output: .planning/codebase/ folder with structured documents about the codebase state.
 </objective>
 
 <execution_context>
@@ -61,7 +61,7 @@ The CLI returns `{mode, total_tokens, file_count, languages}`:
 
 Record the chosen mode + telemetry in the final `.planning/codebase/overview.md` so future runs can reason about drift.
 
-**The mode is decided by repo size alone** — `estimate-size` compares the token estimate to `--threshold` and applies no model check. So single-shot only pays off when the model you launched with actually has a 1M-context window (the default Opus and current Sonnet-class models do; legacy 200K-context models do not). On a 200K-context model, pass a threshold that matches your real window (e.g. `--threshold 150000`) so anything larger resolves to `sharded` instead of overflowing a single agent.
+**The mode is decided by repo size alone** — `estimate-size` compares the token estimate to `--threshold` and applies no model check. So single-shot only pays off when the model you launched with actually has a 1M-context window. On a model with a smaller window, pass a threshold that matches your real window (e.g. `--threshold 150000`) so anything larger resolves to `sharded` instead of overflowing a single agent.
 </stage_0_ingest_mode>
 
 <tool_priority>
@@ -99,14 +99,14 @@ The orchestrator loads context in layers — NOT everything upfront. Mapper agen
    - Agent 5: relationships focus → writes relationships.md
    - Agent 6: practices focus → writes best-practices.md
 4. Wait for agents to complete, collect confirmations (NOT document contents)
-5. Verify all 9 documents exist with line counts
+5. Verify all documents exist with line counts
 6. Commit codebase map
 7. Offer next steps (typically: /pan:new-project or /pan:plan-phase)
 </process>
 
 <success_criteria>
 - [ ] .planning/codebase/ directory created
-- [ ] All 7 codebase documents written by mapper agents
+- [ ] All codebase documents written by mapper agents
 - [ ] Documents follow template structure
 - [ ] Parallel agents completed without errors
 - [ ] User knows next steps

package/commands/pan/mcp-bridge.md

@@ -98,7 +98,7 @@ Normally the host runtime writes this file. The CLI path exists for test fixture
 
 <workflow>
 
-**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, check the host runtime's MCP config — each runtime keeps it somewhere different: Claude Code in `settings.json` under its config dir, OpenCode in `opencode.json`, Copilot in `.github/mcp.json`, Codex in its own config, Gemini in its settings file.
+**New to a project with MCP tools?** Run `/pan:mcp-bridge list` to see what's available. If empty, check the host runtime's MCP config — each runtime keeps it somewhere different: Claude Code in `.mcp.json` at the project root (project scope) or `~/.claude.json` (user and local scopes), OpenCode in `opencode.json`, Copilot in `.github/mcp.json`, Codex in its own config, Gemini in its settings file.
 
 **Planning a phase that might touch external systems?** Run `/pan:mcp-bridge recommend <phase>` to get a ranked shortlist. Copy relevant tool names into the phase plan's "External tools" section so the executor knows to invoke them.
 

package/commands/pan/milestone-done.md

@@ -34,7 +34,7 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
 **User input:**
 
-- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+- Version: $ARGUMENTS (e.g., "1.0", "1.1", "2.0"); `{{version}}` below stands for this value
   </context>
 
 <process>
@@ -137,7 +137,6 @@ The full milestone-done workflow is inlined in <process> below — there is no s
 
 <critical_rules>
 
-- **Load workflow first:** Read milestone-done.md before executing
 - **Verify completion:** All phases must have summary.md files
 - **User confirmation:** Wait for approval at verification gates
 - **Archive before deleting:** Always create archive files before updating/deleting originals

package/commands/pan/optimize.md

@@ -19,6 +19,8 @@ Manage the circular optimization loop: apply recommendations, view stats, list r
 ```
 /pan:optimize apply
 /pan:optimize apply --report <filename>
+/pan:optimize revert <apply_id>
+/pan:optimize revert --last
 /pan:optimize list
 /pan:optimize stats
 /pan:optimize trace init [--description "what you're building"]
@@ -42,7 +44,17 @@ Requires human review (never auto-applied):
 - Workflow step additions
 - Structural changes to commands
 
-After applying, the report lists what was applied and what still needs review.
+After applying, the report lists what was applied and what still needs review, plus the `apply_id` that undoes it. Every apply is recorded action by action in `.planning/optimization/applied.jsonl`: the path, whether the file was created or appended to, the exact text, and a hash of the file after the write. Applying the same report a second time writes nothing: each action names the apply that already wrote it.
+
+### revert
+Undo one apply exactly: delete the memory files it created and cut the text it appended (`revert --last` for the newest).
+
+Revert never destroys work someone did since:
+- It refuses a file whose content changed after the apply. The comparison ignores line endings, so a CRLF checkout still matches.
+- It refuses a file that a later apply also wrote. Revert that later apply first.
+- It says which files it refused, and why.
+
+A CRLF file comes back CRLF. Applies logged before apply records existed cannot be reverted. After a revert, the same report can be applied again.
 
 ### list
 List all optimization reports in `.planning/optimization/reports/`, most recent first.
@@ -52,7 +64,7 @@ Show cumulative optimization statistics:
 - Total trace sessions run
 - Total events traced
 - Total errors/gaps/redundancies seen
-- Total optimizations applied across all runs
+- Total optimizations applied across all runs, the apply runs, the reverted runs, and the last `apply_id`
 - Current active trace session (if any)
 
 ### trace init

package/commands/pan/phase-tests.md

@@ -19,7 +19,7 @@ Generate unit and E2E tests for a completed phase, using its summary.md, context
 
 Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
 
-Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
+Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from phase-tests command`
 </objective>
 
 <execution_context>
@@ -34,6 +34,6 @@ Phase: $ARGUMENTS
 </context>
 
 <process>
-Execute the add-tests workflow from @~/.claude/pan-wizard-core/workflows/phase-tests.md end-to-end.
+Execute the phase-tests workflow from @~/.claude/pan-wizard-core/workflows/phase-tests.md end-to-end.
 Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
 </process>

package/commands/pan/profile.md

@@ -12,7 +12,7 @@ allowed-tools:
 <objective>
 Switch the model profile used by PAN agents. Controls which Claude model each agent uses, balancing quality vs token spend.
 
-Routes to the set-profile workflow which handles:
+Routes to the profile workflow which handles:
 - Argument validation (quality/balanced/budget)
 - Downgrade confirmation (quality → balanced → budget requires 'yes')
 - Config file creation if missing
@@ -25,7 +25,7 @@ Routes to the set-profile workflow which handles:
 </execution_context>
 
 <process>
-**Follow the set-profile workflow** from `@~/.claude/pan-wizard-core/workflows/profile.md`.
+**Follow the profile workflow** from `@~/.claude/pan-wizard-core/workflows/profile.md`.
 
 The workflow handles all logic including:
 1. Profile argument validation

package/commands/pan/research-phase.md

@@ -55,11 +55,9 @@ PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase
 
 ## 2. Check Existing Research
 
-```bash
-ls .planning/phases/${PHASE}-*/research.md 2>/dev/null
-```
+Use `has_research` and `research_path` from INIT.
 
-**If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
+**If exists:** Offer: 1) Update research, 2) View existing (`research_path`), 3) Skip. Wait for response.
 
 **If doesn't exist:** Continue.
 

package/commands/pan/review-deep.md

@@ -38,7 +38,7 @@ Consolidates Spec B v1's X-4 (self-review) + X-12 (harden) into a single command
 /pan:review-deep 07
 ```
 
-Run after `/pan:exec-phase 07` completes. Requires `pan-reviewer` to have already written its review to `.planning/phases/07/review.md` (exec-phase does this automatically).
+Run after `/pan:exec-phase 07` completes. It reads the review that exec-phase's code-review step saved in the phase directory (`.planning/phases/07-<slug>/07-review.md`). The reviewer is read-only, so it is exec-phase that writes the review there.
 
 ### Integrated with exec-phase
 
@@ -46,7 +46,7 @@ Run after `/pan:exec-phase 07` completes. Requires `pan-reviewer` to have alread
 /pan:exec-phase 07 --deep-review
 ```
 
-Runs the normal exec → reviewer pipeline, then auto-invokes this command. Recommended for phases touching auth, payment, PII, migrations, or public APIs.
+Runs the normal exec → reviewer pipeline, then runs this command's process inline, before the verifier. Recommended for phases touching auth, payment, PII, migrations, or public APIs.
 
 ### Integrated with focus-exec
 
@@ -60,7 +60,7 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
 
 <process>
 
-1. **Load reviewer output** — read `.planning/phases/<N>/review.md` written by the earlier `pan-reviewer` step. If missing, warn and offer to run `pan-reviewer` first.
+1. **Load reviewer output.** Resolve the phase with `pan-tools find-phase <N>`, then read `{directory}/{phase_number}-review.md`, which exec-phase's code-review step wrote. If it is missing, warn and offer to run `pan-reviewer` first. Its findings come from the report's closing `pan-verdict` block.
 
 2. **Spawn pan-hardener** (parallel-safe with step 3 isolation below, but recommended sequential for audit clarity):
    - Prompt includes: `<files_to_read>` with phase plan + diff + reviewer output; `<output_path>` = `.planning/reviews/<N>/hardener.md`; `<framework_scope>` block reminding of OWASP/STRIDE coverage.
@@ -73,7 +73,7 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
 4. **Merge** — call:
    ```
    pan-tools review-deep merge <N> \
-     --reviewer-file .planning/phases/<N>/review.md \
+     --reviewer-file {directory}/{phase_number}-review.md \
      --hardener-file .planning/reviews/<N>/hardener.md \
      --meta-file .planning/reviews/<N>/meta.md
    ```
@@ -99,7 +99,7 @@ Verdict is driven by the highest-severity finding across all three sources. Meta
 
 <output_files>
 
-- `.planning/phases/<N>/review.md` — pan-reviewer output (written earlier by exec-phase)
+- `{phase_dir}/{phase_number}-review.md` — pan-reviewer output (written by exec-phase's code-review step)
 - `.planning/reviews/<N>/hardener.md` — pan-hardener output (new)
 - `.planning/reviews/<N>/meta.md` — pan-meta-reviewer output (new)
 - `.planning/reviews/<N>/deep-review.md` — merged consolidated report (final deliverable)
@@ -111,18 +111,18 @@ Verdict is driven by the highest-severity finding across all three sources. Meta
 
 | Runtime | hardener | meta-reviewer | merge |
 |---------|----------|---------------|-------|
-| Claude Code | Full, thinking enabled (6000/4000 budget) | Full | Full |
+| Claude Code | Full; reasoning depth from the agent's `effort:` frontmatter | Full | Full |
 | OpenCode | Prose "think step-by-step" preamble substitutes for thinking | Same | Full (runtime-agnostic CLI) |
 | Gemini | Same | Same | Full |
 | Codex | Same | Same | Full |
 | Copilot | Same | Same | Full |
 
-The merger CLI (`pan-tools review-deep merge`) is pure Node.js and works identically across runtimes. Only the *quality* of the hardener and meta-reviewer outputs varies with model capability — an Opus-class model with extended thinking produces the richest findings.
+The merger CLI (`pan-tools review-deep merge`) is pure Node.js and works identically across runtimes. Only the *quality* of the hardener and meta-reviewer outputs varies with model capability.
 
 </runtime_compatibility>
 
 <calibration_note>
 
-Deep review is opt-in for a reason: it costs roughly 3× a normal review (hardener + meta + merge adds two agent spawns per phase). Use it for high-stakes phases, not every phase. `--deep-review` gating by phase tags is a v3.4 candidate enhancement.
+Deep review is opt-in for a reason: it costs roughly 3× a normal review (hardener + meta + merge adds two agent spawns per phase). Use it for high-stakes phases, not every phase.
 
 </calibration_note>

package/commands/pan/todo-add.md

@@ -13,7 +13,7 @@ allowed-tools:
 <objective>
 Capture an idea, task, or issue that surfaces during a PAN session as a structured todo for later work.
 
-Routes to the add-todo workflow which handles:
+Routes to the todo-add workflow which handles:
 - Directory structure creation
 - Content extraction from arguments or conversation
 - Area inference from file paths
@@ -34,7 +34,7 @@ State is resolved in-workflow via `init todos` and targeted reads.
 </context>
 
 <process>
-**Follow the add-todo workflow** from `@~/.claude/pan-wizard-core/workflows/todo-add.md`.
+**Follow the todo-add workflow** from `@~/.claude/pan-wizard-core/workflows/todo-add.md`.
 
 The workflow handles all logic including:
 1. Directory ensuring

package/commands/pan/todo-check.md

@@ -13,7 +13,7 @@ allowed-tools:
 <objective>
 List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
 
-Routes to the check-todos workflow which handles:
+Routes to the todo-check workflow which handles:
 - Todo counting and listing with area filtering
 - Interactive selection with full context loading
 - Roadmap correlation checking
@@ -32,7 +32,7 @@ Todo state and roadmap correlation are loaded in-workflow using `init todos` and
 </context>
 
 <process>
-**Follow the check-todos workflow** from `@~/.claude/pan-wizard-core/workflows/todo-check.md`.
+**Follow the todo-check workflow** from `@~/.claude/pan-wizard-core/workflows/todo-check.md`.
 
 The workflow handles all logic including:
 1. Todo existence checking

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

@@ -5,7 +5,7 @@
 // context limits (the statusline only shows the user).
 //
 // How it works:
-// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 1. The statusline hook writes metrics to <os tmpdir>/pan-hooks-<uid>/claude-ctx-{session_id}.json
 // 2. This hook reads those metrics after each tool use
 // 3. When remaining context drops below thresholds, it injects a warning
 //    as additionalContext, which the agent sees in its conversation

package/hooks/dist/pan-cost-logger.js

@@ -146,9 +146,11 @@ const CURSOR_FILE = '.cost-cursor.json';
 // the per-invocation `event_sig` discriminator; v4 added `agent_id` and the
 // `agent-transcript` token source. Kept as a literal in each hook —
 // they are standalone zero-dep scripts that can't import from pan-wizard-core, so
-// the two hooks must stay in sync by hand. No constant in pan-wizard-core mirrors
-// it: the readers there take a row field by field rather than switching on its
-// version, so an added field is additive for them.
+// each hook's copy is kept by hand (in lockstep through v4; the trace logger's events
+// have since moved to 5 on their own). cost-rebuild.cjs in
+// pan-wizard-core mirrors it for the rows it rebuilds; the readers there take a row
+// field by field rather than switching on its version, so an added field is additive
+// for them.
 const SCHEMA_V = 4;
 
 // Reverse-map a resolved model id to its cost tier so the "By tier" dashboard
@@ -456,10 +458,13 @@ const MAX_CURSOR_KEYS = 512;
 // marker phantom (an over-count) and from N29 (concurrent same-type siblings).
 //
 // Returns null when the payload cannot be serialized — callers then fail OPEN
-// (record, never mark).
+// (record, never mark). SHA-256 cut to the 40 hex characters the SHA-1 it replaced
+// produced, so persisted `event_sig` values keep their shape: a dedup key, not a
+// security boundary, but CodeQL rightly flags SHA-1 over a payload that carries a
+// session id (2026-09-29).
 function eventSignature(data) {
   try {
-    return crypto.createHash('sha1').update(JSON.stringify(data)).digest('hex');
+    return crypto.createHash('sha256').update(JSON.stringify(data)).digest('hex').slice(0, 40);
   } catch { return null; }
 }
 
@@ -559,6 +564,27 @@ function resolveAgentTranscript(data) {
   }
 }
 
+// Host-internal agents (measured 2026-09-28). Claude Code runs helper agents of its own:
+// the compaction summariser, and one at almost every turn end of an interactive session.
+// It fires SubagentStop for them with an `agent_id`, an EMPTY `agent_type`, and an
+// `agent_transcript_path` it never writes. That shape was captured from a real `/compact`
+// on Claude Code 2.1.280 (tests/fixtures/hooks/subagent-stop-internal-claude.json). Both
+// loggers booked each as an `unknown` zero-token spawn: 181 rows in three field projects
+// in eleven days, skewing optimize learn's agent stats and the ledger's spawn counts.
+// The host documents `agent_type` as present whenever a hook fires inside a subagent, so
+// a named instance with no type and no transcript is not a spawn anyone asked for, and
+// nothing is recorded. A NAMED spawn whose file is late or missing keeps its zero-token
+// row (N17/N25); a payload with no agent instance at all keeps the parent-slice path.
+// Identical in pan-cost-logger.js and pan-trace-logger.js (tests/trace-logger.test.cjs
+// pins the copies).
+function isHostInternalAgent(data, agentTranscript) {
+  if (!data || typeof data !== 'object' || agentTranscript) return false;
+  const typed = [data.agent_type, data.subagent_type].some((v) => typeof v === 'string' && v.trim() !== '');
+  if (typed) return false;
+  return (typeof data.agent_id === 'string' && AGENT_ID_SAFE.test(data.agent_id))
+    || (typeof data.agent_transcript_path === 'string' && data.agent_transcript_path !== '');
+}
+
 // A slice is a SUM over one subagent's conversation, so its ceiling sits above a
 // single call's (PLAUSIBLE_MAX): a long agent legitimately re-reads its cached
 // context on every turn. The cache_read and output ceilings are the absolute
@@ -576,6 +602,29 @@ function clampSlice(n, max) {
   return typeof n === 'number' && n >= 0 && n <= max ? n : 0;
 }
 
+// Copilot CLI's camelCase hook payload (docs.github.com/en/copilot/reference/hooks-reference,
+// read 2026-09-28; documented, not yet observed live) names every field differently from
+// Claude's snake_case one, so this hook read no session, transcript or agent from it and
+// booked every Copilot spawn as `unknown`. Its `agentType` is the KIND of agent (built-in
+// or custom); `agentName` is the configured name PAN's agents carry, so the name wins.
+// Claude payloads carry none of these keys and pass through unchanged. Identical in
+// pan-cost-logger.js and pan-trace-logger.js (tests/copilot-payload.test.cjs pins both).
+function normalizeHookPayload(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return data;
+  const pick = (...keys) => {
+    for (const k of keys) if (typeof data[k] === 'string' && data[k]) return data[k];
+    return undefined;
+  };
+  const out = { ...data };
+  if (out.session_id === undefined && pick('sessionId')) out.session_id = pick('sessionId');
+  if (out.transcript_path === undefined && pick('transcriptPath')) out.transcript_path = pick('transcriptPath');
+  if (out.agent_id === undefined && pick('agentId')) out.agent_id = pick('agentId');
+  const name = pick('agent_name', 'agentName');
+  if (name) out.agent_type = name;
+  else if (out.agent_type === undefined && pick('agentType')) out.agent_type = pick('agentType');
+  return out;
+}
+
 /**
  * Extract what we can from the SubagentStop event payload.
  * Pure function — safe to test without stdin.
@@ -586,6 +635,7 @@ function clampSlice(n, max) {
  */
 function buildCostRecord(data, cwd) {
   if (!data || typeof data !== 'object') return null;
+  data = normalizeHookPayload(data);
 
   // Only log actual subagent stops; ignore other Stop variants.
   if (data.hook_event_name && data.hook_event_name !== 'SubagentStop') return null;
@@ -613,6 +663,7 @@ function buildCostRecord(data, cwd) {
   // a value dropped to 0 by a plausibility guard so a guarded zero is
   // distinguishable from a genuine zero-token run.
   const agentTranscript = resolveAgentTranscript(data);
+  if (isHostInternalAgent(data, agentTranscript)) return null; // the host's own helper, not a spawn
   const parentPath = typeof data.transcript_path === 'string' && data.transcript_path ? data.transcript_path : null;
   // The host NAMED an agent (a bare id, or an explicit agent transcript path) but
   // its file is not there — not flushed yet, or a host that sends ids without
@@ -731,13 +782,14 @@ function buildCostRecord(data, cwd) {
   // Backfill command/phase from the active trace session when the payload omits
   // them (real SubagentStop payloads carry neither); tier is derived from the model.
   const sessionMeta = readActiveSessionMeta(cwd);
-  // The trace session only exists while the optimizer runs, so the parent transcript is
-  // the fallback that makes command attribution work outside focus mode — see
+  // The trace logger's day-scoped auto-session names no command (only a session opened
+  // by `optimize trace init` or focus mode does), so the parent transcript is the
+  // fallback that makes command attribution work in ordinary use — see
   // readCommandFromTranscript.
   const command = data.command || sessionMeta.command || readCommandFromTranscript(data.transcript_path) || null;
-  // The trace session is only present while the optimizer is running (off by
-  // default), so state.md is the fallback that makes phase attribution work in
-  // ordinary use instead of only under tracing.
+  // The day-scoped auto-session names no phase either, so state.md is the fallback
+  // that makes phase attribution work in ordinary use, not only in a session that
+  // was opened with one.
   const phase = data.phase || sessionMeta.phase || readCurrentPhase(cwd) || null;
 
   const record = {
@@ -1003,4 +1055,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { deferToClaudeRegistration, buildCostRecord, appendRecord, readUsageFromTranscript, addCacheTtlSplit, resolveAgentTranscript, readCursor, writeCursor, isPanProject, hasPlanningTree, readCommandFromTranscript, isSessionStale, PAN_RUNTIME_DIRS, METRICS_DIR, TOKENS_FILE, CURSOR_FILE, SLICE_MAX, MAX_CURSOR_KEYS };
+module.exports = { deferToClaudeRegistration, normalizeHookPayload, isHostInternalAgent, buildCostRecord, appendRecord, readUsageFromTranscript, addCacheTtlSplit, resolveAgentTranscript, readCursor, writeCursor, isPanProject, hasPlanningTree, readCommandFromTranscript, isSessionStale, PAN_RUNTIME_DIRS, METRICS_DIR, TOKENS_FILE, CURSOR_FILE, SLICE_MAX, MAX_CURSOR_KEYS };

package/hooks/dist/pan-state-reinject.js

@@ -18,11 +18,30 @@
 // `compact` matcher on both; the source is re-checked here so a registration
 // without the matcher stays inert on every other start.
 //
+// Gemini CLI and Copilot CLI (market-ideas M33) restart no session after a
+// compaction (Gemini's SessionStart sources: startup | resume | clear; Copilot's:
+// startup | resume | new), and their pre-compaction events cannot add context
+// (Gemini PreCompress and Copilot preCompact are advisory). So there the block
+// arrives in two steps:
+//   --mark            on PreCompress / preCompact: when a PAN phase is in flight,
+//                     leave a per-session marker in the per-user hook directory
+//                     under the OS temp directory (0700, written 0600);
+//   --inject <host>   on the next tool result (Gemini AfterTool, Copilot
+//                     postToolUse): consume the marker and return the block once,
+//                     in that host's output shape. With no marker it prints nothing.
+// A tool result is the first point after a compaction where both hosts take added
+// context, including an autonomous `-p` run that never sees another prompt (read
+// 2026-10-03: gemini-cli v0.61.0 docs/hooks/reference.md; the Copilot hooks
+// reference on docs.github.com). The marker modes need no R39 deferral: in a
+// project with both installs, Copilot also runs Claude's registration of this
+// script, but that one is the SessionStart mode, which a Copilot start never matches.
+//
 // Inert unless the project is a PAN project with work in flight: `.planning/`
 // holds a state.md that names a current phase AND a roadmap.md with an unticked
 // phase. Everywhere else — no planning tree, a focus-only project, a finished
-// milestone — it prints nothing. It never writes a file (field finding: hooks
-// that scaffolded `.planning/` in projects that never ran PAN).
+// milestone — it prints nothing. It never writes into the project (field finding:
+// hooks that scaffolded `.planning/` in projects that never ran PAN); the only
+// file it writes is the marker, outside the project.
 //
 // Fail-open everywhere: bad stdin, unreadable files — exit 0 silently. A missing
 // reminder costs a re-read; a crashed hook is a failing hook at every start.
@@ -31,14 +50,16 @@
 // additionalContext; each field is truncated on its own.
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 
 /**
  * Which planning tree this hook acts on.
  *
  * Mirrors pan-wizard-core/bin/lib/planning-root.cjs, which hooks cannot require
- * (they are standalone and run inside the host runtime). All PAN hooks carry an
- * identical copy — if the CLI is pointed at a track while a hook still writes to
+ * (they are standalone and run inside the host runtime). Every PAN hook that
+ * reads the planning tree carries an identical copy — if the CLI is pointed at a track while a hook still writes to
  * `.planning/`, that tree's telemetry lands in the wrong place.
  *
  * Env only — a hook gets no argv. A value that escapes the project root is
@@ -124,7 +145,99 @@ function readIfExists(p) {
   try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
 }
 
+// ─── The marker (Gemini, Copilot) ─────────────────────────────────────────────
+
+// A marker older than this belongs to a session that never made another tool call.
+const MARKER_TTL_MS = 6 * 60 * 60 * 1000;
+
+/** Gemini sends `session_id`; Copilot's camelCase payloads send `sessionId`. */
+function sessionIdOf(payload) {
+  for (const k of ['session_id', 'sessionId']) {
+    if (typeof payload[k] === 'string' && payload[k]) return payload[k];
+  }
+  return '';
+}
+
+/** The per-user hook directory's name: the stop guard's and the context monitor's too. */
+function hookDirName() {
+  const uid = (typeof process.getuid === 'function' ? process.getuid() : process.env.USERNAME || 'win');
+  return `pan-hooks-${uid}`;
+}
+
+// Per-user hook state directory inside tmpdir, created 0700 — the same directory
+// and the same checks as hookStateDir() in pan-stop-guard.js (hooks are standalone
+// files and cannot require one another). Null when the directory is not provably
+// ours: on a shared host another user must not be able to plant a marker that
+// injects, or a symlink the marker is written through (M60).
+function hookStateDir() {
+  const dir = path.join(os.tmpdir(), hookDirName());
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = fs.lstatSync(dir);
+    if (st.isSymbolicLink()) return null;
+    // POSIX-only ownership and mode checks: Windows fakes mode bits (N15).
+    if (typeof process.getuid === 'function') {
+      if (st.uid !== process.getuid()) return null;
+      if ((st.mode & 0o077) !== 0) return null;
+    }
+    return dir;
+  } catch { return null; }
+}
+
+/** One marker per (session, project), named by a hash so neither leaks into a file name. Pure. */
+function markerName(sessionId, projectDir) {
+  const key = crypto.createHash('sha256').update(`${sessionId}\u0000${path.resolve(projectDir)}`).digest('hex').slice(0, 32);
+  return `state-reinject-${key}.json`;
+}
+
+// This hook's files in the shared directory: markers, and one a crash left mid-take.
+const MARKER_FILE_RE = /^state-reinject-[0-9a-f]{32}\.json(?:\.\d+\.taken)?$/;
+
+function writeMarker(file, now = Date.now()) {
+  fs.writeFileSync(file, JSON.stringify({ at: now }), { mode: 0o600 });
+  // Sweep markers no session came back for — only this hook's: the directory
+  // holds the other hooks' state too. Best effort.
+  try {
+    for (const name of fs.readdirSync(path.dirname(file))) {
+      if (!MARKER_FILE_RE.test(name)) continue;
+      const p = path.join(path.dirname(file), name);
+      try { if (now - fs.statSync(p).mtimeMs > MARKER_TTL_MS) fs.unlinkSync(p); } catch { /* raced */ }
+    }
+  } catch { /* unreadable dir */ }
+}
+
+/**
+ * Take the marker if there is a fresh one: rename it first, so two hooks racing on
+ * the same tool result cannot both inject. True when this call took it.
+ */
+function takeMarker(file, now = Date.now()) {
+  const taken = `${file}.${process.pid}.taken`;
+  try { fs.renameSync(file, taken); } catch { return false; }
+  let fresh = false;
+  try { fresh = now - JSON.parse(fs.readFileSync(taken, 'utf8')).at <= MARKER_TTL_MS; } catch { /* unreadable: stale */ }
+  try { fs.unlinkSync(taken); } catch { /* gone */ }
+  return fresh;
+}
+
+/** The block in the shape each host's tool-result event takes. */
+function injectOutput(host, context) {
+  if (host === 'gemini') return { hookSpecificOutput: { hookEventName: 'AfterTool', additionalContext: context } };
+  if (host === 'copilot') return { additionalContext: context };
+  return null;
+}
+
+function contextFor(projectDir) {
+  return buildReinjectContext({
+    stateContent: readIfExists(planningPath(projectDir, 'state.md')),
+    roadmapContent: readIfExists(planningPath(projectDir, 'roadmap.md')),
+    planningRel: planningDirName(),
+  });
+}
+
 function main() {
+  const argv = process.argv.slice(2);
+  const mode = argv.includes('--mark') ? 'mark' : argv.includes('--inject') ? 'inject' : 'session-start';
+  const host = mode === 'inject' ? argv[argv.indexOf('--inject') + 1] : null;
   let input = '';
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', chunk => { input += chunk; });
@@ -133,20 +246,32 @@ function main() {
       let payload = {};
       try { payload = JSON.parse(input); } catch { /* fail open on bad stdin */ }
       if (!payload || typeof payload !== 'object') payload = {};
-      if (payload.source !== 'compact') { process.exit(0); return; }
-
       const projectDir = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
-      const context = buildReinjectContext({
-        stateContent: readIfExists(planningPath(projectDir, 'state.md')),
-        roadmapContent: readIfExists(planningPath(projectDir, 'roadmap.md')),
-        planningRel: planningDirName(),
-      });
-      if (context) {
-        process.stdout.write(JSON.stringify({
-          hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context },
-        }));
+
+      if (mode === 'session-start') {
+        if (payload.source !== 'compact') { process.exit(0); return; }
+        const context = contextFor(projectDir);
+        if (context) {
+          process.stdout.write(JSON.stringify({
+            hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context },
+          }));
+        }
+      } else {
+        const sid = sessionIdOf(payload);
+        // An unknown host leaves the marker for a host that can use it.
+        if (!sid || (mode === 'inject' && !injectOutput(host, ''))) { process.exit(0); return; }
+        const dir = hookStateDir();
+        if (!dir) { process.exit(0); return; }
+        const file = path.join(dir, markerName(sid, projectDir));
+        if (mode === 'mark') {
+          if (contextFor(projectDir)) writeMarker(file);
+        } else if (takeMarker(file)) {
+          // Re-read now: the position after the compaction, not before it.
+          const context = contextFor(projectDir);
+          if (context) process.stdout.write(JSON.stringify(injectOutput(host, context)));
+        }
       }
-    } catch { /* fail open — never break a session start */ }
+    } catch { /* fail open — never break a session or a tool call */ }
     process.exit(0);
   });
 }
@@ -155,4 +280,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { buildReinjectContext, UNTICKED_PHASE_RE };
+module.exports = { buildReinjectContext, UNTICKED_PHASE_RE, markerName, hookDirName, sessionIdOf, injectOutput, MARKER_TTL_MS };

package/hooks/dist/pan-stop-guard.js

@@ -116,8 +116,8 @@ const crypto = require('crypto');
  * Which planning tree this hook acts on.
  *
  * Mirrors pan-wizard-core/bin/lib/planning-root.cjs, which hooks cannot require
- * (they are standalone and run inside the host runtime). All PAN hooks carry an
- * identical copy — if the CLI is pointed at a track while a hook still writes to
+ * (they are standalone and run inside the host runtime). Every PAN hook that
+ * reads the planning tree carries an identical copy — if the CLI is pointed at a track while a hook still writes to
  * `.planning/`, that tree's telemetry lands in the wrong place.
  *
  * Env only — a hook gets no argv. A value that escapes the project root is