jeo-code 0.12.25 → 0.12.27

package/CHANGELOG.md

@@ -9,6 +9,26 @@ The README mirrors the latest 5 entries — regenerate with `bun run changelog:s
 
 ## [Unreleased]
 
+## [0.12.27] - 2026-11-06
+
+### Fixed
+- **A stale managed container no longer blocks every sandbox launch** - `validateManagedRoots` inspects every labelled container, including exited ones, and canonicalized each bind source. A leaked container whose temp workspace had been deleted made `realpath` throw `ENOENT`, so every later launch failed with that opaque error. A vanished source (`ENOENT`, `ENOTDIR`) now resolves through its nearest existing ancestor (lexically for `ENOTDIR`) for the overlap check, which stays enforced; `EACCES`, `ELOOP` and invalid metadata still fail closed.
+- **An unlistable directory or an unhashable fresh file no longer makes the whole workspace snapshot inconclusive** - a non-root directory that cannot be listed is recorded as `u:<rel>:<mode>:<ctimeNs>:<ino>` and its children skipped (a `chmod` or any entry change in it still flips the digest); a fresh file over the racy byte caps, unopenable or changed while read is recorded by its stat fingerprint plus `:x`. Both count in the new `degraded` field. An unreadable root and the entry and time caps still fail the snapshot. Residual risk, documented in the header: rewriting an existing child's content inside a write-only directory with no `chmod` and no entry change is not detected.
+
+### Changed
+- **The done gate recognizes far more real verification commands** - `parseVerifier` accepts `bash -c`, `time`, quoted arguments, `cd "x y" &&`, package-manager flags (`pnpm -r`, `--filter`, `--prefix`, `--cwd`, `yarn workspace`), `make ci|verify`, gradle, mvn, dotnet, rspec, phpunit, playwright and the silent linters ruff, mypy, flake8, golangci-lint, staticcheck, `prettier --check` and `cargo fmt --check`. Direct forms are trusted on tool success. Weak forms whose exit status is not the verifier's own (`| tail`, bare `| tee`, `|| true`, `; echo x`, `set -e;`, `cd x;`, a subshell) count only for test runners, and only with a positive pass summary, no failure marker anywhere in the output and the trailing `echo` text discounted. `make`, `mvn`, `gradle`, `rake` and `dotnet` accept only allow-listed targets, so `make ci deploy` is not a verifier. A direct run that reports zero tests (`0 pass`, `# pass 0`, `Tests run: 0`, `collected 0 items`) is no longer evidence.
+- **A shell call from a shared scratch directory is bracketed on the project it works in** - from `$HOME`, `/` or a system temp dir, `cd <project> && sed -i ...`, or a `cwd`/`subdir` argument naming a project, is measured on the project root (the outermost directory with a `.git`, `package.json`, `Cargo.toml`, ... marker below any scratch root, so `cd app/pkg && echo x > ../src/a.ts` measures `app`) instead of being skipped, so a real unverified edit made that way blocks `done`. If that root cannot be measured BEFORE the call (over the entry or time cap), the call is skipped with one notice, as before, so a big or busy directory such as `/opt/homebrew` never blocks a read-only turn; if it is measurable before but not after, the call counts as a change. Unmeasured by design: a project over the 50k-entry cap (or one inflated earlier in the turn by a call that was not bracketed, such as a recognized `make build`), and a small project nested under a larger marker root. The transcript records `workspace.target` (relative to the cwd, `<outside cwd>` otherwise).
+
+## [0.12.26] - 2026-11-06
+
+### Fixed
+- **A read-only turn is no longer sent through three full-history retries by an unrelated writer** - the done gate counts a `bash` call as a file change when the workspace digest differs before and after it. In a shared directory (`/tmp`) a daemon heartbeat rewritten every 60 s during a 120 s `find /` flipped that digest, so a turn of `pwd`/`jeo-skill doctor` ended `UNVERIFIED` after three correction rounds (226k input tokens for `sleep 70`; the same prompt in an empty directory cost 32k). Three changes: (1) when the cwd *is* a shared scratch root (`$HOME`, `/`, a system temp dir) `bash` and `computer` calls are no longer snapshot-bracketed - the diff there cannot be attributed to one call and no project verifier exists - with one notice and `workspace: { mutation: false, skipped: "scratch" }` on the result; built-in `write`/`edit` and project directories nested inside a scratch root stay gated; (2) evidence that comes only from a shell/computer bracket ("shell-only": no built-in mutator, debug, monitor or job ran) earns one correction instead of three, counted apart from todo/hook nudges, and launch's `onBeforeDone` restatement of the gate (`MUTATION_NUDGE_PREFIX`) no longer disables that cap; (3) a passing verification now also resets the definite-mutation evidence, so a later unrelated write is judged as shell-only again. Re-run with an unrelated writer in a nested project dir: one correction, 47.8k tokens.
+
+### Changed
+- **The done gate names the paths a shell call changed** - a snapshot mismatch is diffed per path (`snapshotChangedPaths`, `formatSnapshotChange`; the snapshot now keeps a relative-path to fingerprint map, digest arithmetic unchanged) and the unverified / stale-verification messages say `the host saw these paths change: modified heartbeat.json`, so the user and model can tell the command's writes from someone else's. The note no longer suggests that replying "read-only" can clear the gate - only a passing verification does - and `workspace snapshot inconclusive` notices and `done deferred` counters show the effective limit (`1/1`).
+- **Transcripts record the workspace evidence** - each bash/computer tool result persists `workspace: { mutation, changed?, inconclusive?, skipped? }` in the session (never sent to a provider), so a rejected completion can be audited from the transcript; before, 1,221 sessions could not show which call latched the mutation flag.
+- `formatRejectedCompletion` pluralizes (`after 1 correction.`).
+
 ## [0.12.25] - 2026-11-06
 
 ### Changed
