@dreki-gg/pi-subagent 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @dreki-gg/pi-subagent
 
+## 0.6.0
+
+### Minor Changes
+
+- [`5e853af`](https://github.com/dreki-gg/pi-extensions/commit/5e853af054a31c4bf87d80f944513e537a39201d) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Sync the extensions repo with Pi 0.68.0 and improve direct agent runs.
+
+  - `@dreki-gg/pi-context7`: remove stale alias docs and align compatibility tests with the canonical tool names actually exported.
+  - `@dreki-gg/pi-modes`: use `before_agent_start.systemPromptOptions.selectedTools` when available so mode prompt text reflects the active prompt tool set.
+  - `@dreki-gg/pi-subagent`: add `/run-agent`, support `sessionStrategy: fork-at` in agent frontmatter, default bundled `worker` and `reviewer` to forked direct runs, and add a custom renderer for run summaries.
+
+## 0.5.0
+
+### Minor Changes
+
+- [`4f2f148`](https://github.com/dreki-gg/pi-extensions/commit/4f2f148488e32ff43f97216a5c221fd9d1716a11) Thanks [@jalbarrang](https://github.com/jalbarrang)! - added agents to the registry so my fork is able to discover subagent files
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -28,6 +28,12 @@ Examples:
 - "have planner make a plan, then worker implement it"
 - "send this to reviewer"
 
+For direct user-invoked single-agent runs, use:
+
+```text
+/run-agent worker implement the auth flow we discussed
+```
+
 `/delegate` is optional. It exists for rigid gated workflows, plan approval, and explicit workflow control.
 
 ## Optional Delegate Command
@@ -65,6 +71,24 @@ Pin a workflow and skip the project-agent confirmation prompt:
 5. **Plan gate** — shows planner output for approval before worker runs
 6. **Summary** — full phase-by-phase report with usage totals
 
+## Direct Agent Runs
+
+Run one agent directly from the current session:
+
+```text
+/run-agent [--scope user|project|both] [--yes-project-agents] <agent> [task]
+```
+
+Examples:
+
+```text
+/run-agent scout trace how auth state is loaded
+/run-agent worker implement the refactor we just planned
+/run-agent --scope project reviewer review the latest changes
+```
+
+If the chosen agent frontmatter sets `sessionStrategy: fork-at`, the command clones the current active path into a new session before running the agent. That keeps long implementation runs isolated in their own branch while preserving the original conversation.
+
 ### Delegate Flags
 
 | Flag | Meaning |
@@ -94,6 +118,7 @@ name: my-agent
 description: What this agent does
 tools: read, grep, find, ls
 model: anthropic/claude-haiku-4-5
+sessionStrategy: fork-at
 ---
 
 System prompt for the agent.
@@ -106,13 +131,17 @@ The package ships with these agents out of the box:
 - `scout` — fast codebase recon
 - `docs-scout` — Context7-first documentation lookup
 - `planner` — implementation planning
-- `worker` — general-purpose implementation
-- `reviewer` — code review
+- `worker` — general-purpose implementation (`sessionStrategy: fork-at` by default)
+- `reviewer` — code review (`sessionStrategy: fork-at` by default)
 - `ux-designer` — frontend UI design
 
 Resolution order is: bundled → user (`~/.pi/agent/agents/`) → project (`.pi/agents/`). Project agents override user and bundled agents by name.
 
-> Note: pi packages do not currently expose a first-class `agents` manifest. If you mirror package agents into `~/.pi/agent/agents/`, treat those files as managed package artifacts rather than hand-authored overrides.
+Optional frontmatter:
+- `thinking` — reasoning effort for the spawned pi process
+- `sessionStrategy: fork-at` — when used with `/run-agent`, clone the current active branch into a new session before running
+
+> Note: pi now supports package-shipped agents via `pi.agents` (or conventional `agents/` directories). This package publishes its bundled agents that way, while user agents in `~/.pi/agent/agents/` and project agents in `.pi/agents/` still override them by name.
 
 ### Managing Agents
 

package/agents/reviewer.md

@@ -4,6 +4,7 @@ description: Code review specialist for quality and security analysis
 tools: read, grep, find, ls, bash
 model: openai/gpt-5.4
 thinking: medium
+sessionStrategy: fork-at
 ---
 
 You are a senior code reviewer. Analyze code for quality, security, and maintainability.

package/agents/worker.md

@@ -3,6 +3,7 @@ name: worker
 description: General-purpose subagent with full capabilities, isolated context
 model: openai/gpt-5.4
 thinking: medium
+sessionStrategy: fork-at
 ---
 
 You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.

package/extensions/subagent/agents.ts

@@ -1,13 +1,22 @@
 /**
  * Agent discovery and configuration
+ *
+ * Supports two discovery strategies:
+ * 1. Package-resolved: Uses pi's ResolvedPaths.agents from the package manager
+ *    when available (pi forks with first-class agents resource support).
+ *    Package agents are resolved, filtered, and toggleable via pi config.
+ * 2. Legacy: Manual filesystem discovery from bundled, user, and project dirs.
+ *    Used as fallback when ResolvedPaths.agents is not available.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getAgentDir, parseFrontmatter } from '@mariozechner/pi-coding-agent';
+import type { ResolvedPaths } from '@mariozechner/pi-coding-agent';
 
 export type AgentScope = 'user' | 'project' | 'both';
-export type AgentSource = 'bundled' | 'user' | 'project';
+export type AgentSource = 'bundled' | 'user' | 'project' | 'package';
+export type AgentSessionStrategy = 'inline' | 'fork-at';
 
 export interface AgentConfig {
   name: string;
@@ -15,6 +24,7 @@ export interface AgentConfig {
   tools?: string[];
   model?: string;
   thinking?: string;
+  sessionStrategy?: AgentSessionStrategy;
   systemPrompt: string;
   source: AgentSource;
   filePath: string;
@@ -28,6 +38,13 @@ export interface AgentDiscoveryResult {
 /** Bundled agents ship with the package (../../agents relative to extensions/subagent/) */
 const bundledAgentsDir = path.resolve(import.meta.dirname, '..', '..', 'agents');
 
+function parseSessionStrategy(value?: string): AgentSessionStrategy | undefined {
+  if (!value) return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'inline' || normalized === 'fork-at') return normalized;
+  return undefined;
+}
+
 function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
   const agents: AgentConfig[] = [];
 
@@ -71,6 +88,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
       tools: tools && tools.length > 0 ? tools : undefined,
       model: frontmatter.model,
       thinking: frontmatter.thinking,
+      sessionStrategy: parseSessionStrategy(frontmatter.sessionStrategy),
       systemPrompt: body,
       source,
       filePath,
@@ -100,6 +118,57 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
   }
 }
 
