one-code-extension 0.4.1 → 0.6.0

package/extensions/workflow/agent-session.ts

@@ -14,13 +14,16 @@
  * `extensionFactories`, which DefaultResourceLoader always loads.
  */
 
+import { childWriteWatcher } from "../lib/child-writes.ts";
+import { randomBytes } from "node:crypto";
 import os from "node:os";
 import { getAgentDir, type ModelRuntime, SessionManager, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { whenAborted } from "../lib/abort.ts";
-import { createSharedModelRuntime, finalAssistantText, openChildSession } from "../lib/agent-loader.ts";
+import { persistIfLarge, sessionResultsDir } from "../lib/persisted-output.ts";
+import { createSharedModelRuntime, disposeChildSession, finalAssistantText, openChildSession } from "../lib/agent-loader.ts";
 import { modelSpec as modelSpecOf, supportsImageInput } from "../lib/model-policy.ts";
 import { isModelUnavailableError } from "../auto-mode/model-select.ts";
 import { agentPromptIdentity, PrefixWarmGate, prefixWarmKey } from "../lib/prefix-warm-gate.ts";
@@ -28,13 +31,17 @@ import type { PermissionBridge } from "../permissions/subagent-gate.ts";
 import { localGateMode, MODE_ENV } from "../lib/permission-gate.ts";
 import type { HookBridge } from "../hooks/subagent-bridge.ts";
 import { summarizeArgs } from "../lib/tui-render.ts";
-import { agentDirs, type AgentDefinition, discoverAgents } from "../subagents/agents.ts";
+import { type AgentDefinition, agentFileSources, agentToolOptions, discoverAgents, unusableAllowlistError } from "../subagents/agents.ts";
+import { defaultDiscoverRoots, discoverPlugins } from "../lib/plugins.ts";
+import { CHILD_EXTENSION_PATHS } from "../lib/child-extensions.ts";
+import { oneTurnHandbackSlot, subagentHandbackExtension } from "../lib/subagent-handback.ts";
 import type { SubagentDefault } from "../subagents/default-model.ts";
 import { expensiveModelGate, resolveSubagentModel, subagentModelMenu } from "../subagents/model-select.ts";
 import { withoutUnusable } from "../lib/model-unusable.ts";
 import { cleanupWorktree, createWorktree, isGitRepo, type Worktree } from "../subagents/worktree.ts";
-import type { AgentCallOptions, AgentCallResult, AgentEffort, AgentRunUpdate } from "./types.ts";
+import type { AgentCallOptions, AgentCallResult, AgentEffort, AgentRunUpdate, KeptWorktree } from "./types.ts";
 import { WorkflowScriptError } from "./types.ts";
+import { type DeferRequest, deferLikeParentExtension, injectedByParent } from "../lib/deferred.ts";
 
 const MAX_SCHEMA_RETRIES = 2;
 const OUTPUT_CAP = 50_000;
@@ -52,6 +59,8 @@ export interface AgentRunnerOptions {
 	unusableModels?: () => ReadonlySet<string>;
 	/** An agent's provider refused its model as not usable on this account (`isModelUnavailableError`): report it so every picker skips it. */
 	onModelUnusable?: (model: string, reason: string) => void;
+	/** An agent's edit or write changed a file (lib/child-writes.ts), for the parent's file-tracker. */
+	onChildWrite?: (path: string, agent: string | undefined) => void;
 	/**
 	 * The parent permissions extension's decision closure (same bridge the
 	 * subagent runner uses): when present, a workflow agent's tool calls route
@@ -65,6 +74,15 @@ export interface AgentRunnerOptions {
 	getHookBridge?: () => HookBridge | undefined;
 	/** Each finished agent's dollar cost (review S13: workflow agents never reached the footer). */
 	onUsage?: (cost: number) => void;
+	/**
+	 * The parent's live MCP tools (lib/mcp-share.ts `watchMcpTools`), injected
+	 * as custom tools over the parent's connections, as the subagent runner does.
+	 */
+	getMcpTools?: () => ToolDefinition[] | Promise<ToolDefinition[]>;
+	/** The tools the parent defers (lib/deferred.ts DEFERRED_QUERY_CHANNEL): the agent defers them too, so its MCP tools are listed, not declared. */
+	getParentDeferred?: () => DeferRequest[];
+	/** Where an answer past OUTPUT_CAP is saved (`<dir>/tool-results/`): the run's directory. */
+	resultsDir?: string;
 }
 
 /**
@@ -199,7 +217,9 @@ export class AgentRunner {
 	static async create(options: AgentRunnerOptions): Promise<AgentRunner> {
 		const agentDir = getAgentDir();
 		const modelRuntime = await createSharedModelRuntime(agentDir);
-		const agentCatalog = discoverAgents(agentDirs(options.cwd, os.homedir()));
+		// The Agent tool's registry: bundled and plugin agents too, not only the user and project folders.
+		const plugins = discoverPlugins(defaultDiscoverRoots(agentDir, options.cwd));
+		const agentCatalog = discoverAgents(agentFileSources(options.cwd, os.homedir(), plugins.agentDirs));
 		const availableModels = [...(await modelRuntime.getAvailable())];
 		return new AgentRunner(options, modelRuntime, agentCatalog, availableModels);
 	}
@@ -245,6 +265,12 @@ export class AgentRunner {
 
 		await this.judgeDelegation(prompt, opts, agentDef, signal);
 
+		// Before the worktree exists: a malformed schema would otherwise leak it.
+		if (opts.schema) assertObjectSchema(opts.schema);
+
+		// Also before the worktree: a rejection here would leak it the same way.
+		const mcpTools = (await this.options.getMcpTools?.()) ?? [];
+
 		let worktree: Worktree | undefined;
 		let cwd = this.options.cwd;
 		if (opts.isolation === "worktree") {
@@ -256,13 +282,27 @@ export class AgentRunner {
 		}
 
 		const capture: { called: boolean; value: unknown } = { called: false, value: undefined };
-		const customTools: ToolDefinition[] = opts.schema ? [buildStructuredOutputTool(opts.schema, capture)] : [];
+		// An agent without a schema hands its answer back through SubagentHandback,
+		// as every child does; with a schema, structured_output is the hand-back.
+		const handback = opts.schema ? undefined : oneTurnHandbackSlot();
+		const customTools: ToolDefinition[] = [
+			...(opts.schema ? [buildStructuredOutputTool(opts.schema, capture)] : []),
+			...mcpTools,
+		];
 
+		// The same child session a subagent gets (SUBAGENTS-WORKFLOWS-REVIEW-2026-09-26
+		// H2, H3, M6): the curated child extensions, the parent's MCP tools, and the
+		// agent file's tool lists through the one shared builder, which keeps
+		// `structured_output` on an allowlist and applies `disallowedTools`.
 		const session = await openChildSession({
 			loader: {
 				cwd: this.options.cwd,
 				agentDir: getAgentDir(),
 				systemPrompt: agentDef?.systemPrompt,
+				extraExtensionPaths: CHILD_EXTENSION_PATHS,
+				// claude-context (a child extension) injects the CLAUDE.md instructions itself.
+				noContextFiles: true,
+				extraFactories: [deferLikeParentExtension(this.options.getParentDeferred?.() ?? [], injectedByParent([])), ...(handback ? [subagentHandbackExtension(handback)] : [])],
 				getPermissionBridge: this.options.getPermissionBridge,
 				getHookBridge: this.options.getHookBridge,
 			},
@@ -272,11 +312,16 @@ export class AgentRunner {
 				modelRuntime: this.modelRuntime,
 				model: modelSpec.model as never,
 				thinkingLevel: modelSpec.thinkingLevel as never,
-				tools: agentDef?.tools,
+				...agentToolOptions(agentDef),
 				customTools,
 				sessionManager: SessionManager.inMemory(cwd),
 			},
 			onError: (error) => this.options.onNotice?.(`${opts.label ?? "agent"}: extension error in ${error.event}: ${error.error}`),
+		}).catch(async (error: unknown) => {
+			// Not yet under the prompt's try/finally: a session that fails to open
+			// must not leak the worktree and its branch.
+			if (worktree) await this.settleWorktree(worktree, opts.label, error);
+			throw error;
 		});
 
 		const unhookAbort = whenAborted(signal, () => void session.abort());
@@ -284,8 +329,11 @@ export class AgentRunner {
 		// refusing the agent's model (the same check the subagent runner makes, so
 		// the refusal reaches every automatic picker — lib/model-unusable.ts).
 		// Never let a bad event shape kill the agent.
+		const childWrote = childWriteWatcher(session.sessionManager?.getCwd?.() ?? this.options.cwd);
 		const unsubscribe = session.subscribe((event) => {
 			try {
+				const wrote = childWrote(event as never);
+				if (wrote) this.options.onChildWrite?.(wrote, opts.label);
 				if (event.type === "message_end") {
 					const reply = (event as { message?: { role?: string; stopReason?: string; errorMessage?: string; provider?: string; model?: string } }).message;
 					if (reply?.role === "assistant" && reply.stopReason === "error" && reply.errorMessage && reply.provider && reply.model && isModelUnavailableError(reply.errorMessage)) {
@@ -310,7 +358,17 @@ export class AgentRunner {
 			prefixWarmKey(agentPromptIdentity(agentDef?.name), cwd, model ? modelSpecOf(model) : undefined),
 			session,
 		);
+		let failure: unknown;
 		try {
+			// An allowlist that matched no real tool would run a tool-less agent.
+			const unusable = unusableAllowlistError(
+				agentDef,
+				session.getAllTools().map((t) => t.name),
+			);
+			if (unusable) throw new WorkflowScriptError(unusable);
+			// A stop during the waits above (MCP tools still connecting, the warm
+			// gate) aborted a session that was idle: never send the first request.
+			if (signal.aborted) throw new WorkflowScriptError("aborted");
 			await session.prompt(this.buildPrompt(prompt, Boolean(opts.schema)));
 			if (signal.aborted) throw new WorkflowScriptError("aborted");
 
@@ -318,27 +376,39 @@ export class AgentRunner {
 			if (opts.schema) {
 				value = await this.resolveStructuredOutput(session, capture, signal);
 			} else {
-				value = finalAssistantText(session.messages);
+				// The handed-back report, else the agent's last message.
+				value = handback?.report ?? finalAssistantText(session.messages);
 				if (typeof value !== "string" || !value.trim()) {
 					throw new Error("subagent produced no output");
 				}
-				value = (value as string).slice(0, OUTPUT_CAP);
+				// Never cut: a long answer is saved to the run directory and the script
+				// gets Claude Code's <persisted-output> block naming the file, which a
+				// later agent can read (SUBAGENTS-WORKFLOWS-REVIEW-2026-09-26 M1).
+				value = persistIfLarge(value as string, {
+					dir: this.options.resultsDir ?? sessionResultsDir(undefined),
+					id: `agent-${randomBytes(4).toString("hex")}`,
+					maxBytes: OUTPUT_CAP,
+				});
 			}
 
 			const stats = session.getSessionStats();
-			// cleanupWorktree keeps trees holding uncommitted changes; report those.
-			let worktreePath: string | undefined;
+			// cleanupWorktree keeps trees holding uncommitted changes or commits; report those.
+			let kept: Worktree | undefined;
 			if (worktree) {
 				const removed = await cleanupWorktree(this.options.cwd, worktree);
-				if (!removed) worktreePath = worktree.path;
+				if (!removed) kept = worktree;
 				worktree = undefined;
 			}
 			return {
 				value,
 				tokens: { input: stats.tokens.input, output: stats.tokens.output, total: stats.tokens.total },
 				cost: stats.cost,
-				worktreePath,
+				worktreePath: kept?.path,
+				worktreeBranch: kept?.branch,
 			};
+		} catch (error) {
+			failure = error;
+			throw error;
 		} finally {
 			// Whatever the outcome — success, failure, or an abort (a user stop, or
 			// the run finishing with this agent un-awaited) — the provider was
@@ -348,11 +418,26 @@ export class AgentRunner {
 			releasePrefix(false);
 			unsubscribe?.();
 			unhookAbort();
-			session.dispose();
-			if (worktree) await cleanupWorktree(this.options.cwd, worktree);
+			disposeChildSession(session);
+			// A failed or aborted agent can still have edited or committed in its
+			// worktree: settled after the session is gone, before the error reaches
+			// the caller, so the kept path rides on it.
+			if (worktree) await this.settleWorktree(worktree, opts.label, failure);
 		}
 	}
 
+	/**
+	 * Remove a failed agent's worktree, or keep it when it holds changes or
+	 * commits: then the run log names it, and the kept path rides on `error`
+	 * (`keptWorktreeOf`) so the agent's end event and the run report list it.
+	 */
+	private async settleWorktree(worktree: Worktree, label: string | undefined, error: unknown): Promise<void> {
+		if (await cleanupWorktree(this.options.cwd, worktree)) return;
+		const kept: KeptWorktree = { path: worktree.path, branch: worktree.branch };
+		this.options.onNotice?.(`${label ?? "agent"}: worktree kept at ${kept.path} (branch ${kept.branch}) with its changes or commits`);
+		if (error instanceof Error) (error as Error & { keptWorktree?: KeptWorktree }).keptWorktree = kept;
+	}
+
 	private judgeDelegation(prompt: string, opts: AgentCallOptions, agentDef: AgentDefinition | undefined, signal: AbortSignal): Promise<void> {
 		return judgeWorkflowDelegation({
 			bridge: this.options.getPermissionBridge?.(),
@@ -367,7 +452,7 @@ export class AgentRunner {
 
 	private buildPrompt(prompt: string, structured: boolean): string {
 		if (!structured) {
-			return `${prompt}\n\nYour final message is returned verbatim to an orchestration script, not shown to a human — reply with the requested data/report only.`;
+			return `${prompt}\n\nThe report you hand back through SubagentHandback is returned verbatim to an orchestration script, not shown to a human — hand back the requested data/report only.`;
 		}
 		return `${prompt}\n\nWhen you are done, you MUST call the \`structured_output\` tool exactly once with your final result. Its arguments are the only output the caller receives.`;
 	}
@@ -398,9 +483,7 @@ export class AgentRunner {
 
 /** Terminating tool capturing schema-validated output (pi validates params pre-execute). */
 function buildStructuredOutputTool(schema: Record<string, unknown>, capture: { called: boolean; value: unknown }): ToolDefinition {
-	if (schema.type !== "object" || typeof schema.properties !== "object") {
-		throw new WorkflowScriptError("agent() schema must be a JSON Schema with top-level type \"object\" and properties");
-	}
+	assertObjectSchema(schema);
 	return {
 		name: "structured_output",
 		label: "Structured Output",
@@ -418,6 +501,13 @@ function buildStructuredOutputTool(schema: Record<string, unknown>, capture: { c
 	} as ToolDefinition;
 }
 
+/** A structured_output schema must be an object schema with properties. */
+function assertObjectSchema(schema: Record<string, unknown>): void {
+	if (schema.type !== "object" || typeof schema.properties !== "object") {
+		throw new WorkflowScriptError("agent() schema must be a JSON Schema with top-level type \"object\" and properties");
+	}
+}
+
 /** Pull the first parseable JSON object/array out of free text (```json fences first). */
 function extractJsonObject(text: string): unknown {
 	const fenced = text.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);

package/extensions/workflow/args.ts

@@ -0,0 +1,24 @@
+/** The workflow tool's argument preparation (pure). */
+
+/**
+ * The call's arguments with `args` as the script should see it, decoded before
+ * the gate, hooks and the stored call see them. Weak models send a list or
+ * object as a JSON-encoded string despite the description (every Qwen 3.8
+ * model, battery round 7), which breaks `args.map` and `pipeline(args, …)`; a
+ * string that parses to an array or object is decoded. Any other value passes
+ * verbatim.
+ */
+export function prepareWorkflowArguments(raw: unknown): unknown {
+	if (!raw || typeof raw !== "object" || !("args" in raw)) return raw;
+	return { ...raw, args: decodedArgs((raw as { args: unknown }).args) };
+}
+
+function decodedArgs(args: unknown): unknown {
+	if (typeof args !== "string" || !/^\s*[[{]/.test(args)) return args;
+	try {
+		const parsed: unknown = JSON.parse(args);
+		return parsed !== null && typeof parsed === "object" ? parsed : args;
+	} catch {
+		return args;
+	}
+}

package/extensions/workflow/description.ts

@@ -0,0 +1,67 @@
+/**
+ * The workflow tool's model-facing description: Claude Code's Workflow text
+ * and its size-guideline line (pure).
+ *
+ * The authoring reference (script API, quality patterns, resume, worked
+ * examples) is the bundled `workflow-authoring` skill, which the description
+ * tells the model to load before writing a script. The size line follows
+ * `workflowSizeGuideline` in One Code's settings (lib/one-code-settings.ts);
+ * "unrestricted" sends no line, as in Claude Code. Changes from Claude Code's
+ * text: the setting is named where Claude Code points to its /config row, and
+ * tool names are One Code's.
+ */
+
+import type { WorkflowSizeGuideline } from "../lib/one-code-settings.ts";
+
+export const WORKFLOW_DESCRIPTION_BODY = `Execute a workflow script that orchestrates multiple subagents deterministically. Workflows run in the background — this tool returns immediately with a task ID, and a <task-notification> arrives when the workflow completes. Use /workflows to watch live progress.
+
+ONLY call this tool when the user has explicitly opted into multi-agent orchestration. Workflows can spawn dozens of agents and consume a large amount of tokens; the user must request that scale, not have it inferred. Explicit opt-in means one of:
+- The user included the keyword "ultracode" in their prompt (you'll see a system-reminder confirming it).
+- Ultracode is on for the session (a system-reminder confirms it) — see **Ultracode** in the workflow authoring reference.
+- The user directly asked you to run a workflow or use multi-agent orchestration in their own words ("use a workflow", "run a workflow", "fan out agents", "orchestrate this with subagents"). The ask must be in the user's words — a task that would merely benefit from a workflow does not count.
+- The user invoked a skill or slash command whose instructions tell you to call Workflow.
+- The user asked you to run a specific named or saved workflow.
+
+For any other task — even one that would clearly benefit from parallelism — do NOT call this tool. Use the Agent tool (if available) for individual subagents, or briefly describe what a multi-agent workflow could do and how much it would roughly cost, and ask the user whether to run it. Mention they can ask for one with "use a workflow" in a future message to skip the ask.
+
+Every script must begin with \`export const meta = {...}\`: a PURE LITERAL (no variables, calls or interpolation) giving the workflow's \`name\`, a one-line \`description\` (shown in the permission dialog) and optionally \`phases\` — one \`{ title, detail? }\` per phase() call, titles matched exactly. Pass the script inline via \`script\` — do not write it to a file first, and do not also set the tool's \`name\` input (that selects a saved workflow); it is plain JavaScript, not TypeScript.
+
+The canonical multi-stage pattern — pipeline by default, each dimension verifies as soon as its review completes:
+  export const meta = {
+    name: 'review-changes',
+    description: 'Review changed files across dimensions, verify each finding',
+    phases: [{ title: 'Review' }, { title: 'Verify' }],
+  }
+  const DIMENSIONS = [{key: 'bugs', prompt: '...'}, {key: 'perf', prompt: '...'}]
+  const results = await pipeline(
+    DIMENSIONS,
+    d => agent(d.prompt, {label: \`review:\${d.key}\`, phase: 'Review', schema: FINDINGS_SCHEMA}),
+    review => parallel(review.findings.map(f => () =>
+      agent(\`Adversarially verify: \${f.title}\`, {label: \`verify:\${f.file}\`, phase: 'Verify', schema: VERDICT_SCHEMA})
+        .then(v => ({...f, verdict: v}))
+    ))
+  )
+  const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
+  return { confirmed }
+  // Dimension 'bugs' findings verify while dimension 'perf' is still reviewing. No wasted wall-clock.
+
+Before writing a script, load the \`workflow-authoring\` skill — the workflow authoring reference: script API and gotchas, resume, the **Ultracode** section, quality patterns, worked examples.`;
+
+/** The agent count each size keeps a workflow under. */
+export const WORKFLOW_SIZE_AGENTS: Record<Exclude<WorkflowSizeGuideline, "unrestricted">, number> = {
+	small: 5,
+	medium: 10,
+	large: 50,
+};
+
+/** The size-guideline line; undefined when no guideline applies. */
+export function workflowSizeLine(guideline: WorkflowSizeGuideline, configured: boolean): string | undefined {
+	if (guideline === "unrestricted") return undefined;
+	const opening = configured ? "A workflow size guideline is configured for this session" : "This session has the default workflow size guideline";
+	return `${opening}: ${guideline} — keep workflows under ${WORKFLOW_SIZE_AGENTS[guideline]} agents. This is a guideline, not a hard limit — follow it unless the user's prompt calls for a different scale. The user can raise or remove it with \`workflowSizeGuideline\` in ~/.onecode/settings.json.`;
+}
+
+export function workflowDescription(guideline: WorkflowSizeGuideline, configured: boolean): string {
+	const line = workflowSizeLine(guideline, configured);
+	return line ? `${WORKFLOW_DESCRIPTION_BODY}\n\n${line}` : WORKFLOW_DESCRIPTION_BODY;
+}

package/extensions/workflow/globals.ts

@@ -25,7 +25,7 @@ import type {
 	JournalEntry,
 	RunProgressEvent,
 } from "./types.ts";
-import { WorkflowScriptError } from "./types.ts";
+import { keptWorktreeOf, type KeptWorktree, WorkflowScriptError } from "./types.ts";
 import type { ReplayCursor } from "./journal.ts";
 
 export const MAX_AGENTS_PER_RUN = 1000;
@@ -186,6 +186,7 @@ export function createScriptGlobals(options: ScriptGlobalsOptions): { globals: S
 				replayed: true,
 				prompt,
 				preview: previewValue(replayed.value),
+				...keptWorktreeField(replayed.worktreePath, replayed.worktreeBranch),
 			});
 			return replayed.value;
 		}
@@ -216,13 +217,14 @@ export function createScriptGlobals(options: ScriptGlobalsOptions): { globals: S
 					tokens: result.tokens,
 					cost: result.cost,
 					preview: previewValue(result.value),
+					...keptWorktreeField(result.worktreePath, result.worktreeBranch),
 				});
 				return result.value;
 			} catch (error) {
 				if (options.signal.aborted) {
 					// Close the record: the viewer would otherwise show a completed or
 					// stopped run with this agent still "running".
-					options.onEvent({ type: "agentEnd", callIndex, label, phase, text: "aborted" });
+					options.onEvent({ type: "agentEnd", callIndex, label, phase, text: "aborted", ...keptWorktreeField(keptWorktreeOf(error)?.path, keptWorktreeOf(error)?.branch) });
 					throw new WorkflowScriptError("Workflow run was aborted");
 				}
 				// A script-authoring mistake (bad agentType/model, worktree without a
@@ -233,7 +235,14 @@ export function createScriptGlobals(options: ScriptGlobalsOptions): { globals: S
 				if (error instanceof WorkflowScriptError) throw error;
 				// A failed agent resolves to null (Claude Code semantics); the
 				// failure is surfaced as a progress event, not an exception.
-				options.onEvent({ type: "agentEnd", callIndex, label, phase, text: `failed: ${(error as Error).message}` });
+				options.onEvent({
+					type: "agentEnd",
+					callIndex,
+					label,
+					phase,
+					text: `failed: ${(error as Error).message}`,
+					...keptWorktreeField(keptWorktreeOf(error)?.path, keptWorktreeOf(error)?.branch),
+				});
 				return null;
 			}
 		});
@@ -272,3 +281,8 @@ export function createScriptGlobals(options: ScriptGlobalsOptions): { globals: S
 
 	return { globals, state };
 }
+
+/** The `worktree` field of an agentEnd event, present only for a kept worktree. */
+function keptWorktreeField(path: string | undefined, branch: string | undefined): { worktree?: KeptWorktree } {
+	return path ? { worktree: branch ? { path, branch } : { path } } : {};
+}