gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0-dev.aeeb2ca00

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -462,6 +462,9 @@ export function registerDbTools(pi) {
             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,
     };
@@ -503,6 +506,9 @@ export function registerDbTools(pi) {
             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,
     };
@@ -569,6 +575,9 @@ export function registerDbTools(pi) {
             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,
     };
@@ -628,6 +637,9 @@ export function registerDbTools(pi) {
                 }),
                 Type.String({ description: "Fallback: verification summary string" }),
             ]), { 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,
     };
@@ -705,6 +717,9 @@ export function registerDbTools(pi) {
                 }),
                 Type.String({ description: "Fallback: slice ID string" }),
             ]), { 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,
     };
@@ -826,6 +841,9 @@ export function registerDbTools(pi) {
             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,
     };
@@ -897,6 +915,9 @@ export function registerDbTools(pi) {
                 expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
             }), { 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,
     };
@@ -941,11 +962,199 @@ export function registerDbTools(pi) {
                 }), { description: "New slices to add" }),
                 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,
     };
     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, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available. Cannot reopen task." }],
+                details: { operation: "reopen_task", error: "db_unavailable" },
+            };
+        }
+        try {
+            const { handleReopenTask } = await import("../tools/reopen-task.js");
+            const result = await handleReopenTask(params, process.cwd());
+            if ("error" in result) {
+                return {
+                    content: [{ type: "text", text: `Error reopening task: ${result.error}` }],
+                    details: { operation: "reopen_task", error: result.error },
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Reopened task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }],
+                details: {
+                    operation: "reopen_task",
+                    milestoneId: result.milestoneId,
+                    sliceId: result.sliceId,
+                    taskId: result.taskId,
+                },
+            };
+        }
+        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", text: `Error reopening task: ${msg}` }],
+                details: { operation: "reopen_task", error: msg },
+            };
+        }
+    };
+    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, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available. Cannot reopen slice." }],
+                details: { operation: "reopen_slice", error: "db_unavailable" },
+            };
+        }
+        try {
+            const { handleReopenSlice } = await import("../tools/reopen-slice.js");
+            const result = await handleReopenSlice(params, process.cwd());
+            if ("error" in result) {
+                return {
+                    content: [{ type: "text", text: `Error reopening slice: ${result.error}` }],
+                    details: { operation: "reopen_slice", error: result.error },
+                };
+            }
+            return {
+                content: [{ type: "text", 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,
+                },
+            };
+        }
+        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", text: `Error reopening slice: ${msg}` }],
+                details: { operation: "reopen_slice", error: msg },
+            };
+        }
+    };
+    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, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available. Cannot reopen milestone." }],
+                details: { operation: "reopen_milestone", error: "db_unavailable" },
+            };
+        }
+        try {
+            const { handleReopenMilestone } = await import("../tools/reopen-milestone.js");
+            const result = await handleReopenMilestone(params, process.cwd());
+            if ("error" in result) {
+                return {
+                    content: [{ type: "text", text: `Error reopening milestone: ${result.error}` }],
+                    details: { operation: "reopen_milestone", error: result.error },
+                };
+            }
+            return {
+                content: [{ type: "text", 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,
+                },
+            };
+        }
+        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", text: `Error reopening milestone: ${msg}` }],
+                details: { operation: "reopen_milestone", error: msg },
+            };
+        }
+    };
+    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, params, _signal, _onUpdate, _ctx) => {
         return executeSaveGateResult(params, process.cwd());

package/dist/resources/extensions/gsd/bootstrap/provider-error-resume.js

@@ -1,10 +1,8 @@
 import { getAutoDashboardData, startAuto } from "../auto.js";
 import { resetTransientRetryState } from "./agent-end-recovery.js";
-import { resetSessionTimeoutState } from "../auto/phases.js";
 const defaultDeps = {
     getSnapshot: () => getAutoDashboardData(),
     resetTransientRetryState,
-    resetSessionTimeoutState,
     startAuto,
 };
 export async function resumeAutoAfterProviderDelay(pi, ctx, deps = defaultDeps) {
@@ -17,11 +15,10 @@ export async function resumeAutoAfterProviderDelay(pi, ctx, deps = defaultDeps)
         ctx.ui.notify("Provider error recovery delay elapsed, but no paused auto-mode base path was available. Leaving auto-mode paused.", "warning");
         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, pi, snapshot.basePath, false, { step: snapshot.stepMode });
     return "resumed";
 }

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -353,7 +353,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         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);
             const errorText = typeof resultPayload === "string"
                 ? resultPayload
@@ -362,6 +362,8 @@ export function registerHooks(pi, ecosystemHandlers) {
                     : (typeof event.content === "string"
                         ? event.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")
@@ -447,12 +449,14 @@ export function registerHooks(pi, ecosystemHandlers) {
     });
     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/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,6 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { minimatch } from "minimatch";
+/**
+ * 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;
 /**
@@ -76,8 +83,15 @@ const GATE_SAFE_TOOLS = new Set([
     "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
     "search_and_read",
 ]);
+/**
+ * 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 = process.env) {
-    return env.GSD_PERSIST_WRITE_GATE_STATE === "1";
+    const v = env.GSD_PERSIST_WRITE_GATE_STATE;
+    return v !== "0" && v !== "false";
 }
 function writeGateSnapshotPath(basePath = process.cwd()) {
     return join(basePath, ".gsd", "runtime", "write-gate-state.json");
@@ -94,9 +108,22 @@ function persistWriteGateSnapshot(basePath = process.cwd()) {
         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) {
+        // 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.code === "EXDEV") {
+            copyFileSync(tempPath, path);
+            unlinkSync(tempPath);
+        }
+        else {
+            throw err;
+        }
+    }
 }
 function clearPersistedWriteGateSnapshot(basePath = process.cwd()) {
     if (!shouldPersistWriteGateSnapshot())
@@ -295,9 +322,9 @@ export function isDepthConfirmationAnswer(selected, options) {
         const confirmLabel = options[0]?.label;
         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(toolName, inputPath, milestoneId, _queuePhaseActive) {
     if (toolName !== "write")
@@ -413,3 +440,94 @@ export function shouldBlockQueueExecutionInSnapshot(snapshot, toolName, input, q
         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, basePath) {
+    const gsdRoot = resolve(basePath, ".gsd");
+    const rel = relative(gsdRoot, absPath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function matchesAllowedGlob(absPath, basePath, globs) {
+    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, mode, what) {
+    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, pathOrCommand, basePath, unitType, policy) {
+    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 };
+}