@sema-agent/core 7.15.0 → 7.17.0

package/dist/tools/fs/gh-rate-limit.d.ts

@@ -1,27 +1,26 @@
 /**
- * gh rate-limit hint (CC 2.1.198 parity — PARITY-SPOT-REMINDERS SR-2).
+ * gh rate-limit hint (CC 2.1.198 parity).
  *
  * CC appends a one-shot <system-reminder> to a FOREGROUND Bash result when a `gh` invocation hits the
- * GitHub API rate limit, so the model sleeps/schedules instead of hammering retries. Anchors:
- * pretty.js:281399-281404 (`Bxa` — the reminder text), :281472-281473 (`m0p` command gate + `f0p`
- * output gate, both ported verbatim), :281426 (`h0p` = 60s throttle), :335536 (attach point — background
- * tasks are never hinted). sema delta (recorded): CC's closing clause names its ScheduleWakeup tool;
- * sema's wait primitive is the Monitor tool, so the clause is adapted — everything else is verbatim.
+ * GitHub API rate limit, so the model sleeps/schedules instead of hammering retries. The command gate,
+ * output gate and 60s throttle below are ported verbatim; a detached/background task is never hinted.
+ * Registered delta: CC's closing clause names its ScheduleWakeup tool; sema's wait primitive is the
+ * Monitor tool, so that clause is adapted — everything else is verbatim.
  */
-/** Test seam: reset the process-wide throttle window (mirrors CC's module-level `Mxa`). */
+/** Test seam: reset the process-wide throttle window (mirrors CC's module-level timestamp). */
 export declare function resetGhRateLimitHintThrottleForTests(): void;
 /**
  * Returns the rate-limit reminder when `command` is a real gh call AND `output` shows a rate-limit
  * error AND the 60s throttle window is open; otherwise undefined. Callers attach it to FOREGROUND
  * Bash results only (CC gates on `backgroundTaskId` — a detached/background task is never hinted).
  *
- * `monitorToolActive` (#181-F6): the closing clause teaches the Monitor tool, but Monitor is mounted
- * by the Runner (`backgroundTaskToolsActive`), not by the Bash tool — under handsReadOnly or a
- * background-less env the taught tool is not on the roster. `false` drops exactly that clause (the
- * sleep-until-reset advice stays); absent/`true` keeps the historic full wording (RB-374① posture:
- * an uninformed caller gets the byte-identical sentence, never a silent rewrite).
+ * `monitorToolActive`: the closing clause teaches the Monitor tool, but Monitor is mounted by the
+ * Runner (`backgroundTaskToolsActive`), not by the Bash tool — under handsReadOnly or a background-less
+ * env the taught tool is not on the roster. `false` drops exactly that clause (the sleep-until-reset
+ * advice stays); absent/`true` keeps the full wording, so an uninformed caller gets the byte-identical
+ * sentence rather than a silent rewrite.
  *
- * design/319 (A ticket): `mark` — the session's reminder provenance mark, stamped on the open tag
- * by the mint home (body bytes unchanged; absent ⇒ historic bare tag).
+ * `mark`: the session's reminder provenance mark, stamped on the open tag by the mint home (body bytes
+ * unchanged; absent ⇒ bare tag).
  */
 export declare function ghRateLimitHint(command: string, output: string, now?: number, monitorToolActive?: boolean, mark?: string): string | undefined;

package/dist/tools/fs/index.d.ts

