gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -491,6 +491,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
       definitionOfDone: Type.Optional(Type.Array(Type.String(), { description: "Definition of done bullets" })),
       requirementCoverage: Type.Optional(Type.String({ description: "Requirement coverage text" })),
       boundaryMapMarkdown: Type.Optional(Type.String({ description: "Boundary map markdown block" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'plan-phase complete')" })),
     }),
     execute: planMilestoneExecute,
   };
@@ -537,6 +540,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
       proofLevel: Type.Optional(Type.String({ description: "Slice proof level" })),
       integrationClosure: Type.Optional(Type.String({ description: "Slice integration closure" })),
       observabilityImpact: Type.Optional(Type.String({ description: "Slice observability impact" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'plan-phase complete')" })),
     }),
     execute: planSliceExecute,
   };
@@ -607,6 +613,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
       inputs: Type.Array(Type.String(), { description: "Input files or references" }),
       expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
       observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'plan-phase complete')" })),
     }),
     execute: planTaskExecute,
   };
@@ -674,6 +683,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
         ]),
         { description: "Array of verification evidence entries" },
       )),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'task verified after retry')" })),
     }),
     execute: taskCompleteExecute,
   };
@@ -771,6 +783,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
         ]),
         { description: "Upstream slice dependencies consumed" },
       )),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'all tasks verified')" })),
     }),
     execute: sliceCompleteExecute,
   };
@@ -905,6 +920,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
       lessonsLearned: Type.Optional(Type.Array(Type.String(), { description: "Lessons learned during the milestone" })),
       followUps: Type.Optional(Type.String({ description: "Follow-up items for future milestones" })),
       deviations: Type.Optional(Type.String({ description: "Deviations from the original plan" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'milestone validation passed')" })),
     }),
     execute: milestoneCompleteExecute,
   };
@@ -989,6 +1007,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
         { description: "Tasks to upsert (update existing or insert new)" },
       ),
       removedTaskIds: Type.Array(Type.String(), { description: "Task IDs to remove from the slice" }),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'blocker discovered during execution')" })),
     }),
     execute: replanSliceExecute,
   };
@@ -1044,6 +1065,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
         ),
         removed: Type.Array(Type.String(), { description: "Slice IDs to remove" }),
       }, { description: "Slice changes to apply" }),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'slice S01 completed, reassessing remaining roadmap')" })),
     }),
     execute: reassessRoadmapExecute,
   };
