@mgiles/perk 1.0.1

package/extension/factories/objectiveSave.ts

@@ -0,0 +1,285 @@
+// The warm `objective_save` door, the objective mirror of planSave.ts. The in-session twin
+// of the Python cold door (`perk objective create`): a deterministic, terminating tool + command
+// that WRAP the existing storage — they do NOT reimplement the GitHub write. `saveObjective()`
+// passes the STRUCTURED roadmap as `--roadmap <json>` (the agent never hand-writes roadmap YAML)
+// and delegates to `perk objective create --json` via the shared cold-door client (`runColdDoor`,
+// the prose rides the run-scratch stdin channel), then links the live session: `active_objective` + a fresh `perk:objective-budget` activation marker
+// (mirrors the `/objective <id>` activation in objective.ts). Failures are loud-but-non-fatal.
+//
+// APPROVAL→SAVE ORCHESTRATION (mirroring planSave.ts's `approvalSave`). The
+// exported `objectiveApprovalSave` seam is the shared APPROVED-review → save flow: re-read the
+// STRUCTURED artifact (`readObjectiveDraft` — never the rendered markdown, never the transcript)
+// → `saveObjective` → D1a gate exit on a successful save (snapshot `gating.isActive()` BEFORE the
+// save; a failed save leaves the gate ON). `plan_review`'s objective arm (planReview.ts) wires
+// its APPROVED outcome into it; the `/objective-save` command is the artifact-first MANUAL
+// FAILSAFE invocation of the same seam, keeping the legacy drive-the-session behavior as the
+// no-draft fallback (objectives have no transcript scrape by design).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import {
+  booleanField,
+  type ColdJson,
+  objectField,
+  runColdDoor,
+  stringField,
+} from "../substrate/coldDoor.ts";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import type { ToolGating } from "../substrate/toolGating.ts";
+import { appendWorkflowState, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { report, type Severity } from "../surfaces/report.ts";
+import { OBJECTIVE_BUDGET_TYPE } from "./objective.ts";
+import {
+  decodeObjectiveSaveParams,
+  ROADMAP_PARAM_SCHEMA,
+  readObjectiveDraft,
+} from "./objectiveDraft.ts";
+
+/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
+export interface ObjectiveSaveOk {
+  /** `id` is the opaque string objective id (GitHub "7", Linear "ENG-7") — §8.21. */
+  objective: { id: string; url: string };
+  existed: boolean | null;
+}
+
+export type ObjectiveSaveResult = Result<ObjectiveSaveOk>;
+
+/** The decoded `perk objective create --json` payload slice the warm door consumes. */
+interface ObjectiveCreatePayload {
+  objective: { id: string; url: string; existed: boolean | undefined };
+}
+
+/** Narrow the `perk objective create --json` success payload; strict on `objective`. */
+function decodeObjectiveCreate(payload: ColdJson): ObjectiveCreatePayload | null {
+  const objective = objectField(payload, "objective");
+  if (objective === undefined) return null;
+  const id = stringField(objective, "id");
+  const url = stringField(objective, "url");
+  if (id === undefined || url === undefined) return null;
+  return { objective: { id, url, existed: booleanField(objective, "existed") } };
+}
+
+/**
+ * The single save implementation both surfaces call. Delegates the GitHub write to the Python cold
+ * door, then links the live session (`active_objective` + budget marker). Returns a soft result
+ * (never throws); failures set `details.ok = false` and append no linkage.
+ */
+export async function saveObjective(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  opts: { prose: string; title?: string; roadmap?: unknown[]; base?: string },
+): Promise<ObjectiveSaveResult> {
+  const fail = failFor(ctx, "objective-save");
+
+  const prose = opts.prose.trim();
+  if (!prose)
+    return fail("no objective prose to save (draft the objective first)", "invalid_input");
+  if (opts.roadmap !== undefined && !Array.isArray(opts.roadmap)) {
+    return fail("roadmap must be a JSON array of nodes", "invalid_input");
+  }
+
+  const branch = () => branchOf(ctx);
+  const runId = rebuildWorkflowState(branch()).run_id ?? "";
+
+  const args = ["objective", "create", "--json"];
+  if (opts.title) args.push("--title", opts.title);
+  if (opts.base) args.push("--base", opts.base);
+  if (runId) args.push("--run-id", runId);
+  if (opts.roadmap && opts.roadmap.length > 0) {
+    args.push("--roadmap", JSON.stringify(opts.roadmap));
+  }
+  const r = await runColdDoor<ObjectiveCreatePayload>(pi, ctx, args, {
+    label: "perk objective create",
+    decode: decodeObjectiveCreate,
+    stdin: { flag: "--body", content: prose, filename: "objective.md" },
+  });
+  if (!r.ok) return fail(r.message, r.errorType);
+
+  // Link the live session: set active_objective (LWW) + seed a fresh budget activation marker
+  // (mirrors objective.ts's `/objective <id>` activation), so budget tracking starts immediately.
+  // The envelope id is already the opaque string id (§8.21) — no coercion needed.
+  const objective = r.data.objective;
+  const objectiveId = objective.id;
+  const linked = rebuildWorkflowState(branch()).active_objective ?? null;
+  if (linked !== objectiveId) {
+    appendWorkflowState(pi, ctx, {
+      data: { active_objective: objectiveId },
+      field: "active_objective",
+      expected: objectiveId,
+      scope: "objective-save",
+      failure: `active_objective read-back failed for #${objectiveId}`,
+    });
+    pi.appendEntry(OBJECTIVE_BUDGET_TYPE, {
+      objective_id: objectiveId,
+      activated_at: new Date().toISOString(),
+    });
+  }
+
+  const verb = objective.existed ? "Found existing" : "Saved";
+  return ok(
+    `${verb} objective #${objective.id} → ${objective.url}`,
+    {
+      objective: { id: objective.id, url: objective.url },
+      existed: objective.existed ?? null,
+    },
+    { terminate: true },
+  );
+}
+
+/** The approval→save orchestration outcome (the objective `ApprovalSaveOutcome`). */
+export type ObjectiveApprovalSaveOutcome =
+  | { status: "no-draft" }
+  | { status: "saved" | "save-failed"; result: ObjectiveSaveResult; gateExited: boolean };
+
+/**
+ * The shared approval→save orchestration seam (the objective sibling of
+ * planSave.ts's `approvalSave`): an APPROVED objective review (`plan_review`'s objective arm)
+ * and the manual `/objective-save` failsafe both run THIS. Flow: re-read the STRUCTURED draft
+ * artifact at save time (`readObjectiveDraft` — never the rendered markdown, never in-hand
+ * bytes) → `saveObjective` → gate exit on a successful save while read-only (the D1a pattern:
+ * snapshot `gating.isActive()` before the save; a failed save leaves the gate ON). No draft →
+ * `no-draft` (nothing saved, the gate untouched); callers render their own fallback. Title
+ * precedence: an explicit `opts.title` wins; else the draft's `title`; else the cold door
+ * derives from the prose heading. The returned result keeps `saveObjective`'s `terminate: true`
+ * for tool-path callers.
+ */
+export async function objectiveApprovalSave(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  opts: { title?: string } = {},
+): Promise<ObjectiveApprovalSaveOutcome> {
+  const draft = readObjectiveDraft(ctx);
+  if (draft === null) return { status: "no-draft" };
+  // D1a: snapshot the gate BEFORE the save; on success, exit it so save marks the read-only →
+  // read-write boundary in one gesture. A failed save leaves the gate on.
+  const wasReadOnly = gating.isActive();
+  const result = await saveObjective(pi, ctx, {
+    prose: draft.prose,
+    title: opts.title ?? draft.title,
+    roadmap: draft.roadmap,
+    base: draft.base,
+  });
+  let gateExited = false;
+  if (result.details.ok && wasReadOnly) {
+    gating.exit(ctx);
+    gateExited = true;
+  }
+  return { status: result.details.ok ? "saved" : "save-failed", result, gateExited };
+}
+
+const TOOL_GUIDELINES = [
+  "Use objective_save only after the objective + roadmap are decision-complete; it creates the canonical perk:objective issue, activates it, and ends the turn.",
+  "Pass the objective PROSE in `prose` and the STRUCTURED roadmap in `roadmap` (a JSON array of nodes) — never hand-write roadmap YAML.",
+  'Each roadmap node needs a stable `id` (e.g. "1.1") and a `description`; `status` defaults to pending. Use `depends_on` for explicit ordering.',
+];
+
+/**
+ * The seed guidance the warm `/objective-save` injects to drive the structured save (the
+ * perk-objective-author skill pointer rides the skill-binding suffix — not hardcoded
+ * here). Pure + exported for offline tests.
+ */
+export function objectiveSaveGuidance(title?: string): string {
+  const named = title?.trim();
+  return [
+    "perk /objective-save — persist the objective the session converged on.",
+    "1. If the objective + roadmap are NOT yet decision-complete, finish converging first, then " +
+      "call the tool.",
+    "2. Call the `objective_save` tool NOW, passing `prose` (the decision-complete objective " +
+      "prose) and `roadmap` (the STRUCTURED roadmap as a JSON array of nodes, each with a stable " +
+      "`id` and `description`) — NEVER hand-write the roadmap as YAML.",
+    named
+      ? `3. Pass \`title: "${named}"\` as the objective title.`
+      : "3. `title` is optional (defaults to the prose's first heading).",
+    "4. The tool creates the perk:objective issue, activates it, starts budget tracking, and " +
+      "terminates the turn. Judgment + durable writes stay with you.",
+  ].join("\n");
+}
+
+/** Register the warm door: the `objective_save` tool (canonical) + the `/objective-save` twin. */
+export function registerObjectiveSave(pi: ExtensionAPI, gating: ToolGating): void {
+  pi.registerTool({
+    name: "objective_save",
+    label: "Save objective",
+    description:
+      "Persist a drafted objective + structured roadmap to GitHub as a perk:objective issue, " +
+      "activate it, and start budget tracking. Terminating: ends the turn on save. Call only when " +
+      "the objective and roadmap are decision-complete.",
+    promptSnippet: "Save the decision-complete objective + roadmap to GitHub (terminates the turn)",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["prose"],
+      properties: {
+        prose: {
+          type: "string",
+          description: "The objective prose (the why, the design, the boundaries/non-goals).",
+        },
+        title: {
+          type: "string",
+          description: "Optional objective title (defaults to the prose's first heading).",
+        },
+        base: {
+          type: "string",
+          description:
+            "Optional target branch for this objective's plans (omit to use the repo default).",
+        },
+        roadmap: {
+          type: "array",
+          description:
+            "The structured roadmap: a JSON array of nodes. Never hand-write roadmap YAML.",
+          items: ROADMAP_PARAM_SCHEMA,
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodeObjectiveSaveParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "objective-save",
+          "objective_save",
+        )(
+          "objective_save needs { prose: string, roadmap?: array } per the tool schema",
+          "bad_input",
+        );
+      }
+      return saveObjective(pi, ctx, decoded);
+    },
+  });
+
+  pi.registerCommand("objective-save", {
+    description:
+      "Save the working objective draft to GitHub — the manual failsafe for the approval→save " +
+      "flow (artifact-first; drives the structured save only when no draft exists).",
+    handler: async (args, ctx) => {
+      const title = args.trim() || undefined;
+      // The artifact-first manual-failsafe invocation of the shared approval→save
+      // seam (the D1a gate exit lives in the seam). The legacy drive-the-session behavior is kept
+      // as the NO-DRAFT fallback — objectives have no transcript scrape by design, so a draftless
+      // session still needs a working save path.
+      const outcome = await objectiveApprovalSave(pi, ctx, gating, { title });
+      if (outcome.status === "no-draft") {
+        // Exit the read-only gate so the objective_save tool (excluded from READ_ONLY_TOOLS)
+        // becomes reachable on the driven turn, then drive the turn (mirrors /address and
+        // /objective-plan).
+        if (gating.isActive()) gating.exit(ctx);
+        report(ctx, "objective-save", "info", "handing the structured save to the session");
+        // The perk-objective-author pointer rides the skill-binding suffix (D5) since a
+        // warm /objective-save outside a stage:objective-author session gets none from Mechanism A.
+        pi.sendUserMessage(
+          objectiveSaveGuidance(title) + bindingSuffix(ctx.cwd, "stage:objective-author"),
+        );
+        return;
+      }
+      // Saved or save-failed: relay the save message. No node-link sub-step on the objective path,
+      // so the severity ladder is simpler than /plan-save's (no warning tier).
+      const result = outcome.result;
+      const message = result.content[0]?.text ?? "objective-save done";
+      const severity: Severity = result.details.ok ? "info" : "error";
+      report(ctx, "objective-save", severity, message);
+    },
+  });
+}

