agentradar-cli 0.3.8 → 0.3.10

package/dist/setup.js

@@ -702,6 +702,26 @@ async function callerSession(deps, env, home, projectPath) {
  * restarts the service) instead of filing a second request. The key is written only into the 0600 runner
  * env file and is never printed.
  */
+/**
+ * UAT-30 (Vadym 13405): a join names the runtime it runs on. `--runtime claude|codex|other`, else what the shell
+ * itself proves (AGENTRADAR_AGENT_BIN, CLAUDECODE, CODEX_HOME). Nothing is assumed: an unknown or unsupported one is
+ * refused before any request, with the command to run next.
+ */
+export function joinRuntime(flag, env) {
+    const map = { claude: "claude", codex: "codex", other: "generic" };
+    if (flag !== undefined) {
+        const key = flag.trim().toLowerCase();
+        const harness = Object.hasOwn(map, key) ? map[key] : undefined;
+        return harness ? { harness } : { refusal: `Unsupported runtime ${JSON.stringify(flag)}: AgentRadar joins Claude Code (claude), Codex (codex) or another CLI you launch yourself (other). Nothing was requested. Now: run the same command again with --runtime other and AGENTRADAR_AGENT_BIN set to your CLI's command, or ask your company which runtime it expects.` };
+    }
+    if (env.AGENTRADAR_AGENT_BIN?.trim())
+        return { harness: "generic" };
+    if (env.CLAUDECODE)
+        return { harness: "claude" };
+    if (env.CODEX_HOME)
+        return { harness: "codex" };
+    return { refusal: "AgentRadar cannot tell which runtime you run on, so nothing was requested. Now: run the same command again with --runtime claude (Claude Code), --runtime codex (Codex) or --runtime other (any other CLI; set AGENTRADAR_AGENT_BIN to its command first). Use the one that is true for you; do not guess." };
+}
 export async function joinOrganisation(enrolmentUrl, deps = {}) {
     const fetchImpl = deps.fetch ?? fetch;
     const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
@@ -858,6 +878,12 @@ and AR_CLI_RUNNER_ID=${runnerId} in its environment. Accept the one-time develop
         return startJoined(state.requestId, state.agentId, { mcpEndpoint: envValue(saved, "AWP_MCP_URL") ?? mcpEndpoint, bearer }, approvedBypass, bypass);
     }
     if (!state) {
+        // index.ts skips the runtime gate for --revoke-bypass (it edits an earlier join); a NEW join still needs a proven runtime.
+        if (deps.revokeBypass && !deps.harness) {
+            const proven = joinRuntime(undefined, env);
+            if ("refusal" in proven)
+                throw new Error(proven.refusal);
+        }
         const agentName = (deps.agentName ?? process.env.AGENTRADAR_AGENT_NAME ?? basename(cwd)).trim();
         if (!agentName)
             throw new Error("Run join from the agent project folder");

package/dist/skill-install.js

@@ -1,6 +1,6 @@
 import { chmod, lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { basename, dirname, join } from "node:path";
+import { basename, join } from "node:path";
 import { awpRequest, envValue } from "./tool-run.js";
 const MANAGED_MARK = ".agentradar-managed";
 async function ensureDirectory(path) {
@@ -45,8 +45,8 @@ export async function installVendorSkill(deps = {}) {
 }
 const runnerSkills = () => import(new URL(import.meta.url.endsWith(".ts")
     ? "../../../templates/vendor-runner/feeder.mjs" : "./vendor-runner/feeder.mjs", import.meta.url).href);
-export async function writeManagedSkills(skillsDir, skills) {
-    return (await runnerSkills()).writeManagedSkills(skillsDir, skills);
+export async function writeManagedSkills(skillsDir, skills, runner) {
+    return (await runnerSkills()).writeManagedSkills(skillsDir, skills, runner);
 }
 /**
  * R650 — a joined agent's AgentRadar skills (`my_skills`: the bundled set plus the ones linked to it), written
@@ -54,17 +54,6 @@ export async function writeManagedSkills(skillsDir, skills) {
  * Codex `$CODEX_HOME/skills`. Done here because a session that acts only through `agentradar run` has no
  * feeder; where the service runs, its feeder keeps them current.
  */
-const BRIEF_MARK = "<!-- Written by AgentRadar and replaced on every sync; edits here are lost. -->";
-/** Replaces the file itself, never a symlink's target, and never a file it did not write (a vendor's AGENTS.md). */
-async function writeBrief(file, text) {
-    const current = await lstat(file).catch(() => null);
-    if (current && (!current.isFile() || !(await readFile(file, "utf8")).startsWith(BRIEF_MARK)))
-        return;
-    await mkdir(dirname(file), { recursive: true });
-    const temporary = `${file}.${randomUUID()}.tmp`;
-    await writeFile(temporary, `${BRIEF_MARK}\n${text.trim()}\n`);
-    await rename(temporary, file);
-}
 /** Where each CLI reads skills. The same table as templates/vendor-runner/feeder.mjs; skill-install.test.ts pins them equal. */
 export const SKILL_DIRS = {
     claude: "$AR_BASE/.claude/skills",
@@ -89,23 +78,24 @@ export async function syncJoinedSkills(runnerId, deps) {
     const skillsDir = skillsDirFor(harness, (name) => name === "HOME" ? deps.home : value(name));
     if (!skillsDir)
         return;
-    const codex = harness === "codex";
-    const root = (codex ? value("CODEX_HOME") : value("AR_BASE")) ?? "";
+    const runner = value("AR_CLI_RUNNER_ID") ?? undefined;
     // 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", {
         protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "agentradar-cli", version: "1.0.0" },
-    }, { home: deps.home, fetch: deps.fetch, logError: deps.log, surface: "skill-sync" });
-    const briefFile = codex ? join(root, "AGENTS.md") : join(root, ".claude", "rules", "agentradar-brief.md");
-    if (root && init?.result?.instructions)
-        await writeBrief(briefFile, init.result.instructions);
-    const have = (await runnerSkills()).heldSkillZips(skillsDir);
-    const body = await awpRequest(runnerId, "tools/call", { name: "my_skills", arguments: { have } }, { home: deps.home, fetch: deps.fetch, logError: deps.log, surface: "skill-sync" });
+    }, { home: deps.home, fetch: deps.fetch, logError: deps.log, surface: "skill-sync", signal: deps.signal });
+    // The feeder's own brief path and writer: one file per runner (MULTI-ORG-PUSH §0).
+    const skills = await runnerSkills();
+    const briefFile = skills.briefFileFor(harness ?? "claude", { AR_BASE: value("AR_BASE") ?? undefined, CODEX_HOME: value("CODEX_HOME") ?? undefined, AR_CLI_RUNNER_ID: runner });
+    if (briefFile && init?.result?.instructions)
+        skills.writeBrief(briefFile, init.result.instructions);
+    const have = skills.heldSkillZips(skillsDir);
+    const body = await awpRequest(runnerId, "tools/call", { name: "my_skills", arguments: { have } }, { home: deps.home, fetch: deps.fetch, logError: deps.log, surface: "skill-sync", signal: deps.signal });
     const text = body?.result?.content?.find((c) => c.type === "text")?.text;
     const answer = (text ? JSON.parse(text) : {});
     if (!answer.ok || !Array.isArray(answer.skills))
         throw new Error("AgentRadar did not return your skills");
-    const written = await writeManagedSkills(skillsDir, answer.skills);
+    const written = await writeManagedSkills(skillsDir, answer.skills, runner);
     deps.log(`Installed ${written.length} AgentRadar skill(s) in ${skillsDir}.`);
 }
 //# sourceMappingURL=skill-install.js.map

