agentradar-cli 0.3.6 → 0.3.8

package/dist/skill-install.js

@@ -82,13 +82,15 @@ export function skillsDirFor(harness, env) {
     return dir.includes("\0") ? null : join(dir);
 }
 export async function syncJoinedSkills(runnerId, deps) {
-    const env = await readFile(join(deps.home, ".agentradar", "agents", `${runnerId}.env`), "utf8");
-    const harness = envValue(env, "AR_AGENT_HARNESS");
-    const skillsDir = skillsDirFor(harness, (name) => name === "HOME" ? deps.home : envValue(env, name));
+    const file = await readFile(join(deps.home, ".agentradar", "agents", `${runnerId}.env`), "utf8").catch(() => null);
+    // A hosted session has no runner file: it is Claude Code, and its channel's env carries AR_BASE (hosted-session-start.mjs).
+    const value = (name) => file === null ? process.env[name] ?? null : envValue(file, name);
+    const harness = file === null ? "claude" : value("AR_AGENT_HARNESS");
+    const skillsDir = skillsDirFor(harness, (name) => name === "HOME" ? deps.home : value(name));
     if (!skillsDir)
         return;
     const codex = harness === "codex";
-    const root = (codex ? envValue(env, "CODEX_HOME") : envValue(env, "AR_BASE")) ?? "";
+    const root = (codex ? value("CODEX_HOME") : value("AR_BASE")) ?? "";
     // Vadym 9988: the server's start instructions with this agent's brief, before its first session starts.
     // Same file and mark as the runner's feeder, which keeps it fresh from then on.
     const init = await awpRequest(runnerId, "initialize", {

package/dist/tool-run.js

@@ -1,8 +1,8 @@
-import { readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { commandFor, DEPRECATED_TOOLS, toolFor } from "./commands.js";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { cliHeader, noteCliUpdate, withCliUpdate } from "./update.js";
+const UNAUTHORIZED = "AgentRadar refused the tool call (401): this agent's key is no longer valid on this server (it was revoked, or the hire it was issued for has ended). Nothing was done. Stop calling tools with this key and tell the person who runs you.";
 /**
  * One `KEY='value'` line as `setup.ts` wrote it, single-quoted with `'` escaped as `'\''`.
  * Nothing here is printed: the file holds the runner's bearer.
@@ -15,39 +15,59 @@ export function envValue(contents, key) {
     const quoted = raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2;
     return (quoted ? raw.slice(1, -1).replaceAll("'\\''", "'") : raw) || null;
 }
-export async function runServiceToolOverCli(runnerId, toolKey, argumentsJson, deps = {}) {
-    const parameters = argumentsJson === undefined ? {} : parseArgumentsObject(argumentsJson, deps.logError ?? console.error);
-    if (!parameters)
-        return 1;
-    return await callAwpTool(runnerId, "run_service_tool", { toolKey, arguments: parameters, entryPoint: "cli" }, deps);
-}
-/** `agentradar call <runner-id> <tool> [--<argument> <value> ...] [--args '<json>']`: any AWP tool from a shell, so a just-joined agent works before its harness reloads MCP tools. */
-export async function callToolOverCli(runnerId, tool, argumentsJson, deps = {}, flags = []) {
+/**
+ * #1871 slice 1: `agentradar <noun> [<sub-noun>] <verb> [--<argument> <value> ...]`, every path read from the server's
+ * tools/list (`_meta.cli.path`), so a new tool or a renamed path needs no CLI release. `command` is that path, or a
+ * tool name (`call <runner-id> <tool>` and `run <runner-id> <tool>` stay until slices 4-5). A group prints its
+ * children, a leaf with --help its generated flags.
+ */
+export async function callToolOverCli(runnerId, command, argumentsJson, deps = {}, flags = []) {
     const switches = new Set(flags.filter(([flag]) => ["help", "dry-run", "json"].includes(flag)).map(([flag]) => flag));
     flags = flags.filter(([flag]) => !switches.has(flag));
-    // A noun has no underscore; a tool name has one unless it is a single word (reply, recall), which the resolver returns as is.
-    if (tool.includes(" ") || (switches.has("help") && tool !== "" && !tool.includes("_"))) {
-        const resolved = await resolveCommand(runnerId, tool, switches.has("help"), deps);
-        if (typeof resolved === "number")
-            return resolved;
-        tool = resolved;
-    }
-    if (switches.has("help"))
-        return await describeTools(runnerId, tool, deps);
+    let tool = command;
     const parameters = argumentsJson === undefined ? {} : parseArgumentsObject(argumentsJson, deps.logError ?? console.error);
     if (!parameters)
         return EXIT.usage;
-    if (flags.length) {
-        const typed = await flagArguments(runnerId, tool, flags, deps);
-        if (!typed)
-            return EXIT.usage;
-        Object.assign(parameters, typed);
+    // A bare tool name with nothing to type goes straight to the server: the hot `inbox next` poll and the get_self probe
+    // cost no tools/list round trip.
+    if (switches.has("help") || flags.length || argumentsJson !== undefined || !command.includes("_")) {
+        const tools = await listedTools(runnerId, deps);
+        if (!tools)
+            return EXIT.refused;
+        const entry = tools.find((candidate) => pathOf(candidate) === command) ?? tools.find((candidate) => candidate.name === command);
+        if (!entry?.name)
+            return groupHelp(runnerId, command, tools, switches.has("help"), deps);
+        if (switches.has("help")) {
+            (deps.log ?? console.log)(leafHelp(entry));
+            return EXIT.ok;
+        }
+        tool = entry.name;
+        const schema = entry.inputSchema?.properties ?? {};
+        // PER-TOOL-MODES (Vadym 12919): `--tool X=ask` builds `tools`, on any tool that takes `tools` and no `tool`.
+        if ("tools" in schema && !("tool" in schema) && flags.some(([flag]) => flag === "tool")) {
+            const named = namedToolFlags(flags);
+            parameters.tools = named.tools;
+            flags = named.flags;
+        }
+        if (flags.length) {
+            const typed = await flagArguments(entry, flags, deps);
+            if (!typed)
+                return EXIT.usage;
+            Object.assign(parameters, typed);
+        }
+        // Provenance for the execution ledger (R572), not permission: the server treats it as the self-report it is.
+        if ("entryPoint" in schema && parameters.entryPoint === undefined)
+            parameters.entryPoint = "cli";
     }
     // --dry-run: say exactly what would be sent, and send nothing.
     if (switches.has("dry-run")) {
         (deps.log ?? console.log)(JSON.stringify({ dryRun: true, tool, arguments: parameters }));
         return EXIT.ok;
     }
+    if (tool === "inbox_search" && !switches.has("json")) {
+        const log = deps.log ?? console.log;
+        deps = { ...deps, log: (text) => log(inboxLines(text)) };
+    }
     if (tool !== "next_event" || !RUNNER_ID.test(runnerId))
         return await callAwpTool(runnerId, tool, parameters, deps);
     // A bare poll acknowledges the batch the previous poll printed, so the command stays byte-identical and
@@ -59,6 +79,8 @@ export async function callToolOverCli(runnerId, tool, argumentsJson, deps = {},
         if (Array.isArray(ids) && ids.length)
             parameters.ackEventIds = ids;
     }
+    // The agent's own poll answers at once: the channel process holds the long poll, and a held agent call stalls its whole turn.
+    parameters.waitMs ??= 0;
     let said = "";
     const code = await callAwpTool(runnerId, tool, parameters, { ...deps, log: (text) => { said = text; (deps.log ?? console.log)(text); } });
     if (code !== 0)
@@ -69,7 +91,8 @@ export async function callToolOverCli(runnerId, tool, argumentsJson, deps = {},
     }
     catch { /* not a batch: nothing to acknowledge */ }
     const ids = Array.isArray(events) ? events.map((event) => event?.eventId).filter((id) => typeof id === "string") : [];
-    await writeFile(delivered, JSON.stringify(ids), { mode: 0o600 }).catch(() => undefined);
+    // A hosted home has no runner file, so the folder may not exist yet; without it the ack and the channel's proof of a poll were lost.
+    await mkdir(dirname(delivered), { recursive: true }).then(() => writeFile(delivered, JSON.stringify(ids), { mode: 0o600 })).catch(() => undefined);
     return 0;
 }
 /**
@@ -77,39 +100,16 @@ export async function callToolOverCli(runnerId, tool, argumentsJson, deps = {},
  * (its sentence is on stderr); 2 the command itself was wrong (unknown command, missing or mistyped argument).
  */
 export const EXIT = { ok: 0, refused: 1, usage: 2 };
-/**
- * `<noun> <verb>` → the tool it names on this server; or an exit code once `<noun> --help` has listed its
- * verbs, or after saying what is wrong.
- */
-async function resolveCommand(runnerId, command, help, deps) {
-    const tools = await listedTools(runnerId, deps);
-    if (!tools)
-        return EXIT.refused;
-    const names = tools.map((entry) => entry.name ?? "").filter((name) => name && !DEPRECATED_TOOLS.has(name));
-    const [noun, verb] = command.split(" ");
-    if (!verb && names.includes(noun))
-        return noun;
-    if (verb) {
-        const tool = toolFor(noun, verb, names);
-        if (tool)
-            return tool;
-    }
-    const verbs = names.filter((name) => commandFor(name)[0] === noun).map((name) => commandFor(name)[1]).sort();
-    const log = help && !verb ? deps.log ?? console.log : deps.logError ?? console.error;
-    log(verbs.length
-        ? `${verb ? `${noun} ${verb} is not a command. ` : ""}agentradar run ${runnerId} ${noun} <verb>: ${verbs.join(" ")}. Add --help to a command for its arguments.`
-        : `${noun} is not a command group. Groups: ${[...new Set(names.map((name) => commandFor(name)[0]))].sort().join(" ")}.`);
-    return help && !verb && verbs.length ? EXIT.ok : EXIT.usage;
-}
-/** Split `<runner-id> <tool> [--args '<json>'] [--<argument> <value> ...]`; null when it is not that shape. */
+const EXIT_CODES = "EXIT CODES\n  0 done   1 refused or unreachable (the reason is on stderr)   2 fix the command";
+/** Split `<word> ... [--args '<json>'] [--<argument> <value> ...]`; null when a flag has no value. */
 export function parseCallArgs(rest) {
-    const positional = [];
+    const words = [];
     const flags = [];
     let json;
     for (let i = 0; i < rest.length; i++) {
         const arg = rest[i];
         if (!arg.startsWith("--")) {
-            positional.push(arg);
+            words.push(arg);
             continue;
         }
         if (arg === "--help" || arg === "--dry-run" || arg === "--json") {
@@ -124,63 +124,99 @@ export function parseCallArgs(rest) {
         else
             flags.push([arg.slice(2), value]);
     }
-    const help = flags.some(([flag]) => flag === "help");
-    // `<runner-id> <noun> <verb>` (Vadym 9970) names the same tool as `<runner-id> <tool>`; resolved against the server's list.
-    if (positional.length === 3)
-        return { runnerId: positional[0], tool: `${positional[1]} ${positional[2]}`, json, flags };
-    return positional.length === 2 || (help && positional.length === 1)
-        ? { runnerId: positional[0], tool: positional[1] ?? "", json, flags } : null;
+    return { words, json, flags };
 }
+const pathOf = (tool) => typeof tool._meta?.cli?.path === "string" ? tool._meta.cli.path : undefined;
+const kebab = (name) => name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+const firstSentence = (text = "") => text.split(/(?<=[.!?])\s/)[0].trim();
+// Vadym 14075: a hosted agent tried ~10 key sets for approvalDetails on request_egress and never found the real ones,
+// so --help spells out a JSON argument's fields and these commands carry one complete example each.
+// The approvals and browser skills quote this output word for word (tool-run.test.ts checks it).
+const APPROVAL_EXAMPLES = {
+    request_egress: `--host supplier.example.com --reason 'The price list task needs this supplier website.' --approval-details '{"context":"The price list task needs prices from a supplier website.","reason":"No connector has these prices, and the website is the only source.","ifDeclined":"The price list stays unfinished.","decisionDetail":"Let my browser reach supplier.example.com."}'`,
+    request_spend_limit: `--monthly-limit-cents 5000 --reason 'The weekly reports need more AI time.' --approval-details '{"context":"I used most of my monthly AI limit by the 20th.","reason":"The weekly reports added this month need more AI time.","ifDeclined":"I pause the weekly reports until next month.","decisionDetail":"Raise my monthly AI limit to $50."}'`,
+    request_hire: `--title 'Support agent' --approval-details '{"context":"Customer emails wait two days for an answer.","reason":"Nobody on the team has time to answer them.","ifDeclined":"Emails keep waiting and some customers may leave.","decisionDetail":"Hire one support agent to answer customer emails."}'`,
+    request_permission: `--area projects --op write --approval-details '{"context":"I was asked to create a project for the spring launch.","reason":"My role can read projects but not create them.","ifDeclined":"Someone else has to create the project.","decisionDetail":"Let my role create and edit projects."}'`,
+};
+/** `  context (required, 1-600 characters): What happened: ...` for each field of a JSON argument. */
+const fieldLines = (name, schema, root) => [`--${kebab(name)} is JSON with these fields:`,
+    ...Object.entries(schema.properties ?? {}).map(([field, own]) => {
+        // A field reusing another's rule arrives as {"$ref": "#/properties/approvalDetails/properties/context"} plus its own description.
+        const f = { ...own.$ref?.split("/").slice(1).reduce((at, key) => at?.[key], root), ...own };
+        const size = f.minLength !== undefined && f.maxLength !== undefined ? `, ${f.minLength}-${f.maxLength} characters` : "";
+        return `  ${field} (${schema.required?.includes(field) ? "required" : "optional"}${size})${f.description ? `: ${f.description}` : ""}`;
+    })];
 async function listedTools(runnerId, deps) {
     const listed = await awpRequest(runnerId, "tools/list", {}, deps);
     return listed ? listed.result?.tools ?? [] : null;
 }
-// An agent that guessed a tool name from memory needs the real list, or it goes looking with commands
-// its harness has not allowed and the session stalls on a permission prompt.
-const unknownTool = (runnerId, tool, tools) => `${tool} is not a tool on this server. Its tools: ${tools.map((entry) => entry.name).join(" ")}. `
-    + `\`agentradar run ${runnerId} <tool> --help\` shows a tool's arguments.`;
-/** `agentradar run <runner-id> [<tool>] --help`: the server's own tool list or one tool's arguments. */
-async function describeTools(runnerId, tool, deps) {
-    const tools = await listedTools(runnerId, deps);
-    if (!tools)
-        return 1;
-    const log = deps.log ?? console.log;
-    if (!tool) {
-        log(`Tools: ${tools.map((entry) => entry.name).join(" ")}. \`agentradar run ${runnerId} <tool> --help\` shows a tool's arguments.`);
-        return 0;
+// A connected service's tool (ask_question on a company's MCP) is never in the tool list, so an agent told to use one by
+// name said "not available" instead of running it (behaviour evals tool-mode, approval-third-person; #2010).
+const serviceTools = (runnerId, tools) => {
+    const command = (name) => { const tool = tools.find((entry) => entry.name === name); return tool && (pathOf(tool) ?? `run ${runnerId} ${name}`); };
+    return command("run_service_tool")
+        ? ` A tool of a service your company connected is not in this list: \`agentradar ${command("list_service_tools")}\` shows them,`
+            + ` and \`agentradar ${command("run_service_tool")} --tool-key <tool> --arguments '<its arguments as JSON>'\` runs one.`
+        : "";
+};
+/** `agentradar <group> --help`: one line per child; anything else that names no command is a usage error that lists the groups. */
+function groupHelp(runnerId, command, tools, help, deps) {
+    const prefix = command ? `${command} ` : "";
+    const children = new Map();
+    for (const tool of tools) {
+        const path = pathOf(tool);
+        if (!path?.startsWith(prefix))
+            continue;
+        const word = path.slice(prefix.length).split(" ")[0];
+        children.set(word, [...children.get(word) ?? [], tool]);
     }
-    const entry = tools.find((candidate) => candidate.name === tool);
-    if (!entry) {
-        (deps.logError ?? console.error)(unknownTool(runnerId, tool, tools));
-        return 1;
+    if (!children.size) {
+        const groups = [...new Set(tools.map(pathOf).filter((path) => path).map((path) => path.split(" ")[0]))].sort();
+        (deps.logError ?? console.error)(`${command} is not a command. Groups: ${groups.join(" ")}. \`agentradar <group> --help\` lists its commands.${serviceTools(runnerId, tools)}`);
+        return EXIT.usage;
     }
-    const required = entry.inputSchema?.required ?? [];
-    const names = Object.keys(entry.inputSchema?.properties ?? {}).map((name) => `--${name}${required.includes(name) ? " (required)" : ""}`);
-    log(`${tool}: ${entry.description ?? ""}\nArguments: ${names.join(" ") || "none"}`);
-    return 0;
+    const lines = [...children].sort(([a], [b]) => a.localeCompare(b)).map(([word, leaves]) => `  ${word.padEnd(16)} ${leaves.length === 1 && pathOf(leaves[0]) === `${prefix}${word}` ? firstSentence(leaves[0].description) : `(${leaves.length} commands)`}`);
+    (help ? deps.log ?? console.log : deps.logError ?? console.error)([
+        `agentradar ${prefix}<${command ? "command" : "group"}>`, ...lines,
+        `Add --help to any of them for its flags.${command ? "" : serviceTools(runnerId, tools)}`,
+    ].join("\n"));
+    return help ? EXIT.ok : EXIT.usage;
+}
+/** `agentradar <path> --help`: the description, usage, required and optional flags, all generated from the inputSchema. */
+function leafHelp(tool) {
+    const properties = tool.inputSchema?.properties ?? {};
+    const required = tool.inputSchema?.required ?? [];
+    const typeOf = (schema) => schema.enum ? schema.enum.join("|")
+        : [schema.type].flat()[0] === "array" ? `${typeOf(schema.items ?? {})} (a list: repeat the flag, or pass one JSON array)` : `<${[schema.type].flat()[0] ?? "value"}>`;
+    const flag = (name) => `  --${kebab(name)} ${typeOf(properties[name])}${properties[name].description ? `  ${firstSentence(properties[name].description)}` : ""}`;
+    const optional = Object.keys(properties).filter((name) => !required.includes(name));
+    const path = pathOf(tool) ?? `call <runner-id> ${tool.name}`;
+    return [
+        tool.description ?? "", "",
+        "USAGE", `  agentradar ${path}${required.map((name) => ` --${kebab(name)} ${typeOf(properties[name] ?? {})}`).join("")}${optional.length ? " [flags]" : ""}`,
+        ...(required.length ? ["REQUIRED", ...required.filter((name) => name in properties).map(flag)] : []),
+        "FLAGS", ...optional.map(flag), "  --dry-run  print the exact call and send nothing   --json  raw JSON   --runner <id>  the runner (default $AR_CLI_RUNNER_ID)",
+        ...Object.entries(properties).flatMap(([name, schema]) => schema.properties ? fieldLines(name, schema, tool.inputSchema) : []),
+        ...(tool.name && APPROVAL_EXAMPLES[tool.name] ? [`Example: agentradar ${path} ${APPROVAL_EXAMPLES[tool.name]}`] : []),
+        EXIT_CODES,
+    ].join("\n");
 }
 /**
  * `--text "hi" --thread-id X` as the tool's own arguments, typed by the inputSchema the server
  * advertises, so an agent never types JSON (braces and quotes) into a shell command.
  */
-async function flagArguments(runnerId, tool, flags, deps) {
+async function flagArguments(entry, flags, deps) {
     const logError = deps.logError ?? console.error;
-    const tools = await listedTools(runnerId, deps);
-    if (!tools)
-        return null;
-    const entry = tools.find((candidate) => candidate.name === tool);
-    if (!entry) {
-        logError(unknownTool(runnerId, tool, tools));
-        return null;
-    }
     const schema = entry.inputSchema?.properties ?? {};
     const out = {};
     const camel = (flag) => flag.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
     for (let [flag, value] of flags) {
         // --body-file page.md: the argument read from a file, so a multi-line page never sits in a quoted
         // shell argument (Claude Code prompts on a newline followed by # inside one).
+        // --content-base64-file page.html: a *Base64 argument gets the file's bytes as base64, any type (ANY-FILE-SEND).
         if (flag.endsWith("-file") && !(flag in schema) && !(camel(flag) in schema)) {
-            const text = await readArgumentFile(value, deps.cwd ?? process.cwd(), deps.home ?? homedir()).catch((error) => error);
+            const binary = camel(flag.slice(0, -"-file".length)).endsWith("Base64");
+            const text = await readArgumentFile(value, deps.cwd ?? process.cwd(), deps.home ?? homedir(), binary).catch((error) => error);
             if (text instanceof Error) {
                 logError(`--${flag}: ${text.message}`);
                 return null;
@@ -190,37 +226,73 @@ async function flagArguments(runnerId, tool, flags, deps) {
         // --text is what agents reach for on append_task_log, whose argument is --entry.
         const key = flag in schema ? flag : flag === "text" && "entry" in schema ? "entry" : camel(flag);
         if (!(key in schema)) {
-            logError(`${tool} has no argument --${flag}. Its arguments: ${Object.keys(schema).map((name) => `--${name}`).join(" ") || "none"}`);
+            logError(`${pathOf(entry) ?? entry.name} has no flag --${flag}. Its flags: ${Object.keys(schema).map((name) => `--${kebab(name)}`).join(" ") || "none"}`);
             return null;
         }
         const type = [schema[key].type].flat()[0];
-        const typed = coerce(type === "array" ? [schema[key].items?.type].flat()[0] : type, value);
+        if (type === "array") {
+            // A list is one JSON array or a repeated flag (#1752): --message-ids a --message-ids b, or --tools '[{...},{...}]'.
+            const itemType = [schema[key].items?.type].flat()[0];
+            const items = parseList(value, itemType);
+            if (!items) {
+                logError(listFlagError(flag, itemType, schema[key]));
+                return null;
+            }
+            out[key] = [...(out[key] ?? []), ...items];
+            continue;
+        }
+        const typed = coerce(type, value);
         if (typed === undefined) {
-            logError(`--${flag} must be ${type === "array" ? "a list of " + schema[key].items?.type : "a " + type}`);
+            logError(schema[key].properties
+                ? `--${flag} must be JSON with the fields ${(schema[key].required ?? Object.keys(schema[key].properties)).join(", ")}; \`agentradar ${pathOf(entry) ?? `call <runner-id> ${entry.name}`} --help\` shows each one.`
+                : `--${flag} must be a ${type}`);
             return null;
         }
-        // A repeated flag builds a list: --message-ids a --message-ids b.
-        out[key] = type === "array" ? [...(out[key] ?? []), typed] : typed;
+        out[key] = typed;
     }
     return out;
 }
+/** One flag's items: a JSON array spreads (a nested-list schema keeps it whole), anything else is a single item; null when an item does not fit the type. */
+function parseList(value, itemType) {
+    let parsed;
+    if (itemType !== "array" && value.trimStart().startsWith("["))
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch { /* a single item that starts with "[" */ }
+    const items = Array.isArray(parsed) ? parsed : [coerce(itemType, value)];
+    const fits = (item) => itemType === "object" ? !!item && typeof item === "object" && !Array.isArray(item)
+        : itemType === "array" ? Array.isArray(item)
+            : itemType === "integer" ? Number.isInteger(item)
+                : itemType === "number" || itemType === "string" || itemType === "boolean" ? typeof item === itemType
+                    : item !== undefined;
+    return items.every(fits) ? items : null;
+}
+/** What an agent reads when a list argument is mistyped: both accepted forms, with an example built from the tool's own item fields. */
+function listFlagError(flag, itemType, schema) {
+    const fields = Object.keys(schema.items?.properties ?? {});
+    const object = `{${(fields.length ? fields : ["key"]).map((name) => `"${name}":"..."`).join(",")}}`;
+    const [one, two] = itemType === "object" ? [object, object] : itemType === "number" || itemType === "integer" ? ["1", "2"] : itemType === "boolean" ? ["true", "false"] : ['"a"', '"b"'];
+    const bare = (item) => (itemType === "object" ? `'${item}'` : item.replaceAll('"', ""));
+    return `--${flag} takes a list of ${itemType ?? "values"}: either one JSON array, --${flag} '[${one},${two}]', or the flag repeated, --${flag} ${bare(one)} --${flag} ${bare(two)}.`;
+}
 /**
  * `agentradar run` is always-allowed, so a file flag must not read and upload any file the agent names:
- * only a regular file inside the working folder (after symlinks), and at most 256 KB — and never one in
+ * only a regular file inside the working folder (after symlinks), and at most 256 KB (7 MB as base64) — and never one in
  * ~/.agentradar, which holds the runner's own key even when the working folder is $HOME.
  * ponytail: a hard link to the key is not caught (same inode, different path); making one is the agent's own act.
  */
-async function readArgumentFile(path, cwd, home) {
+async function readArgumentFile(path, cwd, home, binary = false) {
     const real = await realpath(resolve(cwd, path)).catch(() => { throw new Error(`cannot read ${path}`); });
     const within = (dir) => { const inside = relative(dir, real); return inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside); };
     const own = await realpath(join(home, ".agentradar")).catch(() => null);
     if (own && within(own))
         throw new Error(`${path} is refused: a file flag never reads AgentRadar's own folder (~/.agentradar), which holds this agent's key`);
     const info = await stat(real);
-    if (!info.isFile() || !within(await realpath(cwd)) || info.size > 256 * 1024) {
-        throw new Error(`${path} is refused: a file flag reads only a regular file inside the current folder, up to 256 KB`);
+    if (!info.isFile() || !within(await realpath(cwd)) || info.size > (binary ? 7 * 1024 * 1024 : 256 * 1024)) {
+        throw new Error(`${path} is refused: a file flag reads only a regular file inside the current folder, up to ${binary ? "7 MB" : "256 KB"}`);
     }
-    return await readFile(real, "utf8");
+    return binary ? (await readFile(real)).toString("base64") : await readFile(real, "utf8");
 }
 function coerce(type, value) {
     if (type === "string")
@@ -238,22 +310,7 @@ function coerce(type, value) {
         return type === undefined ? value : undefined;
     }
 }
-// The parity test (server human-metrics-ext-realpg) fails when report_metric gains an argument this line does not name.
-export const METRIC_REPORT_USAGE = "Usage: agentradar metric report <runner-id> --metric-id <id> --value <n> --period-start <iso> --period-end <iso> [--evidence <text>] [--from-event-id <id>] [--comment <text>]";
-// The parity test (server r013-propose-human-realpg) fails when propose_human gains an argument this line does not name.
-export const PROPOSE_HUMAN_USAGE = "Usage: agentradar propose-human <runner-id> --name <name> --email <email> --role-id <id>";
-// The parity test (server listing-description-realpg) fails when set_listing_description gains an argument this line does not name.
-export const LISTING_DESCRIBE_USAGE = "Usage: agentradar listing describe <runner-id> --capabilities <text>";
-// The parity test (server inbox-search-realpg) fails when inbox_search gains an argument this line does not name.
-export const INBOX_SEARCH_USAGE = "Usage: agentradar inbox search <runner-id> [--query <text>] [--channel <c>] [--thread-id <id>] [--sender <s>] [--from <iso>] [--to <iso>] [--has-attachment true] [--unread true] [--unacked true] [--limit <n>] [--before <cursor>] [--after <cursor>] [--around <message-id>] [--json]";
-/**
- * INBOX-SEARCH (Vadym 9974) — `agentradar inbox search <runner-id> [--query <text>] [--<filter> <value> ...] [--json]`:
- * the MCP `inbox_search` on the same endpoint with the same key. One block per message, or the tool's JSON with --json.
- */
-export async function inboxSearchOverCli(runnerId, flags, json, deps = {}) {
-    const log = deps.log ?? console.log;
-    return await callToolOverCli(runnerId, "inbox_search", undefined, json ? deps : { ...deps, log: (text) => log(inboxLines(text)) }, flags);
-}
+/** INBOX-SEARCH (Vadym 9974): one block per message; `--json` keeps the tool's own JSON. */
 function inboxLines(text) {
     let body;
     try {
@@ -270,32 +327,13 @@ function inboxLines(text) {
     const pages = [body.older && `Older: --before ${body.older}`, body.newer && `Newer: --after ${body.newer}`].filter(Boolean);
     return [...results.map((r) => `${r.at}  ${r.channel}  ${r.sender?.name ?? r.from ?? ""}\n  thread ${r.threadId}  message ${r.messageId}\n  ${r.snippet}`), ...pages].join("\n");
 }
-/**
- * Vadym 10719 — `agentradar permissions mine|roles|set|request|grant-tool <runner-id> [--<argument> <value> ...]`: the MCP permission
- * tools on the same endpoint with the same key. The parity test (server permission-tools-realpg) fails when one drifts.
- */
-export const PERMISSION_VERB_TOOLS = {
-    mine: "my_permissions",
-    roles: "read_role_permissions",
-    set: "set_role_permission",
-    request: "request_permission",
-    "grant-tool": "propose_tool_assignment",
-};
-/**
- * Ruling 49 — `agentradar task create|repeat|make-recurring <runner-id> --args '<json>'`: the agent's own
- * `create_task`, `create_recurring_task` or `make_task_recurring` (Vadym 10317), on the same AWP endpoint
- * with the same key, so who it may assign to is the server's decision exactly as it is over MCP.
- */
-export const TASK_VERB_TOOLS = {
-    create: "create_task",
-    repeat: "create_recurring_task",
-    "make-recurring": "make_task_recurring",
-};
-export async function createTaskOverCli(runnerId, verb, argumentsJson, deps = {}) {
-    const parameters = parseArgumentsObject(argumentsJson, deps.logError ?? console.error);
-    if (!parameters)
-        return 1;
-    return await callAwpTool(runnerId, TASK_VERB_TOOLS[verb], parameters, deps);
+/** PER-TOOL-MODES (Vadym 12919): `--tool X=ask --tool Y=blocked` is `tools: [{toolKey: X, mode: ask}, ...]`; a bare `--tool X` takes `--mode`. */
+export function namedToolFlags(flags) {
+    const tools = flags.filter(([flag]) => flag === "tool").map(([, value]) => {
+        const at = value.lastIndexOf("=");
+        return at < 0 ? { toolKey: value } : { toolKey: value.slice(0, at), mode: value.slice(at + 1) };
+    });
+    return { tools, flags: flags.filter(([flag]) => flag !== "tool") };
 }
 function parseArgumentsObject(argumentsJson, logError) {
     let parsed;
@@ -312,14 +350,6 @@ function parseArgumentsObject(argumentsJson, logError) {
     }
     return parsed;
 }
-/**
- * R251 — `agentradar tool list <runner-id>`: the server's own `list_service_tools`, printed as it
- * answered. The listing is the policy's preview for this agent, so the CLI computes nothing — a second
- * copy of the decision here could only drift from the one the MCP tool and every real call make.
- */
-export async function listServiceToolsOverCli(runnerId, deps = {}) {
-    return await callAwpTool(runnerId, "list_service_tools", {}, deps);
-}
 /** One `tools/call` on the runner's AWP MCP endpoint with the runner's own key; the answer is printed verbatim. */
 export async function callAwpTool(runnerId, name, toolArguments, deps) {
     const log = deps.log ?? console.log;
@@ -332,7 +362,8 @@ export async function callAwpTool(runnerId, name, toolArguments, deps) {
     // A refusal is the server's sentence and belongs on stderr with a non-zero exit, or a script that
     // pipes stdout reads "the tool ran" from a body that says it was refused.
     if (body.result?.isError) {
-        logError(said);
+        // The server's JSON, then its plain "AgentRadar refused <tool>: ... Now: ..." line when it sends one.
+        logError([said, ...(body.result.content ?? []).slice(1).map((c) => c.text).filter((t) => typeof t === "string")].join("\n"));
         return 1;
     }
     log(withCliUpdate(said));
@@ -344,7 +375,15 @@ export async function awpRequest(runnerId, method, params, deps) {
     const target = await awpEndpoint(runnerId, deps);
     if (!target)
         return null;
-    return postAwp(target.url, target.bearer, method, params, deps);
+    const result = await postAwp(target.url, target.bearer, method, params, deps);
+    // A hosted workspace stops after 15 idle minutes; the bridge reads this file's mtime, so a background job that
+    // keeps calling AgentRadar keeps it awake. Only a call that succeeded counts: a loop of failing calls must not hold
+    // the box up. Platform hooks (AR_HOOK) and skill sync are not the agent's work.
+    if (result !== null && target.hosted && (deps.env ?? process.env).AR_HOOK !== "1" && deps.surface !== "skill-sync") {
+        const run = join(deps.home ?? homedir(), ".agentradar", "run");
+        await mkdir(run, { recursive: true }).then(() => writeFile(join(run, "activity"), "")).catch(() => { });
+    }
+    return result;
 }
 /** The runner's MCP endpoint and bearer: its runner file, else a hosted run's own environment. */
 export async function awpEndpoint(runnerId, deps) {
@@ -378,7 +417,7 @@ export async function awpEndpoint(runnerId, deps) {
         }
         url = `${origin}/api/mcp`;
     }
-    return { url, bearer };
+    return { url, bearer, hosted: contents === null };
 }
 async function postAwp(url, bearer, method, params, deps) {
     const logError = deps.logError ?? console.error;
@@ -400,14 +439,14 @@ async function postAwp(url, bearer, method, params, deps) {
     });
     await noteCliUpdate(response.headers, logError);
     if (!response.ok) {
-        // 426: this CLI is below the server's minimum; its sentence says how to upgrade.
-        const said = response.status === 426 ? await response.json().then((body) => body.error?.message).catch(() => null) : null;
-        logError(said ?? `AgentRadar refused the tool call (${response.status}).`);
+        // 426 says how to upgrade; 401 says why the key was refused and how to re-join.
+        const said = await response.json().then((body) => body.error?.message).catch(() => null);
+        logError(said ?? (response.status === 401 ? UNAUTHORIZED : `AgentRadar refused the tool call (${response.status}).`));
         return null;
     }
     const body = await response.json();
     if (body.error) {
-        logError(typeof body.error.message === "string" ? body.error.message : "AgentRadar returned an error");
+        logError(typeof body.error.message === "string" ? body.error.message : `AgentRadar returned an error to ${method === "tools/call" ? String(params.name) : method}. Now: run \`agentradar upgrade\`, then try again.`);
         return null;
     }
     return body;