@tintinweb/pi-subagents 0.4.0 → 0.4.3

package/CHANGELOG.md

@@ -5,6 +5,60 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.3] - 2026-03-13
+
+### Added
+- **Persistent agent memory** — new `memory` frontmatter field with three scopes: `"user"` (global `~/.pi/`), `"project"` (per-project `.pi/`), `"local"` (gitignored `.pi/`). Agents with write/edit tools get full read-write memory; read-only agents get a read-only fallback that injects existing MEMORY.md content without granting write access or creating directories.
+- **Git worktree isolation** — new `isolation: "worktree"` frontmatter field and Agent tool parameter. Creates a temporary `git worktree` so agents work on an isolated copy of the repo. On completion, changes are auto-committed to a `pi-agent-<id>` branch; clean worktrees are removed. Includes crash recovery via `pruneWorktrees()`.
+- **Skill preloading** — `skills` frontmatter now accepts a comma-separated list of skill names (e.g. `skills: planning, review`). Reads from `.pi/skills/` (project) then `~/.pi/skills/` (global), tries `.md`/`.txt`/bare extensions. Content injected into the system prompt as `# Preloaded Skill: {name}`.
+- **Tool denylist** — new `disallowed_tools` frontmatter field (e.g. `disallowed_tools: bash, write`). Blocks specified tools even if `builtinToolNames` or extensions would provide them. Enforced for both extension-enabled and extension-disabled agents.
+- **Prompt extras system** — new `PromptExtras` interface in `prompts.ts`; `buildAgentPrompt()` accepts optional memory and skill blocks appended in both `replace` and `append` modes.
+- `getMemoryTools()`, `getReadOnlyMemoryTools()` in `agent-types.ts`.
+- `buildMemoryBlock()`, `buildReadOnlyMemoryBlock()`, `isSymlink()`, `safeReadFile()` in `memory.ts`.
+- `preloadSkills()` in `skill-loader.ts`.
+- `createWorktree()`, `cleanupWorktree()`, `pruneWorktrees()` in `worktree.ts`.
+- `MemoryScope`, `IsolationMode` types; `memory`, `isolation`, `disallowedTools` fields on `AgentConfig`; `worktree`, `worktreeResult` fields on `AgentRecord`.
+- 177 total tests across 8 test files (41 new tests).
+
+### Fixed
+- **Read-only agents no longer escalated to read-write** — enabling `memory` on a read-only agent (e.g. Explore) previously auto-added `write`/`edit` tools. Now the runner detects write capability and branches: read-write agents get full memory tools, read-only agents get read-only memory prompt with only the `read` tool added.
+- **Denylist-aware memory detection** — write capability check now accounts for `disallowedTools`. An agent with `tools: write` + `disallowed_tools: write` correctly gets read-only memory instead of broken read-write instructions.
+- **Worktree requires commits** — repos with no commits (empty HEAD) are now rejected early with a warning instead of failing silently at `git worktree add`.
+- **Worktree failure warning** — when worktree creation fails, a warning is prepended to the agent's prompt instead of silently falling through to the main cwd.
+- **No force-branch overwrite** — worktree cleanup appends a timestamp suffix on branch name conflict instead of using `git branch -f`.
+
+### Security
+- **Whitelist name validation** — agent/skill names must match `^[a-zA-Z0-9][a-zA-Z0-9._-]*$`, max 128 chars. Rejects path traversal, leading dots, spaces, and special characters.
+- **Symlink protection** — `safeReadFile()` and `isSymlink()` reject symlinks in memory directories, MEMORY.md files, and skill files, preventing arbitrary file reads.
+- **Symlink-safe directory creation** — `ensureMemoryDir()` throws on symlinked directories.
+
+### Changed
+- `agent-runner.ts`: tool/extension/skill resolution moved before memory detection; `ctx.cwd` → `effectiveCwd` throughout.
+- `custom-agents.ts`: extracted `parseCsvField()` helper; added `csvListOptional()` and `parseMemory()`.
+- `skill-loader.ts`: uses `safeReadFile()` from `memory.ts` instead of raw `readFileSync`.
+- Agent tool schema updated with `isolation` parameter and help text for `memory`, `isolation`, `disallowed_tools`, and skill list.
+
+## [0.4.2] - 2026-03-12
+
+### Added
+- **Event bus** — agent lifecycle events emitted via `pi.events.emit()`, enabling other extensions to react to sub-agent activity:
+  - `subagents:created` — background agent registered (includes `id`, `type`, `description`, `isBackground`)
+  - `subagents:started` — agent transitions to running (includes queued→running)
+  - `subagents:completed` — agent finished successfully (includes `durationMs`, `tokens`, `toolUses`, `result`)
+  - `subagents:failed` — agent errored, stopped, or aborted (same payload as completed)
+  - `subagents:steered` — steering message sent to a running agent
+- `OnAgentStart` callback and `onStart` constructor parameter on `AgentManager`.
+- **Cross-package manager** now also exposes `spawn()` and `getRecord()` via the `Symbol.for("pi-subagents:manager")` global.
+
+## [0.4.1] - 2026-03-11
+
+### Fixed
+- **Graceful shutdown in headless mode** — the CLI now waits for all running and queued background agents to complete before exiting (`waitForAll` on `session_shutdown`). Previously, background agents could be silently killed mid-execution when the session ended. Only affects headless/non-interactive mode; interactive sessions already kept the process alive.
+
+### Added
+- `hasRunning()` / `waitForAll()` methods on `AgentManager`.
+- **Cross-package manager access** — agent manager exposed via `Symbol.for("pi-subagents:manager")` on `globalThis` for other extensions to check status or await completion.
+
 ## [0.4.0] - 2026-03-11
 
 ### Added
