@sema-agent/core 7.6.3 → 7.8.0

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/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

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) {

package/dist/tools/task-list.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { toolFace } from "../core/tool-catalog-entries.js";
 const STATUS = Type.Union([
     Type.Literal("pending"),
     Type.Literal("in_progress"),
@@ -96,7 +97,7 @@ export function createTaskListTools(store) {
     const tasks = store ?? createMemoryTaskListStore();
     const taskCreate = {
         name: "TaskCreate",
-        contract: { contractId: "core.task_create@1", implementationRevision: "1" },
+        ...toolFace("task-create"),
         description: "Use this tool to create a structured task list for your current session. This helps you track progress, organize complex tasks, and demonstrate thoroughness.\n" +
             "It also helps the user understand the progress of the task and overall progress of their requests.\n" +
             "\n" +
@@ -144,7 +145,6 @@ export function createTaskListTools(store) {
             activeForm: Type.Optional(Type.String({ description: 'Present continuous form shown when in_progress (e.g., "Running tests")' })),
             metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Arbitrary metadata to attach to the task" })),
         }),
-        effect: "write",
         execute: (args) => serialized(tasks, async (tx) => {
             const a = args;
             if (a.metadata)
@@ -169,7 +169,7 @@ export function createTaskListTools(store) {
     };
     const taskGet = {
         name: "TaskGet",
-        contract: { contractId: "core.task_get@1", implementationRevision: "1" },
+        ...toolFace("task-get"),
         description: "Use this tool to retrieve a task by its ID from the task list.\n" +
             "\n" +
             "## When to Use This Tool\n" +
@@ -189,7 +189,6 @@ export function createTaskListTools(store) {
         parameters: Type.Object({
             taskId: Type.String({ description: "The ID of the task to retrieve" }),
         }),
-        effect: "read",
         execute: (args) => serialized(tasks, async (tx) => {
             const id = String(args.taskId);
             const t = await tx.get(id);
@@ -201,7 +200,7 @@ export function createTaskListTools(store) {
     };
     const taskUpdate = {
         name: "TaskUpdate",
-        contract: { contractId: "core.task_update@1", implementationRevision: "1" },
+        ...toolFace("task-update"),
         description: "Use this tool to update a task in the task list.\n" +
             "\n" +
             "## When to Use This Tool\n" +
@@ -285,7 +284,6 @@ export function createTaskListTools(store) {
             addBlocks: Type.Optional(Type.Array(Type.String(), { description: "Task IDs that this task blocks" })),
             addBlockedBy: Type.Optional(Type.Array(Type.String(), { description: "Task IDs that block this task" })),
         }),
-        effect: "idempotent",
         execute: (args) => serialized(tasks, async (tx) => {
             const a = args;
             const id = String(a.taskId);
@@ -395,7 +393,7 @@ export function createTaskListTools(store) {
     };
     const taskList = {
         name: "TaskList",
-        contract: { contractId: "core.task_list@1", implementationRevision: "1" },
+        ...toolFace("task-list"),
         description: "Use this tool to list all tasks in the task list.\n" +
             "\n" +
             "## When to Use This Tool\n" +
@@ -420,7 +418,6 @@ export function createTaskListTools(store) {
             "\n" +
             "Use TaskGet with a specific task ID to view full details including description and metadata.",
         parameters: Type.Object({}),
-        effect: "read",
         execute: () => serialized(tasks, async (tx) => {
             const all = await tx.list();
             if (all.length === 0) {

package/dist/tools/todo.js

@@ -1,10 +1,11 @@
 import { Type } from "typebox";
 import { errorResult } from "../core/tools.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export function createTodoWriteTool() {
     let todos = [];
     return {
         name: "TodoWrite",
-        contract: { contractId: "core.todo_write@1", implementationRevision: "1" },
+        ...toolFace("todo-write"),
         description: "Create and update a task list for the current session. The list is rendered to the user as your working plan.\n" +
             "\n" +
             '- Each todo has `content`, `status` ("pending" | "in_progress" | "completed"), and `activeForm` (present-tense label shown while in progress).\n' +
@@ -80,7 +81,6 @@ export function createTodoWriteTool() {
                 activeForm: Type.String({ minLength: 1, description: "Present-continuous form shown while in progress (e.g. \"Running the tests\")." }),
             })),
         }),
-        effect: "idempotent",
         execute: (args) => {
             const shape = (t) => ({ content: t.content, status: t.status, activeForm: t.activeForm });
             const oldTodos = todos.map(shape);

package/dist/tools/web.js

@@ -7,6 +7,7 @@ import { isPrivateHost } from "../core/runner/image.js";
 import { DEFAULT_CHARS_PER_TOKEN } from "../internal/harness.js";
 import { binaryMagicFormat } from "./fs/safety.js";
 import { pdfMagicMatches } from "./fs/pdf.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 const MAX_REDIRECTS = 10;
 const MAX_URL_LENGTH = 2048;
 const WEBFETCH_ACCEPT = "text/markdown, text/html, */*";
@@ -262,7 +263,7 @@ export function webFetchToolSpec(config = {}) {
     const canSummarize = config.summarize !== undefined;
     return {
         name: "WebFetch",
-        contract: { contractId: "core.web_fetch@1", implementationRevision: "1" },
+        ...toolFace("web-fetch"),
         description: (canSummarize
             ? "Fetches a URL, converts the page to markdown, and answers `prompt` against it with a sub-model.\n"
             : "Fetches a URL, converts the page to markdown, and returns the markdown. This deployment has no " +
@@ -278,8 +279,6 @@ export function webFetchToolSpec(config = {}) {
                 ? { prompt: Type.Optional(Type.String({ description: "The prompt to run on the fetched content (answered by the configured sub-model)." })) }
                 : {}),
         }),
-        effect: "read",
-        contentOrigin: "external",
         execute: async (args, ctx) => {
             const { url, prompt } = args;
             const startedAt = Date.now();
@@ -844,7 +843,7 @@ export function createWebSearchTool(config) {
     const currentMonthYear = new Date().toLocaleString("en-US", { month: "long", year: "numeric" });
     return {
         name: "WebSearch",
-        contract: { contractId: "core.web_search@1", implementationRevision: "1" },
+        ...toolFace("web-search"),
         description: "Search the web. Returns result blocks with titles and URLs.\n" +
             "\n" +
             `- The current month is ${currentMonthYear} — use this when searching for recent information.\n` +
@@ -857,8 +856,6 @@ export function createWebSearchTool(config) {
             allowed_domains: Type.Optional(Type.Array(Type.String(), { description: "Only include search results from these domains" })),
             blocked_domains: Type.Optional(Type.Array(Type.String(), { description: "Never include search results from these domains" })),
         }),
-        effect: "read",
-        contentOrigin: "external",
         execute: async (args, ctx) => {
             const { query, allowed_domains, blocked_domains } = args;
             const startedAt = Date.now();

package/dist/tools/worktree.js

@@ -2,6 +2,7 @@ import { resolve } from "node:path";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../core/tools.js";
 import { addWorktree, pruneWorktrees, WORKTREE_PARENT } from "../core/git-worktree-env.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 const ENTER_DESCRIPTION = "Use this tool ONLY when explicitly instructed to work in a worktree — either by the user directly, or by " +
     "project instructions. This tool creates an isolated git worktree and switches the current session into it.\n" +
     "\n" +
@@ -108,7 +109,7 @@ export function createWorktreeTools(env, opts) {
     const session = opts.session ?? {};
     const enter = defineTool({
         name: "EnterWorktree",
-        contract: { contractId: "core.enter_worktree@1", implementationRevision: "1" },
+        ...toolFace("enter-worktree"),
         description: ENTER_DESCRIPTION,
         parameters: Type.Object({
             name: Type.Optional(Type.String({
@@ -121,7 +122,6 @@ export function createWorktreeTools(env, opts) {
                 description: '"fresh" (default) bases the worktree on the default branch tip (origin default branch, else local main/master, else the current HEAD with a note); "head" bases it on the current local HEAD (unpushed commits present).',
             })),
         }),
-        effect: "write",
         execute: async (args) => {
             const { name, path, baseRef } = args;
             if (path !== undefined && name !== undefined) {
@@ -238,7 +238,7 @@ export function createWorktreeTools(env, opts) {
     });
     const exit = defineTool({
         name: "ExitWorktree",
-        contract: { contractId: "core.exit_worktree@1", implementationRevision: "1" },
+        ...toolFace("exit-worktree"),
         description: EXIT_DESCRIPTION,
         parameters: Type.Object({
             keep: Type.Optional(Type.Boolean({
@@ -254,7 +254,6 @@ export function createWorktreeTools(env, opts) {
                 description: 'Set true to remove the worktree even when it has uncommitted files or unmerged commits — they are permanently discarded. Without it a changed worktree is KEPT (the exit still completes and the reply lists the changes plus this escape), never refused.',
             })),
         }),
-        effect: "write",
         execute: async (args) => {
             const raw = args;
             const keep = raw.keep ?? (raw.action === "keep" ? true : undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.6.3",
+  "version": "7.8.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -79,6 +79,9 @@
     "gate:closed-sets": "node scripts/verify-closed-sets.mjs",
     "gate:agent-returns": "node scripts/verify-agent-returns.mjs",
     "gate:contract-sentences": "node scripts/verify-contract-sentences.mjs",
+    "gate:tool-catalog": "node scripts/verify-tool-catalog.mjs",
+    "gate:tool-names": "node scripts/verify-tool-name-tables.mjs",
+    "gate:tool-docs": "node scripts/gen-tool-spec-fields.mjs --check",
     "gate:all": "node scripts/gate-all.mjs"
   },
   "dependencies": {