@sema-agent/core 5.18.0 → 5.19.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 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**: `parentConstraintCount` gains a screening entry for hook-wired trees — a
+  pending approval checkpoint minted before this change and resumed after (or the reverse)
+  fails pre-CAS with `resume.parent_constraint_mismatch`. **Drain pending checkpoints across
+  the upgrade.** 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
+> two-way-verified against the 5.18.0 artifact by the evaluation line before this release
+> (pre-release criteria [3095], green-lit [3103]).
+
+### BREAKING (vs 5.18.0; both APIs are new in 5.18.0 and cli has not consumed them yet)
+
+- **`confirmRuleApproval` returns `{ ok: true } | { ok: false, reason }`** instead of a bare
+  boolean — seven-member closed reason set (`record_not_found` deliberately covers the
+  foreign-principal arm so record existence does not leak, `selection_missing`,
+  `selection_invalid`, `selection_mismatch`, `batch_takes_no_selection`, `not_pending`,
+  `conflict`). `selectedCandidate` is an integer index.
+- **`prepareCardApproval` refuses caller-supplied `candidates` loudly**
+  (`config.invalid_argument`) instead of silently ignoring them — card options are
+  engine-minted, and a dropped supply attempt is the same silent-narrowing shape this
+  release family removes elsewhere.
+
+### Added
+
+- **`settledBy` on approval settlements** (`"human" | "timeout" | "aborted"`): an optional
+  field on the durable resume outcome's `policy_ask` arm, carried onto the settled call's
+  `tool_end` (top-level key). Out-of-vocabulary values are refused pre-CAS
+  (`checkpoint.invalid_outcome`, `detail.field: "settledBy"` — the row stays pending);
+  `decision: "allow"` accepts only `"human"` or omission (a contradictory record must not
+  become an execution). Core's own arms fill it (elapsed window = `timeout`; abort /
+  unclonable / out-of-contract = `aborted`; human answers = `"human"`); posture arms
+  (headless auto-deny, blanket modes) leave it absent. Absence = an older caller — consumers
+  must not infer semantics from a missing key. New exports: `ApprovalSettledBy`,
+  `APPROVAL_SETTLED_BY_VALUES`, `isApprovalSettledBy`.
+
+### Fixed
+
+- **An elapsed approval window says nobody answered** — the live-deadline refusal no longer
+  borrows the sentence a person's refusal uses; human-refusal and no-provenance wordings are
+  byte-for-byte unchanged (269 existing approval strings verified untouched).
+- **`createAllowDenyPolicy` screens malformed `mcp__` names** (empty segment: `mcp__`,
+  `mcp__a__`) alongside the content form; `mcp__server` / `mcp__server__tool` and the
+  conditionally-retired `Task` spelling stay accepted. The constructor-level retired-name
+  screen added briefly after 5.18.0 was withdrawn — the roster-aware prepare-time audit
+  (`config.legacy_tool_name`, all three kinds) already owns that refusal.
+
 ## 5.18.0 — 2026-08-10
 
 > Two mainline features land together: design/178 personal-assistant memory v1 (the retrieval pair

package/dist/core/checkpoint-store.d.ts

@@ -95,6 +95,7 @@ export type ResumeOutcome = {
     updatedInput?: unknown;
     reason?: string;
     answer?: QuestionAnswer;
+    settledBy?: import("./tool-policy.js").ApprovalSettledBy;
 } | {
     gate: "resource_limit";
     decision: "continue";
@@ -277,10 +278,10 @@ export declare function summarizeCheckpoint(cp: Checkpoint): CheckpointSummary;
 export declare class CheckpointError extends Error {
     readonly code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found" | "checkpoint.gate_mismatch" | "checkpoint.resume_aborted" | "checkpoint.invalid_outcome" | "checkpoint.unsupported_version" | "checkpoint.walltime_axis_retired" | "checkpoint.reopen_revote" | "checkpoint.reopened_concurrently" | "checkpoint.reopen_failed" | "steering.invalid_content" | "steering.queue_full" | "steering.duplicate_input_id" | "wake.gate_pending" | "wake.nothing_to_deliver" | "resume.parent_constraint_missing" | "resume.parent_constraint_mismatch";
     readonly detail?: {
-        field?: "boundCallId" | "boundInputHash" | "answer";
+        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
     } | undefined;
     constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found" | "checkpoint.gate_mismatch" | "checkpoint.resume_aborted" | "checkpoint.invalid_outcome" | "checkpoint.unsupported_version" | "checkpoint.walltime_axis_retired" | "checkpoint.reopen_revote" | "checkpoint.reopened_concurrently" | "checkpoint.reopen_failed" | "steering.invalid_content" | "steering.queue_full" | "steering.duplicate_input_id" | "wake.gate_pending" | "wake.nothing_to_deliver" | "resume.parent_constraint_missing" | "resume.parent_constraint_mismatch", message: string, detail?: {
-        field?: "boundCallId" | "boundInputHash" | "answer";
+        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
     } | undefined);
 }
 export type StoreDurability = "durable" | "process-local";

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,6 +1,6 @@
 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>;
     postToolUse?(toolName: string, input: unknown, output: HookToolOutput, ctx: HookToolContext): PostToolUseResult | undefined | Promise<PostToolUseResult | undefined>;
