@visual-z/xeno 0.4.0 → 0.6.0

package/src/apps/startup.ts

@@ -39,6 +39,7 @@ import type { Settings } from "../core/settings.ts";
 import { readModelSources, readCatalogCacheText, writeCatalogCache, catalogCachePath } from "../store/models.ts";
 import { refreshRemoteCatalog } from "../runtime/models-fetch.ts";
 import { readCursor, writeCursor, type Cursor } from "../store/log.ts";
+import { getBlob } from "../store/blobs.ts";
 import { resolveLogDir, findSessionByPrefix, listSessions, sessionsDir, type ResolveLogOpts } from "../store/sessions.ts";
 import { recoverCut } from "../store/recovery.ts";
 import { planSessionEntry, restoreSessionModel } from "../core/session-entry.ts";
@@ -63,6 +64,13 @@ import {
 import { colorEnabled, createPalette, describeError, stdinIsTty, stdoutIsTty, type Palette } from "./render.ts";
 import { type ActionId, type Keymap } from "../core/keymap.ts";
 import type { StartupInput } from "./startup-input.ts";
+import { FoundationRuntime } from "../runtime/foundation.ts";
+import { readFoundationConfig, readOutputSchema } from "../store/foundation-config.ts";
+import { outputValidator } from "../runtime/output-schema.ts";
+import { loadAgentProfileLayers } from "../runtime/agent-profiles.ts";
+import { resolveAgentProfile, builtinAgentProfileLayer, type ResolvedAgentProfile } from "../core/agent-profile.ts";
+import { workflowToolNames, workflowInstructions, isWorkflowMode, type WorkflowMode } from "../core/workflow-mode.ts";
+import { resolveContextWorkspace } from "../store/context-files.ts";
 
 export const SYSTEM_PROMPT = systemPromptFor(TOOL_SCHEMAS.map((tool) => tool.name));
 
@@ -126,6 +134,15 @@ export type AskSlot = {
 };
 
 export interface Args {
+  agentBase?: { model: string; provider: string; thinking: string; maxTurns: number; excludeTools: string[]; noTools: boolean; noBuiltinTools: boolean;
+    tools?: string[]; toolProfile?: ToolProfile; timeBudgetMs?: number; workflow?: WorkflowMode };
+  clientMcp?: import("../core/mcp-config.ts").McpServers;
+  workflow?: WorkflowMode;
+  agent?: string;
+  outputSchema?: string;
+  outputLastMessage?: string;
+  cliFlags?: readonly string[];
+  role?: ResolvedAgentProfile;
   shellCheckpoints?: boolean;
   workspace: string;
   /**
@@ -155,6 +172,7 @@ export interface Args {
   modelSearch?: string;
   help?: boolean;
   version?: boolean;
+  manualUpdateCheck?: boolean;
   exportFile?: string;
   offline?: boolean;
   tuiMode?: "regular" | "fullscreen";
@@ -177,6 +195,8 @@ export interface Args {
   /** `--no-builtin-tools`. False when the flag was not passed. */
   noBuiltinTools: boolean;
   allowTools: string[];
+  /** `--yolo` / `-y`: skip tool approval for this process only. */
+  yolo: boolean;
   /** `--approve` true, `--no-approve` false. Omitted when neither. */
   approve?: boolean;
   configCommand?: boolean;
@@ -231,14 +251,15 @@ export interface Args {
 }
 
 /**
- * Names `parseArgs` actually accepts. `--refresh` is not here: it is only
- * valid after the `models` subcommand, and listing it would make a top-level
+ * Names `parseArgs` actually accepts. Subcommand-only `--refresh` and
+ * `--check` are not here; listing them would make a top-level
  * `--refresh` suggest itself while still being rejected.
  *
  * Keep in sync with the branches in `parseArgs`. A missing entry still
  * parses; it just cannot be offered as a suggestion.
  */
 const KNOWN_FLAGS: readonly string[] = [
+  "--workflow", "--agent", "--output-schema", "--output-last-message",
   "--checkpoint-shell",
   "--workspace", "-w",
   "--path-root",
@@ -271,6 +292,7 @@ const KNOWN_FLAGS: readonly string[] = [
   "--no-tools", "-nt",
   "--no-builtin-tools",
   "--allow-tools",
+  "--yolo", "-y",
   "--approve", "-a",
   "--no-approve", "-na",
   "--theme",
@@ -334,7 +356,9 @@ function rejectUnknownFlag(flag: string): never {
 
 export function parseArgs(argv: string[], options: { deferExtensions?: boolean; flags?: ReadonlyMap<string, ExtensionFlag> } = {}): Args {
   let selectedTheme: string | undefined;
+  let updateExtensions = false;
   const args: Args = {
+    cliFlags: argv.filter(value => value.startsWith("-")),
     workspace: process.cwd(), logDir: "", maxTurns: 40, prompt: "",
     // Overridable so a node boundary can be forced in a short session --
     // otherwise cutting is only reachable after tens of thousands of tokens,
@@ -343,7 +367,7 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
     model: "", provider: "", apiKey: "", listModels: false, modelsCommand: false, modelsRefresh: false, fresh: false,
     noContextFiles: false, appendSystemPrompt: [],
     systemPrompt: null,
-    excludeTools: [], noTools: false, noBuiltinTools: false, allowTools: [],
+    excludeTools: [], noTools: false, noBuiltinTools: false, allowTools: [], yolo: false,
     print: false,
     theme: "",
     thinking: "",
@@ -359,7 +383,10 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
       console.error(`${a} requires a value`);
       process.exit(1);
     }
-    if (a === "--checkpoint-shell") args.shellCheckpoints = true;
+    if (a === "--workflow") { const mode = argv[++i]; if (!mode || !isWorkflowMode(mode)) throw Error("--workflow requires build or plan"); args.workflow = mode; }
+    else if (a === "--agent") { const name = argv[++i]; if (!name || name.startsWith("-")) throw Error("--agent requires a profile name"); args.agent = name; }
+    else if (a === "--output-schema" || a === "--output-last-message") { const path = argv[++i]; if (!path || path.startsWith("-")) throw Error(`${a} requires a file path`); if (a === "--output-schema") args.outputSchema = resolve(path); else args.outputLastMessage = resolve(path); }
+    else if (a === "--checkpoint-shell") args.shellCheckpoints = true;
     else if (a === "--workspace" || a === "-w") args.workspace = argv[++i] ?? args.workspace;
     else if (a === "--path-root") args.pathRoot = resolve(argv[++i] ?? "/");
     else if (a === "--state-dir") args.stateDir = resolve(argv[++i] ?? ".");
@@ -395,7 +422,8 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
     else if (a === "config" && i === 0) args.configCommand = true;
     else if ((a === "install" || a === "remove" || a === "update" || a === "list") && i === 0) args.packageCommand = {operation:a,sources:[]};
     else if ((a === "--local" || a === "-l") && (args.packageCommand || args.configCommand)) { args.local=true; if(args.packageCommand)args.packageCommand.local=true; }
-    else if (a === "--extensions" && args.packageCommand?.operation === "update") { /* Package-only update; xeno never self-updates. */ }
+    else if (a === "--extensions" && args.packageCommand?.operation === "update") updateExtensions = true;
+    else if (a === "--check" && args.packageCommand?.operation === "update") args.manualUpdateCheck = true;
     else if (a === "--refresh" && args.modelsCommand) {
       args.modelsRefresh = true;
     }
@@ -421,13 +449,14 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
     }
     else if (a === "--tool-profile") {
       const value = argv[++i] ?? "";
-      if (!isToolProfile(value)) throw new Error("unknown tool profile; choose coding, readonly, research, data or full");
+      if (!isToolProfile(value)) throw new Error("unknown tool profile; choose coding, readonly, research, data, foundation or full");
       args.toolProfile = value;
     }
     else if (a === "--exclude-tools" || a === "-xt") args.excludeTools = parseToolList(argv[++i] ?? "");
     else if (a === "--no-tools" || a === "-nt") args.noTools = true;
     else if (a === "--no-builtin-tools" || a === "-nbt") args.noBuiltinTools = true;
     else if (a === "--allow-tools") args.allowTools = parseToolList(argv[++i] ?? "");
+    else if (a === "--yolo" || a === "-y") args.yolo = true;
     else if (a === "--approve" || a === "-a") args.approve = true;
     else if (a === "--no-approve" || a === "-na") args.approve = false;
     else if (a === "--theme") {
@@ -492,6 +521,9 @@ export function parseArgs(argv: string[], options: { deferExtensions?: boolean;
     else args.prompt += (args.prompt ? " " : "") + a;
   }
   if (selectedTheme !== undefined) args.theme = selectedTheme;
+  if (args.manualUpdateCheck && (args.packageCommand!.sources.length || args.local || updateExtensions || args.prompt)) {
+    throw new Error("update --check cannot be combined with package sources, --local, or --extensions");
+  }
   return args;
 }
 
@@ -714,6 +746,7 @@ export interface AppIO {
 }
 
 export interface App {
+  foundation?: FoundationRuntime;
   args: Args;
   session: Session;
   workspace: string;
@@ -843,6 +876,11 @@ export function toolSelectionOf(args: Args) {
   };
 }
 
+export function processPermissionRules(args: Args, foundation?: FoundationRuntime, hostRules?: readonly PermissionRule[]): PermissionRule[] {
+  const configured = [...args.role?.profile.permissions ?? [], ...foundation?.permissions ?? []];
+  return [...(args.yolo ? configured.filter(rule => rule.action === "deny") : configured), ...(hostRules ?? rulesWithAllowTools(args.allowTools, { yolo: args.yolo }))];
+}
+
 /**
  * Schema assembly: every tool is tagged with a source here so
  * `--no-builtin-tools` can drop a category without a later cross-layer
@@ -853,10 +891,16 @@ export function toolSelectionOf(args: Args) {
  * the provider bills, and an extra field there would look like a tool
  * argument.
  */
-export function sessionToolCatalog(args: Args, extensions?: ExtensionRegistry, previous: readonly unknown[] = []) {
-  const custom = [...extensions?.definitions().values() ?? []].map(({ name, description, input_schema }) => ({ name, description, input_schema, source: "extension" as const }));
-  const available = [...TOOL_DEFINITIONS.filter(tool => !extensions?.tools.has(tool.name) && (!tool.optional || args.tools?.includes(tool.name))).map((t) => ({ ...t, source: "builtin" as const })), ...custom];
-  const selected = selectTools(available, toolSelectionOf(args));
+export function sessionToolCatalog(args: Args, extensions?: ExtensionRegistry, previous: readonly unknown[] = [], builtinDefaults?: readonly string[]) {
+  const custom = [...extensions?.definitions().values() ?? []].map(tool => ({ ...tool, source: extensions?.builtinTools.has(tool.name) ? "builtin" as const : "extension" as const }));
+  // O.7/D6: a cold app open uses saved capabilities as defaults, never today's profile.
+  // Explicit selection still wins; extension loading and current exclusions remain live.
+  const retained = builtinDefaults !== undefined && args.tools === undefined && args.toolProfile === undefined ? new Set(builtinDefaults) : undefined;
+  const available = [...TOOL_DEFINITIONS.filter(tool => !extensions?.tools.has(tool.name) &&
+    (retained === undefined ? !tool.optional || args.tools?.includes(tool.name) : retained.has(tool.name))).map((t) => ({ ...t, source: "builtin" as const })),
+    ...custom.filter(tool => tool.source !== "builtin" || retained === undefined || retained.has(tool.name))];
+  const admitted = new Set(workflowToolNames(available, args.workflow ?? "build"));
+  const selected = selectTools(available, { ...toolSelectionOf(args), ...(retained ? { profile: "full" as const } : {}) }).filter(tool => admitted.has(tool.name));
   const deferred = selected.filter(tool => tool.source === "extension" && extensions?.tools.get(tool.name)?.exposure === "deferred")
     .map(({ name, description, input_schema }) => ({ name, description, input_schema }));
   const deferredNames = new Set(deferred.map(tool => tool.name));
@@ -896,6 +940,7 @@ export function createSessionFor(opts: {
   oauth?: boolean;
   effects?: ResolveEffects;
   extensions?: ExtensionRegistry;
+  foundation?: FoundationRuntime;
   acceptanceContract?: AcceptanceContract;
   skills?: readonly Skill[];
 }): Session {
@@ -906,10 +951,14 @@ export function createSessionFor(opts: {
   const tools: ToolContext = {
     root: workspace,
     ...DEFAULT_TOOL_CONTEXT,
+    workflowMode: args.workflow ?? "build",
+    appOwnsPermissions: true,
+    ...(opts.foundation ? { questionSlot: opts.foundation.questionSlot,
+      instructionCheck: (ctx: ToolContext, name: string, input: unknown) => opts.foundation!.instructions(ctx, name, input, args.noContextFiles) } : {}),
     ...(args.pathRoot === undefined ? {} : { pathRoot: args.pathRoot }),
     allow: names,
     deferredTools: deferred,
-    rules: rulesWithAllowTools(args.allowTools),
+    rules: processPermissionRules(args, opts.foundation),
     sessionRules,
     askSlot,
     ...(opts.extensions ? { extensions: opts.extensions.definitions(), extensionHooks: opts.extensions.toolHooks() } : {}),
@@ -922,6 +971,7 @@ export function createSessionFor(opts: {
       shellCheckpoints: args.shellCheckpoints === true,
       tools,
       maxTurns: args.maxTurns,
+      ...(args.agent ? { agentProfile: { name: args.agent, workflowExplicit: args.cliFlags?.includes("--workflow") === true } } : {}),
       ...cliSessionConfig(args),
       ...(opts.skills ? { skills: opts.skills } : {}),
       ...(opts.acceptanceContract ? { acceptanceContract: opts.acceptanceContract } : {}),
@@ -983,14 +1033,44 @@ async function prepareExtensionPackages(args: Args, workspace: string): Promise<
   args.extensionPaths=(args.extensionPaths??[]).filter(path=>!remote.includes(path));
 }
 
-export async function loadSessionResources(args: Args, workspace: string, io: AppIO, trustOverride?: boolean): Promise<{
-  loadedContext: LoadedContext; slash: SlashCatalog; ui: UiState; index: ResourceIndex; trusted: boolean; system: string; extensions: ExtensionRegistry;
+export async function loadSessionResources(args: Args, workspace: string, io: AppIO, trustOverride?: boolean, questionSlot?: import("../runtime/question-tool.ts").QuestionSlot): Promise<{
+  loadedContext: LoadedContext; slash: SlashCatalog; ui: UiState; index: ResourceIndex; trusted: boolean; system: string; extensions: ExtensionRegistry; foundation: FoundationRuntime;
 }> {
   const { trusted } = await projectTrust(workspace, trustOverride ?? args.approve);
+  const profiles = await loadAgentProfileLayers({ workspace, trustProject: trusted });
+  for (const diagnostic of profiles.diagnostics) io.say(diagnostic);
+  if (args.agent) {
+    if (!args.agentBase) args.agentBase = { model: args.model, provider: args.provider, thinking: args.thinking ?? "", maxTurns: args.maxTurns, excludeTools: [...args.excludeTools], noTools: args.noTools, noBuiltinTools: args.noBuiltinTools,
+      ...(args.tools ? { tools: [...args.tools] } : {}), ...(args.toolProfile ? { toolProfile: args.toolProfile } : {}), ...(args.timeBudgetMs ? { timeBudgetMs: args.timeBudgetMs } : {}), ...(args.workflow ? { workflow: args.workflow } : {}) };
+    const explicitWorkflow = args.cliFlags?.includes("--workflow") ? args.workflow : undefined;
+    delete args.tools; delete args.toolProfile; delete args.timeBudgetMs; delete args.workflow;
+    Object.assign(args, args.agentBase);
+    if (explicitWorkflow) args.workflow = explicitWorkflow;
+    if (profiles.diagnostics.length) throw Error("Agent profile configuration is invalid; fix the reported file before selecting a role");
+    const role = resolveAgentProfile(args.agent, [builtinAgentProfileLayer(), ...profiles.layers]);
+    if (!role) throw Error(`Unknown agent profile: ${args.agent}`);
+    args.role = role;
+    const profile = role.profile, explicit = (name: string) => args.cliFlags?.includes(name) === true;
+    if (profile.mode && !explicit("--workflow")) args.workflow = profile.mode;
+    if (profile.model) { if (!explicit("--model") && !explicit("-m")) args.model = profile.model.id; if (!explicit("--provider")) args.provider = profile.model.provider; if (profile.model.thinking && !explicit("--thinking")) args.thinking = profile.model.thinking; }
+    if (profile.tools?.profile && !explicit("--tool-profile")) args.toolProfile = profile.tools.profile;
+    if (profile.tools?.only && !explicit("--tools") && !explicit("-t")) args.tools = [...profile.tools.only];
+    if (profile.tools?.exclude && !explicit("--exclude-tools") && !explicit("-xt")) args.excludeTools = [...profile.tools.exclude];
+    if (profile.tools?.none !== undefined && !explicit("--no-tools")) args.noTools = profile.tools.none;
+    if (profile.tools?.noBuiltin !== undefined && !explicit("--no-builtin-tools")) args.noBuiltinTools = profile.tools.noBuiltin;
+    if (profile.budget?.maxTurns && !explicit("--max-turns")) args.maxTurns = profile.budget.maxTurns;
+    if (profile.budget?.timeBudgetMs && !explicit("--time-budget")) args.timeBudgetMs = profile.budget.timeBudgetMs;
+  }
+  const foundationConfig = await readFoundationConfig(configDir(), workspace, trusted);
+  if (args.clientMcp) { const { parseMcpServers } = await import("../core/mcp-config.ts"); foundationConfig["mcp"] = { ...parseMcpServers(foundationConfig["mcp"]), ...args.clientMcp }; }
+  const foundation = new FoundationRuntime(workspace, foundationConfig, args.offline === true || process.env["XENO_OFFLINE"] === "1", configDir(), questionSlot);
   await prepareExtensionPackages(args,workspace);
   const index = await discoverResources({ ...args, workspace, trusted });
   const extensions = new ExtensionRegistry({ reserved: COMMANDS.map(command => command.name), reservedFlags: KNOWN_FLAGS.map(flag => flag.replace(/^-+/, "")),
     flagValue: (name, definition) => args.extensionFlags && Object.hasOwn(args.extensionFlags, name) ? args.extensionFlags[name] : extensionFlagValue(name, definition, args.extensionInputs && Object.hasOwn(args.extensionInputs, name) ? args.extensionInputs[name] : undefined), report: io.say });
+  extensions.own(() => foundation.dispose());
+  try {
+  await foundation.register(extensions);
   await extensions.load(index);
   if(args.extensionArgv) {
     const validated = parseArgs(args.extensionArgv, { flags: extensions.flags, ...(args.help ? { deferExtensions: true } : {}) });
@@ -998,7 +1078,8 @@ export async function loadSessionResources(args: Args, workspace: string, io: Ap
     args.prompt = validated.prompt; args.extensionFlags = validated.extensionFlags ?? {};
   }
   const loaded = await loadUiResources({ ...args, workspace, trusted, ...(args.theme ? { theme: args.theme } : {}) }, index);
-  const loadedContext = await loadContext({ workspace, cwd: workspace, configDir: configDir(),
+  const instructionRoot = await resolveContextWorkspace(workspace);
+  const loadedContext = await loadContext({ workspace: instructionRoot, cwd: workspace, configDir: configDir(),
     noContextFiles: args.noContextFiles, appendSystemPrompt: args.appendSystemPrompt,
     ...(args.systemPrompt === null ? {} : { systemPrompt: args.systemPrompt }) });
   for (const notice of loadedContext.notices) if (notice.kind === "skipped" || notice.truncated) io.say(io.palette.yellow(formatNotice(notice)));
@@ -1006,11 +1087,13 @@ export async function loadSessionResources(args: Args, workspace: string, io: Ap
     noPromptTemplates: args.noPromptTemplates, skillPaths: args.skillPaths, promptTemplatePaths: args.promptTemplatePaths }, index);
   const slash = resolveSlashCatalog(text.prompts, text.skills);
   for (const line of new Set([...loaded.diagnostics, ...text.diagnostics, ...slash.diagnostics])) io.say(io.palette.yellow(`  ${line}`));
-  const system = appendSkillsToSystem(assembleSystemPrompt(systemPromptFor(visibleSchemas(args, extensions).map(tool => tool.name), sessionEnvironment(workspace)), loadedContext), text.skills);
+  const system = appendSkillsToSystem(assembleSystemPrompt([systemPromptFor(visibleSchemas(args, extensions).map(tool => tool.name), sessionEnvironment(workspace)), workflowInstructions(args.workflow ?? "build"), args.role?.profile.instructions ?? "",
+    ...(args.outputSchema ? ["Return the final answer as JSON matching this schema. Do not use Markdown fences:\n" + JSON.stringify(await readOutputSchema(args.outputSchema))] : [])].filter(Boolean).join("\n\n"), loadedContext), text.skills);
   const ui = toUiState(loaded, colorEnabled());
   // Also reached on /resume and /reload: `auto` is resolved once per process by the Tui (apps/shell.ts), not here.
   if (args.tuiMode) ui.settings = { ...ui.settings, tuiMode: args.tuiMode };
-  return { loadedContext, slash: { ...slash.catalog, skillExecution: true, skillCommands: loaded.settings.enableSkillCommands !== false }, ui, index, trusted, system, extensions };
+  return { loadedContext, slash: { ...slash.catalog, skillExecution: true, skillCommands: loaded.settings.enableSkillCommands !== false }, ui, index, trusted, system, extensions, foundation };
+  } catch (error) { await extensions.dispose().catch(() => {}); throw error; }
 }
 
 /**
@@ -1022,24 +1105,56 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
   session: Session; priorCursor: Cursor | null; providerConfig: ProviderConfig; credential: Resolved;
   workspace: string; blobDir: string; system: string; resources: Awaited<ReturnType<typeof loadSessionResources>>;
 }> {
+  const resourceSelector = () => JSON.stringify([opts.args.agent, opts.args.workflow, opts.args.toolProfile, opts.args.cliFlags]);
+  const preparedSelector = resourceSelector();
   opts.startupPhase?.("Reading session history");
   const recorded = await readCursor(opts.logDir);
   const priorCursor = recorded === null ? null : await recoverCut(opts.logDir, recorded);
+  // A durable selector restores intent, while current trusted files supply code
+  // and permission authority. Missing/revoked project roles fail by name.
+  if (priorCursor?.context_ref) {
+    const savedContext = await getBlob(join(opts.logDir, "artifacts"), priorCursor.context_ref);
+    if (!savedContext) throw Error("missing frozen session context");
+    const metadata: unknown = JSON.parse(savedContext);
+    if (metadata && typeof metadata === "object") {
+      if (!("agentProfile" in metadata) && !opts.args.cliFlags?.includes("--workflow") && "workflowMode" in metadata) {
+        if (metadata.workflowMode !== "build" && metadata.workflowMode !== "plan") throw Error("unsupported saved workflow mode");
+        opts.args.workflow = metadata.workflowMode;
+      }
+      if ("workflowToolProfile" in metadata && metadata.workflowToolProfile !== undefined) {
+        if (metadata.workflowToolProfile !== "foundation") throw Error("unsupported saved workflow tool profile");
+        if (!opts.args.cliFlags?.some(flag => ["--tool-profile", "--tools", "-t", "--no-tools", "--no-builtin-tools"].includes(flag))) opts.args.toolProfile = "foundation";
+      }
+    }
+    if (metadata && typeof metadata === "object" && "agentProfile" in metadata && metadata.agentProfile !== undefined) {
+      const role = metadata.agentProfile;
+      if (!role || typeof role !== "object" || !("name" in role) || typeof role.name !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(role.name) || !("workflowExplicit" in role) || typeof role.workflowExplicit !== "boolean") throw Error("unsupported saved agent profile selector");
+      if (!opts.args.cliFlags?.includes("--agent")) opts.args.agent = role.name;
+      if (role.workflowExplicit && !opts.args.cliFlags?.includes("--workflow") && "workflowMode" in metadata) {
+        if (metadata.workflowMode !== "build" && metadata.workflowMode !== "plan") throw Error("unsupported saved workflow mode");
+        opts.args.workflow = metadata.workflowMode; opts.args.cliFlags = [...opts.args.cliFlags ?? [], "--workflow"];
+      }
+    }
+  }
   const workspace = priorCursor?.workspace ?? opts.workspace;
   if (opts.args.pathRoot) {
     const rel = relative(opts.args.pathRoot, workspace);
     if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error("saved workspace is outside --path-root");
   }
-  if (opts.preparedResources && opts.preparedResources.workspace !== workspace) await opts.preparedResources.value.extensions.dispose();
+  const reusePrepared = opts.preparedResources?.workspace === workspace && preparedSelector === resourceSelector();
+  if (opts.preparedResources && !reusePrepared) await opts.preparedResources.value.extensions.dispose();
   opts.startupPhase?.("Loading session resources");
-  const resources = opts.preparedResources?.workspace === workspace ? opts.preparedResources.value
+  const resources = opts.preparedResources && reusePrepared ? opts.preparedResources.value
     : await loadSessionResources(opts.args, workspace, opts.io, workspace === opts.workspace ? opts.projectTrusted : undefined);
+  let openedSession: Session | undefined;
+  try {
   const interactive = opts.interactive && !opts.args.print && !opts.args.prompt && opts.args.mode !== "json";
   const named = [...opts.args.tools ?? [], ...opts.args.excludeTools, ...opts.args.allowTools];
   const unknown = unknownToolNames(named).filter(name => !resources.extensions.definitions().has(name));
   if (unknown.length) throw new Error(`unknown tool: ${unknown.join(", ")}`);
   const saved = priorCursor === null ? undefined : restoreSessionModel(priorCursor, opts.catalog);
   const flags = { ...opts.modelFlags ?? { model: "", provider: "" } };
+  if (opts.args.agent) { flags.model = opts.args.model; flags.provider = opts.args.provider; }
   const parsedModel = flags.model ? scopedModels([flags.model], flags.provider ? opts.catalog.filter(model => model.provider === flags.provider) : opts.catalog, true).entries[0] : undefined;
   if (parsedModel) flags.model = modelKey(parsedModel.model);
   const explicit = flags.model.length > 0 || flags.provider.length > 0;
@@ -1085,6 +1200,7 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
     ...opts,
     system: resources.system,
     extensions: resources.extensions,
+    foundation: resources.foundation,
     skills: [...resources.slash.skills.values()],
     ...(acceptanceContract ? { acceptanceContract } : {}),
     workspace: priorCursor?.workspace ?? opts.workspace,
@@ -1094,13 +1210,32 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
     credential: restoringCredential,
     ...(oauth(restoring, restoringCredential) ? { oauth: true } : {}),
   });
+  openedSession = session;
   opts.startupPhase?.("Opening session history");
   await session.start();
+  const requestedWorkflow = opts.args.workflow;
+  if (requestedWorkflow === undefined && session.config.tools.workflowMode) opts.args.workflow = session.config.tools.workflowMode;
+  if (opts.args.outputSchema) session.config.validateOutput = outputValidator(await readOutputSchema(opts.args.outputSchema));
   resources.slash = { ...resources.slash, skills: new Map((session.config.skills ?? []).map(skill => [skill.name, skill])) };
-  if (resources.extensions.loaded.length || session.config.frozen.tools.some(tool =>
-    typeof tool === "object" && tool !== null && "name" in tool && typeof tool.name === "string" && unknownToolNames([tool.name]).length)) {
-    await session.reloadResources({ system: resources.system, tools: visibleSchemas(opts.args, resources.extensions, session.config.frozen.tools) });
+  const restoredTools = sessionToolCatalog(opts.args, resources.extensions, session.config.frozen.tools,
+    priorCursor === null ? undefined : declaredToolNames(session.config.frozen.tools));
+  const refreshResources = opts.args.agent !== undefined || opts.args.outputSchema !== undefined || opts.args.cliFlags?.includes("--workflow") === true || resources.extensions.loaded.length > 0 || session.config.frozen.tools.some(tool =>
+    typeof tool === "object" && tool !== null && "name" in tool && typeof tool.name === "string" && unknownToolNames([tool.name]).length);
+  const explicitTools = requestedWorkflow !== undefined || opts.args.agent !== undefined || opts.args.tools !== undefined || opts.args.toolProfile !== undefined || opts.args.noTools ||
+    opts.args.noBuiltinTools || opts.args.excludeTools.length > 0;
+  const previousMode = session.config.tools.workflowMode, previousProfile = session.config.agentProfile, previousScope = session.config.workflowToolProfile;
+  session.config.tools.workflowMode = opts.args.workflow ?? "build";
+  if (opts.args.agent) session.config.agentProfile = { name: opts.args.agent, workflowExplicit: opts.args.cliFlags?.includes("--workflow") === true };
+  if (opts.args.toolProfile === "foundation") session.config.workflowToolProfile = "foundation"; else delete session.config.workflowToolProfile;
+  const metadataChanged = previousMode !== session.config.tools.workflowMode || JSON.stringify(previousProfile) !== JSON.stringify(session.config.agentProfile) || previousScope !== session.config.workflowToolProfile;
+  if (refreshResources || (priorCursor !== null && (explicitTools || metadataChanged))) {
+    await session.reloadResources({ system: refreshResources ? resources.system : session.config.frozen.system, tools: restoredTools.schemas }, undefined, undefined, metadataChanged);
   }
+  // Admission follows this app's selected declaration; current process approval rules stay intact.
+  // Keep this out of Session.start(): an SDK caller can intentionally supply a narrower allowlist.
+  session.config.tools.allow = declaredToolNames(session.config.frozen.tools);
+  session.config.tools.workflowMode = opts.args.workflow ?? "build";
+  session.config.tools.deferredTools = restoredTools.deferred;
   if (restoring.id !== spec.id || restoring.provider !== spec.provider) {
     await session.switchModel(createProvider(providerConfig, credential.ok ? credential.key : "", retryHandler(opts.io),
       { sessionId: providerSessionId(session.config.logDir), ...(oauth(spec, credential) ? { oauth: true } : {}), ...(opts.effects ? { effects: opts.effects } : {}) }));
@@ -1111,6 +1246,11 @@ export async function openSessionFor(opts: OpenSessionOptions): Promise<{
   if (resources.ui.settings.scopedModels) for (const warning of scopedModels(resources.ui.settings.scopedModels, opts.catalog).diagnostics) opts.io.say(`  ${warning}`);
   return { session, priorCursor, providerConfig, credential, workspace: session.config.tools.root,
     blobDir: session.config.blobDir ?? opts.blobDir, system: session.config.frozen.system, resources };
+  } catch (error) {
+    await openedSession?.dispose().catch(() => {});
+    await resources.extensions.dispose().catch(() => {});
+    throw error;
+  }
 }
 
 export async function startup(args: Args, input?: StartupInput): Promise<App> {
@@ -1348,6 +1488,7 @@ export async function startup(args: Args, input?: StartupInput): Promise<App> {
     auth, effects, loadedContext: opened.resources.loadedContext, credentialOf, catalog, io, askSlot,
     ui: opened.resources.ui, slash: opened.resources.slash, resources: opened.resources.index, projectTrusted: opened.resources.trusted,
     extensions: opened.resources.extensions,
+    foundation: opened.resources.foundation,
   };
 }
 
@@ -1447,15 +1588,18 @@ export function printCliHelp(flags?: ReadonlyMap<string, ExtensionFlag>): void {
           "            [-n|--name name] [--session-id id] [--version|-v]\n" +
           "            [models --refresh]\n" +
           "            [install|remove <source>... [--local]] [update [source] [--extensions]] [list]\n" +
+          "            [update --check]  Check for a newer xeno without installing\n" +
           "            [config [--local]] [--export session [output.html]] [--offline]\n" +
           "            [--system-prompt <text-or-file>] [--append-system-prompt <text>]\n" +
           "            [--no-context-files|-nc]\n" +
           "            [--tools names] [--exclude-tools names] [--no-tools]\n" +
-          "            [--tool-profile coding|readonly|research|data|full]\n" +
+          "            [--tool-profile coding|readonly|research|data|foundation|full]\n" +
+          "            [--workflow build|plan] [--agent name]\n" +
+          "            [--output-schema schema.json] [--output-last-message file]\n" +
           "            [--acceptance-file contract.json]\n" +
           "            [--control-socket /private/directory/control.sock]\n" +
           "            [--no-builtin-tools]\n" +
-          "            [--allow-tools names] [--approve|--no-approve]\n" +
+          "            [--allow-tools names] [--yolo|-y] [--approve|--no-approve]\n" +
           "            [--theme <name|path>] [--use-theme name] [--no-themes] [--thinking level] [--models patterns]\n" +
           "            [--skill <path>] [--no-skills]\n" +
           "            [--prompt-template <path>] [--no-prompt-templates]\n" +
@@ -1464,6 +1608,8 @@ export function printCliHelp(flags?: ReadonlyMap<string, ExtensionFlag>): void {
           "            [-p <prompt>] [prompt...]\n\n" +
           "  xeno app-server [session/model flags] runs the experimental JSONL control interface.\n" +
           "  xeno app-server schema prints its versioned request schema without startup.\n" +
+          "  xeno acp [session/model flags] serves the standard ACP protocol over stdio.\n" +
+          "  xeno review [working|last-turn|branch <base>|commit <ref>] runs an independent read-only review.\n" +
           "  --control-socket attaches local adapters to the same live session as the TUI.\n" +
           "  /control opens goal, progress and context panels; XENO_PROGRAM_STATUS=auto|1|0 controls terminal status.\n\n" +
           "  Starts a new session by default; --fresh is an explicit alias. Nothing is deleted.\n" +
@@ -1479,9 +1625,18 @@ export function printCliHelp(flags?: ReadonlyMap<string, ExtensionFlag>): void {
           "  --system-prompt replaces the built-in instructions (text, or a file that exists).\n" +
           "  --append-system-prompt appends; repeatable. -nc skips AGENTS.md discovery.\n" +
           "  --tools is a strict allowlist; excluded tools leave the schema.\n" +
-          "  New sessions use coding (10 tools); full exposes default built-ins.\n" +
+          "  New sessions keep coding (10 tools); foundation adds the new basic workflows.\n" +
+          "  --agent build|plan selects foundation; full exposes the complete builtin catalog.\n" +
+          "  Plan admits read tools plus note/question; Build admits the selected capability set.\n" +
+          "  /agent selects named profiles from ~/.xeno/agents.json and trusted .xeno/agents.json.\n" +
+          "  foundation.json configures MCP, web search, formatters, LSP and resource permissions.\n" +
+          "  --output-schema validates final JSON without coercion; invalid output exits 1.\n" +
+          "  --output-last-message writes the accepted final answer after the owner completes.\n" +
           "  --no-builtin-tools drops built-ins and keeps any other source; --tools still wins.\n" +
-          "  bash asks before it runs. --allow-tools bash skips the ask for this process.\n" +
+          "  Shell entry points (exec_command, environment, bash, target) ask before they run.\n" +
+          "  --allow-tools exec_command skips asks for that tool for this process.\n" +
+          "  --yolo (-y) skips all tool approvals for this process, including resumed sessions.\n" +
+          "  Tool exclusions and path limits still apply; YOLO does not change project trust.\n" +
           "  --time-budget <seconds> tells the model, once, when 75% of the run's wall-clock budget is used.\n" +
           "  --state-dir <dir> keeps snapshots, observations and sessions out of the workspace.\n" +
           "  --checkpoint-shell enables best-effort Git recovery for command changes; ignored files and external effects are excluded.\n" +