one-code-extension 0.1.4 → 0.3.1

package/extensions/subagents/agents.ts

@@ -1,21 +1,39 @@
 /**
  * Agent definition discovery (pure) — Claude Code's `.claude/agents/*.md`
- * layout: YAML frontmatter (name, description, tools, model) plus a system
- * prompt body.
+ * layout: YAML frontmatter (name, description, tools, disallowedTools, model)
+ * plus a system prompt body.
+ *
+ * Tool names in `tools`/`disallowedTools` are Claude Code's (`Read`, `Edit`,
+ * `Bash`, `Grep`, `Glob`, `WebFetch`, …) in every real agent file, and pi's
+ * allowlist is an exact-name set over pi's snake_case names — passing CC names
+ * through verbatim gave the child NO tools at all (SUBAGENT-REVIEW H2). Both
+ * lists are therefore normalized through the shared CC↔pi alias table at parse
+ * time; pi names and `mcp__*` names pass through unchanged.
  *
  * Precedence: user (~/.claude/agents) < project (<cwd>/.claude/agents).
  * Subdirectories are searched recursively.
  */
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
-import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatterLoosely } from "../lib/frontmatter.ts";
+import { claudeUserDir } from "../lib/paths.ts";
+import { normalizeToolName } from "../permissions/matcher.ts";
 
 export interface AgentDefinition {
 	name: string;
 	description: string;
-	/** Tool allowlist for the child; undefined means the child's defaults. */
+	/** Tool allowlist for the child (pi names); undefined means the child's defaults. */
 	tools?: string[];
+	/**
+	 * Tool denylist (pi names): the child gets its default toolset MINUS these —
+	 * Claude Code's "All tools except …" grant shape (its Explore/Plan agents),
+	 * spelled `disallowedTools` in CC frontmatter; `excludeTools` is accepted as
+	 * a synonym for definitions written against earlier One Code builds. Filters
+	 * built-ins, extension tools, and injected custom tools alike (pi's
+	 * excludeTools). Combinable with `tools`, though agents use one or the other.
+	 */
+	excludeTools?: string[];
 	/** Model override (pi model id, e.g. "anthropic/claude-sonnet-5"). */
 	model?: string;
 	systemPrompt: string;
@@ -23,10 +41,23 @@ export interface AgentDefinition {
 }
 
 function collectMarkdownFiles(dir: string, out: string[] = []): string[] {
-	if (!existsSync(dir)) return out;
-	for (const entry of readdirSync(dir)) {
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return out; // missing or unreadable directory: nothing to discover
+	}
+	for (const entry of entries) {
 		const full = join(dir, entry);
-		if (statSync(full).isDirectory()) {
+		// A dangling symlink or an unreadable entry must not take the whole
+		// catalog (and every Agent call) down with it — skip it (review L1).
+		let isDirectory: boolean;
+		try {
+			isDirectory = statSync(full).isDirectory();
+		} catch {
+			continue;
+		}
+		if (isDirectory) {
 			collectMarkdownFiles(full, out);
 		} else if (entry.endsWith(".md")) {
 			out.push(full);
@@ -36,31 +67,23 @@ function collectMarkdownFiles(dir: string, out: string[] = []): string[] {
 }
 
 /**
- * Frontmatter in the wild is not always valid YAML: real Claude Code plugin
- * agents contain unquoted descriptions with `: ` in them, which pi's parser
- * rejects ("Nested mappings are not allowed in compact mappings"). Falling back
- * to line-wise extraction keeps those definitions usable instead of dropping
- * them silently.
+ * A frontmatter tool list (comma string or YAML list) as pi tool names: Claude
+ * Code spellings map through the alias table (`Glob` → `find`, `WebFetch` →
+ * `web_fetch`, `Task` → `Agent`, …), pi names and `mcp__*` pass through,
+ * duplicates collapse. Exported for tests.
  */
-function parseFrontmatterLoosely(content: string): { frontmatter: Record<string, unknown>; body: string } {
-	try {
-		const parsed = parseFrontmatter(content) as { frontmatter?: Record<string, unknown>; body: string };
-		return { frontmatter: parsed.frontmatter ?? {}, body: parsed.body };
-	} catch {
-		// Fall through to the lenient path.
-	}
-
-	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-	if (!match) return { frontmatter: {}, body: content };
-
-	const frontmatter: Record<string, unknown> = {};
-	for (const line of match[1].split(/\r?\n/)) {
-		const keyValue = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
-		if (!keyValue) continue;
-		const value = keyValue[2].trim().replace(/^["']|["']$/g, "");
-		if (value) frontmatter[keyValue[1]] = value;
-	}
-	return { frontmatter, body: match[2] };
+export function parseToolList(raw: unknown): string[] | undefined {
+	const list =
+		typeof raw === "string"
+			? raw
+					.split(",")
+					.map((t) => t.trim())
+					.filter(Boolean)
+			: Array.isArray(raw)
+				? raw.filter((t): t is string => typeof t === "string").map((t) => t.trim()).filter(Boolean)
+				: undefined;
+	if (!list || list.length === 0) return undefined;
+	return [...new Set(list.map(normalizeToolName))];
 }
 
 export function parseAgentFile(path: string, content: string): AgentDefinition | undefined {
@@ -69,21 +92,14 @@ export function parseAgentFile(path: string, content: string): AgentDefinition |
 	const name = typeof fm.name === "string" && fm.name.trim() ? fm.name.trim() : basename(path, ".md");
 	if (!body.trim()) return undefined;
 
-	const rawTools = fm.tools;
-	const tools =
-		typeof rawTools === "string"
-			? rawTools
-					.split(",")
-					.map((t) => t.trim())
-					.filter(Boolean)
-			: Array.isArray(rawTools)
-				? rawTools.filter((t): t is string => typeof t === "string")
-				: undefined;
+	// CC's key first; the One Code synonym merges in so neither spelling is lost.
+	const disallowed = [...(parseToolList(fm.disallowedTools) ?? []), ...(parseToolList(fm.excludeTools) ?? [])];
 
 	return {
 		name,
 		description: typeof fm.description === "string" ? fm.description : "",
-		tools: tools && tools.length > 0 ? tools : undefined,
+		tools: parseToolList(fm.tools),
+		excludeTools: disallowed.length > 0 ? [...new Set(disallowed)] : undefined,
 		// "inherit" is Claude Code's way of saying "use the session model".
 		model: typeof fm.model === "string" && fm.model !== "inherit" ? fm.model : undefined,
 		systemPrompt: body.trim(),
@@ -97,7 +113,7 @@ export function parseAgentFile(path: string, content: string): AgentDefinition |
  * project definition with the same name replaces a bundled one.
  */
 export function agentDirs(cwd: string, home: string, bundled?: string): string[] {
-	return [...(bundled ? [bundled] : []), join(home, ".claude", "agents"), join(cwd, ".claude", "agents")];
+	return [...(bundled ? [bundled] : []), join(claudeUserDir(home), "agents"), join(cwd, ".claude", "agents")];
 }
 
 /** A directory whose agents are exposed as `<namespace>:<name>` (plugins). */
@@ -124,3 +140,31 @@ export function discoverAgents(sources: Array<string | AgentSource>): AgentDefin
 	}
 	return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
+
+/**
+ * Tools a child cannot function without, re-added when an agent file's `tools`
+ * allowlist omits them: pi's allowlist filters built-ins, extension tools AND
+ * injected custom tools by exact name, so a CC-style `tools: Read, Grep` would
+ * otherwise also strip the child's report channel (`SendMessage` → main), its
+ * deferred-tool loader and the runtime's `structured_output`. Claude Code's
+ * allowlist never strips its own plumbing either.
+ */
+const ALLOWLIST_ESSENTIALS = ["SendMessage", "tool_search", "structured_output"];
+
+/** Apply an agent's allowlist to pi's `tools` option, keeping the essentials. */
+export function childToolAllowlist(tools: string[] | undefined): string[] | undefined {
+	if (!tools) return undefined;
+	return [...new Set([...tools, ...ALLOWLIST_ESSENTIALS])];
+}
+
+/**
+ * The names of an agent's `tools` allowlist that pi actually registered. Empty
+ * means the list named no real tool (CC spellings that missed the alias table,
+ * typos), which must fail loud rather than run a tool-less agent that
+ * "completes" with an excuse. Judged against the agent's OWN list — an agent
+ * that deliberately lists only `SendMessage` is narrow, not broken.
+ */
+export function usableAllowlistedTools(registered: string[], allowlist: string[]): string[] {
+	const available = new Set(registered);
+	return allowlist.filter((name) => available.has(name));
+}

package/extensions/subagents/default-model.ts

@@ -12,7 +12,13 @@
  *   same containment rule as `autoMode` config.
  * - `subagentModel` — One Code's own top-level setting, same shape as
  *   `autoMode.classifierModel`. Wins over the env var when both are set,
- *   because it is the more specific statement of intent.
+ *   because it is the more specific statement of intent. It is One Code's key,
+ *   not Claude Code's: it is written to and read from `~/.onecode/settings.json`
+ *   (+ managed settings), never from `~/.claude`, where an old One Code build may
+ *   have left a stale value the current session cannot reach. Claude Code's own
+ *   `CLAUDE_CODE_SUBAGENT_MODEL` env block is still honoured from `~/.claude`
+ *   (that key *is* Claude Code's). See "Own state, borrowed config" in
+ *   docs/decisions/memory-state.md.
  *
  * The env var additionally applies only to Claude-family sessions (see
  * `applicableSubagentDefault`): it is Claude Code's knob, and its typical
@@ -24,40 +30,61 @@
  * pass through to resolveSubagentModel, which owns the semantics.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { claudeUserSettingsPath, readSettingsFile } from "../lib/claude-settings.ts";
+import { isClaudeFamilyModel } from "../lib/model-policy.ts";
+import { oneCodeSettingsPath, readSettingsForWrite, writeSettings } from "../lib/one-code-settings.ts";
 import { autoModeSettingsPaths } from "../auto-mode/config.ts";
 
 export interface SubagentDefault {
 	spec: string;
 	/** Which knob set it, for notices. */
 	source: "subagentModel setting" | "CLAUDE_CODE_SUBAGENT_MODEL";
+	/**
+	 * For the `subagentModel` setting only: the *containment identity* of the
+	 * session it was stamped for when set via `/subagent` — `modelIdentity().containment`,
+	 * i.e. the plain provider for direct vendors but `provider:route:vendor` on a
+	 * gateway (openrouter etc.), matching the granularity `crossesProvider` uses.
+	 * When it differs from the current session's containment, a cross-provider
+	 * setting is treated as stale (set for a session since left) and a
+	 * same-provider model runs instead — see `resolveSubagentModel`. Undefined for
+	 * a hand-edited setting (no stamp) and for the env var.
+	 */
+	setForContainment?: string;
 }
 
 interface SettingsFile {
 	subagentModel?: unknown;
+	subagentModelSetFor?: unknown;
 	env?: Record<string, unknown>;
 }
 
+/** The shared lenient reader, narrowed to the subagent-relevant shape. */
 function readSettings(path: string): SettingsFile | undefined {
-	if (!existsSync(path)) return undefined;
-	try {
-		return JSON.parse(readFileSync(path, "utf-8")) as SettingsFile;
-	} catch {
-		return undefined;
-	}
+	return readSettingsFile(path) as SettingsFile | undefined;
 }
 
 export function loadSubagentDefault(home: string, env: NodeJS.ProcessEnv = process.env): SubagentDefault | undefined {
 	let setting: string | undefined;
+	let settingSetFor: string | undefined;
 	let settingsEnv: string | undefined;
 
+	// `subagentModel` is One Code's own key — read from `~/.onecode` and managed
+	// settings, never from `~/.claude`, where an old build may have left a stale
+	// value. Claude Code's `CLAUDE_CODE_SUBAGENT_MODEL` env block IS Claude Code's,
+	// so it is still read from every file.
+	const claudeUser = claudeUserSettingsPath(home);
 	// Lowest precedence first, so managed settings override user settings.
 	for (const path of autoModeSettingsPaths(home)) {
 		const file = readSettings(path);
 		if (!file) continue;
-		if (typeof file.subagentModel === "string" && file.subagentModel.trim()) {
+		if (path !== claudeUser && typeof file.subagentModel === "string" && file.subagentModel.trim()) {
 			setting = file.subagentModel.trim();
+			// The stamp travels with the model from the same file (a lower-precedence
+			// stamp must not attach to a higher-precedence model).
+			settingSetFor =
+				typeof file.subagentModelSetFor === "string" && file.subagentModelSetFor.trim()
+					? file.subagentModelSetFor.trim()
+					: undefined;
 		}
 		const fromEnvBlock = file.env?.CLAUDE_CODE_SUBAGENT_MODEL;
 		if (typeof fromEnvBlock === "string" && fromEnvBlock.trim()) {
@@ -65,7 +92,7 @@ export function loadSubagentDefault(home: string, env: NodeJS.ProcessEnv = proce
 		}
 	}
 
-	if (setting) return { spec: setting, source: "subagentModel setting" };
+	if (setting) return { spec: setting, source: "subagentModel setting", setForContainment: settingSetFor };
 
 	const fromEnv = env.CLAUDE_CODE_SUBAGENT_MODEL?.trim();
 	if (fromEnv) return { spec: fromEnv, source: "CLAUDE_CODE_SUBAGENT_MODEL" };
@@ -91,32 +118,35 @@ export function applicableSubagentDefault(
 ): SubagentDefault | undefined {
 	if (!configured || configured.source === "subagentModel setting") return configured;
 	if (!sessionModel) return configured;
-	const claudeFamily = sessionModel.provider === "anthropic" || /claude/i.test(sessionModel.id);
-	return claudeFamily ? configured : undefined;
+	return isClaudeFamilyModel(sessionModel) ? configured : undefined;
 }
 
 /**
- * Persist `subagentModel` in the *user* settings file, preserving every other
- * key. `undefined` removes the setting. Always user scope, like the loader:
- * the default may move subagent work to another provider, so it lives where
- * only the user writes — never in a project file (see the module comment).
+ * Persist `subagentModel` in One Code's own settings file
+ * (`~/.onecode/settings.json`), preserving every other key. `undefined` removes
+ * the setting. Never touches Claude Code's files: this is One Code's key, and the
+ * default may move subagent work to another provider, so it lives in One Code's
+ * own state (see the module comment).
  *
  * Unlike loading, this throws on a malformed file: a lenient read merely
- * skips a setting, but a lenient write would replace the user's whole
- * settings file with only ours.
+ * skips a setting, but a lenient write would replace the whole settings file
+ * with only ours.
+ *
+ * `setForContainment` stamps the containment identity of the session the model
+ * was chosen on (modelIdentity().containment), so a later session on a different
+ * provider/vendor can treat the setting as stale. Pass it for a concrete model;
+ * it is cleared for `inherit` (never cross-provider) and on removal.
  */
-export function persistSubagentModel(spec: string | undefined, home: string): void {
-	const path = join(home, ".claude", "settings.json");
-	let file: Record<string, unknown> = {};
-	if (existsSync(path)) {
-		const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
-		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-			throw new Error(`${path}: root must be a JSON object`);
-		}
-		file = parsed as Record<string, unknown>;
+export function persistSubagentModel(spec: string | undefined, home: string, setForContainment?: string): void {
+	const path = oneCodeSettingsPath(home);
+	const file = readSettingsForWrite(path);
+	if (spec === undefined) {
+		delete file.subagentModel;
+		delete file.subagentModelSetFor;
+	} else {
+		file.subagentModel = spec;
+		if (setForContainment && spec !== "inherit") file.subagentModelSetFor = setForContainment;
+		else delete file.subagentModelSetFor;
 	}
-	if (spec === undefined) delete file.subagentModel;
-	else file.subagentModel = spec;
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`);
+	writeSettings(path, file);
 }

package/extensions/subagents/delegation-steer.ts

@@ -0,0 +1,23 @@
+/**
+ * Tiny-tier-only strict delegation directive (pure prompt text), riding the
+ * context stack right after the agent catalog. Static prompt sections
+ * measurably move capable models to delegate broad sweeps (workhorse/cheap
+ * went 2/6 → 6/6 in the 2026-08-31 probe battery) but a sub-Haiku model
+ * ignored the same section (qwen3.6-27b: 0/6 with it verified on the wire); a
+ * <system-reminder> sits closer to the user text, where weak models actually
+ * attend. Keyed and byte-stable, so it is cache-neutral; removed when a model
+ * switch leaves the tiny tier (see index.ts emitDelegationSteer).
+ *
+ * Sibling texts (same delegation policy, separately tuned registers):
+ * DELEGATE_STRICT in system-prompt/tiers/low.ts (tiny prompt) and
+ * DELEGATING_WORK in tiers/mid.ts (workhorse/cheap prompt). The shared policy
+ * invariants are pinned by test/unit/delegation-prose.test.ts — when editing
+ * one register, keep the siblings aligned or that test will say so.
+ */
+
+export const DELEGATION_STEER = [
+	'Delegation policy: when a request requires reading or searching MANY files (a codebase overview, "find every place where…", a consistency audit, exploring unfamiliar code), do NOT sweep the files yourself.',
+	'Make ONE Agent tool call with subagent_type: "explore" and the complete question as the task. The agent searches in its own separate context and returns just the answer; reading file after file yourself fills your context and degrades your answer.',
+	"Search directly only for a single targeted lookup (one known file or symbol).",
+	"When the agent has answered, report its answer and move on — do not re-read the files it already covered.",
+].join("\n");

package/extensions/subagents/hand-back-review.ts

@@ -0,0 +1,67 @@
+/**
+ * The hand-back review of a resident agent's turn, awaited so the verdict
+ * travels WITH the completion report instead of trailing it.
+ *
+ * A resident's spawning call has already returned when its turn ends, so there
+ * is no tool_result for the auto-mode gate to attach its holistic review to.
+ * Emitting the actions and sending the report immediately (the previous
+ * shape) let the "flagged" notice land one or more tool boundaries after the
+ * report — the model could act on an agent's output before hearing that auto
+ * mode had concerns about how it was produced. Claude Code gates the hand-back
+ * (findings §17.2). This module holds the wait: the payload carries an
+ * `onReview` callback the gate answers exactly once (a rendered flag, or
+ * undefined for clean / not in auto mode), and a timeout bounds the wait so a
+ * slow or absent reviewer degrades to "report plus a note", never to a report
+ * that waits forever.
+ */
+import { SUBAGENT_ACTIONS_CHANNEL, type ChildAction, type SubagentActionsPayload } from "../auto-mode/actions.ts";
+
+/** How long a completion report waits for the gate's verdict before going out with a note instead. */
+export const HAND_BACK_REVIEW_TIMEOUT_MS = 45_000;
+
+/** The note that replaces a verdict that did not arrive in time. */
+export const HAND_BACK_REVIEW_TIMEOUT_NOTE =
+	"<system-reminder>\nAuto mode's review of this agent's actions did not finish before the report was delivered. Treat the output as unverified until you have checked it.\n</system-reminder>";
+
+/** The events slice this module needs. */
+export interface ActionsEmitter {
+	emit(channel: string, data: unknown): void;
+}
+
+/**
+ * Emit a resident turn's actions for review and resolve with the gate's
+ * rendered flag (undefined when clean, no actions, or the gate is not in auto
+ * mode). Never rejects. The first answer wins; late or repeated answers are
+ * ignored.
+ */
+export function awaitHandBackReview(
+	events: ActionsEmitter,
+	run: { taskId: string; name: string },
+	actions: ChildAction[] | undefined,
+	timeoutMs = HAND_BACK_REVIEW_TIMEOUT_MS,
+): Promise<string | undefined> {
+	if (!actions?.length) return Promise.resolve(undefined);
+	return new Promise((resolve) => {
+		let settled = false;
+		const finish = (flag: string | undefined) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(flag);
+		};
+		const timer = setTimeout(() => finish(HAND_BACK_REVIEW_TIMEOUT_NOTE), timeoutMs);
+		timer.unref?.();
+		events.emit(SUBAGENT_ACTIONS_CHANNEL, {
+			toolCallId: run.taskId,
+			actions,
+			background: true,
+			agentName: run.name,
+			onReview: finish,
+		} satisfies SubagentActionsPayload);
+	});
+}
+
+/** Prepend a review flag to a notification body, when there is one. */
+export function withReview(body: string, flag: string | undefined): string {
+	return flag ? `${flag}\n\n${body}` : body;
+}