package/extension/factories/planDraft.ts

@@ -0,0 +1,140 @@
+// The `plan_draft` file tool: the first session-data PRODUCER and the
+// narrow structural read-only-gate carve-out (session data dir only).
+//
+// Carve-out doctrine: the tool takes NO path/name parameter — the artifact name is the fixed
+// constant `PLAN_DRAFT_ARTIFACT` and the path is derived exclusively through the session-data
+// accessor seam (`writeSessionArtifact`, sessionData.ts), so the only bytes it can ever write are
+// the one working-plan artifact in the current run's data dir (gitignored scratch). Allowlisting
+// its name in `READ_ONLY_TOOLS` (toolGating.ts) is therefore safe: the read-only invariant (the
+// worktree stays untouched) holds, and the gate's `tool_call` edit/write/bash blocking logic is
+// UNCHANGED. Full rewrite per call, non-terminating; NOT a save — `plan_save`/`/plan-save` still
+// persist to GitHub. Consumers read the draft only via `readSessionArtifact` (digest-validated,
+// fail-open); the artifact is consumed by `resolvePlanSource` (planSave.ts) — both save
+// surfaces prefer it over an explicit param and over the transcript scrape.
+//
+// Imports stay node builtins + sibling seams (sessionData.ts, toolParams.ts, result.ts) so the
+// module loads under `node --test`; no manual `scratch`/`runs` path segments (cacheGuard.test.ts).
+
+import { relative } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import {
+  activeSessionRunId,
+  digestSessionData,
+  type SessionDataCtx,
+  writeSessionArtifact,
+} from "../substrate/sessionData.ts";
+import { paramsOf, stringParam } from "../substrate/toolParams.ts";
+import type { EntrySink } from "../substrate/workflowState.ts";
+import type { ReportTarget } from "../surfaces/report.ts";
+
+/** The fixed working-plan artifact name (NOT `plan.md` — `cache.plan` is a different file). */
+export const PLAN_DRAFT_ARTIFACT = "plan-draft.md";
+
+/**
+ * Decode unknown `plan_draft` tool-call params (the tool-boundary seam). `plan` absent decodes to
+ * `""` (so the core's `invalid_input` arm owns the empty-plan message); present-but-mistyped →
+ * null (strict-fail `bad_input`). Decode-before-side-effect.
+ */
+export function decodePlanDraftParams(params: unknown): { plan: string } | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const plan = stringParam(p, "plan");
+  if (plan === null) return null;
+  return { plan: plan ?? "" };
+}
+
+/** The ok-arm details — provenance-consistent with the recorded `session_artifacts` pointer. */
+export interface PlanDraftOk {
+  name: string;
+  path: string;
+  digest: string;
+  bytes: number;
+  run_id: string;
+}
+
+export type PlanDraftResult = Result<PlanDraftOk>;
+
+/**
+ * The core both the tool handler and tests call: write the working-plan artifact through the
+ * accessor seam (file + `session_artifacts` provenance pointer). Soft result, never throws —
+ * failure taxonomy: empty plan → `invalid_input`; no session run_id → `no_run_id`; file-or-pointer
+ * write failure → `write_failed` (the seam already warned on stderr).
+ */
+export function writePlanDraft(
+  sink: EntrySink,
+  ctx: SessionDataCtx & ReportTarget,
+  plan: string,
+): PlanDraftResult {
+  const fail = failFor(ctx, "plan-draft");
+
+  if (!plan.trim()) {
+    return fail("no plan markdown to write (pass the full working draft)", "invalid_input");
+  }
+
+  const runId = activeSessionRunId(ctx);
+  if (runId === null) {
+    return fail("session has no run_id — cannot write the plan-draft artifact", "no_run_id");
+  }
+
+  const written = writeSessionArtifact(sink, ctx, PLAN_DRAFT_ARTIFACT, plan);
+  if (written === null) {
+    return fail(
+      `could not write the ${PLAN_DRAFT_ARTIFACT} artifact (see warnings)`,
+      "write_failed",
+    );
+  }
+
+  // Derive digest/relative path consistently with the pointer the seam recorded.
+  const digest = digestSessionData(plan);
+  const relPath = relative(ctx.cwd, written);
+  return ok(`Plan draft written → ${relPath} (${digest})`, {
+    name: PLAN_DRAFT_ARTIFACT,
+    path: relPath,
+    digest,
+    bytes: Buffer.byteLength(plan, "utf8"),
+    run_id: runId,
+  });
+}
+
+const TOOL_GUIDELINES = [
+  "Call plan_draft to persist the current working draft as you author or revise the plan; pass the FULL plan markdown each time (it rewrites the whole draft).",
+  "plan_draft never saves to GitHub and never ends the turn — plan_save//plan-save remain the canonical save surface.",
+];
+
+/** Register the `plan_draft` tool (the carve-out producer; interior-only). */
+export function registerPlanDraft(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "plan_draft",
+    label: "Plan draft",
+    description:
+      "Write (or overwrite) the working plan draft to the session data dir and record its " +
+      "provenance pointer. The only sanctioned write surface while read-only. NOT a save — " +
+      "plan_save//plan-save still persist the plan to GitHub.",
+    promptSnippet: "Persist the working plan draft to the session data dir (full rewrite)",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["plan"],
+      properties: {
+        plan: {
+          type: "string",
+          description: "The full working-plan markdown (rewrites the whole draft).",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodePlanDraftParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "plan-draft",
+          "plan_draft",
+        )("plan_draft needs { plan: string } per the tool schema", "bad_input");
+      }
+      return writePlanDraft(pi, ctx, decoded.plan);
+    },
+  });
+}