@@ -188,6 +242,9 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.4.3]: https://github.com/tintinweb/pi-subagents/compare/v0.4.2...v0.4.3
+[0.4.2]: https://github.com/tintinweb/pi-subagents/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/tintinweb/pi-subagents/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/tintinweb/pi-subagents/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/tintinweb/pi-subagents/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/tintinweb/pi-subagents/compare/v0.2.7...v0.3.0

package/README.md

@@ -23,6 +23,11 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Case-insensitive agent types** — `"explore"`, `"Explore"`, `"EXPLORE"` all work. Unknown types fall back to general-purpose with a note
 - **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
 - **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
+- **Persistent agent memory** — three scopes (project, local, user) with automatic read-only fallback for agents without write tools
+- **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
+- **Skill preloading** — inject named skill files from `.pi/skills/` into agent system prompts
+- **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
+- **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
 
 ## Install
 
@@ -138,13 +143,17 @@ All fields are optional — sensible defaults for everything.
 | `display_name` | — | Display name for UI (e.g. widget, agent list) |
 | `tools` | all 7 | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools |
 | `extensions` | `true` | Inherit MCP/extension tools. `false` to disable |
-| `skills` | `true` | Inherit skills from parent |
+| `skills` | `true` | Inherit skills from parent. Can be a comma-separated list of skill names to preload from `.pi/skills/` |
+| `memory` | — | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents |
+| `disallowed_tools` | — | Comma-separated tools to deny even if extensions provide them |
+| `isolation` | — | Set to `worktree` to run in an isolated git worktree |
 | `model` | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`) |
 | `thinking` | inherit | off, minimal, low, medium, high, xhigh |
 | `max_turns` | 50 | Max agentic turns before graceful shutdown |
 | `prompt_mode` | `replace` | `replace`: body is the full system prompt. `append`: body appended to parent's prompt (agent acts as a "parent twin" with optional extra instructions) |
 | `inherit_context` | `false` | Fork parent conversation into agent |
 | `run_in_background` | `false` | Run in background by default |
+| `isolation` | — | `worktree`: run in a temporary git worktree for full repo isolation |
 | `isolated` | `false` | No extension/MCP tools, only built-in |
 | `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
 
@@ -167,6 +176,7 @@ Launch a sub-agent.
 | `run_in_background` | boolean | no | Run without blocking |
 | `resume` | string | no | Agent ID to resume a previous session |
 | `isolated` | boolean | no | No extension/MCP tools |