@@ -104,6 +104,7 @@ export declare function formatHookFeedback(text: string): string;
 export interface ToolGateResult {
     block?: boolean;
     reason?: string;
+    settledBy?: import("./tool-policy.js").ApprovalSettledBy;
     updatedInput?: unknown;
     suspend?: {
         token: import("./checkpoint-store.js").CheckpointToken;
@@ -164,4 +165,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");
 }
@@ -411,9 +443,11 @@ export async function runToolGate(input) {
         if (input.permissionDenied) {
             await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource }), "toolGate.permissionDenied");
         }
+        const denySettledBy = decision.settledBy;
         return {
             block: true,
             reason: formatHookFeedback(denyReason),
+            ...(denySettledBy !== undefined ? { settledBy: denySettledBy } : {}),
             preToolContext,
         };
     }
@@ -422,8 +456,10 @@ export async function runToolGate(input) {
         if (rw !== undefined)
             currentInput = rw;
     }
+    const allowSettledBy = decision.action === "allow" ? decision.settledBy : undefined;
     return {
         updatedInput: currentInput === event.input ? undefined : currentInput,
+        ...(allowSettledBy !== undefined ? { settledBy: allowSettledBy } : {}),
         preToolContext,
     };
 }

package/dist/core/permission-rule-consent.d.ts

@@ -56,7 +56,14 @@ export declare function confirmRuleApproval(opts: {
     principal: string;
     selectedCandidate?: number;
     deps: RuleConsentDeps;
-}): Promise<boolean>;
+}): Promise<ConfirmResult>;
+export type ConfirmRefusalReason = "record_not_found" | "selection_missing" | "selection_invalid" | "selection_mismatch" | "batch_takes_no_selection" | "not_pending" | "conflict";
+export type ConfirmResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: ConfirmRefusalReason;
+};
 export type RedeemResult = {
     status: "redeemed";
     rule: string;

package/dist/core/permission-rule-consent.js

@@ -47,6 +47,11 @@ function parseRuleTicket(ticket) {
 }
 export async function prepareCardApproval(opts) {
     const principal = requirePrincipal(opts.principal, "prepareCardApproval");
+    if ("candidates" in opts) {
+        const e = new Error("prepareCardApproval does not accept caller candidates — card options are minted by the engine from the adjudicated command");
+        e.code = "config.invalid_argument";
+        throw e;
+    }
     if (opts.toolName !== CARD_RULE_TOOL)
         return undefined;
     const scope = opts.scope ?? { kind: "global" };
@@ -70,24 +75,30 @@ export async function prepareCardApproval(opts) {
 const CARD_RULE_TOOL = "Bash";
 export async function confirmRuleApproval(opts) {
     const principal = requirePrincipal(opts.principal, "confirmRuleApproval");
+    const no = (reason) => ({ ok: false, reason });
     const rec = await opts.deps.approvals.get(opts.approvalId);
     if (rec === undefined || rec.principal !== principal)
-        return false;
+        return no("record_not_found");
     if (rec.kind === "card") {
         const chosen = opts.selectedCandidate;
-        if (chosen === undefined || !Number.isInteger(chosen) || rec.candidates[chosen] === undefined)
-            return false;
-        if (rec.state === "approved" || rec.state === "redeemed")
-            return rec.selectedCandidate === chosen;
-        return await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved", selectedCandidate: chosen });
+        if (chosen === undefined)
+            return no("selection_missing");
+        if (!Number.isInteger(chosen) || rec.candidates[chosen] === undefined)
+            return no("selection_invalid");
+        if (rec.state === "approved" || rec.state === "redeemed") {
+            return rec.selectedCandidate === chosen ? { ok: true } : no("selection_mismatch");
+        }
+        const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved", selectedCandidate: chosen });
+        return won ? { ok: true } : no("conflict");
     }
     if (opts.selectedCandidate !== undefined)
-        return false;
+        return no("batch_takes_no_selection");
     if (rec.state === "approved")
-        return true;
+        return { ok: true };
     if (rec.state !== "pending")
-        return false;
-    return await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved" });
+        return no("not_pending");
+    const won = await opts.deps.approvals.cas(rec.id, rec.rev, { ...rec, rev: rec.rev + 1, state: "approved" });
+    return won ? { ok: true } : no("conflict");
 }
 export async function redeemRuleTicket(opts) {
     const principal = requirePrincipal(opts.principal, "redeemRuleTicket");

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";
@@ -64,6 +65,7 @@ export interface Prepared {
         hit: boolean;
     };
     blockedToolCalls: Set<string>;
+    approvalSettledBy: Map<string, import("../tool-policy.js").ApprovalSettledBy>;
     nestedStats: NestedUsageAccum;
     rewindNotes?: NonNullable<TaskResult["rewindNotes"]>;
     cwdRef?: CwdRef;
@@ -329,6 +331,8 @@ export interface InheritedGate {
         policy: ToolPolicy;
         onAsk?: OnAsk;
         durableMandate?: boolean;
+        preToolUse?: Hooks["preToolUse"];
+        hookEnv?: unknown;
     }>;
 }
 export declare function isFableFamilyModelId(id: string): boolean;