@mgiles/perk 3.1.0 → 3.3.0

package/extension/substrate/toolGating.ts

@@ -1,8 +1,9 @@
 // The tool-gating primitive (the keystone). Structural read-only enforcement, NOT
 // prompting. Mirrors pi's authoritative `examples/extensions/plan-mode/` recipe (the
 // `setActiveTools` allowlist + `tool_call` bash sub-allowlist + `before_agent_start` injection
-// (once-only: branch-scan dedup'd on the marker, so a session carries ONE live copy) +
-// `context` strip-when-off) and `preset.ts`'s snapshot-then-restore. The gate attaches to the
+// (once-only per SELECTED BRANCH: full-branch-scan dedup'd on the marker — historical, so a
+// copy compaction has summarized out of model context still suppresses; enforcement never rode
+// the prose) + `context` strip-when-off) and `preset.ts`'s snapshot-then-restore. The gate attaches to the
 // existing `perk:workflow-state.mode` field (`read-only`/`read-write`) — no new registry stage.
 // Beside the gate lives STAGE_TOOLS: per-stage active-tool scoping for the scoped universe
 // (perk's OWN registered tools + the enumerated borrowed-package census), keyed off the
@@ -11,7 +12,7 @@
 //
 // Substrate only: perk-owned plan mode and the read-only CI executor are the consumers of the
 // `enter`/`exit` surface; the allowlist-restore is wired into the existing
-// `session_start`/`session_tree` rebuild points.
+// `session_start`/`session_tree` rebuild points plus one `resources_discover` re-apply.
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { render } from "./prompts.ts";
@@ -83,12 +84,12 @@ export const LINEAR_MUTATING_TOOLS: readonly string[] = [
 ];
 
 /**
- * pi-subagents' delegation family. `subagent`/`wait` register at load time; the parent intercom
- * pair (`subagent_supervisor`, `intercom`) registers during `session_start` — AFTER perk's sync
- * (perk is the first `packages` entry), so it LEAKS past rebuild-point filtering at launch
- * (≈830 schema chars — accepted, documented, test-pinned). A later `session_tree` re-apply
- * filters over the original snapshot (which lacks the late names), so a tree navigation drops
- * them — the pre-existing snapshot behavior, unchanged. Child-side tools (`contact_supervisor`,
+ * pi-subagents' delegation family. `subagent`/`wait` register at load time; the parent supervisor
+ * tool `subagent_supervisor` registers during pi-subagents' own `session_start` — AFTER perk's
+ * sync (perk is the first `packages` entry) — and is admitted by the `resources_discover`
+ * re-apply as a late registrant (see `admitLate`): inside the diet at launch, kept where a stage
+ * list carries it. `intercom` is the separate pi-intercom bridge's tool name — a static census
+ * entry, inert unless that package is present. Child-side tools (`contact_supervisor`,
  * `structured_output`) are out of scope for the STAGE census — spawned children stay
  * stage-unscoped by design (§8.40 adopt-never-impersonates) — but they DO ride READ_ONLY_TOOLS,
  * because the read-only gate IS inherited by adopted children (see SUBAGENT_CHILD_TOOLS).
@@ -102,36 +103,31 @@ export const SUBAGENT_TOOLS: readonly string[] = [
 
 /**
  * pi-subagents' CHILD-side engine tools. `structured_output` and `contact_supervisor` register
- * only inside spawned child sessions (the env-keyed prompt-runtime registration — never in
- * parents, so those names are inert in every gated parent session; `setActiveTools` ignores
- * unknown names). `subagent_wait` is ALSO registered by the top-level parent extension
- * (pi-subagents 0.45.1's `registerWaitTool`) — the accepted widening: a wait-only,
- * non-repo-mutating tool active in gated parents. A gated ADOPTED child (mode inherited via the
- * `adopt` arm, contracts.md §8.3) must keep them active:
+ * inside spawned child sessions through the engine's prompt runtime / native supervisor bridge.
+ * Absent tools are inert in gated parents (`setActiveTools` ignores unknown names). A gated
+ * ADOPTED child (mode inherited via the `adopt` arm, contracts.md §8.3) must keep them active:
  *  - `structured_output` is the engine-REQUIRED completion call when the launch carries an
  *    `outputSchema` — stripping it makes the child physically unable to finish and fails the
  *    run with `structuredOutputFailed`;
- *  - `contact_supervisor` is the child→parent intercom door;
- *  - `subagent_wait` is the fanout-child wait door.
+ *  - `contact_supervisor` is the child→parent supervisor door.
+ * Native wakes need no wait-tool widening in this census.
  * None mutates the repo (`structured_output` writes only the engine's capture file under
  * `.pi-subagents/` scratch). Census decision, recorded: these names deliberately join NEITHER
  * PERK_TOOLS nor BORROWED_TOOLS — the stage-filter universe never sees them because children
  * are stage-unscoped by design (adopt never impersonates a stage), so gate membership is their
  * only governance surface.
  */
