@oh-my-pi/pi-coding-agent 16.0.0 → 16.0.1

package/dist/types/config/settings-schema.d.ts

@@ -1,3 +1,4 @@
+import { type SearchProviderId } from "../web/search/types";
 /** Unified settings schema - single source of truth for all settings.
  *
  * Each setting is defined once here with:
@@ -3605,6 +3606,17 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Enable plan mode for read-only exploration and planning before execution";
         };
     };
+    readonly "plan.defaultOnStartup": {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly ui: {
+            readonly tab: "tasks";
+            readonly group: "Modes";
+            readonly label: "Start in Plan Mode";
+            readonly description: "Automatically enter plan mode at the start of every new session";
+            readonly condition: "planModeEnabled";
+        };
+    };
     readonly "goal.enabled": {
         readonly type: "boolean";
         readonly default: true;
@@ -4120,6 +4132,16 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
+    readonly "providers.webSearchExclude": {
+        readonly type: "array";
+        readonly default: SearchProviderId[];
+        readonly ui: {
+            readonly tab: "providers";
+            readonly group: "Services";
+            readonly label: "Excluded Web Search Providers";
+            readonly description: "Providers that web_search should never use, even as fallbacks";
+        };
+    };
     readonly "providers.image": {
         readonly type: "enum";
         readonly values: readonly ["auto", "openai", "antigravity", "xai", "gemini", "openrouter"];

package/dist/types/discovery/helpers.d.ts

@@ -67,6 +67,13 @@ export declare function getUserPath(ctx: LoadContext, source: SourceId, subpath:
  * Get project-level path for a source (cwd only).
  */
 export declare function getProjectPath(ctx: LoadContext, source: SourceId, subpath: string): string | null;
+/**
+ * Resolve GitHub Copilot CLI's user-global config root. Copilot stores per-user
+ * instructions/prompts/agents/MCP under `~/.copilot`, relocatable via the
+ * `COPILOT_HOME` env var (mirrors Copilot CLI's `--config-dir`). Falls back to
+ * `<home>/.copilot` when the override is unset.
+ */
+export declare function resolveCopilotHome(home: string): string;
 /**
  * Create source metadata for an item.
  */

package/dist/types/eval/__tests__/prelude-agent.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/extensibility/plugins/runtime-config.d.ts

@@ -0,0 +1,3 @@
+import type { PluginRuntimeConfig } from "./types";
+/** Normalizes persisted plugin runtime config across legacy lockfile shapes. */
+export declare function normalizePluginRuntimeConfig(config: Partial<PluginRuntimeConfig>): PluginRuntimeConfig;

package/dist/types/modes/types.d.ts

@@ -45,6 +45,11 @@ export type SubmittedUserInput = {
      *  as a hidden agent-authored `developer` message rather than a visible user
      *  turn. Used by the `c`/`.` continue shortcut. */
     synthetic?: boolean;
+    /** Marks this submission as a deliberate user resume (set by the `.`/`c`
+     *  continue shortcut, which is also `synthetic`). Forwarded to
+     *  `session.prompt({ userInitiated })` so it clears advisor auto-resume
+     *  suppression even though it is synthetic. */
+    userInitiated?: boolean;
     display?: boolean;
     /** Queue intent if the session is (or becomes) busy when this submission is
      *  dispatched: "steer" (interrupt the active turn) or "followUp" (process after

package/dist/types/session/agent-session.d.ts

@@ -250,6 +250,12 @@ export interface PromptOptions {
     toolChoice?: ToolChoice;
     /** Send as developer/system message instead of user. Providers that support it use the developer role; others fall back to user. */
     synthetic?: boolean;
+    /** Marks this prompt as a deliberate user action (typed message, `.`/`c`
+     *  continue). Clears advisor auto-resume suppression that a user interrupt set.
+     *  Defaults to `!synthetic`; manual-continue is synthetic yet user-initiated, so
+     *  it sets this explicitly. Agent-initiated synthetic prompts (auto-continue,
+     *  plan re-prime, reminders) leave it unset and keep suppression latched. */
+    userInitiated?: boolean;
     /** Explicit billing/initiator attribution for the prompt. Defaults to user prompts as `user` and synthetic prompts as `agent`. */
     attribution?: MessageAttribution;
     /** Skip pre-send compaction checks for this prompt (internal use for maintenance flows). */
@@ -1129,7 +1135,7 @@ export declare class AgentSession {
         compact?: boolean;
     }): string;
     /**
-     * Enable or disable the advisor for this session. The setting is persisted,
+     * Enable or disable the advisor for this session. The setting is overridden for the session,
      * and the runtime is started or stopped to match.
      *
      * @returns true when the advisor is actively running after the call.
@@ -1141,6 +1147,10 @@ export declare class AgentSession {
      * @returns true when the advisor is actively running after the call.
      */
     toggleAdvisorEnabled(): boolean;