package/extension/factories/planMode.ts

@@ -0,0 +1,214 @@
+// perk-owned plan mode. The first consumer of the tool-gating primitive
+// (extension/substrate/toolGating.ts). This is the *toggle surface* on top of that structural gate: a
+// `/plan` command, a `Ctrl+Alt+P` shortcut, and a `--plan` flag all flip `gating.enter`/`exit`.
+// perk owns NO parallel enforcement here — the gate is the single read-only authority.
+//
+// It also injects the cooperative *plan-authoring* prompt layer (the gather-then-plan contract)
+// under its own `perk:plan-context` customType (display:false),
+// keyed directly off the read-only gate (read-only ⟹ plan in the main session). The
+// content is stripped from `context` when the gate is off — the same hygiene the gate applies to its
+// `perk:mode-context`. An optional `[workflow] plan_authoring` config addendum (extension/substrate/config.ts)
+// is appended when present.
+//
+// Grounded in pi's official `examples/extensions/plan-mode/` recipe, but perk adopts ONLY the
+// read-only authoring half: there is no in-session "execution mode" flip — perk separates plan
+// (read-only session) from implement (cold-door fresh worktree session), and `[DONE:n]` tracking
+// lives in the implement session.
+//
+// REGISTRATION-TIME DEFERRAL, now THREE-TIER. `registerPlanMode` resolves the plan
+// provider id once at factory time and branches:
+//   - `perk-plan` (and the fail-safe error path) → register EVERYTHING (the default path is the
+//     hard guarantee, zero behavior change).
+//   - `plannotator-plan` (AUGMENT posture) → register everything EXCEPT the `--plan` flag, the
+//     `Ctrl+Alt+P` shortcut, and the `--plan` session_start handler: `@plannotator/pi-extension`
+//     also registers that flag + shortcut, and duplicate flag/shortcut registration is the known
+//     potentially-fatal Pi behavior — plannotator owns `--plan`/`Ctrl+Alt+P` exclusively while
+//     perk keeps `/plan`, the authoring injection, and the read-only gate (plannotator augments
+//     perk's plan flow via the planAdapterPlannotator `plan_review` bridge; it does not replace it).
+//   - any other foreign id (tombell, REPLACE posture) → register NOTHING; the foreign package owns
+//     `/plan`/`Ctrl+Alt+P`/`--plan` unambiguously (Pi suffixes duplicate command names, so
+//     handler-time deferral alone is insufficient once the foreign package is loaded).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key } from "@earendil-works/pi-tui";
+import { loadPerkConfig } from "../substrate/config.ts";
+import {
+  loadProviders,
+  PERK_PLAN_PROVIDER_ID,
+  PLANNOTATOR_PLAN_PROVIDER_ID,
+  resolveProviders,
+} from "../substrate/providers.ts";
+import type { ToolGating } from "../substrate/toolGating.ts";
+import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { report } from "../surfaces/report.ts";
+import { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
+
+/** The plan-authoring context customType (distinct from the gate's `perk:mode-context`). */
+export const PLAN_CONTEXT_TYPE = "perk:plan-context";
+const PLAN_MARKER = "[PLAN AUTHORING]";
+
+/**
+ * The cooperative gather-then-plan contract. This is prompting, NOT enforcement (the gate is the
+ * enforcement). It never leaks internal policy text — it tells the model how to materialize a
+ * decision-complete plan an executor with zero prior context can follow (mirrors
+ * skills/perk-plan/SKILL.md). Durable anchors only, no line numbers.
+ */
+export const PLAN_AUTHORING_CONTEXT = `${PLAN_MARKER}
+You are authoring a perk plan in read-only mode — explore first, then write.
+
+Gather before you plan. Materialize four finding categories from real evidence:
+- Status: what exists today (the current behavior, where it lives).
+- Discoveries: concrete findings with real file paths and function/class names.
+- Corrections: assumptions that turned out wrong, and what is actually true.
+- Codebase evidence: the specific code you verified each decision against.
+
+Check \`docs/learned/\` for relevant prior art and gotchas before you plan. The ambient routing
+index in your system prompt points into the full catalog at \`docs/learned/index.md\`; when a
+routing cue matches your change, \`read\` that doc. This is a check, not a requirement — there may
+be nothing relevant to your change, and your plan does not need to be grounded in prior learnings.
+
+Write the plan so an executor (a future session, or another engineer) with zero prior context can
+implement it without guessing. Anchor every change durably — function/class names, behavioral
+descriptions, structural locations — never line numbers. Resolve every open choice before saving;
+a saved plan must leave no decisions to the implementer.
+
+When the plan is decision-complete, request a human review:
+- Keep the working draft current with plan_draft — the validated plan-draft artifact is what gets
+  reviewed AND auto-saved.
+- Call the plan_review tool — the human reviews the plan in the configured review surface (perk's
+  in-TUI editor review by default).
+- If the review is DENIED: revise per the feedback, rewrite the draft with plan_draft, then call
+  plan_review again.
+- If the review is APPROVED: the plan is auto-saved and the session leaves read-only. Relay the
+  save outcome — do NOT re-dump the plan as a final message and do NOT tell the user to run
+  /plan-save.
+- If plan_review reports it was skipped or unavailable (headless, dismissed, no surface): present
+  the complete plan as your final message; the human runs /plan-save (the manual failsafe).`;
+
+/** Build the full plan-authoring injection, appending the project config addendum when present. */
+export function planContextContent(cwd: string): string {
+  const addendum = loadPerkConfig(cwd).planAuthoring;
+  return addendum ? `${PLAN_AUTHORING_CONTEXT}\n\n${addendum.trim()}` : PLAN_AUTHORING_CONTEXT;
+}
+
+/**
+ * The resolved `[providers] plan` selection id for `cwd`, read fresh per-event (no static state —
+ * the same per-event-read shape `planContextContent(ctx.cwd)` uses). Fail-safe to the perk-plan
+ * reference: any load/resolution failure (corrupt bundled set, etc.) returns the reference id so
+ * perk's own plan mode keeps working — the default path is the hard guarantee.
+ */
+export function resolvedPlanProviderId(cwd: string): string {
+  try {
+    return resolveProviders(loadPerkConfig(cwd).providers, loadProviders()).plan.id;
+  } catch {
+    return PERK_PLAN_PROVIDER_ID;
+  }
+}
+
+/**
+ * Whether perk's own plan-mode reference is the selected plan provider for `cwd`. When a foreign
+ * plan provider is selected via `[providers] plan`, perk's authoring surface steps aside (defers).
+ */
+export function isPerkPlanReferenceSelected(cwd: string): boolean {
+  return resolvedPlanProviderId(cwd) === PERK_PLAN_PROVIDER_ID;
+}
+
+/**
+ * Register the perk-owned plan-mode toggle surface over the read-only gate. Idempotent enter/exit (the gate
+ * tracks its own on/off transition), fail-safe-headless (notify when UI, else stderr).
+ */
+export function registerPlanMode(pi: ExtensionAPI, gating: ToolGating): void {
+  // Three-tier registration branch (see the header comment): full registration for the reference
+  // (fail-safe default), a PARTIAL vacate (skip only `--plan` + `Ctrl+Alt+P`) under the augment-
+  // posture plannotator selection, and a full vacate under any other foreign selection (tombell).
+  const providerId = resolvedPlanProviderId(process.cwd());
+  const plannotatorSelected = providerId === PLANNOTATOR_PLAN_PROVIDER_ID;
+  if (providerId !== PERK_PLAN_PROVIDER_ID && !plannotatorSelected) return;
+
+  if (!plannotatorSelected) {
+    pi.registerFlag("plan", {
+      description: "Start in perk plan mode (read-only exploration + plan authoring).",
+      type: "boolean",
+      default: false,
+    });
+  }
+
+  function announce(ctx: ExtensionContext, on: boolean): void {
+    const message = on
+      ? "plan mode ON — read-only exploration; author the plan, then review with plan_review (approval auto-saves; /plan-save is the manual failsafe)."
+      : "plan mode OFF — full tool access restored.";
+    report(ctx, "plan-mode", "info", message);
+  }
+
+  function toggle(ctx: ExtensionContext): void {
+    if (gating.isActive()) {
+      gating.exit(ctx);
+      announce(ctx, false);
+    } else {
+      gating.enter(ctx);
+      announce(ctx, true);
+    }
+  }
+
+  pi.registerCommand("plan", {
+    description: "Toggle perk plan mode (read-only exploration + plan authoring).",
+    handler: async (_args, ctx) => toggle(ctx),
+  });
+
+  if (!plannotatorSelected) {
+    pi.registerShortcut(Key.ctrlAlt("p"), {
+      description: "Toggle perk plan mode",
+      handler: async (ctx) => toggle(ctx),
+    });
+
+    // `--plan` cold start: enter read-only on session_start when the flag is set and the gate is
+    // off. (index.ts's session_start already syncs the gate from the rebuilt `mode`; this layers
+    // the flag on top for ad-hoc `pi --plan` interactive starts — the cold plan door drives
+    // read-only via the handoff `mode`, not this flag.) Skipped under the plannotator selection
+    // along with the flag itself (the flag no longer exists on perk's side).
+    pi.on("session_start", async (_event, ctx) => {
+      if (pi.getFlag("plan") === true && !gating.isActive()) {
+        gating.enter(ctx);
+      }
+    });
+  }
+
+  // Inject the plan-authoring context while the read-only gate is active (display:false). The one
+  // exception: an objective-author session is ALSO read-only, but objectiveAuthor.ts injects its
+  // own authoring context there — so plan mode defers when the launched stage is objective-author
+  // (the coupling break: plan-authoring context is no longer keyed off the bare read-only gate).
+  pi.on("before_agent_start", async (_event, ctx) => {
+    if (!gating.isActive()) return;
+    const branch = branchOf(ctx);
+    if (rebuildWorkflowState(branch).stage === OBJECTIVE_AUTHOR_STAGE) return;
+    return {
+      message: {
+        customType: PLAN_CONTEXT_TYPE,
+        content: planContextContent(ctx.cwd),
+        display: false,
+      },
+    };
+  });
+
+  // Strip the stale plan-authoring marker from context when the gate is off (so it never lingers).
+  pi.on("context", async (event) => {
+    if (gating.isActive()) return;
+    return {
+      messages: event.messages.filter((m) => {
+        const msg = m as { customType?: string; role?: string; content?: unknown };
+        if (msg.customType === PLAN_CONTEXT_TYPE) return false;
+        if (msg.role !== "user") return true;
+        const content = msg.content;
+        if (typeof content === "string") return !content.includes(PLAN_MARKER);
+        if (Array.isArray(content)) {
+          return !content.some(
+            (c) =>
+              (c as { type?: string; text?: string }).type === "text" &&
+              ((c as { text?: string }).text ?? "").includes(PLAN_MARKER),
+          );
+        }
+        return true;
+      }),
+    };
+  });
+}