@@ -2762,7 +2782,8 @@ _Initial release._
 ### Added
 - Initial jeo-code agent and CLI.
 
-[Unreleased]: https://github.com/akillness/jeo-code/compare/v0.12.25...HEAD
+[Unreleased]: https://github.com/akillness/jeo-code/compare/v0.12.26...HEAD
+[0.12.26]: https://github.com/akillness/jeo-code/releases/tag/v0.12.26
 [0.12.25]: https://github.com/akillness/jeo-code/releases/tag/v0.12.25
 [0.12.24]: https://github.com/akillness/jeo-code/releases/tag/v0.12.24
 [0.12.23]: https://github.com/akillness/jeo-code/releases/tag/v0.12.23

package/README.ja.md

@@ -462,10 +462,10 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.27]** (2026-11-06)
+- **[0.12.26]** (2026-11-06)
 - **[0.12.25]** (2026-11-06)
 - **[0.12.24]** (2026-11-06)
-- **[0.12.23]** (2026-11-06)
-- **[0.12.22]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -517,10 +517,10 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.27]** (2026-11-06)
+- **[0.12.26]** (2026-11-06)
 - **[0.12.25]** (2026-11-06)
 - **[0.12.24]** (2026-11-06)
-- **[0.12.23]** (2026-11-06)
-- **[0.12.22]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -506,10 +506,10 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.27]** (2026-11-06)
+- **[0.12.26]** (2026-11-06)
 - **[0.12.25]** (2026-11-06)
 - **[0.12.24]** (2026-11-06)
-- **[0.12.23]** (2026-11-06)
-- **[0.12.22]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -460,10 +460,10 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
 - **[Unreleased]**
+- **[0.12.27]** (2026-11-06)
+- **[0.12.26]** (2026-11-06)
 - **[0.12.25]** (2026-11-06)
 - **[0.12.24]** (2026-11-06)
-- **[0.12.23]** (2026-11-06)
-- **[0.12.22]** (2026-11-04)
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.12.25",
+  "version": "0.12.27",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
 

package/src/agent/AGENTS.md

@@ -29,8 +29,9 @@ The core runtime loop, tool registry, session management, and state persistence
 | `hooks.ts` | Command-hook runtime: `loadHooks` (user registry `~/.jeo/hooks.json` ⊕ `config.json`/project `.jeo/hooks.json`, with the `hooks.enabled=false` kill switch and project `enabled:false` opt-out; the registry is skipped in sandboxed sessions), `runPreToolHooks` (veto by exit code or structured `permissionDecision`, `additionalContext` passthrough), `runPostTurnHooksForBatch`, `runPostImplementationHooks`, and the per-turn `runPrePromptHooks` (context injected by `commands/launch.ts` into the prompt message) / `runTurnEndHooks` (final reply to ingesters); payloads follow the Claude hook protocol on the host (`hook_event_name`, `session_id`, `cwd`, `tool_name`/`tool_input`) and stay legacy-shaped in a sandbox |
 | `json.ts` | Brief description of purpose |
 | `loop.ts` | The primary execution loop orchestrating model calls and tool execution |