+    /**
+     * Whether the advisor setting is enabled for this session.
+     */
+    isAdvisorEnabled(): boolean;
     /**
      * Whether a live advisor agent is attached to this session. True only when
      * `advisor.enabled` is set AND a model resolved for the `advisor` role AND

package/dist/types/session/session-manager.d.ts

@@ -250,8 +250,11 @@ export declare class SessionManager {
     /**
      * Open a specific session file.
      * @param sessionDir Optional dir for /new or /branch; defaults to the file's parent.
+     * @param options.initialCwd Cwd to use when the file is empty or missing.
      */
-    static open(filePath: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionManager>;
+    static open(filePath: string, sessionDir?: string, storage?: SessionStorage, options?: {
+        initialCwd?: string;
+    }): Promise<SessionManager>;
     /** Continue the most recent session, or create a new one if none exists. */
     static continueRecent(cwd: string, sessionDir?: string, storage?: SessionStorage): Promise<SessionManager>;
     /** Create an in-memory session (no file persistence). */

package/dist/types/task/index.d.ts

@@ -26,6 +26,27 @@ export declare function formatResultOutputFallback(result: Pick<SingleResult, "o
  * the same agent ≥2× all without roles. Returns undefined when no nudge applies.
  */
 export declare function buildSpecializationAdvisory(agentName: string | undefined, items: TaskItem[], depthCapacity: boolean): string | undefined;
+/**
+ * Suggestion — never a rejection — nudging the spawner to coordinate via `irc`
+ * when one call creates ≥2 live siblings and it still holds spawn capacity.
+ * Returns undefined when there is nothing to coordinate or IRC is unavailable.
+ */
+export declare function buildCoordinationAdvisory(items: TaskItem[], depthCapacity: boolean, ircEnabled: boolean): string | undefined;
+/**
+ * Compose the non-blocking advisory appended to a `task` result: the
+ * specialization nudge, plus — only when the siblings keep running after this
+ * call (`willRunAsync`) — the coordination suggestion. Coordination is gated on
+ * async because a sync fanout's siblings have already finished, so a
+ * "coordinate while they run" hint would misfire. Returns undefined when
+ * neither applies.
+ */
+export declare function composeSpawnAdvisory(args: {
+    agentName: string | undefined;
+    items: TaskItem[];
+    depthCapacity: boolean;
+    ircEnabled: boolean;
+    willRunAsync: boolean;
+}): string | undefined;
 /**
  * Task tool - Delegate tasks to specialized agents.
  *

package/dist/types/tools/github-cache.d.ts

@@ -8,10 +8,11 @@
  *   helpers swallow open/IO failures and degrade to "no cache" so a corrupt or
  *   unreadable DB never blocks a `gh` call.
  *
- * TTL:
  *   Soft TTL → return cached row directly.
- *   Past soft TTL but within hard TTL → return cached row AND schedule a
- *     background refresh (errors logged, never thrown).
+ *   Stateful issue/PR rows past soft TTL but within hard TTL → refresh
+ *     synchronously, falling back to the cached row if the live fetch fails.
+ *   Expensive PR diff rows past soft TTL but within hard TTL → return cached
+ *     row AND schedule a background refresh (errors logged, never thrown).
  *   Past hard TTL → treat as miss and fetch fresh.
  */
 import { Database } from "bun:sqlite";
@@ -101,7 +102,7 @@ export interface CacheLookupOptions<T> {
     settings?: Settings | undefined;
     now?: number;
 }
-export type CacheStatus = "miss" | "fresh" | "stale" | "disabled";
+export type CacheStatus = "miss" | "fresh" | "refreshed" | "stale" | "disabled";
 export interface CacheLookupResult<T> {
     rendered: string;
     sourceUrl: string | undefined;

package/dist/types/tools/job.d.ts

@@ -56,6 +56,7 @@ export declare class JobTool implements AgentTool<typeof jobSchema, JobToolDetai
 interface JobRenderArgs {
     poll?: string[];
     cancel?: string[];
+    list?: boolean;
 }
 export declare const jobToolRenderer: {
     inline: boolean;

package/dist/types/web/search/index.d.ts

@@ -80,6 +80,6 @@ export declare class WebSearchTool implements AgentTool<typeof webSearchSchema,
 /** Web search tool as CustomTool (for TUI rendering support) */
 export declare const webSearchCustomTool: CustomTool<typeof webSearchSchema, SearchRenderDetails>;
 export declare function getSearchTools(): CustomTool<any, any>[];
-export { getSearchProvider, setPreferredSearchProvider } from "./provider";
+export { getSearchProvider, setExcludedSearchProviders, setPreferredSearchProvider } from "./provider";
 export type { SearchProviderId as SearchProvider, SearchResponse } from "./types";
-export { isSearchProviderPreference } from "./types";
+export { isSearchProviderId, isSearchProviderPreference } from "./types";

package/dist/types/web/search/provider.d.ts

@@ -13,6 +13,8 @@ export declare function getSearchProviderLabel(id: SearchProviderId): string;
 export declare function getSearchProvider(id: SearchProviderId): Promise<SearchProvider>;
 /** Set the preferred web search provider from settings */
 export declare function setPreferredSearchProvider(provider: SearchProviderId | "auto"): void;
+/** Set providers that web search should never use, including fallbacks. */
+export declare function setExcludedSearchProviders(providers: readonly SearchProviderId[]): void;
 /**
  * Determine which providers are configured and currently available.
  * Each candidate is loaded (and its `isAvailable()` called) only as the chain

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "16.0.0",
+	"version": "16.0.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -47,17 +47,17 @@
 		"@agentclientprotocol/sdk": "0.25.0",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "16.0.0",
-		"@oh-my-pi/omp-stats": "16.0.0",
-		"@oh-my-pi/pi-agent-core": "16.0.0",
-		"@oh-my-pi/pi-ai": "16.0.0",
-		"@oh-my-pi/pi-catalog": "16.0.0",
-		"@oh-my-pi/pi-mnemopi": "16.0.0",
-		"@oh-my-pi/pi-natives": "16.0.0",
-		"@oh-my-pi/pi-tui": "16.0.0",
-		"@oh-my-pi/pi-utils": "16.0.0",
-		"@oh-my-pi/pi-wire": "16.0.0",
-		"@oh-my-pi/snapcompact": "16.0.0",
+		"@oh-my-pi/hashline": "16.0.1",
+		"@oh-my-pi/omp-stats": "16.0.1",
+		"@oh-my-pi/pi-agent-core": "16.0.1",
+		"@oh-my-pi/pi-ai": "16.0.1",
+		"@oh-my-pi/pi-catalog": "16.0.1",
+		"@oh-my-pi/pi-mnemopi": "16.0.1",
+		"@oh-my-pi/pi-natives": "16.0.1",
+		"@oh-my-pi/pi-tui": "16.0.1",
+		"@oh-my-pi/pi-utils": "16.0.1",
+		"@oh-my-pi/pi-wire": "16.0.1",
+		"@oh-my-pi/snapcompact": "16.0.1",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",

package/src/cli/args.ts

@@ -279,6 +279,7 @@ export function getExtraHelpText(): string {
   KILO_API_KEY               - Kilo Gateway models
   MISTRAL_API_KEY            - Mistral models
   ZAI_API_KEY                - z.ai models (ZhipuAI/GLM)
+  UMANS_AI_CODING_PLAN_API_KEY - Umans AI Coding Plan models
   MINIMAX_API_KEY            - MiniMax models
   OPENCODE_API_KEY           - OpenCode Zen/OpenCode Go models
   CURSOR_ACCESS_TOKEN        - Cursor AI models

package/src/collab/host.ts

@@ -396,7 +396,7 @@ export class CollabHost {
 		}
 		const name = peer.name;
 		void this.#ctx.session
-			.abort()
+			.abort({ reason: USER_INTERRUPT_LABEL })
 			.then(() => this.#ctx.session.emitNotice("info", `${name} interrupted`, "collab"))
 			.catch(err => logger.warn("collab guest abort failed", { error: String(err) }));
 	}

package/src/config/settings-schema.ts

@@ -34,7 +34,7 @@ import {
 	TTS_LOCAL_VOICE_VALUES,
 } from "../tts/models";
 import { EDIT_MODES } from "../utils/edit-mode";
-import { SEARCH_PROVIDER_OPTIONS, SEARCH_PROVIDER_PREFERENCES } from "../web/search/types";
+import { SEARCH_PROVIDER_OPTIONS, SEARCH_PROVIDER_PREFERENCES, type SearchProviderId } from "../web/search/types";
 
 /** Unified settings schema - single source of truth for all settings.
  *
@@ -3454,6 +3454,18 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"plan.defaultOnStartup": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tasks",
+			group: "Modes",
+			label: "Start in Plan Mode",
+			description: "Automatically enter plan mode at the start of every new session",
+			condition: "planModeEnabled",
+		},
+	},
+
 	"goal.enabled": {
 		type: "boolean",
 		default: true,
@@ -3846,6 +3858,16 @@ export const SETTINGS_SCHEMA = {
 			options: SEARCH_PROVIDER_OPTIONS,
 		},
 	},
+	"providers.webSearchExclude": {
+		type: "array",
+		default: [] as SearchProviderId[],
+		ui: {
+			tab: "providers",
+			group: "Services",
+			label: "Excluded Web Search Providers",
+			description: "Providers that web_search should never use, even as fallbacks",
+		},
+	},
 	"providers.image": {
 		type: "enum",
 		values: ["auto", "openai", "antigravity", "xai", "gemini", "openrouter"] as const,

package/src/discovery/claude-plugins.ts

@@ -124,43 +124,6 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 	}
 	return { items, warnings };
 }
-async function loadSkillSlashCommands(ctx: LoadContext, root: ClaudePluginRoot): Promise<LoadResult<SlashCommand>> {
-	const { dir: skillsDir, warning } = await resolvePluginDir(root, ["skills"], "skills");
-	const warnings: string[] = warning ? [warning] : [];
-	const skillsResult = await scanSkillsFromDir(ctx, {
-		dir: skillsDir,
-		providerId: PROVIDER_ID,
-		level: root.scope,
-	});
-	warnings.push(...(skillsResult.warnings ?? []));
-
-	const commands = await Promise.all(
-		skillsResult.items.map(async skill => {
-			const content = await readFile(skill.path);
-			if (content === null) {
-				warnings.push(`Failed to read skill slash command: ${skill.path}`);
-				return null;
-			}
-			// Slash command name MUST come from the skill directory basename, not
-			// frontmatter `name`: `expandSlashCommand` splits the command at the first
-			// whitespace, so a display name like "Understand Anything" would never match
-			// `/understand`. The documented layout is `skills/<name>/SKILL.md` → `/<name>`.
-			const command: SlashCommand = {
-				name: path.basename(path.dirname(skill.path)),
-				path: skill.path,
-				content,
-				level: skill.level,
-				_source: skill._source,
-			};
-			return command;
-		}),
-	);
-
-	return {
-		items: commands.filter((command): command is SlashCommand => command !== null),
-		warnings,
-	};
-}
 
 // =============================================================================
 // Slash Commands
@@ -189,16 +152,14 @@ async function loadSlashCommands(ctx: LoadContext): Promise<LoadResult<SlashComm
 					};
 				},
 			});
-			const skillCommandResult = await loadSkillSlashCommands(ctx, root);
-			return { commandResult, skillCommandResult, warning };
+			return { commandResult, warning };
 		}),
 	);
 
-	for (const { commandResult, skillCommandResult, warning } of results) {
+	for (const { commandResult, warning } of results) {
 		if (warning) warnings.push(warning);
-		items.push(...commandResult.items, ...skillCommandResult.items);
+		items.push(...commandResult.items);
 		if (commandResult.warnings) warnings.push(...commandResult.warnings);
-		if (skillCommandResult.warnings) warnings.push(...skillCommandResult.warnings);
 	}
 
 	return { items, warnings };

package/src/discovery/github.ts

@@ -5,11 +5,14 @@
  * Priority: 30 (shared standard provider)
  *
  * Sources:
- * - Project: .github/ (project-only, no user-level discovery)
+ * - Project: .github/ (repo-local Copilot config)
+ * - User: ~/.copilot/ (user-global Copilot CLI config; relocatable via COPILOT_HOME)
+ * - Extra: directories listed in COPILOT_CUSTOM_INSTRUCTIONS_DIRS
  *
  * Capabilities:
- * - context-files: copilot-instructions.md in .github/
- * - instructions: *.instructions.md in .github/instructions/ with applyTo frontmatter
+ * - context-files: copilot-instructions.md in .github/ and ~/.copilot/; AGENTS.md in each COPILOT_CUSTOM_INSTRUCTIONS_DIRS
+ * - instructions: *.instructions.md under .github/instructions/ (project) and <dir>/.github/instructions/ for each custom dir (applyTo frontmatter)
+ * - prompts: *.prompt.md in .github/prompts/ (VS Code Copilot prompt files)
  * - skills: <name>/SKILL.md in .github/skills/ (GitHub Agent Skills layout)
  */
 import * as path from "node:path";
@@ -18,10 +21,19 @@ import { registerProvider } from "../capability";
 import { type ContextFile, contextFileCapability } from "../capability/context-file";
 import { readFile } from "../capability/fs";
 import { type Instruction, instructionCapability } from "../capability/instruction";
+import { type Prompt, promptCapability } from "../capability/prompt";
 import { type Skill, skillCapability } from "../capability/skill";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
 
-import { calculateDepth, createSourceMeta, getProjectPath, loadFilesFromDir, scanSkillsFromDir } from "./helpers";
+import {
+	calculateDepth,
+	createSourceMeta,
+	getProjectPath,
+	loadFilesFromDir,
+	parseCSV,
+	resolveCopilotHome,
+	scanSkillsFromDir,
+} from "./helpers";
 
 const PROVIDER_ID = "github";
 const DISPLAY_NAME = "GitHub Copilot";
@@ -52,6 +64,33 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 		}
 	}
 
+	// User-global instructions (~/.copilot/copilot-instructions.md), applied across all repos.
+	const userInstructionsPath = path.join(resolveCopilotHome(ctx.home), "copilot-instructions.md");
+	const userContent = await readFile(userInstructionsPath);
+	if (userContent) {
+		items.push({
+			path: userInstructionsPath,
+			content: userContent,
+			level: "user",
+			_source: createSourceMeta(PROVIDER_ID, userInstructionsPath, "user"),
+		});
+	}
+
+	// Each COPILOT_CUSTOM_INSTRUCTIONS_DIRS entry contributes an AGENTS.md (Copilot CLI
+	// searches these dirs for AGENTS.md + .github/instructions/**; the latter is handled
+	// by loadInstructions). copilot-instructions.md is NOT part of the custom-dir spec.
+	for (const dir of copilotCustomInstructionDirs()) {
+		const agentsMdPath = path.join(dir, "AGENTS.md");
+		const agentsMdContent = await readFile(agentsMdPath);
+		if (agentsMdContent) {
+			items.push({
+				path: agentsMdPath,
+				content: agentsMdContent,
+				level: "user",
+				_source: createSourceMeta(PROVIDER_ID, agentsMdPath, "user"),
+			});
+		}
+	}
 	return { items, warnings };
 }
 
@@ -65,9 +104,23 @@ async function loadInstructions(ctx: LoadContext): Promise<LoadResult<Instructio
 
 	const instructionsDir = getProjectPath(ctx, "github", "instructions");
 	if (instructionsDir) {
+		// Path-specific instructions live "within or below" .github/instructions/ → recurse.
 		const result = await loadFilesFromDir<Instruction>(ctx, instructionsDir, PROVIDER_ID, "project", {
 			extensions: ["md"],
 			transform: transformInstruction,
+			recursive: true,
+		});
+		items.push(...result.items);
+		if (result.warnings) warnings.push(...result.warnings);
+	}
+
+	// Each COPILOT_CUSTOM_INSTRUCTIONS_DIRS entry contributes <dir>/.github/instructions/**/*.instructions.md.
+	for (const dir of copilotCustomInstructionDirs()) {
+		const customInstructionsDir = path.join(dir, ".github", "instructions");
+		const result = await loadFilesFromDir<Instruction>(ctx, customInstructionsDir, PROVIDER_ID, "user", {
+			extensions: ["md"],
+			transform: transformInstruction,
+			recursive: true,
 		});
 		items.push(...result.items);
 		if (result.warnings) warnings.push(...result.warnings);
@@ -99,6 +152,39 @@ function transformInstruction(name: string, content: string, filePath: string, s
 	};
 }
 
+// =============================================================================
+// Prompts
+// =============================================================================
+
+async function loadPrompts(ctx: LoadContext): Promise<LoadResult<Prompt>> {
+	// `.github/prompts/*.prompt.md` is the VS Code Copilot prompt-file convention (the
+	// Copilot CLI has no prompt-file feature of its own); surface them as slash commands.
+	const promptsDir = getProjectPath(ctx, "github", "prompts");
+	if (!promptsDir) return { items: [], warnings: [] };
+
+	return loadFilesFromDir<Prompt>(ctx, promptsDir, PROVIDER_ID, "project", {
+		extensions: ["md"],
+		transform: transformPrompt,
+	});
+}
+
+function transformPrompt(name: string, content: string, filePath: string, source: SourceMeta): Prompt | null {
+	// Prompt files are `*.prompt.md`; ignore other markdown that may share the dir.
+	if (!name.endsWith(".prompt.md")) return null;
+
+	const { frontmatter, body } = parseFrontmatter(content, { source: filePath });
+	const promptName =
+		typeof frontmatter.name === "string" && frontmatter.name ? frontmatter.name : path.basename(name, ".prompt.md");
+
+	return { name: promptName, path: filePath, content: body, _source: source };
+}
+
+/** Directories listed in the COPILOT_CUSTOM_INSTRUCTIONS_DIRS env var (comma-separated). */
+function copilotCustomInstructionDirs(): string[] {
+	const raw = process.env.COPILOT_CUSTOM_INSTRUCTIONS_DIRS;
+	return raw ? parseCSV(raw) : [];
+}
+
 // =============================================================================
 // Skills
 // =============================================================================
@@ -132,7 +218,8 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 registerProvider(contextFileCapability.id, {
 	id: PROVIDER_ID,
 	displayName: DISPLAY_NAME,
-	description: "Load copilot-instructions.md from .github/",
+	description:
+		"Load copilot-instructions.md from .github/ and ~/.copilot/; AGENTS.md from COPILOT_CUSTOM_INSTRUCTIONS_DIRS",
 	priority: PRIORITY,
 	load: loadContextFiles,
 });
@@ -140,7 +227,7 @@ registerProvider(contextFileCapability.id, {
 registerProvider(instructionCapability.id, {
 	id: PROVIDER_ID,
 	displayName: DISPLAY_NAME,
-	description: "Load *.instructions.md from .github/instructions/ with applyTo frontmatter",
+	description: "Load *.instructions.md from .github/instructions/ and COPILOT_CUSTOM_INSTRUCTIONS_DIRS",
 	priority: PRIORITY,
 	load: loadInstructions,
 });
@@ -152,3 +239,11 @@ registerProvider<Skill>(skillCapability.id, {
 	priority: PRIORITY,
 	load: loadSkills,
 });
+
+registerProvider<Prompt>(promptCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load *.prompt.md from .github/prompts/ (VS Code Copilot prompt files)",
+	priority: PRIORITY,
+	load: loadPrompts,
+});

package/src/discovery/helpers.ts

@@ -107,6 +107,17 @@ export function getProjectPath(ctx: LoadContext, source: SourceId, subpath: stri
 	return path.join(ctx.cwd, paths.projectDir, subpath);
 }
 
+/**
+ * Resolve GitHub Copilot CLI's user-global config root. Copilot stores per-user
+ * instructions/prompts/agents/MCP under `~/.copilot`, relocatable via the
+ * `COPILOT_HOME` env var (mirrors Copilot CLI's `--config-dir`). Falls back to
+ * `<home>/.copilot` when the override is unset.
+ */
+export function resolveCopilotHome(home: string): string {
+	const override = process.env.COPILOT_HOME?.trim();
+	return override ? override : path.join(home, ".copilot");
+}
+
 /**
  * Create source metadata for an item.
  */

package/src/eval/__tests__/prelude-agent.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "bun:test";
+import * as vm from "node:vm";
+import { JAVASCRIPT_PRELUDE_SOURCE } from "../js/shared/prelude";
+
+/**
+ * The eval `agent()` helper grows a `returnHandle` option that turns its bare
+ * text result into a DAG node dict carrying the spawned agent's recoverable
+ * `agent://<id>` handle, so a downstream `pipeline`/`parallel` stage can wire
+ * the transcript by reference instead of re-inlining it. These lock the node
+ * shape, backward compatibility of the default path, the schema interaction,
+ * and the no-`details` fallback (the helper must never throw).
+ *
+ * The prelude source is executed verbatim in a throwaway VM context with only
+ * the host bridge (`__omp_call_tool__`) stubbed — no worker, no kernel — so the
+ * test runs against the real shipped helper, not a re-implementation.
+ */
+function loadPrelude(callTool: (name: string, args: unknown) => Promise<unknown>): Record<string, unknown> {
+	const sandbox: Record<string, unknown> = { __omp_call_tool__: callTool };
+	vm.createContext(sandbox);
+	vm.runInContext(JAVASCRIPT_PRELUDE_SOURCE, sandbox);
+	return sandbox;
+}
+
+type AgentHelper = (prompt: string, opts?: Record<string, unknown>) => Promise<unknown>;
+
+describe("eval js agent() returnHandle", () => {
+	it("returns a DAG node carrying the agent:// handle when returnHandle is set", async () => {
+		let seenName: string | undefined;
+		const sandbox = loadPrelude(async name => {
+			seenName = name;
+			return { text: "hello world", details: { agent: "task", id: "abc123", model: "m", structured: false } };
+		});
+		const node = await (sandbox.agent as AgentHelper)("say hi", { returnHandle: true });
+		expect(seenName).toBe("__agent__");
+		expect(node).toEqual({
+			text: "hello world",
+			output: "hello world",
+			handle: "agent://abc123",
+			id: "abc123",
+			agent: "task",
+		});
+	});
+
+	it("returns bare text by default (backward compatible)", async () => {
+		const sandbox = loadPrelude(async () => ({
+			text: "hello world",
+			details: { agent: "task", id: "abc123", structured: false },
+		}));
+		const out = await (sandbox.agent as AgentHelper)("say hi");
+		expect(out).toBe("hello world");
+	});
+
+	it("carries the parsed object under data when schema and returnHandle combine", async () => {
+		const payload = JSON.stringify({ k: 1 });
+		const sandbox = loadPrelude(async () => ({
+			text: payload,
+			details: { agent: "task", id: "id-9", structured: true },
+		}));
+		const node = (await (sandbox.agent as AgentHelper)("emit", {
+			schema: { type: "object" },
+			returnHandle: true,
+		})) as Record<string, unknown>;
+		expect(node.handle).toBe("agent://id-9");
+		expect(node.data).toEqual({ k: 1 });
+		expect(node.text).toBe(payload);
+	});
+
+	it("falls back to a null handle without throwing when the bridge omits details", async () => {
+		const sandbox = loadPrelude(async () => ({ text: "lonely" }));
+		const node = await (sandbox.agent as AgentHelper)("x", { returnHandle: true });
+		expect(node).toEqual({ text: "lonely", output: "lonely", handle: null, id: null, agent: null });
+	});
+});

package/src/eval/js/shared/prelude.txt

@@ -117,10 +117,19 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 	};
 
 	const agent = async (prompt, opts, ...rest) => {
-		const o = optionsArg("agent", opts, rest, ["agentType", "model", "label", "schema"], "{ agentType, model, label, schema }");
-		const res = await globalThis.__omp_call_tool__("__agent__", { prompt, ...o });
+		const o = optionsArg("agent", opts, rest, ["agentType", "model", "label", "schema"], "{ agentType, model, label, schema, returnHandle }");
+		const { returnHandle, ...callArgs } = o;
+		const res = await globalThis.__omp_call_tool__("__agent__", { prompt, ...callArgs });
 		const text = res && typeof res === "object" ? res.text : res;
-		return hasOwn(o, "schema") ? JSON.parse(text) : text;
+		const parsed = hasOwn(callArgs, "schema") ? JSON.parse(text) : text;
+		if (!returnHandle) return parsed;
+		const details = res && typeof res === "object" ? res.details : undefined;
+		if (!details || typeof details !== "object" || details.id == null) {
+			return { text, output: text, handle: null, id: null, agent: null };
+		}
+		const node = { text, output: text, handle: `agent://${details.id}`, id: details.id, agent: details.agent ?? null };
+		if (hasOwn(callArgs, "schema")) node.data = parsed;
+		return node;
 	};
 
 	// Pool ceiling mirrors the task tool's `task.maxConcurrency` setting so an