+/**
+ * Load agents from package-manager resolved paths (enabled only).
+ * This is called with pre-resolved paths from an async context.
+ */
+export function loadAgentsFromResolvedPaths(resolvedPaths: ResolvedPaths): AgentConfig[] {
+  // Check if the agents field exists (compatibility with upstream pi)
+  const agentResources = (resolvedPaths as unknown as Record<string, unknown>).agents;
+  if (!agentResources || !Array.isArray(agentResources)) {
+    return [];
+  }
+
+  const agents: AgentConfig[] = [];
+  for (const resource of agentResources) {
+    if (!resource.enabled) continue;
+    const agent = loadAgentFromFile(resource.path, 'package');
+    if (agent) agents.push(agent);
+  }
+  return agents;
+}
+
+function loadAgentFromFile(filePath: string, source: AgentSource): AgentConfig | null {
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+
+  const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+  if (!frontmatter.name || !frontmatter.description) {
+    return null;
+  }
+
+  const tools = frontmatter.tools
+    ?.split(',')
+    .map((t: string) => t.trim())
+    .filter(Boolean);
+
+  return {
+    name: frontmatter.name,
+    description: frontmatter.description,
+    tools: tools && tools.length > 0 ? tools : undefined,
+    model: frontmatter.model,
+    thinking: frontmatter.thinking,
+    sessionStrategy: parseSessionStrategy(frontmatter.sessionStrategy),
+    systemPrompt: body,
+    source,
+    filePath,
+  };
+}
+
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
   const userDir = path.join(getAgentDir(), 'agents');
   const projectAgentsDir = findNearestProjectAgentsDir(cwd);