-export const SUBAGENT_CHILD_TOOLS: readonly string[] = [
-  "structured_output",
-  "contact_supervisor",
-  "subagent_wait",
-];
+export const SUBAGENT_CHILD_TOOLS: readonly string[] = ["structured_output", "contact_supervisor"];
 
 /**
  * @ff-labs/pi-fff's search tools. BOTH mode name-sets are enumerated (static names, inert
  * when absent — the code_search version-tolerance precedent): warm sessions run pi-fff's
- * default tools-and-ui mode (fffind/ffgrep [+ fff-multi-grep when enabled upstream]);
- * perk cold launches inject PI_FFF_MODE=override, where FFF registers under the builtin
- * names find/grep (already allowlisted/pass-through) plus multi_grep. All register at
- * load time. Frecency/history state lives under ~/.pi/agent/fff/ — outside the worktree
+ * default tools-and-ui mode (fffind/ffgrep [+ fff-multi-grep when enabled upstream]), and
+ * perk launches inject PI_FFF_MODE=tools-and-ui (the same additive mode) so pi's builtin
+ * find/grep stay host-builtins for pi-subagents' host-tool intersection (an override-mode
+ * pi-fff shadows them by name and fails review/scout lanes closed). The override name-set
+ * (multi_grep; find/grep already allowlisted/pass-through) stays enumerated for an operator
+ * `PI_FFF_MODE=override` opt-in. All register at load time. Frecency/history state lives under ~/.pi/agent/fff/ — outside the worktree
  * (the fetch_content cache-write precedent), so the read-only bar holds.
  */
 export const FFF_SEARCH_TOOLS: readonly string[] = [
@@ -149,12 +145,12 @@ export const FFF_SEARCH_TOOLS: readonly string[] = [
  * stage filter (fail-open — enumeration here is diet-completeness, not correctness).
  *
  * Audit records (the per-package census):
- *  - Registration timing: every census name registers at load time EXCEPT pi-subagents' parent
- *    supervisor pair (see SUBAGENT_TOOLS — session_start, leaks past rebuild-point filtering).
+ *  - Registration timing: every census name registers at load time EXCEPT pi-subagents'
+ *    `subagent_supervisor` (SUBAGENT_TOOLS — session_start; admitted at `resources_discover`).
  *  - Foreign `setActiveTools` owners: plannotator's phase machinery and @tombell/pi-plan's plan
- *    mode run their OWN toggles — perk re-applies only at rebuild points, so a foreign toggle
- *    between rebuilds wins (fail-open direction), and a mid-session rebuild re-installs perk's
- *    stage set over a foreign restriction. Pre-existing interplay, recorded, not re-engineered.
+ *    mode run their OWN toggles — perk re-applies only at its reconciliation points (the rebuilds
+ *    + the startup `resources_discover` re-apply), so a toggle between them wins (fail-open) and
+ *    every reconciliation re-installs perk's set over it, admitted late tools included (§8.40).
  *  - Zero-tool packages: @tombell/pi-diff (commands only), the footer providers, and the hunk
  *    review CLI (not a Pi package) register nothing — nothing to enumerate.
  *  - Single-governance rule: a name is governed ONCE — it lives in exactly one census. perk
@@ -223,9 +219,9 @@ export const READ_ONLY_TOOLS = [
   // FFF local search belongs in read-only exploration (the override names find/grep are
   // already present above; these are the additive tools-and-ui names + multi_grep).
   ...FFF_SEARCH_TOOLS,
-  // The delegation carve-in: `subagent`/`wait` (+ the parent supervisor pair, which already
-  // leaks active into cold-door gated sessions via late registration — keeping warm-entered
-  // gates consistent, and letting the parent answer child `contact_supervisor` asks) stay
+  // The delegation carve-in: `subagent`/`wait` (+ pi-subagents' late-registered
+  // `subagent_supervisor`, kept by every gate-ON re-apply because it is allowlisted here —
+  // letting the parent answer child `contact_supervisor` asks) stay
   // reachable while gated for the other delegation flows (the gated objective-plan guidance now
   // names the `explore_objective_node` tool below, not a direct spawn). ACCEPTED LENIENCY,
   // deliberately documented: spawned children are unscoped by design (§8.40
@@ -238,6 +234,11 @@ export const READ_ONLY_TOOLS = [
   // the already-carved-in SUBAGENT tools (the draft-review-wave precedent) and writes nothing to
   // the worktree.
   "explore_objective_node",
+  // The scout-wave carve-in: the authoring sessions' launcher — `run_scout_wave` spawns
+  // read-only `perk.scout` lanes over the already-carved-in delegation family and writes
+  // nothing to the worktree; reachable in every gated stage except `objective-refine` on the
+  // `explore_objective_node` precedent (contracts.md §8.70).
+  "run_scout_wave",
   // The child-side carve-in: gated adopt-children must keep the engine's injected tools — see
   // SUBAGENT_CHILD_TOOLS.
   ...SUBAGENT_CHILD_TOOLS,
@@ -273,6 +274,46 @@ export const READ_ONLY_TOOLS = [
   "run_dream_wave",
 ];
 
+/**
+ * The refinement stage id — the ONE stage whose gate-ON selection differs from READ_ONLY_TOOLS.
+ * (Registry vocabulary; the feature module re-declares the same literal as its stage constant.)
+ */
+export const REFINE_STAGE_ID = "objective-refine";
+
+/**
+ * The refinement session's gate-ON selection (contracts.md §8.68): read / research / question
+ * / local exploration, the backend-neutral review door, and the ONE refinement draft writer.
+ * Deliberately NOT READ_ONLY_TOOLS: no `objective_node` (a refinement never claims), no other
+ * draft tools (no plan/objective/gist artifact can be authored or routed from here), no save
+ * tools, no delegation spawn surface (children are unscoped by design) — and consequently no
+ * SUBAGENT_CHILD_TOOLS either: a child that inherited `stage: objective-refine` would lose
+ * `structured_output`/`contact_supervisor` under this allowlist. Unreachable today (no perk wave
+ * spawns from a refinement session; the lifecycle test pins `gatedToolsFor(stage)`) — revisit
+ * the moment refinement gains any delegation. Same static-name posture as READ_ONLY_TOOLS;
+ * `setActiveTools` ignores absent names.
+ */
+export const REFINEMENT_READ_ONLY_TOOLS: readonly string[] = [
+  "read",
+  "grep",
+  "find",
+  "ls",
+  "bash",
+  "ask_user_question",
+  "plan_review",
+  // The objective_refinement_draft carve-out: it writes only the one working-refinement
+  // artifact in the session data dir (fixed artifact name, seam-derived path, bound to the
+  // session's grounding context); the gate's edit/write/bash blocking is unchanged.
+  "objective_refinement_draft",
+  ...WEB_RESEARCH_TOOLS,
+  ...LINEAR_READ_TOOLS,
+  ...FFF_SEARCH_TOOLS,
+];
+
+/** The gate-ON allowlist for a stage: refinement's own selection, else READ_ONLY_TOOLS. */
+export function gatedToolsFor(stage: string | null): readonly string[] {
+  return stage === REFINE_STAGE_ID ? REFINEMENT_READ_ONLY_TOOLS : READ_ONLY_TOOLS;
+}
+
 /**
  * Every tool perk itself registers (contracts.md §8.40). Name-keyed: `setActiveTools` ignores
  * unknown names, so an absent tool is inert (e.g. a borrowed census name whose package stripped
@@ -291,6 +332,10 @@ export const PERK_TOOLS: readonly string[] = [
   "objective_draft",
   "gist_draft",
   "gist_save",
+  // The refinement session's ONE model-facing writer (contracts.md §8.67). Never in
+  // READ_ONLY_TOOLS: only the refinement gate-ON selection carries it, so no other gated
+  // stage can author a refinement draft.
+  "objective_refinement_draft",
   "learn",
   "run_learn_wave",
   "run_audit_wave",
@@ -302,8 +347,8 @@ export const PERK_TOOLS: readonly string[] = [
   "classify_review_feedback",
   "finalize_address",
   "explore_objective_node",
+  "run_scout_wave",
   "run_pr_review_wave",
-  "run_pr_review_dynamic_wave",
   "submit_pr_review",
   "start_review_wave",
   "collect_review_wave",
@@ -312,6 +357,10 @@ export const PERK_TOOLS: readonly string[] = [
   "collect_draft_review_wave",
   "run_ci",
   "submit",
+  "resolve_submit_conflicts",
+  // The stack-review launch-recovery tool (contracts.md §8.4): parameterless — the snapshot
+  // comes only from the `perk objective stack review` launch handoff.
+  "open_stack_review",
   // The stacked-delivery warm surface (contracts.md §8.51/§8.56): read + control tools over
   // the cold `objective stack` workers. Never in READ_ONLY_TOOLS — sync/adopt/recover/land
   // mutate published branches and PRs; the gated posture is the driving commands' soft
@@ -350,6 +399,7 @@ const RESEARCH_TOOLS: readonly string[] = [
 const WORKTREE_STAGE_TOOLS: readonly string[] = [
   "ask_user_question",
   "submit",
+  "resolve_submit_conflicts",
   "ready",
   "run_ci",
   "land",
@@ -359,7 +409,6 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
   "finalize_address",
   "post_pr_review",
   "run_pr_review_wave",
-  "run_pr_review_dynamic_wave",
   "submit_pr_review",
   // The human review doors' companion tools (/pr-review-terminal, /pr-review-browser): the
   // review-wave pair + the door-primed annotation push. The plan-stage widening landed via the
@@ -411,6 +460,15 @@ const WORKTREE_STAGE_TOOLS: readonly string[] = [
  *    review arm; the drive-coverage guard forces both the moment the guidance names them).
  */
 export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
+  // The isolated refinement stage (contracts.md §8.68): the gate-OFF (defensive) arm scopes the
+  // draft writer + the review door + research only — no PR-loop, save, claim or other draft
+  // tools. The session normally runs GATED, where REFINEMENT_READ_ONLY_TOOLS is the set.
+  [REFINE_STAGE_ID]: [
+    "ask_user_question",
+    "objective_refinement_draft",
+    "plan_review",
+    ...RESEARCH_TOOLS,
+  ],
   "gist-author": ["ask_user_question", "gist_draft", "gist_save", ...RESEARCH_TOOLS],
   "gist-save": ["ask_user_question", "gist_draft", "gist_save", ...RESEARCH_TOOLS],
   "objective-author": [
@@ -420,6 +478,10 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
     "reconcile_objective",
     "add_objective_node",
     "objective_node",
+    // The scout launcher rides the three AUTHORING stages (plan / objective-plan /
+    // objective-author) and no other — the one name by which this list and objective-save
+    // now differ (contracts.md §8.70).
+    "run_scout_wave",
     // The /objective-review-browser companions (gate-OFF coverage: after objectiveApprovalSave
     // exits the gate mid-flow, late collects/pushes must not dead-end) + plan_review (the door
     // guidance names it; it routes to the objective review arm here).
@@ -450,6 +512,8 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
     "plan_save",
     "objective_node",
     "explore_objective_node",
+    // The scout launcher (see the objective-author note).
+    "run_scout_wave",
     "reconcile_objective",
     "add_objective_node",
     // The /plan-review-browser companions (gate-OFF coverage: after approvalSave exits the gate
@@ -465,6 +529,8 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
     "plan_draft",
     "plan_review",
     "plan_save",
+    // The scout launcher (see the objective-author note).
+    "run_scout_wave",
     // The /plan-review-browser companions (see the objective-plan note).
     "start_draft_review_wave",
     "collect_draft_review_wave",
@@ -491,18 +557,62 @@ export const STAGE_TOOLS: Readonly<Record<string, readonly string[]>> = {
   // (read-only mode), where this list is inert; it exists for the keys≡registry pin and the
   // defensive gate-off arm.
   audit: ["ask_user_question", "run_audit_wave", ...RESEARCH_TOOLS],
+  // The stacked-PR browser-review launcher (`perk objective stack review`): exactly the flow
+  // set the stack.md guidance names — the launch-recovery tool, the review-wave pair, the
+  // annotation push, per-PR posting, delegation (the wave's relay loop), and research.
+  "stack-review": [
+    "ask_user_question",
+    "open_stack_review",
+    "start_review_wave",
+    "collect_review_wave",
+    "push_annotations",
+    "submit_pr_review",
+    ...SUBAGENT_TOOLS,
+    ...RESEARCH_TOOLS,
+  ],
 };
 
 /** The read-only marker / custom-message type injected into context while active. */
 const MODE_CONTEXT_TYPE = "perk:mode-context";
 const READ_ONLY_MARKER = "[READ-ONLY MODE]";
+/** The refinement flavor's DISTINCT dedup marker (not a superstring of the default marker, so
+ * neither flavor's presence masks the other's dedup scan). */
+const REFINEMENT_READ_ONLY_MARKER = "[READ-ONLY REFINEMENT MODE]";
+const MODE_MARKERS: readonly string[] = [READ_ONLY_MARKER, REFINEMENT_READ_ONLY_MARKER];
 
 /** Exported for tests: the injected read-only mode context. (No tool enumeration — gate-ON
  * already applies READ_ONLY_TOOLS via setActiveTools, so the active tool set IS the list.) */
 export const READ_ONLY_CONTEXT = render("contexts/read-only.md", {
   marker: READ_ONLY_MARKER,
+  writer: "plan_draft",
+  artifact: "working-plan artifact",
+});
+
+/** Exported for tests: the refinement flavor — names the ACTUAL sanctioned writer. */
+export const REFINEMENT_READ_ONLY_CONTEXT = render("contexts/read-only.md", {
+  marker: REFINEMENT_READ_ONLY_MARKER,
+  writer: "objective_refinement_draft",
+  artifact: "working-refinement artifact",
 });
 
+/** The mode-context flavor for a stage (the refinement session names its own writer). */
+function modeContextFor(stage: string | null): { marker: string; content: string } {
+  return stage === REFINE_STAGE_ID
+    ? { marker: REFINEMENT_READ_ONLY_MARKER, content: REFINEMENT_READ_ONLY_CONTEXT }
+    : { marker: READ_ONLY_MARKER, content: READ_ONLY_CONTEXT };
+}
+
+function textCarries(content: unknown, needles: readonly string[]): boolean {
+  if (typeof content === "string") return needles.some((n) => content.includes(n));
+  if (Array.isArray(content)) {
+    return content.some((c) => {
+      const part = c as { type?: string; text?: string };
+      return part.type === "text" && needles.some((n) => (part.text ?? "").includes(n));
+    });
+  }
+  return false;
+}
+
 // --- pure policy (copied from plan-mode/utils.ts so this primitive is self-contained; perk-owned
 // so retiring the borrowed pi-plan extension leaves no dangling import) -------
 
@@ -615,8 +725,19 @@ const SAFE_PATTERNS = [
   // perk's own read-only objective queries (show/next + their s/n aliases, plus the non-mutating
   // node-engagement read the objective-plan factory needs). The trailing \b keeps the `n` alias
   // from matching the mutating `node` subcommand; node-engagement allowed; create/node/reconcile
-  // stay blocked.
+  // stay blocked. node-engagement materializes a present refinement under the run scratch dir —
+  // the same accepted leniency as `perk pr review-context` below (the CLI writes its own
+  // gitignored scratch file; the destructive veto still blocks `> file` redirects).
   /^\s*perk\s+(objective|obj)\s+(show|s|next|n|node-engagement)\b/i,
+  // Report children need exactly these query forms, not arbitrary PR operations: plan-bound
+  // children (`/pr-review`, `/address`) use the `--expected-pr` form; the human-triage doors'
+  // adversarial children — and the stack-review routing step — use the foreign `--pr` /
+  // `--pr --stack` forms (a read-only parent would otherwise block the doors' children outright).
+  // ONE anchored alternation: `--json` last, nothing else; the flagless form stays out (only the
+  // write-capable foreground conflict-resolver uses it, outside the gate). The destructive veto
+  // still blocks `> file` redirects — the CLI writes its own scratch files.
+  /^\s*perk\s+pr\s+review-context\s+(?:--expected-pr\s+[1-9][0-9]*|--pr\s+[1-9][0-9]*(?:\s+--stack)?)\s+--json\s*$/,
+  /^\s*perk\s+pr\s+feedback\s+--json\s*$/,
   // Read-only `gh` queries — the guidance in the managed AGENTS block ("GitHub access goes
   // through gh") must be followable in read-only sessions. Query-shaped subcommands only;
   // `gh api` stays blocked (it can POST/PATCH), as do all mutating subcommands (create/edit/
@@ -636,7 +757,7 @@ const SAFE_PATTERNS = [
  * Known limitation: backslash-escaped quote characters are not handled. This is acceptable — the
  * whole-string destructive veto in isReadOnlyBashCommand remains the backstop.
  */
-function splitTopLevelSegments(command: string): string[] {
+export function splitTopLevelSegments(command: string): string[] {
   const segments: string[] = [];
   let current = "";
   let quote: '"' | "'" | null = null;
@@ -724,16 +845,37 @@ function isReadOnlyMode(mode: string | undefined): boolean {
   return mode === "read-only";
 }
 
-export function registerToolGating(pi: ExtensionAPI): ToolGating {
+/** The engagement record: the host's active starting set (the restore authority — never
+ * `getAllTools()`), the registry census at snapshot time, and the late registrants admitted so far. */
+type Engaged = { snapshot: readonly string[]; census: ReadonlySet<string>; admitted: Set<string> };
+
+export function registerToolGating(
+  pi: ExtensionAPI,
+  readOnlyFloor: () => boolean = () => false,
+): ToolGating {
   // In-memory gate (mirrors plan-mode's `planModeEnabled`): the authority `tool_call` consults.
   // Fail-closed — a failed sync never opens this; tool_call blocks on any internal error.
   let active = false;
   // The branch-LWW stage id this session is scoped to (null = unscoped). Fail-open by contrast
   // with `active`: no stage / unknown stage / any lookup miss → no filtering.
   let stageId: string | null = null;
-  // Pre-engagement tool snapshot, taken ONCE on the first engagement of either concern (the
-  // preset.ts discipline, shared by the gate and stage scoping).
-  let snapshot: string[] | null = null;
+  // Taken ONCE on the first engagement of either concern (the preset.ts discipline, shared by the
+  // gate and stage scoping); cleared when neither is engaged any more.
+  let engaged: Engaged | null = null;
+
+  function hasFloor(): boolean {
+    try {
+      return readOnlyFloor();
+    } catch {
+      // A broken restriction supplier cannot grant authority for this observation.
+      return true;
+    }
+  }
+
+  const isActive = () => active || hasFloor();
+  // The gate-ON allowlist follows the scoped stage: refinement's own selection, else the
+  // shared READ_ONLY_TOOLS (recomputed per observation — a late stage sync re-scopes it).
+  const gatedToolNames = (): ReadonlySet<string> => new Set(gatedToolsFor(stageId));
 
   /**
    * Recompute + install the active tool set from both concerns (contracts.md §8.40):
@@ -742,10 +884,10 @@ export function registerToolGating(pi: ExtensionAPI): ToolGating {
    *    `/objective-plan` carve-out and recreate the seed/gate contradiction class). "The gate
    *    never widens a stage's set and vice versa" still holds: engaging the gate only ever
    *    narrows, and stage scoping never adds a tool.
-   *  - gate OFF + stage scoped → a SUBTRACTIVE filter over the snapshot: names outside the
-   *    scoped universe (builtins, un-enumerated foreign tools) pass through untouched; scoped
-   *    names (PERK_TOOLS ∪ BORROWED_TOOLS) survive only when the stage's list carries them.
-   *  - neither engaged → restore the snapshot if one exists (a session that never engages gets
+   *  - gate OFF + stage scoped → a SUBTRACTIVE filter over the baseline (`admitLate`): names
+   *    outside the scoped universe (builtins, un-enumerated foreign tools) pass through untouched;
+   *    scoped names (PERK_TOOLS ∪ BORROWED_TOOLS) survive only when the stage's list carries them.
+   *  - neither engaged → restore the baseline and forget it (a session that never engages gets
    *    ZERO setActiveTools calls — bare warm sessions stay byte-identical).
    * While engaged the set is re-installed on every sync (tree navigation across mode entries
    * must recompute correctly).
@@ -754,40 +896,73 @@ export function registerToolGating(pi: ExtensionAPI): ToolGating {
   // un-enumerated foreign names pass through every stage filter untouched (fail-open).
   const SCOPED_TOOL_NAMES: ReadonlySet<string> = new Set([...PERK_TOOLS, ...BORROWED_TOOLS]);
 
+  /**
+   * The gate-OFF reconciliation baseline `snapshot ∪ admitted`. A tool the census never saw
+   * (pi-subagents' `subagent_supervisor` registers in its own `session_start`, after perk's sync)
+   * is admitted the first time it is seen active and stays admitted through perk's own filtering
+   * (so a navigation back to an admitting stage restores it); an owner that deactivates its late
+   * tool before perk ever sees it active is respected; a tool the census saw inactive is never
+   * re-activated. Gate-OFF paths only (the gate-ON set is by name — no bookkeeping there).
+   */
+  function admitLate(e: Engaged): string[] {
+    for (const name of pi.getActiveTools()) if (!e.census.has(name)) e.admitted.add(name);
+    return [...new Set([...e.snapshot, ...e.admitted])];
+  }
+
   function apply(nextActive: boolean, nextStage: string | null): void {
+    // Fail-closed: a read-only sync engages the in-memory gate BEFORE the fallible reads/installs.
+    if (nextActive) active = true;
+    const effective = nextActive || hasFloor();
     const stageList = nextStage === null ? undefined : STAGE_TOOLS[nextStage];
-    // First engagement of either concern: take the one snapshot.
-    if ((nextActive || stageList !== undefined) && snapshot === null) {
-      snapshot = pi.getActiveTools();
+    // First engagement of either concern: ONE literal (a throwing read records no half state).
+    if ((effective || stageList !== undefined) && engaged === null) {
+      engaged = {
+        snapshot: pi.getActiveTools(),
+        census: new Set(pi.getAllTools().map((t) => t.name)),
+        admitted: new Set(),
+      };
     }
-    if (nextActive) {
-      pi.setActiveTools([...READ_ONLY_TOOLS]);
-    } else if (stageList !== undefined) {
-      // The snapshot-missing fallback mirrors the restore path below: the FULL configured tool
-      // set (pi.getAllTools()), never a hardcoded list that would silently drop grep/find/ls
-      // and perk's custom tools (plan_save/submit/land/learn).
-      const base = snapshot ?? pi.getAllTools().map((t) => t.name);
-      pi.setActiveTools(
-        base.filter((name) => !SCOPED_TOOL_NAMES.has(name) || stageList.includes(name)),
-      );
-    } else if (snapshot !== null) {
-      pi.setActiveTools(snapshot);
-      snapshot = null;
+    if (effective) {
+      pi.setActiveTools([...gatedToolsFor(nextStage)]);
+    } else if (engaged !== null) {
+      const base = admitLate(engaged);
+      if (stageList !== undefined) {
+        pi.setActiveTools(
+          base.filter((name) => !SCOPED_TOOL_NAMES.has(name) || stageList.includes(name)),
+        );
+      } else {
+        pi.setActiveTools(base);
+        engaged = null;
+      }
     }
     active = nextActive;
     stageId = nextStage;
   }
 
-  // Structural backstop: block writes + non-allowlisted bash while active. Fail-closed on error.
+  // Pi fires `resources_discover` after EVERY extension's `session_start` has run (pi-subagents
+  // registers `subagent_supervisor` there, after perk's sync) — the one point where startup-late
+  // registrants meet the gate/stage diet: re-apply the in-memory mode/stage (no rebuild, no other
+  // checkpoint). Idempotent on `reason: "reload"`; a throw is Pi-reported and never opens the gate.
+  pi.on("resources_discover", async () => {
+    apply(active, stageId);
+  });
+
+  // Enforce the whole allowlist even if toolset narrowing failed or foreign tools registered late.
   pi.on("tool_call", async (event) => {
     try {
-      if (!active) return;
+      if (!isActive()) return;
       if (event.toolName === "edit" || event.toolName === "write") {
         return {
           block: true,
           reason: `perk read-only mode: ${event.toolName} is blocked (file modifications disabled).`,
         };
       }
+      if (!gatedToolNames().has(event.toolName)) {
+        return {
+          block: true,
+          reason: `perk read-only mode: ${event.toolName} is blocked (tool not allowlisted).`,
+        };
+      }
       if (event.toolName === "bash") {
         const command = String((event.input as { command?: unknown }).command ?? "");
         if (!isReadOnlyBashCommand(command)) {
@@ -806,33 +981,51 @@ export function registerToolGating(pi: ExtensionAPI): ToolGating {
 
   // Inject the hidden read-only mode context while active (display:false → not shown in transcript).
   pi.on("before_agent_start", async (_event, ctx) => {
-    if (!active) return;
-    // Once-only: injected customs persist to the branch, so a live copy suppresses re-injection;
-    // compaction dropping it makes the scan come up clean and the next turn re-injects.
-    if (branchCarries(branchOf(ctx), READ_ONLY_MARKER)) return;
+    if (!isActive()) return;
+    // Once-only per selected branch: injected customs persist to the branch, and the FULL-branch
+    // scan (not live model context) dedups — a copy compaction summarized away still counts as
+    // delivered on this branch history and is NOT re-injected; navigating to a branch that never
+    // carried it injects again. Deliberate: this is the structural gate's guidance, and the gate
+    // itself (tool_call) enforces regardless of what the model can still read.
+    // The flavor follows the scoped stage: the refinement session names its actual writer. The
+    // dedup key is the SELECTED flavor's marker, so a session gated under the default flavor
+    // that then enters refinement still receives the refinement flavor once.
+    const flavor = modeContextFor(stageId);
+    try {
+      if (branchCarries(branchOf(ctx), flavor.marker)) return;
+    } catch {
+      // An unreadable branch cannot suppress required read-only guidance.
+    }
     return {
-      message: { customType: MODE_CONTEXT_TYPE, content: READ_ONLY_CONTEXT, display: false },
+      message: { customType: MODE_CONTEXT_TYPE, content: flavor.content, display: false },
     };
   });
 
-  // Strip the stale read-only marker from context when the gate is off (so it never lingers).
+  // Gate OFF: strip every stale mode-context flavor (so none lingers). Gate ON: retain ONLY the
+  // current flavor's injected block — a stale `plan_draft`-only block from before a stage
+  // change is dropped from model context (the injected customType only; user content is never
+  // touched while the gate is on).
   pi.on("context", async (event) => {
-    if (active) return;
+    if (isActive()) {
+      const current = modeContextFor(stageId).marker;
+      const stale = (m: unknown): boolean => {
+        const msg = m as { customType?: string; content?: unknown };
+        return (
+          msg.customType === MODE_CONTEXT_TYPE &&
+          textCarries(msg.content, MODE_MARKERS) &&
+          !textCarries(msg.content, [current])
+        );
+      };
+      // No stale flavor → no intervention (the hook stays a no-op for every other message).
+      if (!event.messages.some(stale)) return;
+      return { messages: event.messages.filter((m) => !stale(m)) };
+    }
     return {
       messages: event.messages.filter((m) => {
         const msg = m as { customType?: string; role?: string; content?: unknown };
         if (msg.customType === MODE_CONTEXT_TYPE) return false;
         if (msg.role !== "user") return true;
-        const content = msg.content;
-        if (typeof content === "string") return !content.includes(READ_ONLY_MARKER);
-        if (Array.isArray(content)) {
-          return !content.some(
-            (c) =>
-              (c as { type?: string; text?: string }).type === "text" &&
-              ((c as { text?: string }).text ?? "").includes(READ_ONLY_MARKER),
-          );
-        }
-        return true;
+        return !textCarries(msg.content, MODE_MARKERS);
       }),
     };
   });
@@ -846,11 +1039,13 @@ export function registerToolGating(pi: ExtensionAPI): ToolGating {
       apply(true, stageId);
     },
     exit(_ctx?: ExtensionContext): void {
+      if (hasFloor()) {
+        apply(true, stageId);
+        return;
+      }
       pi.appendEntry(WORKFLOW_STATE_TYPE, { mode: "read-write" });
       apply(false, stageId);
     },
-    isActive(): boolean {
-      return active;
-    },
+    isActive,
   };
 }

package/extension/substrate/unifiedDiff.ts

@@ -1,5 +1,5 @@
 // A deliberately strict unified-diff applier for the plannotator "Direct Edits" feedback only
-// (`extension/adapters/planAdapterPlannotator.ts` extracts the ```diff fence; the plan arm of
+// (`extension/pi/v1/providers/plannotator.ts` extracts the ```diff fence; the plan arm of
 // `plan_review` applies it to the exact draft bytes it submitted) — this is NOT a general-purpose
 // patch tool.
 //