@opengsd/gsd-core 1.16.0 → 1.17.0

package/gsd-core/bin/lib/verification.cjs

@@ -258,6 +258,11 @@ function reportStatusOf(fm, filePath) {
  * too): it re-runs the verifier, which regenerates VERIFICATION.md and its
  * digest (#4682, #4887).
  */
+/**
+ * The one remedy for a stale report (#4682 / #5118), shared by the route table and by the more specific
+ * diagnostic below so the two cannot drift: only re-running the verifier regenerates VERIFICATION.md.
+ */
+const STALE_REMEDY = 'Re-run execute-phase for this phase: it resumes at the verification gates and re-runs the verifier, regenerating VERIFICATION.md and its digest. verify-work alone cannot refresh a stale report.';
 const VERIFICATION_ROUTES = Object.freeze({
     passed: Object.freeze({
         next_action: 'Verification passed — continue.',
@@ -279,7 +284,7 @@ const VERIFICATION_ROUTES = Object.freeze({
     stale: Object.freeze({
         // #4682 / #5118: the only remedy for a stale report is re-running the
         // verifier; /gsd-verify-work on its own never rewrites VERIFICATION.md.
-        next_action: 'Verification is stale — covered source files changed after the verifier last ran. Re-run execute-phase for this phase: it resumes at the verification gates and re-runs the verifier, regenerating VERIFICATION.md and its digest. verify-work alone cannot refresh a stale report.',
+        next_action: `Verification is stale — covered source files changed after the verifier last ran. ${STALE_REMEDY}`,
         command: 'execute-phase',
         tail: '',
     }),
@@ -540,7 +545,7 @@ function phaseArtifactPaths(phaseDir, projectRoot) {
     const scan = scanPhasePlans(phaseDir);
     // Fail closed on a non-COMPLETE scan (unreadable phase dir, or an
     // unreadable nested plans/ dir) — a partial scan's invisible contents can
-    // never be proven covered (mirrors allCurrentArtifactsCovered's own
+    // never be proven covered (mirrors uncoveredCurrentArtifacts's own
     // fail-closed contract).
     if (scan.scope !== SCOPE.COMPLETE) {
         return { ok: false, reason: `phase directory scan is incomplete (scope: ${scan.scope}): ${phaseDir}` };
@@ -849,9 +854,9 @@ function computeCoveredDigest(projectRoot, coveredFiles, version = FINGERPRINT_V
  * each is represented in `coveredFiles` — matched by suffix (mirrors
  * `matchRequestedFile`'s convention) since `coveredFiles` holds
  * project-root-relative paths while the scan returns phase-relative
- * filenames. Returns `true` if every current plan/summary is covered,
- * `false` otherwise — callers only ever branch on this pass/fail, so no
- * caller needs which artifact was uncovered.
+ * filenames. Returns the current plans/summaries the report never declared
+ * (empty when every one is covered), so the stale diagnostic can name them (#4817); `null` when the
+ * scan itself was incomplete, which callers treat as stale.
  *
  * Fails CLOSED on an incomplete scan: `scanPhasePlans` never throws on a
  * readdir failure — it reports it via `scope` (`SCOPE.UNREADABLE` for the
@@ -860,18 +865,18 @@ function computeCoveredDigest(projectRoot, coveredFiles, version = FINGERPRINT_V
  * contract (`planning-scope.cts`): zero items under a non-`COMPLETE` scope
  * is a NON-answer, never "this phase has no plans." Branching on `scope`
  * here (rather than a try/catch, which this scan never triggers) is what
- * makes an unreadable `plans/` dir report `false` instead of silently
+ * makes an unreadable `plans/` dir report `null` (stale) instead of silently
  * treating its invisible contents as vacuously covered — the same
  * fail-open regression #3057 B3 fixed for the legacy path.
  */
-function allCurrentArtifactsCovered(phaseDir, coveredFiles) {
+function uncoveredCurrentArtifacts(phaseDir, coveredFiles) {
     const scan = scanPhasePlans(phaseDir);
     if (scan.scope !== SCOPE.COMPLETE)
-        return false;
+        return null;
     const coveredPosix = canonicalizeCoveredFiles(coveredFiles);
-    return [...scan.allPlanFiles, ...scan.summaryFiles].every((artifact) => {
+    return [...scan.allPlanFiles, ...scan.summaryFiles].filter((artifact) => {
         const artifactPosix = toPosix(artifact);
-        return coveredPosix.some((c) => c === artifactPosix || c.endsWith(`/${artifactPosix}`));
+        return !coveredPosix.some((c) => c === artifactPosix || c.endsWith(`/${artifactPosix}`));
     });
 }
 /**
@@ -943,6 +948,73 @@ function defaultPhaseCleanCommitTimesMs(phaseDir, files, execGitFn = shell_comma
     }
     return commitTimes;
 }
+/**
+ * #4857: which declared covered files changed since the report was written.
+ * `covered_digest` is one aggregate hash, so it can say THAT something moved
+ * but not what; this names the files by time instead — each covered file
+ * (report paths and, for v2+, shared planning documents excluded, exactly as
+ * the digest excludes them) whose clean commit time, or mtime when it is
+ * uncommitted or edited since, is newer than the report's own. A file that
+ * can no longer be statted counts as moved. Advisory only: it never decides
+ * staleness (the digest does), and an unreadable clock yields fewer names,
+ * never a wrong status. Timed through the same injectable resolver the
+ * legacy mtime check uses, rooted at the project so the covered paths
+ * (project-root-relative) resolve.
+ */
+function coveredFilesMovedSinceReport(projectRoot, phaseDir, reportPath, coveredFiles, version, fsImpl, resolver) {
+    const sharedRoots = version >= 2 ? sharedRootsFor(projectRoot, phaseDir, null) : [];
+    const files = canonicalizeCoveredFiles(coveredFiles, { version })
+        .filter((f) => !isVerificationReportPath(f) && !isSharedPlanningDoc(f, sharedRoots));
+    if (files.length === 0)
+        return [];
+    const reportRel = toPosix(node_path_1.default.relative(projectRoot, reportPath));
+    let commitTimes;
+    try {
+        commitTimes = resolver(projectRoot, [reportRel, ...files]);
+    }
+    catch {
+        commitTimes = new Map();
+    }
+    const timeOf = (rel) => {
+        const committed = commitTimes.get(rel);
+        if (committed !== undefined)
+            return committed;
+        try {
+            return fsImpl.statSync(node_path_1.default.join(projectRoot, rel)).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+    };
+    const reportTime = timeOf(reportRel);
+    if (reportTime === null)
+        return [];
+    return files.filter((rel) => {
+        const t = timeOf(rel);
+        return t === null || t > reportTime;
+    });
+}
+/** At most this many uncovered artifact names are spelled out in `next_action`; the rest are counted. */
+const STALE_NAMED_ARTIFACT_LIMIT = 5;
+function staleNextAction(detail) {
+    const name = (items) => {
+        const shown = items.slice(0, STALE_NAMED_ARTIFACT_LIMIT).map((a) => io.formatDiagnosticToken(a));
+        const more = items.length - shown.length;
+        return `${shown.join(', ')}${more > 0 ? ` and ${more} more` : ''}`;
+    };
+    const reasons = [];
+    if (detail.moved.length > 0) {
+        reasons.push(`covered source files changed after the verifier last ran: ${name(detail.moved)}`);
+    }
+    else if (detail.digestMoved) {
+        reasons.push('covered source files changed after the verifier last ran');
+    }
+    if (detail.uncovered.length > 0) {
+        reasons.push(`the report never covered ${name(detail.uncovered)} (a current phase plan or summary it did not declare in covered_files)`);
+    }
+    const tail = detail.digestMoved ? '' : '; no covered file changed';
+    return `Verification is stale — ${reasons.join(', and ')}${tail}. ${STALE_REMEDY}`;
+}
 /**
  * The one result builder (#5118): every `VerificationStatusResult` is
  * projected from `VERIFICATION_ROUTES[status]` here — `route` (the bare
@@ -951,12 +1023,18 @@ function defaultPhaseCleanCommitTimesMs(phaseDir, files, execGitFn = shell_comma
  */
 function routeResult(status, ctx) {
     const entry = VERIFICATION_ROUTES[status];
+    const detail = status === VERIFICATION_STATUS.STALE && ctx.staleDetail
+        && (ctx.staleDetail.uncovered.length > 0 || ctx.staleDetail.moved.length > 0)
+        ? ctx.staleDetail
+        : undefined;
     return {
         status,
-        next_action: entry.next_action,
+        next_action: detail ? staleNextAction(detail) : entry.next_action,
         next_command: projectNextCommand(entry.command, ctx.runtime, `${ctx.phaseArg}${entry.tail}`),
         route: entry.command,
         ...(ctx.message !== undefined ? { message: ctx.message } : {}),
+        ...(detail && detail.uncovered.length > 0 ? { uncovered_artifacts: detail.uncovered } : {}),
+        ...(detail && detail.moved.length > 0 ? { moved_files: detail.moved } : {}),
         ...(ctx.staleCheckIndeterminate ? { staleCheckIndeterminate: true } : {}),
     };
 }
@@ -1396,12 +1474,13 @@ function readVerificationStatus(phaseDir, opts = {}) {
         typeof coveredDigestVal === 'string' &&
         coveredDigestVal.trim().length > 0;
     let staleCheckIndeterminate = false;
+    let staleDetail;
     let isStale;
     if (declaresFingerprint) {
         // Stated directly rather than relying on `null !== coveredDigestVal`
         // being true whenever the pair is malformed: `!hasWellFormedFingerprint`
         // fails closed explicitly, and its `||` short-circuit means
-        // computeCoveredDigest/allCurrentArtifactsCovered never run on a
+        // computeCoveredDigest/uncoveredCurrentArtifacts never run on a
         // malformed (wrong-shaped) `coveredFilesVal`. The two `||`s after it
         // short-circuit in turn: the live-directory re-scan (for a plan/summary
         // added AFTER verification and never declared in covered_files) only
@@ -1423,17 +1502,28 @@ function readVerificationStatus(phaseDir, opts = {}) {
             // #5095 (R1): v3's digest is computed over the declared set UNIONED
             // with the phase's own live artifacts — a plan/summary added after
             // fingerprinting already moves the digest itself, so the separate
-            // live-directory re-scan (`allCurrentArtifactsCovered`) is redundant
+            // live-directory re-scan (`uncoveredCurrentArtifacts`) is redundant
             // for v3 and is not run.
             isStale =
                 computeCoveredDigest(projectRoot, coveredFilesVal, storedVersion, { phaseDir }) !== coveredDigestVal;
+            if (isStale) {
+                const moved = coveredFilesMovedSinceReport(projectRoot, phaseDir, located.filePath, coveredFilesVal, storedVersion, fsImpl, phaseCleanCommitTimesMs);
+                if (moved.length > 0)
+                    staleDetail = { uncovered: [], moved, digestMoved: true };
+            }
         }
         else {
             // v1/v2: unchanged — the digest alone cannot see a plan/summary that
             // was never declared, so the live-directory re-scan still runs.
-            isStale =
-                computeCoveredDigest(projectRoot, coveredFilesVal, storedVersion, { phaseDir }) !== coveredDigestVal ||
-                    !allCurrentArtifactsCovered(phaseDir, coveredFilesVal);
+            const digestMoved = computeCoveredDigest(projectRoot, coveredFilesVal, storedVersion, { phaseDir }) !== coveredDigestVal;
+            const uncovered = uncoveredCurrentArtifacts(phaseDir, coveredFilesVal);
+            isStale = digestMoved || uncovered === null || uncovered.length > 0;
+            const moved = digestMoved
+                ? coveredFilesMovedSinceReport(projectRoot, phaseDir, located.filePath, coveredFilesVal, storedVersion, fsImpl, phaseCleanCommitTimesMs)
+                : [];
+            if ((uncovered !== null && uncovered.length > 0) || moved.length > 0) {
+                staleDetail = { uncovered: uncovered ? [...uncovered].sort() : [], moved, digestMoved };
+            }
         }
     }
     else {
@@ -1449,7 +1539,7 @@ function readVerificationStatus(phaseDir, opts = {}) {
     if (isStale) {
         // #4682 / #5118: the one stale route — execute-phase's verify_phase_goal
         // step re-runs the verifier, regenerating VERIFICATION.md and its digest.
-        return route(VERIFICATION_STATUS.STALE);
+        return route(VERIFICATION_STATUS.STALE, staleDetail ? { staleDetail } : {});
     }
     // 3. Route the writer-set member through the one table.
     return route(reportStatus, { staleCheckIndeterminate });

package/gsd-core/workflows/code-review.md

@@ -750,6 +750,19 @@ if [ -n "$FALLOW_JSON_PATH" ] && [ -f "$FALLOW_JSON_PATH" ]; then
 fi
 ```
 
+Gather the capability review rules addressed to this reviewer (#4790): active `contribution` hooks with `into: code-reviewer`,
+read from the loop point the review step is registered at (`workflow.code_review_point`, default `execute:post`). This is
+advisory by construction: any failure leaves the prompt without them and never blocks the review. The fragments are handed over once,
+below, beside — never instead of — `${AGENT_SKILLS_REVIEWER}`:
+```bash
+REVIEWER_POINT=$(gsd_run query config-get workflow.code_review_point --raw 2>/dev/null) || REVIEWER_POINT="execute:post"
+case "$REVIEWER_POINT" in execute:post|execute:wave:post) ;; *) REVIEWER_POINT="execute:post" ;; esac
+REVIEWER_HOOKS_JSON=$(gsd_run loop render-hooks "${REVIEWER_POINT}" --raw 2>/dev/null) || REVIEWER_HOOKS_JSON=""
+if [[ "$REVIEWER_HOOKS_JSON" == @file:* ]]; then REVIEWER_HOOKS_JSON=$(cat "${REVIEWER_HOOKS_JSON#@file:}" 2>/dev/null || true); fi
+# A literal closing tag inside a fragment is escaped so third-party text cannot end the block early.
+REVIEWER_CONTRIBUTIONS=$(printf '%s' "$REVIEWER_HOOKS_JSON" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const h=(JSON.parse(s).activeHooks||[]).filter(x=>x&&x.kind==="contribution"&&x.into==="code-reviewer"&&x.fragment&&typeof x.fragment.inline==="string"&&x.fragment.inline!=="").map(x=>x.fragment.inline.split("</capability_review_rules>").join("<\\/capability_review_rules>"));if(h.length)process.stdout.write("<capability_review_rules>\n"+h.join("\n\n")+"\n</capability_review_rules>")}catch(e){}})' 2>/dev/null || true)
+```
+
 Spawn the gsd-code-reviewer agent:
 
 Print: `◆ Spawning code reviewer... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
@@ -783,7 +796,9 @@ ${CONFIG_FILES}
 
 Review the listed source files at ${REVIEW_DEPTH} depth. Write findings to ${REVIEW_PATH}.
 Do NOT commit the output — the orchestrator handles that.
-${AGENT_SKILLS_REVIEWER}")
+${AGENT_SKILLS_REVIEWER}
+
+${REVIEWER_CONTRIBUTIONS}")
 ```
 
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.

package/gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md

@@ -340,7 +340,7 @@ fi
 
 `worktree create` records the entry in `$WAVE_WORKTREE_MANIFEST` itself, so **do not** call `worktree.record-agent` for these plans — that verb is the harness-path counterpart, used because the harness creates the worktree behind GSD's back. Double-recording is deduped by path+branch, but the create verb is the single writer here.
 
-Spawn `EXEC_JSON`'s `command` + `args` as a background process with its working directory set to `EXEC_JSON.cwd`, capturing the PID (`WORKER_PID=$!`) and redirecting stdout+stderr into a per-worker log placed BESIDE the worktree — `${WT_PATH}.worker.log`, not inside it: cleanup removes the worktree, and the log plus the lifecycle record must survive it. The `cwd` is returned for **every** host, including those whose descriptor has no cwd flag (`cwdFlag: null`) and therefore bind through the process's own working directory — always set it, never assume the flag did the job.
+Spawn `EXEC_JSON`'s `command` + `args` as a background process with its working directory set to `EXEC_JSON.cwd`, capturing the PID (`WORKER_PID=$!`) and redirecting stdout+stderr into a per-worker log placed BESIDE the worktree — `${WT_PATH}.worker.log`, not inside it: cleanup removes the worktree, and the log plus the lifecycle record must survive it. The `cwd` is returned for **every** host, including those whose descriptor has no cwd flag (`cwdFlag: null`) and therefore bind through the process's own working directory — always set it, never assume the flag did the job. Launch from a shell that has `cd`'d into it (`cd "$cwd" && command args &`), not from a process API that only sets the child's working directory: OpenCode 2.x resolves its directory from `$PWD` and ignores a bare cwd change, so a stale inherited `$PWD` would bind the worker to the main checkout.
 
 **Record the launch before any wait (#4624).** A bare background `wait` left the wave with no durable lifecycle: when the orchestrator's turn ended first, a finished worker sat undiscovered and a blocked one sat unreported, and a resumed session had nothing to recover from. Immediately after the spawn — before waiting on anything — persist the launch identity and result location:
 

package/gsd-core/workflows/execute-phase.md

@@ -1,7 +1,7 @@
 <!-- gsd:loop-host
 step: execute
 points: execute:pre, execute:wave:pre, execute:wave:post, execute:post
-agent-roles: executor, verifier
+agent-roles: executor, verifier, code-reviewer
 produces: SUMMARY.md
 consumes: PLAN.md
 -->
@@ -187,6 +187,8 @@ EXECUTE_POST_HOOKS_JSON=$(gsd_run loop render-hooks execute:post --raw)
 TDD_MODE=$(gsd_run loop render-hooks execute:post --active-cap tdd)
 ```
 
+A `contribution` hook at this point with `into: code-reviewer` (#4790) is not dispatched from this envelope: `code-review.md` reads it itself and hands it to `gsd-code-reviewer` exactly once.
+
 <step name="safe_resume_gate">
 Before trusting `STATE.md` or dispatching any executor, derive `CURRENT_PLAN_ID`
 from the active incomplete plan in `INIT`, then search recent history:

package/gsd-core/workflows/resume-project.md

@@ -75,21 +75,25 @@ shopt -s nullglob 2>/dev/null; setopt NULL_GLOB 2>/dev/null
 # Check for structured handoff (preferred — machine-readable)
 cat .planning/HANDOFF.json 2>/dev/null || true
 
-# Check for continue-here files (phase + non-phase + legacy fallback).
-# Use `find` rather than a chained `ls` of bare globs: under zsh's default
-# NOMATCH option (macOS default shell), a single non-matching glob aborts
-# the entire command during word-expansion — silently dropping every
-# pattern after the first miss, including `.planning/.continue-here*.md`.
-# `find` does not use shell glob expansion and tolerates absent
-# directories on both bash and zsh.
-find .planning -maxdepth 3 -name '.continue-here*.md' -print 2>/dev/null || true
-find . -maxdepth 1 -name '.continue-here*.md' -print 2>/dev/null || true
+# Check for continue-here files (phase + non-phase + legacy fallback), three levels below .planning.
+# Guarded glob loops, not `find` and not a chained `ls` of bare globs (#4805, #3689):
+#  - a chained `ls` of bare globs aborts under zsh's default NOMATCH on the first miss, silently
+#    dropping every pattern after it, including `.planning/.continue-here*.md` (#3689);
+#  - `find` is an external binary that allowlisted agent shells (an fd-only policy, for one) refuse, and a
+#    per-line `2>/dev/null || true` then hid the refusal, so a checkpoint on disk looked absent (#4805).
+# The shell alone does this: nullglob (set above) drops an unmatched glob, `[ -e ]` guards the shells that
+# keep it, and an absent directory simply matches nothing. Output is `.planning/...` and `./...` as before.
+for f in .planning/.continue-here*.md .planning/*/.continue-here*.md .planning/*/*/.continue-here*.md ./.continue-here*.md; do
+  if [ -e "$f" ]; then echo "$f"; fi
+done 2>/dev/null || true
 
 # Outstanding async external jobs (legal external_job_waiting half-state).
 # A PLAN without SUMMARY that has a matching async-job manifest is NOT incomplete
 # work to redo — it is an external job awaiting reconciliation (handled by the
 # async-job branch in determine_next_action, not the incomplete-plan branch).
-find .planning/async-jobs -maxdepth 1 -name '*.json' -print 2>/dev/null || true
+for f in .planning/async-jobs/*.json; do
+  if [ -e "$f" ]; then echo "$f"; fi
+done 2>/dev/null || true
 
 # Check for plans without summaries (incomplete execution)
 for plan in .planning/phases/*/*-PLAN.md; do

package/hooks/dist/gsd-check-update.js

@@ -67,26 +67,32 @@ const cacheFile = path.join(cacheDir, updateCacheFileName);
 const projectVersionFile = path.join(projectConfigDir, 'gsd-core', 'VERSION');
 const globalVersionFile = path.join(globalConfigDir, 'gsd-core', 'VERSION');
 
-// Ensure cache directory exists
-if (!fs.existsSync(cacheDir)) {
+// This background check is advisory. Cache or worker failures must not make
+// the SessionStart hook fail. Recursive mkdir is safe if another session
+// creates the directory concurrently.
+try {
   fs.mkdirSync(cacheDir, { recursive: true });
-}
 
-// Run check in background via a dedicated worker script.
-// Spawning a file (rather than node -e '<inline code>') keeps the worker logic
-// in plain JS with no template-literal regex-escaping concerns, and makes the
-// worker independently testable.
-const workerPath = path.join(__dirname, 'gsd-check-update-worker.js');
-const child = spawn(process.execPath, [workerPath], {
-  stdio: 'ignore',
-  windowsHide: true,
-  detached: true,  // Required on Windows for proper process detachment
-  env: {
-    ...process.env,
-    GSD_CACHE_FILE: cacheFile,
-    GSD_PROJECT_VERSION_FILE: projectVersionFile,
-    GSD_GLOBAL_VERSION_FILE: globalVersionFile,
-  },
-});
+  // Run check in background via a dedicated worker script.
+  // Spawning a file (rather than node -e '<inline code>') keeps the worker logic
+  // in plain JS with no template-literal regex-escaping concerns, and makes the
+  // worker independently testable.
+  const workerPath = path.join(__dirname, 'gsd-check-update-worker.js');
+  const child = spawn(process.execPath, [workerPath], {
+    stdio: 'ignore',
+    windowsHide: true,
+    detached: true,  // Required on Windows for proper process detachment
+    env: {
+      ...process.env,
+      GSD_CACHE_FILE: cacheFile,
+      GSD_PROJECT_VERSION_FILE: projectVersionFile,
+      GSD_GLOBAL_VERSION_FILE: globalVersionFile,
+    },
+  });
 
-child.unref();
+  // A spawn failure can also arrive asynchronously on the child process.
+  child.on('error', () => {});
+  child.unref();
+} catch {
+  // Update hints are best effort; a failed check must not interrupt startup.
+}

package/hooks/dist/gsd-context-monitor.js

@@ -14,6 +14,8 @@
 // Thresholds:
 //   WARNING  (remaining <= 35%): Agent should wrap up current task
 //   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+// "remaining" is of the auto-compact threshold — the statusline puts the
+// bridge on that scale (#4985), so both fire before Claude Code compacts.
 // Both fire-points are overridable per project via .planning/config.json
 // (hooks.context_warning_threshold / hooks.context_critical_threshold, #4285);
 // the values above are the defaults used when the keys are absent or unusable.
@@ -500,23 +502,30 @@ const handleStdinEnd = () => {
     }
 
     // Build advisory warning message (never use imperative commands that
-    // override user preferences — see #884)
+    // override user preferences — see #884). The percentages are of the
+    // auto-compact threshold (#4985); the token counts, when the bridge has
+    // them, are the ones /context shows (#2451).
+    const kTokens = n => `${Math.round(n / 1000)}k`;
+    const tokenDetail = Number.isFinite(metrics.used_tokens) && Number.isFinite(metrics.threshold_tokens)
+      ? ` (${kTokens(metrics.used_tokens)} of ${kTokens(metrics.threshold_tokens)} usable tokens)`
+      : '';
+    const usage = `Usage at ${usedPct}%${tokenDetail}. Remaining: ${remaining}%. `;
     let message;
     if (isCritical) {
       message = isGsdActive
-        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        ? `CONTEXT CRITICAL: ${usage}` +
           'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
           'GSD state is already tracked in STATE.md. Inform the user so they can run ' +
           '/gsd:pause-work at the next natural stopping point.'
-        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        : `CONTEXT CRITICAL: ${usage}` +
           'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
           'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';
     } else {
       message = isGsdActive
-        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        ? `CONTEXT WARNING: ${usage}` +
           'Context is getting limited. Avoid starting new complex work. If not between ' +
           'defined plan steps, inform the user so they can prepare to pause.'
-        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        : `CONTEXT WARNING: ${usage}` +
           'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
           'starting new complex work.';
     }

package/hooks/dist/gsd-secret-read-guard.js

@@ -103,9 +103,23 @@
 //   edit of `.env` lands in the link target — a write redirection, the
 //   out-of-scope write class, not a read.)
 //
+// A second, unrelated contract is enforced on the Bash leg because this is the
+// one hook that already parses EVERY Bash command (#5214): a Bash command that
+// launches the debugger as a CLI process — `claude … --agent gsd-debugger` — is
+// denied (`debugger-cli-spawn`). The debug session manager is required to spawn
+// gsd-debugger with `Agent(run_in_background=false)` so it can read the
+// debugger's structured return; on a captured 1.15.0 run it routed around that
+// literal and shelled out with the Bash parameter `run_in_background: true`,
+// so no return ever came back and the checkpoint never advanced. Prose in the
+// agent file cannot stop an improvised tool call; a PreToolUse denial can, and
+// Claude Code runs plugin hooks for a subagent's tool calls too. A person
+// running `claude --agent gsd-debugger` in their own terminal never reaches
+// this hook. Only the debugger is named: it is the agent whose blocking return
+// the managed debug loop depends on.
+//
 // Triggers on: Read, Grep, Bash tool calls (Kimi: ReadFile, Grep, Shell)
 // Action: BLOCK (decision: 'block', exit 2) — codes secret-read |
-//         glob-too-complex | command-too-large
+//         glob-too-complex | command-too-large | debugger-cli-spawn
 // No-op: other tools, non-secret targets, hook errors (fail open — a parser
 //        bug in a hook that runs on EVERY Bash call must never brick a
 //        session; the crash policy is declared once below).
@@ -1004,6 +1018,100 @@ function findSecretRead(command, depth) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// gsd-debugger CLI spawn scan (#5214)
+// ---------------------------------------------------------------------------
+
+const DEBUGGER_AGENT_NAME = 'gsd-debugger';
+const CLAUDE_BINARY_RE = /^claude(\.exe)?$/;
+
+// `gsd-debugger`, or a plugin-namespaced `<plugin>:gsd-debugger`.
+function isDebuggerAgent(value) {
+  return value.slice(value.lastIndexOf(':') + 1) === DEBUGGER_AGENT_NAME;
+}
+
+// `timeout [flags] DURATION cmd …` is not in CMD_PREFIXES because its first
+// operand is a duration, not the command. Returns the command that follows it.
+function unwrapTimeout(cmd) {
+  let { base, operands } = cmd;
+  while (base === 'timeout') {
+    let k = 0;
+    while (k < operands.length && operands[k].text.startsWith('-')) k++;
+    k++; // the DURATION operand
+    const rest = resolveCommand(operands.slice(k));
+    if (!rest) return null;
+    ({ base, operands } = rest);
+  }
+  return { base, operands };
+}
+
+// Returns the `--agent` value text of a debugger launch, or null.
+function findDebuggerCliSpawn(command, depth) {
+  const { tokens, nested } = tokenize(command);
+
+  for (const sub of nested) {
+    if (depth < MAX_NESTING_DEPTH) {
+      const hit = findDebuggerCliSpawn(sub, depth + 1);
+      if (hit) return hit;
+    }
+  }
+
+  const bySeg = new Map();
+  for (const t of tokens) {
+    if (t.kind !== 'word' && t.kind !== 'op') continue;
+    if (!bySeg.has(t.seg)) bySeg.set(t.seg, []);
+    bySeg.get(t.seg).push(t);
+  }
+
+  for (const segTokens of bySeg.values()) {
+    const words = [];
+    for (let k = 0; k < segTokens.length; k++) {
+      const t = segTokens[k];
+      if (t.kind === 'op') {
+        // A redirect consumes its target word; it is never the command.
+        if (!t.dup && segTokens[k + 1] && segTokens[k + 1].kind === 'word') k++;
+        continue;
+      }
+      words.push(t);
+    }
+    if (!words.length) continue;
+
+    const first = resolveCommand(words);
+    const cmd = first && unwrapTimeout(first);
+    if (!cmd) continue;
+    const { base, operands } = cmd;
+
+    if (base === 'eval') {
+      if (depth < MAX_NESTING_DEPTH) {
+        const hit = findDebuggerCliSpawn(operands.map((w) => w.text).join(' '), depth + 1);
+        if (hit) return hit;
+      }
+      continue;
+    }
+
+    if (SHELL_INTERPRETERS.has(base)) {
+      const cIdx = operands.findIndex((w) => DASH_C_RE.test(w.text));
+      if (cIdx !== -1 && operands[cIdx + 1] && depth < MAX_NESTING_DEPTH) {
+        const hit = findDebuggerCliSpawn(operands[cIdx + 1].text, depth + 1);
+        if (hit) return hit;
+      }
+      continue;
+    }
+
+    if (!CLAUDE_BINARY_RE.test(base)) continue;
+    for (let k = 0; k < operands.length; k++) {
+      const text = operands[k].text;
+      if (text === '--agent') {
+        const value = operands[k + 1];
+        if (value && isDebuggerAgent(value.text)) return value.text;
+      } else if (text.startsWith('--agent=') && isDebuggerAgent(text.slice('--agent='.length))) {
+        return text.slice('--agent='.length);
+      }
+    }
+  }
+  return null;
+}
+
 // A shell interpreter's script comes from `-c`, a file operand, or stdin.
 function scanShellInterpreter(operands, heredocs, hereStrings, s, bySeg, sepAfter, depth) {
   const cIdx = operands.findIndex((w) => DASH_C_RE.test(w.text));
@@ -1102,6 +1210,12 @@ function reasonFor(code, tool, target) {
     return `Secret read guard: the Grep glob '${target}' expands to more than ${MAX_GLOB_ALTERNATIVES} ` +
       'alternatives and cannot be checked for secret-file matches. Use a narrower glob.';
   }
+  if (code === 'debugger-cli-spawn') {
+    return `Debugger spawn guard: this Bash command launches the debugger as a CLI process ('--agent ${target}'). ` +
+      'A shell-spawned debugger runs detached, returns no structured result, and the debug checkpoint never advances. ' +
+      'Spawn it with the Agent tool instead: Agent(subagent_type="gsd-debugger", run_in_background=false, ...) ' +
+      'and wait for its structured return.';
+  }
   return `Secret read guard: ${tool} would read '${target}', which matches a protected secret-file ` +
     `pattern (${PATTERN_TEXT}). Secret values must not be read into the conversation. ` +
     'If you need a specific value, ask the user for it; if you need the variable NAMES, ' +
@@ -1253,6 +1367,8 @@ process.stdin.on('end', () => {
     if (command.length > MAX_COMMAND_LENGTH) emitBlock('command-too-large', tool, '');
     const hit = findSecretRead(command, 0);
     if (hit !== null) emitBlock('secret-read', tool, hit);
+    const spawn = findDebuggerCliSpawn(command, 0);
+    if (spawn !== null) emitBlock('debugger-cli-spawn', tool, spawn);
     allow(undefined);
   } catch {
     // Fail open — never block valid tool calls due to hook errors.