-| `loop-guards.ts` | Intermediate-judgment classification (gjc ultragoal-guard parity): named `GuardState` taxonomy, `GUARD_LIMITS` thresholds, and pure classifiers (`verifierCores`/`isVerificationSignal` — recognizes wrapped verifiers such as `cd x && bun test`, env/`timeout`/`uv run`/`rtk` prefixes and `2>&1`, never pipes or `;` — `repeatHint`, `classifyDoneGate` incl. `done_stale_verification`, and `formatRejectedCompletion`, which keeps the last candidate answer under an `UNVERIFIED` marker when corrections are exhausted) consumed by `engine.ts` |
-| `workspace-snapshot.ts` | Host-side workspace fingerprint (`snapshotWorkspace`, `defaultWorkspaceSnapshotter`, `workspaceSnapshotChanged`): bounded lstat walk excluding `.git`/`.jeo`/`node_modules`, racy content hash for files modified near the bracket anchor; the engine brackets non-verifier `bash` and state-affecting `computer` calls with it so only a real workspace change counts as a mutation (snapshot error or cap counts as a mutation) |
+| `loop-guards.ts` | Intermediate-judgment classification (gjc ultragoal-guard parity): named `GuardState` taxonomy, `GUARD_LIMITS` thresholds, and pure classifiers (`verifierCores`/`isVerificationSignal` — `parseVerifier` recognizes wrapped verifiers such as `cd x && bun test`, `bash -c`, env/`timeout`/`time`/`uv run`/`rtk` prefixes and `2>&1`; direct forms are trusted on tool success, while weak forms whose exit status is not the verifier's own (`| tail`, bare `| tee`, `|| true`, `; echo x`, `set -e;`, `cd x;`, a subshell) count only for test runners and only with a positive pass summary, no failure marker anywhere in the output and the trailing `echo` text discounted; `make`/`mvn`/`gradle`/`rake` accept only allow-listed targets — `repeatHint`, `classifyDoneGate` incl. `done_stale_verification`, and `formatRejectedCompletion`, which keeps the last candidate answer under an `UNVERIFIED` marker when corrections are exhausted) consumed by `engine.ts` |
+| `workspace-snapshot.ts` | Host-side workspace fingerprint (`snapshotWorkspace`, `defaultWorkspaceSnapshotter`, `workspaceSnapshotChanged`): bounded lstat walk excluding `.git`/`.jeo`/`node_modules`, racy content hash for files modified near the bracket anchor; the engine brackets non-verifier `bash` and state-affecting `computer` calls with it so only a real workspace change counts as a mutation (snapshot error or cap counts as a mutation); an unlistable non-root directory (`u:<rel>:<mode>:<ctimeNs>:<ino>`) or a racy file that cannot be hashed (stat fingerprint plus `:x`) degrades to a marker and is counted in `degraded` instead of failing the snapshot; an ok snapshot keeps a relative-path fingerprint map (`snapshotChangedPaths`/`formatSnapshotChange` name what changed) and `isSharedScratchRoot` marks `$HOME`, `/` and system temp dirs where `bash`/`computer` calls are not bracketed unless `snapshot-target.ts` finds a nested project |
+| `snapshot-target.ts` | `snapshotTarget`/`describeSnapshotTarget`: for a `bash` call from a shared scratch cwd, resolves the project directory the call works in (`args.cwd`/`args.subdir`, then a leading literal `cd <path> &&`/`;`, up to 8 hops) and returns it only when it has a project marker (`.git`, `package.json`, `Cargo.toml`, …) below any scratch root; the engine brackets that directory and fails OPEN (skipped, one notice) when it cannot be measured, so a big or busy directory never blocks a turn |
 | `memory.ts` | OKF concept-bundle memory: session distill, query-aware budget injection with a **hybrid reranker ported from memsearch** — `priorityOrder` fuses two ranked channels via `reciprocalRankFusion` (RRF, k=60): lexical IDF relevance (`buildCorpusStats`/`scoreConcept`, the sparse/BM25 channel so rare discriminating terms steer retrieval) ⊕ graph proximity (`graphProximityOrder`, the local dense/semantic-neighbour channel — a hub linked from multiple query hits surfaces even with no keyword of its own); all embedding-free, deterministic, atop the failure-first tier + pinned-invariant reserved budget. Plus mid-loop `recordFailedAttempt` capture, shared `upsertConceptFile` writer, legacy MEMORY.md migration (`migrateLegacyMemory`) + `JEO_MEMORY_LEGACY` rollback toggle |
 | `memory-okf.ts` | OKF v0.1 format layer: frontmatter parse/serialize, concept IDs, conformance validation |
 | `memory-graph.ts` | Concept cross-link graph: build/expand (1-hop search), broken-link-tolerant lint, optional graphify detection |

package/src/agent/engine.ts

@@ -32,8 +32,12 @@ import { StepBudget, dynamicStepBudgetConfig, resolveStepBudgetConfig, hashSigna
 
 import { historyTokens, trimToolResultsInPlace, stripReasoningArtifactsInPlace } from "./compaction";
 import { jeoEnv } from "../util/env";
-import { GUARD_LIMITS, isVerificationSignal, verificationProducedEvidence, repeatHint, classifyDoneGate, formatRejectedCompletion } from "./loop-guards";
-import { defaultWorkspaceSnapshotter, workspaceSnapshotChanged, type WorkspaceSnapshot, type WorkspaceSnapshotter } from "./workspace-snapshot";
+import { GUARD_LIMITS, MUTATION_NUDGE_PREFIX, isVerificationSignal, verificationProducedEvidence, repeatHint, classifyDoneGate, formatRejectedCompletion } from "./loop-guards";
+import {
+  defaultWorkspaceSnapshotter, formatSnapshotChange, isSharedScratchRoot, snapshotChangedPaths, workspaceSnapshotChanged,
+  type WorkspaceSnapshot, type WorkspaceSnapshotter,
+} from "./workspace-snapshot";
+import { describeSnapshotTarget, snapshotTarget, snapshotTargetLabel } from "./snapshot-target";
 import { stripLeakedReasoningTags } from "../ai/think-tags";
 
 const MID_TASK_PROSE_RE =
@@ -411,6 +415,9 @@ export interface AgentLoopOptions {
   /** Host-side workspace fingerprint used to decide whether a bash/computer call mutated the
    *  workspace. Defaults to defaultWorkspaceSnapshotter; tests inject fakes. */
   workspaceSnapshot?: WorkspaceSnapshotter;
+  /** Directories treated as shared scratch roots (default: `$HOME`, `/`, system temp dirs). Where the cwd IS one of
+   *  these, bash/computer calls are not snapshot-bracketed. Tests inject a hermetic root instead of touching `$TMPDIR`. */
+  scratchRoots?: readonly string[];
   signal?: AbortSignal;
   events?: AgentLoopEvents;
   /** Step-budget overrides (gjc-style retry flow). `{ maxExtensions: 0 }` restores the
@@ -546,9 +553,13 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
   }
   const tools = opts.tools ?? DEFAULT_TOOLS;
   const snapshotter: WorkspaceSnapshotter = opts.workspaceSnapshot ?? defaultWorkspaceSnapshotter;
-  // Turn-scoped memo: once the workspace is over the snapshot cap, gated calls count as
-  // mutations without re-walking a tree that is known to be too large.
-  let snapshotCapped = false;
+  // Turn-scoped memo, keyed per bracketed directory, so one oversized directory never poisons the measurement of the
+  // cwd or of another target. For the cwd any cap is remembered (gated calls count as mutations without re-walking a
+  // tree known to be too large). For a NESTED target only a cap seen on the BEFORE side is remembered: that directory
+  // was already unmeasurable before the call ran, so nothing in it is attributable. An AFTER-side cap is never
+  // remembered, because it may have been this very call's files that pushed the tree over the cap — a later small
+  // write in the same directory must still be judged on its own, not skipped by that memo.
+  const cappedDirs = new Set<string>();
   // Why a bash/computer bracket could not be measured (cap or error), when one failed. The call still
   // counts as a possible mutation, but the user and the done gate are told the real reason instead of
   // only "files were modified" — a busy or oversized cwd (e.g. $HOME, /tmp) looks identical otherwise.
@@ -563,21 +574,54 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
     }
     return snap;
   };
-  const takeSnapshot = async (racySinceMs?: number): Promise<WorkspaceSnapshot> => {
-    if (snapshotCapped) return { ok: false, reason: "cap", detail: "workspace exceeded the snapshot cap earlier this turn" };
+  // A BEFORE-side failure on a NESTED target is returned as-is (not noted as unmeasured): the bracket then fails open
+  // for it, because before nested targeting those calls were skipped as scratch, and a read-only `cd ~/.cache && ls`
+  // must not start counting as a mutation just because that directory is big or busy. An AFTER-side failure is noted
+  // like the cwd's: the directory WAS measurable a moment ago, so files appeared during the call (fail-safe).
+  // Exception: a directory this turn already made unmeasurable (`grownDirs`, an after-side failure with a good before)
+  // never fails open again — it was this session's own writes that inflated it, so a later call there (even after a
+  // passing verification) must not be waved through just because the tree is now too big to measure.
+  const grownDirs = new Set<string>();
+  const takeSnapshot = async (dir: string, side: "before" | "after", racySinceMs?: number): Promise<WorkspaceSnapshot> => {
+    const nested = dir !== cwd;
+    const failOpen = nested && side === "before" && !grownDirs.has(dir);
+    const memoApplies = !nested || side === "before";
+    if (memoApplies && cappedDirs.has(dir)) {
+      const memo: WorkspaceSnapshot = { ok: false, reason: "cap", detail: "workspace exceeded the snapshot cap earlier this turn" };
+      return nested && !failOpen ? noteUnmeasured(memo) : memo;
+    }
     try {
-      const snap = await snapshotter(cwd, racySinceMs);
-      if (!snap.ok && snap.reason === "cap") snapshotCapped = true;
-      return noteUnmeasured(snap);
+      const snap = await snapshotter(dir, racySinceMs);
+      if (memoApplies && !snap.ok && snap.reason === "cap") cappedDirs.add(dir);
+      return failOpen ? snap : noteUnmeasured(snap);
     } catch (err) {
-      return noteUnmeasured({ ok: false, reason: "error", detail: err instanceof Error ? err.message : String(err) });
+      const failure: WorkspaceSnapshot = { ok: false, reason: "error", detail: err instanceof Error ? err.message : String(err) };
+      return failOpen ? failure : noteUnmeasured(failure);
     }
   };
+  const unmeasurableNested = new Set<string>();
   // bash/computer calls whose mutation status is decided by a workspace diff. Recognized
   // verifiers are never mutations, and observe-only computer actions are read-only.
-  const snapshotGated = (tool: string, args: Record<string, any> | undefined): boolean =>
+  // A shared scratch root ($HOME, /, the system temp dir) is written by unrelated processes (daemon heartbeats,
+  // logs, other agents) and holds no project verifier, so a snapshot diff there cannot be attributed to one shell
+  // call: bash and computer calls are not bracketed (a built-in write/edit still counts as a definite mutation).
+  // The one exception is a bash call whose literal target (`cd ~/work/app && …`, a `cwd`/`subdir` argument) is a
+  // project (it, or an ancestor below the scratch root, holds a marker such as `.git`/`package.json`) nested under
+  // the scratch cwd: `snapshotTarget` names the outermost such project root and the bracket measures THAT directory,
+  // so an edit made through a scratch cwd (even from a subdirectory, `cd app/pkg && echo X > ../src/a.ts`) is not
+  // invisible. If that root was already unmeasurable BEFORE the call it is skipped like scratch (fail open); one that
+  // becomes unmeasurable DURING the call counts as a mutation. A project directory used as cwd stays gated as
+  // before, and there an unmeasurable bracket counts as a mutation.
+  const scratchCwd = isSharedScratchRoot(cwd, opts.scratchRoots);
+  let scratchNoted = false;
+  const snapshotCandidate = (tool: string, args: Record<string, any> | undefined): boolean =>
     (tool === "bash" && !isVerificationSignal(String(args?.command ?? args?.cmd ?? ""))) ||
     (tool === "computer" && computerActionMayAffectState(args));
+  // Mutation evidence that came ONLY from a shell/computer snapshot bracket, kept apart from definite mutators
+  // (write/edit/eval/…): an unrelated writer in the cwd is indistinguishable from the command's own writes, so a
+  // shell-only block gets one correction (naming the paths) instead of the full budget.
+  let definiteMutation = false;
+  const shellChanges: string[] = [];
   const sandbox = currentSandboxExecution();
   const parentTools: Record<string, true> = { task: true, subagent: true, irc: true, todo: true, sandbox_request: true };
   const maxSteps = opts.maxSteps ?? 15;
@@ -703,6 +747,9 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
   let verificationCycles = 0;
   let completionGraceUsed = false;
   let doneCorrections = 0;
+  // Corrections spent on a shell-only block, counted apart so an earlier todo/hook nudge cannot use up the one
+  // correction that names the changed paths.
+  let shellOnlyCorrections = 0;
   // Most recent non-empty completion candidate, kept so an exhausted gate still shows it.
   let lastCompletionCandidate = "";
   // F1 (round 4): the run-command of the most recent post-turn hook FAILURE whose
@@ -1219,11 +1266,23 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       };
       const candidate = stripLeakedReasoningTags(String(toolCalls[0].arguments?.reason ?? ""));
       if (candidate.trim()) lastCompletionCandidate = candidate;
-      const doneGate = classifyDoneGate({ ...evidence, pendingHookFailure, unmeasured: unmeasuredSnapshot ?? undefined });
+      const doneGate = classifyDoneGate({
+        ...evidence,
+        pendingHookFailure,
+        unmeasured: unmeasuredSnapshot ?? undefined,
+        shellChanged: !definiteMutation && shellChanges.length ? shellChanges.slice(-3).join(" | ") : undefined,
+      });
       const nudge = await ev.onBeforeDone?.((toolCalls[0].arguments?.reason as string) ?? "", evidence);
-      const rejection = [doneGate.block ? doneGate.message : "", nudge].filter(Boolean).join("\n\n");
+      // launch's onBeforeDone restates the mutation gate in its own words when the gate blocks; the engine's message
+      // names the paths, so the restatement is dropped and does not count as an independent reason to keep going.
+      const independentNudge = nudge && !(doneGate.block && nudge.startsWith(MUTATION_NUDGE_PREFIX)) ? nudge : "";
+      const rejection = [doneGate.block ? doneGate.message : "", independentNudge].filter(Boolean).join("\n\n");
       if (rejection) {
-        if (doneCorrections >= GUARD_LIMITS.MAX_DONE_CORRECTIONS) {
+        // Shell-only evidence (no built-in mutator succeeded) cannot tell the command's writes from an unrelated
+        // process's, so it earns one correction naming the paths; every other block keeps the full budget.
+        const shellOnlyBlock = doneGate.block && doneGate.state !== "done_hook_failing" && !definiteMutation && !independentNudge;
+        const correctionLimit = shellOnlyBlock ? GUARD_LIMITS.MAX_SHELL_ONLY_DONE_CORRECTIONS : GUARD_LIMITS.MAX_DONE_CORRECTIONS;
+        if (shellOnlyBlock ? shellOnlyCorrections >= correctionLimit : doneCorrections >= correctionLimit) {
           return finish({
             done: false,
             steps: step,
@@ -1232,9 +1291,10 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
           });
         }
         doneCorrections++;
+        if (shellOnlyBlock) shellOnlyCorrections++;
         pushAssistantTurn(history, responseText, reasonBuf, artifactBuf);
         history.push({ role: "user", content: rejection });
-        ev.onNotice?.(`done deferred — completion correction ${doneCorrections}/${GUARD_LIMITS.MAX_DONE_CORRECTIONS}`);
+        ev.onNotice?.(`done deferred — completion correction ${shellOnlyBlock ? shellOnlyCorrections : doneCorrections}/${correctionLimit}`);
         step++;
         continue;
       }
@@ -1371,6 +1431,8 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       let output: string;
       let images: import("../ai/types").ImageAttachment[] | undefined;
       let mutationMayHaveOccurred: boolean | undefined;
+      let workspace: import("../ai/types").ToolResultRecord["workspace"];
+      let bracketed = false;
       if (tool === "done") {
         success = false;
         output = "Error: 'done' can only be called as the single tool invocation, not in a batch. Please send 'done' alone.";
@@ -1393,8 +1455,23 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
             success = false;
             output = preHookResult.error + (preHookResult.output ? `\n${preHookResult.output}` : "");
           } else {
+            // Which directory this call's bracket measures. Undefined = skip: a scratch cwd with no resolvable
+            // nested project target (`snapshotTarget` returns `cwd` itself exactly when it found none).
+            let bracketDir: string | undefined;
+            if (snapshotCandidate(tool, args)) {
+              const dir = scratchCwd ? snapshotTarget(cwd, tool, args, opts.scratchRoots) : cwd;
+              if (scratchCwd && dir === cwd) {
+                workspace = { mutation: false, skipped: "scratch" };
+                if (!scratchNoted) {
+                  scratchNoted = true;
+                  ev.onNotice?.(`cwd ${cwd} is a shared scratch directory: shell and computer calls here are not checked for file changes`);
+                }
+              } else {
+                bracketDir = dir;
+              }
+            }
             // Taken after pre-tool hooks so hook writes are never attributed to the call.
-            const before = snapshotGated(tool, args) ? await takeSnapshot() : undefined;
+            const before = bracketDir !== undefined ? await takeSnapshot(bracketDir, "before") : undefined;
             try {
               const onProgress = ev.onToolProgress ? (partial: string) => ev.onToolProgress!(tool, partial) : undefined;
               const sandboxedHandler = sandbox && !Object.hasOwn(parentTools, tool) && !SANDBOX_MEDIATED_TOOLS.has(handler)
@@ -1419,11 +1496,36 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
                 ((tool === "monitor" || tool === "job") && String(args?.action ?? "").trim().toLowerCase() === "start");
               if (explicitSignal || knownMutatingCall) mutationMayHaveOccurred = true;
             }
-            if (before) {
+            if (before && bracketDir !== undefined) {
               // bash/computer: the workspace diff is the sole mutation authority (overrides
               // handler flags and the catch heuristic). Both sides share one racy anchor so
               // an unchanged recently-modified file is hashed on both sides or neither.
-              mutationMayHaveOccurred = before.ok ? workspaceSnapshotChanged(before, await takeSnapshot(before.startedAtMs)) : true;
+              const after = before.ok ? await takeSnapshot(bracketDir, "after", before.startedAtMs) : undefined;
+              const failed = !before.ok ? before : after && !after.ok ? after : undefined;
+              const nested = bracketDir !== cwd;
+              if (nested && after && !after.ok) grownDirs.add(bracketDir);
+              if (nested && !before.ok && !grownDirs.has(bracketDir)) {
+                // Fail open ONLY when the nested target was already unmeasurable BEFORE the call (cap, time cap,
+                // error): nothing in it is attributable, and it behaves like today's scratch skip so a big read-only
+                // directory cannot block a finished answer. A failing AFTER snapshot (before was ok) falls through
+                // below and counts as a mutation: files appeared during the call.
+                workspace = { mutation: false, skipped: "scratch", target: describeSnapshotTarget(cwd, bracketDir) };
+                if (!unmeasurableNested.has(bracketDir)) {
+                  unmeasurableNested.add(bracketDir);
+                  ev.onNotice?.(`nested target ${snapshotTargetLabel(cwd, bracketDir)} could not be measured; treated as scratch`);
+                }
+              } else {
+                mutationMayHaveOccurred = after ? workspaceSnapshotChanged(before, after) : true;
+                bracketed = true;
+                const change = after ? snapshotChangedPaths(before, after) : null;
+                workspace = {
+                  mutation: mutationMayHaveOccurred,
+                  // Paths stay relative to the bracketed directory; `target` says which directory that was.
+                  ...(mutationMayHaveOccurred && change ? { changed: formatSnapshotChange(change) } : {}),
+                  ...(failed && !failed.ok ? { inconclusive: `${failed.reason}: ${failed.detail}` } : {}),
+                  ...(nested ? { target: describeSnapshotTarget(cwd, bracketDir) } : {}),
+                };
+              }
             }
             // A pre-tool hook's structured `additionalContext` rides along with the result
             // so the model sees it next to the output it concerns.
@@ -1431,7 +1533,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
           }
         }
       }
-      return { success, output, images, mutationMayHaveOccurred };
+      return { success, output, images, mutationMayHaveOccurred, bracketed, workspace };
     };
 
     const WRITE_TOOLS = new Set(["write", "edit"]);
@@ -1474,7 +1576,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       }
     }
 
-    const results: { success: boolean; output: string; executed: boolean; images?: import("../ai/types").ImageAttachment[]; mutationMayHaveOccurred?: boolean }[] = Array.from(
+    const results: { success: boolean; output: string; executed: boolean; images?: import("../ai/types").ImageAttachment[]; mutationMayHaveOccurred?: boolean; bracketed?: boolean; workspace?: import("../ai/types").ToolResultRecord["workspace"] }[] = Array.from(
       { length: toolCalls.length },
       () => ({ success: false, output: "", executed: false })
     );
@@ -1563,6 +1665,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         id: idFor(idx),
         output: bodies[i],
         isError: !results[idx].success,
+        ...(results[idx].workspace ? { workspace: results[idx].workspace } : {}),
       }));
       pushAssistantTurn(history, responseText, reasonBuf, artifactBuf, toolUse);
       const resultMsg: Message = { role: "user", content: resultBlocks.join("\n\n"), toolResults };
@@ -1607,11 +1710,16 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         if (results[i].success && verificationProducedEvidence(command, String(results[i].output ?? ""))) {
           sawVerification = true;
           lastVerificationSeq = ++mutVerSeq;
-          if (!pendingHookFailure) doneCorrections = 0;
+          // A passing verification supersedes the evidence before it: what happens next is judged on its own.
+          definiteMutation = false;
+          shellChanges.length = 0;
+          unmeasuredSnapshot = null;
+          if (!pendingHookFailure) { doneCorrections = 0; shellOnlyCorrections = 0; }
         } else {
           sawVerification = false;
           if (results[i].mutationMayHaveOccurred === true) {
             sawMutation = true;
+            definiteMutation = true; // a verifier is never snapshot-bracketed: this flag came from the handler itself
             lastMutationSeq = ++mutVerSeq;
           }
         }
@@ -1619,6 +1727,7 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
       }
       if (t === "todo" && results[i].success && doneCorrections > 0 && (!sawMutation || (sawVerification && lastMutationSeq < lastVerificationSeq)) && !pendingHookFailure) {
         doneCorrections = 0;
+        shellOnlyCorrections = 0;
       }
 
       const output = String(results[i].output ?? "").trim();
@@ -1638,19 +1747,28 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
         if (results[i].success || results[i].mutationMayHaveOccurred === true) {
           sawMutation = true;
           lastMutationSeq = ++mutVerSeq;
+          if (results[i].bracketed !== true) definiteMutation = true;
+          else if (results[i].workspace?.changed) {
+            const w = results[i].workspace!;
+            // A nested bracket's paths are relative to that directory, so the gate message names it.
+            shellChanges.push(w.target ? `${w.changed} (in ${w.target})` : w.changed!);
+          }
         }
       } else if (t === "debug" && MUTATING_DEBUG_ACTIONS[String(toolCalls[i].arguments?.action ?? "")] === true) {
         sawMutation = true;
+        definiteMutation = true;
         lastMutationSeq = ++mutVerSeq;
       } else if (t === "monitor" && String(toolCalls[i].arguments?.action ?? "").trim().toLowerCase() === "start") {
         // Starting a background monitor can mutate the workspace asynchronously;
         // read-only monitor controls (list/tail/await/cancel) do not invalidate verification.
         sawMutation = true;
+        definiteMutation = true;
         lastMutationSeq = ++mutVerSeq;
       } else if (t === "job" && String(toolCalls[i].arguments?.action ?? "").trim().toLowerCase() === "start") {
         // Starting a background shell may mutate the workspace asynchronously;
         // read-only job controls (list/tail/await/cancel) do not invalidate verification.
         sawMutation = true;
+        definiteMutation = true;
         lastMutationSeq = ++mutVerSeq;
       }
     }