@agentprojectcontext/apx 1.77.3 → 1.79.0

package/src/core/agent/skills/loader.js

@@ -30,9 +30,10 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
+import { SKILLS_DIR } from "#core/config/paths.js";
 import { fileURLToPath } from "node:url";
 import { apcSkillsDir } from "#core/apc/paths.js";
+import { parseFrontmatter } from "#core/apc/frontmatter.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname  = path.dirname(__filename);
@@ -44,32 +45,12 @@ const PACKAGE_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
 // <packageRoot>/skills/ so external tools that copy "skills/" from the repo
 // don't accidentally pull the rich set or the runtime CLI docs.
 const BUILTIN_SKILLS_DIR = path.join(PACKAGE_ROOT, "src", "core", "runtime-skills");
-const GLOBAL_DIR         = path.join(os.homedir(), ".apx", "skills");
+const GLOBAL_DIR         = SKILLS_DIR;
 
 // ---------------------------------------------------------------------------
 // Frontmatter parsing (minimal — handles the YAML we ship)
 // ---------------------------------------------------------------------------
 
-function parseFrontmatter(raw) {
-  if (!raw.startsWith("---")) return { fm: {}, body: raw };
-  const end = raw.indexOf("\n---", 3);
-  if (end < 0) return { fm: {}, body: raw };
-
-  const fmBlock = raw.slice(3, end).trim();
-  const body = raw.slice(end + 4).replace(/^\n/, "");
-
-  const fm = {};
-  for (const line of fmBlock.split("\n")) {
-    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/);
-    if (!m) continue;
-    let val = m[2].trim();
-    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
-      val = val.slice(1, -1);
-    }
-    fm[m[1]] = val;
-  }
-  return { fm, body };
-}
 
 // ---------------------------------------------------------------------------
 // Directory scanners

package/src/core/agent/super-agent.js

