@securecoms/agent-runtime 0.12.1 → 0.12.2

package/README.md

@@ -207,9 +207,13 @@ the runtime works as follows in the owner's private chat:
   recalls memories.
 - **The memory tool gate.** On every owner private-chat turn, and on any turn
   that carries memories, the gate checks each tool call before it runs:
+  <!-- [COPY, approved by Eric 2026-10-12] skills spec 2026-10-12 section 7 C-3. -->
+  - What a tool may do is decided by its handler, not its name. A skill file
+    that reuses a built-in's name with a different handler is not loaded.
   - `current_time`, `echo` and `memory_note` run as usual.
-  - `web_search`, `fetch_url`, `http_request` and `sql_query` run only when
-    their arguments pass the gate. The gate refuses an argument that holds a
+  - Network reads (`web_search`, `fetch_url`, `sql_query`, `http_request` GET)
+    run only when the values they will send pass the gate. Numbers are checked
+    too. The gate refuses an argument that holds a
     number the owner did not type in this message (digits, number words, and
     Roman numerals longer than one letter); a URL, an e-mail address or a
     base64-like token longer than 24 characters that is not in the owner's
@@ -222,9 +226,14 @@ the runtime works as follows in the owner's private chat:
     number (`YEAR_WINDOW` = 1). It still counts toward the 3-word runs and the
     200-character budget.
   - `http_request` sends only GET on these turns. Any other method is refused.
-  - Every other tool, skills included, is refused on these turns.
-  - The gate stops copying of numbers, links and exact wording. It does not
-    stop the model from rewording a memory, and it binds only this runtime.
+  - Anything that sends, changes or deletes something is refused on these
+    turns.
+  - The bridge decides which tools a turn may use. Today it allows only
+    `current_time` and `web_search` in the owner's private chat, and no custom
+    skill on any turn.
+  - The gate stops a model from pasting numbers, links and exact wording from
+    memory into a tool. It does not stop a model that rewords a memory or
+    deliberately encodes it in other words, and it binds only this runtime.
 
 **With bridge 0.28 or older.** A turn without the bridge's `memory_unified`
 reply works as in runtime 0.11.0: `memory_note` saves, replaces or forgets a
@@ -233,6 +242,11 @@ not run.
 
 ## Adding a skill
 
+<!-- [COPY, approved by Eric 2026-10-12] skills spec 2026-10-12 section 7 C-3. -->
+Note: a skill you add here is loaded but not offered to the model yet. The
+bridge grants tools per turn, and it does not grant custom skills on any turn.
+The six built-ins below are the tools agents use today.
+
 A skill is either a JSON manifest or a `SKILL.md` file, dropped under
 `SECURECOMS_SKILLS_DIR` in one of three layouts:
 

package/dist/bin.js

@@ -2585,8 +2585,12 @@ async function readCapped(res, maxBytes) {
 }
 
 // src/builtins/fetch-url.ts