@@ -128,6 +197,34 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
   return { agents: Array.from(agentMap.values()), projectAgentsDir };
 }
 
+/**
+ * Discover agents with package-resolved paths merged in.
+ * Package-resolved agents (from pi.agents in installed packages) are loaded
+ * at lowest priority, then overridden by bundled, user, and project agents.
+ *
+ * Falls back to discoverAgents() when resolvedPaths is not provided or
+ * does not contain the agents field (upstream pi compatibility).
+ */
+export function discoverAgentsWithPackages(
+  cwd: string,
+  scope: AgentScope,
+  resolvedPaths?: ResolvedPaths,
+): AgentDiscoveryResult {
+  const base = discoverAgents(cwd, scope);
+
+  if (!resolvedPaths) return base;
+
+  const packageAgents = loadAgentsFromResolvedPaths(resolvedPaths);
+  if (packageAgents.length === 0) return base;
+
+  // Package agents are lowest priority: existing agents override by name
+  const agentMap = new Map<string, AgentConfig>();
+  for (const agent of packageAgents) agentMap.set(agent.name, agent);
+  for (const agent of base.agents) agentMap.set(agent.name, agent);
+
+  return { agents: Array.from(agentMap.values()), projectAgentsDir: base.projectAgentsDir };
+}
+
 export { bundledAgentsDir };
 
 export function formatAgentList(

package/extensions/subagent/delegate-args.ts

@@ -8,6 +8,13 @@ export interface DelegateCommandOptions {
   explicitTask?: string;
 }
 
+export interface RunAgentCommandOptions {
+  agentScope: AgentScope;
+  confirmProjectAgents: boolean;
+  agentName?: string;
+  explicitTask?: string;
+}
+
 const WORKFLOW_IDS = new Set<WorkflowId>([
   'scout-only',
   'scout-and-plan',
@@ -82,3 +89,57 @@ export function parseDelegateArgs(rawArgs?: string):
     },
   };
 }
+
+export function formatRunAgentUsage(): string {
+  return 'Usage: /run-agent [--scope user|project|both] [--yes-project-agents] <agent> [task]';
+}
+
+export function parseRunAgentArgs(rawArgs?: string):
+  | { ok: true; options: RunAgentCommandOptions }
+  | { ok: false; error: string } {
+  const tokens = tokenize(rawArgs?.trim() ?? '');
+  const taskTokens: string[] = [];
+
+  let agentScope: AgentScope = 'user';
+  let confirmProjectAgents = true;
+  let agentName: string | undefined;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+
+    if (token === '--scope') {
+      const value = tokens[++i];
+      if (!value || !['user', 'project', 'both'].includes(value)) {
+        return { ok: false, error: `Invalid --scope value.\n\n${formatRunAgentUsage()}` };
+      }
+      agentScope = value as AgentScope;
+      continue;
+    }
+
+    if (token === '--yes-project-agents') {
+      confirmProjectAgents = false;
+      continue;
+    }
+
+    if (token.startsWith('--')) {
+      return { ok: false, error: `Unknown option: ${token}\n\n${formatRunAgentUsage()}` };
+    }
+
+    if (!agentName) {
+      agentName = token;
+      continue;
+    }
+
+    taskTokens.push(token);
+  }
+
+  return {
+    ok: true,
+    options: {
+      agentScope,
+      confirmProjectAgents,
+      agentName,
+      explicitTask: taskTokens.join(' ').trim() || undefined,
+    },
+  };
+}

package/extensions/subagent/delegate-executor.ts

@@ -3,8 +3,9 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { withFileMutationQueue } from '@mariozechner/pi-coding-agent';
+import type { ResolvedPaths } from '@mariozechner/pi-coding-agent';
 import type { Message } from '@mariozechner/pi-ai';