@@ -80,8 +80,6 @@ export async function runSuperAgent({
     throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
   }
 
-  const sa = globalConfig.super_agent;
-
   // Memory Broker (Pieza 4): assemble the [MEMORIA RELEVANTE] block before the
   // turn. Silent + bounded (≤ broker_budget_ms); skipped for tool-free callers
   // (summarize/ask) where injected context would only confuse the transcript.

package/src/core/agent/tool-summary.js

@@ -0,0 +1,65 @@
+// A compact record of what a turn actually DID, small enough to store on every
+// message.
+//
+// The full trace carries arguments and results and can run to kilobytes; on a
+// channel like Telegram, writing it to the ledger on every reply would bloat
+// the day-file for a detail nobody reads back. What people do want, looking at
+// a conversation after the fact, is "it read three files and sent a message" —
+// and whether any of it failed. That fits in a line.
+//
+// Shape: { total, failed, tools: [{ name, count, failed }] }
+
+/** How many entries to keep. A turn with 40 distinct tools is a runaway, not a report. */
+const MAX_KINDS = 12;
+
+function isError(result) {
+  if (!result || typeof result !== "object") return false;
+  // Tools signal failure two ways: an `error` field, or the budget's
+  // `suppressed`. Both are "it did not happen", which is what the reader needs.
+  return Boolean(result.error) || result.suppressed === true;
+}
+
+/**
+ * @param {{tool: string, result?: unknown}[]} trace
+ * @returns {{total: number, failed: number, tools: {name: string, count: number, failed: number}[]}|null}
+ *          null when there is nothing to report, so callers can spread it
+ *          conditionally without writing an empty object into every message.
+ */
+export function summarizeToolTrace(trace) {
+  if (!Array.isArray(trace) || trace.length === 0) return null;
+
+  const byName = new Map();
+  let failed = 0;
+
+  for (const item of trace) {
+    const name = String(item?.tool || "tool");
+    const row = byName.get(name) || { name, count: 0, failed: 0 };
+    row.count += 1;
+    if (isError(item?.result)) {
+      row.failed += 1;
+      failed += 1;
+    }
+    byName.set(name, row);
+  }
+
+  // Failures first, then the busiest. If the list is truncated, what went wrong
+  // must survive the truncation — that is the half worth reading.
+  const tools = [...byName.values()].sort(
+    (a, b) => (b.failed - a.failed) || (b.count - a.count) || a.name.localeCompare(b.name),
+  );
+
+  return {
+    total: trace.length,
+    failed,
+    tools: tools.slice(0, MAX_KINDS),
+  };
+}
+
+/** One line for a terminal or a log. "" when there is nothing to say. */
+export function formatToolSummary(summary) {
+  if (!summary?.tools?.length) return "";
+  const parts = summary.tools.map((t) =>
+    `${t.name}${t.count > 1 ? `×${t.count}` : ""}${t.failed ? ` (${t.failed} failed)` : ""}`,
+  );
+  return parts.join(", ");
+}

package/src/core/agent/tools/handlers/call-runtime.js

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import path from "node:path";
 import { loggerFor } from "#core/logging.js";
 import { readAgents } from "#core/apc/parser.js";
@@ -15,9 +14,10 @@ import {
   findEngineSessionById,
   readEngineSessionContext,
 } from "#core/stores/engine-sessions.js";
-import { runProcess } from "#host/daemon/runtimes/_spawn.js";
-import { getRuntime, RUNTIME_IDS } from "#host/daemon/runtimes/index.js";
+import { runProcess } from "#core/runtimes/_spawn.js";
+import { getRuntime, RUNTIME_IDS } from "#core/runtimes/index.js";
 import { buildAgentSystem, resolveProject } from "../helpers.js";
+import { readJson } from "#core/util/json-file.js";
 
 const log = loggerFor("call_runtime");
 
@@ -90,7 +90,7 @@ function resolveProjectForAgent(projects, project, slug) {
 
 function projectName(project) {
   try {
-    const meta = JSON.parse(fs.readFileSync(apcProjectFile(project.path), "utf8"));
+    const meta = readJson(apcProjectFile(project.path), {});
     if (meta.name) return meta.name;
   } catch {}
   return path.basename(project.path);

package/src/core/agent/tools/handlers/list-commitments.js

@@ -0,0 +1,80 @@
+import { listCommitments, listCommitmentsAcrossProjects } from "#core/stores/commitments.js";
+
+/**
+ * Read back what is owed, to whom, by when.
+ *
+ * Cross-project by default. "What do I owe people this week" almost never
+ * respects a repo boundary, and forcing the model to pick a project first is
+ * how the anchors end up reporting one project's promises as if they were all
+ * of them.
+ */
+export default {
+  name: "list_commitments",
+  schema: {
+    type: "function",
+    function: {
+      name: "list_commitments",
+      description:
+        "List commitments — things promised to named people. Use for 'what do I owe X', " +
+        "'what's overdue', or when preparing a meeting with someone. Searches ALL projects " +
+        "unless a project is given. Distinct from list_tasks: these have a counterparty " +
+        "waiting, and an overdue one costs trust.",
+      parameters: {
+        type: "object",
+        properties: {
+          project:      { type: "string", description: "Optional project id, name or path. Omit to search every project." },
+          counterparty: { type: "string", description: "Filter by who is waiting — matches part of the name, case-insensitive." },
+          state:        { type: "string", enum: ["open", "kept", "missed", "all"], description: "Defaults to open." },
+          overdue:      { type: "boolean", description: "Only ones past their date and still open." },
+          due_before:   { type: "string", description: "ISO date — only those due on or before it." },
+          limit:        { type: "integer", description: "Max rows. Defaults to 50." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async (args = {}) => {
+    const { project: ref, counterparty, state, overdue, due_before, limit } = args;
+    const opts = {
+      counterparty: counterparty || undefined,
+      state: state || undefined,
+      overdue: overdue === true || undefined,
+      due_before: due_before || undefined,
+      limit: Number.isFinite(limit) ? limit : 50,
+    };
+
+    if (ref) {
+      const r = String(ref);
+      const found = projects.list().find((p) => String(p.id) === r || p.name === r || p.path === r);
+      if (!found) return { error: `project not found: ${ref}` };
+      const proj = projects.get(found.id);
+      if (!proj) return { error: `project storage not loaded: ${ref}` };
+      return { commitments: listCommitments(proj.storagePath, opts).map(compact) };
+    }
+
+    const entries = [];
+    for (const entry of projects.list()) {
+      const p = projects.get(entry.id);
+      if (!p?.storagePath) continue;
+      entries.push({ id: entry.id, name: entry.name || entry.path, path: entry.path, storagePath: p.storagePath });
+    }
+    const { commitments, skipped } = listCommitmentsAcrossProjects(entries, opts);
+    return {
+      commitments: commitments.map(compact),
+      // Say what could not be read rather than quietly reporting less.
+      ...(skipped.length ? { skipped } : {}),
+    };
+  },
+};
+
+/** Only the fields worth spending prompt tokens on. */
+function compact(c) {
+  return {
+    id: c.id,
+    counterparty: c.counterparty,
+    body: c.body,
+    due: c.due,
+    state: c.state,
+    ...(c.project_name ? { project: c.project_name } : {}),
+    ...(c.renegotiated_count ? { moved: c.renegotiated_count } : {}),
+  };
+}

package/src/core/agent/tools/handlers/list-tasks.js

@@ -1,5 +1,18 @@
-import { listTasks } from "#core/stores/tasks.js";
+import { listTasks, listTasksAcrossProjects } from "#core/stores/tasks.js";
 
+/**
+ * Tasks, across every project by default.
+ *
+ * `project` USED TO BE REQUIRED, and that was the bug. The cross-project fold
+ * has existed in core since C2 and is exposed over HTTP and in the CLI, but the
+ * agent could not reach it — so a chief-of-staff routine asked "what is due
+ * today" by calling this once per registered project. On this install that was
+ * eleven calls, eleven prompt round-trips, and a morning anchor that ran out of
+ * iterations before it managed to say anything.
+ *
+ * Omitting `project` now means "everywhere", matching list_commitments. Passing
+ * one keeps the old behaviour exactly.
+ */
 export default {
   name: "list_tasks",
   schema: {
@@ -7,46 +20,72 @@ export default {
     function: {
       name: "list_tasks",
       description:
-        "List tasks for a project. Use when the user asks 'what's pending', 'qué tengo que hacer', or to recall TODOs. Defaults to open tasks. Project resolves by id, name or absolute path.",
+        "List tasks. Use when the user asks 'what's pending', 'qué tengo que hacer', or to recall TODOs. " +
+        "Searches ALL projects unless you pass `project` — for anything cross-project " +
+        "(what is due today, what is overdue, a morning summary) OMIT it and call this ONCE. " +
+        "Never loop over projects calling this per project. Defaults to open tasks.",
       parameters: {
         type: "object",
-        required: ["project"],
         properties: {
-          project:    { type: "string", description: "Project id, name, or path." },
+          project:    { type: "string", description: "Optional project id, name or path. Omit to search every project." },
           state:      { type: "string", enum: ["open", "done", "dropped", "all"], description: "Filter by state. Default 'open'." },
+          status:     { type: "string", enum: ["pending", "running", "in_review", "blocked"], description: "Workflow sub-status of an open task." },
           tag:        { type: "string", description: "Filter by exact tag match." },
           agent:      { type: "string", description: "Filter by agent slug." },
           due_before: { type: "string", description: "Return only tasks due on or before this ISO date." },
-          limit:      { type: "number", description: "Cap on rows returned. Default unlimited (clamped server-side)." },
+          limit:      { type: "number", description: "Cap on rows returned. Default 100." },
         },
       },
     },
   },
-  makeHandler: ({ projects }) => async ({ project: ref, state, tag, agent, due_before, limit }) => {
-    if (!ref) return { error: "project required" };
-    const all = projects.list();
-    const r = String(ref);
-    const found = all.find((p) =>
-      String(p.id) === r || p.name === r || p.path === r
-    );
-    if (!found) return { error: `project not found: ${ref}` };
-    const proj = projects.get(found.id);
-    if (!proj) return { error: `project storage not loaded: ${ref}` };
-    const rows = listTasks(proj.storagePath, {
+  makeHandler: ({ projects }) => async (args = {}) => {
+    const { project: ref, state, status, tag, agent, due_before, limit } = args;
+    const opts = {
       state: state || undefined,
+      status: status || undefined,
       tag: tag || undefined,
       agent: agent || undefined,
       due_before: due_before || undefined,
-      limit: typeof limit === "number" ? limit : undefined,
-    });
-    return rows.map((t) => ({
-      id: t.id,
-      state: t.state,
-      title: t.title,
-      tags: t.tags,
-      due: t.due,
-      agent: t.agent,
-      created_at: t.created_at,
-    }));
+      limit: typeof limit === "number" ? limit : 100,
+    };
+
+    if (ref) {
+      const r = String(ref);
+      const found = projects.list().find((p) => String(p.id) === r || p.name === r || p.path === r);
+      if (!found) return { error: `project not found: ${ref}` };
+      const proj = projects.get(found.id);
+      if (!proj) return { error: `project storage not loaded: ${ref}` };
+      return listTasks(proj.storagePath, opts).map(compact);
+    }
+
+    const entries = [];
+    for (const entry of projects.list()) {
+      const p = projects.get(entry.id);
+      if (!p?.storagePath) continue;
+      entries.push({ id: entry.id, name: entry.name || entry.path, path: entry.path, storagePath: p.storagePath });
+    }
+    const { tasks, skipped } = listTasksAcrossProjects(entries, opts);
+    return {
+      tasks: tasks.map(compact),
+      // Say what could not be read rather than quietly reporting less — an
+      // anchor that says "nothing due" because a store failed to open is worse
+      // than one that says it could not check.
+      ...(skipped.length ? { skipped } : {}),
+    };
   },
 };
+
+/** Only the fields worth spending prompt tokens on. */
+function compact(t) {
+  return {
+    id: t.id,
+    state: t.state,
+    status: t.status,
+    title: t.title,
+    tags: t.tags,
+    due: t.due,
+    agent: t.agent,
+    created_at: t.created_at,
+    ...(t.project_name ? { project: t.project_name } : {}),
+  };
+}

package/src/core/agent/tools/handlers/record-commitment.js

@@ -0,0 +1,68 @@
+import { createCommitment } from "#core/stores/commitments.js";
+
+/**
+ * Capture a promise made to a person.
+ *
+ * Deliberately separate from create_task. The model needs a reason to reach
+ * for one over the other, and "did you promise this to someone by name?" is a
+ * question it can actually answer from the conversation — which is why the
+ * description leads with the phrasing that gives it away ("I told Ana I'd send
+ * it Friday") rather than with an abstract definition.
+ */
+export default {
+  name: "record_commitment",
+  schema: {
+    type: "function",
+    function: {
+      name: "record_commitment",
+      description:
+        "Record something the user PROMISED TO A PERSON — 'I told Ana I'd send it Friday', " +
+        "'I said we'd have the quote by the 10th'. Use this instead of create_task whenever " +
+        "there is a named counterparty waiting on it: breaking a promise costs trust, and " +
+        "these are tracked, chased and reported separately from ordinary work. " +
+        "A to-do with no one waiting on it is a task, not a commitment. " +
+        "Do not ask permission to record one you clearly heard — record it and say you did.",
+      parameters: {
+        type: "object",
+        required: ["project", "counterparty", "body"],
+        properties: {
+          project:      { type: "string", description: "Project id, name, or path." },
+          counterparty: { type: "string", description: "Who is waiting on this. A name as the user says it — free text, not an id." },
+          body:         { type: "string", description: "What was promised, in one line." },
+          due:          { type: "string", description: "When it was promised for (ISO date or datetime). Include it whenever the user gave one, even loosely resolved ('Friday' → that date)." },
+          origin_channel: { type: "string", description: "Where the promise was made (telegram, meeting, email, …)." },
+          origin_message_ref: { type: "string", description: "Optional reference back to the message it came from." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects, channel }) => async (args = {}) => {
+    const { project: ref, counterparty, body, due, origin_channel, origin_message_ref } = args;
+    if (!ref) return { error: "project required" };
+    if (!counterparty) return { error: "counterparty required — without one this is a task, use create_task" };
+    if (!body) return { error: "body required" };
+
+    const r = String(ref);
+    const found = projects.list().find((p) => String(p.id) === r || p.name === r || p.path === r);
+    if (!found) return { error: `project not found: ${ref}` };
+    const proj = projects.get(found.id);
+    if (!proj) return { error: `project storage not loaded: ${ref}` };
+
+    const c = createCommitment(proj.storagePath, {
+      counterparty,
+      body,
+      due: due || null,
+      origin_channel: origin_channel || channel || "super-agent",
+      origin_message_ref: origin_message_ref || null,
+      created_by: "super-agent",
+    });
+
+    return {
+      id: c.id,
+      project: { id: proj.id, name: proj.name },
+      counterparty: c.counterparty,
+      due: c.due,
+      state: c.state,
+    };
+  },
+};

package/src/core/agent/tools/handlers/search-sessions.js

@@ -3,7 +3,7 @@ import {
   ENGINES,
   collectAllSessions,
   findSessionAcrossEngines,
-} from "#interfaces/cli/commands/sessions.js";
+} from "#core/sessions/index.js";
 
 // Your own work sessions. This is how you remember what you did — never tell
 // the user to run `apx session ...`; call this and answer from the result.

package/src/core/agent/tools/handlers/send-telegram.js

@@ -1,3 +1,28 @@
+import { canNudge, recordNudge, nudgeFeedbackKeyboard } from "#core/nudge/index.js";
+import { CHANNELS } from "#core/constants/channels.js";
+
+/**
+ * Is the person we are about to message the same person who is talking to us
+ * right now?
+ *
+ * PUSH PATH 3 OF 4, and the only one whose solicited-ness is not fixed. When
+ * the turn came in over Telegram and the text is going back to that same chat,
+ * the user is on the other end waiting — that is a reply, not an interruption,
+ * and spending their daily budget on it would be wrong. Every other case (a
+ * routine, a web turn pushing to the phone, a cron) is APX choosing to speak.
+ */
+function isReplyToTheLiveChat(ctx, chatId) {
+  if (ctx?.channel !== CHANNELS.TELEGRAM) return false;
+  // buildTelegramMeta (channels/telegram/helpers.js:59) spells it `chatId`.
+  // Reading `chat_id` here would have silently made every reply look
+  // unsolicited and started charging the user's budget for their own answers.
+  const origin = ctx?.channelMeta?.chatId ?? ctx?.channelMeta?.chat_id;
+  if (!origin) return false;
+  // No chat_id given means "the channel default", which for a Telegram turn is
+  // the chat it arrived on.
+  if (chatId == null || chatId === "") return true;
+  return String(chatId) === String(origin);
+}
 
 function decodeBase64(b64) {
   const clean = String(b64).replace(/^data:[a-z/-]+;base64,/, "");
@@ -76,7 +101,8 @@ export default {
       },
     },
   },
-  makeHandler: ({ plugins, requirePermission }) => async (args = {}) => {
+  makeHandler: (ctx) => async (args = {}) => {
+    const { plugins, requirePermission, globalConfig } = ctx;
     const {
       channel, chat_id, text,
       photo_base64, photo_path, photo_url,
@@ -100,11 +126,44 @@ export default {
       );
     }
 
+    const solicited = isReplyToTheLiveChat(ctx, chat_id);
+    const gate = canNudge(
+      {
+        kind: ctx?.channelMeta?.routineName ? `routine:${ctx.channelMeta.routineName}` : "agent_message",
+        project_id: ctx?.channelMeta?.projectId ?? null,
+        // Severity is set by a DETECTOR when one ran (watch routines put their
+        // peak signal severity here), never by the model. Letting the model
+        // grade its own message would hand it a switch marked "ignore the
+        // budget" — and it would find it.
+        severity: ctx?.channelMeta?.signalSeverity || "normal",
+        unsolicited: !solicited,
+        // Set only by an anchor routine (routines/runner.js), never by the
+        // model — it has no way to declare its own message scheduled.
+        scheduled: ctx?.channelMeta?.scheduledByUser === true,
+        channel: "telegram",
+      },
+      globalConfig || {},
+    );
+    if (!gate.allowed) {
+      // Returned as a tool result, not thrown: the model should learn that it
+      // is out of budget and stop trying, which a raw error does not convey.
+      return {
+        ok: false,
+        suppressed: true,
+        reason: gate.reason,
+        retry_after_ms: gate.retry_after_ms,
+        hint:
+          "The interruption budget refused this unrequested message. Do not retry now — " +
+          "say it in your reply instead, or wait until the user writes to you.",
+      };
+    }
+
     const photo = decodePhoto({ photo_base64, photo_path, photo_url });
     if (photo) {
       const result = await telegram.sendPhoto({
         channel, chat_id, photo, caption: text, author: "apx",
       });
+      recordNudge(gate, { chat_id, preview: text });
       return { ok: true, kind: "photo", message_id: result.message_id };
     }
 
@@ -113,10 +172,17 @@ export default {
       const result = await telegram.sendDocument({
         channel, chat_id, document, caption: text, filename, mime_type,
       });
+      recordNudge(gate, { chat_id, preview: text });
       return { ok: true, kind: "document", message_id: result.message_id, filename };
     }
 
-    const result = await telegram.send({ channel, chat_id, text });
+    const result = await telegram.send({
+      channel, chat_id, text,
+      // Only unprompted messages carry the feedback keyboard. Asking "was that
+      // useful?" under an answer the user just asked for is noise itself.
+      reply_markup: gate.unsolicited ? nudgeFeedbackKeyboard(gate.nudge_id) : undefined,
+    });
+    recordNudge(gate, { chat_id, preview: text });
     return { ok: true, kind: "text", message_id: result.message_id };
   },
 };

package/src/core/agent/tools/handlers/set-permission-mode.js

@@ -1,6 +1,13 @@
+// Changes the super-agent's own autonomy level. This is the gate that decides
+// whether destructive tools run unattended, so the mode vocabulary must come
+// from one place: it used to be spelled out three times in this file (a Set,
+// the schema enum, and the error message), which meant adding or renaming a
+// mode silently left two of them stale.
 import { readConfig, writeConfig } from "#core/config/index.js";
+import { PERMISSION_MODES } from "#core/constants/permissions.js";
 
-const MODES = new Set(["total", "automatico", "permiso"]);
+const MODES = Object.values(PERMISSION_MODES);
+const MODE_LIST = MODES.join(", ");
 
 export default {
   name: "set_permission_mode",
@@ -8,11 +15,11 @@ export default {
     type: "function",
     function: {
       name: "set_permission_mode",
-      description: "Set APX tool permission mode in ~/.apx/config.json. Modes: total, automatico, permiso.",
+      description: `Set APX tool permission mode in ~/.apx/config.json. Modes: ${MODE_LIST}.`,
       parameters: {
         type: "object",
         properties: {
-          mode: { type: "string", enum: ["total", "automatico", "permiso"] },
+          mode: { type: "string", enum: MODES },
         },
         required: ["mode"],
       },
@@ -20,7 +27,7 @@ export default {
   },
   makeHandler: ({ requirePermission }) => async ({ mode, confirmed = false }) => {
     await requirePermission("set_permission_mode", { dangerous: true, confirmed, args: { mode } });
-    if (!MODES.has(mode)) throw new Error("mode must be total, automatico, or permiso");
+    if (!MODES.includes(mode)) throw new Error(`mode must be one of: ${MODE_LIST}`);
     const cfg = readConfig();
     cfg.super_agent = cfg.super_agent || {};
     cfg.super_agent.permission_mode = mode;

package/src/core/agent/tools/names.js

@@ -41,9 +41,15 @@ export const TOOLS = Object.freeze({
   // Tasks
   LIST_TASKS:          "list_tasks",
   CREATE_TASK:         "create_task",
+  RECORD_COMMITMENT:   "record_commitment",
+  LIST_COMMITMENTS:    "list_commitments",
 
   // Interaction
   ASK_QUESTIONS:       "ask_questions",
+  // Synthesised by run-agent.js rather than living in handlers/ — it is how the
+  // model declares the turn is over. It was missing from this catalog, so
+  // security.js referenced it as a bare "finish" literal.
+  FINISH:              "finish",
 
   // Delegation / external
   CALL_AGENT:          "call_agent",
@@ -131,6 +137,8 @@ export const NATIVE_TOOL_NAMES = new Set([
   TOOLS.LOAD_SKILL,
   TOOLS.LIST_TASKS,
   TOOLS.CREATE_TASK,
+  TOOLS.RECORD_COMMITMENT,
+  TOOLS.LIST_COMMITMENTS,
   TOOLS.ASK_QUESTIONS,
   TOOLS.SEARCH_SESSIONS,
   TOOLS.TRANSCRIBE_AUDIO,
@@ -178,6 +186,7 @@ export const CODE_PLAN_TOOLS = Object.freeze([
   TOOLS.LIST_SKILLS,
   TOOLS.LOAD_SKILL,
   TOOLS.LIST_TASKS,
+  TOOLS.LIST_COMMITMENTS,
   TOOLS.ASK_QUESTIONS,
   TOOLS.FETCH,
   TOOLS.SEARCH,
@@ -195,3 +204,58 @@ export const CODE_PLAN_TOOLS = Object.freeze([
  * "*" as "expose every tool the channel is otherwise allowed to see".
  */
 export const CODE_BUILD_TOOLS = "*";
+
+// ---------------------------------------------------------------------------
+// Behavioural tool sets
+//
+// These drive real user-facing protections, so they belong next to the names
+// they reference rather than as string literals scattered across the loop. The
+// side-effect set in particular was an inline `new Set([...])` inside
+// runAgent(): rename a tool there and the de-duplication below silently stops
+// working, with the only symptom being a user receiving the same Telegram
+// message three times. tests/tool-name-sets.test.js fails if any member here
+// stops being a real tool.
+// ---------------------------------------------------------------------------
+
+/**
+ * Tools that mutate the world. Weak models (Gemini especially) re-emit the
+ * same call across iterations; for these we remember the (name + args)
+ * signature and answer duplicates with a synthetic "already done" instead of
+ * running them again. Read-only tools are exempt — they are idempotent and are
+ * legitimately repeated (list_tasks before and after a change).
+ */
+export const SIDE_EFFECT_TOOLS = new Set([
+  TOOLS.SEND_TELEGRAM,
+  TOOLS.CREATE_TASK,
+  TOOLS.RECORD_COMMITMENT,
+  TOOLS.WRITE_FILE,
+  TOOLS.EDIT_FILE,
+  TOOLS.RUN_SHELL,
+  TOOLS.CALL_RUNTIME,
+  TOOLS.ADD_PROJECT,
+  TOOLS.SET_IDENTITY,
+]);
+
+/**
+ * Tools that only acknowledge — the turn has produced no new information for
+ * the user, so a run of them is capped (MAX_CONSECUTIVE_ACKS).
+ */
+export const ACK_ONLY_TOOLS = new Set([TOOLS.SEND_TELEGRAM]);
+
+/**
+ * Tools whose semantics REQUIRE handing control back to a human. The loop
+ * breaks after these even under a completion contract, because the task
+ * cannot advance without a reply. Without it, models under forced toolChoice
+ * ask the same question every iteration.
+ */
+export const TURN_ENDING_TOOLS = new Set([TOOLS.ASK_QUESTIONS]);
+
+/**
+ * Tools exempt from the injected `security_risk` parameter: they cannot touch
+ * anything, so grading them is noise the model has to pay for on every call.
+ */
+export const RISK_EXEMPT_TOOLS = new Set([
+  TOOLS.FINISH,
+  TOOLS.ASK_QUESTIONS,
+  TOOLS.DISCOVER_TOOLS,
+]);