one-code-extension 0.4.1 → 0.6.0

package/extensions/skill/invoke.ts

@@ -1,18 +1,18 @@
 /**
  * User-invoked skill commands (pure). pi registers each skill as a `/skill:<name>`
  * slash command and, on invocation, expands it into a `<skill>` block that it
- * submits as a *user message* — so loading a skill shows up in the transcript as
- * a new user turn. One Code intercepts that command in the `input` hook and
- * re-delivers the same block as a hidden message instead (see index.ts), so the
- * model receives byte-identical content but nothing renders.
+ * submits as a *user message*. One Code intercepts that command (and its own
+ * bare `/<name>` and typed `/<plugin>:<skill>` forms) and delivers the skill
+ * the way Claude Code does: a hidden message holding the command breadcrumb
+ * and the skill's text, so nothing renders and no `skill` call is needed.
+ * A model's `skill` call gets Claude Code's "Launching skill" result with the
+ * same text beside it (see index.ts).
  *
- * These helpers mirror pi's own `_expandSkillCommand`/`formatSkillInvocation`
- * exactly (same `/skill:` prefix, same block template) so the model sees the same
- * bytes it would have without the interception — only the display changes.
+ * pi's own `<skill>` block still reaches a session through pi's native
+ * expansion on older pi (steer/followUp skip the `input` hook there), which
+ * is why the off-skill redaction below still matches it.
  */
 
-import { dirname } from "node:path";
-
 const SKILL_PREFIX = "/skill:";
 
 /** Parse a `/skill:<name> [args]` command; undefined if it is not one. */
@@ -45,84 +45,115 @@ export function resolveSkill<T extends { name: string }>(all: T[], wanted: strin
 }
 
 /**
- * Rebuild the exact `<skill>` block pi's `/skill:` expansion produces. `body` is
- * the SKILL.md with frontmatter already stripped and trimmed; `filePath` is the
- * skill file (its directory is the base for relative references, as pi does).
+ * Claude Code's breadcrumb for a typed slash command, the first text block of
+ * the message a typed skill becomes. Its arguments ride `<command-args>` only
+ * when there are some.
  */
-export function buildSkillBlock(skill: { name: string; filePath: string }, body: string, args: string): string {
-	const block = `<skill name="${skill.name}" location="${skill.filePath}">
-References are relative to ${dirname(skill.filePath)}.
-
-${body}
-</skill>`;
-	return args ? `${block}\n\n${args}` : block;
+export function commandBreadcrumb(name: string, args: string): string {
+	return `<command-message>${name}</command-message>\n<command-name>/${name}</command-name>${args ? `\n<command-args>${args}</command-args>` : ""}\n`;
 }
 
-/** Fast pre-check before the regex walk; also the marker `redactOffSkillText` scans for. */
-const SKILL_BLOCK_START = '<skill name="';
-const SKILL_BLOCK_RE = /<skill name="([^"]+)"[^>]*>[\s\S]*?<\/skill>/g;
-
-export const offSkillNotice = (name: string): string =>
-	`[Skill "${name}" is turned off — its instructions were removed. The user can re-enable it from /skills or /plugins.]`;
+// commandBreadcrumb's shape at the start of a message; the arguments may span lines.
+const BREADCRUMB = /^<command-message>[^<\n]*<\/command-message>\n<command-name>(\/[^<\n]*)<\/command-name>(?:\n<command-args>([\s\S]*?)<\/command-args>)?\n/;
 
 /**
- * Replace every `<skill>` block belonging to a turned-off skill with a short
- * refusal notice. Returns the rewritten text, or undefined when nothing
- * needed redacting (so callers keep the original object untouched).
- *
- * This is the fail-closed backstop behind the `input`-hook interception:
- * pi's `steer()`/`followUp()` expand `/skill:<name>` natively WITHOUT firing
- * the `input` event (queued interactive messages after the first, RPC
- * steer/followUp), so an off skill's instructions can land in the session
- * history. Redacting on the `context` hook strips them from every outgoing
- * request — the session file keeps the original bytes, and the rewrite is
- * deterministic for a fixed override state, so the request prefix stays
- * byte-stable across turns (prompt-cache friendly).
+ * What a user message that opens with commandBreadcrumb shows in the
+ * transcript: the command as typed, `/name args`. Claude Code shows a prompt
+ * command (a skill, `/init`, `/doctor`) by its command line and keeps the
+ * expanded text out of the transcript. `undefined` for any other message.
  */