+| `isolation` | `"worktree"` | no | Run in an isolated git worktree |
 | `inherit_context` | boolean | no | Fork parent conversation into agent |
 | `join_mode` | `"async"` \| `"group"` | no | Override join strategy for background completion notifications (default: smart) |
 
@@ -251,6 +261,77 @@ When background agents complete, they notify the main agent. The **join mode** c
 - Per-call: `Agent({ ..., join_mode: "async" })` overrides for that agent
 - Global default: `/agents` → Settings → Join mode
 
+## Events
+
+Agent lifecycle events are emitted via `pi.events.emit()` so other extensions can react:
+
+| Event | When | Key fields |
+|-------|------|------------|
+| `subagents:created` | Background agent registered | `id`, `type`, `description`, `isBackground` |
+| `subagents:started` | Agent transitions to running (including queued→running) | `id`, `type`, `description` |
+| `subagents:completed` | Agent finished successfully | `id`, `type`, `durationMs`, `tokens`, `toolUses`, `result` |
+| `subagents:failed` | Agent errored, stopped, or aborted | same as completed + `error`, `status` |
+| `subagents:steered` | Steering message sent | `id`, `message` |
+
+## Persistent Agent Memory
+
+Agents can have persistent memory across sessions. Set `memory` in frontmatter to enable:
+
+```yaml
+---
+memory: project   # project | local | user
+---
+```
+
+| Scope | Location | Use case |
+|-------|----------|----------|
+| `project` | `.pi/agent-memory/<name>/` | Shared across the team (committed) |
+| `local` | `.pi/agent-memory-local/<name>/` | Machine-specific (gitignored) |
+| `user` | `~/.pi/agent-memory/<name>/` | Global personal memory |
+
+Memory uses a `MEMORY.md` index file and individual memory files with frontmatter. Agents with write tools get full read-write access. **Read-only agents** (no `write`/`edit` tools) automatically get read-only memory — they can consume memories written by other agents but cannot modify them. This prevents unintended tool escalation.
+
+The `disallowed_tools` field is respected when determining write capability — an agent with `tools: write` + `disallowed_tools: write` correctly gets read-only memory.
+
+## Worktree Isolation
+
+Set `isolation: worktree` to run an agent in a temporary git worktree:
+
+```
+Agent({ subagent_type: "refactor", prompt: "...", isolation: "worktree" })
+```
+
+The agent gets a full, isolated copy of the repository. On completion:
+- **No changes:** worktree is cleaned up automatically
+- **Changes made:** changes are committed to a new branch (`pi-agent-<id>`) and returned in the result
+
+If the worktree cannot be created (not a git repo, no commits), the agent falls back to the main working directory with a warning.
+
+## Skill Preloading
+
+Skills can be preloaded as named files from `.pi/skills/` or `~/.pi/skills/`:
+
+```yaml
+---
+skills: api-conventions, error-handling
+---
+```
+
+Skill files (`.md`, `.txt`, or extensionless) are read and injected into the agent's system prompt. Project-level skills take priority over global ones. Symlinked skill files are rejected for security.
+
+## Tool Denylist
+
+Block specific tools from an agent even if extensions provide them:
+
+```yaml
+---
+tools: read, bash, grep, write
+disallowed_tools: write, edit
+---
+```
+
+This is useful for creating agents that inherit extension tools but should not have write access.
+
 ## Architecture
 
 ```
@@ -263,6 +344,9 @@ src/
   agent-manager.ts    # Agent lifecycle, concurrency queue, completion notifications
   group-join.ts       # Group join manager: batched completion notifications with timeout
   custom-agents.ts    # Load user-defined agents from .pi/agents/*.md
+  memory.ts           # Persistent agent memory (resolve, read, build prompt blocks)
+  skill-loader.ts     # Preload skill files from .pi/skills/
+  worktree.ts         # Git worktree isolation (create, cleanup, prune)
   prompts.ts          # Config-driven system prompt builder
   context.ts          # Parent conversation context for inherit_context
   env.ts              # Environment detection (git, platform)

package/dist/agent-manager.d.ts

@@ -0,0 +1,70 @@
+/**
+ * agent-manager.ts — Tracks agents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are queued and auto-started as running agents complete.
+ * Foreground agents bypass the queue (they block the parent anyway).
+ */
+import type { ExtensionContext, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { Model } from "@mariozechner/pi-ai";
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import { type ToolActivity } from "./agent-runner.js";
+import type { SubagentType, AgentRecord, ThinkingLevel } from "./types.js";
+export type OnAgentComplete = (record: AgentRecord) => void;
+interface SpawnOptions {
+    description: string;
+    model?: Model<any>;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    isBackground?: boolean;
+    /** Called on tool start/end with activity info (for streaming progress to UI). */
+    onToolActivity?: (activity: ToolActivity) => void;
+    /** Called on streaming text deltas from the assistant response. */
+    onTextDelta?: (delta: string, fullText: string) => void;
+    /** Called when the agent session is created (for accessing session stats). */
+    onSessionCreated?: (session: AgentSession) => void;
+}
+export declare class AgentManager {
+    private agents;
+    private cleanupInterval;
+    private onComplete?;
+    private maxConcurrent;
+    /** Queue of background agents waiting to start. */
+    private queue;
+    /** Number of currently running background agents. */
+    private runningBackground;
+    constructor(onComplete?: OnAgentComplete, maxConcurrent?: number);
+    /** Update the max concurrent background agents limit. */
+    setMaxConcurrent(n: number): void;
+    getMaxConcurrent(): number;
+    /**
+     * Spawn an agent and return its ID immediately (for background use).
+     * If the concurrency limit is reached, the agent is queued.
+     */
+    spawn(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: SpawnOptions): string;
+    /** Actually start an agent (called immediately or from queue drain). */
+    private startAgent;
+    /** Start queued agents up to the concurrency limit. */
+    private drainQueue;
+    /**
+     * Spawn an agent and wait for completion (foreground use).
+     * Foreground agents bypass the concurrency queue.
+     */
+    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: Omit<SpawnOptions, "isBackground">): Promise<AgentRecord>;
+    /**
+     * Resume an existing agent session with a new prompt.
+     */
+    resume(id: string, prompt: string, signal?: AbortSignal): Promise<AgentRecord | undefined>;
+    getRecord(id: string): AgentRecord | undefined;
+    listAgents(): AgentRecord[];
+    abort(id: string): boolean;
+    private cleanup;
+    /** Whether any agents are still running or queued. */
+    hasRunning(): boolean;
+    /** Wait for all running and queued agents to complete (including queued ones). */
+    waitForAll(): Promise<void>;
+    dispose(): void;
+}
+export {};

package/dist/agent-manager.js

@@ -0,0 +1,236 @@
+/**
+ * agent-manager.ts — Tracks agents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are queued and auto-started as running agents complete.
+ * Foreground agents bypass the queue (they block the parent anyway).
+ */
+import { randomUUID } from "node:crypto";
+import { runAgent, resumeAgent } from "./agent-runner.js";
+/** Default max concurrent background agents. */
+const DEFAULT_MAX_CONCURRENT = 4;
+export class AgentManager {
+    agents = new Map();
+    cleanupInterval;
+    onComplete;
+    maxConcurrent;
+    /** Queue of background agents waiting to start. */
+    queue = [];
+    /** Number of currently running background agents. */
+    runningBackground = 0;
+    constructor(onComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT) {
+        this.onComplete = onComplete;
+        this.maxConcurrent = maxConcurrent;
+        // Cleanup completed agents after 10 minutes (but keep sessions for resume)
+        this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+    }
+    /** Update the max concurrent background agents limit. */
+    setMaxConcurrent(n) {
+        this.maxConcurrent = Math.max(1, n);
+        // Start queued agents if the new limit allows
+        this.drainQueue();
+    }
+    getMaxConcurrent() {
+        return this.maxConcurrent;
+    }
+    /**
+     * Spawn an agent and return its ID immediately (for background use).
+     * If the concurrency limit is reached, the agent is queued.
+     */
+    spawn(pi, ctx, type, prompt, options) {
+        const id = randomUUID().slice(0, 17);
+        const abortController = new AbortController();
+        const record = {
+            id,
+            type,
+            description: options.description,
+            status: options.isBackground ? "queued" : "running",
+            toolUses: 0,
+            startedAt: Date.now(),
+            abortController,
+        };
+        this.agents.set(id, record);
+        const args = { pi, ctx, type, prompt, options };
+        if (options.isBackground && this.runningBackground >= this.maxConcurrent) {
+            // Queue it — will be started when a running agent completes
+            this.queue.push({ id, args });
+            return id;
+        }
+        this.startAgent(id, record, args);
+        return id;
+    }
+    /** Actually start an agent (called immediately or from queue drain). */
+    startAgent(id, record, { pi, ctx, type, prompt, options }) {
+        record.status = "running";
+        record.startedAt = Date.now();
+        if (options.isBackground)
+            this.runningBackground++;
+        const promise = runAgent(ctx, type, prompt, {
+            pi,
+            model: options.model,
+            maxTurns: options.maxTurns,
+            isolated: options.isolated,
+            inheritContext: options.inheritContext,
+            thinkingLevel: options.thinkingLevel,
+            signal: record.abortController.signal,
+            onToolActivity: (activity) => {
+                if (activity.type === "end")
+                    record.toolUses++;
+                options.onToolActivity?.(activity);
+            },
+            onTextDelta: options.onTextDelta,
+            onSessionCreated: (session) => {
+                record.session = session;
+                options.onSessionCreated?.(session);
+            },
+        })
+            .then(({ responseText, session, aborted, steered }) => {
+            // Don't overwrite status if externally stopped via abort()
+            if (record.status !== "stopped") {
+                record.status = aborted ? "aborted" : steered ? "steered" : "completed";
+            }
+            record.result = responseText;
+            record.session = session;
+            record.completedAt ??= Date.now();
+            if (options.isBackground) {
+                this.runningBackground--;
+                this.onComplete?.(record);
+                this.drainQueue();
+            }
+            return responseText;
+        })
+            .catch((err) => {
+            // Don't overwrite status if externally stopped via abort()
+            if (record.status !== "stopped") {
+                record.status = "error";
+            }
+            record.error = err instanceof Error ? err.message : String(err);
+            record.completedAt ??= Date.now();
+            if (options.isBackground) {
+                this.runningBackground--;
+                this.onComplete?.(record);
+                this.drainQueue();
+            }
+            return "";
+        });
+        record.promise = promise;
+    }
+    /** Start queued agents up to the concurrency limit. */
+    drainQueue() {
+        while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
+            const next = this.queue.shift();
+            const record = this.agents.get(next.id);
+            if (!record || record.status !== "queued")
+                continue;
+            this.startAgent(next.id, record, next.args);
+        }
+    }
+    /**
+     * Spawn an agent and wait for completion (foreground use).
+     * Foreground agents bypass the concurrency queue.
+     */
+    async spawnAndWait(pi, ctx, type, prompt, options) {
+        const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
+        const record = this.agents.get(id);
+        await record.promise;
+        return record;
+    }
+    /**
+     * Resume an existing agent session with a new prompt.
+     */
+    async resume(id, prompt, signal) {
+        const record = this.agents.get(id);
+        if (!record?.session)
+            return undefined;
+        record.status = "running";
+        record.startedAt = Date.now();
+        record.completedAt = undefined;
+        record.result = undefined;
+        record.error = undefined;
+        try {
+            const responseText = await resumeAgent(record.session, prompt, {
+                onToolActivity: (activity) => {
+                    if (activity.type === "end")
+                        record.toolUses++;
+                },
+                signal,
+            });
+            record.status = "completed";
+            record.result = responseText;
+            record.completedAt = Date.now();
+        }
+        catch (err) {
+            record.status = "error";
+            record.error = err instanceof Error ? err.message : String(err);
+            record.completedAt = Date.now();
+        }
+        return record;
+    }
+    getRecord(id) {
+        return this.agents.get(id);
+    }
+    listAgents() {
+        return [...this.agents.values()].sort((a, b) => b.startedAt - a.startedAt);
+    }
+    abort(id) {
+        const record = this.agents.get(id);
+        if (!record)
+            return false;
+        // Remove from queue if queued
+        if (record.status === "queued") {
+            this.queue = this.queue.filter(q => q.id !== id);
+            record.status = "stopped";
+            record.completedAt = Date.now();
+            return true;
+        }
+        if (record.status !== "running")
+            return false;
+        record.abortController?.abort();
+        record.status = "stopped";
+        record.completedAt = Date.now();
+        return true;
+    }
+    cleanup() {
+        const cutoff = Date.now() - 10 * 60_000;
+        for (const [id, record] of this.agents) {
+            if (record.status === "running" || record.status === "queued")
+                continue;
+            if ((record.completedAt ?? 0) >= cutoff)
+                continue;
+            // Dispose and clear session so memory can be reclaimed
+            if (record.session) {
+                record.session.dispose();
+                record.session = undefined;
+            }
+            this.agents.delete(id);
+        }
+    }
+    /** Whether any agents are still running or queued. */
+    hasRunning() {
+        return [...this.agents.values()].some(r => r.status === "running" || r.status === "queued");
+    }
+    /** Wait for all running and queued agents to complete (including queued ones). */
+    async waitForAll() {
+        // Loop because drainQueue respects the concurrency limit — as running
+        // agents finish they start queued ones, which need awaiting too.
+        while (true) {
+            this.drainQueue();
+            const pending = [...this.agents.values()]
+                .filter(r => r.status === "running" || r.status === "queued")
+                .map(r => r.promise)
+                .filter(Boolean);
+            if (pending.length === 0)
+                break;
+            await Promise.allSettled(pending);
+        }
+    }
+    dispose() {
+        clearInterval(this.cleanupInterval);
+        // Clear queue
+        this.queue = [];
+        for (const record of this.agents.values()) {
+            record.session?.dispose();
+        }
+        this.agents.clear();
+    }
+}

package/dist/agent-runner.d.ts

@@ -0,0 +1,60 @@
+/**
+ * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
+ */
+import { type AgentSession, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { Model } from "@mariozechner/pi-ai";
+import type { SubagentType, ThinkingLevel } from "./types.js";
+/** Get the default max turns value. */
+export declare function getDefaultMaxTurns(): number;
+/** Set the default max turns value (minimum 1). */
+export declare function setDefaultMaxTurns(n: number): void;
+/** Get the grace turns value. */
+export declare function getGraceTurns(): number;
+/** Set the grace turns value (minimum 1). */
+export declare function setGraceTurns(n: number): void;
+/** Info about a tool event in the subagent. */
+export interface ToolActivity {
+    type: "start" | "end";
+    toolName: string;
+}
+export interface RunOptions {
+    /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
+    pi: ExtensionAPI;
+    model?: Model<any>;
+    maxTurns?: number;
+    signal?: AbortSignal;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    /** Called on tool start/end with activity info. */
+    onToolActivity?: (activity: ToolActivity) => void;
+    /** Called on streaming text deltas from the assistant response. */
+    onTextDelta?: (delta: string, fullText: string) => void;
+    onSessionCreated?: (session: AgentSession) => void;
+}
+export interface RunResult {
+    responseText: string;
+    session: AgentSession;
+    /** True if the agent was hard-aborted (max_turns + grace exceeded). */
+    aborted: boolean;
+    /** True if the agent was steered to wrap up (hit soft turn limit) but finished in time. */
+    steered: boolean;
+}
+export declare function runAgent(ctx: ExtensionContext, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+/**
+ * Send a new prompt to an existing session (resume).
+ */
+export declare function resumeAgent(session: AgentSession, prompt: string, options?: {
+    onToolActivity?: (activity: ToolActivity) => void;
+    signal?: AbortSignal;
+}): Promise<string>;
+/**
+ * Send a steering message to a running subagent.
+ * The message will interrupt the agent after its current tool execution.
+ */
+export declare function steerAgent(session: AgentSession, message: string): Promise<void>;
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export declare function getAgentConversation(session: AgentSession): string;