@dreki-gg/pi-subagent 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @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

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

@@ -16,6 +16,7 @@ import type { ResolvedPaths } from '@mariozechner/pi-coding-agent';
 
 export type AgentScope = 'user' | 'project' | 'both';
 export type AgentSource = 'bundled' | 'user' | 'project' | 'package';
+export type AgentSessionStrategy = 'inline' | 'fork-at';
 
 export interface AgentConfig {
   name: string;
@@ -23,6 +24,7 @@ export interface AgentConfig {
   tools?: string[];
   model?: string;
   thinking?: string;
+  sessionStrategy?: AgentSessionStrategy;
   systemPrompt: string;
   source: AgentSource;
   filePath: string;
@@ -36,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[] = [];
 
@@ -79,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,
@@ -152,6 +162,7 @@ function loadAgentFromFile(filePath: 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,

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/index.ts

@@ -32,7 +32,7 @@ import {
   withFileMutationQueue,
 } from '@mariozechner/pi-coding-agent';
 import type { ResolvedPaths } from '@mariozechner/pi-coding-agent';
-import { Container, Markdown, Spacer, Text } from '@mariozechner/pi-tui';
+import { Box, Container, Markdown, Spacer, Text } from '@mariozechner/pi-tui';
 import { Type } from '@sinclair/typebox';
 import {
   type AgentConfig,
@@ -42,7 +42,12 @@ import {
   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 {
@@ -182,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';
@@ -1160,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,
@@ -1328,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',
@@ -1379,24 +1630,22 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      if ((agentScope === 'project' || agentScope === 'both') && confirmProjectAgents && ctx.hasUI) {
+      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;
         }
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.5.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"