@@ -17,34 +17,34 @@ export * from "./read-face.js";
 import { type CwdRef, type ReadImageDownsamplerOption } from "./fs-shared.js";
 /** Options for {@link createHandsToolkit}. */
 export interface HandsToolkitOptions {
-    /** design/119 (CC --add-dir parity): extra allowed containment roots (canonical). Widens file-tool
-     *  containment only; the primary root keeps the cwd/base role. The full `bash` (effect:write) is NOT
-     *  constrained by these — it is deliberately unsandboxed and only uses them for its post-`cd`
-     *  disclosure note. RB-413: `bash_readonly` IS constrained by them (that face refuses a read outside
-     *  the roots), so widening here widens what the read-only band may read. */
+    /** CC --add-dir parity: extra allowed containment roots (canonical). Widens file-tool containment
+     *  only; the primary root keeps the cwd/base role. The full `bash` (effect:write) is NOT constrained
+     *  by these — it is deliberately unsandboxed and only uses them for its post-`cd` disclosure note.
+     *  `bash_readonly` IS constrained by them (that face refuses a read outside the roots), so widening
+     *  here widens what the read-only band may read. */
     additionalRoots?: readonly string[];
-    /** Ruled 2026-08-05 (read-boundary whitelist): extra allowed containment roots for the READ faces
-     *  only — read_file/grep/glob/repo_map and (RB-413) `bash_readonly` admit them; edit_file/
-     *  write_file/notebook_edit and the full `bash`'s disclosure roots deliberately do NOT (widening
-     *  reads must never silently widen writes). Caveat, same tradeoff RB-413 already states for
-     *  `additionalRoots`: `bash_readonly`'s COMMAND allowlist is a deployment declaration — a
+    /** The read-boundary whitelist: extra allowed containment roots for the READ faces only —
+     *  read_file/grep/glob/repo_map and `bash_readonly` admit them; edit_file/write_file/notebook_edit
+     *  and the full `bash`'s disclosure roots deliberately do NOT (widening reads must never silently
+     *  widen writes). Caveat, the same tradeoff `additionalRoots` states:
+     *  `bash_readonly`'s COMMAND allowlist is a deployment declaration — a
      *  deployment that puts a mutating command into `bashReadonlyAllow` has declared it read-safe,
      *  and that declaration applies inside every root, these included. Keep the allowlist genuinely
      *  non-mutating if these roots must stay read-only through the shell face too. */
     additionalReadRoots?: readonly string[];
     /** Mount a shell tool. Pass false for an env without a real shell (e.g. `StubExecutionEnv`) so a bash
-     *  tool that can only error never reaches the model (design/44 §9 S1). Default false. */
+     *  tool that can only error never reaches the model. Default false. */
     includeShell?: boolean;
-    /** Verifier read-only boundary (design/44 §6): mount ONLY effect:read hand tools — read_file/grep/glob
+    /** Verifier read-only boundary: mount ONLY effect:read hand tools — read_file/grep/glob
      *  (+ `bash_readonly` when `includeShell`). Drops edit_file/write_file and the full `bash`. Default false. */
     readOnly?: boolean;
     /** Override the `bash_readonly` command allowlist (default {@link BASH_READONLY_DEFAULT_ALLOW}). */
     bashReadonlyAllow?: readonly string[];
-    /** Commit-message attribution trailer for the `bash` git protocol (design/64 §8.1D). Default NONE
-     *  ([c209] BREAKING: attribution is a deployment identity asset — the branded scenario sets it);
-     *  pass `"Name <email>"` to advertise one, `false` (≡ unset) for no trailer section. */
+    /** Commit-message attribution trailer for the `bash` git protocol. Default NONE — attribution is a
+     *  deployment identity asset, so the branded deployment sets it; pass `"Name <email>"` to advertise
+     *  one, `false` (≡ unset) for no trailer section. */
     commitCoAuthor?: string | false;
-    /** design/99 §E13 — the caller's own {@link CwdRef} to track this task's logical cwd, instead of one
+    /** The caller's own {@link CwdRef} to track this task's logical cwd, instead of one
      *  created internally. The Runner passes its own so it can OBSERVE `cd` moves (`cwdRef.current` changes)
      *  and emit a `workspace_changed` event. Ignored in `readOnly` mode (no `cd`). Default: a fresh ref at root. */
     cwdRef?: CwdRef;
@@ -53,56 +53,55 @@ export interface HandsToolkitOptions {
     /** Runner-owned owner/scope fallback used when a tool execute context is unavailable in tests. */
     taskOwner?: string;
     taskScope?: string;
-    /** design/129 — see createBashTool's taskOpts.sessionId: session-resident background commands. */
+    /** See createBashTool's taskOpts.sessionId: session-resident background commands. */
     sessionId?: string;
     /** Mount TaskOutput/TaskStop directly from this band. Runner sets false and mounts the unified dispatcher once. */
     mountBackgroundTaskTools?: boolean;
-    /** design/116 §7 G2b: completion-notification sink for finished background commands (threaded to
-     *  createBashTool's onTaskNotification; the Runner wires the run-local injection lane here). */
+    /** Completion-notification sink for finished background commands (threaded to createBashTool's
+     *  onTaskNotification; the Runner wires the run-local injection lane here). */
     taskNotification?: (n: import("../../core/task-notification.js").TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
-    /** design/116 detach: the run-local per-tool-call detach hub (mid-flight ctrl+b → adopt as background). */
+    /** The run-local per-tool-call detach hub (mid-flight ctrl+b → adopt as background). */
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
-    /** RB-370 ② (cli): the Bash `timeout` parameter's DEFAULT budget, in ms — applied when the
-     *  model omits `timeout`. Resolution (options over env over constant — the standing sema discipline:
-     *  deployments configure the tool, not the process): this field ?? env `BASH_DEFAULT_TIMEOUT_MS` ??
-     *  120000; invalid (non-finite / <= 0) values are discarded at every leg. See
+    /** The Bash `timeout` parameter's DEFAULT budget, in ms — applied when the model omits `timeout`.
+     *  Resolution (options over env over constant — the standing sema discipline: deployments configure
+     *  the tool, not the process): this field ?? env `BASH_DEFAULT_TIMEOUT_MS` ?? 120000; invalid
+     *  (non-finite / <= 0) values are discarded at every leg. See
      *  {@link import("./fs-shared.js").resolveBashTimeoutCaps} — the SAME resolver renders the tool
-     *  description, so the advertised numbers always match the enforced ones. Additive: absent ⇒
-     *  byte-compat 120s. Applies to both shell legs (`bash` and `bash_readonly`). */
+     *  description, so the advertised numbers always match the enforced ones. Absent ⇒ 120s. Applies to
+     *  both shell legs (`bash` and `bash_readonly`). */
     bashDefaultTimeoutMs?: number;
-    /** RB-370 ② (cli): the Bash `timeout` parameter's engine CEILING, in ms — requests above it
-     *  are clamped (with the RB-370 requested/capped disclosure naming THIS value). Resolution: (this
-     *  field ?? env `BASH_MAX_TIMEOUT_MS` ?? 600000), then floored at the resolved default — CC's own
-     *  only-widen semantic: a ceiling below the default is a narrowing intent = invalid, ignored in
-     *  favor of the default. Additive: absent ⇒ byte-compat 600s. */
+    /** The Bash `timeout` parameter's engine CEILING, in ms — requests above it are clamped (the
+     *  requested/capped disclosure names THIS value). Resolution: (this field ?? env
+     *  `BASH_MAX_TIMEOUT_MS` ?? 600000), then floored at the resolved default — CC's own only-widen
+     *  semantic: a ceiling below the default is a narrowing intent = invalid, ignored in favor of the
+     *  default. Absent ⇒ 600s. */
     bashMaxTimeoutMs?: number;
     /** Structured sink for the timeout-cap discard announcements both shell legs emit at mount (see
      *  {@link import("../../core/types.js").EngineNotice} / `RunnerDeps.onNotice`). Wired, it REPLACES
      *  their `console.warn` line (a forwarding host must not show every fact twice); absent, the
-     *  console line prints verbatim (byte-compat loudness). Threaded per toolkit build — never a
+     *  console line prints verbatim (last-resort loudness). Threaded per toolkit build — never a
      *  global. */
     onNotice?: (n: import("../../core/types.js").EngineNotice) => void;
-    /** RB-220 — see createBashTool's taskOpts.oneShot / createTaskOutputTool's TaskToolOptions.oneShot for
-     *  the full contract: this run has no later turn for an async background notification to land in.
+    /** See createBashTool's taskOpts.oneShot / createTaskOutputTool's TaskToolOptions.oneShot for the
+     *  full contract: this run has no later turn for an async background notification to land in.
      *  Threaded to both the Bash background-launch receipt and (when this band mounts TaskOutput itself,
-     *  `mountBackgroundTaskTools: true`) the TaskOutput poll receipt. Absent ⇒ byte-compat (unbranched,
-     *  pre-RB-220 wording). */
+     *  `mountBackgroundTaskTools: true`) the TaskOutput poll receipt. Absent ⇒ the unbranched wording. */
     oneShot?: boolean;
-    /** RB-198 F1 (CC 220 `Zry`/`WZi.#m` parity): see createBashTool's taskOpts field of the same name for the
-     *  full contract. Threaded from {@link HandsBandOptions.autoBackgroundOnTimeout} (a deployment-level
-     *  opt-in) — NOT from `detachHub`/`taskRegistry` merely being present, which are wired unconditionally by
-     *  the Runner for every task and so cannot double as an opt-in signal. Default undefined ⇒ `false`
-     *  downstream (byte-compat: an omitted field changes nothing for any existing caller). */
+    /** CC `Zry`/`WZi.#m` parity: see createBashTool's taskOpts field of the same name for the full
+     *  contract. Threaded from {@link HandsBandOptions.autoBackgroundOnTimeout} (a deployment-level
+     *  opt-in) — NOT from `detachHub`/`taskRegistry` merely being present, which are wired unconditionally
+     *  by the Runner for every task and so cannot double as an opt-in signal. Default undefined ⇒ `false`
+     *  downstream. */
     autoBackgroundOnTimeout?: boolean;
-    /** 批③: Read-image downsampler seam ({@link ReadImageDownsamplerOption}). Default undefined = auto-detect
+    /** Read-image downsampler seam ({@link ReadImageDownsamplerOption}). Default undefined = auto-detect
      *  the optional sharp dependency once per process; `false` disables it (deterministic no-sharp behavior). */
     readImageDownsampler?: ReadImageDownsamplerOption;
-    /** PDF degradation chain v2: the SERVING model's PDF capability profile (prepare-task derives it via
+    /** PDF degradation chain: the SERVING model's PDF capability profile (prepare-task derives it via
      *  {@link import("./fs-pdf.js").pdfModelCapabilitiesOf}). A model without native document input gets pdftotext text extraction →
      *  rendered page images (vision) → an honest placeholder, instead of a brain-level placeholder. Default
-     *  undefined = fully capable (byte-compat: native document block). */
+     *  undefined = fully capable (native document block). */
     pdfModelCapabilities?: PdfModelCapabilities;
     /** Append the per-read content-safety reminder after a successful text read
      *  ({@link import("./fs-shared.js").readCyberReminderText}). Default TRUE — a BYOM deployment cannot
@@ -112,10 +111,10 @@ export interface HandsToolkitOptions {
      *  exemption gate the upstream 88 source had around the same mechanism (see readCyberReminderText's note
      *  for the full attribution). Absent ⇒ appended. */
     readCyberReminder?: boolean;
-    /** design/138 S2-C — write-time content gate for Write/Edit/NotebookEdit (see {@link BeforeWriteHook}).
-     *  The Runner wires the MemoryEngine's memory-domain scan here; absent ⇒ byte-identical behavior. */
+    /** Write-time content gate for Write/Edit/NotebookEdit (see {@link BeforeWriteHook}). The Runner
+     *  wires the MemoryEngine's memory-domain scan here; absent ⇒ byte-identical behavior. */
     beforeWrite?: BeforeWriteHook;
-    /** design/381 — first-touch file-history hook for Write/Edit/NotebookEdit (see
+    /** First-touch file-history hook for Write/Edit/NotebookEdit (see
      *  {@link TrackFileEditHook}): called after the content gates pass, immediately before the final
      *  env write, so the file's pre-edit state is durably recorded before it changes. The Runner
      *  wires it to `FileHistoryStore.trackEdit`; absent ⇒ byte-identical behavior (no history). */
@@ -126,54 +125,51 @@ export interface HandsToolkitOptions {
      *  Purely additive: it cannot refuse a write, and a fault in it is contained in both shapes (a
      *  synchronous throw and a rejected promise), neither of them awaited. */
     onFileEdited?: FileEditedHook;
-    /** #181-F6 — see createBashTool's taskOpts field of the same name: whether the Monitor tool is on
-     *  this run's roster (the Runner mounts Monitor, this band never does). `false` drops the gh
-     *  rate-limit hint's Monitor clause; absent ⇒ historic full wording (byte-compat). */
+    /** See createBashTool's taskOpts field of the same name: whether the Monitor tool is on this run's
+     *  roster (the Runner mounts Monitor, this band never does). `false` drops the gh rate-limit hint's
+     *  Monitor clause; absent ⇒ the full wording. */
     monitorToolActive?: boolean;
-    /** design/199 件B — ADDITIONS to the built-in sensitive-path READ deny set
+    /** ADDITIONS to the built-in sensitive-path READ deny set
      *  ({@link import("./read-deny.js").READ_FACE_DEFAULT_DENY_ENTRIES}), judged by the structured read
      *  faces (Read/Grep/Glob/RepoMap and their traversals) in BOTH containment modes. Add-only:
      *  additions union with the active built-ins, `[]` ≡ absent (union identity), and additions can
      *  never remove a built-in — the one removal channel is the deployment's built-in configuration
-     *  ({@link readDenyBuiltinTiers} / {@link readDenyBuiltinExclude}, #245 revision of D-4). Bad entry
-     *  shapes throw at wiring time (#123). The write faces are untouched (their guard is
-     *  createSensitivePathPolicy). */
+     *  ({@link readDenyBuiltinTiers} / {@link readDenyBuiltinExclude}). Bad entry shapes throw at wiring
+     *  time. The write faces are untouched (their guard is createSensitivePathPolicy). */
     readDenyPatterns?: readonly ReadDenyEntry[];
-    /** #245 — the deployment's built-in-table TIER selection ({@link import("./read-deny.js").ReadDenyBuiltinConfig}
+    /** The deployment's built-in-table TIER selection ({@link import("./read-deny.js").ReadDenyBuiltinConfig}
      *  `tiers` key): EXACTLY the listed tiers of {@link import("./read-deny.js").READ_FACE_BUILTIN_DENY_TABLE}
      *  are active (`[]` = none — explicit and legal); absent = the default selection
      *  ({@link import("./read-deny.js").READ_DENY_DEFAULT_TIERS} — every tier except `shell-history`).
      *  Composes with {@link readDenyBuiltinExclude} (tier selection first, then row removal) and never
-     *  touches the additions seats. Unknown tier names throw at wiring time (#123). Deployment seat
-     *  ONLY — deliberately not a TaskSpec key, so no task can widen below its deployment. */
+     *  touches the additions seats. Unknown tier names throw at wiring time. Deployment seat ONLY —
+     *  deliberately not a TaskSpec key, so no task can widen below its deployment. */
     readDenyBuiltinTiers?: readonly string[];
-    /** #245 — per-row removal from the built-in table by STABLE NAME (= the row's canonical pattern
-     *  text, e.g. `".ssh"`, `".config/gcloud"`), applied after {@link readDenyBuiltinTiers} selection.
-     *  Naming a row of an inactive tier is a satisfied intent (no-op); a name matching NO table row
-     *  throws at wiring time (#123 — never silently ignored). Deployment seat ONLY, same clamp
-     *  argument as the tiers key. */
+    /** Per-row removal from the built-in table by STABLE NAME (= the row's canonical pattern text, e.g.
+     *  `".ssh"`, `".config/gcloud"`), applied after {@link readDenyBuiltinTiers} selection. Naming a row
+     *  of an inactive tier is a satisfied intent (no-op); a name matching NO table row throws at wiring
+     *  time (never silently ignored). Deployment seat ONLY, same clamp argument as the tiers key. */
     readDenyBuiltinExclude?: readonly string[];
-    /** design/199 件A — the READ-face containment state for the structured read faces
+    /** The READ-face containment state for the structured read faces
      *  ({@link import("./read-face.js").ReadFace}; resolved through the SAME
      *  {@link import("./read-face.js").resolveReadFace} order prepare-task uses). Absent ⇒ the
-     *  resolution order's default = "roots" (D-1b: the engine never opens implicitly). "open" skips
-     *  ONLY the roots containment judgment — the deny set, the UNC out-of-set refusal and the
-     *  special-file type gates run in both faces (§2.0). Beside `readOnly: true` the mount wins:
-     *  this seat is deps-shaped (a deployment default, not a per-call assertion), so its "open"
-     *  CLAMPS to "roots" and the clamp is ANNOUNCED (`config.read_face_deployment_clamped`, through
-     *  `onNotice` / `console.warn`) — the loud refusal belongs to the TASK seat (`TaskSpec.readFace`),
-     *  which is the one genuine per-call contradiction (#237; stale "refused loudly" wording here
-     *  predated the 96ef89d seat distinction). Never affects the write faces. */
+     *  resolution order's default = "roots" (the engine never opens implicitly). "open" skips ONLY the
+     *  roots containment judgment — the deny set, the UNC out-of-set refusal and the special-file type
+     *  gates run in both faces. Beside `readOnly: true` the mount wins: this seat is deps-shaped (a
+     *  deployment default, not a per-call assertion), so its "open" CLAMPS to "roots" and the clamp is
+     *  ANNOUNCED (`config.read_face_deployment_clamped`, through `onNotice` / `console.warn`) — the loud
+     *  refusal belongs to the TASK seat (`TaskSpec.readFace`), the one genuine per-call contradiction.
+     *  Never affects the write faces. */
     readFace?: "open" | "roots";
-    /** design/319 (A ticket) — the session's reminder provenance mark: the band's engine-minted
+    /** The session's reminder provenance mark: the band's engine-minted
      *  `<system-reminder>` open tags (the Read cyber/dedup/offset/empty reminders and the gh
      *  rate-limit hint) carry it as `mark="…"`, matching the system-prompt declaration the Runner
      *  renders for the same session. Threaded by prepare-task; a library-direct mount that omits it
-     *  keeps the historic bare tags (byte-compat — with no declaration in its prompt, a bare tag is
-     *  the honest form). The tag is rendered by the mint home (core/reminder-mint.ts) — the content
-     *  BODY next to it is byte-untouched. */
+     *  keeps bare tags — with no declaration in its prompt, a bare tag is the honest form. The tag is
+     *  rendered by the mint home (core/reminder-mint.ts) — the content BODY next to it is
+     *  byte-untouched. */
     reminderMark?: string;
-    /** design/319 (B ticket) — the per-run trailer/defuse trigger counters (observation seat, G9②):
+    /** The per-run trailer/defuse trigger counters (observation seat):
      *  the Read text/notebook/PDF-text disclosure trailers bump `read.*` / `notebook.*` / `pdf.*`
      *  keys here. The form suffixes are enumerated once, on the consumer-facing contract
      *  (`TaskResult.stats.mechanisms.reminderDisclosures` in core/types.ts) — this map is the same
@@ -183,11 +179,15 @@ export interface HandsToolkitOptions {
      *  is off anyway when `reminderMark` is absent). */
     reminderDisclosureCounts?: import("../../core/reminder-disclosure.js").ReminderDisclosureCounts;
 }
+/** Whether the band's WRITE half (Edit / Write / NotebookEdit, and the full `bash`) mounts for these options — the ONE
+ *  predicate {@link createHandsToolkit} branches on and prepare-task plans by (the memory phase must know, before the
+ *  band exists, whether the instruction-taught write channel will be there). `readOnly` is the verifier boundary. */
+export declare function handsWriteHalfMounts(opts: Pick<HandsToolkitOptions, "readOnly">): boolean;
 /**
- * Build the per-task hand tool band over an injected env + fresh per-task read state (design/44 §11 A).
+ * Build the per-task hand tool band over an injected env + fresh per-task read state.
  * `rootCanonical` is the already-canonicalized containment root (prepare-task resolves it once). Normal
  * mode mounts read/edit/write/grep/glob (+`bash` when `includeShell`); `readOnly` mode mounts only the
  * effect:read tools read/grep/glob (+`bash_readonly` when `includeShell`) — the verifier boundary. Subset
- * selection beyond that is the caller's job via the existing design/38 tool-filter.
+ * selection beyond that is the caller's job via the tool-filter.
  */
 export declare function createHandsToolkit(env: ExecutionEnv, readFileState: ReadFileState, rootCanonical: string, opts?: HandsToolkitOptions): AgentTool[];

package/dist/tools/fs/index.js

@@ -21,6 +21,9 @@ import { createReadFileTool } from "./fs-read.js";
 import { createEditFileTool, createWriteFileTool, createNotebookEditTool } from "./fs-write.js";
 import { createGrepTool, createGlobTool } from "./fs-search-tools.js";
 import { createBashTool, createBashReadonlyTool, createEnvTaskOutputTool, createEnvTaskStopTool } from "./fs-bash.js";
+export function handsWriteHalfMounts(opts) {
+    return opts.readOnly !== true;
+}
 export function createHandsToolkit(env, readFileState, rootCanonical, opts = {}) {
     const { includeShell = false, readOnly = false, bashReadonlyAllow, commitCoAuthor = false, mountBackgroundTaskTools = true, additionalRoots, additionalReadRoots, } = opts;
     const readFaceRoots = additionalReadRoots === undefined || additionalReadRoots.length === 0
@@ -49,7 +52,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
     const tools = [
         createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts),
     ];
-    if (!readOnly) {
+    if (handsWriteHalfMounts({ readOnly })) {
         tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited));
     }
     tools.push(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef), createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef), createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace));

