@agnishc/edb-subagents 0.10.9 → 0.12.0

package/CHANGELOG.md

@@ -1,7 +1,26 @@
 # Changelog
 
+## [0.12.0] - 2026-05-22
+
+### Fixed
+- Add missing `unlinkSync` import
+
+### Added
+- Bridge context threading and promptGuidelines on tools
+
 ## [0.10.9] - 2026-05-18
 
+### Added
+- **edb-bridge integration** — injects `<bridge_parent_session>`, `<bridge_agent_id>`, and `<task_store_path>` XML tags into sub-agent system prompts at spawn time
+- **`bridgeContext` option** — new optional field on `SpawnOptions` and `RunOptions`; when present, bridge metadata is embedded into the sub-agent's prompt extras
+- **`bridge:ready` listener** — captures the parent session's broker session ID when edb-bridge connects
+- **`todo:store_path` listener** — captures the active edb-todo task store path for injection into sub-agents
+- **`bridgeContext` threading** — passes bridge context through `manager.spawn()`, `manager.spawnAndWait()`, and the `sharedRunOptions` in `agent-manager.ts`
+
+### Changed
+- `prompts.ts` `PromptExtras` gains optional `bridgeContext` field; when set, a `<bridge_context>` XML block is appended to the sub-agent system prompt
+- `agent-runner.ts` reads `options.bridgeContext` and populates `extras.bridgeContext` before building the agent prompt
+
 ## [0.10.8] - 2026-05-18
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agnishc/edb-subagents",
-	"version": "0.10.9",
+	"version": "0.12.0",
 	"description": "Pi extension: Claude Code-style autonomous sub-agents with live widget, parallel execution, mid-run steering, and custom agent types",
 	"keywords": [
 		"pi-package",

package/src/agent-manager.ts

@@ -34,6 +34,8 @@ interface SpawnArgs {
 
 interface SpawnOptions {
 	description: string;
+	/** Short memorable name (e.g. 'Quinn'). Shown in agent widget. Falls back to description if not set. */
+	agentName?: string;
 	model?: Model<any>;
 	maxTurns?: number;
 	isolated?: boolean;
@@ -54,6 +56,19 @@ interface SpawnOptions {
 	invocation?: AgentInvocation;
 	/** Parent abort signal — when aborted, the subagent is also stopped. */
 	signal?: AbortSignal;
+	/**
+	 * edb-bridge context: injected into sub-agent system prompt so it can communicate back.
+	 * Set by edb-subagents when bridgeSessionId is available.
+	 */
+	bridgeContext?: {
+		parentSessionId: string;
+		agentId: string;
+		storePath?: string;
+		taskId?: string;
+		agentIsSubtask?: boolean;
+	};
+	/** Called when the agent lifecycle changes: start, complete (success/steered/aborted), or failed (error/stopped). */
+	onTaskLifecycle?: (event: "start" | "complete" | "failed") => void;
 	/** 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. */
@@ -144,6 +159,8 @@ export class AgentManager {
 			id,
 			type,
 			description: options.description,
+			agentName: options.agentName,
+			taskId: options.bridgeContext?.taskId,
 			status: options.isBackground ? "queued" : "running",
 			toolUses: 0,
 			startedAt: Date.now(),
@@ -194,6 +211,11 @@ export class AgentManager {
 		record.status = "running";
 		record.startedAt = Date.now();
 		if (options.isBackground) this.runningBackground++;
+		try {
+			options.onTaskLifecycle?.("start");
+		} catch {
+			/* ignore */
+		}
 		this.onStart?.(record);
 
 		// Wire parent abort signal to stop the subagent when the parent is interrupted
@@ -218,6 +240,8 @@ export class AgentManager {
 			thinkingLevel: options.thinkingLevel,
 			cwd: worktreeCwd,
 			signal: record.abortController!.signal,
+			// Pass through edb-bridge context if provided
+			...(options.bridgeContext ? { bridgeContext: options.bridgeContext } : {}),
 			onToolActivity: (activity: ToolActivity) => {
 				if (activity.type === "end") record.toolUses++;
 				options.onToolActivity?.(activity);
@@ -303,6 +327,13 @@ export class AgentManager {
 					}
 				}
 
+				// Auto-lifecycle: notify task management regardless of foreground/background
+				try {
+					options.onTaskLifecycle?.("complete");
+				} catch {
+					/* ignore */
+				}
+
 				if (options.isBackground) {
 					this.runningBackground--;
 					try {
@@ -344,6 +375,13 @@ export class AgentManager {
 					}
 				}
 
+				// Auto-lifecycle: notify task management on failure
+				try {
+					options.onTaskLifecycle?.("failed");
+				} catch {
+					/* ignore */
+				}
+
 				if (options.isBackground) {
 					this.runningBackground--;
 					this.onComplete?.(record);
@@ -391,6 +429,58 @@ export class AgentManager {
 		return record;
 	}
 
+	/**
+	 * Resume an existing agent session with a new prompt in the background (non-blocking).
+	 * Returns immediately; the record's promise resolves when done.
+	 */
+	resumeInBackground(id: string, prompt: string): AgentRecord | undefined {
+		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;
+
+		record.promise = resumeAgent(record.session, prompt, {
+			onToolActivity: (activity) => {
+				if (activity.type === "end") record.toolUses++;
+			},
+			onAssistantUsage: (usage) => {
+				addUsage(record.lifetimeUsage, usage);
+			},
+			onCompaction: (info) => {
+				record.compactionCount++;
+				this.onCompact?.(record, info);
+			},
+		})
+			.then((responseText) => {
+				record.status = "completed";
+				record.result = responseText;
+				record.completedAt = Date.now();
+				try {
+					this.onComplete?.(record);
+				} catch {
+					/* ignore */
+				}
+				return responseText;
+			})
+			.catch((err) => {
+				record.status = "error";
+				record.error = err instanceof Error ? err.message : String(err);
+				record.completedAt = Date.now();
+				try {
+					this.onComplete?.(record);
+				} catch {
+					/* ignore */
+				}
+				return "";
+			});
+
+		return record;
+	}
+
 	/**
 	 * Resume an existing agent session with a new prompt.
 	 */

package/src/agent-runner.ts

@@ -2,6 +2,7 @@
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
 
+import { existsSync } from "node:fs";
 import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
@@ -15,6 +16,7 @@ import {
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import {
+	BUILTIN_TOOL_NAMES,
 	getAgentConfig,
 	getConfig,
 	getMemoryToolNames,
@@ -30,7 +32,40 @@ import { preloadSkills } from "./skill-loader.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
-const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent", "send_to_agent"];
+
+/**
+ * Extract parent session extension file paths from the parent's tool registry.
+ * These are passed to the sub-agent's DefaultResourceLoader as additionalExtensionPaths,
+ * so sub-agents get access to the same extension tools as the parent session
+ * (e.g., TaskCreate, TaskUpdate from edb-todo).
+ *
+ * Excludes:
+ * - Built-in / SDK tools (paths inside node_modules)
+ * - Synthetic paths (non-existent on disk)
+ * - Extensions where ALL registered tools are in the EXCLUDED_TOOL_NAMES list
+ *   (i.e., edb-subagents itself — only has Agent, get_subagent_result, steer_subagent)
+ */
+function extractParentExtensionPaths(pi: ExtensionAPI): string[] {
+	const excluded = new Set(EXCLUDED_TOOL_NAMES);
+	const pathTools = new Map<string, string[]>();
+
+	for (const tool of pi.getAllTools()) {
+		const p = tool.sourceInfo?.path ?? "";
+		if (!p) continue;
+		if (!pathTools.has(p)) pathTools.set(p, []);
+		pathTools.get(p)!.push(tool.name);
+	}
+
+	const result: string[] = [];
+	for (const [p, toolNames] of pathTools) {
+		if (p.includes("node_modules")) continue;
+		if (!existsSync(p)) continue;
+		if (toolNames.every((name) => excluded.has(name))) continue;
+		result.push(p);
+	}
+	return result;
+}
 
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns: number | undefined;
@@ -109,6 +144,17 @@ export interface RunOptions {
 	thinkingLevel?: ThinkingLevel;
 	/** Override working directory (e.g. for worktree isolation). */
 	cwd?: string;
+	/**
+	 * edb-bridge context: injected into the sub-agent's system prompt so edb-bridge + edb-todo
+	 * extensions in the sub-agent session can connect back to the orchestrator.
+	 */
+	bridgeContext?: {
+		parentSessionId: string;
+		agentId: string;
+		storePath?: string;
+		taskId?: string;
+		agentIsSubtask?: boolean;
+	};
 	/** Called on tool start/end with activity info. */
 	onToolActivity?: (activity: ToolActivity) => void;
 	/** Called on streaming text deltas from the assistant response. */
@@ -197,10 +243,21 @@ export async function runAgent(
 	// Build prompt extras (memory, skill preloading)
 	const extras: PromptExtras = {};
 
+	// Inject edb-bridge context if provided (enables ask_supervisor, notify_parent, shared task store)
+	if (options.bridgeContext) {
+		extras.bridgeContext = options.bridgeContext;
+	}
+
 	// Resolve extensions/skills: isolated overrides to false
 	const extensions = options.isolated ? false : config.extensions;
 	const skills = options.isolated ? false : config.skills;
 
+	// Extract parent session extension paths so sub-agents inherit the same extension
+	// tools (e.g. TaskCreate/TaskUpdate from edb-todo). Without this, sub-agents
+	// running in a session started with `-ne -e <path>` would have no extension tools
+	// because the DefaultResourceLoader doesn't know about the parent's explicit -e paths.
+	const parentExtensionPaths = extensions !== false ? extractParentExtensionPaths(options.pi) : [];
+
 	// Skill preloading: when skills is string[], preload their content into prompt
 	if (Array.isArray(skills)) {
 		const loaded = preloadSkills(skills, effectiveCwd);
@@ -259,7 +316,12 @@ export async function runAgent(
 	const loader = new DefaultResourceLoader({
 		cwd: effectiveCwd,
 		agentDir,
-		noExtensions: extensions === false,
+		// When we have explicit parent extension paths, suppress standard discovery so
+		// sub-agents don't accidentally pick up globally installed extensions the parent
+		// didn't opt into (e.g. when parent was started with -ne). Standard discovery
+		// is kept when there are no explicit paths (parent has no extensions).
+		noExtensions: extensions === false || parentExtensionPaths.length > 0,
+		additionalExtensionPaths: parentExtensionPaths,
 		noSkills,
 		noPromptTemplates: true,
 		noThemes: true,
@@ -282,7 +344,13 @@ export async function runAgent(
 		settingsManager: SettingsManager.create(effectiveCwd, agentDir),
 		modelRegistry: ctx.modelRegistry,
 		model,
-		tools: toolNames,
+		// Do NOT pass tools: [...] or noTools here. Passing tools: toolNames creates a
+		// hard allowedToolNames restriction that permanently blocks extension tools from
+		// the registry even after bindExtensions() registers them (setActiveToolsByName
+		// silently ignores names not in the registry). Using noTools: "all" empties the
+		// registry entirely. Instead, let the session use its default (full registry:
+		// all built-ins + all extension tools from the loader), then restrict via
+		// setActiveToolsByName after bindExtensions().
 		resourceLoader: loader,
 	};
 	if (thinkingLevel) {
@@ -294,21 +362,56 @@ export async function runAgent(
 	const baseSessionName = agentConfig?.name ?? type;
 	session.setSessionName(options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName);
 
+	// Bind extensions FIRST so that extension tools (e.g. TaskCreate from edb-todo)
+	// are registered before we query the active tool set. This ensures extension
+	// tools are available for filtering (vs. being invisible at query time).
+	await session.bindExtensions({
+		onError: (err) => {
+			options.onToolActivity?.({
+				type: "end",
+				toolName: `extension-error:${err.extensionPath}`,
+			});
+		},
+	});
+
 	// Build disallowed tools set from agent config
 	const disallowedSet = agentConfig?.disallowedTools ? new Set(agentConfig.disallowedTools) : undefined;
 
 	// Filter active tools: remove our own tools to prevent nesting,
-	// apply extension allowlist if specified, and apply disallowedTools denylist
+	// apply extension allowlist if specified, and apply disallowedTools denylist.
+	//
+	// SOURCE: Use extensionRunner.getAllRegisteredTools() for extension tools — this
+	// bypasses any session-level allowlist restriction and gives us ALL tools registered
+	// by extensions. Combined with BUILTIN_TOOL_NAMES we get a complete picture.
+	//
+	// createAgentSession is called without tools/noTools so the session uses its default
+	// (full registry, all built-ins + extension tools from the loader, no allowlist).
+	// setActiveToolsByName then restricts to exactly what this agent type should have.
+	//
+	// Built-in tools (bash, read, edit, write, grep, find, ls) are gated by the
+	// per-agent builtinToolNames config. Extension tools (TaskCreate, ask_supervisor…)
+	// are gated by the extensions config (true = all, string[] = allowlist, false = none).
 	if (extensions !== false) {
 		const builtinToolNameSet = new Set(toolNames);
-		const activeTools = session.getActiveToolNames().filter((t) => {
+		const allBuiltins = new Set(BUILTIN_TOOL_NAMES);
+		// Get all extension tools from the extension runner (not filtered by any allowlist)
+		const registeredExtensionToolNames = session.extensionRunner
+			.getAllRegisteredTools()
+			.map((t) => t.definition.name);
+		// Combine: built-in tools + all registered extension tools
+		const allKnown = [...new Set([...BUILTIN_TOOL_NAMES, ...registeredExtensionToolNames])];
+		const activeTools = allKnown.filter((t) => {
 			if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-			if (disallowedSet?.has(t)) return false;
-			if (builtinToolNameSet.has(t)) return true;
+			// Built-in tools: respect the per-agent builtinToolNames allowlist
+			if (allBuiltins.has(t)) return builtinToolNameSet.has(t);
+			// Extension tools: whitelist (allowed_tools) wins over blacklist (disallowed_tools)
 			if (Array.isArray(extensions)) {
+				// Whitelist mode — disallowedTools is ignored
 				return extensions.some((ext) => t.startsWith(ext) || t.includes(ext));
 			}
-			return true;
+			// Blacklist mode — exclude disallowed tools
+			if (disallowedSet?.has(t)) return false;
+			return true; // extensions === true → include all extension tools
 		});
 		session.setActiveToolsByName(activeTools);
 	} else if (disallowedSet) {
@@ -317,19 +420,6 @@ export async function runAgent(
 		session.setActiveToolsByName(activeTools);
 	}
 
-	// Bind extensions so that session_start fires and extensions can initialize
-	// (e.g. loading credentials, setting up state). Placed after tool filtering
-	// so extension-provided skills/prompts from extendResourcesFromExtensions()
-	// respect the active tool set. All ExtensionBindings fields are optional.
-	await session.bindExtensions({
-		onError: (err) => {
-			options.onToolActivity?.({
-				type: "end",
-				toolName: `extension-error:${err.extensionPath}`,
-			});
-		},
-	});
-
 	options.onSessionCreated?.(session);
 
 	// Track turns for graceful max_turns enforcement

package/src/custom-agents.ts

@@ -54,9 +54,12 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
 			name,
 			displayName: str(fm.display_name),
 			description: str(fm.description) ?? name,
+			context: str(fm.context),
 			builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
 			disallowedTools: csvListOptional(fm.disallowed_tools),
-			extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+			// allowed_tools: whitelist for extension tools (wins over disallowed_tools when both set)
+			// extensions: legacy field — string[] format is treated as allowed_tools whitelist
+			extensions: parseExtensions(fm.allowed_tools ?? fm.extensions),
 			skills: inheritField(fm.skills ?? fm.inherit_skills),
 			model: str(fm.model),
 			fallbackModels: csvListOptional(fm.fallback_models),
@@ -138,3 +141,22 @@ function inheritField(val: unknown): true | string[] | false {
 	const items = csvList(val, []);
 	return items.length > 0 ? items : false;
 }
+
+/**
+ * Parse the extensions/allowed_tools field.
+ * - undefined/null/true → all extension tools (true)
+ * - false/"none" → no extension tools (false)
+ * - "TaskCreate, ask_supervisor" → whitelist of tool name patterns (string[])
+ * - absolute path (legacy executor.md style) → treat as true (path-based extensions
+ *   are handled by extractParentExtensionPaths; ignore the path here)
+ */
+function parseExtensions(val: unknown): true | string[] | false {
+	if (val === undefined || val === null || val === true) return true;
+	if (val === false || val === "none") return false;
+	// Legacy: absolute path string → treat as "all extensions enabled"
+	if (typeof val === "string" && (val.startsWith("/") || val.startsWith(".") || val.includes("node_modules"))) {
+		return true;
+	}
+	const items = csvList(val, []);
+	return items.length > 0 ? items : true;
+}

package/src/default-agents.ts

@@ -15,6 +15,8 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
 			name: "general-purpose",
 			displayName: "Agent",
 			description: "General-purpose agent for complex, multi-step tasks",
+			context:
+				"Use for any multi-step task that requires reasoning, writing code, or making changes. The default choice when no specialized agent fits.",
 			// builtinToolNames omitted — means "all available tools" (resolved at lookup time)
 			// inheritContext / runInBackground / isolated omitted — strategy fields, callers decide per-call.
 			// Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
@@ -31,6 +33,8 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
 			name: "Explore",
 			displayName: "Explore",
 			description: "Fast codebase exploration agent (read-only)",
+			context:
+				"Use when you need to understand an unfamiliar codebase, find where something is implemented, or answer 'where is X' / 'how does Y work' questions. Read-only, fast, and cheap.",
 			builtinToolNames: READ_ONLY_TOOLS,
 			extensions: true,
 			skills: true,
@@ -73,6 +77,8 @@ Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find,
 			name: "Plan",
 			displayName: "Plan",
 			description: "Software architect for implementation planning (read-only)",
+			context:
+				"Use when you need a detailed implementation plan before writing code. Analyzes the codebase and produces a step-by-step plan without making any changes.",
 			builtinToolNames: READ_ONLY_TOOLS,
 			extensions: true,
 			skills: true,

package/src/index.ts

@@ -5,6 +5,7 @@
  *   Agent             — LLM-callable: spawn a sub-agent
  *   get_subagent_result  — LLM-callable: check background agent status/result
  *   steer_subagent       — LLM-callable: send a steering message to a running agent
+ *   send_to_agent        — LLM-callable: send a follow-up to a completed agent (context preserved)
  *
  * Commands:
  *   /agents                 — Interactive agent management menu
@@ -518,6 +519,63 @@ export default function (pi: ExtensionAPI) {
 	// --- Cross-extension RPC via pi.events ---
 	let currentCtx: ExtensionContext | undefined;
 
+	// edb-bridge + edb-todo integration: track current session's bridge ID and todo store path
+	let bridgeSessionId: string | undefined;
+	let todoStorePath: string | undefined;
+
+	// Promise that resolves when bridge:ready fires (or immediately if already ready).
+	// Used to avoid a race where a sub-agent is spawned before the bridge connects.
+	let bridgeReadyResolve: (() => void) | undefined;
+	const bridgeReadyPromise = new Promise<void>((resolve) => {
+		bridgeReadyResolve = resolve;
+	});
+
+	pi.events.on("bridge:ready", (payload: unknown) => {
+		const p = payload as { sessionId?: string } | undefined;
+		if (p?.sessionId) {
+			bridgeSessionId = p.sessionId;
+			bridgeReadyResolve?.();
+		}
+	});
+
+	pi.events.on("todo:store_path", (payload: unknown) => {
+		const p = payload as { path?: string } | undefined;
+		if (p?.path) todoStorePath = p.path;
+	});
+
+	/**
+	 * Read a task from the shared task store (synchronous, best-effort).
+	 * Returns undefined if the store is not available or the task doesn't exist.
+	 */
+	function readTaskFromStore(
+		taskId: string,
+	): { parentId?: string; status?: string; blockQuestion?: string; blockMessageId?: string } | undefined {
+		if (!todoStorePath) return undefined;
+		try {
+			const raw = readFileSync(todoStorePath, "utf-8");
+			const data = JSON.parse(raw) as {
+				tasks?: Array<{
+					id: string;
+					parentId?: string;
+					status?: string;
+					blockQuestion?: string;
+					blockMessageId?: string;
+				}>;
+			};
+			return data.tasks?.find((t) => t.id === taskId);
+		} catch {
+			return undefined;
+		}
+	}
+
+	/**
+	 * Update a task via pi.events — edb-todo handles the write.
+	 * Fires "todo:update_task" which edb-todo listens for and applies synchronously.
+	 */
+	function updateTask(taskId: string, fields: { status?: string; owner?: string }): void {
+		pi.events.emit("todo:update_task", { taskId, fields });
+	}
+
 	// ---- Subagent scheduler ----
 	// Session-scoped: store is constructed inside session_start once sessionId
 	// is available. Mirrors pi-chonky-tasks's session-scoped task store —
@@ -660,21 +718,21 @@ export default function (pi: ExtensionAPI) {
 		const defaultNames = getDefaultAgentNames().filter((n) => getAgentConfig(n)?.enabled !== false);
 		const userNames = getUserAgentNames().filter((n) => getAgentConfig(n)?.enabled !== false);
 
-		const defaultDescs = defaultNames.map((name) => {
+		const formatAgent = (name: string, isDefault: boolean) => {
 			const cfg = getAgentConfig(name);
-			const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
-			return `- ${name}: ${cfg?.description ?? name}${modelSuffix}`;
-		});
-
-		const customDescs = userNames.map((name) => {
-			const cfg = getAgentConfig(name);
-			return `- ${name}: ${cfg?.description ?? name}`;
-		});
+			const modelSuffix = isDefault && cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+			const desc = `- ${name}: ${cfg?.description ?? name}${modelSuffix}`;
+			// Include context block if defined — tells the orchestrator when/why to use this agent
+			if (cfg?.context) {
+				return `${desc}\n  When to use: ${cfg.context.trim()}`;
+			}
+			return desc;
+		};
 
 		return [
 			"Default agents:",
-			...defaultDescs,
-			...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
+			...defaultNames.map((n) => formatAgent(n, true)),
+			...(userNames.length > 0 ? ["", "Custom agents:", ...userNames.map((n) => formatAgent(n, false))] : []),
 			"",
 			`Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
 		].join("\n");
@@ -746,6 +804,7 @@ Guidelines:
 - Use run_in_background for work you don't need immediately. You will be notified when it completes.
 - Use resume with an agent ID to continue a previous agent's work.
 - Use steer_subagent to send mid-run messages to a running background agent.
+- Use send_to_agent to follow up with a completed agent (preserves full conversation context).
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.
@@ -810,6 +869,23 @@ Guidelines:
 							'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
 					}),
 				),
+				task_id: Type.Optional(
+					Type.String({
+						description:
+							"Optional task ID from the shared task store to associate with this agent. " +
+							"When set: the agent auto-updates its task status (in_progress on start, completed/failed on finish), " +
+							"the agent's system prompt is given task lifecycle instructions, " +
+							"and subtask creation follows the two-layer rule (top-level tasks can create subtasks; subtasks cannot).",
+					}),
+				),
+				agent_name: Type.Optional(
+					Type.String({
+						description:
+							"A short, memorable name for this agent (e.g. 'Quinn', 'Atlas', 'Hex'). " +
+							"Shown in the task widget as [name] when the agent owns a task. " +
+							"Separate from description (which is the task summary). Keep it 1-2 words, evocative of the role.",
+					}),
+				),
 				...scheduleParam,
 			}),
 			promptSnippet: "Launch a specialized subagent to autonomously handle a complex multi-step task",
@@ -911,9 +987,19 @@ Guidelines:
 			// ---- Execute ----
 
 			execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+				// Extract extended params — task_id and agent_name are optional Agent tool params
+				// not reflected in the TypeBox static type, accessed via explicit cast here.
+				const taskId = (params as any).task_id as string | undefined;
+				const agentName = (params as any).agent_name as string | undefined;
+
 				// Ensure we have UI context for widget rendering
 				widget.setUICtx(ctx.ui as UICtx);
 
+				// Wait for bridge:ready (up to 3s) to avoid race where bridge hasn't connected yet
+				if (!bridgeSessionId) {
+					await Promise.race([bridgeReadyPromise, new Promise<void>((res) => setTimeout(res, 3000))]);
+				}
+
 				// Reload custom agents so new .pi/agents/*.md files are picked up without restart
 				reloadCustomAgents();
 
@@ -1065,6 +1151,7 @@ Guidelines:
 					try {
 						id = manager.spawn(pi, ctx, subagentType, params.prompt, {
 							description: params.description,
+							agentName: agentName,
 							model,
 							fallbackModels: params.fallback_models as string[] | undefined,
 							maxTurns: effectiveMaxTurns,
@@ -1074,6 +1161,33 @@ Guidelines:
 							isBackground: true,
 							isolation,
 							invocation: agentInvocation,
+							// edb-bridge + edb-todo: inject orchestrator context into sub-agent
+							...(bridgeSessionId
+								? {
+										bridgeContext: {
+											parentSessionId: bridgeSessionId,
+											agentId: String(agentName ?? params.description ?? subagentType),
+											storePath: todoStorePath,
+											taskId: taskId,
+											agentIsSubtask: taskId ? !!readTaskFromStore(taskId!)?.parentId : undefined,
+										},
+									}
+								: {}),
+							// Auto task lifecycle
+							...(taskId
+								? {
+										onTaskLifecycle: (event: "start" | "complete" | "failed") => {
+											const agentId = String(agentName ?? params.description ?? subagentType);
+											if (event === "start") {
+												updateTask(taskId, { status: "in_progress", owner: agentId });
+											} else if (event === "complete") {
+												updateTask(taskId, { status: "completed", owner: agentId });
+											} else {
+												updateTask(taskId, { status: "failed", owner: agentId });
+											}
+										},
+									}
+								: {}),
 							...bgCallbacks,
 						});
 					} catch (err) {
@@ -1122,6 +1236,9 @@ Guidelines:
 							`Description: ${params.description}\n` +
 							(record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
 							(isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
+							(!bridgeSessionId
+								? `\nNote: edb-bridge not connected — ask_supervisor and notify_parent will not work.\n`
+								: "") +
 							`\nYou will be notified when this agent completes.\n` +
 							`Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
 							`Do not duplicate this agent's work.`,
@@ -1180,6 +1297,7 @@ Guidelines:
 				try {
 					record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
 						description: params.description,
+						agentName: agentName,
 						model,
 						fallbackModels: params.fallback_models as string[] | undefined,
 						maxTurns: effectiveMaxTurns,
@@ -1189,6 +1307,33 @@ Guidelines:
 						isolation,
 						invocation: agentInvocation,
 						signal,
+						// edb-bridge + edb-todo: inject orchestrator context into sub-agent
+						...(bridgeSessionId
+							? {
+									bridgeContext: {
+										parentSessionId: bridgeSessionId,
+										agentId: String(agentName ?? params.description ?? "agent"),
+										storePath: todoStorePath,
+										taskId: taskId,
+										agentIsSubtask: taskId ? !!readTaskFromStore(taskId!)?.parentId : undefined,
+									},
+								}
+							: {}),
+						// Auto task lifecycle
+						...(taskId
+							? {
+									onTaskLifecycle: (event: "start" | "complete" | "failed") => {
+										const agentId = String(agentName ?? params.description ?? "agent");
+										if (event === "start") {
+											updateTask(taskId, { status: "in_progress", owner: agentId });
+										} else if (event === "complete") {
+											updateTask(taskId, { status: "completed", owner: agentId });
+										} else {
+											updateTask(taskId, { status: "failed", owner: agentId });
+										}
+									},
+								}
+							: {}),
 						...fgCallbacks,
 					});
 				} catch (err) {
@@ -1234,7 +1379,8 @@ Guidelines:
 			name: "get_subagent_result",
 			label: "Get Agent Result",
 			description:
-				"Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
+				"Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.\n\n" +
+				"If the agent has called ask_supervisor and is waiting for your answer, wait: true will detect this and return the question and message_id immediately instead of blocking.",
 			parameters: Type.Object({
 				agent_id: Type.String({
 					description: "The agent ID to check.",
@@ -1259,6 +1405,26 @@ Guidelines:
 				}
 
 				// Wait for completion if requested.
+				// Check if the agent's linked task is blocked (waiting for answer_subagent).
+				// If so, waiting would cause a deadlock — return immediately with the question.
+				if (params.wait && record.status === "running" && record.taskId && todoStorePath) {
+					try {
+						const task = readTaskFromStore(record.taskId);
+						if (task && (task as any).status === "blocked" && (task as any).blockQuestion) {
+							const q = (task as any).blockQuestion as string;
+							const msgId = (task as any).blockMessageId as string | undefined;
+							return textResult(
+								`Agent is blocked waiting for your answer.\n\n` +
+									`Question: "${q}"\n\n` +
+									(msgId ? `Call: answer_subagent({ message_id: "${msgId}", answer: "..." })\n\n` : "") +
+									`After answering, call get_subagent_result again to wait for completion.`,
+							);
+						}
+					} catch {
+						/* ignore — best-effort check */
+					}
+				}
+
 				// Pre-mark resultConsumed BEFORE awaiting: onComplete fires inside .then()
 				// (attached earlier at spawn time) and always runs before this await resumes.
 				// Setting the flag here prevents a redundant follow-up notification.
@@ -1371,6 +1537,72 @@ Guidelines:
 		}),
 	);
 
+	// ---- send_to_agent tool ----
+
+	pi.registerTool(
+		defineTool({
+			name: "send_to_agent",
+			label: "Send to Agent",
+			description:
+				"Send a follow-up message to a completed (or running) agent, continuing its existing session. " +
+				"The agent retains its full conversation context — no context is lost. " +
+				"Use this instead of spawning a new agent when you want to build on prior work. " +
+				"Use run_in_background: true to fire and check later via get_subagent_result.",
+			parameters: Type.Object({
+				agent_id: Type.String({
+					description: "The agent ID to send the message to.",
+				}),
+				message: Type.String({
+					description: "The follow-up message / next task for the agent.",
+				}),
+				run_in_background: Type.Optional(
+					Type.Boolean({
+						description:
+							"If true, returns immediately with the agent ID. Use get_subagent_result to collect the response later. " +
+							"Default: false (waits for the agent to finish and returns its response).",
+					}),
+				),
+			}),
+			promptSnippet: "Send a follow-up message to a previously completed agent (preserves full context)",
+			execute: async (_toolCallId, params, signal, _onUpdate, _ctx) => {
+				const record = manager.getRecord(params.agent_id);
+				if (!record) {
+					return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
+				}
+				if (!record.session) {
+					return textResult(
+						`Agent "${params.agent_id}" has no active session (status: ${record.status}). ` +
+							"It may have been cleaned up after 10 minutes of inactivity.",
+					);
+				}
+				if (record.status === "running") {
+					return textResult(
+						`Agent "${params.agent_id}" is currently running. ` +
+							"Use steer_subagent to redirect it mid-run, or wait for it to finish first.",
+					);
+				}
+
+				if (params.run_in_background) {
+					const updated = manager.resumeInBackground(params.agent_id, params.message);
+					if (!updated) {
+						return textResult(`Failed to resume agent "${params.agent_id}" in background.`);
+					}
+					return textResult(
+						`Message sent to agent ${params.agent_id} (running in background). ` +
+							"Call get_subagent_result to collect the response when ready.",
+					);
+				}
+
+				// Foreground: wait for response
+				const updated = await manager.resume(params.agent_id, params.message, signal);
+				if (!updated) {
+					return textResult(`Failed to resume agent "${params.agent_id}".`);
+				}
+				return textResult(updated.result?.trim() || updated.error?.trim() || "No output.");
+			},
+		}),
+	);
+
 	// ---- /agents interactive menu ----
 
 	const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");

package/src/prompts.ts

@@ -10,6 +10,17 @@ export interface PromptExtras {
 	memoryBlock?: string;
 	/** Preloaded skill contents to inject. */
 	skillBlocks?: { name: string; content: string }[];
+	/**
+	 * edb-bridge context for sub-agent communication.
+	 * Injected as XML tags so sub-agent's edb-bridge and edb-todo extensions can read it.
+	 */
+	bridgeContext?: {
+		parentSessionId: string; // broker session ID of the parent
+		agentId: string; // edb-subagents agent ID
+		storePath?: string; // parent's edb-todo task store file path
+		taskId?: string; // assigned task ID for this agent
+		agentIsSubtask?: boolean; // true = already a subtask (depth 1) — no further subtasks allowed
+	};
 }
 
 /**
@@ -50,6 +61,19 @@ Platform: ${env.platform}`;
 			extraSections.push(`\n# Preloaded Skill: ${skill.name}\n${skill.content}`);
 		}
 	}
+	// edb-bridge context: inject XML tags so sub-agent extensions can read parent session info
+	if (extras?.bridgeContext) {
+		const { parentSessionId, agentId, storePath, taskId, agentIsSubtask } = extras.bridgeContext;
+		const storeTag = storePath ? `\n<task_store_path>${storePath}</task_store_path>` : "";
+		const taskTag = taskId ? `\n<assigned_task_id>${taskId}</assigned_task_id>` : "";
+		extraSections.push(
+			`<bridge_context>\n<bridge_parent_session>${parentSessionId}</bridge_parent_session>\n<bridge_agent_id>${agentId}</bridge_agent_id>${storeTag}${taskTag}\n</bridge_context>`,
+		);
+		// Task context instructions — only when task_id was provided
+		if (taskId) {
+			extraSections.push(buildTaskContextBlock(taskId, agentId, agentIsSubtask ?? false));
+		}
+	}
 	const extrasSuffix = extraSections.length > 0 ? `\n\n${extraSections.join("\n")}` : "";
 
 	if (config.promptMode === "append") {
@@ -98,3 +122,29 @@ const genericBase = `# Role
 You are a general-purpose coding agent for complex, multi-step tasks.
 You have full access to read, write, edit files, and execute commands.
 Do what has been asked; nothing more, nothing less.`;
+
+/**
+ * Build the task context block injected when a task_id is assigned at spawn time.
+ *
+ * Tells the sub-agent:
+ * - Its assigned task ID and how to update it
+ * - Whether it can create subtasks (depth-0 task: yes; depth-1 subtask: no)
+ * - That depth-1 agents must not create further subtasks (two-layer rule)
+ */
+function buildTaskContextBlock(taskId: string, agentId: string, agentIsSubtask: boolean): string {
+	const subtaskSection = agentIsSubtask
+		? `**Subtasks:** You are already a subtask (${taskId}). Do NOT create further subtasks (parentId is not allowed). You are at the maximum nesting depth. If you need internal tracking, you may use TaskCreate without parentId — those tasks will not appear in the orchestrator's widget.`
+		: `**Subtasks (optional):** You may break your work into subtasks visible to the orchestrator:\n  TaskCreate({ content: "...", parentId: "${taskId}" })\n  Update them as you work: TaskUpdate({ id: "<subtask-id>", status: "in_progress" })`;
+
+	return `## Your Assigned Task
+You have been assigned task **${taskId}**.
+
+**Lifecycle (required — the orchestrator tracks these):**
+1. When you begin: \`TaskUpdate({ id: "${taskId}", status: "in_progress", owner: "${agentId}" })\`
+2. Optionally set progress: \`TaskUpdate({ id: "${taskId}", activeForm: "Doing X..." })\`
+3. When done: \`TaskUpdate({ id: "${taskId}", status: "completed", owner: "${agentId}" })\`
+4. If you need clarification from the orchestrator: \`ask_supervisor({ question: "..." })\` — this will block you until answered.
+5. For progress updates: \`notify_parent({ message: "..." })\` — task_id is auto-injected, updates the widget spinner text.
+
+${subtaskSection}`;
+}

package/src/types.ts

@@ -55,6 +55,12 @@ export interface AgentConfig {
 	enabled?: boolean;
 	/** Where this agent was loaded from */
 	source?: "default" | "project" | "global";
+	/**
+	 * Usage context — when and why to use this agent.
+	 * Injected into the main agent's system prompt so it knows which agent to spawn for what tasks.
+	 * Example: "Use when exploring an unfamiliar codebase to find where something is implemented."
+	 */
+	context?: string;
 }
 
 export type JoinMode = "async" | "group" | "smart";
@@ -63,6 +69,10 @@ export interface AgentRecord {
 	id: string;
 	type: SubagentType;
 	description: string;
+	/** Short memorable name given by the orchestrator (e.g. 'Quinn'). Shown in widget alongside description. */
+	agentName?: string;
+	/** Linked task ID in the shared task store. Used for blocked-state check in get_subagent_result. */
+	taskId?: string;
 	status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
 	result?: string;
 	error?: string;

package/src/ui/agent-widget.ts

@@ -273,6 +273,7 @@ export class AgentWidget {
 			type: SubagentType;
 			status: string;
 			description: string;
+			agentName?: string;
 			toolUses: number;
 			startedAt: number;
 			completedAt?: number;
@@ -312,7 +313,7 @@ export class AgentWidget {
 		parts.push(duration);
 
 		const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
-		return `${icon} ${theme.fg("dim", name)}${modeTag}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
+		return `${icon} ${theme.fg("dim", name)}${modeTag}${a.agentName ? `  ${theme.fg("dim", a.agentName)}` : ""}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
 	}
 
 	/**
@@ -373,7 +374,7 @@ export class AgentWidget {
 			runningLines.push([
 				truncate(
 					theme.fg("dim", "├─") +
-						` ${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`,
+						` ${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}${a.agentName ? `  ${theme.fg("accent", theme.bold(a.agentName))}` : ""}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`,
 				),
 				truncate(theme.fg("dim", "│  ") + theme.fg("dim", `  ⎿  ${activity}`)),
 			]);