@opengsd/gsd-pi 1.3.0-dev.965d1788 → 1.3.0-dev.cca9c184

package/packages/pi-ai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-ai",
-  "version": "1.3.0-dev.965d1788",
+  "version": "1.3.0-dev.cca9c184",
   "description": "Unified LLM API with automatic model discovery and provider configuration",
   "type": "module",
   "gsd": {

package/packages/pi-coding-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-coding-agent",
-  "version": "1.3.0-dev.965d1788",
+  "version": "1.3.0-dev.cca9c184",
   "description": "Coding agent CLI (vendored from earendil-works/pi)",
   "type": "module",
   "gsd": {
@@ -33,7 +33,7 @@
     "copy-assets": "node scripts/copy-assets.cjs"
   },
   "dependencies": {
-    "@opengsd/contracts": "^1.3.0-dev.965d1788",
+    "@opengsd/contracts": "^1.3.0-dev.cca9c184",
     "@mariozechner/jiti": "^2.6.2",
     "@silvia-odwyer/photon-node": "0.3.4",
     "chalk": "5.6.2",
@@ -53,11 +53,11 @@
     "typebox": "1.1.38",
     "undici": "7.28.0",
     "yaml": "2.9.0",
-    "@gsd/agent-core": "^1.3.0-dev.965d1788",
-    "@gsd/native": "^1.3.0-dev.965d1788",
-    "@gsd/pi-agent-core": "^1.3.0-dev.965d1788",
-    "@gsd/pi-ai": "^1.3.0-dev.965d1788",
-    "@gsd/pi-tui": "^1.3.0-dev.965d1788",
+    "@gsd/agent-core": "^1.3.0-dev.cca9c184",
+    "@gsd/native": "^1.3.0-dev.cca9c184",
+    "@gsd/pi-agent-core": "^1.3.0-dev.cca9c184",
+    "@gsd/pi-ai": "^1.3.0-dev.cca9c184",
+    "@gsd/pi-tui": "^1.3.0-dev.cca9c184",
     "@sinclair/typebox": "^0.34.41"
   },
   "devDependencies": {

package/packages/pi-tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-tui",
-  "version": "1.3.0-dev.965d1788",
+  "version": "1.3.0-dev.cca9c184",
   "description": "Terminal UI library (vendored from earendil-works/pi)",
   "type": "module",
   "gsd": {
@@ -21,7 +21,7 @@
     "build": "node ../../scripts/clean-package-dist.cjs && tsc -p tsconfig.json --incremental false"
   },
   "dependencies": {
-    "@gsd/native": "^1.3.0-dev.965d1788",
+    "@gsd/native": "^1.3.0-dev.cca9c184",
     "get-east-asian-width": "1.6.0",
     "marked": "15.0.12",
     "@sinclair/typebox": "^0.34.41"

package/packages/rpc-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/rpc-client",
-  "version": "1.3.0-dev.965d1788",
+  "version": "1.3.0-dev.cca9c184",
   "description": "Standalone RPC client SDK for GSD — zero internal dependencies",
   "license": "MIT",
   "gsd": {
@@ -34,7 +34,7 @@
     "test": "node --test dist/rpc-client.test.js"
   },
   "dependencies": {
-    "@opengsd/contracts": "^1.3.0-dev.965d1788"
+    "@opengsd/contracts": "^1.3.0-dev.cca9c184"
   },
   "engines": {
     "node": ">=22.0.0"

package/pkg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittercowboy/gsd",
-  "version": "1.3.0-dev.965d1788",
+  "version": "1.3.0-dev.cca9c184",
   "piConfig": {
     "name": "gsd",
     "configDir": ".gsd"

package/src/resources/extensions/claude-code-cli/models.ts

@@ -48,6 +48,15 @@ export const CLAUDE_CODE_MODELS = [
 		contextWindow: 1_000_000,
 		maxTokens: 128_000,
 	},
+	{
+		id: "claude-sonnet-5",
+		name: "Claude Sonnet 5 (via Claude Code)",
+		reasoning: true,
+		input: ["text", "image"] as ("text" | "image")[],
+		cost: ZERO_COST,
+		contextWindow: 1_000_000,
+		maxTokens: 128_000,
+	},
 	{
 		id: "claude-sonnet-4-6",
 		name: "Claude Sonnet 4.6 (via Claude Code)",

package/src/resources/extensions/claude-code-cli/tests/index.test.ts

@@ -30,6 +30,20 @@ test("registers the claude-code provider with a streamSimple delegate", () => {
 	assert.equal(typeof providers[0].config.streamSimple, "function");
 });
 
+test("registers Claude Sonnet 5 as a Claude Code CLI model", () => {
+	const { pi, providers } = makeMockPi();
+	claudeCodeCli(pi as never);
+
+	const models = providers[0].config.models as Array<Record<string, unknown>>;
+	const sonnet5 = models.find((model) => model.id === "claude-sonnet-5");
+
+	assert.ok(sonnet5, "claude-sonnet-5 must be selectable via the claude-code provider");
+	assert.equal(sonnet5.name, "Claude Sonnet 5 (via Claude Code)");
+	assert.equal(sonnet5.reasoning, true);
+	assert.equal(sonnet5.contextWindow, 1_000_000);
+	assert.equal(sonnet5.maxTokens, 128_000);
+});
+
 test("registers a before_provider_request hook to capture the UI context", () => {
 	const { pi, handlers } = makeMockPi();
 	claudeCodeCli(pi as never);

package/src/resources/extensions/gsd/auto/loop-deps.ts

@@ -52,6 +52,7 @@ export type PauseAutoUnitIdentity = {
 
 export interface PauseAutoOptions {
   expectedCurrentUnit?: PauseAutoUnitIdentity | null;
+  abortActiveTurn?: boolean;
 }
 
 type PauseAutoFn = (

package/src/resources/extensions/gsd/auto/session.ts

@@ -212,6 +212,13 @@ export class AutoSession {
    * the issues after MAX_PRE_EXEC_RETRIES re-attempts.
    */
   readonly preExecRetryCount: Map<string, number> = new Map();
+  /**
+   * Tracks how many times each slice unit has been re-dispatched to plan-slice
+   * because task plan files were missing. Keyed by unitId (e.g. "M001/S01").
+   * Separate from preExecRetryCount so pre-exec gate failures do not block or
+   * conflate with missing-task-plan recovery.
+   */
+  readonly missingTaskPlanRetryCount: Map<string, number> = new Map();
 
   // ── Tool invocation errors (#2883) ──────────────────────────────────
   /** Set when a GSD tool execution ends with isError due to malformed/truncated
@@ -413,6 +420,7 @@ export class AutoSession {
     this.consecutiveCompleteBootstraps = 0;
     this.lastPreExecFailure = null;
     this.preExecRetryCount.clear();
+    this.missingTaskPlanRetryCount.clear();
     this.lastToolInvocationError = null;
     this.toolUnavailableRetries = 0;
     this.lastUnitAgentEndMessages = null;

package/src/resources/extensions/gsd/auto-budget.ts

@@ -79,7 +79,9 @@ export function resolveCompactionThresholdPercent(raw: number | undefined): numb
   return value <= 1 ? value * 100 : value;
 }
 
-export function shouldRerootStepSessionForContext(
+export const HARD_CONTEXT_REROOT_THRESHOLD_PERCENT = 90;
+
+export function shouldWarnStepSessionForContext(
   contextPercent: number | null | undefined,
   compactionThresholdPercent?: number,
 ): boolean {
@@ -88,3 +90,12 @@ export function shouldRerootStepSessionForContext(
     resolveCompactionThresholdPercent(compactionThresholdPercent),
   ) === "pause";
 }
+
+export function shouldRerootStepSessionForContext(
+  contextPercent: number | null | undefined,
+): boolean {
+  return getContextPauseAction(
+    contextPercent,
+    HARD_CONTEXT_REROOT_THRESHOLD_PERCENT,
+  ) === "pause";
+}

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -1523,6 +1523,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
       const sid = state.activeSlice!.id;
       const sTitle = state.activeSlice!.title;
       const tid = state.activeTask.id;
+      const unitId = `${mid}/${sid}`;
       const artifactBasePath = resolveArtifactBasePath(basePath, mid, session);
 
       // Guard: if the slice plan exists but the individual task plan files are
@@ -1562,6 +1563,17 @@ export const DISPATCH_RULES: DispatchRule[] = [
         !existsSync(projectionTaskPlanPath) &&
         !tasksEmbeddedInSlicePlan
       ) {
+        const MAX_MISSING_TASK_PLAN_RETRIES = 2;
+        const retryCount = session?.missingTaskPlanRetryCount?.get(unitId) ?? 0;
+        if (retryCount >= MAX_MISSING_TASK_PLAN_RETRIES) {
+          session?.missingTaskPlanRetryCount?.delete(unitId);
+          return {
+            action: "stop",
+            reason: `Missing task-plan recovery failed ${retryCount} times for ${unitId} - manual intervention required. Task plan ${tid} is still missing after regenerating the slice plan. Fix the task-plan files manually, then run /gsd auto to resume.`,
+            level: "error",
+          };
+        }
+        session?.missingTaskPlanRetryCount?.set(unitId, retryCount + 1);
         if (isDebugEnabled()) {
           const expectedTaskPlanPath = join(artifactBasePath, relTaskFile(artifactBasePath, mid, sid, tid, "PLAN"));
           const originalProjectRoot = session?.originalBasePath || basePath;
@@ -1585,7 +1597,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
         return {
           action: "dispatch",
           unitType: "plan-slice",
-          unitId: `${mid}/${sid}`,
+          unitId,
           prompt: await buildPlanSlicePrompt(
             mid,
             midTitle,
@@ -1598,6 +1610,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
         };
       }
 
+      session?.missingTaskPlanRetryCount?.delete(unitId);
       return null;
     },
   },

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -17,7 +17,7 @@ import {
   resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
   resolveTasksDir, resolveTaskFiles, resolveTaskFile,
   relMilestoneFile, relSliceFile, relSlicePath, relMilestonePath,
-  resolveGsdRootFile, relGsdRootFile, resolveRuntimeFile,
+  relTaskFile, resolveGsdRootFile, relGsdRootFile, resolveRuntimeFile,
 } from "./paths.js";
 import { resolveInlineLevel, loadEffectiveGSDPreferences } from "./preferences.js";
 import { isContextModeEnabled } from "./preferences-types.js";
@@ -2662,7 +2662,7 @@ export async function buildExecuteTaskPrompt(
 
   const taskPlanPath = resolveTaskFile(base, mid, sid, tid, "PLAN");
   const taskPlanContent = taskPlanPath ? await loadFile(taskPlanPath) : null;
-  const taskPlanRelPath = relSlicePath(base, mid, sid) + `/tasks/${tid}-PLAN.md`;
+  const taskPlanRelPath = relTaskFile(base, mid, sid, tid, "PLAN");
   const taskPlanContext = taskPlanContent
     ? [
       "## Inlined Task Plan (authoritative local execution contract)",
@@ -3901,7 +3901,7 @@ export async function buildReactiveExecutePrompt(
 
     const taskPlanPath = resolveTaskFile(base, mid, sid, tid, "PLAN");
     const taskPlanContent = taskPlanPath ? await loadFile(taskPlanPath) : null;
-    const taskPlanRelPath = `${relSlicePath(base, mid, sid)}/tasks/${tid}-PLAN.md`;
+    const taskPlanRelPath = relTaskFile(base, mid, sid, tid, "PLAN");
     const taskPlanInline = taskPlanContent
       ? [
           "## Inlined Task Plan (authoritative local execution contract)",

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -35,7 +35,7 @@ import { isValidationTerminal } from "./state.js";
 import { getErrorMessage } from "./error-utils.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readIntegrationBranch } from "./git-service.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, isInactiveStatus } from "./status-guards.js";
 import {
   resolveSlicePath,
   resolveSliceFile,
@@ -295,7 +295,7 @@ export function writeReactiveExecuteBlocker(
   transaction(() => {
     for (const tid of summaryPresent) {
       const task = getTask(mid, sid, tid);
-      if (!task || isClosedStatus(task.status)) {
+      if (!task || isInactiveStatus(task.status)) {
         unchangedTaskIds.push(tid);
         continue;
       }
@@ -304,7 +304,7 @@ export function writeReactiveExecuteBlocker(
     }
     for (const tid of summaryMissing) {
       const task = getTask(mid, sid, tid);
-      if (!task || isClosedStatus(task.status)) {
+      if (!task || isInactiveStatus(task.status)) {
         unchangedTaskIds.push(tid);
         continue;
       }

package/src/resources/extensions/gsd/auto.ts

@@ -97,8 +97,10 @@ import {
   getNewBudgetAlertLevel,
   getBudgetEnforcementAction,
   getContextPauseAction,
+  HARD_CONTEXT_REROOT_THRESHOLD_PERCENT,
   resolveCompactionThresholdPercent,
   shouldRerootStepSessionForContext,
+  shouldWarnStepSessionForContext,
 } from "./auto-budget.js";
 import {
   markToolStart as _markToolStart,
@@ -701,6 +703,7 @@ export {
   getContextPauseAction,
   resolveCompactionThresholdPercent,
   shouldRerootStepSessionForContext,
+  shouldWarnStepSessionForContext,
 } from "./auto-budget.js";
 
 function closeOutSignalInterruptedUnit(currentBasePath: string): void {
@@ -1375,9 +1378,10 @@ export async function rerootCommandSession(
 }
 
 /**
- * After a completed step-mode unit, reclaim context headroom when usage is at
- * or above the compaction threshold. Writes a context-mode snapshot first, then
- * re-roots the visible command session while leaving the NEXT progress surface.
+ * After a completed step-mode unit, warn when usage reaches the configurable
+ * soft context threshold. At the fixed hard boundary, write a context-mode
+ * snapshot and re-root the visible command session while leaving the NEXT
+ * progress surface.
  */
 export async function maybeRerootStepSessionForHighContext(
   ctx: ExtensionContext,
@@ -1392,7 +1396,19 @@ export async function maybeRerootStepSessionForHighContext(
   const prefs = loadEffectiveGSDPreferences(workspaceRoot);
   const compactionThreshold = prefs?.preferences.context_management?.compaction_threshold_percent;
 
-  if (!shouldRerootStepSessionForContext(contextPercent, compactionThreshold)) {
+  const shouldWarn = shouldWarnStepSessionForContext(contextPercent, compactionThreshold);
+  const shouldReroot = shouldRerootStepSessionForContext(contextPercent);
+  if (!shouldWarn && !shouldReroot) {
+    return { rerooted: false };
+  }
+
+  const displayPercent = (contextPercent as number).toFixed(1);
+  const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
+  if (!shouldReroot) {
+    ctx.ui.notify(
+      `Step complete — context at ${displayPercent}% (soft threshold: ${thresholdDisplay}%). Use /compact when convenient; continuing in this session is still safe.`,
+      "info",
+    );
     return { rerooted: false };
   }
 
@@ -1401,12 +1417,10 @@ export async function maybeRerootStepSessionForHighContext(
   const { writeContextModeCompactionSnapshot } = await import("./context-mode-snapshot.js");
   await writeContextModeCompactionSnapshot(snapshotBase);
 
-  const displayPercent = (contextPercent as number).toFixed(1);
-  const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
   const result = await rerootCommandSession(cmdCtx, workspaceRoot);
   if (result.status === "ok") {
     ctx.ui.notify(
-      `Step complete — context at ${displayPercent}% (threshold: ${thresholdDisplay}%). Fresh session ready for /gsd next.`,
+      `Step complete — context at ${displayPercent}% (hard threshold: ${HARD_CONTEXT_REROOT_THRESHOLD_PERCENT}%). Fresh session ready for /gsd next.`,
       "info",
     );
     return { rerooted: true };
@@ -2102,7 +2116,7 @@ export function _selectStopAutoWorktreeExit(args: {
 /**
  * Pause auto-mode without destroying state. Context is preserved.
  * The user can interact with the agent, then `/gsd auto` resumes
- * from disk state. Called when the user presses Escape during auto-mode.
+ * from disk state. Called when the user presses Escape or runs `/gsd pause`.
  */
 export async function pauseAuto(
   ctx?: ExtensionContext,
@@ -2129,6 +2143,7 @@ export async function pauseAuto(
 
   s.active = false;
   s.paused = true;
+  if (options.abortActiveTurn && ctx && !ctx.isIdle()) ctx.abort();
   clearUnitTimeout();
   stopAutoCommandPolling();
 

package/src/resources/extensions/gsd/bootstrap/core-session-tools.ts

@@ -28,6 +28,7 @@ const NON_REPEATABLE_FROM_MINIMAL_BASE = new Set<string>([
 
 /** Additional core tools not in MINIMAL_AUTO_BASE but routinely multi-called per turn. */
 const EXTRA_INHERENTLY_REPEATABLE = [
+  "gsd_exec",
   "multi_edit",
   "todo_write",
   "notebook_edit",

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

@@ -690,8 +690,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
     promptSnippet: "Plan a slice via DB write + PLAN render + cache invalidation",
     promptGuidelines: [
       "Use gsd_plan_slice for slice planning instead of writing S##-PLAN.md or task PLAN files directly.",
-      "Keep parameters flat and provide the full slice planning payload, including tasks.",
-      "The tool validates input, requires an existing parent slice, writes slice/task planning data, renders PLAN.md and task plan files from DB, and clears both state and parse caches after success.",
+      "For incremental planning, call gsd_plan_slice with slice metadata only, then call gsd_plan_task once per task.",
+      "When tasks is omitted or empty, the tool writes only slice planning metadata and preserves existing tasks.",
+      "When tasks is non-empty, the tool validates input, requires an existing parent slice, writes slice/task planning data, renders PLAN.md and task plan files from DB, and clears both state and parse caches after success.",
       "Use the canonical name gsd_plan_slice; gsd_slice_plan is only an alias.",
     ],
     parameters: Type.Object({
@@ -699,7 +700,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
       sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
       goal: Type.String({ description: "Slice goal" }),
-      tasks: Type.Array(Type.Object({
+      tasks: Type.Optional(Type.Array(Type.Object({
         taskId: Type.String({ description: "Task ID (e.g. T01)" }),
         title: Type.String({ description: "Task title" }),
         description: Type.String({ description: "Task description / steps block" }),
@@ -709,7 +710,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
         inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
         expectedOutput: Type.Array(Type.String(), { description: "Array<string> of files this task creates or overwrites; pass [\"path\"] or [], never prose or a single string" }),
         observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
-      }), { description: "Planned tasks for the slice" }),
+      }), { description: "Optional full task replacement for the slice. Omit for incremental planning, then call gsd_plan_task once per task." })),
       // ── Enrichment metadata (optional — defaults to empty) ────────────
       successCriteria: Type.Optional(Type.String({ description: "Slice success criteria block" })),
       proofLevel: Type.Optional(Type.String({ description: "Slice proof level" })),

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

@@ -18,6 +18,7 @@ import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
 import { logWarning, isGsdExtensionStderrEnabled } from "../workflow-logger.js";
 import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.js";
+import { installManifestFlushOnProcessTeardown } from "../workflow-manifest.js";
 // Static import so cmux event listeners are registered synchronously during
 // extension bootstrap. Prior implementation used `void import().then()` which
 // queued listener registration as a microtask — any CMUX_CHANNELS emit fired
@@ -196,6 +197,7 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
     });
 
   installEpipeGuard();
+  installManifestFlushOnProcessTeardown();
 
   // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
   // GSD-owned `before_agent_start` dispatch step (#3338).

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

@@ -34,7 +34,7 @@ import {
 } from "../auto-runtime-state.js";
 import { applyProviderPayloadPolicy } from "../provider-payload-policy.js";
 
-import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
+import { checkToolCallLoop, recordToolCallLoopMutation, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 import { maybePauseAutoForApprovalGate, resetPendingGatePauseGuard } from "./pending-gate-pause.js";
 import { saveActivityLog } from "../activity-log.js";
@@ -76,6 +76,7 @@ import { supportsSourceObservationsForUnit } from "../source-observations.js";
 import { clearPendingAutoStart } from "../pending-auto-start.js";
 import { resolveWorkflowToolBasePath } from "./dynamic-tools.js";
 import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.js";
+import { flushAllManifests } from "../workflow-manifest.js";
 
 let approvalQuestionAbortInFlight = false;
 
@@ -583,6 +584,21 @@ function contextBasePath(ctx?: { cwd?: string }): string {
   return typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd();
 }
 
+const LOOP_GUARD_INTERACTIVE_INSTRUCTIONS = [
+  "Do not retry this tool or call other tools this turn — stop and respond to the user in text.",
+  "Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.",
+];
+const LOOP_GUARD_AUTO_INSTRUCTION =
+  "Do not re-issue this blocked tool. In /gsd auto, stop tool calls for this turn and return control to the auto-mode recovery/replan path.";
+
+function formatLoopGuardBlockReason(reason: string | undefined): string | undefined {
+  if (!reason || !getAutoRuntimeSnapshot().active) return reason;
+  return LOOP_GUARD_INTERACTIVE_INSTRUCTIONS.reduce(
+    (formatted, instruction) => formatted.replace(instruction, LOOP_GUARD_AUTO_INSTRUCTION),
+    reason,
+  );
+}
+
 function beginSourceObservationStoreForCurrentUnit(
   ctx?: { cwd?: string },
 ): ReturnType<typeof getSourceObservationStore> | null {
@@ -1080,6 +1096,19 @@ export function registerHooks(
     const { handleAgentEnd } = await import("./agent-end-recovery.js");
     const agentEndBasePath = contextBasePath(ctx);
     try {
+      // The manifest is a non-critical projection (the append-only event log is
+      // the authoritative recovery source), so a flush failure must not skip
+      // agent_end recovery. drainManifestWrites still propagates write failures
+      // to explicit flush callers; here we deliberately log and continue so
+      // handleAgentEnd (and the finally below) always run.
+      try {
+        await flushAllManifests();
+      } catch (err) {
+        safetyLogWarning(
+          "manifest",
+          `flushAllManifests on agent_end failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
       await handleAgentEnd(pi, event, ctx);
     } finally {
       activateDeferredApprovalGate(agentEndBasePath);
@@ -1286,7 +1315,7 @@ export function registerHooks(
     // ── Loop guard: block repeated identical tool calls ──
     const loopCheck = checkToolCallLoop(toolName, event.input as Record<string, unknown>);
     if (loopCheck.block) {
-      return { block: true, reason: loopCheck.reason };
+      return { block: true, reason: formatLoopGuardBlockReason(loopCheck.reason) };
     }
 
     const deferredGateGuard = shouldBlockDeferredApprovalTool(
@@ -1558,6 +1587,7 @@ export function registerHooks(
       }
     }
     if (!event.isError) {
+      recordToolCallLoopMutation(toolName);
       refreshSourceObservationAfterMutation(toolName, event.input, ctx);
       clearSourceObservationsAfterShell(toolName);
     }

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

@@ -9,13 +9,14 @@
 
 import { test, describe, before, after } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { mkdtempSync, rmSync, existsSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import {
   markDepthVerified,
   loadWriteGateSnapshot,
+  shouldBlockContextArtifactSaveInSnapshot,
   clearDiscussionFlowState,
 } from "../write-gate.js";
 
@@ -100,4 +101,51 @@ describe("write-gate basePath regression", () => {
       "loadWriteGateSnapshot(baseDirB) must not bleed state from baseDirA",
     );
   });
+
+  test("worktree basePath reads depth verification from project-root snapshot", (t) => {
+    const prev = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    t.after(() => {
+      if (prev === undefined) {
+        delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+      } else {
+        process.env.GSD_PERSIST_WRITE_GATE_STATE = prev;
+      }
+    });
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
+
+    const projectRoot = makeTempDir();
+    const worktreePath = join(projectRoot, ".gsd-worktrees", "M020");
+    t.after(() => {
+      rmSync(projectRoot, { recursive: true, force: true });
+    });
+
+    clearDiscussionFlowState(projectRoot);
+    clearDiscussionFlowState(worktreePath);
+
+    // Simulate MCP routing: verification recorded at project root.
+    markDepthVerified("M020", projectRoot);
+
+    // Worktree has a local .gsd projection but no write-gate snapshot file.
+    mkdirSync(join(worktreePath, ".gsd", "runtime"), { recursive: true });
+    mkdirSync(join(projectRoot, ".gsd", "milestones"), { recursive: true });
+
+    const projectSnapshotPath = join(projectRoot, ".gsd", "runtime", "write-gate-state.json");
+    const worktreeSnapshotPath = join(worktreePath, ".gsd", "runtime", "write-gate-state.json");
+    assert.ok(existsSync(projectSnapshotPath), "verification snapshot lives at project root");
+    assert.ok(!existsSync(worktreeSnapshotPath), "worktree must not have its own snapshot file");
+
+    const snapshotFromWorktree = loadWriteGateSnapshot(worktreePath);
+    assert.ok(
+      snapshotFromWorktree.verifiedDepthMilestones.includes("M020"),
+      "loadWriteGateSnapshot(worktree) must inherit project-root verification",
+    );
+
+    const guard = shouldBlockContextArtifactSaveInSnapshot(
+      snapshotFromWorktree,
+      "CONTEXT",
+      "M020",
+      null,
+    );
+    assert.equal(guard.block, false, "CONTEXT save must unblock once project-root gate is verified");
+  });
 });

package/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts

@@ -14,10 +14,12 @@
  * to stop tooling for the rest of that turn and answer in text.
  *
  * The per-tool-name check (#783 Brief C) tracks call counts within a
- * turn regardless of args. This catches improvisation
+ * turn regardless of args, decaying after successful state-mutating tools.
+ * This catches improvisation
  * loops where the model attempts the same missing workflow tool through
  * varied surfaces (bash → `node -e` → CLI), each with a different
- * signature, so the identical-args streak never trips. Whichever guard
+ * signature, so the identical-args streak never trips, while allowing
+ * tool-heavy turns that are making file-mutation progress. Whichever guard
  * trips first blocks.
  */
 
@@ -42,6 +44,8 @@ const MAX_CONSECUTIVE_STRICT = 1;
  */
 const PER_TOOL_DEFAULT_CAP = 6;
 const PER_TOOL_REPEATABLE_CAP = 15;
+const PER_TOOL_CAP_EXEMPT_TOOLS = new Set(["find", "glob", "grep", "ls", "read", "search_and_read"]);
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
 
 let consecutiveCount = 0;
 let lastSignature = "";
@@ -50,6 +54,8 @@ let enabled = true;
 
 /** Per-tool-name call counts within the current turn (#783 Brief C). */
 const perToolCounts = new Map<string, number>();
+let mutationEpoch = 0;
+const perToolLastMutationEpoch = new Map<string, number>();
 
 /** Hash tool name + args into a compact signature for comparison. */
 function hashToolCall(toolName: string, args: Record<string, unknown>): string {
@@ -77,7 +83,8 @@ function hashToolCall(toolName: string, args: Record<string, unknown>): string {
  *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
  *     ask_user_questions).
  *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
- *     independent of args — catches improvisation loops (#783).
+ *     independent of args, reset after file-mutation progress — catches
+ *     improvisation loops (#783).
  */
 export function checkToolCallLoop(
   toolName: string,
@@ -114,8 +121,20 @@ export function checkToolCallLoop(
   // ── Guard 2: per-tool-name cap, independent of args (#783 Brief C) ──
   // Catches improvisation loops where the same tool is invoked many times with
   // varied args (e.g. retrying a missing workflow tool via bash/node -e/CLI).
-  const perToolCount = (perToolCounts.get(toolName) ?? 0) + 1;
+  const priorPerToolCount =
+    (perToolLastMutationEpoch.get(toolName) ?? mutationEpoch) < mutationEpoch
+      ? 0
+      : (perToolCounts.get(toolName) ?? 0);
+  const perToolCount = priorPerToolCount + 1;
   perToolCounts.set(toolName, perToolCount);
+  perToolLastMutationEpoch.set(toolName, mutationEpoch);
+
+  // Read-only navigation tools are normal context gathering; Guard 1 still
+  // catches true reread loops with identical arguments.
+  if (PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName)) {
+    return { block: false, count: consecutiveCount };
+  }
+
   const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
     ? PER_TOOL_REPEATABLE_CAP
     : PER_TOOL_DEFAULT_CAP;
@@ -135,6 +154,13 @@ export function checkToolCallLoop(
   return { block: false, count: consecutiveCount };
 }
 
+/** Record successful mutation progress so Guard 2 can decay on the next count. */
+export function recordToolCallLoopMutation(toolName: string): void {
+  if (!enabled) return;
+  if (!STATE_MUTATING_TOOL_SET.has(toolName)) return;
+  mutationEpoch++;
+}
+
 /** Reset the guard state. Call at agent turn boundaries. */
 export function resetToolCallLoopGuard(): void {
   consecutiveCount = 0;
@@ -142,6 +168,8 @@ export function resetToolCallLoopGuard(): void {
   lastToolName = "";
   enabled = true;
   perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Disable the guard (e.g. during shutdown). */
@@ -151,6 +179,8 @@ export function disableToolCallLoopGuard(): void {
   lastSignature = "";
   lastToolName = "";
   perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Get current consecutive count for diagnostics. */