package/dist/tools/fs/notebook.d.ts

@@ -1,17 +1,16 @@
 import type { ImageContent } from "../../internal/llm.js";
 /**
- * RB-227 — the Read tool's Jupyter-notebook projection: `.ipynb` is rendered as cells
- * with outputs (CC 2.1.220 parity: `Ctd`/`wtd`/`Zx_`/`Qx_`/`eI_`/`tI_`/`Atd`, pretty220.js
- * :371265-:371426), never as raw JSON text. The raw-JSON rendering let a notebook's base64 outputs
- * overflow the Read token cap, auto-paginate into an `isPartialView` entry, and thereby lock
- * NotebookEdit out via the requireRead gate (RB-200 F2) — with the marker's own offset/limit hint
- * pointing at a range that itself exceeds the cap (the base64 lives on one mega-line).
+ * The Read tool's Jupyter-notebook projection: `.ipynb` is rendered as cells with outputs (CC 2.1.220
+ * parity), never as raw JSON text. Raw-JSON rendering lets a notebook's base64 outputs overflow the
+ * Read token cap, auto-paginate into an `isPartialView` entry, and thereby lock NotebookEdit out via
+ * the requireRead gate — with the marker's own offset/limit hint pointing at a range that itself
+ * exceeds the cap (the base64 lives on one mega-line). That is the failure mode this lane removes.
  *
  * Pure module (no I/O, no env): index.ts owns reading/decoding/state; this owns parse + render.
  */
