pi-workflow-engine 0.13.0 → 1.1.0

package/.pi/extensions/pi-workflow-engine/src/agent-runner.ts

@@ -9,13 +9,9 @@ import {
   type AgentAttemptResult,
   type AgentReplayPlan,
 } from "./agent-replay.ts";
-import {
-  resolveAgentModel,
-  type ResolvedAgentModel,
-} from "./agent-session.ts";
+import { resolveAgentModel } from "./agent-session.ts";
 import type {
   AgentExecutionOptions,
-  AgentRunTags,
   RunContext,
 } from "./agent-runner-types.ts";
 import type { AgentResumeBaseContext } from "./resume-context.ts";
@@ -33,8 +29,6 @@ export type {
   CreateAgentSession,
   RunContext,
 } from "./agent-runner-types.ts";
-export { resolveAgentModel } from "./agent-session.ts";
-export type { ResolvedAgentModel, ResolvedAgentModelRequest } from "./agent-session.ts";
 
 /**
  * Run one subagent to completion in an isolated in-memory session.
@@ -54,7 +48,6 @@ export async function runAgent(
 
   const label = opts.label ?? "agent";
   const phase = opts.phase ?? "Workflow";
-  const tags: AgentRunTags = { label, phase };
 
   return await rc.perf.time("agent.total_ms", async () => {
     throwIfAborted(rc.signal);
@@ -73,7 +66,7 @@ export async function runAgent(
           const agentRc: RunContext = { ...rc, signal: liveScope.signal };
           throwIfAborted(agentRc.signal);
           if (!isReplayEnabled(replay)) assertWorkflowBudgetAvailable(agentRc.budget);
-          rc.progress.agentStart(opts.phase, label, rowId);
+          rc.progress.agentStart(rowId);
           if (replay.kind === "disabled") {
             rc.progress.log(`${label}: resume disabled for this call (${replay.reason})`);
           }
@@ -92,7 +85,7 @@ export async function runAgent(
                 replay: attemptPlan,
                 label,
                 rowId,
-                tags,
+                phase,
                 admitLiveAgent: liveScope.admit,
               });
             } catch (error) {
@@ -108,23 +101,23 @@ export async function runAgent(
               providerRetries++;
               const delayMs = agentRetryDelayMs(providerRetries);
               rc.progress.log(`${label}: transient provider failure; retry ${providerRetries}/${agentRc.agentRetries} in ${delayMs}ms`);
-              rc.perf.counter("agent.provider_retry", 1, tags);
-              rc.perf.observe("agent.provider_retry_delay_ms", delayMs, tags);
-              attemptPlan = { kind: "off" };
+              rc.perf.counter("agent.provider_retry");
+              rc.perf.observe("agent.provider_retry_delay_ms", delayMs);
+              // Keep the replay plan: the failed attempt recorded nothing, and the restart recaptures identity.
               await agentRc.retryScheduler.sleep(delayMs, agentRc.signal);
               continue;
             }
-            const settlement = await settleAgentAttempt({ rc: agentRc, label, tags, replay: attemptPlan, outcome });
+            const settlement = await settleAgentAttempt({ rc: agentRc, label, outcome });
             if (settlement.kind === "retry-live") {
               attemptPlan = { kind: "off" };
               continue;
             }
-            rc.progress.agentDone(label, rowId);
+            rc.progress.agentDone(rowId);
             return settlement.result;
           }
         },
         {
-          onQueueWaitMs: (durationMs) => rc.perf.observe("agent.queue_wait_ms", durationMs, tags),
+          onQueueWaitMs: (durationMs) => rc.perf.observe("agent.queue_wait_ms", durationMs),
           signal: rc.signal,
         },
       );
@@ -132,13 +125,13 @@ export async function runAgent(
       let failure = error;
       if (liveScope.signal.aborted) failure = abortReason(liveScope.signal);
       if (rc.signal?.aborted) failure = abortReason(rc.signal);
-      rc.progress.agentFailed(label, failure, rowId);
+      rc.progress.agentFailed(rowId, failure);
       rc.progress.log(`${label} failed: ${unknownErrorMessage(failure)}`);
       throw failure;
     } finally {
       liveScope.dispose();
     }
-  }, tags);
+  });
 }
 
 function createAgentLiveScope(rc: RunContext, label: string) {
@@ -169,18 +162,19 @@ function resolveAgentRouting(
   rc: RunContext,
   opts: AgentExecutionOptions,
   label: string,
-): { readonly model: ResolvedAgentModel["model"]; readonly thinkingLevel: AgentExecutionOptions["thinkingLevel"] } {
+): ReturnType<typeof resolveAgentModelProfile> {
   try {
     return resolveAgentModelProfile(
       {
         request: opts,
         profiles: rc.modelProfiles,
-        resolveExplicitModel: (modelRef) => resolveAgentModel(modelRef, rc.modelRegistry, rc.hostModel).model,
+        resolveExplicitModel: (modelRef) => resolveAgentModel(modelRef, rc.modelRegistry),
         hostModel: rc.hostModel,
       },
     );
   } catch (error) {
-    rc.progress.agentFailed(label, error);
+    // Routing runs before the call has a row; give the failure its own so it cannot land on a same-label sibling.
+    rc.progress.agentFailed(rc.progress.agentQueued(opts.phase, label), error);
     throw error;
   }
 }

package/.pi/extensions/pi-workflow-engine/src/agent-session-identity.ts

@@ -6,11 +6,11 @@ import { normalizeWorkspaceReferences } from "./replay-path-identity.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import {
   captureEffectiveToolSourceIdentity,
+  nonEmptyString,
   type EffectiveToolSourceIdentity,
   type EffectiveToolSourceInfoLike,
-  type ToolSourceFingerprintCache,
+  type ToolSourceIdentityOptions,
 } from "./tool-source-identity.ts";
-export type { EffectiveToolSourceIdentity, EffectiveToolSourceInfoLike } from "./tool-source-identity.ts";
 
 export interface EffectiveAgentModelLike {
   readonly provider: string;
@@ -78,14 +78,6 @@ export interface EffectiveAgentSessionIdentityOptions {
   readonly signal?: AbortSignal;
 }
 
-interface IdentityComponents {
-  readonly runtimeVersion: string;
-  readonly systemPromptFingerprint: string;
-  readonly model: EffectiveAgentModelLike;
-  readonly thinkingLevel: string;
-  readonly tools: readonly EffectiveToolIdentity[];
-}
-
 /**
  * Capture the post-creation AgentSession state that determines whether a cached
  * agent result is safe to replay. Any missing or opaque executable identity
@@ -105,7 +97,13 @@ export async function captureEffectiveAgentSessionIdentity(
     const model = captureModel(session.model);
     const activeToolNames = captureActiveToolNames(session.getActiveToolNames());
     const toolInfoByName = indexToolInfo(session.getAllTools());
-    const sourceCaptures: ToolSourceFingerprintCache = new Map();
+    const toolSourceOptions: ToolSourceIdentityOptions = {
+      runtimeVersion,
+      signal: options.signal,
+      sessionCwd,
+      cache: new Map(),
+      workspaceRoot,
+    };
     const tools: EffectiveToolIdentity[] = [];
 
     for (const name of activeToolNames) {
@@ -114,18 +112,10 @@ export async function captureEffectiveAgentSessionIdentity(
       if (!info) throw new Error(`active tool "${name}" is absent from the tool registry`);
       const definition = session.getToolDefinition(name);
       if (!definition) throw new Error(`active tool "${name}" has no executable definition`);
-      tools.push(
-        await captureToolIdentity(name, info, definition, {
-          runtimeVersion,
-          signal: options.signal,
-          sessionCwd,
-          sourceCaptures,
-          workspaceRoot,
-        }),
-      );
+      tools.push(await captureToolIdentity(name, info, definition, toolSourceOptions));
     }
 
-    const components: IdentityComponents = {
+    const components = {
       runtimeVersion,
       systemPromptFingerprint: hashIdentity(
         normalizeWorkspaceReferences(systemPrompt, { sessionCwd, workspaceRoot }),
@@ -147,19 +137,11 @@ export async function captureEffectiveAgentSessionIdentity(
   }
 }
 
-interface ToolCaptureOptions {
-  readonly runtimeVersion: string;
-  readonly sessionCwd: string;
-  readonly workspaceRoot: string;
-  readonly sourceCaptures: ToolSourceFingerprintCache;
-  readonly signal?: AbortSignal;
-}
-
 async function captureToolIdentity(
   name: string,
   info: EffectiveToolInfoLike,
   definition: EffectiveToolDefinitionLike,
-  options: ToolCaptureOptions,
+  options: ToolSourceIdentityOptions,
 ): Promise<EffectiveToolIdentity> {
   if (nonEmptyString(info.name, `registry name for active tool "${name}"`) !== name) {
     throw new Error(`tool registry returned a mismatched definition for "${name}"`);
@@ -175,13 +157,7 @@ async function captureToolIdentity(
     definition.prepareArguments === undefined
       ? null
       : inspectableFunctionSource(definition.prepareArguments, `argument-preparation handler for active tool "${name}"`);
-  const source = await captureEffectiveToolSourceIdentity(info.sourceInfo, {
-    runtimeVersion: options.runtimeVersion,
-    sessionCwd: options.sessionCwd,
-    workspaceRoot: options.workspaceRoot,
-    cache: options.sourceCaptures,
-    signal: options.signal,
-  });
+  const source = await captureEffectiveToolSourceIdentity(info.sourceInfo, options);
 
   return {
     name,
@@ -244,12 +220,6 @@ function optionalString(value: string | undefined, label: string): string | null
   return stringValue(value, label);
 }
 
-function nonEmptyString(value: string, label: string): string {
-  const result = stringValue(value, label);
-  if (result.length === 0) throw new Error(`${label} is empty`);
-  return result;
-}
-
 function stringValue(value: string, label: string): string {
   if (typeof value !== "string") throw new Error(`${label} is not a string`);
   return value;

package/.pi/extensions/pi-workflow-engine/src/agent-session-providers.ts

@@ -8,12 +8,17 @@ type HostProviderRegistry = Pick<
   | "getRegisteredProviderConfig"
   | "getRegisteredProviderIds"
   | "isUsingOAuth"
->;
+> & {
+  /** pi 1.x keeps providers registered as objects (`pi.registerProvider(provider)`) apart from config providers. */
+  getRegisteredNativeProvider?(providerId: string): unknown;
+};
+
+type ChildModelRuntime = ModelRuntime & { registerNativeProvider?(provider: unknown): void };
 
 /** Mirror the host's live provider and selected-model auth state into a child runtime. */
 export async function synchronizeWorkflowModelRuntime(input: {
   readonly host: HostProviderRegistry;
-  readonly child: ModelRuntime;
+  readonly child: ChildModelRuntime;
   readonly selectedModel: Model<Api> | undefined;
   readonly removeChildOnlyProviders: boolean;
 }): Promise<void> {
@@ -28,9 +33,16 @@ export async function synchronizeWorkflowModelRuntime(input: {
 
   for (const providerId of hostProviderIds) {
     const config = host.getRegisteredProviderConfig(providerId);
-    if (!config) continue;
-    child.unregisterProvider(providerId);
-    child.registerProvider(providerId, config);
+    if (config) {
+      child.unregisterProvider(providerId);
+      child.registerProvider(providerId, config);
+      continue;
+    }
+    const native = host.getRegisteredNativeProvider?.(providerId);
+    if (native && child.registerNativeProvider) {
+      child.unregisterProvider(providerId);
+      child.registerNativeProvider(native);
+    }
   }
 
   const selectedProvider = selectedModel?.provider;

package/.pi/extensions/pi-workflow-engine/src/agent-session.ts

@@ -1,10 +1,12 @@
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
 import {
   createAgentSessionFromServices,
   createAgentSessionServices,
+  createCodemodeExtension,
   defineTool,
   SessionManager,
   type CreateAgentSessionOptions,
+  type CreateAgentSessionServicesOptions,
   type ModelRegistry,
   type Skill,
   type ToolDefinition,
@@ -12,7 +14,7 @@ import {
 import { prepareAgentSkillResources } from "./agent-skills.ts";
 import type {
   AgentExecutionOptions,
-  AgentRunTags,
+  AgentProgress,
   AgentRunnerSession,
   RunContext,
 } from "./agent-runner-types.ts";
@@ -23,26 +25,26 @@ import {
 } from "./structured-output.ts";
 import { providerErrorFromMessages } from "./agent-retry.ts";
 import { synchronizeWorkflowModelRuntime } from "./agent-session-providers.ts";
+import { hostToolProxy, isMcpToolName, WorkflowHostToolUnavailableError, type HostToolBridge } from "./host-tools.ts";
 import { matchesAgentToolHint, WorkflowToolHintUnavailableError } from "./tool-capabilities.ts";
-import type { AgentToolHint } from "./types.ts";
+import { parseAgentModelRef } from "./model-ref.ts";
+import { truncateText } from "./text.ts";
+import { WORKFLOW_TOOL_NAME, type AgentToolHint } from "./types.ts";
 
 export const FINAL_TOOL = "final_answer";
+/** pi's codemode tool; SDK sessions only have it when their resource loader registers the extension. */
+export const CODEMODE_TOOL = "codemode";
 
 const SCHEMA_REPROMPT =
   `You ended your turn without calling the ${FINAL_TOOL} tool, so no result was recorded. ` +
   `Call ${FINAL_TOOL} now with your final answer as its arguments. Do not reply with plain text.`;
 const DEFAULT_SEARCH_BASE_TOOLS = ["read", "bash", "grep", "find", "ls"];
-
-export interface ResolvedAgentModelRequest {
-  readonly ref: string;
-  readonly provider: string;
-  readonly id: string;
-}
-
-export interface ResolvedAgentModel {
-  readonly model: Model<Api> | undefined;
-  readonly requested: ResolvedAgentModelRequest | undefined;
-}
+const RETRY_REASON_CHARS = 160;
+const RETRY_DISABLED_WARNING =
+  "pi auto-retry is disabled (retry.enabled: false in pi settings), so subagents will not retry failed provider turns. " +
+  "pi-workflow-engine 0.12.0 and 0.13.0 wrote that setting into ~/.pi/agent/settings.json; remove it unless you disabled retry on purpose.";
+/** Runs (keyed by their shared progress sink) already warned about disabled pi auto-retry. */
+const retryDisabledWarnedRuns = new WeakSet<AgentProgress>();
 
 export interface AgentSessionHandle {
   readonly session: AgentRunnerSession;
@@ -51,19 +53,14 @@ export interface AgentSessionHandle {
   structuredResult(): unknown;
 }
 
-export function resolveAgentModel(
-  modelRef: string | undefined,
-  modelRegistry: Pick<ModelRegistry, "find">,
-  hostModel: Model<Api> | undefined,
-): ResolvedAgentModel {
-  if (modelRef === undefined) return { model: hostModel, requested: undefined };
-
+/** Resolve an explicit `agent({ model })` ref; unknown refs fail instead of falling back to another model. */
+export function resolveAgentModel(modelRef: string, modelRegistry: Pick<ModelRegistry, "find">): Model<Api> {
   const parsed = parseAgentModelRef(modelRef);
   const found = modelRegistry.find(parsed.provider, parsed.id);
   if (!found) {
     throw new Error(`Agent model "${modelRef}" not found (resolved as ${parsed.provider}/${parsed.id}).`);
   }
-  return { model: found, requested: parsed };
+  return found;
 }
 
 export async function openAgentSession(input: {
@@ -73,9 +70,8 @@ export async function openAgentSession(input: {
   readonly cwd: string;
   readonly model: Model<Api> | undefined;
   readonly label: string;
-  readonly tags: AgentRunTags;
 }): Promise<AgentSessionHandle> {
-  const { rc, prompt, opts, cwd, model, label, tags } = input;
+  const { rc, prompt, opts, cwd, model, label } = input;
   let captured = false;
   let structuredResult: unknown;
   const customTools: ToolDefinition[] = opts.schema
@@ -86,6 +82,8 @@ export async function openAgentSession(input: {
           description:
             "Return your final structured answer. This MUST be your last action — do not write a normal reply after calling it.",
           parameters: opts.schema,
+          // The agent's own terminal action: a codemode script must not answer on its behalf.
+          exposure: "model-only",
           async execute(_toolCallId, params) {
             captured = true;
             structuredResult = params;
@@ -94,32 +92,29 @@ export async function openAgentSession(input: {
         }),
       ]
     : [];
+  customTools.push(...requestedHostTools(opts, rc.hostTools));
   let session: AgentRunnerSession | undefined;
   try {
     throwIfAborted(rc.signal);
-    const resourceInput = { rc, prompt, opts, cwd, model, customTools, label };
-    const resources = rc.createSession
-      ? await prepareAgentSessionResources(resourceInput)
-      : await rc.perf.time(
-          "agent.session_resources_ms",
-          () => prepareAgentSessionResources(resourceInput),
-          tags,
-        );
+    const resources = await rc.perf.time(
+      "agent.session_resources_ms",
+      () => prepareAgentSessionResources({ rc, prompt, opts, cwd, model, customTools, label }),
+    );
     const toolSelection = buildToolSelection(opts, resources.selectedSkills.length > 0);
     session = (
       await rc.perf.time(
         "agent.create_session_ms",
         () => resources.createSession(toolSelection.sessionOptions),
-        tags,
       )
     ).session;
-    session.setAutoRetryEnabled(false);
     const matchedToolHints = toolSelection.toolHints.length === 0
       ? new Set<AgentToolHint>()
       : applyDynamicToolHints(session, toolSelection);
+    // A nested run would get its own concurrency cap and budget, so subagents may start one only when allowlisted.
+    if (!opts.tools?.includes(WORKFLOW_TOOL_NAME)) withholdWorkflowTool(session);
     if (opts.requireToolHints) {
       const missing = toolSelection.toolHints.filter((hint) => !matchedToolHints.has(hint));
-      if (missing.length > 0) throw new WorkflowToolHintUnavailableError(missing);
+      if (missing.length > 0) throw new WorkflowToolHintUnavailableError(missing, { hostToolsReachable: rc.hostTools !== undefined });
     }
     throwIfAborted(rc.signal);
     return {
@@ -129,11 +124,8 @@ export async function openAgentSession(input: {
       structuredResult: () => structuredResult,
     };
   } catch (error) {
-    if (session) {
-      const activeSession = session;
-      session = undefined;
-      rc.perf.timeSync("agent.dispose_ms", () => activeSession.dispose(), tags);
-    }
+    const created = session;
+    if (created) rc.perf.timeSync("agent.dispose_ms", () => created.dispose());
     throw error;
   }
 }
@@ -145,87 +137,78 @@ export async function promptAgentSession(input: {
   readonly opts: AgentExecutionOptions;
   readonly label: string;
   readonly rowId: number;
-  readonly tags: AgentRunTags;
+  readonly phase: string;
 }): Promise<unknown> {
-  const { rc, handle, prompt, opts, label, rowId, tags } = input;
+  const { rc, handle, prompt, opts, label, rowId, phase } = input;
   const { session } = handle;
+  throwIfAborted(rc.signal);
+  // pi drops a retried turn's failed message from session.messages; keep it so usage covers every attempt.
+  const retriedFailures: AssistantMessage[] = [];
+  let lastFailure: AssistantMessage | undefined;
   const unsubscribe = session.subscribe((event) => {
-    if (event.type === "tool_execution_start" && event.toolName !== undefined && event.toolName !== FINAL_TOOL) {
-      rc.progress.agentTool(label, event.toolName, rowId);
+    if (event.type === "tool_execution_start" && event.toolName !== FINAL_TOOL) {
+      rc.progress.agentTool(rowId, event.toolName);
+    } else if (event.type === "message_end" && event.message.role === "assistant" && event.message.stopReason === "error") {
+      lastFailure = event.message;
+    } else if (event.type === "auto_retry_start") {
+      if (lastFailure) retriedFailures.push(lastFailure);
+      lastFailure = undefined;
+      const reason = truncateText(event.errorMessage, RETRY_REASON_CHARS);
+      rc.progress.log(
+        `${label}: transient provider failure (${reason}); retrying turn ${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms`,
+      );
+      rc.perf.counter("agent.turn_retry");
     }
   });
+  const unlinkPromptAbort = linkSessionAbort(rc.signal, session);
+  const promptSession = async (text: string) => {
+    await rc.perf.time("agent.prompt_ms", () => raceWithAbort(() => session.prompt(text), rc.signal));
+    const failure = providerErrorFromMessages(session.messages, {
+      pauseOnUsageLimit: rc.pauseOnProviderUsageLimit,
+    });
+    if (failure) throw failure;
+  };
 
   try {
-    const finalPrompt = opts.schema
-      ? `${prompt}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
-      : prompt;
-    throwIfAborted(rc.signal);
-    const unlinkPromptAbort = linkSessionAbort(rc.signal, session);
-    try {
-      try {
-        const promptSession = async (text: string) => {
-          await rc.perf.time("agent.prompt_ms", () => raceWithAbort(() => session.prompt(text), rc.signal), tags);
-          const failure = providerErrorFromMessages(session.messages, {
-            pauseOnUsageLimit: rc.pauseOnProviderUsageLimit,
-          });
-          if (failure) throw failure;
-        };
-        await promptSession(finalPrompt);
-        if (opts.schema) {
-          for (let attempt = 0; !handle.hasStructuredResult() && attempt < MAX_SCHEMA_REPAIR_ATTEMPTS; attempt++) {
-            throwIfAborted(rc.signal);
-            session.setActiveToolsByName([FINAL_TOOL]);
-            rc.progress.log(`${label}: no final answer; re-prompting (${attempt + 1}/${MAX_SCHEMA_REPAIR_ATTEMPTS})`);
-            rc.perf.counter("agent.structured_reprompt", 1, tags);
-            await promptSession(SCHEMA_REPROMPT);
-          }
-        }
-
+    await promptSession(
+      opts.schema ? `${prompt}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.` : prompt,
+    );
+    if (opts.schema && !handle.hasStructuredResult()) {
+      const activeTools = session.getActiveToolNames();
+      for (let attempt = 0; !handle.hasStructuredResult() && attempt < MAX_SCHEMA_REPAIR_ATTEMPTS; attempt++) {
         throwIfAborted(rc.signal);
-        return rc.perf.timeSync(
-          "agent.extract_result_ms",
-          () => {
-            if (!opts.schema) {
-              return session.getLastAssistantText() ?? "";
-            }
-            if (!handle.hasStructuredResult()) {
-              rc.progress.log(`${label}: no structured answer returned`);
-              rc.perf.counter("agent.structured_missing", 1, tags);
-              throw new WorkflowStructuredOutputError(label, MAX_SCHEMA_REPAIR_ATTEMPTS);
-            }
-            return handle.structuredResult();
-          },
-          tags,
-        );
-      } finally {
-        rc.usage.recordAgentSession({ label, phase: tags.phase, messages: session.messages });
+        session.setActiveToolsByName([FINAL_TOOL]);
+        rc.progress.log(`${label}: no final answer; re-prompting (${attempt + 1}/${MAX_SCHEMA_REPAIR_ATTEMPTS})`);
+        rc.perf.counter("agent.structured_reprompt");
+        await promptSession(SCHEMA_REPROMPT);
       }
-    } finally {
-      unlinkPromptAbort();
+      // Narrowing also rebuilds pi's system prompt; restore both so replay validation sees the captured identity.
+      session.setActiveToolsByName(activeTools);
     }
+
+    throwIfAborted(rc.signal);
+    return rc.perf.timeSync(
+      "agent.extract_result_ms",
+      () => {
+        if (!opts.schema) {
+          return session.getLastAssistantText() ?? "";
+        }
+        if (!handle.hasStructuredResult()) {
+          rc.progress.log(`${label}: no structured answer returned`);
+          rc.perf.counter("agent.structured_missing");
+          throw new WorkflowStructuredOutputError(label, MAX_SCHEMA_REPAIR_ATTEMPTS);
+        }
+        return handle.structuredResult();
+      },
+    );
   } finally {
+    // Detach first: recording publishes usage to the UI and must not be able to skip listener cleanup.
+    unlinkPromptAbort();
     unsubscribe();
+    rc.usage.recordAgentSession({ label, phase, messages: [...retriedFailures, ...session.messages] });
   }
 }
 
-function parseAgentModelRef(modelRef: string): ResolvedAgentModelRequest {
-  const normalized = modelRef.trim();
-  if (normalized.length === 0) {
-    throw new Error('Invalid agent model ref: expected a bare model id or "provider/id".');
-  }
-  if (normalized !== modelRef) {
-    throw new Error(`Invalid agent model ref "${modelRef}": remove leading or trailing whitespace.`);
-  }
-
-  const slash = modelRef.indexOf("/");
-  if (slash === -1) return { ref: modelRef, provider: "anthropic", id: modelRef };
-  const provider = modelRef.slice(0, slash);
-  const id = modelRef.slice(slash + 1);
-  if (provider.length === 0 || id.length === 0 || id.startsWith("/")) {
-    throw new Error(`Invalid agent model ref "${modelRef}": expected "provider/id".`);
-  }
-  return { ref: modelRef, provider, id };
-}
 
 interface AgentSessionResources {
   readonly selectedSkills: readonly Skill[];
@@ -270,7 +253,7 @@ async function prepareAgentSessionResources(input: {
   const preparedSkills = prepareAgentSkillResources(skillOptions);
   const services = await createAgentSessionServices({
     cwd,
-    resourceLoaderOptions: preparedSkills.resourceLoaderOptions,
+    resourceLoaderOptions: { ...preparedSkills.resourceLoaderOptions, ...codemodeExtension(opts) },
   });
   await synchronizeWorkflowModelRuntime({
     host: rc.modelRegistry,
@@ -282,6 +265,10 @@ async function prepareAgentSessionResources(input: {
   for (const diagnostic of services.diagnostics) {
     rc.progress.log(`${label}: session ${diagnostic.type}: ${diagnostic.message}`);
   }
+  if (!services.settingsManager.getRetryEnabled() && !retryDisabledWarnedRuns.has(rc.progress)) {
+    retryDisabledWarnedRuns.add(rc.progress);
+    rc.progress.log(RETRY_DISABLED_WARNING);
+  }
   const selectedSkills = preparedSkills.resolve(services.resourceLoader);
   return {
     selectedSkills,
@@ -293,6 +280,36 @@ async function prepareAgentSessionResources(input: {
   };
 }
 
+/**
+ * SDK sessions load none of pi's built-in extensions, so codemode is registered only for agents whose
+ * allowlist names it. Scripts can call just the agent's other allowed tools. Mode "on" keeps those
+ * tools declared whatever the user's `codemode.mode`, so the author's allowlist stays what the model sees.
+ */
+function codemodeExtension(opts: AgentExecutionOptions): Pick<SessionResourceLoaderOptions, "extensionFactories"> {
+  if (!opts.tools?.includes(CODEMODE_TOOL)) return {};
+  return { extensionFactories: [{ name: CODEMODE_TOOL, factory: createCodemodeExtension({ mode: "on" }), replaceable: true }] };
+}
+
+type SessionResourceLoaderOptions = NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>;
+
+/**
+ * Proxies for the host MCP tools this agent asked for: those named in its allowlist, and open-world
+ * research tools when it hints `external-search`. Local `search` hints never bridge, because host tools
+ * run in the host session's working directory, not the agent's (an isolated worktree, for example).
+ * A named tool the run cannot reach fails the agent, like `requireToolHints`, rather than letting it
+ * work without a tool its prompt may rely on.
+ */
+function requestedHostTools(opts: AgentExecutionOptions, bridge: HostToolBridge | undefined): ToolDefinition[] {
+  const named = new Set((opts.tools ?? []).filter(isMcpToolName));
+  const externalSearch = opts.toolHints?.includes("external-search") ?? false;
+  if (named.size === 0 && !externalSearch) return [];
+  const available = bridge?.tools() ?? [];
+  const selected = available.filter((tool) => named.has(tool.name) || (externalSearch && matchesAgentToolHint(tool, "external-search")));
+  const missing = [...named].filter((name) => !selected.some((tool) => tool.name === name));
+  if (missing.length > 0) throw new WorkflowHostToolUnavailableError(missing, bridge !== undefined);
+  return bridge ? selected.map((tool) => hostToolProxy(tool, bridge)) : [];
+}
+
 function linkSessionAbort(signal: AbortSignal | undefined, session: AgentRunnerSession): () => void {
   if (!signal) return () => {};
   const onAbort = () => {
@@ -322,16 +339,8 @@ function buildToolSelection(opts: AgentExecutionOptions, skillsEnabled: boolean)
       ? ["read"]
       : undefined;
   const activeTools = buildToolList(opts, skillsEnabled, fallback);
-  if (toolHints.length === 0) {
-    return {
-      sessionOptions: { tools: activeTools ? [...activeTools] : undefined },
-      activeTools,
-      toolHints,
-    };
-  }
-
   return {
-    sessionOptions: { noTools: "builtin" },
+    sessionOptions: toolHints.length === 0 ? { tools: activeTools } : { noTools: "builtin" },
     activeTools,
     toolHints,
   };
@@ -350,11 +359,16 @@ function buildToolList(
   return allow;
 }
 
+function withholdWorkflowTool(session: AgentRunnerSession): void {
+  const active = session.getActiveToolNames();
+  if (active.includes(WORKFLOW_TOOL_NAME)) session.setActiveToolsByName(active.filter((name) => name !== WORKFLOW_TOOL_NAME));
+}
+
 function applyDynamicToolHints(
   session: AgentRunnerSession,
   selection: ToolSelection,
 ): ReadonlySet<AgentToolHint> {
-  const active = new Set(selection.activeTools ?? []);
+  const active = new Set(selection.activeTools);
   const matched = new Set<AgentToolHint>();
   for (const tool of session.getAllTools()) {
     for (const hint of selection.toolHints) {