package/dist/tool-run.js

@@ -1,8 +1,9 @@
-import { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, realpath, stat, utimes, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { hostIsTeammate } from "./channel.js";
 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.";
+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 human 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.
@@ -25,7 +26,8 @@ export async function callToolOverCli(runnerId, command, argumentsJson, deps = {
     const switches = new Set(flags.filter(([flag]) => ["help", "dry-run", "json"].includes(flag)).map(([flag]) => flag));
     flags = flags.filter(([flag]) => !switches.has(flag));
     let tool = command;
-    const parameters = argumentsJson === undefined ? {} : parseArgumentsObject(argumentsJson, deps.logError ?? console.error);
+    let entry;
+    const parameters = argumentsJson === undefined ? {} : await parseArgumentsObject(argumentsJson, deps);
     if (!parameters)
         return EXIT.usage;
     // A bare tool name with nothing to type goes straight to the server: the hot `inbox next` poll and the get_self probe
@@ -34,11 +36,11 @@ export async function callToolOverCli(runnerId, command, argumentsJson, deps = {
         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);
+        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));
+            (deps.log ?? console.log)(switches.has("json") ? leafHelpJson(entry) : leafHelp(entry));
             return EXIT.ok;
         }
         tool = entry.name;
@@ -51,8 +53,8 @@ export async function callToolOverCli(runnerId, command, argumentsJson, deps = {
         }
         if (flags.length) {
             const typed = await flagArguments(entry, flags, deps);
-            if (!typed)
-                return EXIT.usage;
+            if (Array.isArray(typed))
+                return showInputErrors({ path: pathOf(entry) ?? command, flags, json: switches.has("json"), entry }, typed, deps);
             Object.assign(parameters, typed);
         }
         // Provenance for the execution ledger (R572), not permission: the server treats it as the self-report it is.
@@ -68,12 +70,21 @@ export async function callToolOverCli(runnerId, command, argumentsJson, deps = {
         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);
+    const shown = { path: (entry && pathOf(entry)) ?? command, flags, json: switches.has("json"), entry };
+    if (!RUNNER_ID.test(runnerId))
+        return await callAwpTool(runnerId, tool, parameters, deps, shown);
+    const delivered = join(deps.home ?? homedir(), ".agentradar", "agents", `${runnerId}.delivered.json`);
+    if (tool !== "next_event") {
+        // Any call after a channel wake proves the agent took it in: touch the file the channel watches before acking the batch.
+        const code = await callAwpTool(runnerId, tool, parameters, deps, shown);
+        const now = new Date();
+        await utimes(delivered, now, now).catch(() => mkdir(dirname(delivered), { recursive: true })
+            .then(() => writeFile(delivered, "[]", { mode: 0o600, flag: "wx" }))).catch(() => undefined);
+        return code;
+    }
     // A bare poll acknowledges the batch the previous poll printed, so the command stays byte-identical and
     // an operator can allow it once. Asking for the next event means the last one was read; a lost or
     // failed poll leaves the file as it was, so delivery stays at-least-once.
-    const delivered = join(deps.home ?? homedir(), ".agentradar", "agents", `${runnerId}.delivered.json`);
     if (parameters.ackEventIds === undefined) {
         const ids = await readFile(delivered, "utf8").then((text) => JSON.parse(text), () => []);
         if (Array.isArray(ids) && ids.length)
@@ -82,7 +93,7 @@ export async function callToolOverCli(runnerId, command, argumentsJson, deps = {
     // 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); } });
+    const code = await callAwpTool(runnerId, tool, parameters, { ...deps, log: (text) => { said = text; (deps.log ?? console.log)(text); } }, shown);
     if (code !== 0)
         return code;
     let events = [];
@@ -101,7 +112,7 @@ export async function callToolOverCli(runnerId, command, argumentsJson, deps = {
  */
 export const EXIT = { ok: 0, refused: 1, usage: 2 };
 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. */
+/** Split `<word> ... [--input <json|file|->] [--<argument> <value> ...]`; null when a flag has no value. */
 export function parseCallArgs(rest) {
     const words = [];
     const flags = [];
@@ -116,11 +127,16 @@ export function parseCallArgs(rest) {
             flags.push([arg.slice(2), ""]);
             continue;
         }
+        // The reply refusal for a literal \n says "pass --force-format", bare; `--force-format true` works too.
+        if (arg === "--force-format" && !/^(true|false)$/.test(rest[i + 1] ?? "")) {
+            flags.push(["force-format", "true"]);
+            continue;
+        }
         const value = rest[++i];
         if (value === undefined)
             return null;
-        if (arg === "--args")
-            json = value;
+        if (arg === "--input" || arg === "--args")
+            json = value; // --args: hidden alias, older templates and agent prompts still say it
         else
             flags.push([arg.slice(2), value]);
     }
@@ -159,6 +175,14 @@ const serviceTools = (runnerId, tools) => {
             + ` and \`agentradar ${command("run_service_tool")} --tool-key <tool> --arguments '<its arguments as JSON>'\` runs one.`
         : "";
 };
+/** Top-level `--help` headings (main 10-15: ~6 sections so 37 groups scan). */
+const SECTIONS = {
+    Work: ["inbox", "threads", "tasks", "projects", "outcomes", "escalations", "interventions", "incidents", "briefs", "feedback", "me", "team", "browser", "files"],
+    Channels: ["channels", "contacts", "webhooks", "integrations", "join-links", "onboarding"],
+    Access: ["permissions", "approvals", "secrets", "roles", "org-chart", "org"],
+    Data: ["vaults", "memory", "skills", "metrics", "model", "hosting", "subscriptions", "selftest"],
+    Money: ["spend", "wallet", "usage", "marketplace", "placement", "karma"],
+};
 /** `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} ` : "";
@@ -171,86 +195,241 @@ function groupHelp(runnerId, command, tools, help, deps) {
         children.set(word, [...children.get(word) ?? [], tool]);
     }
     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)}`);
+        const paths = tools.map(pathOf).filter((path) => !!path);
+        const groups = [...new Set(paths.map((path) => path.split(" ")[0]))].sort();
+        const near = closest(command, [...new Set(paths.flatMap((path) => path.split(" ").map((_, i, words) => words.slice(0, i + 1).join(" "))))]);
+        (deps.logError ?? console.error)(`${command} is not a command.${near ? ` Did you mean \`agentradar ${near}\`?` : ""} Groups: ${groups.join(" ")}. \`agentradar <group> --help\` lists its commands.${serviceTools(runnerId, tools)}`);
         return EXIT.usage;
     }
-    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)`}`);
+    const line = ([word, leaves]) => `  ${word.padEnd(16)} ${leaves.length === 1 && pathOf(leaves[0]) === `${prefix}${word}` ? firstSentence(leaves[0].description) : `(${leaves.length} commands)`}`;
+    const sorted = [...children].sort(([a], [b]) => a.localeCompare(b));
+    // The top level scans in headed sections (Local, the commands that run on this machine, is in `agentradar --help`); a group the table doesn't name lands under More.
+    const lines = command ? sorted.map(line) : [...Object.keys(SECTIONS), "More"].flatMap((section) => {
+        const rows = sorted.filter(([word]) => (SECTIONS[section]?.includes(word) ? section : "More") === section);
+        return rows.length ? [`${section.toUpperCase()}`, ...rows.map(line)] : [];
+    });
     (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) {
+/** What a flag takes, from its schema: `a|b` for an enum, `<number>`, `key=<type>,... (repeatable)` for a list of small objects, `<type> (a list: ...)` for a list of scalars. */
+function typeOf(schema) {
+    const type = [schema.type].flat()[0];
+    if (schema.enum)
+        return schema.enum.join("|");
+    if (type === "array") {
+        const fields = objectItems(schema);
+        const item = fields ? ` (one item as ${Object.entries(fields).map(([key, field]) => `${key}=<${[field.type].flat()[0] ?? "value"}>`).join(",")})` : "";
+        return `${typeOf(schema.items ?? {})} (a list: repeat the flag, or pass one JSON array)${item}`;
+    }
+    return `<${type ?? "value"}>`;
+}
+const objectItems = (schema) => [schema.type].flat()[0] === "array" && [schema.items?.type].flat()[0] === "object" ? schema.items?.properties : undefined;
+const singular = (word) => word.endsWith("ies") ? `${word.slice(0, -3)}y` : word.endsWith("s") && !word.endsWith("ss") ? word.slice(0, -1) : word;
+/** Design §4.2: the four approval explanation fields are flags named for the question the owner reads; the stored keys stay. */
+const APPROVAL_FLAGS = { context: "what-happened", reason: "why", ifDeclined: "if-declined", decisionDetail: "need" };
+/**
+ * Design §4.1: every top-level argument is a flag; one level of nested object is flattened into flags with no prefix
+ * (`approvalDetails.taskId` is `--task-id`; the four explanation fields are `--what-happened --why --if-declined --need`); a list of small objects is a repeated `key=value` flag named for one
+ * item (`contextLinks` is `--context-link`). A flattened name that a top-level argument already took stays on the
+ * top-level one.
+ */
+function flagTable(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 table = [];
+    const named = (name, schema) => kebab(objectItems(schema) ? singular(name) : name);
+    const flattened = Object.entries(properties).filter(([, schema]) => [schema.type].flat()[0] === "object" && schema.properties);
+    for (const [name, schema] of Object.entries(properties)) {
+        if (!flattened.some(([group]) => group === name))
+            table.push({ flag: kebab(name), path: [name], schema, required: required.includes(name) });
+    }
+    for (const [group, schema] of flattened) {
+        for (const [name, nested] of Object.entries(schema.properties)) {
+            const flag = group === "approvalDetails" ? APPROVAL_FLAGS[name] ?? named(name, nested) : named(name, nested);
+            if (!table.some((taken) => taken.flag === flag))
+                table.push({ flag, path: [group, name], schema: nested, required: required.includes(group) && !!schema.required?.includes(name) });
+        }
+    }
+    // The whole object as one JSON flag still works (the approvals and browser skills quote `--approval-details '{...}'`, #1882).
+    for (const [group, schema] of flattened)
+        if (!table.some((taken) => taken.flag === kebab(group)))
+            table.push({ flag: kebab(group), path: [group], schema, required: false });
+    return table;
+}
+/** `agentradar <path> --help`: the description, usage, required and optional flags, all generated from the inputSchema. */
+function leafHelp(tool) {
+    const table = flagTable(tool);
+    const flag = (entry) => `  --${entry.flag} ${typeOf(entry.schema)}${entry.schema.description ? `  ${firstSentence(entry.schema.description)}` : ""}`;
+    const required = table.filter((entry) => entry.required);
+    const optional = table.filter((entry) => !entry.required);
     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) : []),
+        "USAGE", `  agentradar ${path}${required.map((entry) => ` --${entry.flag} ${typeOf(entry.schema)}`).join("")}${optional.length ? " [flags]" : ""}`,
+        ...(required.length ? ["REQUIRED", ...required.map(flag)] : []),
+        "FLAGS", ...optional.map(flag), "  --input <json|file|->  the whole call as one JSON object, checked the same way",
+        "  --dry-run  print the exact call and send nothing",
+        "  --json  raw JSON",
+        "  --runner <id>  the runner (default $AR_CLI_RUNNER_ID)",
+        ...Object.entries(tool.inputSchema?.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");
 }
+/** `--help --json`: the same facts as `leafHelp`, for a program; `schema` is the tool's own JSON Schema. */
+function leafHelpJson(tool) {
+    return JSON.stringify({
+        command: pathOf(tool) ?? tool.name, description: tool.description ?? "",
+        flags: flagTable(tool).map((entry) => ({ flag: `--${entry.flag}`, type: typeOf(entry.schema), required: entry.required, description: entry.schema.description ?? "" })),
+        schema: tool.inputSchema ?? {},
+    });
+}
+/** `agentradar schema <command>`: the JSON Schema the server checks that command's input against. */
+export async function schemaOverCli(runnerId, command, deps = {}) {
+    const tools = await listedTools(runnerId, deps);
+    if (!tools)
+        return EXIT.refused;
+    const entry = tools.find((candidate) => pathOf(candidate) === command);
+    if (!entry)
+        return groupHelp(runnerId, command, tools, false, deps);
+    (deps.log ?? console.log)(JSON.stringify({ command, schema: entry.inputSchema ?? {} }));
+    return EXIT.ok;
+}
+/** Set `value` at `path`, or append to the list there; one level of object, as `flagTable` flattens. */
+function place(out, entry, value) {
+    const into = entry.path.length === 2 ? (out[entry.path[0]] ??= {}) : out;
+    const key = entry.path[entry.path.length - 1];
+    const list = [entry.schema.type].flat()[0] === "array";
+    into[key] = list ? [...(into[key] ?? []), value] : value;
+}
+/** `label=Invoice,url=https://a.b/c?d=e` as an object, split only before a key the item has; null when it has none of them. */
+function keyValues(text, fields) {
+    const names = Object.keys(fields);
+    const parts = text.split(new RegExp(`,(?=(?:${names.join("|")})=)`));
+    const out = {};
+    for (const part of parts) {
+        const at = part.indexOf("=");
+        const key = at < 0 ? "" : part.slice(0, at);
+        if (!names.includes(key))
+            return `must look like ${names.map((name) => `${name}=<${[fields[name].type].flat()[0] ?? "value"}>`).join(",")}`;
+        const typed = coerce([fields[key].type].flat()[0], part.slice(at + 1));
+        if (typed === undefined)
+            return `${key} must be a ${[fields[key].type].flat()[0]}`;
+        out[key] = typed;
+    }
+    return out;
+}
 /**
  * `--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(entry, flags, deps) {
-    const logError = deps.logError ?? console.error;
-    const schema = entry.inputSchema?.properties ?? {};
+    const table = flagTable(entry);
     const out = {};
-    const camel = (flag) => flag.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    const problems = [];
+    const fieldOf = (target) => target.path.join(".");
     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)) {
+        if (flag.endsWith("-file") && !table.some((candidate) => candidate.flag === kebab(flag))) {
             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;
+                problems.push({ field: flag, problem: text.message });
+                continue;
             }
             [flag, value] = [flag.slice(0, -"-file".length), text];
         }
         // --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(`${pathOf(entry) ?? entry.name} has no flag --${flag}. Its flags: ${Object.keys(schema).map((name) => `--${kebab(name)}`).join(" ") || "none"}`);
-            return null;
+        const wanted = kebab(flag) === "text" && !table.some((candidate) => candidate.flag === "text") ? "entry" : kebab(flag);
+        const target = table.find((candidate) => candidate.flag === wanted);
+        if (!target) {
+            const near = closest(kebab(flag), table.map((candidate) => candidate.flag));
+            problems.push({ field: flag, problem: "unknown flag", ...(near ? { suggestion: fieldOf(table.find((candidate) => candidate.flag === near)) } : {}) });
+            continue;
         }
-        const type = [schema[key].type].flat()[0];
-        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 type = [target.schema.type].flat()[0];
+        const fields = objectItems(target.schema);
+        // A list is one JSON array or a repeated flag (#1752): --message-ids a --message-ids b, or --tools '[{...},{...}]'.
+        if (type === "array" && (!fields || /^\s*[[{]/.test(value))) {
+            const itemType = [target.schema.items?.type].flat()[0];
             const items = parseList(value, itemType);
-            if (!items) {
-                logError(listFlagError(flag, itemType, schema[key]));
-                return null;
-            }
-            out[key] = [...(out[key] ?? []), ...items];
+            if (!items)
+                problems.push({ field: fieldOf(target), problem: listFlagError(target.flag, itemType, target.schema) });
+            else
+                for (const item of items)
+                    place(out, target, item);
             continue;
         }
-        const typed = coerce(type, value);
-        if (typed === undefined) {
-            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;
+        const typed = fields ? keyValues(value, fields) : coerce(type, value);
+        if (typed === undefined || typeof typed === "string" && fields) {
+            problems.push({ field: fieldOf(target), problem: typeof typed === "string" ? typed : target.schema.properties
+                    ? `must be JSON with the fields ${(target.schema.required ?? Object.keys(target.schema.properties)).join(", ")}; \`agentradar ${pathOf(entry) ?? `call <runner-id> ${entry.name}`} --help\` shows each one.`
+                    : `must be ${type === "array" ? "a list of " + target.schema.items?.type : "a " + type}` });
+            continue;
         }
-        out[key] = typed;
+        // A repeated flag builds a list: --message-ids a --message-ids b.
+        place(out, target, typed);
     }
-    return out;
+    return problems.length ? problems : out;
+}
+const camel = (flag) => flag.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+/** The flag that sets a field (`approvalDetails.reason` is `--why`); a field no flag sets stays the JSON key the agent wrote. */
+const flagFor = (table) => (field) => {
+    const found = table.find((entry) => entry.path.join(".") === field);
+    return found ? `--${found.flag}` : /[.[]/.test(field) ? field : `--${kebab(field)}`;
+};
+const shellWord = (value) => /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+function distance(a, b) {
+    let row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const next = [i];
+        for (let j = 1; j <= b.length; j++)
+            next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        row = next;
+    }
+    return row[b.length];
+}
+/** The candidate within 2 edits of `word`, nearest first; the server does the same over fields and their labels. */
+const closest = (word, candidates) => candidates.map((candidate) => [candidate, distance(word, candidate)]).filter(([, d]) => d <= 2).sort((a, b) => a[1] - b[1])[0]?.[0];
+/**
+ * Design §5.1: what was wrong, flag by flag; the agent's own command with only the bad flags fixed; one next step.
+ * Stderr, exit 2; with --json the same on stdout.
+ */
+function showInputErrors(shown, errors, deps) {
+    const table = shown.entry ? flagTable(shown.entry) : [];
+    const flagOf = flagFor(table);
+    const byField = new Map(errors.map((error) => [error.field, error]));
+    const fixed = shown.flags.flatMap(([flag, value]) => {
+        const error = byField.get(flag) ?? byField.get(camel(flag)) ?? byField.get(table.find((entry) => entry.flag === kebab(flag))?.path.join(".") ?? "");
+        if (error?.problem.startsWith("unknown"))
+            return error.suggestion ? [`${flagOf(error.suggestion)} ${shellWord(value)}`] : [];
+        return [`--${flag} ${shellWord(value)}`];
+    });
+    const missing = errors.filter((error) => error.problem === "required" && !/[.[]/.test(error.field)).map((error) => `${flagOf(error.field)} "..."`);
+    const example = `agentradar ${shown.path}${[...fixed, ...missing].map((part) => ` ${part}`).join("")}`;
+    const help = `agentradar ${shown.path} --help`;
+    if (shown.json) {
+        (deps.log ?? console.log)(JSON.stringify({ ok: false, error: { code: "E_VALIDATION", command: shown.path,
+                errors: errors.map((error) => ({ ...error, flag: flagOf(error.field), ...(error.suggestion ? { suggestion: flagOf(error.suggestion) } : {}) })), example, help } }));
+        return EXIT.usage;
+    }
+    const width = Math.max(...errors.map((error) => flagOf(error.field).length));
+    const lines = errors.map((error) => `  ${flagOf(error.field).padEnd(width)}   ${error.problem.replace(/\.$/, "")}.${error.expected ? ` ${error.expected}.` : ""}${error.suggestion ? ` Did you mean ${flagOf(error.suggestion)}?` : ""}`);
+    const properties = Object.keys(shown.entry?.inputSchema?.properties ?? {});
+    const guessless = errors.some((error) => error.problem.startsWith("unknown") && !error.suggestion) && table.length;
+    (deps.logError ?? console.error)([
+        `error: ${errors.length} problem${errors.length === 1 ? "" : "s"} with \`agentradar ${shown.path}\`. Nothing was sent${properties.includes("approvalDetails") ? "; your owner has not been asked yet" : ""}.`,
+        ...lines,
+        ...(guessless ? [`This command takes: ${table.map((entry) => `--${entry.flag}`).join(" ")}`] : []),
+        "example:", `  ${example}`,
+        `next: fix it and run it again. Every flag: ${help}`,
+    ].join("\n"));
+    return EXIT.usage;
 }
 /** 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) {
@@ -335,41 +514,65 @@ export function namedToolFlags(flags) {
     });
     return { tools, flags: flags.filter(([flag]) => flag !== "tool") };
 }
-function parseArgumentsObject(argumentsJson, logError) {
+/** `--input` is the JSON itself, a file inside the working folder, or `-` for standard input. */
+async function readInput(value, deps) {
+    if (/^\s*[{[]/.test(value))
+        return value;
+    if (value === "-")
+        return await (deps.stdin ?? (async () => { const chunks = []; for await (const chunk of process.stdin)
+            chunks.push(chunk); return Buffer.concat(chunks).toString("utf8"); }))();
+    return await readArgumentFile(value, deps.cwd ?? process.cwd(), deps.home ?? homedir());
+}
+async function parseArgumentsObject(argumentsJson, deps) {
+    const logError = deps.logError ?? console.error;
     let parsed;
     try {
-        parsed = JSON.parse(argumentsJson);
+        parsed = JSON.parse(await readInput(argumentsJson, deps));
     }
-    catch {
-        logError("--args must be a JSON object, e.g. --args '{\"title\":\"a real issue\"}'");
+    catch (error) {
+        logError(error instanceof SyntaxError || !(error instanceof Error) ? "--input must be a JSON object, a file holding one, or - for standard input, e.g. --input '{\"title\":\"a real issue\"}'" : `--input ${error.message}`);
         return null;
     }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        logError("--args must be a JSON object");
+        logError("--input must be a JSON object");
         return null;
     }
     return parsed;
 }
 /** 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) {
+export async function callAwpTool(runnerId, name, toolArguments, deps, shown = { path: name, flags: [], json: false }) {
     const log = deps.log ?? console.log;
     const logError = deps.logError ?? console.error;
     const body = await awpRequest(runnerId, "tools/call", { name, arguments: toolArguments }, deps);
     if (!body)
         return 1;
     const text = body.result?.content?.[0]?.text;
-    const said = typeof text === "string" ? text : JSON.stringify(body.result ?? {});
+    // qa-sec-6 (#1880): server CTAs name the shell variable, which an attached pane never has; this command knows the runner.
+    const named = (t) => t.replaceAll("agentradar run $AR_CLI_RUNNER_ID", `agentradar run ${runnerId}`);
+    const said = named(typeof text === "string" ? text : JSON.stringify(body.result ?? {}));
     // 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) {
+        // A server that names fields (#1871 slice 2) gets them shown as flags; an older one's sentence prints as it is.
+        let refusal = {};
+        try {
+            refusal = JSON.parse(said);
+        }
+        catch { /* a plain sentence */ }
+        if (refusal.code === "E_VALIDATION" && Array.isArray(refusal.errors) && refusal.errors.length)
+            return showInputErrors(shown, refusal.errors, deps);
         // 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"));
+        logError([said, ...(body.result.content ?? []).slice(1).map((c) => c.text).filter((t) => typeof t === "string").map(named)].join("\n"));
         return 1;
     }
     log(withCliUpdate(said));
+    // A notice the server adds beside the answer (a routine run held while you are mid-turn) goes to stderr, so a piped stdout stays the answer.
+    const notices = (body.result?.content ?? []).slice(1).map((c) => c.text).filter((t) => typeof t === "string");
+    if (notices.length)
+        logError(notices.map(named).join("\n"));
     return 0;
 }
-const RUNNER_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+export const RUNNER_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 /** One JSON-RPC request on the runner's AWP MCP endpoint with the runner's own key; null after logging why it failed. */
 export async function awpRequest(runnerId, method, params, deps) {
     const target = await awpEndpoint(runnerId, deps);
@@ -425,6 +628,11 @@ async function postAwp(url, bearer, method, params, deps) {
         method: "POST",
         headers: {
             ...(await cliHeader(deps.surface)),
+            // Vadym 16706: a sub-agent never acts as the agent. The server refuses its send and act tools on this header.
+            // A teammate pane is found by its --agent-id ancestor; an in-process sub-agent by agent-guard's AR_CALLER (guard.mjs bash).
+            ...((deps.teammate ?? ((deps.env ?? process.env).AR_CALLER === "teammate" || hostIsTeammate())) ? { "x-agentradar-caller": "teammate" }
+                // 18229: the feeder's retrospective side-run (AR_CALLER=retro) reads an untrusted digest; the server lets it task only the agent itself.
+                : (deps.env ?? process.env).AR_CALLER === "retro" ? { "x-agentradar-caller": "retro" } : {}),
             authorization: `Bearer ${bearer}`,
             "content-type": "application/json",
             // Both, because the endpoint answers JSON only when the client says it takes JSON.
@@ -436,6 +644,7 @@ async function postAwp(url, bearer, method, params, deps) {
             method,
             params,
         }),
+        ...(deps.signal ? { signal: deps.signal } : {}),
     });
     await noteCliUpdate(response.headers, logError);
     if (!response.ok) {