@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/agent/tools/handlers/attach-media.js

@@ -0,0 +1,56 @@
+// attach_media — queue one of a skill's images to ride along with the message
+// this run delivers (web + Telegram). The model does not need to SEE the image
+// to send it: the skill's manifest (id → caption) is in the prompt, the model
+// picks an id, and the runner hands the file to the delivery adapters.
+//
+// The set of attachable images is precomputed by the runner from the agent's
+// declared skills (ctx.attachableMedia) so this handler never guesses at the
+// filesystem, and a queued attachment lands in ctx.mediaSink for the runner to
+// read after the loop finishes.
+export default {
+  name: "attach_media",
+  schema: {
+    type: "function",
+    function: {
+      name: "attach_media",
+      description:
+        "Attach one of your skill's images to the message this run delivers (shown in web chat and sent as a Telegram photo). Pass the image id from the skill's manifest. Optionally add a caption; otherwise the message text is used. Call once per image.",
+      parameters: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "image id from the skill manifest (read_skill / the prompt lists them)" },
+          skill: { type: "string", description: "optional skill slug to disambiguate when two skills share an id" },
+          caption: { type: "string", description: "optional caption for this image" },
+        },
+        required: ["id"],
+      },
+    },
+  },
+  makeHandler: (ctx = {}) => ({ id, skill, caption } = {}) => {
+    if (!id) throw new Error("attach_media: id required");
+    const pool = Array.isArray(ctx.attachableMedia) ? ctx.attachableMedia : [];
+    if (!pool.length) {
+      return { error: "no attachable images — this agent's skills declare none." };
+    }
+    const want = String(id).trim();
+    const matches = pool.filter((m) => m.id === want && (!skill || m.skill === skill));
+    if (!matches.length) {
+      return {
+        error: `no image "${want}"${skill ? ` in skill ${skill}` : ""}.`,
+        available: pool.map((m) => ({ id: m.id, skill: m.skill, caption: m.caption })),
+      };
+    }
+    const item = matches[0];
+    const sink = Array.isArray(ctx.mediaSink) ? ctx.mediaSink : null;
+    if (!sink) {
+      // Delivery isn't wired for this invocation (e.g. a direct engine call with
+      // no runner collecting attachments). Say so instead of pretending it sent.
+      return { ok: false, error: "media delivery is not available on this channel." };
+    }
+    // Idempotent: attaching the same id twice sends one image.
+    if (!sink.some((m) => m.path === item.path)) {
+      sink.push({ id: item.id, skill: item.skill, path: item.path, mime: item.mime, caption: caption || item.caption || "" });
+    }
+    return { ok: true, id: item.id, skill: item.skill, note: `image "${item.id}" queued for delivery.` };
+  },
+};

package/src/core/agent/tools/handlers/calendar-create-event.js

@@ -0,0 +1,38 @@
+import * as calendar from "#core/integrations/plugins/calendar.js";
+import { resolveCalendar, PROJECT_ARG } from "./_calendar.js";
+
+export default {
+  name: "calendar_create_event",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "calendar_create_event",
+      description: "Put an event on the calendar. Times are ISO 8601 with an offset.",
+      parameters: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          start: { type: "string", description: "ISO start, e.g. 2026-08-19T15:00:00-03:00" },
+          end: { type: "string", description: "ISO end" },
+          description: { type: "string" },
+          location: { type: "string" },
+          attendees: { type: "array", items: { type: "string" }, description: "email addresses — they get a real invitation" },
+          meet: { type: "boolean", description: "add a Google Meet video link (defaults to the connection's preference)" },
+          confirmed: { type: "boolean", description: "set once the user has approved this write" },
+          ...PROJECT_ARG,
+        },
+        required: ["title", "start", "end"],
+      },
+    },
+  },
+  // An event lands in someone's day, and with attendees it lands in several.
+  // That is an outward-facing write and it confirms first, like send_telegram.
+  makeHandler: ({ projects, requirePermission }) => async ({ project, title, start, end, description, location, attendees, meet, confirmed = false } = {}) => {
+    await requirePermission("calendar_create_event", { dangerous: true, confirmed, args: { title, start } });
+    const { config, calendarId } = resolveCalendar(projects, project, { needsWrite: true });
+    // Default the Meet link to the connection's preference; an explicit arg wins.
+    const withMeet = meet ?? !!config.meet;
+    return { event: await calendar.createEvent(config, { calendarId, title, start, end, description, location, attendees, meet: withMeet }) };
+  },
+};