+function coerceFetchUrlArgs(args) {
+  const url = typeof args.url === "string" ? args.url.trim() : "";
+  return { url, outbound: { fields: [{ key: "url", value: url, source: args.url }], runs: [], patterns: [], sendable: true } };
+}
 var fetchUrl = async (args, ctx) => {
-  const raw = typeof args.url === "string" ? args.url.trim() : "";
+  const raw = coerceFetchUrlArgs(args).url;
   if (!raw) return toolError('fetch_url needs a "url" string');
   let parsed;
   try {
@@ -2620,8 +2624,38 @@ function httpMethodIsGet(args) {
   if (method === void 0 || method === null) return true;
   return typeof method === "string" && method.toUpperCase() === "GET";
 }
-var httpRequest = async (args, ctx) => {
+function coerceHttpRequestArgs(args) {
   const name = typeof args.name === "string" ? args.name : "";
+  const method = String(args.method ?? "GET").toUpperCase();
+  const rawPath = String(args.path ?? "");
+  const body = typeof args.body === "string" ? args.body : void 0;
+  const noFragment = rawPath.split("#")[0];
+  const queryAt = noFragment.indexOf("?");
+  const pathPart = queryAt === -1 ? noFragment : noFragment.slice(0, queryAt);
+  const queryPart = queryAt === -1 ? "" : noFragment.slice(queryAt + 1);
+  let segments;
+  let decodedPath = "";
+  try {
+    segments = pathPart.split("/").filter((s) => s && s !== "." && s !== "..").map((s) => decodeURIComponent(s));
+    decodedPath = pathPart.split("/").map((s) => decodeURIComponent(s)).join("/");
+  } catch {
+    segments = null;
+  }
+  const query = [...new URLSearchParams(queryPart)];
+  const fields = [
+    { key: "name", value: name, source: args.name },
+    { key: "method", value: method, source: args.method }
+  ];
+  for (const s of segments ?? []) fields.push({ key: "path", value: s, source: args.path });
+  for (const [k, v] of query) fields.push({ key: "path", value: k, source: args.path }, { key: "path", value: v, source: args.path });
+  if (body !== void 0) fields.push({ key: "body", value: body, source: args.body });
+  const runs2 = [[...segments ?? [], ...query.flat()].join(" ")].filter((r) => r !== "");
+  const patterns = [decodedPath, queryPart, query.length > 0 ? String(new URLSearchParams(query)) : ""].filter((s) => s !== "");
+  return { name, method, rawPath, segments, queryPart, query, body, outbound: { fields, runs: runs2, patterns, sendable: segments !== null } };
+}
+var httpRequest = async (args, ctx) => {
+  const call = coerceHttpRequestArgs(args);
+  const name = call.name;
   const endpoint = ctx.skillsConfig.endpoints[name];
   if (!endpoint) {
     return toolError(
@@ -2631,7 +2665,7 @@ var httpRequest = async (args, ctx) => {
   if (endpoint.headersFileRefused) {
     return toolError(secretPathRefusedMessage(`the headers file for endpoint "${name}"`));
   }
-  const method = String(args.method ?? "GET").toUpperCase();
+  const method = call.method;
   if (!METHODS.has(method)) return toolError(`unsupported method "${method}": use GET, POST, PUT or DELETE`);
   let base;
   try {
@@ -2639,7 +2673,7 @@ var httpRequest = async (args, ctx) => {
   } catch {
     return toolError(`endpoint "${name}" has an unusable baseUrl`);
   }
-  const rawPath = String(args.path ?? "");
+  const rawPath = call.rawPath;
   let asWritten;
   try {
     asWritten = new URL(rawPath, base);
@@ -2649,18 +2683,11 @@ var httpRequest = async (args, ctx) => {
   if (asWritten.origin !== base.origin) {
     return toolError(`path must stay on the configured endpoint (${base.origin}): "${rawPath}" points elsewhere`);
   }
-  const noFragment = rawPath.split("#")[0];
-  const queryAt = noFragment.indexOf("?");
-  const pathPart = queryAt === -1 ? noFragment : noFragment.slice(0, queryAt);
-  const queryPart = queryAt === -1 ? "" : noFragment.slice(queryAt + 1);
-  let segments;
-  try {
-    segments = pathPart.split("/").filter((s) => s && s !== "." && s !== "..").map((s) => encodeURIComponent(decodeURIComponent(s)));
-  } catch {
+  if (call.segments === null) {
     return toolError(`"${rawPath}" is not a usable path for endpoint "${name}"`);
   }
-  const url = new URL(segments.join("/"), base);
-  if (queryPart) url.search = new URLSearchParams(queryPart).toString();
+  const url = new URL(call.segments.map((s) => encodeURIComponent(s)).join("/"), base);
+  if (call.queryPart) url.search = new URLSearchParams(call.query).toString();
   const headers = { accept: "application/json" };
   if (endpoint.headersFile) {
     try {
@@ -2671,7 +2698,7 @@ var httpRequest = async (args, ctx) => {
       return toolError(`cannot read the headers file for endpoint "${name}"`);
     }
   }
-  const body = typeof args.body === "string" ? args.body : void 0;
+  const body = call.body;
   if (body) headers["content-type"] = headers["content-type"] ?? "application/json";
   try {
     const res = await safeFetch(url.toString(), {
@@ -3068,8 +3095,18 @@ function envelope(columns, rows, truncated, reason) {
   }
   return toolError("database result metadata exceeded the response limit");
 }
-var sqlQuery = async (args, ctx) => {
+function coerceSqlQueryArgs(args) {
   const name = typeof args.name === "string" ? args.name : "";
+  const sql = String(args.sql ?? "");
+  return {
+    name,
+    sql,
+    outbound: { fields: [{ key: "name", value: name, source: args.name }, { key: "sql", value: sql, source: args.sql }], runs: [], patterns: [], sendable: true }
+  };
+}
+var sqlQuery = async (args, ctx) => {
+  const call = coerceSqlQueryArgs(args);
+  const name = call.name;
   const db = ctx.skillsConfig.databases[name];
   if (!db) {
     return toolError(
@@ -3081,7 +3118,7 @@ var sqlQuery = async (args, ctx) => {
   }
   let sql;
   try {
-    sql = assertReadOnlySelect(String(args.sql ?? ""));
+    sql = assertReadOnlySelect(call.sql);
   } catch (e) {
     return toolError(e instanceof Error ? e.message : String(e));
   }
@@ -3111,10 +3148,16 @@ var sqlQuery = async (args, ctx) => {
 
 // src/builtins/web-search.ts
 var MIN_RESULTS = 5;
-var webSearch = async (args, ctx) => {
+function coerceWebSearchArgs(args) {
   const query = typeof args.query === "string" ? args.query.trim() : "";
-  if (!query) return toolError('web_search needs a non-empty "query"');
   const count = Math.min(10, Math.max(MIN_RESULTS, Number(args.count) || MIN_RESULTS));
+  const fields = [{ key: "query", value: query, source: args.query }];
+  if (args.count !== void 0) fields.push({ key: "count", value: String(args.count), source: args.count });
+  return { query, count, outbound: { fields, runs: [], patterns: [], sendable: true } };
+}
+var webSearch = async (args, ctx) => {
+  const { query, count } = coerceWebSearchArgs(args);
+  if (!query) return toolError('web_search needs a non-empty "query"');
   const brave = ctx.readKeyFile("brave");
   const tavily = brave ? null : ctx.readKeyFile("tavily");
   if (!brave && !tavily) {
@@ -3261,6 +3304,174 @@ var BUILTINS = {
   sql_query: sqlQuery
 };
 
+// src/memory-note.ts
+var MEMORY_NOTE = "memory_note";
+var MEMORY_NOTE_TOOL = {
+  type: "function",
+  function: {
+    name: MEMORY_NOTE,
+    description: "Save, change or delete one short note in this chat's saved notes. Save only what the owner asked you to keep. First check the saved notes already shown to you: if the fact is already saved, do not call this tool; just tell the owner it is already remembered. `text` must be copied word for word from the owner's CURRENT message (a contiguous part of it is fine). You cannot save something said earlier, said in a call, found by a tool, or your own summary. If the owner asks you to remember something from earlier, ask them to type it in one short message. Never store credentials, keys or passwords. To change or delete a note, pass its id: [n7] is id 7. To forget a remembered message shown to you as [r12], pass op forget with id \"r12\". You can make only one change (replace or forget) per owner message: One change per message. Ask the owner to confirm the next one.",
+    parameters: {
+      type: "object",
+      properties: {
+        op: { type: "string", enum: ["add", "replace", "forget"] },
+        text: { type: "string" },
+        id: { anyOf: [{ type: "integer", minimum: 1 }, { type: "string", pattern: "^r[1-9][0-9]*$" }] }
+      },
+      required: ["op"],
+      additionalProperties: false
+    }
+  }
+};
+var MEMORY_PIN_TOOL = {
+  type: "function",
+  function: {
+    name: MEMORY_NOTE,
+    description: (
+      // [COPY, NEW] model-facing. Signed off by Eric 2026-10-11 with the final-review copy fixes (plan Task 37).
+      `Pin one short fact the owner asked you to keep, or forget one remembered item. Pin only when the owner asks. You may reword, but every word that carries meaning must be a word the owner typed in this message, in a pinned fact, or in the owner's earlier typed words shown to you (words spoken on a call do not count); otherwise the pin is refused. Words the owner speaks on a call in this private chat may be remembered automatically, but they cannot be pinned. Never pin credentials, keys or passwords. To forget an item shown to you as [r12], pass op forget with id "r12". You can make only one change per owner message.`
+    ),
+    parameters: {
+      type: "object",
+      properties: {
+        op: { type: "string", enum: ["add", "forget"] },
+        text: { type: "string" },
+        id: { type: "string", pattern: "^r[1-9][0-9]*$" }
+      },
+      required: ["op"],
+      additionalProperties: false
+    }
+  }
+};
+function memoryNoteAllowed(auth, m) {
+  return auth.sender_membership === "active" && auth.memory_write === true && m.memoryNote !== void 0;
+}
+var MEMORY_NOTE_MAX_TEXT_UNITS = 2 * 600;
+var REFUSAL = {
+  too_long: "Not saved. The note text is too long. Ask the owner to type the fact in one short message.",
+  provenance: `Not saved. A note must be copied word for word from the owner's current message, and that message must be short. Ask the owner to type the fact in one short message, for example "Remember: ...".`,
+  secret: "Not saved. The text looks like a password or a key. Never store credentials.",
+  cap: "Not saved. The notes are full or the note is too long. Replace or forget older notes first.",
+  audience: "Not saved. Notes can be saved only from the owner's own typed message in their private chat.",
+  cleared: "Not saved. The owner cleared the notes after this message arrived.",
+  // [COPY] spec 7b §9.1.
+  budget: "One change per message. Ask the owner to confirm the next one.",
+  // [COPY, NEW] Approved by Eric 2026-10-09. The bridge emits it when the chat's memory was purged after the write was queued.
+  purged: "Not saved. This chat's memory was removed after this message arrived.",
+  mode: "Not saved. Notes are turned off for this agent right now."
+};
+var UNIFIED_PIN_CAP = 200;
+var UNIFIED_PIN_MAX_CHARS = 400;
+var UNIFIED_REFUSAL = {
+  // [COPY, NEW] Mini live check 2026-10-11: the model asked the owner to retype a fact they had just typed. Approved by Eric 2026-10-11.
+  not_owner_words: "Not pinned. A pinned fact must use the owner's own typed words from this message or from their earlier typed words shown to you. Words spoken on a call do not count. Call memory_note once more with the fact copied exactly from the owner's words in this message. Only if that is refused too, ask the owner to type the fact.",
+  cap: `Not pinned. There are already ${UNIFIED_PIN_CAP} pinned facts, or the fact is longer than ${UNIFIED_PIN_MAX_CHARS} characters. Ask the owner to forget a pinned fact first, or to shorten it.`,
+  secret: REFUSAL.secret,
+  audience: "Not pinned. Facts can be pinned only from the owner's own typed message in their private chat.",
+  cleared: REFUSAL.cleared,
+  budget: REFUSAL.budget,
+  purged: REFUSAL.purged,
+  mode: "Not pinned. Memory is turned off for this agent right now.",
+  invalid: "Not changed. The fact is already pinned or has no usable words, the id was not shown with this message, or the request was not a pin or a forget.",
+  // [COPY, NEW] fix round 1: unified turns never fall back to the legacy "replace" wording.
+  too_long: "Not pinned. The fact is too long. Ask the owner to type the fact in one short message.",
+  provenance: "Not pinned. A pinned fact must use the owner's own typed words from this message or from their earlier typed words shown to you. Words spoken on a call do not count. Call memory_note once more with the fact copied exactly from the owner's words in this message. Only if that is refused too, ask the owner to type the fact in one short message.",
+  failed: "Not changed. The memory could not be updated right now. Try again later.",
+  // [COPY, NEW] C26: the bridge also emits these; no spec wording, so plain wording in the style of REFUSAL.
+  message: "Not pinned. The owner's message could not be used for this change. Ask the owner to type the fact again.",
+  store: "Not changed. The memory could not be saved right now. Try again later."
+};
+var UNIFIED_ARGS_ERROR = 'memory_note needs op add with text, or op forget with an id like "r12"';
+function parseArgs(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const a = parsed;
+  const id = typeof a.id === "number" && Number.isSafeInteger(a.id) && a.id >= 1 ? a.id : void 0;
+  const text = typeof a.text === "string" && a.text.length > 0 ? a.text : void 0;
+  if (a.op === "add" && text !== void 0 && a.id === void 0) return { op: "add", text };
+  if (a.op === "replace" && text !== void 0 && id !== void 0) return { op: "replace", text, id };
+  const recallId = typeof a.id === "string" && /^r[1-9][0-9]{0,15}$/.test(a.id) && Number.isSafeInteger(Number(a.id.slice(1))) ? a.id : void 0;
+  if (a.op === "forget" && a.text === void 0) {
+    if (id !== void 0) return { op: "forget", id };
+    if (recallId !== void 0) return { op: "forget", id: recallId };
+  }
+  return null;
+}
+async function runMemoryNoteCalls(calls, m, ctx = {}) {
+  const clock = ctx.clock ?? (() => performance.now());
+  const out = [];
+  const refusal = ctx.unified ? UNIFIED_REFUSAL : REFUSAL;
+  for (const call of calls) {
+    const started = clock();
+    let content;
+    let cancelled = false;
+    if (ctx.signal?.aborted) {
+      cancelled = true;
+      content = toolError("Tool execution cancelled");
+    } else {
+      const req = parseArgs(call.function.arguments);
+      if (!req || !m.memoryNote) content = toolError(ctx.unified ? UNIFIED_ARGS_ERROR : "memory_note needs op add with text, replace with id and text, or forget with id");
+      else if (req.text !== void 0 && req.text.length > MEMORY_NOTE_MAX_TEXT_UNITS) {
+        content = JSON.stringify({ saved: false, reason: "too_long", message: refusal.too_long });
+      } else {
+        let r;
+        try {
+          r = await m.memoryNote(req);
+        } catch {
+          r = { ok: false, reason: "failed" };
+        }
+        if (!r.ok && r.reason === "aborted") cancelled = true;
+        const reason = r.reason ?? "unknown";
+        content = JSON.stringify(r.ok ? { saved: true, op: req.op, id: r.id } : { saved: false, reason, message: Object.hasOwn(refusal, reason) ? refusal[reason] : "Not saved." });
+      }
+    }
+    out.push({ role: "tool", content, tool_call_id: call.id });
+    ctx.onTiming?.({ tool_call_id: call.id, ms: clock() - started, ok: !content.includes('"saved":false') && !content.startsWith('{"error"'), cancelled });
+  }
+  return out;
+}
+
+// src/effect-class.ts
+var BUILTIN_EFFECT_CLASS = Object.freeze({
+  current_time: "local",
+  echo: "local",
+  web_search: "read",
+  fetch_url: "read",
+  sql_query: "read",
+  http_request: "per_call"
+});
+var BUILTIN_NAMES = new Set(Object.keys(BUILTINS));
+function builtinNameMismatch(manifest) {
+  if (manifest.name === MEMORY_NOTE) return true;
+  if (manifest.handler.startsWith("builtin:")) return manifest.handler.slice("builtin:".length) !== manifest.name;
+  return typeof manifest.name === "string" && BUILTIN_NAMES.has(manifest.name);
+}
+function effectClassOf(manifest, args) {
+  if (!manifest) return "uninspectable";
+  const handler = manifest.handler;
+  if (handler.startsWith("builtin:")) {
+    const name = handler.slice("builtin:".length);
+    if (!Object.hasOwn(BUILTIN_EFFECT_CLASS, name)) return "uninspectable";
+    const cls = BUILTIN_EFFECT_CLASS[name];
+    if (cls === "per_call") return httpMethodIsGet(args) ? "read" : "side_effect";
+    return cls;
+  }
+  if (handler.startsWith("script:")) {
+    return manifest.effects === "read" ? "uninspectable" : "side_effect";
+  }
+  return "uninspectable";
+}
+function manifestOfferableOnGatedTurn(manifest) {
+  if (manifest?.handler === "builtin:http_request") return true;
+  const cls = effectClassOf(manifest, void 0);
+  return cls === "local" || cls === "read";
+}
+
 // src/side-effect-ledger.ts
 import { createHash } from "node:crypto";
 import { chmodSync, mkdirSync as mkdirSync3 } from "node:fs";
@@ -3446,6 +3657,10 @@ var SkillInvoker = class {
   }
   /** Later file wins, with a warning naming both paths (spec §3). */
   register(manifest, path) {
+    if (builtinNameMismatch(manifest)) {
+      writeServiceLog("warn", "skills.builtin_name_mismatch");
+      return;
+    }
     const prior = this.sources.get(manifest.name);
     if (prior) writeServiceLog("warn", "skills.duplicate_replaced");
     this.skills.set(manifest.name, manifest);
@@ -3503,6 +3718,18 @@ var SkillInvoker = class {
     }
     return out;
   }
+  /** R1, R2: this call's effect class, from the loaded manifest's handler, never from the name. */
+  effectClass(name, args) {
+    return effectClassOf(this.skills.get(name), args);
+  }
+  /** R4: the handler the memory tool gate inspects for; undefined when no manifest of that name is loaded. */
+  handlerOf(name) {
+    return this.skills.get(name)?.handler;
+  }
+  /** R5: false for a tool the gated-turn offer filter drops. */
+  offerableOnGatedTurn(name) {
+    return manifestOfferableOnGatedTurn(this.skills.get(name));
+  }
   /**
    * Execute a skill by name with the given arguments.
    *
@@ -4460,138 +4687,6 @@ async function runToolCalls(toolCalls, skills, context) {
   return out;
 }
 
-// src/memory-note.ts
-var MEMORY_NOTE = "memory_note";
-var MEMORY_NOTE_TOOL = {
-  type: "function",
-  function: {
-    name: MEMORY_NOTE,
-    description: "Save, change or delete one short note in this chat's saved notes. Save only what the owner asked you to keep. First check the saved notes already shown to you: if the fact is already saved, do not call this tool; just tell the owner it is already remembered. `text` must be copied word for word from the owner's CURRENT message (a contiguous part of it is fine). You cannot save something said earlier, said in a call, found by a tool, or your own summary. If the owner asks you to remember something from earlier, ask them to type it in one short message. Never store credentials, keys or passwords. To change or delete a note, pass its id: [n7] is id 7. To forget a remembered message shown to you as [r12], pass op forget with id \"r12\". You can make only one change (replace or forget) per owner message: One change per message. Ask the owner to confirm the next one.",
-    parameters: {
-      type: "object",
-      properties: {
-        op: { type: "string", enum: ["add", "replace", "forget"] },
-        text: { type: "string" },
-        id: { anyOf: [{ type: "integer", minimum: 1 }, { type: "string", pattern: "^r[1-9][0-9]*$" }] }
-      },
-      required: ["op"],
-      additionalProperties: false
-    }
-  }
-};
-var MEMORY_PIN_TOOL = {
-  type: "function",
-  function: {
-    name: MEMORY_NOTE,
-    description: (
-      // [COPY, NEW] model-facing. Signed off by Eric 2026-10-11 with the final-review copy fixes (plan Task 37).
-      `Pin one short fact the owner asked you to keep, or forget one remembered item. Pin only when the owner asks. You may reword, but every word that carries meaning must be a word the owner typed in this message, in a pinned fact, or in the owner's earlier typed words shown to you (words spoken on a call do not count); otherwise the pin is refused. Words the owner speaks on a call in this private chat may be remembered automatically, but they cannot be pinned. Never pin credentials, keys or passwords. To forget an item shown to you as [r12], pass op forget with id "r12". You can make only one change per owner message.`
-    ),
-    parameters: {
-      type: "object",
-      properties: {
-        op: { type: "string", enum: ["add", "forget"] },
-        text: { type: "string" },
-        id: { type: "string", pattern: "^r[1-9][0-9]*$" }
-      },
-      required: ["op"],
-      additionalProperties: false
-    }
-  }
-};
-function memoryNoteAllowed(auth, m) {
-  return auth.sender_membership === "active" && auth.memory_write === true && m.memoryNote !== void 0;
-}
-var MEMORY_NOTE_MAX_TEXT_UNITS = 2 * 600;
-var REFUSAL = {
-  too_long: "Not saved. The note text is too long. Ask the owner to type the fact in one short message.",
-  provenance: `Not saved. A note must be copied word for word from the owner's current message, and that message must be short. Ask the owner to type the fact in one short message, for example "Remember: ...".`,
-  secret: "Not saved. The text looks like a password or a key. Never store credentials.",
-  cap: "Not saved. The notes are full or the note is too long. Replace or forget older notes first.",
-  audience: "Not saved. Notes can be saved only from the owner's own typed message in their private chat.",
-  cleared: "Not saved. The owner cleared the notes after this message arrived.",
-  // [COPY] spec 7b §9.1.
-  budget: "One change per message. Ask the owner to confirm the next one.",
-  // [COPY, NEW] Approved by Eric 2026-10-09. The bridge emits it when the chat's memory was purged after the write was queued.
-  purged: "Not saved. This chat's memory was removed after this message arrived.",
-  mode: "Not saved. Notes are turned off for this agent right now."
-};
-var UNIFIED_PIN_CAP = 200;
-var UNIFIED_PIN_MAX_CHARS = 400;
-var UNIFIED_REFUSAL = {
-  // [COPY, NEW] Mini live check 2026-10-11: the model asked the owner to retype a fact they had just typed. Approved by Eric 2026-10-11.
-  not_owner_words: "Not pinned. A pinned fact must use the owner's own typed words from this message or from their earlier typed words shown to you. Words spoken on a call do not count. Call memory_note once more with the fact copied exactly from the owner's words in this message. Only if that is refused too, ask the owner to type the fact.",
-  cap: `Not pinned. There are already ${UNIFIED_PIN_CAP} pinned facts, or the fact is longer than ${UNIFIED_PIN_MAX_CHARS} characters. Ask the owner to forget a pinned fact first, or to shorten it.`,
-  secret: REFUSAL.secret,
-  audience: "Not pinned. Facts can be pinned only from the owner's own typed message in their private chat.",
-  cleared: REFUSAL.cleared,
-  budget: REFUSAL.budget,
-  purged: REFUSAL.purged,
-  mode: "Not pinned. Memory is turned off for this agent right now.",
-  invalid: "Not changed. The fact is already pinned or has no usable words, the id was not shown with this message, or the request was not a pin or a forget.",
-  // [COPY, NEW] fix round 1: unified turns never fall back to the legacy "replace" wording.
-  too_long: "Not pinned. The fact is too long. Ask the owner to type the fact in one short message.",
-  provenance: "Not pinned. A pinned fact must use the owner's own typed words from this message or from their earlier typed words shown to you. Words spoken on a call do not count. Call memory_note once more with the fact copied exactly from the owner's words in this message. Only if that is refused too, ask the owner to type the fact in one short message.",
-  failed: "Not changed. The memory could not be updated right now. Try again later.",
-  // [COPY, NEW] C26: the bridge also emits these; no spec wording, so plain wording in the style of REFUSAL.
-  message: "Not pinned. The owner's message could not be used for this change. Ask the owner to type the fact again.",
-  store: "Not changed. The memory could not be saved right now. Try again later."
-};
-var UNIFIED_ARGS_ERROR = 'memory_note needs op add with text, or op forget with an id like "r12"';
-function parseArgs(raw) {
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return null;
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
-  const a = parsed;
-  const id = typeof a.id === "number" && Number.isSafeInteger(a.id) && a.id >= 1 ? a.id : void 0;
-  const text = typeof a.text === "string" && a.text.length > 0 ? a.text : void 0;
-  if (a.op === "add" && text !== void 0 && a.id === void 0) return { op: "add", text };
-  if (a.op === "replace" && text !== void 0 && id !== void 0) return { op: "replace", text, id };
-  const recallId = typeof a.id === "string" && /^r[1-9][0-9]{0,15}$/.test(a.id) && Number.isSafeInteger(Number(a.id.slice(1))) ? a.id : void 0;
-  if (a.op === "forget" && a.text === void 0) {
-    if (id !== void 0) return { op: "forget", id };
-    if (recallId !== void 0) return { op: "forget", id: recallId };
-  }
-  return null;
-}
-async function runMemoryNoteCalls(calls, m, ctx = {}) {
-  const clock = ctx.clock ?? (() => performance.now());
-  const out = [];
-  const refusal = ctx.unified ? UNIFIED_REFUSAL : REFUSAL;
-  for (const call of calls) {
-    const started = clock();
-    let content;
-    let cancelled = false;
-    if (ctx.signal?.aborted) {
-      cancelled = true;
-      content = toolError("Tool execution cancelled");
-    } else {
-      const req = parseArgs(call.function.arguments);
-      if (!req || !m.memoryNote) content = toolError(ctx.unified ? UNIFIED_ARGS_ERROR : "memory_note needs op add with text, replace with id and text, or forget with id");
-      else if (req.text !== void 0 && req.text.length > MEMORY_NOTE_MAX_TEXT_UNITS) {
-        content = JSON.stringify({ saved: false, reason: "too_long", message: refusal.too_long });
-      } else {
-        let r;
-        try {
-          r = await m.memoryNote(req);
-        } catch {
-          r = { ok: false, reason: "failed" };
-        }
-        if (!r.ok && r.reason === "aborted") cancelled = true;
-        const reason = r.reason ?? "unknown";
-        content = JSON.stringify(r.ok ? { saved: true, op: req.op, id: r.id } : { saved: false, reason, message: Object.hasOwn(refusal, reason) ? refusal[reason] : "Not saved." });
-      }
-    }
-    out.push({ role: "tool", content, tool_call_id: call.id });
-    ctx.onTiming?.({ tool_call_id: call.id, ms: clock() - started, ok: !content.includes('"saved":false') && !content.startsWith('{"error"'), cancelled });
-  }
-  return out;
-}
-
 // src/memory-text.ts
 var QUOTES = {
   "\u2018": "'",
@@ -4628,12 +4723,18 @@ var STOP_WORDS = new Set(
 );
 
 // src/memory-tool-gate.ts
-var GATED_TOOLS = /* @__PURE__ */ new Set(["web_search", "fetch_url", "http_request", "sql_query"]);
-var NON_NETWORK_TOOLS = /* @__PURE__ */ new Set(["current_time", "echo", "memory_note"]);
+var GATED_TOOLS = new Set(Object.keys(BUILTIN_EFFECT_CLASS).filter((n) => BUILTIN_EFFECT_CLASS[n] !== "local"));
+var NON_NETWORK_TOOLS = /* @__PURE__ */ new Set([...Object.keys(BUILTIN_EFFECT_CLASS).filter((n) => BUILTIN_EFFECT_CLASS[n] === "local"), MEMORY_NOTE]);
 var RUN_LEN = 3;
 var COMPARE_BUDGET_CHARS = 200;
 var MEMORY_GATE_REFUSAL = "Refused: this request repeats a number, link, address or wording from memory or the chat history that the owner did not type in this message. Ask the owner to confirm or type it.";
-var MEMORY_GATE_ACTION_REFUSAL = "Refused: on a turn that uses memory, only read requests (GET) can be sent. Tell the owner the request was not sent.";
+var MEMORY_GATE_ACTION_REFUSAL = "Refused: in this chat, a tool that sends, changes or deletes something cannot run yet. Tell the owner it was not done.";
+var MEMORY_GATE_UNAVAILABLE_REFUSAL = "Refused: this tool cannot be used in this chat. Do not ask the owner to retype anything; tell them the tool is unavailable here.";
+var REASON = {
+  copy: MEMORY_GATE_REFUSAL,
+  action: MEMORY_GATE_ACTION_REFUSAL,
+  unavailable: MEMORY_GATE_UNAVAILABLE_REFUSAL
+};
 var URL_RE = /\b(?:https?|ftp):\/\/[^\s"'<>]+|\bwww\.[^\s"'<>]+/gi;
 var EMAIL_RE = /[^\s@"'<>]+@[^\s@"'<>]+\.[^\s@"'<>]+/g;
 var BASE64_RE = /[A-Za-z0-9+/=_-]{25,}/g;
@@ -4646,11 +4747,12 @@ function memoryGateApplies(m, unified) {
   const ownerDm = m.authorization.audience === "owner_dm" || m.authorization.relay_speaker === "owner";
   return ownerDm || unified.items.length > 0 || unified.pinnedMore > 0;
 }
-function leaves(v, out) {
-  if (typeof v === "string") out.push(v);
-  else if (Array.isArray(v)) for (const x of v) leaves(x, out);
-  else if (v && typeof v === "object") for (const x of Object.values(v)) leaves(x, out);
-}
+var OUTBOUND = Object.freeze({
+  "builtin:web_search": (a) => coerceWebSearchArgs(a).outbound,
+  "builtin:fetch_url": (a) => coerceFetchUrlArgs(a).outbound,
+  "builtin:http_request": (a) => coerceHttpRequestArgs(a).outbound,
+  "builtin:sql_query": (a) => coerceSqlQueryArgs(a).outbound
+});
 var runs = (ts) => {
   const out = [];
   for (let i = 0; i + RUN_LEN <= ts.length; i++) {
@@ -4668,8 +4770,13 @@ var MemoryToolGate = class {
   compareRuns = /* @__PURE__ */ new Set();
   spent = 0;
   year;
-  /** `now` is the test seam for the year window; production passes nothing (Date.now). */
+  tools;
+  /**
+   * `tools` is the turn's skill snapshot (R2, R8): the class and handler of each tool. `now` is the test seam for the
+   * year window; production passes nothing (Date.now).
+   */
   constructor(o) {
+    this.tools = o.tools;
     this.year = new Date((o.now ?? Date.now)()).getUTCFullYear();
     const ot = tokens(o.ownerMessage);
     this.ownerTokens = new Set(ot);
@@ -4684,30 +4791,48 @@ var MemoryToolGate = class {
   isNearYear(t) {
     return YEAR_RE.test(t) && Math.abs(Number(t) - this.year) <= YEAR_WINDOW;
   }
-  refuse() {
-    return { allowed: false, reason: MEMORY_GATE_REFUSAL };
+  refuse(code, effectClass) {
+    return { allowed: false, reason: REASON[code], gate: { code, effectClass } };
   }
+  /** R3: the verdict follows the class of the handler that will run (R1, R2), never the tool's name. */
   check(toolName, argumentsJson) {
-    if (NON_NETWORK_TOOLS.has(toolName)) return { allowed: true };
-    if (!GATED_TOOLS.has(toolName)) return this.refuse();
     let args;
+    let parsed = true;
     try {
       args = JSON.parse(argumentsJson);
     } catch {
-      return this.refuse();
+      parsed = false;
+    }
+    const cls = this.tools.effectClass(toolName, parsed ? args : void 0);
+    if (cls === "local") return { allowed: true };
+    if (cls === "uninspectable") return this.refuse("unavailable", cls);
+    if (!parsed) return this.refuse("copy", cls);
+    if (cls === "side_effect") return this.refuse("action", cls);
+    const handler = this.tools.handlerOf(toolName);
+    const outboundOf = handler !== void 0 && Object.hasOwn(OUTBOUND, handler) ? OUTBOUND[handler] : void 0;
+    if (!outboundOf) return this.refuse("unavailable", cls);
+    if (!args || typeof args !== "object" || Array.isArray(args)) return this.refuse("copy", cls);
+    let out;
+    try {
+      out = outboundOf(args);
+    } catch {
+      return this.refuse("copy", cls);
     }
-    if (toolName === "http_request") {
-      if (!httpMethodIsGet(args)) return { allowed: false, reason: MEMORY_GATE_ACTION_REFUSAL };
+    if (!out.sendable) return this.refuse("copy", cls);
+    for (const text of out.patterns) {
+      for (const m of text.match(URL_RE) ?? []) if (!this.ownerFolded.includes(foldText(m))) return this.refuse("copy", cls);
+      for (const m of text.match(EMAIL_RE) ?? []) if (!this.ownerFolded.includes(foldText(m))) return this.refuse("copy", cls);
+      for (const m of text.match(BASE64_RE) ?? []) if (!this.ownerFolded.includes(foldText(m))) return this.refuse("copy", cls);
     }
-    const strs = [];
-    leaves(args, strs);
     let charge = 0;
     let yearUsed = false;
-    for (const s of strs) {
-      const asciiYears = new Set([...s.matchAll(ASCII_YEAR_RE)].map((m) => m[0]));
-      for (const m of s.match(URL_RE) ?? []) if (!this.ownerFolded.includes(foldText(m))) return this.refuse();
-      for (const m of s.match(EMAIL_RE) ?? []) if (!this.ownerFolded.includes(foldText(m))) return this.refuse();
-      for (const m of s.match(BASE64_RE) ?? []) if (!this.ownerFolded.includes(foldText(m))) return this.refuse();
+    for (const f of out.fields) {
+      if (handler === "builtin:web_search" && f.key === "count" && typeof f.source === "number") continue;
+      const s = f.value;
+      const asciiYears = new Set(typeof f.source === "string" ? [...s.matchAll(ASCII_YEAR_RE)].map((m) => m[0]) : []);
+      for (const m of s.match(URL_RE) ?? []) if (!this.ownerFolded.includes(foldText(m))) return this.refuse("copy", cls);
+      for (const m of s.match(EMAIL_RE) ?? []) if (!this.ownerFolded.includes(foldText(m))) return this.refuse("copy", cls);
+      for (const m of s.match(BASE64_RE) ?? []) if (!this.ownerFolded.includes(foldText(m))) return this.refuse("copy", cls);
       const ts = tokens(s);
       for (const t of ts) {
         if (STOP_WORDS.has(t) || ONE_LETTER_ROMAN.has(t)) continue;
@@ -4716,13 +4841,14 @@ var MemoryToolGate = class {
             yearUsed = true;
             continue;
           }
-          return this.refuse();
+          return this.refuse("copy", cls);
         }
       }
-      for (const r of runs(ts)) if (this.compareRuns.has(r) && !this.ownerRuns.has(r)) return this.refuse();
+      for (const r of runs(ts)) if (this.compareRuns.has(r) && !this.ownerRuns.has(r)) return this.refuse("copy", cls);
       for (const t of ts) if (!STOP_WORDS.has(t) && this.compareTokens.has(t) && !this.ownerTokens.has(t)) charge += t.length;
     }
-    if (this.spent + charge > COMPARE_BUDGET_CHARS) return this.refuse();
+    for (const text of out.runs) for (const r of runs(tokens(text))) if (this.compareRuns.has(r) && !this.ownerRuns.has(r)) return this.refuse("copy", cls);
+    if (this.spent + charge > COMPARE_BUDGET_CHARS) return this.refuse("copy", cls);
     this.spent += charge;
     return { allowed: true };
   }
@@ -5177,9 +5303,11 @@ ${recalledText}` } : null;
     const toolsStart = clock();
     const eligibleTools = deps.tools();
     const tools = eligibleTools.filter((tool) => toolIsOffered(m.authorization, tool.function.name));
+    const gatedTurn = memoryGateApplies(m, unified);
+    if (gatedTurn) tools.splice(0, tools.length, ...tools.filter((tool) => skills.offerableOnGatedTurn(tool.function.name)));
     if (memoryNoteAllowed(m.authorization, m)) tools.push(m.memoryUnified === true ? MEMORY_PIN_TOOL : MEMORY_NOTE_TOOL);
     const offeredNames = new Set(tools.map((tool) => tool.function.name));
-    const memoryGate = memoryGateApplies(m, unified) ? new MemoryToolGate({ ownerMessage: text, compareTexts: [...unified.items.map((i) => i.text), ...history.map((h) => typeof h.content === "string" ? h.content : "")] }) : void 0;
+    const memoryGate = gatedTurn ? new MemoryToolGate({ ownerMessage: text, compareTexts: [...unified.items.map((i) => i.text), ...history.map((h) => typeof h.content === "string" ? h.content : "")], tools: skills }) : void 0;
     const systemParts = [persona];
     if (m.voiceGuidance) systemParts.push(`${VOICE_TURN_PREFIX}${m.voiceGuidance}`);
     if (tools.length > 0) systemParts.push(toolAvailabilityLine([...offeredNames]));
@@ -5408,7 +5536,9 @@ ${notesLines.slice(0, k).join("\n")}` };
       for (const v of verdicts) {
         if (!v.verdict.allowed) {
           denied++;
-          log("warn", "turn.tool_call_denied");
+          const g = v.verdict.gate;
+          if (g) log("warn", "turn.tool_call_denied", { reason: logLabel(g.code), class: logLabel(g.effectClass) });
+          else log("warn", "turn.tool_call_denied");
         }
       }
       if (turnCapDenied > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-runtime",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "type": "module",
   "bin": {
     "securecoms-agent": "dist/bin.js"