@sema-agent/core 5.18.1 → 5.20.0

package/CHANGELOG.md

@@ -1,5 +1,149 @@
 # Changelog
 
+## 5.20.0 — 2026-08-08
+
+### BREAKING
+
+Configuration hygiene sweep. A malformed numeric knob used to be accepted and then quietly do
+something — usually the OPPOSITE of what it was set to. Every seam below now either refuses the
+value at its resolution point or clamps it and says so. Well-formed values in the documented range
+are untouched everywhere; the break is that values which used to be accepted-then-misbehave are
+now rejected, so a deployment carrying one gets a loud failure at wiring time instead of a
+mysterious runtime.
+
+- **MCP millisecond env knobs** (`MCP_TOOL_TIMEOUT`, `MCP_TOOL_TIMEOUT_TOTAL`,
+  `MCP_IDLE_TIMEOUT_STDIO`, `MCP_IDLE_TIMEOUT_HTTP`, `MCP_TIMEOUT`) share one parser, which was
+  `parseInt`-based: `1e9` meant 1ms, `30s` meant 30ms, and `100_000_000` — the way this repo writes
+  the default constant it invites you to copy — meant 100ms. Past 2^31-1 the host timer truncated
+  the delay and fired at once, so widening a watchdog to "basically off" made it abort every call,
+  while the failure text quoted the requested number back. The parser now reads plain digits,
+  scientific notation and digit grouping, refuses anything else, and clamps into
+  **[1000, 2147483647] ms**, warning once on stderr with the knob name, the raw text and the value
+  actually in force. Timeout frames quote the resolved value. `MAX_MCP_OUTPUT_TOKENS` moves onto the
+  same grammar (its `1e5` used to mean a 4-char budget), keeping upstream's unbounded range.
+  Upgrade note (the widening side of this fix): on 5.19.0 and earlier, `1e9` / `1_800_000` — both
+  legal upstream spellings — silently took effect as **1ms**. After upgrading they take effect at
+  face value, so a deployment that wrote one of these will see the knob jump from 1ms to the
+  number it always said.
+- **Millisecond knobs that arm a host timer** are refused above 2147483647ms (~24.8 days), where
+  the timer truncates and fires immediately: the stall watchdogs (`connectTimeoutMs`,
+  `firstTokenTimeoutMs`, `idleTimeoutMs`), `brainCallGuardrailMs`, `runWorkflow`'s `totalTimeoutMs`
+  / `stallMs` / `throttleBackoffMs`, and `createApprovalPolicy`'s `approvalTimeoutMs` — the last of
+  which would otherwise have denied every request instantly, fail-closed and silent. Each already
+  documents `0` / `false` / omission as "off". `limits.maxWalltimeMs` is the exception and keeps
+  its promise of no ceiling: the hard-abort timer now waits in representable chunks.
+- **Retention policies** (`BackgroundAgentStore.reap`, `MailboxStore.reap`, `WorkflowRunStore.reap`,
+  `reapDurableAgents`, both roster stores' constructors) refuse a non-finite or negative bound with
+  `config.retention_policy_invalid`. `keep` is consumed as `slice(Math.max(0, keep))`, where NaN
+  collapses to `slice(0)` and deleted EVERY terminal row in the scope; the roster's `maxAgeMs` made
+  every durable address read as expired. Absent fields keep their "this arm is not applied" meaning.
+  Operational note: this is a refusal, not a sanitize — a deployment with a malformed retention knob
+  will see every reap throw (rows accumulate) until the knob is corrected. Fix the knob before
+  upgrading; nothing is auto-repaired on your behalf.
+- **Web and circuit-breaker knobs**: `timeoutMs` on WebFetch / WebSearch / the Searxng backend fed a
+  bare `setTimeout`, where NaN and Infinity both become 1ms — a budget written as "no limit" aborted
+  every request on arrival and reported "timed out after NaNms". `maxResults` fed `slice(0, max)`,
+  so a NaN or 0 cap emptied every search from a backend that answered. The circuit breaker's
+  `failureThreshold` / `cooldownMs` / `halfOpenProbes` had no validation at all, and `failures >= NaN`
+  is false forever — an unevaluable threshold left the breaker permanently open-loop. All are now
+  resolved at assembly time (`config.web_timeout_invalid`,
+  `config.web_search_max_results_invalid`, `config.circuit_breaker_invalid`). `probeSearchBackend`
+  keeps its documented never-throws contract: a malformed budget comes back as `{ ok: false, error }`.
+
+### Added
+
+- **`Hooks.preToolUseObservational`** — a deployment declares that its PreToolUse face is a pure
+  OBSERVER (a tracer, an audit sink) and never judges. 5.19.0's delegation fold keys on PRESENCE,
+  which cannot tell a tracer from a screener: a deployment that flipped on a default-OFF diagnostic
+  hook thereby added an opaque constraint to every delegated child, and a child that durably parked
+  recorded that count on its row — where an approval redeemed by a leg that cannot re-supply the
+  live screening closure has no recovery path. With the declaration the face contributes **no
+  chain entry**, so `parentConstraintCount` counts only constraints that actually judge; without it,
+  5.19.0 behavior is unchanged. The callback still runs in the installing task's own gate, on every
+  call, with the same crash posture (a throw is still the fail-closed deny) — only the inherited
+  constraint goes away. A declared-observational face that returns something anyway has that return
+  **refused, not obeyed**: the call proceeds as if the face had no opinion (this covers
+  `additionalContext` too) and `onError` is told (`phase:"hook"`, classification
+  `observational-hook-verdict-ignored`), so the declaration cannot become a quiet way to keep a
+  screening face's verdicts while shedding the delegation constraint they belong to. A declared face
+  is also handed a **detached copy of the arguments** (best-effort, same helper and same limits as the
+  other observe-only payloads): the gate reads a rewrite off reference identity, so an in-place edit
+  would be a second channel outliving the dropped return. Two further consequences of "it does not
+  judge": a declared face no longer collapses an ancestor's screening entry that names the same
+  callback (the descendant no longer honors it, so the ancestor's constraint is folded instead), and it
+  no longer counts as an effect-aware gate for the loud ungated-write-surface warning.
+- **`createPreToolUseConstraintPolicy` is now a public export**, and a durable park under an inherited
+  screening constraint says so at PARK time. A checkpoint records only how many opaque constraints its
+  leg ran under; the resume must hand the same chain back. Every entry kind except one is a policy the
+  deployment authored — the screening entry 5.19.0 added is engine-minted, so a hook-wired tree's
+  parked children were redeemable only in the process that spawned them (same-Runner resumes are
+  auto-re-supplied from the in-memory registry and were never affected). The mint is now exported, so a
+  fresh Runner can rebuild the entry — same callback, same installed env — and hand the full chain to
+  `resumeStream(..., internals)`; the recorded-count check is unchanged, so a short or mismatched chain
+  is still refused pre-CAS. And the park itself now announces the requirement once per task on
+  `onError` (`phase:"degraded"`, classification `screening-constraint-in-durable-chain`), naming the
+  recorded count and the ways out, instead of leaving it to be discovered at a redemption that fails.
+
+## 5.19.0 — 2026-08-10
+
+> Three bundles, each pre-verified two-way by the evaluation line against the 5.18.1 artifact
+> before this release (criteria [3134], green-lit [3146]).
+
+### BREAKING
+
+- **A task's PreToolUse screening face now screens its DELEGATED CHILDREN** (issue #33). The
+  face used to run only in the gate of the task that installed it, so a call it denied executed
+  unrefused one level down — sync, background and workflow legs alike, at any depth. It now
+  folds into a ToolPolicy on the existing ancestor-constraint chain (full-installation identity,
+  four-axis dedup so a deps-level hook is consulted once per call at any depth). A screening
+  `ask` resolves at the installing task's frozen approver; a hook-wired parent with no approver
+  denies its children's screened calls fail-closed.
+  **Operational (corrected per downstream measurement)**: `parentConstraintCount` gains a
+  screening entry for hook-wired trees. Pre-5.19.0 rows (including hook-wired parents) recorded
+  the old count and rebuild legs that supply it keep matching — upgrade and rollback are clean
+  for EXISTING pending checkpoints. The unrecoverable case is a checkpoint **minted on 5.19.0**
+  by a hook-wired parent and redeemed by a rebuild leg that cannot re-supply the live screening
+  entry (cross-replica redemption): it fails pre-CAS with `resume.parent_constraint_mismatch`
+  and stays pending, with no recovery path (the count is written at park time; disabling the
+  hook afterwards does not change it). Same-replica resumes via `resumeStream(..., internals)`
+  are unaffected. A delegated child of a hook-wired parent also sets
+  `requiresParentConstraint`, so its durable resume must re-supply the chain via
+  `resumeStream(..., internals)`.
+- **Write guards judge the call's live cwd** (P1, host-lane proven bypass). A resident shell's
+  `cd` moved what a relative Write/Edit/NotebookEdit target meant, while the guards kept
+  judging the wiring-time root — `cd .git/hooks` + `Write("pre-commit")` landed unrefused.
+  Every path-resolving guard (sensitive-path, fs-write-gate, session-rule allowDirs,
+  active-skill allowPaths, transcript-integrity, run-spec frozen deny) now resolves the target
+  against `ToolCallRequest.cwd`, stamped per call from the same tracked cwd the tools resolve
+  with. **The asymmetry is deliberate**: the target follows the live cwd; each guard's own
+  configured directories stay anchored to the static root, so a `cd` cannot relocate the fence
+  itself. Absent the stamp (direct invocation), every guard falls back to its configured root —
+  byte-identical prior behavior. Also newly asked: a non-read-only Bash whose cwd sits inside
+  the transcript directory, and a POSIX filename containing a backslash (fail-closed).
+  Registered, not fixed: bash builtin writes, hook `touchedPaths`, the shell-operand axis
+  (backlog #108 notes).
+
+### Fixed
+
+- **Read-only shell classification (`shellGate:"classify"`) prompts less and is more accurate
+  in both directions.** The compound splitter carries quote state, so a quoted connector —
+  `grep -E "a|b"`, the ordinary spelling of a read-only monitoring pipeline — is argument text
+  rather than a phantom command boundary; `2>/dev/null` and output-descriptor fd duplication
+  are recognized as moving no data into any file. No widening: every other redirection form
+  still rejects, unbalanced quoting falls back to the stricter blind scan, and phantom segments
+  could only ever add a rejection. Also tightened in the demoting direction: operand counts now
+  match what bash passes, so stdin-reading forms that would hang (`grep "a | b"`,
+  `cut -d , -f1`, `grep -if-`, `grep -f/dev/zero`) no longer auto-allow.
+
+### Guards / tooling (no behavior surface)
+
+- `scripts/ship-post-lint.mjs`: release-post commit references are ancestry-verified against
+  the release, and negative claims get the real two-version dist delta to be written against.
+- A brain silent-recovery-arm ratchet freezes the 26 existing tell-nobody arms so a new one has
+  to be argued for; the delegation carriage surfaces (live chain, constraint entry, checkpoint
+  projection) are exhaustively registered so a new field stops compiling until its travel is
+  recorded.
+
 ## 5.18.1 — 2026-08-10
 
 > The 5.18.0 post-release verification round, folded back in. Every surface below was

package/dist/agents/roster-store.js

@@ -1,4 +1,5 @@
 import { mkdirSync, readFileSync } from "node:fs";
+import { assertRetentionPolicy } from "../core/retention-policy.js";
 import { atomicWriteFile } from "../stores/file/fs-atomic.js";
 import { dirname } from "node:path";
 import { normalizeAgentName } from "../core/task-registry.js";
@@ -50,6 +51,7 @@ export class MemoryRosterStore {
     maxAgeMs;
     gc;
     constructor(opts) {
+        assertRetentionPolicy("RosterStore", opts);
         this.maxAgeMs = opts?.maxAgeMs;
         this.gc = opts;
     }
@@ -78,6 +80,7 @@ export class FileRosterStore {
     gc;
     onCorruptRead;
     constructor(path, opts) {
+        assertRetentionPolicy("RosterStore", opts);
         this.path = path;
         this.maxAgeMs = opts?.maxAgeMs;
         this.gc = opts;

package/dist/brain/circuit-breaker.js

@@ -24,10 +24,21 @@ function errorAssistantMessage(model, code, detail, stopReason = "error") {
         timestamp: Date.now(),
     };
 }
+function finiteBreakerKnob(value, knob, fallback, wholeAtLeastOne) {
+    if (value === undefined)
+        return fallback;
+    const ok = wholeAtLeastOne ? Number.isInteger(value) && value >= 1 : Number.isFinite(value) && value >= 0;
+    if (!ok) {
+        const e = new Error(`createCircuitBreakerBrain: ${knob} must be ${wholeAtLeastOne ? "a whole number of 1 or more" : "a finite, non-negative number of milliseconds"} (got ${String(value)}) — an unevaluable knob leaves the breaker permanently open-loop, which is a protection that is silently not there`);
+        e.code = "config.circuit_breaker_invalid";
+        throw e;
+    }
+    return value;
+}
 export function createCircuitBreakerBrain(inner, opts = {}) {
-    const failureThreshold = opts.failureThreshold ?? 5;
-    const cooldownMs = opts.cooldownMs ?? 30_000;
-    const halfOpenProbes = opts.halfOpenProbes ?? 1;
+    const failureThreshold = finiteBreakerKnob(opts.failureThreshold, "failureThreshold", 5, true);
+    const cooldownMs = finiteBreakerKnob(opts.cooldownMs, "cooldownMs", 30_000, false);
+    const halfOpenProbes = finiteBreakerKnob(opts.halfOpenProbes, "halfOpenProbes", 1, true);
     const countCodes = new Set(opts.countCodes ?? ["network", "server", "rate_limit"]);
     const keyOf = opts.key ?? ((m) => `${m.provider}:${m.id}`);
     const state = opts.state ?? new InMemoryBreakerState();

package/dist/brain/timeout.d.ts

@@ -1,4 +1,5 @@
 import type { StreamFn } from "../internal/llm.js";
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
 export declare function resolveStallTimeoutMs(value: number | undefined, knob: string): number | undefined;
 export declare const STALL_CONNECT_MS = 30000;
 export declare const STALL_FIRST_TOKEN_MS = 120000;

package/dist/brain/timeout.js

@@ -1,3 +1,4 @@
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export function resolveStallTimeoutMs(value, knob) {
     if (value === undefined)
         return undefined;
@@ -6,6 +7,11 @@ export function resolveStallTimeoutMs(value, knob) {
         e.code = "config.stall_timeout_invalid";
         throw e;
     }
+    if (value > MAX_TIMER_DELAY_MS) {
+        const e = new Error(`${knob} must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so this watchdog would abort every call instead of tolerating a long one (got ${String(value)}). Pass 0 to disable it.`);
+        e.code = "config.stall_timeout_invalid";
+        throw e;
+    }
     return value;
 }
 export const STALL_CONNECT_MS = 30_000;
@@ -66,6 +72,11 @@ export function resolveBrainCallGuardrailMs(knob) {
         e.code = "config.brain_call_guardrail_invalid";
         throw e;
     }
+    if (knob > MAX_TIMER_DELAY_MS) {
+        const e = new Error(`brainCallGuardrailMs must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so the backstop would abort every model call (got ${String(knob)}). Pass false or 0 to turn the backstop off.`);
+        e.code = "config.brain_call_guardrail_invalid";
+        throw e;
+    }
     return knob;
 }
 function armCallGuardrail(limitMs, outerSignal, ref) {

package/dist/core/background-agent-store.d.ts

@@ -87,6 +87,7 @@ export interface BackgroundAgentReapOptions {
     keep?: number;
     staleRunningMaxAgeMs?: number;
 }
+export declare function assertBackgroundAgentReapOptions(opts: BackgroundAgentReapOptions | undefined): void;
 export interface BackgroundAgentStore {
     put(record: BackgroundAgentRecord): Promise<void>;
     get(handle: string, scope: string): Promise<BackgroundAgentRecord | null>;

package/dist/core/background-agent-store.js

@@ -1,4 +1,5 @@
 import { uuidv7 } from "../internal/harness.js";
+import { assertRetentionPolicy } from "./retention-policy.js";
 export const REVIVED_ROW_CLEARED_FIELDS = [
     "settledAt",
     "stoppedBy",
@@ -43,6 +44,9 @@ export function canAccessAgentRecord(record, access) {
     return false;
 }
 export const STALE_RUNNING_REAP_ATTRIBUTION = "the host process was interrupted while this agent was running — its in-process state was lost. Check its worktree / output file for partial work before assuming the task landed (stale running row reaped).";
+export function assertBackgroundAgentReapOptions(opts) {
+    assertRetentionPolicy("BackgroundAgentStore.reap", opts);
+}
 export async function reconcileParkedAgents(stores, scope, now, opts) {
     const out = { failed: 0, rolledBack: 0 };
     const excluded = (row) => (opts?.excludeHandles?.has(row.handle) ?? false) ||
@@ -256,6 +260,7 @@ export class InMemoryBackgroundAgentStore {
         return [...new Set([...this.rows.values()].map((r) => r.scope))].sort();
     }
     async reap(scope, now, opts) {
+        assertBackgroundAgentReapOptions(opts);
         if (!opts || (opts.maxAgeMs === undefined && opts.keep === undefined && opts.staleRunningMaxAgeMs === undefined))
             return 0;
         const flippedKeys = new Set();

package/dist/core/fs-write-gate-policy.js

@@ -15,7 +15,7 @@ export function createFsWriteGatePolicy(opts) {
             if (path === undefined) {
                 return ask(`write tool "${req.toolName}" requires approval: the call has no resolvable path target to confine`);
             }
-            const canon = await canonicalizeTarget(env, path, signal, rootPath);
+            const canon = await canonicalizeTarget(env, path, signal, req.cwd ?? rootPath);
             if (!canon.ok) {
                 return ask(`write to "${path}" requires approval: its real target could not be resolved (${canon.message})`);
             }

package/dist/core/hooks.d.ts

@@ -1,8 +1,9 @@
 import type { DocumentContent, ImageContent, TextContent } from "../internal/llm.js";
 import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../internal/harness-types.js";
-import type { PermissionResult, ResolvedAsk, ToolCallRequest } from "./tool-policy.js";
+import type { PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
 export interface Hooks {
     preToolUse?(toolName: string, input: unknown, ctx: HookToolContext): PreToolUseResult | undefined | Promise<PreToolUseResult | undefined>;
+    preToolUseObservational?: true;
     postToolUse?(toolName: string, input: unknown, output: HookToolOutput, ctx: HookToolContext): PostToolUseResult | undefined | Promise<PostToolUseResult | undefined>;
     userPromptSubmit?(prompt: string): UserPromptSubmitResult | undefined | Promise<UserPromptSubmitResult | undefined>;
     stop?(ctx: StopHookContext): StopHookResult | undefined | Promise<StopHookResult | undefined>;
@@ -165,4 +166,5 @@ export interface ToolGateInput {
         }) => void;
     };
 }
+export declare function createPreToolUseConstraintPolicy(preToolUse: NonNullable<Hooks["preToolUse"]>, env?: HookEnvCapabilities, onCrash?: (err: unknown) => void): ToolPolicy;
 export declare function runToolGate(input: ToolGateInput): Promise<ToolGateResult>;

package/dist/core/hooks.js

@@ -98,6 +98,38 @@ function screenPreToolUseResult(r) {
         return undefined;
     return refuseOutOfContractDecision(r);
 }
+export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash) {
+    return {
+        check: async (req) => {
+            let r;
+            try {
+                r = screenPreToolUseResult(await preToolUse(req.toolName, req.args, { toolCallId: req.toolCallId, toolName: req.toolName, ...(env !== undefined ? { env } : {}) }));
+            }
+            catch (err) {
+                try {
+                    onCrash?.(err);
+                }
+                catch {
+                }
+                return { action: "deny", message: preToolUseCrashReason(`this call to "${req.toolName}"`, err), decisionReason: "hook" };
+            }
+            if (r === undefined)
+                return { action: "allow" };
+            if (r.action === "deny") {
+                return { action: "deny", message: decisionText(r) ?? `tool "${req.toolName}" blocked by a PreToolUse hook`, decisionReason: "hook" };
+            }
+            if (r.action === "ask") {
+                return {
+                    action: "ask",
+                    message: decisionText(r) ?? `approval required for "${req.toolName}" (inherited PreToolUse hook)`,
+                    decisionReason: "hook",
+                    ...(r.updatedInput !== undefined ? { updatedInput: r.updatedInput } : {}),
+                };
+            }
+            return r.updatedInput !== undefined ? { action: "allow", updatedInput: r.updatedInput } : { action: "allow" };
+        },
+    };
+}
 function traceHookCrash(input, err, notifier) {
     notifier.notify(() => input.onHookError?.(err), "toolGate.onHookError");
 }

package/dist/core/mailbox-store.js

@@ -1,3 +1,4 @@
+import { assertRetentionPolicy } from "./retention-policy.js";
 export function newestSentAt(messages) {
     let newest;
     for (const m of messages) {
@@ -65,6 +66,7 @@ export class InMemoryMailboxStore {
         this.boxes.delete(this.key(scope, handle));
     }
     async reap(scope, now, opts) {
+        assertRetentionPolicy("MailboxStore.reap", opts);
         if (opts?.maxAgeMs === undefined)
             return 0;
         let dropped = 0;

package/dist/core/mcp.d.ts

@@ -63,11 +63,15 @@ export declare function gateMcpOutput(content: Array<TextContent | ImageContent>
 export declare function structuredContentErrorLine(structuredContent: unknown, collectedText: string): string | undefined;
 export declare function truncateMcpErrorText(s: string): string;
 export declare const MCP_TOOL_TIMEOUT_DEFAULT_MS = 100000000;
+export declare const MCP_ENV_MS_MIN = 1000;
+export declare const MCP_ENV_MS_MAX = 2147483647;
+export declare function __resetMcpEnvAnnouncements(): void;
 export declare function mcpToolTimeoutMs(): number;
 export declare function mcpToolTotalTimeoutMs(perCallMs: number): number;
 export declare const MCP_IDLE_TIMEOUT_STDIO_DEFAULT_MS: number;
 export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
 export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
+export declare function mcpStartupTimeoutMs(): number | undefined;
 export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
 export declare function collapseMcpErrorPrefix(message: string): string;
 export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;

package/dist/core/mcp.js

@@ -24,13 +24,18 @@ export function resolveMcpDeclaredResultSize(meta) {
     return Math.min(declared, MCP_META_RESULT_SIZE_CAP);
 }
 function mcpMaxOutputTokens() {
-    const raw = process.env.MAX_MCP_OUTPUT_TOKENS;
-    if (raw) {
-        const n = parseInt(raw, 10);
-        if (Number.isFinite(n) && n > 0)
-            return n;
+    const rawEnv = process.env.MAX_MCP_OUTPUT_TOKENS;
+    if (rawEnv === undefined)
+        return MCP_OUTPUT_TOKENS_DEFAULT;
+    const raw = rawEnv.trim();
+    if (raw === "")
+        return MCP_OUTPUT_TOKENS_DEFAULT;
+    const n = parseWholeNumber(raw);
+    if (n === undefined || n <= 0) {
+        announceMcpEnvKnob(`MAX_MCP_OUTPUT_TOKENS=${rawEnv} was ignored — it is not a positive whole number of tokens. Using ${MCP_OUTPUT_TOKENS_DEFAULT} instead.`);
+        return MCP_OUTPUT_TOKENS_DEFAULT;
     }
-    return MCP_OUTPUT_TOKENS_DEFAULT;
+    return n;
 }
 function mcpTruncationNote(limitTokens) {
     return (`\n\n[OUTPUT TRUNCATED - exceeded ${limitTokens} token limit]\n\n` +
@@ -100,12 +105,54 @@ export function truncateMcpErrorText(s) {
     return out.length < s.length ? out : s;
 }
 export const MCP_TOOL_TIMEOUT_DEFAULT_MS = 100_000_000;
+export const MCP_ENV_MS_MIN = 1_000;
+export const MCP_ENV_MS_MAX = 2_147_483_647;
+const ENV_SCIENTIFIC_RE = /^[+-]?(\d+(\.\d*)?|\.\d+)[eE][+-]?\d+$/;
+const ENV_GROUPED_RE = /^[+-]?\d{1,3}([_,\u00A0\u202F ])\d{3}(?:\1\d{3})*$/;
+const ENV_GROUP_SEPARATORS_RE = /[_,\u00A0\u202F ]/g;
+const ENV_NUMERIC_MAX_LEN = 32;
+function parseWholeNumber(raw) {
+    if (/^[+-]?\d+$/.test(raw)) {
+        const n = Number(raw);
+        return Number.isSafeInteger(n) ? n : undefined;
+    }
+    if (raw.length > ENV_NUMERIC_MAX_LEN)
+        return undefined;
+    if (ENV_SCIENTIFIC_RE.test(raw)) {
+        const n = Number(raw);
+        return Number.isSafeInteger(n) ? n : undefined;
+    }
+    if (ENV_GROUPED_RE.test(raw))
+        return parseInt(raw.replace(ENV_GROUP_SEPARATORS_RE, ""), 10);
+    return undefined;
+}
+const announcedMcpEnvKnobs = new Set();
+function announceMcpEnvKnob(line) {
+    if (announcedMcpEnvKnobs.has(line))
+        return;
+    announcedMcpEnvKnobs.add(line);
+    console.warn(line);
+}
+export function __resetMcpEnvAnnouncements() {
+    announcedMcpEnvKnobs.clear();
+}
 function parseEnvMs(name) {
-    const raw = process.env[name];
-    if (!raw)
+    const rawEnv = process.env[name];
+    if (rawEnv === undefined)
+        return undefined;
+    const raw = rawEnv.trim();
+    if (raw === "")
         return undefined;
-    const n = parseInt(raw, 10);
-    return Number.isFinite(n) && n > 0 ? n : undefined;
+    const n = parseWholeNumber(raw);
+    if (n === undefined || n <= 0) {
+        announceMcpEnvKnob(`${name}=${rawEnv} was ignored — it is not a positive whole number of milliseconds. Using the built-in default instead.`);
+        return undefined;
+    }
+    const clamped = Math.min(Math.max(n, MCP_ENV_MS_MIN), MCP_ENV_MS_MAX);
+    if (clamped !== n) {
+        announceMcpEnvKnob(`${name}=${rawEnv} is outside the range this runtime can honor (${MCP_ENV_MS_MIN}..${MCP_ENV_MS_MAX} ms). Using ${clamped}ms instead.`);
+    }
+    return clamped;
 }
 export function mcpToolTimeoutMs() {
     return parseEnvMs("MCP_TOOL_TIMEOUT") ?? MCP_TOOL_TIMEOUT_DEFAULT_MS;
@@ -150,7 +197,7 @@ function armMcpIdleWatchdog(health, idleMs, outerSignal) {
         },
     };
 }
-function mcpStartupTimeoutMs() {
+export function mcpStartupTimeoutMs() {
     return parseEnvMs("MCP_TIMEOUT");
 }
 const MCP_SPEC_ERROR_CODE_NAMES = new Map([

package/dist/core/retention-policy.d.ts

@@ -0,0 +1,7 @@
+export interface RetentionPolicyKnobs {
+    maxAgeMs?: number;
+    keep?: number;
+    staleRunningMaxAgeMs?: number;
+    maxEntries?: number;
+}
+export declare function assertRetentionPolicy(label: string, opts: RetentionPolicyKnobs | undefined): void;

package/dist/core/retention-policy.js

@@ -0,0 +1,21 @@
+function invalidPolicy(label, knob, value, requirement) {
+    const e = new Error(`${label}: ${knob} must be ${requirement} (got ${String(value)}) — a retention bound that cannot be evaluated silently decides what to delete instead of bounding it`);
+    e.code = "config.retention_policy_invalid";
+    throw e;
+}
+export function assertRetentionPolicy(label, opts) {
+    if (opts === undefined)
+        return;
+    for (const knob of ["maxAgeMs", "staleRunningMaxAgeMs"]) {
+        const v = opts[knob];
+        if (v !== undefined && (!Number.isFinite(v) || v < 0)) {
+            invalidPolicy(label, knob, v, "a finite, non-negative number of milliseconds");
+        }
+    }
+    for (const knob of ["keep", "maxEntries"]) {
+        const v = opts[knob];
+        if (v !== undefined && (!Number.isInteger(v) || v < 0)) {
+            invalidPolicy(label, knob, v, "a whole number of rows, 0 or more");
+        }
+    }
+}

package/dist/core/runner/active-skill-scope.js

@@ -96,7 +96,7 @@ export function createActiveSkillScopePolicy(opts) {
                             decisionReason: "safety",
                         };
                     }
-                    const canon = await canonicalizeTarget(env, path, signal, rootPath);
+                    const canon = await canonicalizeTarget(env, path, signal, req.cwd ?? rootPath);
                     if (!canon.ok) {
                         return {
                             action: "deny",

package/dist/core/runner/prepare-task.d.ts

@@ -10,6 +10,7 @@ import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
 import type { OnAsk, ToolPolicy } from "../tool-policy.js";
 import { type ActiveSkillFrame } from "./active-skill-scope.js";
 import type { SessionPermissionRules } from "../session-policy-store.js";
+import { type Hooks } from "../hooks.js";
 import { type RecoveredOrphan } from "../session-reconcile.js";
 import { CacheBreakDetector, type ToolFingerprintInput } from "../cache-break-detector.js";
 import { type BrainCallGuardrailRef } from "../../brain/timeout.js";
@@ -330,6 +331,8 @@ export interface InheritedGate {
         policy: ToolPolicy;
         onAsk?: OnAsk;
         durableMandate?: boolean;
+        preToolUse?: Hooks["preToolUse"];
+        hookEnv?: unknown;
     }>;
 }
 export declare function isFableFamilyModelId(id: string): boolean;