package/src/core/agent/tools/handlers/calendar-find-slot.js

@@ -0,0 +1,39 @@
+import * as calendar from "#core/integrations/plugins/calendar.js";
+import { resolveCalendar, PROJECT_ARG, todayWindow } from "./_calendar.js";
+
+export default {
+  name: "calendar_find_slot",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "calendar_find_slot",
+      description:
+        "Free gaps of at least N minutes in a window. Computed from the calendar's busy blocks, not guessed.",
+      parameters: {
+        type: "object",
+        properties: {
+          minutes: { type: "number", description: "how long the gap must be (default 30)" },
+          time_min: { type: "string", description: "ISO start of the search window (default: now)" },
+          time_max: { type: "string", description: "ISO end of the search window (default: end of today)" },
+          limit: { type: "number", description: "how many gaps to return (default 5)" },
+          ...PROJECT_ARG,
+        },
+        required: [],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project, minutes = 30, time_min, time_max, limit = 5 } = {}) => {
+    const { config, calendarId } = resolveCalendar(projects, project);
+    const window = todayWindow();
+    return {
+      slots: await calendar.findSlots(config, {
+        calendarId,
+        timeMin: time_min || window.timeMin,
+        timeMax: time_max || window.timeMax,
+        minutes,
+        limit,
+      }),
+    };
+  },
+};

package/src/core/agent/tools/handlers/calendar-list-events.js

@@ -0,0 +1,39 @@
+import * as calendar from "#core/integrations/plugins/calendar.js";
+import { resolveCalendar, PROJECT_ARG, todayWindow } from "./_calendar.js";
+
+export default {
+  name: "calendar_list_events",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "calendar_list_events",
+      description:
+        "What is on the calendar. Defaults to the rest of today when no window is given.",
+      parameters: {
+        type: "object",
+        properties: {
+          time_min: { type: "string", description: "ISO start of the window (default: now)" },
+          time_max: { type: "string", description: "ISO end of the window (default: end of today)" },
+          q: { type: "string", description: "free-text search over the events" },
+          max_results: { type: "number", description: "default 25" },
+          ...PROJECT_ARG,
+        },
+        required: [],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project, time_min, time_max, q, max_results = 25 } = {}) => {
+    const { config, calendarId } = resolveCalendar(projects, project);
+    const window = todayWindow();
+    return {
+      events: await calendar.listEvents(config, {
+        calendarId,
+        timeMin: time_min || window.timeMin,
+        timeMax: time_max || window.timeMax,
+        q,
+        maxResults: max_results,
+      }),
+    };
+  },
+};

package/src/core/agent/tools/handlers/calendar-update-event.js