-import { discoverAgents, type AgentScope } from './agents';
+import { discoverAgentsWithPackages, type AgentScope } from './agents';
 import type { AgentResult, UsageStats } from './delegate-types';
 
 function emptyUsage(): UsageStats {
@@ -45,6 +46,7 @@ export interface RunAgentOptions {
   onUpdate?: OnPhaseUpdate;
   phaseName?: string;
   signal?: AbortSignal;
+  resolvedPaths?: ResolvedPaths;
 }
 
 export async function runAgent(
@@ -53,7 +55,7 @@ export async function runAgent(
   task: string,
   options: RunAgentOptions = {},
 ): Promise<AgentResult> {
-  const { agents } = discoverAgents(cwd, options.agentScope ?? 'user');
+  const { agents } = discoverAgentsWithPackages(cwd, options.agentScope ?? 'user', options.resolvedPaths);
   const agent = agents.find((a) => a.name === agentName);
 
   if (!agent) {

package/extensions/subagent/index.ts

@@ -25,11 +25,14 @@ import { StringEnum } from '@mariozechner/pi-ai';
 import {
   type ExtensionAPI,
   type ExtensionCommandContext,
+  DefaultPackageManager,
   getAgentDir,
   getMarkdownTheme,
+  SettingsManager,
   withFileMutationQueue,
 } from '@mariozechner/pi-coding-agent';
-import { Container, Markdown, Spacer, Text } from '@mariozechner/pi-tui';
+import type { ResolvedPaths } from '@mariozechner/pi-coding-agent';
+import { Box, Container, Markdown, Spacer, Text } from '@mariozechner/pi-tui';
 import { Type } from '@sinclair/typebox';
 import {
   type AgentConfig,
@@ -37,8 +40,14 @@ import {
   type AgentSource,
   bundledAgentsDir,
   discoverAgents,
+  discoverAgentsWithPackages,
 } from './agents.js';
-import { formatDelegateUsage, parseDelegateArgs } from './delegate-args.js';
+import {
+  formatDelegateUsage,
+  formatRunAgentUsage,
+  parseDelegateArgs,
+  parseRunAgentArgs,
+} from './delegate-args.js';
 import { runAgent, runParallel } from './delegate-executor.js';
 import { buildSynthesisPrompt, extractRecentConversation } from './synthesis.js';
 import type {
@@ -178,6 +187,20 @@ interface UsageStats {
   turns: number;
 }
 
+interface RunAgentSummaryDetails {
+  agent: string;
+  agentSource: AgentSource;
+  agentScope: AgentScope;
+  sessionStrategy: string;
+  forked: boolean;
+  exitCode: number;
+  stopReason?: string;
+  errorMessage?: string;
+  usage: UsageStats;
+  task: string;
+  output: string;
+}
+
 interface SingleResult {
   agent: string;
   agentSource: AgentSource | 'unknown';
@@ -507,6 +530,26 @@ const SubagentParams = Type.Object({
   ),
 });
 
+/**
+ * Try to resolve package paths including the agents resource.
+ * Returns null if the pi version does not support ResolvedPaths.agents.
+ */
+async function tryResolvePackagePaths(cwd: string): Promise<ResolvedPaths | undefined> {
+  try {
+    const agentDir = getAgentDir();
+    const settingsManager = SettingsManager.create(cwd, agentDir);
+    const packageManager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+    const resolved = await packageManager.resolve();
+    // Check if this pi version has agents support
+    if ('agents' in resolved && Array.isArray((resolved as Record<string, unknown>).agents)) {
+      return resolved;
+    }
+  } catch {
+    // Incompatible pi version or missing API
+  }
+  return undefined;
+}
+
 export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: 'subagent',
@@ -521,7 +564,8 @@ export default function (pi: ExtensionAPI) {
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const agentScope: AgentScope = params.agentScope ?? 'user';
-      const discovery = discoverAgents(ctx.cwd, agentScope);
+      const resolvedPaths = await tryResolvePackagePaths(ctx.cwd);
+      const discovery = discoverAgentsWithPackages(ctx.cwd, agentScope, resolvedPaths);
       const agents = discovery.agents;
       const confirmProjectAgents = params.confirmProjectAgents ?? true;
 
@@ -1135,6 +1179,130 @@ export default function (pi: ExtensionAPI) {
       .join('\n\n');
   }
 
+  async function confirmProjectAgentsIfNeeded(
+    ctx: ExtensionCommandContext,
+    agents: AgentConfig[],
+    projectAgentsDir: string | null,
+    confirmProjectAgents: boolean,
+  ): Promise<boolean> {
+    if (!ctx.hasUI || !confirmProjectAgents || agents.length === 0) return true;
+
+    const names = Array.from(new Set(agents.map((agent) => agent.name))).join(', ');
+    const dir = projectAgentsDir ?? '(unknown)';
+    return ctx.ui.confirm(
+      'Run project-local agents?',
+      `Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
+    );
+  }
+
+  function buildRunAgentTask(conversation: string, explicitTask?: string): string | undefined {
+    const trimmedConversation = conversation.trim();
+    const trimmedTask = explicitTask?.trim();
+
+    if (trimmedTask && trimmedConversation) {
+      return `Assigned task:\n${trimmedTask}\n\nRelevant main-session context:\n${trimmedConversation}`;
+    }
+
+    if (trimmedTask) return trimmedTask;
+    if (trimmedConversation) {
+      return `Use the following main-session context to determine and complete the task:\n\n${trimmedConversation}`;
+    }
+
+    return undefined;
+  }
+
+  function formatRunAgentSummary(options: {
+    agent: AgentConfig;
+    agentScope: AgentScope;
+    task: string;
+    result: AgentResult;
+    forked: boolean;
+  }): string {
+    const { agent, agentScope, task, result, forked } = options;
+    const output = getFinalText(result).trim();
+    const usage = formatUsageStats(result.usage, result.model);
+    const failed = result.exitCode !== 0 || result.stopReason === 'error';
+    const status = failed ? 'failed' : 'completed';
+    const lines = [
+      '## Agent Run',
+      `- Agent: \`${agent.name}\``,
+      `- Source: ${agent.source}`,
+      `- Scope: ${agentScope}`,
+      `- Session strategy: ${agent.sessionStrategy ?? 'inline'}`,
+      `- Session handling: ${forked ? 'forked current branch at active entry' : 'inline in current session'}`,
+      `- Status: ${status}`,
+      '',
+      '## Task',
+      task,
+      '',
+      '## Output',
+      output || '_No output returned._',
+    ];
+
+    if (failed) {
+      const errorText = result.errorMessage?.trim() || result.stderr.trim();
+      if (errorText) {
+        lines.push('', '## Error', errorText);
+      }
+    }
+
+    if (usage) {
+      lines.push('', '## Usage', usage);
+    }
+
+    return lines.join('\n');
+  }
+
+  pi.registerMessageRenderer('run-agent-summary', (message, { expanded }, theme) => {
+    const details = message.details as RunAgentSummaryDetails | undefined;
+    if (!details) return new Text(typeof message.content === 'string' ? message.content : '', 0, 0);
+
+    const failed = details.exitCode !== 0 || details.stopReason === 'error';
+    const icon = failed ? theme.fg('error', '✗') : theme.fg('success', '✓');
+    const title = `${icon} ${theme.fg('toolTitle', theme.bold(details.agent))}${theme.fg('muted', ` (${details.agentSource})`)}`;
+    const modeLine = theme.fg(
+      'dim',
+      `${details.forked ? 'forked branch' : 'inline'} • ${details.agentScope} • ${details.sessionStrategy}`,
+    );
+    const usageLine = formatUsageStats(details.usage);
+    const outputPreview = details.output.trim() || '(no output)';
+
+    if (!expanded) {
+      const previewLines = outputPreview.split('\n').slice(0, 3).join('\n');
+      const text = [
+        title,
+        modeLine,
+        theme.fg('muted', `Task: ${details.task}`),
+        failed && details.errorMessage ? theme.fg('error', `Error: ${details.errorMessage}`) : previewLines,
+        usageLine ? theme.fg('dim', usageLine) : undefined,
+        theme.fg('muted', '(Ctrl+O to expand)'),
+      ]
+        .filter((line): line is string => Boolean(line))
+        .join('\n');
+      const box = new Box(1, 1, (text) => theme.bg('customMessageBg', text));
+      box.addChild(new Text(text, 0, 0));
+      return box;
+    }
+
+    const mdTheme = getMarkdownTheme();
+    const box = new Box(1, 1, (text) => theme.bg('customMessageBg', text));
+    box.addChild(new Text(title, 0, 0));
+    box.addChild(new Text(modeLine, 0, 0));
+    if (usageLine) box.addChild(new Text(theme.fg('dim', usageLine), 0, 0));
+    box.addChild(new Spacer(1));
+    box.addChild(new Text(theme.fg('muted', 'Task'), 0, 0));
+    box.addChild(new Text(theme.fg('text', details.task), 0, 0));
+    if (failed && details.errorMessage) {
+      box.addChild(new Spacer(1));
+      box.addChild(new Text(theme.fg('error', 'Error'), 0, 0));
+      box.addChild(new Text(theme.fg('error', details.errorMessage), 0, 0));
+    }
+    box.addChild(new Spacer(1));
+    box.addChild(new Text(theme.fg('muted', 'Output'), 0, 0));
+    box.addChild(new Markdown(outputPreview, 0, 0, mdTheme));
+    return box;
+  });
+
   async function executePhase(
     cwd: string,
     phase: PhaseDefinition,
@@ -1142,6 +1310,7 @@ export default function (pi: ExtensionAPI) {
     previousOutput: string,
     ctx: ExtensionCommandContext,
     agentScope: AgentScope,
+    resolvedPaths?: ResolvedPaths,
   ): Promise<{ results: AgentResult[]; output: string; aborted: boolean }> {
     const task = phase.taskTemplate
       .replace(/\{synthesis\}/g, synthesis)
@@ -1160,11 +1329,13 @@ export default function (pi: ExtensionAPI) {
           // Streaming updates happen per-message
         },
         phaseName: phase.name,
+        resolvedPaths,
       });
     } else {
       const result = await runAgent(cwd, phase.agents[0], task, {
         agentScope,
         phaseName: phase.name,
+        resolvedPaths,
       });
       results = [result];
     }
@@ -1300,6 +1471,114 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand('run-agent', {
+    description:
+      'Run a single agent directly — honors agent sessionStrategy metadata such as fork-at',
+    handler: async (args, ctx) => {
+      const parsed = parseRunAgentArgs(args);
+      if (!parsed.ok) {
+        ctx.ui.notify(parsed.error, 'warning');
+        return;
+      }
+
+      const { agentName, explicitTask, agentScope, confirmProjectAgents } = parsed.options;
+      if (!agentName) {
+        ctx.ui.notify(formatRunAgentUsage(), 'warning');
+        return;
+      }
+
+      const resolvedPaths = await tryResolvePackagePaths(ctx.cwd);
+      const discovery = discoverAgentsWithPackages(ctx.cwd, agentScope, resolvedPaths);
+      const agent = discovery.agents.find((candidate) => candidate.name === agentName);
+
+      if (!agent) {
+        const available = discovery.agents.map((candidate) => candidate.name).join(', ') || 'none';
+        ctx.ui.notify(`Unknown agent: "${agentName}". Available: ${available}`, 'warning');
+        return;
+      }
+
+      const requestedProjectAgents = agent.source === 'project' ? [agent] : [];
+      const approved = await confirmProjectAgentsIfNeeded(
+        ctx,
+        requestedProjectAgents,
+        discovery.projectAgentsDir,
+        confirmProjectAgents,
+      );
+      if (!approved) {
+        ctx.ui.notify('Run cancelled — project-local agents not approved.', 'info');
+        return;
+      }
+
+      const conversation = extractRecentConversation(ctx);
+      const task = buildRunAgentTask(conversation, explicitTask);
+      if (!task) {
+        ctx.ui.notify(`No conversation context and no task specified.\n\n${formatRunAgentUsage()}`, 'warning');
+        return;
+      }
+
+      let forked = false;
+      if (agent.sessionStrategy === 'fork-at') {
+        const leafId = ctx.sessionManager.getLeafId?.();
+        if (!leafId) {
+          ctx.ui.notify(
+            `Agent "${agent.name}" prefers fork-at, but the current session cannot be forked. Running inline instead.`,
+            'warning',
+          );
+        } else {
+          const forkCompat = ctx.fork as unknown as (
+            entryId: string,
+            options?: { position: 'at' },
+          ) => Promise<{ cancelled: boolean }>;
+          const forkResult = await forkCompat(leafId, { position: 'at' });
+          if (forkResult.cancelled) {
+            ctx.ui.notify(`Run cancelled — unable to fork session for "${agent.name}".`, 'info');
+            return;
+          }
+          forked = true;
+        }
+      }
+
+      ctx.ui.notify(
+        `Running agent: ${agent.name} [${agent.source}${forked ? ', forked' : ', inline'}]`,
+        'info',
+      );
+
+      const result = await runAgent(ctx.cwd, agent.name, task, { agentScope, resolvedPaths });
+      const failed = result.exitCode !== 0 || result.stopReason === 'error';
+      const output = getFinalText(result).trim();
+
+      ctx.ui.notify(
+        failed ? `Agent "${agent.name}" failed.` : `Agent "${agent.name}" complete.`,
+        failed ? 'error' : 'info',
+      );
+
+      pi.sendMessage({
+        customType: 'run-agent-summary',
+        content: formatRunAgentSummary({
+          agent,
+          agentScope,
+          task,
+          result,
+          forked,
+        }),
+        display: true,
+        details: {
+          agent: agent.name,
+          agentSource: agent.source,
+          agentScope,
+          sessionStrategy: agent.sessionStrategy ?? 'inline',
+          forked,
+          exitCode: result.exitCode,
+          stopReason: result.stopReason,
+          errorMessage: result.errorMessage,
+          usage: result.usage,
+          task,
+          output,
+        } satisfies RunAgentSummaryDetails,
+      });
+    },
+  });
+
   pi.registerCommand('delegate', {
     description:
       'Orchestrate subagent workflows — supports --scope, --workflow, and project-local agents',
@@ -1311,6 +1590,7 @@ export default function (pi: ExtensionAPI) {
       }
 
       const { explicitTask, agentScope, workflowId, confirmProjectAgents } = parsed.options;
+      const resolvedPaths = await tryResolvePackagePaths(ctx.cwd);
 
       // Step 1: Synthesize
       const conversation = extractRecentConversation(ctx);
@@ -1322,7 +1602,7 @@ export default function (pi: ExtensionAPI) {
       const prompt = buildSynthesisPrompt(conversation, explicitTask);
       ctx.ui.notify('⏳ Synthesizing task from conversation...', 'info');
 
-      const synthResult = await runAgent(ctx.cwd, 'planner', prompt, { agentScope });
+      const synthResult = await runAgent(ctx.cwd, 'planner', prompt, { agentScope, resolvedPaths });
       const synthesis = getFinalText(synthResult);
 
       if (!synthesis.trim()) {
@@ -1350,24 +1630,22 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      if ((agentScope === 'project' || agentScope === 'both') && confirmProjectAgents && ctx.hasUI) {
-        const discovery = discoverAgents(ctx.cwd, agentScope);
+      if (agentScope === 'project' || agentScope === 'both') {
+        const discovery = discoverAgentsWithPackages(ctx.cwd, agentScope, resolvedPaths);
         const requestedProjectAgents = workflow.phases
           .flatMap((phase) => phase.agents)
           .map((name) => discovery.agents.find((agent) => agent.name === name))
           .filter((agent): agent is AgentConfig => agent?.source === 'project');
 
-        if (requestedProjectAgents.length > 0) {
-          const names = Array.from(new Set(requestedProjectAgents.map((agent) => agent.name))).join(', ');
-          const dir = discovery.projectAgentsDir ?? '(unknown)';
-          const ok = await ctx.ui.confirm(
-            'Run project-local agents?',
-            `Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
-          );
-          if (!ok) {
-            ctx.ui.notify('Delegate cancelled — project-local agents not approved.', 'info');
-            return;
-          }
+        const ok = await confirmProjectAgentsIfNeeded(
+          ctx,
+          requestedProjectAgents,
+          discovery.projectAgentsDir,
+          confirmProjectAgents,
+        );
+        if (!ok) {
+          ctx.ui.notify('Delegate cancelled — project-local agents not approved.', 'info');
+          return;
         }
       }
 
@@ -1391,6 +1669,7 @@ export default function (pi: ExtensionAPI) {
           previousOutput,
           ctx,
           agentScope,
+          resolvedPaths,
         );
 
         const phase: PhaseResult = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Subagent tool and delegate orchestration for pi — isolated agents, parallel scouts, planning gates, and workflow presets",
   "keywords": [
     "pi-package"
@@ -28,6 +28,9 @@
     ],
     "prompts": [
       "./prompts"
+    ],
+    "agents": [
+      "./agents"
     ]
   },
   "devDependencies": {