@sema-agent/core 7.7.0 → 7.9.0

package/dist/stores/file/permission-rule-store.js

@@ -1,17 +1,18 @@
 import { closeSync, constants as FS, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
+import { isRuleBehavior, readRowBehavior } from "../../core/permission-rule-model.js";
 import { PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, } from "../../core/permission-rule-store.js";
 import { canonicalize } from "../../core/canonical-json.js";
 import { BootLock } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 function isRuleFile(v) {
     const p = v;
-    return typeof p === "object" && p !== null && p.schemaVersion === 3 && Array.isArray(p.rules) && Array.isArray(p.tombstones) && typeof p.rev === "number" && (p.quarantined === undefined || Array.isArray(p.quarantined));
+    return typeof p === "object" && p !== null && p.schemaVersion === 4 && Array.isArray(p.rules) && Array.isArray(p.tombstones) && typeof p.rev === "number" && (p.quarantined === undefined || Array.isArray(p.quarantined));
 }
-function isLegacyRuleFile(v) {
+function isOlderRuleFile(v) {
     const p = v;
-    return typeof p === "object" && p !== null && (p.schemaVersion === 1 || p.schemaVersion === 2) && Array.isArray(p.rules) && Array.isArray(p.tombstones) && typeof p.rev === "number";
+    return typeof p === "object" && p !== null && (p.schemaVersion === 1 || p.schemaVersion === 2 || p.schemaVersion === 3) && Array.isArray(p.rules) && Array.isArray(p.tombstones) && typeof p.rev === "number";
 }
 function isOrgStateFile(v) {
     const p = v;
@@ -24,7 +25,7 @@ function jsonForm(v) {
     return JSON.parse(JSON.stringify(v));
 }
 export const ORG_STATE_FILE = "org.json";
-export const SCHEMA3_MARKER_FILE = ".rule-schema-3";
+export const SCHEMA_MARKER_FILE = ".rule-schema-4";
 export class OrgRevisionRefusal extends Error {
 }
 const LOCAL_OWNER_FILE = "local-owner.json";
@@ -158,8 +159,8 @@ class FileDurableRulePartition {
         }
         if (!isRuleFile(parsed)) {
             const sv = schemaVersionWord(parsed);
-            const why = sv === 1 || sv === 2
-                ? `${this.file} is a schema ${String(sv)} bucket that was not migrated to schema 3 (written by an older engine after this directory was migrated?); refusing the whole file and loading zero rules`
+            const why = sv === 1 || sv === 2 || sv === 3
+                ? `${this.file} is a schema ${String(sv)} bucket that was not migrated to schema 4 (written by an older engine after this directory was migrated?); refusing the whole file and loading zero rules`
                 : `${this.file} does not carry a readable rule-file shape; refusing the whole file and loading zero rules`;
             this.disclose(why);
             return { unreadable: why };
@@ -170,6 +171,19 @@ class FileDurableRulePartition {
             this.disclose(why);
             return { unreadable: why };
         }
+        const rowKinds = [
+            ["rule", parsed.rules],
+            ["tombstone", parsed.tombstones],
+            ["quarantined", parsed.quarantined ?? []],
+        ];
+        for (const [kind, rows] of rowKinds) {
+            const bad = rows.findIndex((r) => !isRuleBehavior(r?.behavior));
+            if (bad !== -1) {
+                const why = `${this.file} carries a ${kind} row (#${bad}) whose behavior word is outside deny/ask/allow — a schema 4 row must name its behavior; refusing the whole file and loading zero rules`;
+                this.disclose(why);
+                return { unreadable: why };
+            }
+        }
         return { file: parsed };
     }
     disclose(message) {
@@ -218,7 +232,7 @@ class FileDurableRulePartition {
             throw new Error(`refusing to write the permission-rule store while it cannot be read: ${r.unreadable}`);
         }
         if ("absent" in r) {
-            return { schemaVersion: 3, actor: `file-${randomBytes(6).toString("hex")}`, counter: 0, rev: 0, rules: [], tombstones: [] };
+            return { schemaVersion: 4, actor: `file-${randomBytes(6).toString("hex")}`, counter: 0, rev: 0, rules: [], tombstones: [] };
         }
         return {
             schemaVersion: r.file.schemaVersion,
@@ -324,7 +338,7 @@ export class FileDurableRulePartitionProvider {
     migrateLegacyBuckets() {
         if (!existsSync(this.dir))
             return;
-        if (existsSync(join(this.dir, SCHEMA3_MARKER_FILE)))
+        if (existsSync(join(this.dir, SCHEMA_MARKER_FILE)))
             return;
         try {
             assertSafeDir(this.dir);
@@ -359,7 +373,7 @@ export class FileDurableRulePartitionProvider {
                     legacy.push({ name, file: read });
             }
             if (legacy.length === 0) {
-                this.writeSchema3Marker();
+                this.writeSchemaMarker();
                 return;
             }
             const orgHome = this.fileOrgPersistence();
@@ -380,12 +394,18 @@ export class FileDurableRulePartitionProvider {
                         }
                     }
                 }
-                const next = { ...rest, schemaVersion: 3 };
+                const stamped = stampRowBehaviors(rest);
+                if (stamped === undefined) {
+                    complete = false;
+                    this.onError?.(`bucket ${name} left untouched: a row carries a behavior word outside deny/ask/allow, which no engine version wrote; the file is not migrated`);
+                    continue;
+                }
+                const next = { ...stamped, schemaVersion: 4 };
                 atomicPublish(this.dir, join(this.dir, name), JSON.stringify({ ...next, checksum: checksumOf(next) }, null, 2));
-                this.onError?.(`migrated ${name} to rule-file schema 3${org !== undefined ? ` (its org block moved to ${ORG_STATE_FILE})` : ""}`);
+                this.onError?.(`migrated ${name} to rule-file schema 4${org !== undefined ? ` (its org block moved to ${ORG_STATE_FILE})` : ""}`);
             }
             if (complete)
-                this.writeSchema3Marker();
+                this.writeSchemaMarker();
         }
         finally {
             if (!held) {
@@ -394,12 +414,12 @@ export class FileDurableRulePartitionProvider {
             }
         }
     }
-    writeSchema3Marker() {
+    writeSchemaMarker() {
         try {
-            atomicPublish(this.dir, join(this.dir, SCHEMA3_MARKER_FILE), JSON.stringify({ schemaVersion: 3 }));
+            atomicPublish(this.dir, join(this.dir, SCHEMA_MARKER_FILE), JSON.stringify({ schemaVersion: 4 }));
         }
         catch (err) {
-            this.onError?.(`could not write ${SCHEMA3_MARKER_FILE}: ${err.message}; the legacy scan will run again next construction`);
+            this.onError?.(`could not write ${SCHEMA_MARKER_FILE}: ${err.message}; the legacy scan will run again next construction`);
         }
     }
     orgStatePersistence() {
@@ -449,6 +469,34 @@ export class FileDurableRulePartitionProvider {
         this.lock = undefined;
     }
 }
+function stampRowBehaviors(body) {
+    const rules = [];
+    for (const r of body.rules) {
+        const behavior = readRowBehavior(r.behavior);
+        if (behavior === undefined)
+            return undefined;
+        rules.push({ ...r, behavior });
+    }
+    const tombstones = [];
+    for (const t of body.tombstones) {
+        const behavior = readRowBehavior(t.behavior);
+        if (behavior === undefined)
+            return undefined;
+        tombstones.push({ ...t, behavior });
+    }
+    let quarantined;
+    if (body.quarantined !== undefined) {
+        quarantined = [];
+        for (const q of body.quarantined) {
+            const behavior = readRowBehavior(q.behavior);
+            if (behavior === undefined)
+                return undefined;
+            quarantined.push({ ...q, behavior });
+        }
+    }
+    const { rules: _r, tombstones: _t, quarantined: _q, ...rest } = body;
+    return { ...rest, rules, tombstones, ...(quarantined !== undefined ? { quarantined } : {}) };
+}
 function readLegacyBucket(file) {
     let raw;
     try {
@@ -467,7 +515,7 @@ function readLegacyBucket(file) {
     catch {
         return undefined;
     }
-    if (!isLegacyRuleFile(parsed))
+    if (!isOlderRuleFile(parsed))
         return undefined;
     const { checksum, ...body } = parsed;
     return checksum === checksumOf(body) ? parsed : undefined;

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -80,7 +80,7 @@ export interface LeadingCommandNameOptions {
      * name instead of refusing it.
      *
      * OPT-IN, and used by ONE family of callers: the persisted permission-RULE lane
-     * ({@link import("../../core/permission-rule-model.js").parseAllowRuleText} and its matcher), where
+     * ({@link import("../../core/permission-rule-model.js").parseRuleText} and its matcher), where
      * both sides of the comparison are literal text a person read on an approval card. The refusal this
      * option lifts exists for the argv[0]-NAME filters (the read-only allowlist, the coarse
      * command-name policy, the skill specifier): those compare a bare token against a name set, and a

package/dist/tools/fs/fs-bash.d.ts

@@ -62,7 +62,7 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  * the read-only allowlist face (`core.bash_readonly@1`). Consumed by prepare-task's
  * fullShellReachable roster assertion (its first load-bearing consumer).
  */
-export declare const FULL_SHELL_CONTRACT_ID = "core.bash@1";
+export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
 /** The CC-verbatim exit-1 interpretation for `command`, or undefined when exit 1 means a real error.
  *  Conservative parse: last `;`/`&&`/`||`/newline statement → last `|` pipeline segment → leading
  *  command name (env-assignments skipped, path prefix stripped); `git grep`/`git diff` special-cased

package/dist/tools/fs/fs-bash.js

@@ -2,7 +2,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { defaultTaskRegistry } from "../../core/task-registry.js";
 import { accountDroppedBytes, spoolDropNote } from "../../core/task-registry-shared.js";
-import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_CONTRACT, TASK_STOP_CONTRACT, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, ENV_DIRECT_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "../../core/task-tool-shape.js";
+import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, ENV_DIRECT_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "../../core/task-tool-shape.js";
 import { hasBackgroundShell } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
@@ -12,6 +12,7 @@ import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
 import { PROBE_CAUSE_PATH_MAX, inlineUntrusted } from "../../core/untrusted-text.js";
 import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
+import { toolFace } from "../../core/tool-catalog-entries.js";
 const RECURSIVE_CAUSE_MAX_PATHS = 3;
 const RECURSIVE_READ_CAUSE_CODE = "shell.recursive_read_unbounded";
 function operandFamily(paths) {
@@ -58,7 +59,7 @@ export function bashReversibilityProbe(allow, boundary) {
             : { reversible: false, ...outOfRootGate() };
     };
 }
-export const FULL_SHELL_CONTRACT_ID = "core.bash@1";
+export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";
 const EXIT1_INTERPRETATION = {
     grep: "No matches found",
     rg: "No matches found",
@@ -537,7 +538,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
     const bgEnvIsolatedOwned = hasDestroy(env) && isIsolated(env);
     return defineTool({
         name: "Bash",
-        contract: { contractId: FULL_SHELL_CONTRACT_ID, implementationRevision: "1" },
+        ...toolFace("bash"),
         description: bashDescription(coAuthor, timeoutCaps, bgNotifies, bgRetained, bgSessionScoped, bgEnvIsolatedOwned),
         parameters: Type.Object({
             command: Type.String({ description: "The command to execute" }),
@@ -559,8 +560,6 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                 description: "Set to true to run this command in the background.",
             })),
         }),
-        effect: "write",
-        contentOrigin: "execution",
         isConcurrencySafe: (args) => {
             const cmd = args?.command;
             if (typeof cmd !== "string")
@@ -991,7 +990,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
     const canonicalBoundary = createCanonicalReadBoundary(env, readRoots);
     return defineTool({
         name: "Bash",
-        contract: { contractId: "core.bash_readonly@1", implementationRevision: "1" },
+        ...toolFace("bash-readonly"),
         description: `Run a SINGLE read-only inspection command (e.g. ${sample}, …) and return its output. Shell ` +
             "operators (pipes, redirects, ;, &&, command substitution, subshells) are rejected and only " +
             "allowlisted commands run. Reads are confined to the workspace root(s): a path outside them is " +
@@ -1002,7 +1001,6 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
             command: Type.String({ description: "A single allowlisted read-only command (no shell operators)." }),
             timeout: Type.Optional(Type.Number({ description: bashTimeoutParamDescription(timeoutCaps, true) })),
         }),
-        effect: "read",
         execute: async (args, ctx) => {
             const { command, timeout } = args;
             const timeoutRefusal = bashTimeoutArgRefusal(timeout, timeoutCaps);
@@ -1035,10 +1033,9 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
 export function createEnvTaskOutputTool(env) {
     return defineTool({
         name: TASK_OUTPUT_TOOL_NAME,
-        contract: TASK_OUTPUT_CONTRACT,
+        ...toolFace("task-output-hands"),
         description: composeTaskOutputDescription(ENV_DIRECT_TASK_TOOL_CAPS),
         parameters: composeTaskOutputParams(ENV_DIRECT_TASK_TOOL_CAPS),
-        effect: "read",
         execute: async (args) => {
             const { task_id, filter } = args;
             const id = resolveTaskIdArg(task_id);
@@ -1073,10 +1070,9 @@ export function createEnvTaskOutputTool(env) {
 export function createEnvTaskStopTool(env, registry = defaultTaskRegistry) {
     return defineTool({
         name: TASK_STOP_TOOL_NAME,
-        contract: TASK_STOP_CONTRACT,
+        ...toolFace("task-stop-hands"),
         description: composeTaskStopDescription(ENV_DIRECT_TASK_TOOL_CAPS),
         parameters: TASK_STOP_PARAMS,
-        effect: "write",
         execute: async (args) => {
             const { task_id, shell_id } = args;
             const id = resolveTaskIdArg(task_id, shell_id);

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

@@ -29,7 +29,7 @@ type ReadPdfReturn = string | {
  *   downsampler seam then applies the same pipeline as the Read image branch). poppler absent → HONEST
  *   degradation with the working alternative, never a fake success.
  * Wire discipline: the base64 payload rides `details.file` only while ≤48K chars (same OMIT rule as the
- * image variant — a bigger card would be dropped whole by the structuredFrom 4×cap and blind the shell).
+ * image variant — a bigger card would be dropped whole by the card projector's 4×cap and blind the shell).
  * structured-card audit item B (2026-08-05): that budget management assumed `"document"` was on `CC_DETAIL_TYPES`, which
  * it was not — every `document` card, sized or not, was dropped at the gate, making the 48K rule dead
  * code and the pages/fallback-level disclosure invisible to a host. The word is registered now.

package/dist/tools/fs/fs-read.js

@@ -9,6 +9,7 @@ import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, MAX_IMAGE_READ_BYTES, MAX_IMAGE_
 import { readPdfFile, pdfResultToToolReturn } from "./fs-pdf.js";
 import { openSystemReminder } from "../../core/reminder-mint.js";
 import { discloseReminderShaped } from "../../core/reminder-disclosure.js";
+import { toolFace } from "../../core/tool-catalog-entries.js";
 export function createReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption, readCyberReminder, readDeny, readFace, reminderMark, reminderDisclosureCounts) {
     const cyberReminder = readCyberReminder === false ? "" : readCyberReminderText(reminderMark);
     const reminderDisclosureWindows = new Map();
@@ -23,7 +24,7 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
         : "- `file_path` may be relative (resolved against the tracked working directory) or absolute (within the configured roots).\n";
     return defineTool({
         name: "Read",
-        contract: { contractId: "core.read@1", implementationRevision: "1" },
+        ...toolFace("read"),
         description: "Reads a file from the local filesystem.\n" +
             "\n" +
             pathBoundLine +
@@ -55,7 +56,6 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             limit: Type.Optional(Type.Integer({ minimum: 1, description: "The number of lines to read. Only provide if the file is too large to read at once. (Default: the whole file, bounded by the output-token cap.)" })),
             pages: Type.Optional(Type.String({ description: `Page range for PDF files (e.g., "1-5", "3", "10-20"). Only applicable to PDF files. Maximum ${PDF_MAX_PAGES_PER_READ} pages per request.` })),
         }),
-        effect: "read",
         execute: async (args, ctx) => {
             const { offset, limit, pages } = args;
             const path = fileArgPath(args);

package/dist/tools/fs/fs-search-tools.d.ts

@@ -1,5 +1,4 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import type { ToolEffect } from "../../core/types.js";
 import type { ReadDenyMatcher } from "./read-deny.js";
 import type { ReadFace } from "./read-face.js";
 /**
@@ -13,9 +12,3 @@ import type { ReadFace } from "./read-face.js";
 export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number, structuredRows?: readonly import("./search.js").GrepRow[]): Record<string, unknown>;
 export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;
 export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;
-/** Static side-effect class of every hand tool, by name (design/44 §3). Used by prepare-task to (a) feed
- *  wake/resume reconciliation and (b) drive the verifier read-only boundary. Every mutating hand tool is
- *  `write` (RB-264 ⑥W1 folded `Write` back in — see below); `bash` is `write` (a command can do anything);
- *  `bash_readonly` is `read` (so it survives the verifier boundary — but still goes through the policy
- *  gate, council #7: effect:read is a redo-safety class, never a policy circumvention). */
-export declare const HAND_TOOL_EFFECTS: Readonly<Record<string, ToolEffect>>;

package/dist/tools/fs/fs-search-tools.js

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { resolveKey, violationText, violationDetails } from "./safety.js";
 import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern, invalidGlobTokens } from "./search.js";
+import { toolFace } from "../../core/tool-catalog-entries.js";
 export function grepDetailFields(text, mode, offset, structuredRows) {
     const structuredIdentityComplete = structuredRows !== undefined && structuredRows.every((r) => r.path !== undefined || r.text === "--");
     const structuredPaths = structuredIdentityComplete && structuredRows !== undefined ? [...new Set(structuredRows.filter((r) => r.path !== undefined).map((r) => r.path))] : undefined;
@@ -74,7 +75,7 @@ export function grepDetailFields(text, mode, offset, structuredRows) {
 export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, readFace) {
     return defineTool({
         name: "Grep",
-        contract: { contractId: "core.grep@1", implementationRevision: "1" },
+        ...toolFace("grep"),
         description: "Content search built on ripgrep. Prefer this over `grep`/`rg` via Bash — results integrate with the permission UI and file links.\n" +
             "\n" +
             '- Full regex syntax (e.g. "log.*Error", "function\\s+\\w+"). Ripgrep, not grep — escape literal braces (`interface\\{\\}`).\n' +
@@ -107,7 +108,6 @@ export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, re
             })),
             offset: Type.Optional(Type.Number({ description: "Skip the first N output lines (pagination partner of head_limit)." })),
         }),
-        effect: "read",
         execute: async (args, ctx) => {
             const retired = args;
             for (const [name, repair] of [
@@ -175,7 +175,7 @@ export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, re
 export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, readFace) {
     return defineTool({
         name: "Glob",
-        contract: { contractId: "core.glob@1", implementationRevision: "1" },
+        ...toolFace("glob"),
         description: 'Fast file pattern matching. Supports glob patterns like "**/*.js" or "src/**/*.ts". Returns matching file paths sorted by modification time.\n' +
             "\n" +
             "- On environments that do not report modification times, results fall back to alphabetical order\n" +
@@ -194,7 +194,6 @@ export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, re
             })),
             max_results: Type.Optional(Type.Number({ description: "Cap results (default 500)." })),
         }),
-        effect: "read",
         execute: async (args, ctx) => {
             let { pattern, path } = args;
             const { max_results } = args;
@@ -222,15 +221,3 @@ export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, re
         },
     });
 }
-export const HAND_TOOL_EFFECTS = {
-    Read: "read",
-    Edit: "write",
-    Write: "write",
-    NotebookEdit: "write",
-    Grep: "read",
-    Glob: "read",
-    RepoMap: "read",
-    Bash: "write",
-    TaskOutput: "read",
-    TaskStop: "write",
-};

package/dist/tools/fs/fs-write.js

@@ -4,6 +4,7 @@ import { defineTool, errorResult } from "../../core/tools.js";
 import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, applyRecordedEdit, } from "./fs-shared.js";
+import { toolFace } from "../../core/tool-catalog-entries.js";
 async function envFinalWrite(env, key, content, signal, opts) {
     const fireEdited = () => {
         if (opts?.edited?.hook === undefined)
@@ -88,7 +89,7 @@ async function gateToolWrite(hook, tool, path, key, content) {
 export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
     return defineTool({
         name: "Edit",
-        contract: { contractId: "core.edit@1", implementationRevision: "1" },
+        ...toolFace("edit"),
         description: "Performs exact string replacement in a file.\n" +
             "\n" +
             "- You must Read the file in this conversation before editing, or the call will fail.\n" +
@@ -101,7 +102,6 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
             new_string: Type.Optional(Type.String({ description: "The text to replace it with (must be different from old_string)" })),
             replace_all: Type.Optional(Type.Boolean({ description: "Replace all occurrences of old_string (default false)" })),
         }),
-        effect: "write",
         validateInput: async (args, ctx) => {
             const a = args;
             if (Array.isArray(a.edits) && a.edits.length > 0)
@@ -327,7 +327,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
 export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
     return defineTool({
         name: "Write",
-        contract: { contractId: "core.write@1", implementationRevision: "1" },
+        ...toolFace("write"),
         description: "Writes a file to the local filesystem, overwriting if one exists.\n" +
             "\n" +
             "When to use: creating a new file, or fully replacing one you've already Read. Overwriting an existing " +
@@ -337,7 +337,6 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             ...FILE_PATH_PARAMS,
             content: Type.String({ description: "The content to write to the file" }),
         }),
-        effect: "write",
         validateInput: async (args, ctx) => {
             const path = fileArgPath(args);
             if (path === undefined)
@@ -427,7 +426,7 @@ const NOTEBOOK_CELL_ID_REQUIRED_MESSAGE = `Error (NotebookEdit): cell_id is requ
 export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit, onEdited) {
     return defineTool({
         name: "NotebookEdit",
-        contract: { contractId: "core.notebook_edit@1", implementationRevision: "1" },
+        ...toolFace("notebook-edit"),
         description: "Replaces, inserts, or deletes a single cell in a Jupyter notebook (.ipynb file).\n" +
             "\n" +
             "Usage:\n" +
@@ -449,7 +448,6 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 description: "The type of edit to make (replace, insert, delete). Defaults to replace.",
             })),
         }),
-        effect: "write",
         validateInput: async (args, ctx) => {
             const a = args;
             const mode = a.edit_mode ?? "replace";

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

@@ -92,5 +92,5 @@ export interface NotebookRender {
 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
  *  carries raw image bytes (they ride the model-facing content blocks; an oversized card would be
- *  omitted whole by the structuredFrom 4×cap and blind the shell). */
+ *  omitted whole by the card projector's 4×cap and blind the shell). */
 export declare function stripNotebookImageData(cell: NotebookCell): NotebookCell;

package/dist/tools/fs/repo-map.js

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { resolveKey, violationText, violationDetails } from "./safety.js";
 import { buildIgnore, denyWithheldNote, walk, walkIsPartial } from "./search.js";
+import { toolFace } from "../../core/tool-catalog-entries.js";
 const DEFAULT_MAX_CHARS = 16_000;
 const DEFAULT_MAX_FILES = 400;
 const FILE_SCAN_MAX_BYTES = 256 * 1024;
@@ -82,7 +83,7 @@ function rankEntries(a, b) {
 export function createRepoMapTool(env, rootCanonical, additionalRoots, readDeny, readFace) {
     return defineTool({
         name: "RepoMap",
-        contract: { contractId: "core.repo_map@1", implementationRevision: "1" },
+        ...toolFace("repo-map"),
         description: "Get a compact map of the repository: each source file with its top-level symbols (functions, " +
             "classes, types). Use this FIRST to orient in an unfamiliar codebase before grepping — it shows " +
             "what exists and where, so you can jump to the relevant files. Token-budgeted and honest about " +
@@ -92,7 +93,6 @@ export function createRepoMapTool(env, rootCanonical, additionalRoots, readDeny,
             max_chars: Type.Optional(Type.Number({ description: `Token budget for the rendered map in chars (default ${DEFAULT_MAX_CHARS}; a very small value yields only a truncation note).` })),
             max_files: Type.Optional(Type.Number({ description: `Max files to scan (default ${DEFAULT_MAX_FILES}).` })),
         }),
-        effect: "read",
         execute: async (args, ctx) => {
             const a = args;
             const signal = ctx.signal;

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

@@ -1,4 +1,5 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+import { protectivePathTargetOf, type ToolCallLike } from "../../core/tool-registry.js";
 /**
  * batch-B (CC 2.1.187 parity): Read/Edit/Write take the file path as `file_path`. Read the target the same way
  * EVERYWHERE the path is consumed from a tool-call's args — not just the tool body but ALSO every gate that
@@ -28,7 +29,7 @@ export declare function fileArgPath(args: unknown): string | undefined;
  * this module stays dependency-free of the alias table — "NotebookEdit" is the canonical CC name and
  * old→new normalization is identity for it).
  */
-export declare function writeTargetPath(canonicalName: string, args: unknown): string | undefined;
+export declare function writeTargetPath(call: ToolCallLike, pt?: ReturnType<typeof protectivePathTargetOf>): string | undefined;
 /**
  * The "hand" file tools (design/44) — safety invariants ported from CC's `FileEditTool` (design/43 Rule
  * 7): without these a weak model blind-edits / overwrites files (P0 safety, not polish). This module is
@@ -320,7 +321,7 @@ export declare function violationText(toolName: string, v: FsViolation): string;
  * every renderer of a {@link resolveKey} violation — `undefined` keeps the pre-existing detail-less
  * shape for all other violation codes, so nothing else changes byte-wise.
  *
- * RB-397-c (回溯复查批): `type` is the WIRE discriminator — `structuredFrom`'s `CC_DETAIL_TYPES` gate
+ * RB-397-c (回溯复查批): `type` is the WIRE discriminator — the leg's card projector (`createStructuredProjector`, design/388 L4)
  * (tool-output-projection.ts) keys on `details.type`, so without it the card never reached
  * `tool_end.structured` and the "count from fields" promise above held for in-process readers only.
  * `code` stays as-is for the existing RB-371 consumers — the new key is strictly additive.

package/dist/tools/fs/safety.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
+import { pathTargetValue, protectivePathTargetOf } from "../../core/tool-registry.js";
 export function fileArgPath(args) {
     const a = args;
     const fp = a?.file_path;
@@ -8,12 +9,12 @@ export function fileArgPath(args) {
     const p = a?.path;
     return typeof p === "string" && p.length > 0 ? p : undefined;
 }
-export function writeTargetPath(canonicalName, args) {
-    const np = args?.notebook_path;
+export function writeTargetPath(call, pt = protectivePathTargetOf(call)) {
+    if (pt !== undefined)
+        return pathTargetValue(call.args, pt);
+    const np = call.args?.notebook_path;
     const notebook = typeof np === "string" && np.length > 0 ? np : undefined;
-    if (canonicalName === "NotebookEdit")
-        return notebook ?? fileArgPath(args);
-    return fileArgPath(args) ?? notebook;
+    return fileArgPath(call.args) ?? notebook;
 }
 export function sha256(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");

package/dist/tools/monitor.js

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../core/tools.js";
 import { hasBackgroundShell } from "../core/background-shell.js";
 import { MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, } from "../core/task-registry.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its stdout as a stream of events.\n" +
     "\n" +
     "- Each line the command writes to stdout becomes a notification event delivered to you between turns; " +
@@ -42,7 +43,7 @@ function envBackgroundWallSec(caps, requestedSec) {
 export function createMonitorTool(env, opts) {
     return defineTool({
         name: "Monitor",
-        contract: { contractId: "core.monitor@1", implementationRevision: "1" },
+        ...toolFace("monitor"),
         description: MONITOR_DESCRIPTION,
         parameters: Type.Object({
             command: Type.String({
@@ -58,7 +59,6 @@ export function createMonitorTool(env, opts) {
                 description: "Set to true for a session-resident monitor with no watch timeout of its own (default false). It keeps watching until the execution environment's background time budget expires, until you stop it with TaskStop, or until the session ends.",
             })),
         }),
-        effect: "write",
         execute: async (args, ctx) => {
             const { command, description, timeout_ms, persistent } = args;
             if (!hasBackgroundShell(env)) {

package/dist/tools/scheduler-tools.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../core/tools.js";
 import { hasScheduler, isValidCronExpr, } from "../core/scheduler.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export const SCHEDULE_WAKEUP_TOOL_NAME = "ScheduleWakeup";
 export const AUTONOMOUS_LOOP_SENTINEL = "<<autonomous-loop>>";
 export const AUTONOMOUS_LOOP_DYNAMIC_SENTINEL = "<<autonomous-loop-dynamic>>";
@@ -199,7 +200,7 @@ Every user who asks for "9am" gets \`0 9\`, and every user who asks for "hourly"
 Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past", coordinating with a meeting). When in doubt, nudge a few minutes early or late — the user will not notice, and the fleet will.`;
     const cronCreate = defineTool({
         name: "CronCreate",
-        contract: { contractId: "core.cron_create@1", implementationRevision: "1" },
+        ...toolFace("cron-create"),
         description: cronCreateDescription,
         parameters: Type.Object({
             prompt: Type.String({ description: "Self-contained instructions for the future task (it runs unattended)." }),
@@ -222,7 +223,6 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
             })),
             label: Type.Optional(Type.String({ description: "Short label (also a dedup key with the schedule)." })),
         }),
-        effect: "write",
         execute: async (args) => serializedCronCreateOp(async () => {
             const a = args;
             if (a.schedule !== undefined && a.cron !== undefined) {
@@ -305,10 +305,9 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
     };
     const cronCancel = defineTool({
         name: "CronDelete",
-        contract: { contractId: "core.cron_delete@1", implementationRevision: "1" },
+        ...toolFace("cron-delete"),
         description: "Cancel a cron job previously scheduled with CronCreate. Idempotent; ids also appear in CronList.",
         parameters: Type.Object({ id: Type.String({ description: "Job ID returned by CronCreate." }) }),
-        effect: "idempotent",
         execute: async (args) => {
             const { id } = args;
             const taskId = id;
@@ -329,10 +328,9 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
     });
     const cronList = defineTool({
         name: "CronList",
-        contract: { contractId: "core.cron_list@1", implementationRevision: "1" },
+        ...toolFace("cron-list"),
         description: "List all cron jobs scheduled via CronCreate (id, when, label).",
         parameters: Type.Object({}),
-        effect: "read",
         execute: async () => {
             const rows = [];
             const seen = new Set();
@@ -409,7 +407,7 @@ MOUNT NOTE: this host has no resident wakeup leg, so ${SCHEDULE_WAKEUP_TOOL_NAME
 MOUNT NOTE: this host does not vouch for session-scoped scheduling, so a wakeup scheduled here is PERSISTENT — contrary to the paragraph above, it can outlive this session instead of ending with it. End the loop explicitly with \`stop: true\` when the work is done; do not rely on the session ending to cancel it.`;
     const scheduleWakeup = defineTool({
         name: SCHEDULE_WAKEUP_TOOL_NAME,
-        contract: { contractId: "core.schedule_wakeup@1", implementationRevision: "1" },
+        ...toolFace("schedule-wakeup"),
         description: `${SCHEDULE_WAKEUP_PROMPT}${wakeupMountNote}`,
         parameters: Type.Object({
             delaySeconds: Type.Optional(Type.Number({
@@ -428,7 +426,6 @@ MOUNT NOTE: this host does not vouch for session-scoped scheduling, so a wakeup
                 description: "true = nothing changed (you checked and there is nothing to report). false = something happened worth keeping (edited a file, posted a message, advanced state, surfaced a finding). Consecutive noop:true ticks are collapsed in the user's terminal view and tracked as a streak. Required unless `stop` is true.",
             })),
         }),
-        effect: "write",
         execute: async (args) => serializedWakeupOp(async () => {
             const a = args;
             if (a.stop === true) {