@@ -0,0 +1,35 @@
+import * as calendar from "#core/integrations/plugins/calendar.js";
+import { resolveCalendar, PROJECT_ARG } from "./_calendar.js";
+
+export default {
+  name: "calendar_update_event",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "calendar_update_event",
+      description: "Move or edit an event. Only the fields given are changed.",
+      parameters: {
+        type: "object",
+        properties: {
+          event_id: { type: "string", description: "id from calendar_list_events" },
+          title: { type: "string" },
+          start: { type: "string", description: "ISO start" },
+          end: { type: "string", description: "ISO end" },
+          description: { type: "string" },
+          location: { type: "string" },
+          attendees: { type: "array", items: { type: "string" }, description: "email addresses — replaces the guest list and re-sends invites" },
+          confirmed: { type: "boolean", description: "set once the user has approved this write" },
+          ...PROJECT_ARG,
+        },
+        required: ["event_id"],
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => async ({ project, event_id, confirmed = false, ...fields } = {}) => {
+    await requirePermission("calendar_update_event", { dangerous: true, confirmed, args: { event_id } });
+    const { config, calendarId } = resolveCalendar(projects, project, { needsWrite: true });
+    const { project: _ignored, ...patch } = fields;
+    return { event: await calendar.updateEvent(config, { calendarId, eventId: event_id, ...patch }) };
+  },
+};

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

@@ -1,6 +1,7 @@
-import { callEngine } from "#core/engines/index.js";
+import { callEngineWithFallback } from "#core/agent/engine-call.js";
 import { readAgents } from "#core/apc/parser.js";
 import { agentScopedMemoryBlock } from "#core/memory/index.js";
+import { resolveAgentModel } from "#core/agent/agent-model.js";
 import { buildAgentSystem, resolveProject } from "../helpers.js";
 
 export default {
@@ -25,14 +26,19 @@ export default {
     const p = resolveProject(projects, project);
     const agent = readAgents(p.path).find((a) => a.slug === slug);
     if (!agent) throw new Error(`agent ${slug} not found`);
-    if (!agent.fields.Model) throw new Error(`agent ${slug} has no model`);
 
     const config = p.config || globalConfig;
+    const modelId = await resolveAgentModel({ agent, config });
+    if (!modelId) throw new Error(`no model for agent ${slug} (no override, no router default)`);
+
     // Scoped RAG recall for this agent + its project, grounded in the prompt.
     const scopedMemory = await agentScopedMemoryBlock(prompt, { project: p, agent, config });
 
-    const result = await callEngine({
-      modelId: agent.fields.Model,
+    // Same fallback chain the agent loop walks. Without it a provider hiccup
+    // on the delegated call — a Zen 429 the caller's own turn would have
+    // rotated past without noticing — came back as a hard failure.
+    const result = await callEngineWithFallback({
+      modelId,
       system: buildAgentSystem(p, agent, {
         invocation: "engine",
         caller: "super_agent_tool",
@@ -50,8 +56,10 @@ export default {
       actor_kind: "agent",
       author: slug,
       body: result.text,
-      meta: { invoked_by: "super_agent_tool", usage: result.usage },
+      meta: { invoked_by: "super_agent_tool", usage: result.usage, model: result.model },
     });
-    return { text: result.text, usage: result.usage };
+    // `model` is the one that ANSWERED — after a rotation it is not the one
+    // that was asked, and a caller reporting back should say which.
+    return { text: result.text, usage: result.usage, model: result.model };
   },
 };

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

@@ -9,40 +9,35 @@ import {
 } from "#core/stores/runtime-sessions.js";
 import { writePendingCallback, deletePendingCallback } from "#core/stores/runtime-callbacks.js";
 import { buildRuntimeBridgeHint as buildApfHint } from "#core/agent/runtime-bridge.js";
-import { detectAll } from "#core/runtimes/detect.js";
 import {
   findEngineSessionById,
   readEngineSessionContext,
 } from "#core/stores/engine-sessions.js";
-import { runProcess } from "#core/runtimes/_spawn.js";
 import { getRuntime, RUNTIME_IDS } from "#core/runtimes/index.js";
+import { runtimeLooksLikeFailure, runtimeAvailability } from "#core/runtimes/outcome.js";
 import { buildAgentSystem, resolveProject } from "../helpers.js";
 import { readJson } from "#core/util/json-file.js";
 
 const log = loggerFor("call_runtime");
 
-// Decide if the runtime actually did the work the model asked for. A spawn
-// failure (-1), a non-zero exit, or a clean exit with no captured output and
-// no transcript path all point at "process didn't really run" — exactly the
-// false-positive scenario this guard exists to catch.
-function runtimeLooksLikeFailure(r) {
-  if (!r) return { failed: true, reason: "no runtime result" };
-  if (r.exitCode === -1 || r.error) {
-    return { failed: true, reason: r.error || "spawn error" };
-  }
-  if (typeof r.exitCode === "number" && r.exitCode !== 0) {
-    return { failed: true, reason: `exit ${r.exitCode}` };
-  }
-  if (r.killed) return { failed: true, reason: "killed (timeout)" };
-  const out = String(r.output || "").trim();
-  const stderr = String(r.stderr || "").trim();
-  if (!out && !r.externalSessionPath && !r.sessionId) {
-    return {
-      failed: true,
-      reason: stderr ? `empty output (stderr: ${stderr.slice(0, 120)})` : "empty output",
-    };
-  }
-  return { failed: false };
+
+// A runtime that refuses to run is news the user needs BEFORE anything else
+// happens. Left to itself the model treats the failure as a routing hint: it
+// silently retries the next runtime, and if one of them answers it reports that
+// answer as a success — the user never learns their Claude CLI is logged out,
+// and gets a different engine's work under the name of the one they asked for.
+// So the failing result carries the obligation with it. An instruction, not a
+// sentence to parrot: the model still writes the message in its own voice, in
+// the user's language, with the diagnosis it just read.
+function runtimeFailureNextStep(runtime, reason) {
+  return [
+    `STOP. Tell the user, in your own words and their language, that "${runtime}" did not run`,
+    `and why (${reason}).`,
+    "Do NOT silently retry another runtime: a different engine's answer is not the one they asked for.",
+    "If a different runtime could still do the job, say so and let them choose;",
+    "if the cause looks fixable on their machine (login, quota, missing binary, stale version),",
+    "say what they would need to do. Never present a fallback runtime's output as if the requested one produced it.",
+  ].join(" ");
 }
 
 // If the model passed resume_session_id, look the session up (claude / codex /
@@ -121,30 +116,6 @@ function buildRuntimeSystem(project, agent, runtime, sessionId, caller) {
   ].join("\n\n");
 }
 
-async function runtimeAvailability(runtime, rt) {
-  const probe = await runProcess({
-    command: rt.binary,
-    args: rt.versionFlag ? [rt.versionFlag] : ["--version"],
-    timeoutMs: 3000,
-  });
-  if (probe.exitCode === 0 || probe.stdout || probe.stderr) {
-    return { ok: true };
-  }
-
-  const detected = await detectAll();
-  const current = detected.find((d) => d.id === runtime || d.binary === rt.binary);
-  if (current?.installed) {
-    return { ok: true, detected };
-  }
-  return {
-    ok: false,
-    reason: current?.reason || `${rt.binary} not found`,
-    detected,
-    installed: detected
-      .filter((d) => d.category === "runtime" && d.installed)
-      .map((d) => d.id),
-  };
-}
 
 export default {
   name: "call_runtime",
@@ -260,6 +231,7 @@ export default {
     // it as a callback instead of crashing an un-awaited promise.
     const runToCompletion = async () => {
       try {
+        const startedAt = Date.now();
         const r = await rt.run({
           system: buildRuntimeSystem(p, agent, runtime, session.id, "super_agent_tool"),
           prompt: effectivePrompt,
@@ -267,7 +239,11 @@ export default {
           timeoutMs: effectiveTimeoutS * 1000,
         });
 
-        const failure = runtimeLooksLikeFailure(r);
+        // A killed process can outlive its own SIGTERM: an orphaned grandchild
+        // holds the pipes open, so `close` (and this await) can land well after
+        // the deadline. "Did we reach the deadline", not "how long did we wait".
+        const timedOut = Date.now() - startedAt >= effectiveTimeoutS * 1000;
+        const failure = runtimeLooksLikeFailure(r, { timedOut, timeoutS: effectiveTimeoutS });
         const result = extractApfResult(r.output) || (r.output || "").slice(0, 200);
         closeRuntimeSession({
           filePath: session.path,
@@ -284,6 +260,7 @@ export default {
           body: effectivePrompt,
           meta: { runtime, invoked_by: "super_agent_tool", apc_session: session.id, resume_session_id: resume_session_id || null },
         });
+        // attribution-exempt: external runtime (claude/codex/…) stdout — APX did not make the model call, so it has no model/usage to record.
         p.logMessage({
           agent_slug: actor,
           channel: "runtime",
@@ -322,6 +299,7 @@ export default {
             output: (r.output || "").slice(0, 2000),
             external_session_path: r.externalSessionPath || null,
             session_id: r.sessionId || null,
+            next_step: runtimeFailureNextStep(runtime, failure.reason),
           };
         }
 

package/src/core/agent/tools/handlers/comment-task.js

@@ -0,0 +1,78 @@
+import { addComment } from "#core/stores/tasks.js";
+import { mentionedAgents } from "#core/tasks/comment-turn.js";
+import { missingArg, projectMeta, resolveProject } from "../helpers.js";
+import { SUPERAGENT_ACTOR_ID } from "#core/constants/actors.js";
+
+// Leave a comment on a task. The write-up half of working on one: an agent that
+// reviewed, tested or fixed something says so where the task is, instead of the
+// result living only in a chat nobody will scroll back to.
+//
+// IT DOES NOT SUMMON ANYONE. Mentions are recorded on the comment (so the thread
+// says who it was addressed to) but writing one here starts no agent turn. Only
+// the owner's own comment — and the cascade already running under its ceiling —
+// can do that. Otherwise an agent mid-cascade could open a second cascade from
+// inside its own turn, and the ceiling that makes the whole thing safe would be
+// counting one thread while several ran. Handing work to another agent is done
+// by naming them in the REPLY, which the cascade scans.
+export default {
+  name: "comment_task",
+  schema: {
+    type: "function",
+    function: {
+      name: "comment_task",
+      description:
+        "Add a comment to a task's thread. Use it to report what you found or did while working on a " +
+        "task — a QA verdict, a review note, what is blocking you — so it stays attached to the task " +
+        "instead of only in this conversation. Keep it to a few lines: it renders in a side panel next " +
+        "to the task. Call list_tasks first if you do not have the task id.",
+      parameters: {
+        type: "object",
+        required: ["task", "text"],
+        properties: {
+          task:    { type: "string", description: "Task id or unique id prefix (≥3 chars)." },
+          text:    { type: "string", description: "The comment. A few lines. Lead with the conclusion." },
+          project: { type: "string", description: "Project id, name or path. Defaults to 'default'." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects, channelMeta }) => async (args = {}) => {
+    const { task, text, project } = args;
+    if (!task) return missingArg("comment_task", "task", { required: ["task", "text"], optional: ["project"] }, args);
+    if (!text || !String(text).trim()) {
+      return missingArg("comment_task", "text", { required: ["task", "text"], optional: ["project"] }, args);
+    }
+
+    let p;
+    try {
+      p = resolveProject(projects, project || "default");
+    } catch (e) {
+      return { error: e.message };
+    }
+
+    try {
+      // Whoever is running this turn signs the comment. Falling back to a
+      // generic id would make every agent's notes indistinguishable in a thread
+      // whose entire value is knowing who said what.
+      const by = channelMeta?.agentSlug || SUPERAGENT_ACTOR_ID;
+      const mentions = mentionedAgents(text, p.path, by);
+      const result = addComment(p.storagePath, task, { by, text, mentions });
+      if (!result) return { error: `task not found: ${task}` };
+      return {
+        ok: true,
+        project: projectMeta(projects, p),
+        task: { id: result.id, title: result.title, comments: result.comments.length },
+        ...(mentions.length
+          ? {
+              mentions,
+              note:
+                "Recorded on the comment, but nobody was summoned by this call. " +
+                "To hand the work over, name them in your reply text instead.",
+            }
+          : {}),
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  },
+};

package/src/core/agent/tools/handlers/complete-task.js

@@ -0,0 +1,60 @@
+import { doneTask, dropTask, reopenTask, setTaskStatus } from "#core/stores/tasks.js";
+import { missingArg, projectMeta, resolveProject } from "../helpers.js";
+
+// Close or move a task. The sibling of create_task: the super-agent could add
+// and list tasks but not finish one, so a "mark it done" turned into a shelled
+// `apx task done`. This is the write-back half.
+export default {
+  name: "complete_task",
+  schema: {
+    type: "function",
+    function: {
+      name: "complete_task",
+      description:
+        "Change the state of an existing task: mark it done, drop it (archive without completing), reopen it, or set its workflow status (pending|running|in_review|blocked). Use after list_tasks to act on what you found. `done` vs `drop` matters — drop is 'no longer relevant', done is 'finished'.",
+      parameters: {
+        type: "object",
+        required: ["task", "action"],
+        properties: {
+          project: { type: "string", description: "Project id, name or path. Omit or 'default' for ~/.apx/projects/default." },
+          task:    { type: "string", description: "Task id or a ≥3-char unique prefix (from list_tasks)." },
+          action:  { type: "string", enum: ["done", "drop", "reopen", "status"], description: "done | drop | reopen | status." },
+          status:  { type: "string", enum: ["pending", "running", "in_review", "blocked"], description: "Required when action is 'status'." },
+          by:      { type: "string", description: "Optional: who completed/dropped it." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => async (args = {}) => {
+    const { project, task, action, status, by } = args;
+    await requirePermission("complete_task", { dangerous: true, args: { task, action } });
+    // `task`, not `id` — and the error says so, because list_tasks and
+    // create_task both hand back `id` and a model that copies it straight back
+    // here has no other way to learn the difference.
+    if (!task) return missingArg("complete_task", "task", { required: ["task", "action"], optional: ["project", "status", "by"] }, args);
+    let p;
+    try {
+      p = resolveProject(projects, project || "default");
+    } catch (e) {
+      return { error: e.message };
+    }
+    try {
+      let result;
+      if (action === "done") result = doneTask(p.storagePath, task, by || null);
+      else if (action === "drop") result = dropTask(p.storagePath, task, by || null);
+      else if (action === "reopen") result = reopenTask(p.storagePath, task);
+      else if (action === "status") {
+        if (!status) return { error: "status required when action is 'status'" };
+        result = setTaskStatus(p.storagePath, task, status);
+      } else return { error: `unknown action "${action}" (use done|drop|reopen|status)` };
+      if (!result) return { error: `task not found: ${task}` };
+      return {
+        ok: true,
+        project: projectMeta(projects, p),
+        task: { id: result.id, title: result.title, state: result.state, status: result.status },
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  },
+};

package/src/core/agent/tools/handlers/configure-agent.js

@@ -0,0 +1,70 @@
+import { setAgentConfig } from "#core/apc/agent-write.js";
+import { readAgents } from "#core/apc/parser.js";
+import { projectMeta, resolveProject } from "../helpers.js";
+
+// Change an existing agent's frontmatter (model, type, area, role, skills, …)
+// without touching its system prompt (use set_agent_prompt for that). Completes
+// the agent CRUD: create_agent → set_agent_prompt → configure_agent → remove_agent.
+export default {
+  name: "configure_agent",
+  schema: {
+    type: "function",
+    function: {
+      name: "configure_agent",
+      description:
+        "Edit an existing agent's settings (its frontmatter): model, type, area, role, description, language, skills, tools, emoji/icon, autonomy, parent, is_master. Keeps the system prompt (use set_agent_prompt to change that). Only the fields you pass change; pass an empty string to clear one.",
+      parameters: {
+        type: "object",
+        required: ["agent"],
+        properties: {
+          project:     { type: "string", description: "Project id, name or path. Omit or 'default' for ~/.apx/projects/default." },
+          agent:       { type: "string", description: "Slug of the agent to edit (from list_agents)." },
+          model:       { type: "string", description: "Per-agent model override (empty string clears it → follows the default)." },
+          role:        { type: "string", description: "One-line role." },
+          description: { type: "string", description: "One line of metadata for listings." },
+          language:    { type: "string", description: "Default language code, e.g. 'es'." },
+          type:        { type: "string", description: "Agent typology (specialist, orchestrator, …)." },
+          area:        { type: "string", description: "Org area slug/name." },
+          skills:      { type: "array", items: { type: "string" }, description: "Replace the skill list." },
+          tools:       { type: "array", items: { type: "string" }, description: "Replace the tools allowlist (declaring one NARROWS the agent)." },
+          emoji:       { type: "string", description: "Emoji badge." },
+          icon:        { type: "string", description: "Avatar blob key." },
+          autonomy:    { type: "string", description: "Per-agent autonomy: total | automatico | permiso." },
+          parent:      { type: "string", description: "Parent agent slug." },
+          is_master:   { type: "boolean", description: "Mark/unmark as a master agent." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects, requirePermission }) => async (args = {}) => {
+    const { project, agent } = args;
+    await requirePermission("configure_agent", { dangerous: true, args: { agent, project } });
+    if (!agent) return { error: "agent required" };
+    let p;
+    try {
+      p = resolveProject(projects, project || "default");
+    } catch (e) {
+      return { error: e.message };
+    }
+    try {
+      setAgentConfig(p, agent, args);
+      projects.rebuild(p.id);
+      const updated = readAgents(p.path).find((a) => a.slug === agent);
+      const f = updated?.fields || {};
+      return {
+        ok: true,
+        project: projectMeta(projects, p),
+        agent: {
+          slug: agent,
+          role: f.Role || null,
+          model: f.Model || null,
+          type: f.Type || null,
+          area: f.Area || null,
+          skills: f.Skills || [],
+        },
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  },
+};