-/** CC 220 `o3r` (:60226): extname === ".ipynb". */
+/** CC `o3r` parity: extname === ".ipynb". */
 export declare function isNotebookPath(p: string): boolean;
-/** CC 220 `Jx_ = 1e4` (:371426): PER-CELL cap on the summed output payload (text chars + image
+/** CC `Jx_` = 1e4: PER-CELL cap on the summed output payload (text chars + image
  *  base64 chars). A cell over it has its ENTIRE outputs array replaced by one pointer line —
  *  per cell, never a running global budget (CC's `Xx_` accumulator restarts for every cell). */
 export declare const NOTEBOOK_CELL_OUTPUT_POINTER_CHARS = 10000;
@@ -20,12 +19,12 @@ export declare const NOTEBOOK_CELL_OUTPUT_POINTER_CHARS = 10000;
  *  text exceeds 10K is always pointered, so this clip is unreachable insurance kept at the same
  *  10K yardstick (simplification of CC's two-stage clip, recorded deliberately). */
 export declare const NOTEBOOK_OUTPUT_TEXT_CLIP = 10000;
-/** RB-227 E4 — cumulative image budget across the WHOLE notebook: the 10K per-cell pointer bounds
- *  one cell, but N cells × ~9KB images is unbounded. CC gets an implicit bound because image data
- *  counts toward its 256KB projected-JSON cap (`ePi = 262144`, :61029) and then HARD-ERRORS; sema
- *  reuses that same figure but as a DEGRADATION budget — images past it are dropped with an honest
- *  marker instead of making the notebook unreadable/uneditable (which is the RB-227 failure mode
- *  this whole lane exists to remove). Divergence-logged. */
+/** Cumulative image budget across the WHOLE notebook: the 10K per-cell pointer bounds one cell, but
+ *  N cells × ~9KB images is unbounded. CC gets an implicit bound because image data counts toward its
+ *  256KB projected-JSON cap (`ePi` = 262144) and then HARD-ERRORS; sema reuses that same figure but as
+ *  a DEGRADATION budget — images past it are dropped with an honest marker instead of making the
+ *  notebook unreadable/uneditable, which is the failure mode this lane exists to remove.
+ *  Divergence-logged. */
 export declare const NOTEBOOK_IMAGE_BASE64_BUDGET = 262144;
 export interface NotebookOutputImage {
     /** Whitespace-stripped base64 (magic-validated — never an unverified blob, see `imageFromData`). */
@@ -40,9 +39,9 @@ export interface NotebookOutput {
 export interface NotebookCell {
     /** `cell.id`, or the synthesized `cell-${index}` for nbformat<4.5 — index = the UNFILTERED array
      *  position, because NotebookEdit's `/^cell-(\d+)$/` positional fallback resolves exactly that.
-     *  Deliberate delta (review r2 finding 2): sema synthesizes for any NON-STRING id (`typeof id ===
-     *  "string"` guard in `parseNotebookCells`) where CC's `wtd` uses `e.id ?? cell-${t}` (:371314)
-     *  and would render e.g. a numeric id literally — but NotebookEdit's id match is string-only, so
+     *  Deliberate delta: sema synthesizes for any NON-STRING id (`typeof id === "string"` guard in
+     *  `parseNotebookCells`) where CC's `wtd` uses `e.id ?? cell-${t}` and would render e.g. a numeric
+     *  id literally — but NotebookEdit's id match is string-only, so
      *  CC's literal form would be un-addressable while sema's positional alias resolves; nbformat
      *  ids are spec-string, so this branch only fires on out-of-spec input. */
     cell_id: string;
@@ -62,7 +61,7 @@ export type ParsedNotebook = {
     reason: "json" | "shape";
 };
 /**
- * CC `Ctd` + `wtd` (:371373 / :371313): parse the notebook JSON into the projected cell list.
+ * CC `Ctd` + `wtd`: parse the notebook JSON into the projected cell list.
  * Failure is a typed reason, not a throw — the Read lane falls back to raw text on it (sema
  * divergence from CC's hard error: a corrupt notebook stays readable so the model can see what is
  * wrong; NotebookEdit still refuses it with its own JSON-validation errors, so nothing is loosened).
@@ -81,13 +80,13 @@ export interface NotebookRender {
     imageChars: number;
 }
 /**
- * CC `eI_`/`tI_`/`Atd` (:371339/:371349/:371399): render projected cells to content blocks.
- * Tag shape is CC-verbatim, including the deliberately malformed closing tag `</cell id="X">`;
- * `<cell_type>` only when not code, `<language>` only for code cells whose language !== "python".
- * Output text rides with a leading "\n" (tI_) and adjacent text blocks merge with "\n" (Atd), so an
- * all-text notebook collapses to a single text block. Images ride as real image blocks in sema's
- * `{type:"image", data, mimeType}` shape, bounded by the cumulative `imageBase64Budget` (E4): past
- * it the image is DROPPED with an honest text marker — a degradation, never an error.
+ * CC `eI_`/`tI_`/`Atd`: render projected cells to content blocks. Tag shape is CC-verbatim, including
+ * the deliberately malformed closing tag `</cell id="X">`; `<cell_type>` only when not code,
+ * `<language>` only for code cells whose language !== "python". Output text rides with a leading "\n"
+ * and adjacent text blocks merge with "\n", so an all-text notebook collapses to a single text block.
+ * Images ride as real image blocks in sema's `{type:"image", data, mimeType}` shape, bounded by the
+ * cumulative `imageBase64Budget`: past it the image is DROPPED with an honest text marker — a
+ * degradation, never an error.
  */
 export declare function renderNotebookCells(cells: readonly NotebookCell[], imageBase64Budget: number): NotebookRender;
 /** Wire-card projection of a cell: base64 replaced by a length marker so the `details` card never

package/dist/tools/fs/pdf.d.ts

@@ -1,7 +1,7 @@
 /**
- * PDF read pipeline (+ 审计 — CC FileReadTool parity).
+ * PDF read pipeline (CC FileReadTool parity).
  *
- * CC ground truth (original-source-code, 取证 2026-07-07):
+ * CC ground truth (original source code):
  * - Whole-PDF path (`FileReadTool.ts:987-1016` + `utils/pdf.ts:88-103`): the file bytes are base64'd and
  *   sent as a native `{type:"document",source:{type:"base64",media_type:"application/pdf",data}}` content
  *   block — the model reads the text layer directly (no local text extraction).
@@ -40,7 +40,7 @@ export declare function parsePdfPageRange(pages: string): PdfPageRange | undefin
  * nothing matches (page tree inside compressed object streams — modern writers), NEVER a guess.
  */
 export declare function countPdfPagesFromBytes(bytes: Uint8Array): number | undefined;
-/** Max chars of a failed poppler call's stderr/stdout kept in the reported error (A-005.15). */
+/** Max chars of a failed poppler call's stderr/stdout kept in the reported error. */
 export declare const PDF_EXEC_ERROR_PREVIEW_CHARS = 400;
 /** Bound a poppler exec failure's captured stream to {@link PDF_EXEC_ERROR_PREVIEW_CHARS}, marking the cut
  *  (a bare slice reads identical to a short capture that just happened to end there — the model has no way

package/dist/tools/fs/read-deny.d.ts

@@ -60,9 +60,9 @@ export interface ReadDenyMatcher {
     readonly rgProbeGlobs: readonly ReadDenyRgGlob[];
 }
 /**
- * The closed set of built-in tiers (#245). A tier is the deployment's selection unit
+ * The closed set of built-in tiers. A tier is the deployment's selection unit
  * ({@link ReadDenyBuiltinConfig.tiers}); every {@link READ_FACE_BUILTIN_DENY_TABLE} row belongs to
- * exactly one. Unknown tier names refuse loudly (#123) — this array is the validation source and the
+ * exactly one. Unknown tier names refuse loudly — this array is the validation source and the
  * admin-face vocabulary, never re-spelled downstream.
  */
 export declare const READ_DENY_BUILTIN_TIERS: readonly ["credentials", "shell-history", "browser", "wallet", "agent-config"];
@@ -78,12 +78,12 @@ export interface ReadDenyBuiltinRow {
     readonly tier: ReadDenyBuiltinTier;
 }
 /**
- * READ_FACE_BUILTIN_DENY_TABLE — the FULL built-in table with tier metadata (#245: the material
- * basis of the deployment admin face — what an org administrator "sees" before selecting tiers /
- * excluding rows). Activation is a separate fact: the default face is the table under
+ * READ_FACE_BUILTIN_DENY_TABLE — the FULL built-in table with tier metadata: the material basis of
+ * the deployment admin face, what an org administrator "sees" before selecting tiers / excluding
+ * rows. Activation is a separate fact: the default face is the table under
  * {@link READ_DENY_DEFAULT_TIERS} (shell-history rows exist here but are OFF by default).
  * The dotenv family is deliberately NOT here — workspace `.env` files are working material for the
- * tasks this engine runs (the design's `outside_workspace` tier was also ruled OUT).
+ * tasks this engine runs; an `outside_workspace` tier is likewise deliberately absent.
  *
  * Each row states its tradeoff. Rows are matched as segment runs anywhere in the path, so a repo
  * fixture spelled `fixtures/.ssh/id_rsa` is refused too — deliberate: the refusal names the pattern,
@@ -99,20 +99,20 @@ export interface ReadDenyBuiltinRow {
  *
  * agent-config tier — the agent's OWN configuration files whose `env` / server blocks carry API keys
  * in cleartext (the shell's `settings.json` env block, a project `.mcp.json` server env, the engine
- * host's data-root `.env`). A structured read of one of these used to land the key verbatim in the
- * tool result and therefore in the session record. Rows name FILES, not the config DIRECTORIES:
+ * host's data-root `.env`). Unguarded, a structured read of one of these lands the key verbatim in
+ * the tool result and therefore in the session record. Rows name FILES, not the config DIRECTORIES:
  * `.sema`/`.claude` also hold agents, skills, hooks and (under the shell's layout,
  * `~/.sema/engine-data`) the engine data root with the memory library — material the model reads
  * and edits as ordinary work, and a directory-wide row would need a data-root passthrough (one more
  * rule) to keep it readable. The write face guards the directories (`sensitive-path-policy.ts`): a
  * write there is self-authorization; a read of a non-credential file there is debugging. Token
- * STORES of the same tooling (`.credentials.json`, `.codex/auth.json`, …) are credentials rows, not
+ * STORES of the same tooling (`.credentials.json`, an agent CLI's `auth.json`, …) are credentials rows, not
  * agent-config rows: a deployment that switches this tier off to debug its agent configuration must
  * not also expose the OAuth stores beside it.
  */
 export declare const READ_FACE_BUILTIN_DENY_TABLE: readonly ReadDenyBuiltinRow[];
 /**
- * The DEFAULT tier selection (#245 ruling ②): every tier EXCEPT `shell-history` — history files are
+ * The DEFAULT tier selection: every tier EXCEPT `shell-history` — history files are
  * unrestricted unless a deployment opts the tier in. Derived, not re-listed: a tier added to the
  * closed set is default-ON unless this expression is deliberately revisited (`agent-config` joined
  * default-ON this way: an unconfigured deployment refuses the agent's own key-bearing settings files;
@@ -120,30 +120,30 @@ export declare const READ_FACE_BUILTIN_DENY_TABLE: readonly ReadDenyBuiltinRow[]
  */
 export declare const READ_DENY_DEFAULT_TIERS: readonly ReadDenyBuiltinTier[];
 /**
- * The deployment's built-in-table configuration (#245 — deployment seat ONLY: RunnerDeps /
+ * The deployment's built-in-table configuration — deployment seat ONLY (RunnerDeps /
  * HandsToolkitOptions; deliberately NOT a TaskSpec key and NOT in the governed workflow whitelist,
  * so no task or governed script can widen below its deployment).
  *  - `tiers` — EXACTLY-these tier selection: listed tiers are active, unlisted ones are not
  *    (`[]` = no built-in tiers at all — an explicit, legal posture; absent = {@link READ_DENY_DEFAULT_TIERS}).
  *  - `exclude` — per-row removal by canonical pattern name, applied AFTER tier selection.
- * Unknown tier names / unknown row names refuse loudly (#123) — never silently ignored.
+ * Unknown tier names / unknown row names refuse loudly — never silently ignored.
  */
 export interface ReadDenyBuiltinConfig {
     tiers?: readonly string[];
     exclude?: readonly string[];
 }
 /**
- * Resolve the ACTIVE built-in rows under a deployment configuration (validated, loud — #123's three
- * bad-value states all throw: garbage shapes, unknown tier names, unknown row names). The one
+ * Resolve the ACTIVE built-in rows under a deployment configuration (validated, loud — all three
+ * bad-value states throw: garbage shapes, unknown tier names, unknown row names). The one
  * resolution used by {@link compileReadDeny}; exported so an admin face can preview the effective
  * table under a candidate configuration with the engine's own rules.
  */
 export declare function resolveReadDenyBuiltins(config?: ReadDenyBuiltinConfig): readonly ReadDenyBuiltinRow[];
 /**
  * READ_FACE_DEFAULT_DENY_ENTRIES — the DEFAULT-ACTIVE built-in set: {@link READ_FACE_BUILTIN_DENY_TABLE}
- * under {@link READ_DENY_DEFAULT_TIERS} (#245: shell-history rows are in the table, not in this face).
- * Kept as the historical name for consumers rendering "what does an unconfigured deployment refuse";
- * the tier-annotated table is the admin-face export.
+ * under {@link READ_DENY_DEFAULT_TIERS} (shell-history rows are in the table, not in this face). This
+ * is the export for consumers rendering "what does an unconfigured deployment refuse"; the
+ * tier-annotated table is the admin-face export.
  */
 export declare const READ_FACE_DEFAULT_DENY_ENTRIES: readonly ReadDenyEntry[];
 /** A compiled segment-run pattern (shared engine — the write guard delegates here too). */
@@ -159,8 +159,8 @@ export interface CompiledSegmentPattern {
  *  · "ascii"   — ASCII-case-insensitive (deny-set contract);
  *  · "unicode" — RegExp `i` flag (the write guard's historical host-keyed behavior — kept for it
  *    byte-identically; NOT used by the deny set).
- * Returns null when the pattern reduces to zero segments — the CALLER owns its loud path (#123: the
- * two consumers refuse with their own surface-specific texts).
+ * Returns null when the pattern reduces to zero segments — the CALLER owns its loud path (the two
+ * consumers refuse with their own surface-specific texts).
  */
 export declare function compileSegmentPattern(raw: string, fold: "none" | "ascii" | "unicode"): CompiledSegmentPattern | null;
 /**
@@ -185,10 +185,10 @@ export declare function persistedReadDenyEntryProblem(e: unknown): string | null
  * Compile the read-face deny judge: ACTIVE built-in rows ∪ additions. Additions are add-only at every
  * task layer (`[]` additions ≡ absent, deliberately a no-op rather than a refusal: an array API
  * cannot observe a "replace" intent, and union-with-empty is the identity, not a silent fallback);
- * the built-in half is selected by the DEPLOYMENT's `builtin` config (#245 — absent = the default
- * tier selection, see {@link resolveReadDenyBuiltins}). A deployment that turned a tier off can still
+ * the built-in half is selected by the DEPLOYMENT's `builtin` config (absent = the default tier
+ * selection, see {@link resolveReadDenyBuiltins}). A deployment that turned a tier off can still
  * re-add single patterns through the additions seats — they then ride as ordinary additions.
  * Bad entry shapes / zero-segment patterns / unknown tier or row names throw loudly, naming the
- * layer or knob (#123).
+ * layer or knob.
  */
 export declare function compileReadDeny(additions?: readonly ReadDenyEntry[], layer?: string, builtin?: ReadDenyBuiltinConfig): ReadDenyMatcher;