@@ -1051,6 +1075,203 @@ export function registerDbTools(pi: ExtensionAPI): void {
   pi.registerTool(reassessRoadmapTool);
   registerAlias(pi, reassessRoadmapTool, "gsd_roadmap_reassess", "gsd_reassess_roadmap");
 
+  // ─── gsd_task_reopen (gsd_reopen_task alias) ───────────────────────────
+  // Single-writer v3, Stream 3: reversibility tools for closed units.
+
+  const reopenTaskExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const dbAvailable = await ensureDbOpen();
+    if (!dbAvailable) {
+      return {
+        content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reopen task." }],
+        details: { operation: "reopen_task", error: "db_unavailable" } as any,
+      };
+    }
+    try {
+      const { handleReopenTask } = await import("../tools/reopen-task.js");
+      const result = await handleReopenTask(params, process.cwd());
+      if ("error" in result) {
+        return {
+          content: [{ type: "text" as const, text: `Error reopening task: ${result.error}` }],
+          details: { operation: "reopen_task", error: result.error } as any,
+        };
+      }
+      return {
+        content: [{ type: "text" as const, text: `Reopened task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }],
+        details: {
+          operation: "reopen_task",
+          milestoneId: result.milestoneId,
+          sliceId: result.sliceId,
+          taskId: result.taskId,
+        } as any,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError("tool", `reopen_task tool failed: ${msg}`, { tool: "gsd_task_reopen", error: String(err) });
+      return {
+        content: [{ type: "text" as const, text: `Error reopening task: ${msg}` }],
+        details: { operation: "reopen_task", error: msg } as any,
+      };
+    }
+  };
+
+  const reopenTaskTool = {
+    name: "gsd_task_reopen",
+    label: "Reopen Task",
+    description:
+      "Reset a completed task back to 'pending' so it can be re-done. Cleans up SUMMARY.md so the DB-filesystem reconciler does not auto-correct the task back to complete. " +
+      "Both the parent slice and milestone must still be open — use gsd_slice_reopen first if the slice has been closed.",
+    promptSnippet: "Reopen a completed GSD task (resets status to pending, removes SUMMARY.md)",
+    promptGuidelines: [
+      "Use gsd_task_reopen when a completed task needs to be re-done (e.g. verification missed a regression, requirements changed).",
+      "Will fail if the parent slice or milestone is already closed — reopen those first.",
+      "Will fail if the task is not currently 'complete' — there is nothing to reopen.",
+      "Use the canonical name gsd_task_reopen; gsd_reopen_task is only an alias.",
+    ],
+    parameters: Type.Object({
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
+      taskId: Type.String({ description: "Task ID (e.g. T01)" }),
+      reason: Type.Optional(Type.String({ description: "Why the task is being reopened (recorded in the audit trail)" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'regression discovered post-completion')" })),
+    }),
+    execute: reopenTaskExecute,
+  };
+
+  pi.registerTool(reopenTaskTool);
+  registerAlias(pi, reopenTaskTool, "gsd_reopen_task", "gsd_task_reopen");
+
+  // ─── gsd_slice_reopen (gsd_reopen_slice alias) ─────────────────────────
+
+  const reopenSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const dbAvailable = await ensureDbOpen();
+    if (!dbAvailable) {
+      return {
+        content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reopen slice." }],
+        details: { operation: "reopen_slice", error: "db_unavailable" } as any,
+      };
+    }
+    try {
+      const { handleReopenSlice } = await import("../tools/reopen-slice.js");
+      const result = await handleReopenSlice(params, process.cwd());
+      if ("error" in result) {
+        return {
+          content: [{ type: "text" as const, text: `Error reopening slice: ${result.error}` }],
+          details: { operation: "reopen_slice", error: result.error } as any,
+        };
+      }
+      return {
+        content: [{ type: "text" as const, text: `Reopened slice ${result.sliceId} (${result.milestoneId}); reset ${result.tasksReset} task(s) to pending.` }],
+        details: {
+          operation: "reopen_slice",
+          milestoneId: result.milestoneId,
+          sliceId: result.sliceId,
+          tasksReset: result.tasksReset,
+        } as any,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError("tool", `reopen_slice tool failed: ${msg}`, { tool: "gsd_slice_reopen", error: String(err) });
+      return {
+        content: [{ type: "text" as const, text: `Error reopening slice: ${msg}` }],
+        details: { operation: "reopen_slice", error: msg } as any,
+      };
+    }
+  };
+
+  const reopenSliceTool = {
+    name: "gsd_slice_reopen",
+    label: "Reopen Slice",
+    description:
+      "Reset a completed slice back to 'in_progress' and reset ALL of its tasks back to 'pending'. Cleans up SUMMARY.md / UAT.md and per-task summaries. " +
+      "Reopening a slice means re-doing the work — partial resets create ambiguous state, so all tasks are reset.",
+    promptSnippet: "Reopen a completed GSD slice (resets all tasks to pending, removes summaries)",
+    promptGuidelines: [
+      "Use gsd_slice_reopen when a completed slice needs to be re-done (e.g. integration issue surfaced, requirements changed).",
+      "All tasks within the slice are reset to 'pending' — there is no partial-reopen.",
+      "Will fail if the parent milestone is already closed — reopen the milestone first.",
+      "Will fail if the slice is not currently 'complete' — there is nothing to reopen.",
+      "Use the canonical name gsd_slice_reopen; gsd_reopen_slice is only an alias.",
+    ],
+    parameters: Type.Object({
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
+      reason: Type.Optional(Type.String({ description: "Why the slice is being reopened (recorded in the audit trail)" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'cross-slice regression discovered')" })),
+    }),
+    execute: reopenSliceExecute,
+  };
+
+  pi.registerTool(reopenSliceTool);
+  registerAlias(pi, reopenSliceTool, "gsd_reopen_slice", "gsd_slice_reopen");
+
+  // ─── gsd_milestone_reopen (gsd_reopen_milestone alias) ─────────────────
+
+  const reopenMilestoneExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const dbAvailable = await ensureDbOpen();
+    if (!dbAvailable) {
+      return {
+        content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reopen milestone." }],
+        details: { operation: "reopen_milestone", error: "db_unavailable" } as any,
+      };
+    }
+    try {
+      const { handleReopenMilestone } = await import("../tools/reopen-milestone.js");
+      const result = await handleReopenMilestone(params, process.cwd());
+      if ("error" in result) {
+        return {
+          content: [{ type: "text" as const, text: `Error reopening milestone: ${result.error}` }],
+          details: { operation: "reopen_milestone", error: result.error } as any,
+        };
+      }
+      return {
+        content: [{ type: "text" as const, text: `Reopened milestone ${result.milestoneId}; reset ${result.slicesReset} slice(s) and ${result.tasksReset} task(s).` }],
+        details: {
+          operation: "reopen_milestone",
+          milestoneId: result.milestoneId,
+          slicesReset: result.slicesReset,
+          tasksReset: result.tasksReset,
+        } as any,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logError("tool", `reopen_milestone tool failed: ${msg}`, { tool: "gsd_milestone_reopen", error: String(err) });
+      return {
+        content: [{ type: "text" as const, text: `Error reopening milestone: ${msg}` }],
+        details: { operation: "reopen_milestone", error: msg } as any,
+      };
+    }
+  };
+
+  const reopenMilestoneTool = {
+    name: "gsd_milestone_reopen",
+    label: "Reopen Milestone",
+    description:
+      "Reset a closed milestone back to 'active', all of its slices to 'in_progress', and all tasks to 'pending'. " +
+      "Cleans up MILESTONE-SUMMARY.md, slice summaries, and task summaries so the DB-filesystem reconciler does not auto-correct status back to complete.",
+    promptSnippet: "Reopen a closed GSD milestone (resets slices and tasks, removes summaries)",
+    promptGuidelines: [
+      "Use gsd_milestone_reopen when a closed milestone needs to be re-done (e.g. validation failure surfaced after closure).",
+      "All slices reset to 'in_progress' and all tasks reset to 'pending' — no partial reopen.",
+      "Will fail if the milestone is not currently closed — there is nothing to reopen.",
+      "Use the canonical name gsd_milestone_reopen; gsd_reopen_milestone is only an alias.",
+    ],
+    parameters: Type.Object({
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      reason: Type.Optional(Type.String({ description: "Why the milestone is being reopened (recorded in the audit trail)" })),
+      // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'post-closure validation failure')" })),
+    }),
+    execute: reopenMilestoneExecute,
+  };
+
+  pi.registerTool(reopenMilestoneTool);
+  registerAlias(pi, reopenMilestoneTool, "gsd_reopen_milestone", "gsd_milestone_reopen");
+
   // ─── gsd_save_gate_result ──────────────────────────────────────────────
 
   const saveGateResultExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {

package/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts

@@ -6,14 +6,12 @@ import type {
 
 import { getAutoDashboardData, startAuto, type AutoDashboardData } from "../auto.js";
 import { resetTransientRetryState } from "./agent-end-recovery.js";
-import { resetSessionTimeoutState } from "../auto/phases.js";
 
 type AutoResumeSnapshot = Pick<AutoDashboardData, "active" | "paused" | "stepMode" | "basePath">;
 
 export interface ProviderErrorResumeDeps {
   getSnapshot(): AutoResumeSnapshot;
   resetTransientRetryState(): void;
-  resetSessionTimeoutState(): void;
   startAuto(
     ctx: ExtensionCommandContext,
     pi: ExtensionAPI,
@@ -26,7 +24,6 @@ export interface ProviderErrorResumeDeps {
 const defaultDeps: ProviderErrorResumeDeps = {
   getSnapshot: () => getAutoDashboardData(),
   resetTransientRetryState,
-  resetSessionTimeoutState,
   startAuto,
 };
 
@@ -48,11 +45,10 @@ export async function resumeAutoAfterProviderDelay(
     return "missing-base";
   }
 
-  // Reset retry counters before restarting — without this, counters
-  // accumulate across pause/resume cycles and permanently lock out
-  // auto-resume after their respective MAX thresholds.
+  // Reset provider-error retry state before restarting. Session-creation
+  // timeout state intentionally survives delayed resumes so the bounded
+  // auto-resume limit cannot be reset into an infinite pause/resume loop.
   deps.resetTransientRetryState();
-  deps.resetSessionTimeoutState();
 
   await deps.startAuto(
     ctx as ExtensionCommandContext,

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -393,7 +393,7 @@ export function registerHooks(
     if (isAutoActive() && typeof event.toolCallId === "string") {
       markToolEnd(event.toolCallId);
     }
-    if (isAutoActive() && event.isError && event.toolName.startsWith("gsd_")) {
+    if (isAutoActive() && event.isError) {
       const resultPayload = ("result" in event ? event.result : undefined) as any;
       const errorText = typeof resultPayload === "string"
         ? resultPayload
@@ -402,6 +402,8 @@ export function registerHooks(
             : (typeof (event as any).content === "string"
                 ? (event as any).content
                 : String(resultPayload ?? "")));
+      // Let recordToolInvocationError classify the failure so non-gsd_ harness
+      // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
     }
     if (event.toolName !== "ask_user_questions") return;
@@ -489,12 +491,14 @@ export function registerHooks(
 
   pi.on("tool_execution_end", async (event) => {
     markToolEnd(event.toolCallId);
-    // #2883: Capture tool invocation errors (malformed/truncated JSON arguments)
+    // #2883/#4974: Capture deterministic invocation/policy errors
     // so postUnitPreVerification can break the retry loop instead of re-dispatching.
-    if (event.isError && event.toolName.startsWith("gsd_")) {
+    if (event.isError) {
       const errorText = typeof event.result === "string"
         ? event.result
         : (typeof event.result?.content?.[0]?.text === "string" ? event.result.content[0].text : String(event.result));
+      // Let recordToolInvocationError classify the failure so non-gsd_ harness
+      // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
     }
     // Safety harness: record tool execution results for evidence cross-referencing

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -1,7 +1,25 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
-const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
+import { minimatch } from "minimatch";
+
+/**
+ * Declarative tools-policy for a unit. Inlined here because the worktree
+ * branch predates the full unit-context-manifest export (#4934).
+ */
+export type ToolsPolicy =
+  | { mode: "all" }
+  | { mode: "read-only" }
+  | { mode: "planning" }
+  | { mode: "docs"; allowedPathGlobs: readonly string[] };
+
+/**
+ * Regex matching milestone CONTEXT.md file names in both legacy M001
+ * and unique M001-abc123 formats. Exported so regex-hardening tests
+ * can exercise the real pattern rather than a drift-prone inline
+ * re-implementation (see #4835).
+ */
+export const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
 
@@ -91,8 +109,15 @@ export interface WriteGateSnapshot {
   pendingGateId: string | null;
 }
 
+/**
+ * Persistence is ON by default (opt-out).
+ * Set GSD_PERSIST_WRITE_GATE_STATE="0" or GSD_PERSIST_WRITE_GATE_STATE="false"
+ * to disable. All other values — including unset — persist the snapshot.
+ * (Inverted from the original opt-in guard; see #4950.)
+ */
 function shouldPersistWriteGateSnapshot(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env.GSD_PERSIST_WRITE_GATE_STATE === "1";
+  const v = env.GSD_PERSIST_WRITE_GATE_STATE;
+  return v !== "0" && v !== "false";
 }
 
 function writeGateSnapshotPath(basePath: string = process.cwd()): string {
@@ -111,9 +136,20 @@ function persistWriteGateSnapshot(basePath: string = process.cwd()): void {
   if (!shouldPersistWriteGateSnapshot()) return;
   const path = writeGateSnapshotPath(basePath);
   mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true });
-  const tempPath = `${path}.tmp`;
+  const tempPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
   writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(), null, 2), "utf-8");
-  renameSync(tempPath, path);
+  try {
+    renameSync(tempPath, path);
+  } catch (err: unknown) {
+    // EXDEV: cross-device rename (temp and dest on different mounts). Fall back
+    // to copy-then-delete so the snapshot is still written atomically enough.
+    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "EXDEV") {
+      copyFileSync(tempPath, path);
+      unlinkSync(tempPath);
+    } else {
+      throw err;
+    }
+  }
 }
 
 function clearPersistedWriteGateSnapshot(basePath: string = process.cwd()): void {
@@ -353,9 +389,9 @@ export function isDepthConfirmationAnswer(
     return typeof confirmLabel === "string" && value === confirmLabel;
   }
 
-  // Fallback when options aren't available (e.g., older call sites):
-  // accept only if it contains "(Recommended)" — the prompt convention suffix.
-  return value.includes("(Recommended)");
+  // Fail-closed: no options means we cannot structurally validate the answer.
+  // Returning false prevents any free-form string from unlocking the gate.
+  return false;
 }
 
 export function shouldBlockContextWrite(
@@ -497,3 +533,116 @@ export function shouldBlockQueueExecutionInSnapshot(
     reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. Unknown tools are not permitted during queue mode.`,
   };
 }
+
+// ─── Planning-unit tools-policy enforcement (#4934) ───────────────────────
+
+const PLANNING_WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "notebook_edit"]);
+const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
+
+const PLANNING_SAFE_TOOLS = new Set([
+  "read", "grep", "find", "ls", "glob",
+  "ask_user_questions",
+  "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
+  "search_and_read",
+]);
+
+function isPathUnderGsd(absPath: string, basePath: string): boolean {
+  const gsdRoot = resolve(basePath, ".gsd");
+  const rel = relative(gsdRoot, absPath);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function matchesAllowedGlob(absPath: string, basePath: string, globs: readonly string[]): boolean {
+  const rel = relative(basePath, absPath);
+  if (rel.startsWith("..") || isAbsolute(rel)) return false;
+  const posix = rel.split(sep).join("/");
+  return globs.some(g => minimatch(posix, g, { dot: false, nocase: false }));
+}
+
+function blockReason(unitType: string, mode: string, what: string): string {
+  return [
+    `HARD BLOCK: unit "${unitType}" runs under tools-policy "${mode}" — ${what}.`,
+    `This is a mechanical gate enforced by manifest.tools (#4934). You MUST NOT proceed,`,
+    `retry the same call, or rationalize past this block. If you need to write user source,`,
+    `the work belongs in execute-task, not in a planning unit.`,
+  ].join(" ");
+}
+
+/**
+ * Planning-unit tool-policy enforcement. Returns { block } per the policy
+ * resolved from the active unit's manifest:
+ *
+ *   - "all"        → never blocks.
+ *   - "read-only"  → blocks all writes, bash, and subagent dispatch.
+ *   - "planning"   → blocks writes to paths outside <basePath>/.gsd/,
+ *                    bash that isn't read-only, and subagent dispatch.
+ *   - "docs"       → like "planning" but also allows writes to paths
+ *                    matching `allowedPathGlobs` relative to basePath.
+ *
+ * `policy` of null means "no manifest resolved" — pass-through.
+ */
+export function shouldBlockPlanningUnit(
+  toolName: string,
+  pathOrCommand: string,
+  basePath: string,
+  unitType: string,
+  policy: ToolsPolicy | null | undefined,
+): { block: boolean; reason?: string } {
+  if (!policy) return { block: false };
+  if (policy.mode === "all") return { block: false };
+
+  const tool = toolName;
+
+  if (policy.mode === "read-only") {
+    if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
+    if (tool.startsWith("gsd_")) return { block: false };
+    if (PLANNING_WRITE_TOOLS.has(tool) || tool === "bash" || PLANNING_SUBAGENT_TOOLS.has(tool)) {
+      return { block: true, reason: blockReason(unitType, policy.mode, `${tool} is not permitted (read-only)`) };
+    }
+    return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
+  }
+
+  // planning / docs modes
+  if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
+  if (tool.startsWith("gsd_")) return { block: false };
+
+  if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
+    return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
+  }
+
+  if (tool === "bash") {
+    if (BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
+    return {
+      block: true,
+      reason: blockReason(
+        unitType,
+        policy.mode,
+        `bash is restricted to read-only commands (cat/grep/git log/etc); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`,
+      ),
+    };
+  }
+
+  if (PLANNING_WRITE_TOOLS.has(tool)) {
+    if (!pathOrCommand) {
+      return { block: true, reason: blockReason(unitType, policy.mode, `${tool} called with empty path`) };
+    }
+    const absPath = isAbsolute(pathOrCommand) ? pathOrCommand : resolve(basePath, pathOrCommand);
+
+    if (isPathUnderGsd(absPath, basePath)) return { block: false };
+
+    if (policy.mode === "docs" && matchesAllowedGlob(absPath, basePath, policy.allowedPathGlobs)) {
+      return { block: false };
+    }
+
+    return {
+      block: true,
+      reason: blockReason(
+        unitType,
+        policy.mode,
+        `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`,
+      ),
+    };
+  }
+
+  return { block: false };
+}