-export function redactOffSkillText(text: string, isOff: (name: string) => boolean): string | undefined {
-	if (!text.includes(SKILL_BLOCK_START)) return undefined;
-	let changed = false;
-	const redacted = text.replace(SKILL_BLOCK_RE, (block, name: string) => {
-		if (!isOff(name)) return block;
-		changed = true;
-		return offSkillNotice(name);
-	});
-	return changed ? redacted : undefined;
+export function commandDisplayLine(text: string): string | undefined {
+	const match = BREADCRUMB.exec(text);
+	if (!match) return undefined;
+	return match[2] ? `${match[1]} ${match[2]}` : match[1];
 }
 
 /**
- * Apply redactOffSkillText across a request's messages (user and custom roles,
- * string or text-block content). Returns a rewritten copy, or undefined when
- * no message needed redacting — callers must then keep the original array so
- * untouched requests stay byte-identical.
+ * Claude Code's argument substitution in a skill's text: `$ARGUMENTS`,
+ * `$ARGUMENTS[n]` and `$n` (both counted from 0) take the arguments, and a
+ * backslash keeps a `$` literal. When nothing was substituted, the arguments
+ * follow the text on an `ARGUMENTS:` line.
  */
-export function redactOffSkillMessages<M extends { role: string; content?: unknown }>(
-	messages: readonly M[],
-	isOff: (name: string) => boolean,
-): M[] | undefined {
-	let changed = false;
-	const out = messages.map((message) => {
-		if (message.role !== "user" && message.role !== "custom") return message;
-		if (typeof message.content === "string") {
-			const redacted = redactOffSkillText(message.content, isOff);
-			if (redacted === undefined) return message;
-			changed = true;
-			return { ...message, content: redacted };
+export function substituteSkillArguments(text: string, args: string): string {
+	if (!args.trim()) return text;
+	const parts = args.trim().split(/\s+/);
+	let used = false;
+	// One pass, so an argument holding `$0` is never substituted again.
+	const out = text.replace(/\\\$(?=\d|ARGUMENTS)|\$ARGUMENTS\[(\d+)\]|\$ARGUMENTS|\$(\d+)(?!\w)/g, (match, listed?: string, positional?: string) => {
+		if (match.startsWith("\\")) return "$";
+		if (match === "$ARGUMENTS") {
+			used = true;
+			return args;
 		}
-		if (!Array.isArray(message.content)) return message;
-		let blockChanged = false;
-		const blocks = message.content.map((block: { type?: string; text?: string }) => {
-			if (block?.type !== "text" || typeof block.text !== "string") return block;
-			const redacted = redactOffSkillText(block.text, isOff);
-			if (redacted === undefined) return block;
-			blockChanged = true;
-			return { ...block, text: redacted };
-		});
-		if (!blockChanged) return message;
-		changed = true;
-		return { ...message, content: blocks };
+		const part = parts[Number(listed ?? positional)];
+		if (part === undefined) return match;
+		used = true;
+		return part;
 	});
-	return changed ? out : undefined;
+	return used ? out : `${out}\n\nARGUMENTS: ${args}`;
+}
+
+/**
+ * The text a skill hands the model, as Claude Code builds it: the skill's
+ * folder first (`Base directory for this skill: …`, so relative `references/`
+ * and `scripts/` resolve), then the body with its arguments. A skill that
+ * ships inside One Code, like Claude Code's own, names no folder.
+ */
+export function skillPromptText(body: string, args: string, baseDir: string | undefined): string {
+	const text = substituteSkillArguments(body, args);
+	return baseDir ? `Base directory for this skill: ${baseDir}\n\n${text}` : text;
+}
+
+/**
+ * The message a typed skill command becomes, as Claude Code sends it: the
+ * breadcrumb, then the skill's text, each ending in a newline. Arguments a
+ * generated body already carries are not passed again.
+ */
+export function typedSkillContent(name: string, typedArgs: string, promptText: string): [string, string] {
+	return [commandBreadcrumb(name, typedArgs), promptText.endsWith("\n") ? promptText : `${promptText}\n`];
+}
+
+/**
+ * A prompt command (`/init`, `/doctor`, a plugin command) as one user message,
+ * in a typed skill's exact bytes: Claude Code sends every prompt command led by
+ * its breadcrumb, and the transcript shows it as its command line
+ * (commandDisplayLine).
+ */
+export function promptCommandText(name: string, args: string, prompt: string): string {
+	return typedSkillContent(name, args, prompt).join("\n");
+}
+
+/** Claude Code's result for a model's skill call; the skill's text follows it as a second block. */
+export const launchingSkill = (name: string): string => `Launching skill: ${name}`;
+
+/**
+ * The lines that open and close a skill tool result when the model called a
+ * skill that takes arguments without passing any. A skill's text is its
+ * instructions, not a manual: a weak model "checking the interface" of
+ * `/loop` got the no-argument body, which starts an autonomous loop. A mild
+ * opening line lost to that body's "The user invoked /loop with no prompt"
+ * on DeepSeek V4.1 Flash; telling it to stop and check, plus a closing
+ * reminder, turned it around. Only the model's tool calls get this; a user's
+ * bare `/<name>` is deliberate.
+ */
+export function missingArgumentsNote(argumentHint: string): { before: string; after: string } {
+	return {
+		before: `Stop and check before following this. This skill takes arguments (${argumentHint}) and this call passed none, so what follows is its no-argument mode, written as if the user asked for the skill with nothing after it. If the user's request names any of those arguments, do not follow the instructions below: call the skill again with them in \`args\`.`,
+		after: "Reminder: those were the no-argument instructions. If the user's request included arguments, call the skill again with them in `args` instead of following them.",
+	};
+}
+
+/**
+ * The hidden message a `/skill:` command is delivered as. `details.input` is
+ * the text the user typed, so an extension that saw that text at `input` (the
+ * hooks extension's UserPromptSubmit context) can find the message that
+ * replaced it.
+ */
+export const SKILL_INVOCATION_TYPE = "one-code:skill-invocation";
+export interface SkillInvocationDetails {
+	skill: string;
+	args: string;
+	input?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -184,3 +215,15 @@ export function skillCommandCandidates<T extends { name: string; source: string
 	}
 	return out;
 }
+
+/**
+ * The `/` suggestions without pi's `/skill:<name>` entry for a skill that also
+ * has its bare `/<name>` command, so each skill is listed once, as in Claude
+ * Code. Kept when the user is typing `/skill:` themselves, and for a skill
+ * whose bare name was skipped (a collision), where `/skill:` is its only form.
+ * Typed `/skill:<name>` still runs either way: this only trims the list.
+ */
+export function withoutDuplicateSkillCommands<T extends { value: string }>(items: T[], prefix: string, bareSkills: ReadonlySet<string>): T[] {
+	if (!prefix.startsWith("/") || prefix.startsWith("/skill:")) return items;
+	return items.filter((item) => !(item.value.startsWith("skill:") && bareSkills.has(item.value.slice("skill:".length))));
+}

package/extensions/skill/listing.ts

@@ -2,20 +2,144 @@
  * The model-facing skills listing (pure). The state decides visibility: "on"
  * carries name + description, "name-only" just the name (saving context
  * tokens), "user-only"/"off" are hidden so the model won't auto-trigger them.
- * The description goes in whole, newlines included, the way Claude Code lists
- * it: a skill written with a YAML block description puts its "Use when…"
- * trigger on the later lines, and a first-line-only listing dropped exactly
- * the sentence that tells the model when to reach for the skill.
+ * A skill whose frontmatter sets `disable-model-invocation: true` is hidden
+ * whatever its state: only the user may start it, as in Claude Code.
+ *
+ * Each line is built the way Claude Code builds it: the description, then
+ * " - " and the `when_to_use` frontmatter when there is one, clipped at 1,536
+ * characters (1,535 and an ellipsis). The description keeps its newlines: a
+ * skill written with a YAML block description puts its "Use when…" trigger on
+ * the later lines, and a first-line-only listing dropped exactly the sentence
+ * that tells the model when to reach for the skill.
+ *
+ * The whole listing has a budget, 1% of the context window in characters
+ * (`SLASH_COMMAND_TOOL_CHAR_BUDGET` replaces it). Over budget, a bundled skill
+ * and a name-only one keep their lines; the others keep theirs by usage rank
+ * while the budget lasts and are listed by name after that.
  */
 
 import { type SkillState, skillListingVisibility } from "../lib/skill-overrides.ts";
+import type { UsageEntry } from "../lib/usage-tracker.ts";
 
-export function skillListingText(skills: ReadonlyArray<{ name: string; description?: string; state: SkillState }>): string {
-	const lines = skills.flatMap((skill) => {
+/** Claude Code's per-entry cap (its `skillListingMaxDescChars` default). */
+export const SKILL_DESCRIPTION_CAP = 1536;
+/** The listing's share of the context window, at 4 characters per token, 200K tokens when the window is unknown. */
+const BUDGET_FRACTION = 0.01;
+const CHARS_PER_TOKEN = 4;
+const DEFAULT_CONTEXT_WINDOW = 200_000;
+
+export interface ListedSkill {
+	name: string;
+	description?: string;
+	/** The `when_to_use` frontmatter, appended after " - ". */
+	whenToUse?: string;
+	state: SkillState;
+	disableModelInvocation?: boolean;
+	/** Ships inside One Code: keeps its line over budget, as Claude Code's bundled skills do. */
+	bundled?: boolean;
+	/** The usage score that ranks the line over budget (`usageScore`). */
+	usage?: number;
+}
+
+/** The text after `- <name>: `, clipped as Claude Code clips it. */
+export function listingDescription(skill: Pick<ListedSkill, "description" | "whenToUse">): string {
+	const description = skill.description?.trim() ?? "";
+	const whenToUse = skill.whenToUse?.trim();
+	const text = whenToUse ? `${description} - ${whenToUse}` : description;
+	return text.length > SKILL_DESCRIPTION_CAP ? `${text.slice(0, SKILL_DESCRIPTION_CAP - 1)}…` : text;
+}
+
+/** The listing's character budget for a context window (tokens). */
+export function skillListingBudget(contextWindow: number | undefined, env: NodeJS.ProcessEnv = process.env): number {
+	const fromEnv = Number.parseInt(env.SLASH_COMMAND_TOOL_CHAR_BUDGET ?? "", 10);
+	if (fromEnv > 0) return fromEnv;
+	const window = contextWindow && contextWindow > 0 ? contextWindow : DEFAULT_CONTEXT_WINDOW;
+	return Math.max(1, Math.floor(window * CHARS_PER_TOKEN * BUDGET_FRACTION));
+}
+
+/** Claude Code's ranking score: uses, halved every week since the last one, never below a tenth. */
+export function usageScore(entry: UsageEntry | undefined, now: Date = new Date()): number {
+	if (!entry) return 0;
+	const last = Date.parse(entry.lastUsedAt);
+	if (Number.isNaN(last)) return 0;
+	const days = (now.getTime() - last) / 86_400_000;
+	return entry.count * Math.max(0.5 ** (days / 7), 0.1);
+}
+
+export function skillListingText(skills: ReadonlyArray<ListedSkill>, budget = Number.POSITIVE_INFINITY): string {
+	const listed = skills.flatMap((skill) => {
+		if (skill.disableModelInvocation) return [];
 		const visibility = skillListingVisibility(skill.state);
 		if (visibility === "hidden") return [];
-		if (visibility === "name") return [`- ${skill.name}`];
-		return [`- ${skill.name}${skill.description?.trim() ? `: ${skill.description.trim()}` : ""}`];
+		const short = `- ${skill.name}`;
+		if (visibility === "name") return [{ skill, short, full: short }];
+		const text = listingDescription(skill);
+		return [{ skill, short, full: text ? `${short}: ${text}` : short }];
 	});
-	return lines.length === 0 ? "(no skills available)" : lines.join("\n");
+	if (listed.length === 0) return "(no skills available)";
+	const separators = listed.length - 1;
+	const whole = listed.reduce((sum, line) => sum + line.full.length, 0) + separators;
+	if (whole <= budget) return listed.map((line) => line.full).join("\n");
+
+	// A name-only line's full form is its short form, so it needs no place in `kept`.
+	const kept = new Set(listed.filter((line) => line.skill.bundled));
+	const ranked = listed.filter((line) => !kept.has(line));
+	let left = budget - (listed.reduce((sum, line) => sum + (kept.has(line) ? line.full.length : line.short.length), 0) + separators);
+	// A stable sort: equal scores keep the listing's order.
+	for (const line of [...ranked].sort((a, b) => (b.skill.usage ?? 0) - (a.skill.usage ?? 0))) {
+		const extra = line.full.length - line.short.length;
+		if (extra > left) continue;
+		kept.add(line);
+		left -= extra;
+	}
+	return listed.map((line) => (kept.has(line) ? line.full : line.short)).join("\n");
+}
+
+/**
+ * The skills listing for a session without the skill tool: each skill's file,
+ * to read with `reader`. The same states as the tool's listing: user-only and
+ * off skills stay hidden, a name-only skill shows no description. Undefined
+ * when nothing is listable.
+ */
+export function readableSkillListing(
+	skills: ReadonlyArray<ListedSkill & { path?: string; kind?: string }>,
+	reader: string,
+): string | undefined {
+	const lines = skills
+		.filter((skill) => !skill.kind && !skill.disableModelInvocation && skill.path && skillListingVisibility(skill.state) !== "hidden")
+		.map((skill) => {
+			const text = skillListingVisibility(skill.state) === "full" ? listingDescription(skill) : "";
+			return `- ${skill.name}${text ? `: ${text}` : ""} (${skill.path})`;
+		});
+	if (lines.length === 0) return undefined;
+	return `The following skills provide specialized instructions for specific tasks. Read a skill's file with ${reader} when the task matches its description:\n\n${lines.join("\n")}`;
+}
+
+/**
+ * Claude Code's reading of a boolean frontmatter flag such as
+ * `disable-model-invocation`: `true` or the string `"true"`, nothing else.
+ */
+export function frontmatterFlag(value: unknown): boolean {
+	return value === true || value === "true";
+}
+
+/**
+ * pi's own skills section in a rendered system prompt (`formatSkillsForPrompt`):
+ * pi 1.0 renders it as a `<skills>` section, older pi (the 0.84 floor)
+ * appends it after a blank line. Both start with this sentence.
+ */
+const PI_SKILLS_LEAD = "The following skills provide specialized instructions for specific tasks.";
+const PI_SKILLS_SECTION = /\n*<skills>\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>\n<\/skills>/;
+const PI_SKILLS_APPENDED = /\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/;
+
+/**
+ * `prompt` without pi's own skills section ("Use the read tool to load a
+ * skill's file …" and its `<available_skills>` list), unchanged when it has
+ * none. A session with the skill tool lists skills for that tool instead, and
+ * a child agent's prompt (pi adds the section to an agent's own prompt)
+ * otherwise told it both "read the file" and "call the skill tool first".
+ */
+export function withoutPiSkillsBlock(prompt: string): string {
+	if (!prompt.includes(PI_SKILLS_LEAD)) return prompt;
+	return prompt.replace(PI_SKILLS_SECTION, "").replace(PI_SKILLS_APPENDED, "");
 }

package/extensions/skill/panel/keys.ts

@@ -1,41 +1,40 @@
 /**
- * Raw-byte key decoding for the /skills panel (pure).
+ * Key decoding for the /skills panel (pure), named through
+ * `lib/key-input.ts` so every terminal encoding of a key decodes alike.
  *
- * Same control-byte map as the /plugins panel; kept local so the skill
+ * Same key map as the /plugins panel; kept local so the skill
  * extension carries no dependency on another extension's internals. Printable
  * input is a `text` intent the state layer routes (into the search box, or as a
  * single-letter action when search is inactive). Skill names never contain
  * spaces, so Space is always the cycle action, never typed.
  */
 
+import { keyId, keyText } from "../../lib/key-input.ts";
+
 export type SkillsKey =
 	| { kind: "up" | "down" | "enter" | "space" | "back" | "backspace" | "close" }
 	| { kind: "text"; text: string };
 
 export function decodeSkillsKey(data: string): SkillsKey | undefined {
-	switch (data) {
-		case "\x1b[A":
-		case "\x1bOA":
+	switch (keyId(data)) {
+		case "up":
 			return { kind: "up" };
-		case "\x1b[B":
-		case "\x1bOB":
+		case "down":
 			return { kind: "down" };
-		case "\r":
-		case "\n":
+		case "enter":
 			return { kind: "enter" };
-		case " ":
+		case "space":
 			return { kind: "space" };
-		case "\x1b":
+		case "escape":
 			return { kind: "back" };
-		case "\x7f":
-		case "\b":
+		case "backspace":
+		case "ctrl+backspace":
 			return { kind: "backspace" };
-		case "\x03":
+		case "ctrl+c":
 			return { kind: "close" };
 		default:
 			break;
 	}
-	if (data.startsWith("\x1b")) return undefined;
-	const text = [...data].filter((ch) => ch >= " " && ch !== "\x7f").join("");
+	const text = keyText(data);
 	return text ? { kind: "text", text } : undefined;
 }

package/extensions/skill/panel/render.ts

@@ -9,7 +9,7 @@
  * under-measure and risk pi's overwide-line crash.
  */
 
-import { cutPlainText, padPlainText, panelTopRule, searchBoxLines, visibleWidth } from "../../lib/tui-render.ts";
+import { cutPlainText, padPlainText, panelTopRule, searchBoxLines, visibleWidth, wrapHints } from "../../lib/tui-render.ts";
 import type { SkillState } from "../../lib/skill-overrides.ts";
 import { clampSkillsCursor, type SkillsPanelState, type SkillsRow, visibleRows } from "./state.ts";
 
@@ -64,7 +64,10 @@ export function renderSkillsPanel(input: SkillsRenderInput, paint: SkillsPaint):
 	const out: string[] = [panelTopRule(paint.fg, width)];
 	out.push(` ${paint.bold("Skills")}`);
 	const sortNote = state.sort === "state" ? "sorted by state" : "sorted by name";
-	out.push(paint.fg("dim", cutPlainText(` ${rows.length} skill${rows.length === 1 ? "" : "s"} · ${sortNote} · enter/space to cycle, / to search, t to sort, Esc to close`, width - 1)));
+	// Wraps at the separators on a narrow terminal, so no key is cut off; the
+	// list budget below is taken after it.
+	const hints = `${rows.length} skill${rows.length === 1 ? "" : "s"} · ${sortNote} · enter/space to cycle · / to search · t to sort · Esc to close`;
+	for (const line of wrapHints(hints, Math.max(1, width - 2))) out.push(paint.fg("dim", ` ${line}`));
 	out.push("");
 	out.push(...searchBoxLines(state.search, "Search skills…", paint.fg, width));
 	out.push("");

package/extensions/skill/panel/state.ts

@@ -14,7 +14,8 @@ export interface SkillsRow {
 	/** Override-store key, `<scope>:<name>`. */
 	key: string;
 	name: string;
-	scope: SkillScope;
+	/** Shown in the row: where the skill comes from; "bundled" is One Code's own catalog. */
+	scope: SkillScope | "bundled";
 	tokens: number;
 	/** Current state; for locked (plugin) rows this is the effective on/off. */
 	state: SkillState;
@@ -63,6 +64,16 @@ export function clampSkillsCursor(state: SkillsPanelState, visible: SkillsRow[])
 	state.cursor = Math.max(0, Math.min(state.cursor, visible.length - 1));
 }
 
+/**
+ * Keep the cursor on the skill `key` after the list reordered (a sort toggle,
+ * or a state change under the state sort), so the next key acts on the skill
+ * the user was looking at, not the one that slid into its row.
+ */
+export function followRow(state: SkillsPanelState, visible: SkillsRow[], key: string): void {
+	const index = visible.findIndex((row) => row.key === key);
+	if (index >= 0) state.cursor = index;
+}
+
 /**
  * Fold a key into the state, returning an effect the wiring must act on. The
  * caller passes the already-filtered/sorted rows so "the selected row" matches

package/extensions/subagents/agent-args.ts

@@ -0,0 +1,39 @@
+import { DEFAULT_AGENT } from "./runs.ts";
+
+/**
+ * The Agent tool's argument preparation (pure), run by pi before schema
+ * validation. `task` is required in the schema: a weak model read an optional
+ * task as optional and sent run options with no task, again and again
+ * (DeepSeek V3.2, live, 2026-10-05). Two callers still validate:
+ *
+ * - a Claude Code-trained model writes the task as `prompt`, which is moved
+ *   into `task` (TOOL-FIDELITY-REVIEW-2026-09-07 H1);
+ * - `action: "list"` only browses the catalog and needs no task.
+ *
+ * A run that names no agent gets general-purpose here, as in Claude Code, so
+ * the permission gate, hooks and the stored call see the agent that runs: an
+ * `Agent(general-purpose)` deny rule must stop a call that omits the type.
+ *
+ * Anything that is not a plain object is passed through for the validator to
+ * reject as it does today.
+ */
+export function prepareAgentArguments(args: unknown): unknown {
+	if (!args || typeof args !== "object" || Array.isArray(args)) return args;
+	const input = args as Record<string, unknown>;
+	const prepared = withTask(input);
+	if (!isRun(input) || (typeof input.subagent_type === "string" && input.subagent_type)) return prepared;
+	return { ...prepared, subagent_type: DEFAULT_AGENT };
+}
+
+function withTask(input: Record<string, unknown>): Record<string, unknown> {
+	if (typeof input.task === "string" && input.task.length > 0) return input;
+	if (typeof input.prompt === "string" && input.prompt.length > 0) return { ...input, task: input.prompt };
+	if (input.action === "list" && input.task === undefined) return { ...input, task: "" };
+	return input;
+}
+
+/** A call carrying run options (a task, a name, a model/thinking/isolation override, or action:"run"); one with none lists the catalog. */
+function isRun(input: Record<string, unknown>): boolean {
+	if (input.action === "list") return false;
+	return input.action === "run" || [input.task, input.prompt, input.name, input.model, input.isolation, input.thinking].some((value) => value != null);
+}