pi-workflow-engine 0.11.0 → 0.12.0

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

@@ -1,6 +1,7 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import {
-  createAgentSession,
+  createAgentSessionFromServices,
+  createAgentSessionServices,
   defineTool,
   SessionManager,
   type CreateAgentSessionOptions,
@@ -8,32 +9,28 @@ import {
   type Skill,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import {
-  appendSkillReminder,
-  createAgentSkillResourceLoader,
-  extractSkillSelectorsFromText,
-} from "./agent-skills.ts";
+import { prepareAgentSkillResources } from "./agent-skills.ts";
 import type {
   AgentExecutionOptions,
   AgentRunTags,
   AgentRunnerSession,
-  AgentRunnerToolInfo,
   RunContext,
 } from "./agent-runner-types.ts";
+import { raceWithAbort, throwIfAborted } from "./cancellation.ts";
 import {
-  captureEffectiveAgentSessionIdentity,
-  type EffectiveAgentSessionIdentity,
-  type EffectiveToolInfoLike,
-} from "./agent-session-identity.ts";
-import { throwIfAborted } from "./cancellation.ts";
+  MAX_SCHEMA_REPAIR_ATTEMPTS,
+  WorkflowStructuredOutputError,
+} from "./structured-output.ts";
+import { providerErrorFromMessages } from "./agent-retry.ts";
+import { synchronizeWorkflowModelRuntime } from "./agent-session-providers.ts";
+import { matchesAgentToolHint, WorkflowToolHintUnavailableError } from "./tool-capabilities.ts";
+import type { AgentToolHint } from "./types.ts";
 
 export const FINAL_TOOL = "final_answer";
 
-const SCHEMA_REPROMPT_ATTEMPTS = 1;
 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 BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
 const DEFAULT_SEARCH_BASE_TOOLS = ["read", "bash", "grep", "find", "ls"];
 
 export interface ResolvedAgentModelRequest {
@@ -50,13 +47,10 @@ export interface ResolvedAgentModel {
 export interface AgentSessionHandle {
   readonly session: AgentRunnerSession;
   readonly selectedSkills: readonly Skill[];
+  hasStructuredResult(): boolean;
   structuredResult(): unknown;
 }
 
-export type EffectiveSessionCapture =
-  | { readonly kind: "verified"; readonly identity: EffectiveAgentSessionIdentity }
-  | { readonly kind: "unverifiable"; readonly reason: string };
-
 export function resolveAgentModel(
   modelRef: string | undefined,
   modelRegistry: Pick<ModelRegistry, "find">,
@@ -82,22 +76,8 @@ export async function openAgentSession(input: {
   readonly tags: AgentRunTags;
 }): Promise<AgentSessionHandle> {
   const { rc, prompt, opts, cwd, model, label, tags } = input;
-  const skillSetup = shouldCreateSkillResourceLoader(rc, prompt, opts)
-    ? await rc.perf.time(
-        "agent.skills_ms",
-        () =>
-          createAgentSkillResourceLoader({
-            cwd,
-            prompt,
-            skills: opts.skills,
-            log: (message) => rc.progress.log(`${label}: ${message}`),
-          }),
-        tags,
-      )
-    : undefined;
-  const selectedSkills = skillSetup?.selectedSkills ?? [];
-  const toolSelection = buildToolSelection(opts, selectedSkills.length > 0);
-  let captured: unknown = null;
+  let captured = false;
+  let structuredResult: unknown;
   const customTools: ToolDefinition[] = opts.schema
     ? [
         defineTool({
@@ -107,47 +87,47 @@ export async function openAgentSession(input: {
             "Return your final structured answer. This MUST be your last action — do not write a normal reply after calling it.",
           parameters: opts.schema,
           async execute(_toolCallId, params) {
-            captured = params;
+            captured = true;
+            structuredResult = params;
             return { content: [{ type: "text", text: "Recorded." }], details: params, terminate: true };
           },
         }),
       ]
     : [];
-  const createSessionForRun = rc.createSession ?? defaultCreateSession;
-  const createSubagentSession = (sessionOptions: ToolSessionOptions) =>
-    rc.perf.time(
-      "agent.create_session_ms",
-      () =>
-        createSessionForRun({
-          cwd,
-          model,
-          modelRegistry: rc.modelRegistry as ModelRegistry,
-          thinkingLevel: opts.thinkingLevel,
-          tools: sessionOptions.tools,
-          excludeTools: sessionOptions.excludeTools,
-          customTools,
-          resourceLoader: skillSetup?.resourceLoader,
-          sessionManager: SessionManager.inMemory(cwd),
-        }),
-      tags,
-    );
-
   let session: AgentRunnerSession | undefined;
   try {
     throwIfAborted(rc.signal);
-    session = (await createSubagentSession(toolSelection.sessionOptions)).session;
-    const dynamicToolHintsApplied = toolSelection.toolHints.length === 0 || applyDynamicToolHints(session, toolSelection);
-    if (!dynamicToolHintsApplied) {
-      rc.progress.log(`${label}: dynamic tool hints unavailable; falling back to concrete tools only`);
-      rc.perf.counter("agent.tool_hint_fallback", 1, tags);
-      const dynamicSession = session;
-      session = undefined;
-      rc.perf.timeSync("agent.dispose_ms", () => dynamicSession.dispose(), tags);
-      throwIfAborted(rc.signal);
-      session = (await createSubagentSession(toolSelection.fallbackSessionOptions)).session;
+    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 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);
+    if (opts.requireToolHints) {
+      const missing = toolSelection.toolHints.filter((hint) => !matchedToolHints.has(hint));
+      if (missing.length > 0) throw new WorkflowToolHintUnavailableError(missing);
     }
     throwIfAborted(rc.signal);
-    return { session, selectedSkills, structuredResult: () => captured };
+    return {
+      session,
+      selectedSkills: resources.selectedSkills,
+      hasStructuredResult: () => captured,
+      structuredResult: () => structuredResult,
+    };
   } catch (error) {
     if (session) {
       const activeSession = session;
@@ -168,7 +148,7 @@ export async function promptAgentSession(input: {
   readonly tags: AgentRunTags;
 }): Promise<unknown> {
   const { rc, handle, prompt, opts, label, rowId, tags } = input;
-  const { session, selectedSkills } = handle;
+  const { session } = handle;
   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);
@@ -176,21 +156,28 @@ export async function promptAgentSession(input: {
   });
 
   try {
-    const promptedWithSkills = appendSkillReminder(prompt, selectedSkills);
     const finalPrompt = opts.schema
-      ? `${promptedWithSkills}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
-      : promptedWithSkills;
+      ? `${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 {
-        await rc.perf.time("agent.prompt_ms", () => session.prompt(finalPrompt), tags);
+        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.structuredResult() === null && attempt < SCHEMA_REPROMPT_ATTEMPTS; attempt++) {
+          for (let attempt = 0; !handle.hasStructuredResult() && attempt < MAX_SCHEMA_REPAIR_ATTEMPTS; attempt++) {
             throwIfAborted(rc.signal);
-            rc.progress.log(`${label}: no final answer; re-prompting (${attempt + 1}/${SCHEMA_REPROMPT_ATTEMPTS})`);
+            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 rc.perf.time("agent.prompt_ms", () => session.prompt(SCHEMA_REPROMPT), tags);
+            await promptSession(SCHEMA_REPROMPT);
           }
         }
 
@@ -198,18 +185,20 @@ export async function promptAgentSession(input: {
         return rc.perf.timeSync(
           "agent.extract_result_ms",
           () => {
-            if (!opts.schema) return lastAssistantText(session.state);
-            const result = handle.structuredResult();
-            if (result === null) {
+            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 result;
+            return handle.structuredResult();
           },
           tags,
         );
       } finally {
-        rc.usage.recordAgentSession({ label, phase: tags.phase, messages: session.state.messages });
+        rc.usage.recordAgentSession({ label, phase: tags.phase, messages: session.messages });
       }
     } finally {
       unlinkPromptAbort();
@@ -219,38 +208,6 @@ export async function promptAgentSession(input: {
   }
 }
 
-export async function captureEffectiveSession(
-  session: AgentRunnerSession,
-  sessionCwd: string,
-  workspaceRoot: string,
-  signal: AbortSignal | undefined,
-): Promise<EffectiveSessionCapture> {
-  const state = session.state;
-  if (typeof state.systemPrompt !== "string") {
-    return { kind: "unverifiable", reason: "effective system prompt is unavailable" };
-  }
-  if (!state.model) return { kind: "unverifiable", reason: "effective model is unavailable" };
-  if (typeof state.thinkingLevel !== "string") {
-    return { kind: "unverifiable", reason: "effective thinking level is unavailable" };
-  }
-  if (!session.getActiveToolNames || !session.getAllTools || !session.getToolDefinition) {
-    return { kind: "unverifiable", reason: "effective tool APIs are unavailable" };
-  }
-  const toolInfos = effectiveToolInfos(session.getAllTools());
-  if (toolInfos.kind === "unverifiable") return toolInfos;
-  return await captureEffectiveAgentSessionIdentity(
-    {
-      systemPrompt: state.systemPrompt,
-      model: state.model,
-      thinkingLevel: state.thinkingLevel,
-      getActiveToolNames: () => session.getActiveToolNames!(),
-      getAllTools: () => toolInfos.tools,
-      getToolDefinition: (name) => session.getToolDefinition!(name),
-    },
-    { sessionCwd, workspaceRoot, signal },
-  );
-}
-
 function parseAgentModelRef(modelRef: string): ResolvedAgentModelRequest {
   const normalized = modelRef.trim();
   if (normalized.length === 0) {
@@ -270,51 +227,111 @@ function parseAgentModelRef(modelRef: string): ResolvedAgentModelRequest {
   return { ref: modelRef, provider, id };
 }
 
-async function defaultCreateSession(options: CreateAgentSessionOptions): Promise<{ session: AgentRunnerSession }> {
-  const { session } = await createAgentSession(options);
-  return { session };
+interface AgentSessionResources {
+  readonly selectedSkills: readonly Skill[];
+  createSession(sessionOptions: ToolSessionOptions): Promise<{ session: AgentRunnerSession }>;
+}
+
+async function prepareAgentSessionResources(input: {
+  readonly rc: RunContext;
+  readonly prompt: string;
+  readonly opts: AgentExecutionOptions;
+  readonly cwd: string;
+  readonly model: Model<Api> | undefined;
+  readonly customTools: ToolDefinition[];
+  readonly label: string;
+}): Promise<AgentSessionResources> {
+  const { rc, prompt, opts, cwd, model, customTools, label } = input;
+  const commonSessionOptions = (sessionOptions: ToolSessionOptions) => ({
+    model,
+    thinkingLevel: opts.thinkingLevel,
+    noTools: sessionOptions.noTools,
+    tools: sessionOptions.tools,
+    customTools,
+    sessionManager: SessionManager.inMemory(cwd),
+  });
+  const createSession = rc.createSession;
+  if (createSession) {
+    return {
+      selectedSkills: [],
+      createSession: (sessionOptions) =>
+        createSession({
+          cwd,
+          ...commonSessionOptions(sessionOptions),
+        }),
+    };
+  }
+
+  const skillOptions = {
+    prompt,
+    skills: opts.skills,
+    log: (message: string) => rc.progress.log(`${label}: ${message}`),
+  };
+  const preparedSkills = prepareAgentSkillResources(skillOptions);
+  const services = await createAgentSessionServices({
+    cwd,
+    resourceLoaderOptions: preparedSkills.resourceLoaderOptions,
+  });
+  await synchronizeWorkflowModelRuntime({
+    host: rc.modelRegistry,
+    child: services.modelRuntime,
+    selectedModel: model,
+    // Shared-cwd sessions mirror live removals; isolated cwd sessions retain target-only providers.
+    removeChildOnlyProviders: cwd === rc.cwd,
+  });
+  for (const diagnostic of services.diagnostics) {
+    rc.progress.log(`${label}: session ${diagnostic.type}: ${diagnostic.message}`);
+  }
+  const selectedSkills = preparedSkills.resolve(services.resourceLoader);
+  return {
+    selectedSkills,
+    createSession: (sessionOptions) =>
+      createAgentSessionFromServices({
+        services,
+        ...commonSessionOptions(sessionOptions),
+      }),
+  };
 }
 
 function linkSessionAbort(signal: AbortSignal | undefined, session: AgentRunnerSession): () => void {
   if (!signal) return () => {};
+  const onAbort = () => {
+    void session.abort().catch(() => undefined);
+  };
   if (signal.aborted) {
-    void session.abort();
+    onAbort();
     return () => {};
   }
-  const onAbort = () => {
-    void session.abort();
-  };
   signal.addEventListener("abort", onAbort, { once: true });
   return () => signal.removeEventListener("abort", onAbort);
 }
 
-type ToolSessionOptions = Pick<CreateAgentSessionOptions, "tools" | "excludeTools">;
+type ToolSessionOptions = Pick<CreateAgentSessionOptions, "tools" | "noTools">;
 
 interface ToolSelection {
   readonly sessionOptions: ToolSessionOptions;
-  readonly fallbackSessionOptions: ToolSessionOptions;
   readonly activeTools?: readonly string[];
   readonly toolHints: NonNullable<AgentExecutionOptions["toolHints"]>;
 }
 
-interface DynamicToolSession extends AgentRunnerSession {
-  getAllTools(): readonly AgentRunnerToolInfo[];
-  setActiveToolsByName(toolNames: readonly string[]): void;
-}
-
 function buildToolSelection(opts: AgentExecutionOptions, skillsEnabled: boolean): ToolSelection {
   const toolHints = opts.toolHints ?? [];
-  const fallback = toolHints.includes("search") ? DEFAULT_SEARCH_BASE_TOOLS : undefined;
+  const fallback = toolHints.includes("search")
+    ? DEFAULT_SEARCH_BASE_TOOLS
+    : toolHints.includes("external-search")
+      ? ["read"]
+      : undefined;
   const activeTools = buildToolList(opts, skillsEnabled, fallback);
-  const strictSessionOptions = { tools: activeTools ? [...activeTools] : undefined };
   if (toolHints.length === 0) {
-    return { sessionOptions: strictSessionOptions, fallbackSessionOptions: strictSessionOptions, activeTools, toolHints };
+    return {
+      sessionOptions: { tools: activeTools ? [...activeTools] : undefined },
+      activeTools,
+      toolHints,
+    };
   }
 
-  const explicitlyActive = new Set(activeTools ?? []);
   return {
-    sessionOptions: { excludeTools: BUILTIN_TOOL_NAMES.filter((name) => !explicitlyActive.has(name)) },
-    fallbackSessionOptions: { tools: activeTools ? [...activeTools] : [] },
+    sessionOptions: { noTools: "builtin" },
     activeTools,
     toolHints,
   };
@@ -333,81 +350,19 @@ function buildToolList(
   return allow;
 }
 
-function applyDynamicToolHints(session: AgentRunnerSession, selection: ToolSelection): boolean {
-  if (!hasDynamicToolApis(session)) return false;
-
+function applyDynamicToolHints(
+  session: AgentRunnerSession,
+  selection: ToolSelection,
+): ReadonlySet<AgentToolHint> {
   const active = new Set(selection.activeTools ?? []);
+  const matched = new Set<AgentToolHint>();
   for (const tool of session.getAllTools()) {
-    if (selection.toolHints.some((hint) => hint === "search" && isSearchLikeTool(tool))) active.add(tool.name);
-  }
-  session.setActiveToolsByName([...active]);
-  return true;
-}
-
-function hasDynamicToolApis(session: AgentRunnerSession): session is DynamicToolSession {
-  return typeof session.getAllTools === "function" && typeof session.setActiveToolsByName === "function";
-}
-
-function isSearchLikeTool(tool: AgentRunnerToolInfo): boolean {
-  if (/(?:^|[-_])(?:edit|write|replace|patch|apply|delete|remove|move|rename|create|commit|push)(?:$|[-_])/.test(tool.name.toLowerCase())) {
-    return false;
-  }
-  const name = tool.name.toLowerCase();
-  if (name.includes("grep") || name.includes("find") || name.includes("search") || name === "rg" || name.includes("ripgrep")) return true;
-  return /\b(?:grep|find|search|ripgrep|rg|structural search|code search)\b/.test(tool.description?.toLowerCase() ?? "");
-}
-
-function shouldCreateSkillResourceLoader(rc: RunContext, prompt: string, opts: AgentExecutionOptions): boolean {
-  return !rc.createSession || opts.skills !== undefined || extractSkillSelectorsFromText(prompt).length > 0;
-}
-
-function effectiveToolInfos(
-  tools: readonly AgentRunnerToolInfo[],
-): { readonly kind: "verified"; readonly tools: readonly EffectiveToolInfoLike[] } | { readonly kind: "unverifiable"; readonly reason: string } {
-  const normalized: EffectiveToolInfoLike[] = [];
-  for (const tool of tools) {
-    if (typeof tool.description !== "string" || tool.parameters === undefined || !tool.sourceInfo) {
-      return { kind: "unverifiable", reason: `active tool metadata is incomplete for ${tool.name}` };
+    for (const hint of selection.toolHints) {
+      if (!matchesAgentToolHint(tool, hint)) continue;
+      matched.add(hint);
+      active.add(tool.name);
     }
-    normalized.push({
-      name: tool.name,
-      description: tool.description,
-      parameters: tool.parameters,
-      promptGuidelines: tool.promptGuidelines,
-      sourceInfo: tool.sourceInfo,
-    });
   }
-  return { kind: "verified", tools: normalized };
-}
-
-function lastAssistantText(state: { readonly messages: readonly unknown[] }): string {
-  for (let index = state.messages.length - 1; index >= 0; index--) {
-    const message = state.messages[index];
-    if (hasRole(message, "assistant")) return messageTextContent(message).trim();
-  }
-  return "";
-}
-
-function hasRole(value: unknown, role: string): value is { role: string } {
-  return typeof value === "object" && value !== null && "role" in value && value.role === role;
-}
-
-function messageTextContent(message: unknown): string {
-  if (!hasContentArray(message)) return "";
-  return message.content.filter(isTextPart).map((part) => part.text).join("");
-}
-
-function hasContentArray(value: unknown): value is { content: unknown[] } {
-  return typeof value === "object" && value !== null && "content" in value && Array.isArray(value.content);
-}
-
-function isTextPart(value: unknown): value is { type: "text"; text: string } {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "type" in value &&
-    value.type === "text" &&
-    "text" in value &&
-    typeof value.text === "string"
-  );
+  session.setActiveToolsByName([...active]);
+  return matched;
 }

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

@@ -1,14 +1,16 @@
-import { DefaultResourceLoader, getAgentDir, type ResourceDiagnostic, type Skill } from "@earendil-works/pi-coding-agent";
+import type {
+  CreateAgentSessionServicesOptions,
+  ResourceDiagnostic,
+  ResourceLoader,
+  Skill,
+} from "@earendil-works/pi-coding-agent";
 import { dirname, resolve } from "node:path";
 import { logicalWorkspacePath, type ReplayWorkspaceRoots } from "./replay-path-identity.ts";
 import { captureTreeFingerprint } from "./tree-fingerprint.ts";
 import type { ResolvedSkillIdentity } from "./resume-context.ts";
 
-export type AgentSkillRequestSource = "explicit" | "prompt";
-
-export interface AgentSkillRequest {
+interface AgentSkillRequest {
   readonly selectors: readonly string[];
-  readonly source: AgentSkillRequestSource;
   readonly strict: boolean;
 }
 
@@ -17,11 +19,14 @@ export interface AgentSkillResolution {
   readonly unmatched: readonly string[];
 }
 
-export interface AgentSkillResourceSetup {
-  readonly resourceLoader: DefaultResourceLoader;
-  readonly selectedSkills: readonly Skill[];
-  readonly unmatchedSelectors: readonly string[];
-  readonly diagnostics: readonly ResourceDiagnostic[];
+type AgentSkillResourceLoaderOptions = Pick<
+  NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>,
+  "noSkills" | "skillsOverride"
+>;
+
+interface PreparedAgentSkillResources {
+  readonly resourceLoaderOptions: AgentSkillResourceLoaderOptions;
+  resolve(resourceLoader: Pick<ResourceLoader, "getSkills">): readonly Skill[];
 }
 
 export type AgentSkillIdentityCapture =
@@ -51,9 +56,9 @@ const PURPOSE_BOUNDARY_PATTERN = /\s+\b(?:for|to|when|while|so|because|in\s+orde
  */
 export function resolveAgentSkillRequest(prompt: string, explicitSkills: unknown): AgentSkillRequest {
   if (explicitSkills !== undefined) {
-    return { selectors: normalizeExplicitSkillSelectors(explicitSkills), source: "explicit", strict: true };
+    return { selectors: normalizeExplicitSkillSelectors(explicitSkills), strict: true };
   }
-  return { selectors: extractSkillSelectorsFromText(prompt), source: "prompt", strict: false };
+  return { selectors: extractSkillSelectorsFromText(prompt), strict: false };
 }
 
 export function extractSkillSelectorsFromText(text: string): string[] {
@@ -98,19 +103,21 @@ export function selectAgentSkills(skills: readonly Skill[], selectors: readonly
   return { selected: [...selected.values()], unmatched };
 }
 
-export async function createAgentSkillResourceLoader(options: {
-  readonly cwd: string;
+/**
+ * Prepare the skill-selection hooks consumed by pi's session-service factory.
+ * The returned resolver is scoped to one resource loader and must not be reused
+ * across concurrently-created session services.
+ */
+export function prepareAgentSkillResources(options: {
   readonly prompt: string;
   readonly skills: unknown;
   readonly log?: (message: string) => void;
-}): Promise<AgentSkillResourceSetup> {
+}): PreparedAgentSkillResources {
   const request = resolveAgentSkillRequest(options.prompt, options.skills);
   let resolution: AgentSkillResolution = { selected: [], unmatched: [] };
   let availableSkillNames: readonly string[] = [];
 
-  const loader = new DefaultResourceLoader({
-    cwd: options.cwd,
-    agentDir: getAgentDir(),
+  const resourceLoaderOptions: AgentSkillResourceLoaderOptions = {
     noSkills: request.selectors.length === 0,
     skillsOverride:
       request.selectors.length === 0
@@ -120,30 +127,29 @@ export async function createAgentSkillResourceLoader(options: {
             resolution = selectAgentSkills(current.skills, request.selectors);
             return { skills: [...resolution.selected], diagnostics: current.diagnostics };
           },
-  });
-  await loader.reload();
-  const { diagnostics } = loader.getSkills();
-  logSkillDiagnostics(options.log, diagnostics, request.selectors.length > 0);
-
-  if (request.strict && resolution.unmatched.length > 0) {
-    throw new Error(
-      `Unknown subagent skill${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}. Available: ${
-        availableSkillNames.join(", ") || "(none)"
-      }.`,
-    );
-  }
-
-  if (!request.strict && resolution.unmatched.length > 0) {
-    options.log?.(`Ignoring unrecognized subagent skill mention${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}`);
-  }
-
-  return { resourceLoader: loader, selectedSkills: resolution.selected, unmatchedSelectors: resolution.unmatched, diagnostics };
-}
-
-export function appendSkillReminder(prompt: string, skills: readonly Pick<Skill, "name" | "filePath">[]): string {
-  if (skills.length === 0) return prompt;
-  const skillList = skills.map((skill) => `${skill.name} (${skill.filePath})`).join(", ");
-  return `${prompt}\n\nWorkflow subagent skills enabled: ${skillList}. If you rely on an enabled skill, first read its SKILL.md with the read tool and follow its instructions. No other skills are available in this subagent.`;
+  };
+
+  return {
+    resourceLoaderOptions,
+    resolve(resourceLoader) {
+      const { diagnostics } = resourceLoader.getSkills();
+      logSkillDiagnostics(options.log, diagnostics, request.selectors.length > 0);
+
+      if (request.strict && resolution.unmatched.length > 0) {
+        throw new Error(
+          `Unknown subagent skill${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}. Available: ${
+            availableSkillNames.join(", ") || "(none)"
+          }.`,
+        );
+      }
+
+      if (!request.strict && resolution.unmatched.length > 0) {
+        options.log?.(`Ignoring unrecognized subagent skill mention${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}`);
+      }
+
+      return resolution.selected;
+    },
+  };
 }
 
 /** Capture the exact selected skill directories before journal lookup. */

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

@@ -1,5 +1,6 @@
-import type { AgentExecutionOptions, RunContext } from "./agent-runner-types.ts";
+import type { AgentExecutionOptions, AgentProgress } from "./agent-runner-types.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
+import type { WorktreeRegistry } from "./worktree.ts";
 
 interface AgentWorkspaceBase {
   readonly cwd: string;
@@ -18,8 +19,15 @@ export interface IsolatedAgentWorkspace extends AgentWorkspaceBase {
 
 export type AgentWorkspace = SharedAgentWorkspace | IsolatedAgentWorkspace;
 
+export interface AgentWorkspaceContext {
+  readonly cwd: string;
+  readonly worktrees: Pick<WorktreeRegistry, "probe" | "add" | "capturePatch" | "remove">;
+  readonly signal: AbortSignal | undefined;
+  readonly progress: Pick<AgentProgress, "log">;
+}
+
 export async function createAgentWorkspace(
-  rc: RunContext,
+  rc: AgentWorkspaceContext,
   opts: AgentExecutionOptions,
   label: string,
 ): Promise<AgentWorkspace> {
@@ -68,7 +76,7 @@ export async function createAgentWorkspace(
 }
 
 export async function disposeAgentWorkspace(
-  rc: RunContext,
+  rc: Pick<AgentWorkspaceContext, "progress">,
   label: string,
   workspace: AgentWorkspace | undefined,
 ): Promise<void> {