@hheei/pi-subagents 0.1.2 → 0.2.3

package/dist/session-bootstrap.js

@@ -2,19 +2,33 @@ import { randomUUID } from "node:crypto";
 import { open, readdir, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "@hheei/pi-ext-core";
 import { resolveAgent } from "./agent-resolver.js";
-import { isRecord, isSessionId } from "./domain.js";
+import { builtinAgentToolProblem } from "./builtin-agents.js";
+import { isSessionId } from "./domain.js";
 import { assembleChildPrompt, resolveBridgeExtensionPath, resolvePiInvocation, } from "./launch-spec.js";
+import { formatSessionReferencePrompt } from "./session-fork.js";
 /** Bounded read for a session header; the first line holds the whole identity of the file. */
 const HEADER_READ_BYTES = 64 * 1024;
 /**
- * The Pi session directory a child would use by default for its cwd. It is asked
- * of Pi itself instead of re-deriving the layout, and is always passed to the child
- * as an explicit `--session-dir` so recovery can find the file again.
+ * The session directory Pi itself would use for this cwd. At the top level it holds the
+ * human's own sessions, which is why children never write there directly.
  */
 export function resolveDefaultSessionDir(cwd) {
     return SessionManager.create(cwd).getSessionDir();
 }
+/** Child sessions live in this subdirectory of the parent-scoped session directory. */
+const SUBAGENT_SESSION_DIR_NAME = "agents";
+/**
+ * The session directory a delegated child writes to.
+ *
+ * Pi discovers sessions with a non-recursive `readdir` of the session directory, so a
+ * subdirectory keeps delegated sessions out of the human's session list while the child still
+ * receives that directory as an explicit `--session-dir` recovery can find again.
+ */
+export function resolveSubagentSessionDir(cwd) {
+    return join(resolveDefaultSessionDir(cwd), SUBAGENT_SESSION_DIR_NAME);
+}
 async function readSessionHeader(path) {
     const handle = await open(path, "r");
     try {
@@ -86,7 +100,7 @@ export async function planSessionPlacement(options) {
     if (!isSessionId(options.sessionId)) {
         throw new Error(`Invalid session id ${options.sessionId}`);
     }
-    const sessionDir = options.sessionDir ?? resolveDefaultSessionDir(options.cwd);
+    const sessionDir = options.sessionDir ?? resolveSubagentSessionDir(options.cwd);
     const sessionPath = options.sessionPath;
     if (sessionPath !== undefined &&
         (await stat(sessionPath).then(() => true, () => false))) {
@@ -107,8 +121,27 @@ export async function planSessionPlacement(options) {
     }
     return { sessionId: options.sessionId, sessionDir, persistence: "never_flushed" };
 }
-export function createSubagentId() {
-    return `sa_${randomUUID().replace(/-/gu, "").slice(0, 12)}`;
+let nextSubagentIndex = 0;
+export function resetSubagentIdCounter(value = 0) {
+    nextSubagentIndex = value;
+}
+export function createSubagentId(existingIds) {
+    if (existingIds !== undefined && existingIds.length > 0) {
+        let max = 0;
+        for (const id of existingIds) {
+            const match = /^agent-(\d+)$/u.exec(id);
+            if (match?.[1]) {
+                const num = Number.parseInt(match[1], 10);
+                if (num > max)
+                    max = num;
+            }
+        }
+        if (max > 0) {
+            nextSubagentIndex = Math.max(nextSubagentIndex, max);
+        }
+    }
+    nextSubagentIndex += 1;
+    return `agent-${nextSubagentIndex}`;
 }
 /**
  * One resolution chain for a spawn: agent definition + explicit parent defaults
@@ -118,13 +151,16 @@ export function createSubagentId() {
 export async function resolveSubagentLaunch(options) {
     const task = options.input.task.trim();
     if (task === "")
-        throw new Error("spawn_subagent requires a non-empty task");
+        throw new Error("spawn_agent requires a non-empty task");
     const name = options.input.agent?.trim();
     if (name === undefined || name === "") {
-        throw new Error("spawn_subagent requires an explicit agent name; V1 has no built-in default agent");
+        throw new Error("spawn_agent requires an explicit agent name; V1 has no built-in default agent");
     }
     const cwd = resolve(options.input.cwd?.trim() || options.cwd);
-    const subagentId = options.subagentId ?? createSubagentId();
+    const requestedTitle = options.input.title?.trim();
+    // A blank title is the same as no title: the child derives one from its own identity.
+    const title = requestedTitle === "" ? undefined : requestedTitle;
+    const subagentId = options.subagentId ?? createSubagentId(options.existingSubagentIds);
     const sessionId = options.sessionId ?? randomUUID();
     const bridgeExtensionPath = options.bridgeExtensionPath ?? resolveBridgeExtensionPath();
     const policy = await resolveAgent({
@@ -134,25 +170,53 @@ export async function resolveSubagentLaunch(options) {
         parent: options.parent,
         bridgeExtensionPath,
         ...(options.homeDirectory === undefined ? {} : { homeDirectory: options.homeDirectory }),
+        ...(options.skillCatalog === undefined ? {} : { skillCatalog: options.skillCatalog }),
+        ...(options.onWarning === undefined ? {} : { onWarning: options.onWarning }),
     });
+    if (options.enforceEnabled === true && policy.enabled === false) {
+        throw new Error(`Agent "${policy.agent.name}" is disabled: no model is specified in user configuration (~/.pi/agent/agents/ or .pi/agents/)`);
+    }
+    let instructions = policy.agent.instructions;
+    if (options.referencedSessionPath !== undefined && options.referencedSessionPath.trim() !== "") {
+        instructions = `${instructions.trim()}\n\n${formatSessionReferencePrompt(options.referencedSessionPath)}`;
+    }
     return Object.freeze({
         subagentId,
         invocation: options.invocation ?? resolvePiInvocation(),
         cwd,
         sessionId,
-        sessionDir: resolveDefaultSessionDir(cwd),
+        sessionDir: resolveSubagentSessionDir(cwd),
+        ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
+        ...(options.referencedSessionPath === undefined
+            ? {}
+            : { referencedSessionPath: options.referencedSessionPath }),
         agent: policy.agent,
         model: policy.model,
         thinking: policy.thinking,
-        tools: policy.tools,
+        tools: childTools(policy),
         excludeTools: policy.excludeTools,
         extensions: policy.extensions,
         skills: policy.skills,
-        prompt: assembleChildPrompt(policy.agent.instructions),
+        prompt: assembleChildPrompt(instructions),
         bridgeExtensionPath,
         interactive: policy.interactive,
+        ...(policy.codemodeOnly ? { codemodeOnly: true } : {}),
+        ...(title === undefined ? {} : { title }),
     });
 }
+/**
+ * The child's tool allowlist: a built-in agent must still resolve to exactly the tools its
+ * definition declares. Failing here happens before any process exists, rather than launching
+ * a child with different permissions than it advertises.
+ */
+function childTools(policy) {
+    const tools = policy.tools;
+    const problem = builtinAgentToolProblem(policy.agent.sourcePath, tools);
+    if (problem !== undefined) {
+        throw new Error(`Built-in agent ${policy.agent.name} cannot run: ${problem}`);
+    }
+    return tools;
+}
 /**
  * Writes the spawn intent before anything is launched. Registry failure propagates,
  * so a child is never started from intent that could not be recovered.
@@ -183,8 +247,8 @@ export async function persistSubagentIntent(options) {
         cwd: launchConfig.cwd,
         initialTask: task,
         intent: "active",
-        state: "starting",
-        mode: options.mode ?? "rpc",
+        state: "running",
+        presentation: options.presentation ?? "background",
         persistence: placement.persistence,
         launchConfig: Object.freeze({
             ...launchConfig,

package/dist/session-fork.d.ts

@@ -0,0 +1,16 @@
+import type { SubagentRegistry } from "./registry.js";
+/** Reads all JSON entries from a session file on disk. */
+export declare function readSessionJsonlEntries(sessionPath: string): Promise<unknown[]>;
+export interface ResolveForkSessionReferenceOptions {
+    readonly forkFrom: string;
+    readonly parentSessionPath?: string | undefined;
+    readonly registry?: Pick<SubagentRegistry, "get"> | undefined;
+    readonly onWarning?: ((message: string) => void) | undefined;
+}
+/**
+ * Resolves the source session JSONL file path for on-demand context inspection.
+ * Rejects 'current' to prevent ambiguous self-references.
+ */
+export declare function resolveForkSessionReference(options: ResolveForkSessionReferenceOptions): Promise<string>;
+/** Formats instructions explaining where the referenced session file is and how to inspect it on demand. */
+export declare function formatSessionReferencePrompt(sessionPath: string): string;

package/dist/session-fork.js

@@ -0,0 +1,67 @@
+import { readFile, stat } from "node:fs/promises";
+import { findSessionFile } from "./session-bootstrap.js";
+/** Reads all JSON entries from a session file on disk. */
+export async function readSessionJsonlEntries(sessionPath) {
+    const raw = await readFile(sessionPath, "utf8");
+    const lines = raw.split("\n").filter((line) => line.trim() !== "");
+    const entries = [];
+    for (const line of lines) {
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // ignore trailing malformed line
+        }
+    }
+    return entries;
+}
+/**
+ * Resolves the source session JSONL file path for on-demand context inspection.
+ * Rejects 'current' to prevent ambiguous self-references.
+ */
+export async function resolveForkSessionReference(options) {
+    const { forkFrom, parentSessionPath, registry } = options;
+    const target = forkFrom.trim();
+    if (target === "current") {
+        throw new Error("forkFrom cannot be 'current'. Use 'parent' to reference the parent session, or specify a subagent id like 'agent-1'.");
+    }
+    if (target === "parent" || target === "self") {
+        if (parentSessionPath !== undefined && parentSessionPath.trim() !== "") {
+            return parentSessionPath;
+        }
+        throw new Error("Parent session has no associated session file on disk to reference");
+    }
+    if (registry !== undefined) {
+        const record = await registry.get(target).catch(() => undefined);
+        if (record !== undefined) {
+            const subagentSessionPath = record.sessionPath ??
+                (await findSessionFile(record.launchConfig.sessionDir, record.sessionId));
+            if (subagentSessionPath !== undefined) {
+                return subagentSessionPath;
+            }
+            throw new Error(`Subagent ${target} has no session file on disk to reference`);
+        }
+        if (/^agent-\d+$/u.test(target)) {
+            throw new Error(`Subagent ${target} was not found in registry`);
+        }
+    }
+    // Treat as explicit session file path
+    try {
+        const st = await stat(target);
+        if (st.isFile())
+            return target;
+    }
+    catch {
+        // ignore
+    }
+    throw new Error(`Referenced session file not found: ${target}`);
+}
+/** Formats instructions explaining where the referenced session file is and how to inspect it on demand. */
+export function formatSessionReferencePrompt(sessionPath) {
+    return [
+        "## Referenced Session Context",
+        "Prior session transcript is available for reference at:",
+        sessionPath,
+        "Use tools (such as read or grep) to inspect earlier messages, tool outputs, or context from this JSONL file on demand as needed instead of loading the entire history.",
+    ].join("\n");
+}

package/dist/state.d.ts

@@ -3,11 +3,18 @@ export interface StateSnapshot {
     readonly state: SubagentState;
     readonly summary?: string;
     readonly interrupted?: string;
+    readonly activeTool?: string;
     readonly usage: UsageSummary;
 }
 export interface StateProjector {
     applyEvent(event: unknown): StateSnapshot;
     rebuild(entries: readonly unknown[]): StateSnapshot;
+    /**
+     * Puts the projected state back in step with a state the child itself reported. Without it a
+     * transcript that still ends in a tool result keeps projecting "running" over a child that has
+     * answered that it is idle, and the next state-less event writes that back onto the record.
+     */
+    syncState(state: SubagentState): StateSnapshot;
     snapshot(): StateSnapshot;
 }
 export declare function summarizeCurrentBranch(entries: readonly unknown[]): string | undefined;

package/dist/state.js

@@ -1,3 +1,4 @@
+import { isRecord } from "@hheei/pi-ext-core";
 const EMPTY_USAGE = {
     inputTokens: 0,
     outputTokens: 0,
@@ -7,9 +8,7 @@ const EMPTY_USAGE = {
     turns: 0,
 };
 function record(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value)
-        ? Object.fromEntries(Object.entries(value))
-        : undefined;
+    return isRecord(value) ? Object.fromEntries(Object.entries(value)) : undefined;
 }
 function finite(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
@@ -102,15 +101,17 @@ export function aggregateUsage(entries) {
     }
     return total;
 }
-export function createStateProjector(initialState = "starting") {
+export function createStateProjector(initialState = "running") {
     let state = initialState;
     let summary;
     let interrupted;
+    let activeTool;
     let usage = EMPTY_USAGE;
     const snapshot = () => ({
         state,
         ...(summary === undefined ? {} : { summary }),
         ...(interrupted === undefined ? {} : { interrupted }),
+        ...(activeTool === undefined ? {} : { activeTool }),
         usage,
     });
     return {
@@ -118,49 +119,83 @@ export function createStateProjector(initialState = "starting") {
             const value = record(event);
             if (value === undefined)
                 return snapshot();
-            if (value.type === "agent_start")
+            if (value.type === "agent_start" ||
+                value.type === "auto_retry_start" ||
+                value.type === "auto_retry") {
                 state = "running";
+                interrupted = undefined;
+                activeTool = undefined;
+            }
+            else if (value.type === "tool_execution_start") {
+                activeTool = typeof value.toolName === "string" ? value.toolName : undefined;
+            }
+            else if (value.type === "tool_execution_end") {
+                activeTool = undefined;
+            }
+            else if (value.type === "message_update") {
+                const message = record(value.message);
+                if (message?.role === "assistant") {
+                    const currentText = text(message);
+                    if (currentText !== undefined) {
+                        summary = currentText;
+                        activeTool = undefined;
+                    }
+                }
+            }
             else if (value.type === "agent_end" || value.type === "agent_settled") {
-                state = "idle";
+                activeTool = undefined;
+                // agent_end precedes retries, compaction and queued continuation work.
+                if (value.type === "agent_settled") {
+                    if (state !== "error" && state !== "blocked") {
+                        state = "done";
+                        interrupted = undefined;
+                    }
+                }
                 const messages = Array.isArray(value.messages) ? value.messages : [];
                 const message = record(messages.length > 0 ? messages[messages.length - 1] : value.message);
                 if (message?.role === "assistant") {
                     summary = text(message) ?? summary;
-                    interrupted = diagnostic(message) ?? interrupted;
-                    if (message.stopReason === "error")
-                        state = "failed";
+                    if (value.type === "agent_settled") {
+                        interrupted = diagnostic(message);
+                        if (message.stopReason === "error")
+                            state = "error";
+                        else
+                            interrupted = undefined;
+                    }
                 }
             }
             else if (value.type === "error") {
-                state = "failed";
+                state = "error";
                 interrupted =
                     typeof value.message === "string" ? value.message : "Runner reported an error";
             }
-            else if (value.type === "runner_events_dropped") {
-                const count = typeof value.count === "number" ? value.count : undefined;
-                interrupted =
-                    count === undefined
-                        ? "Runner dropped events; live state may be stale"
-                        : `Runner dropped ${count} events; live state may be stale`;
-            }
-            else if (value.type === "runner_exit" || value.type === "exit") {
-                state = value.code === 0 ? "done" : "failed";
-                if (value.code !== 0)
-                    interrupted = `Runner exited${typeof value.code === "number" ? ` with code ${value.code}` : " unexpectedly"}`;
-            }
             return snapshot();
         },
         rebuild(entries) {
+            activeTool = undefined;
             summary = summarizeCurrentBranch(entries);
             usage = aggregateUsage(entries);
+            let lastAssistant;
             for (const entry of entries) {
                 const item = assistant(entry);
                 if (item === undefined || !completed(item.message))
                     continue;
-                interrupted = diagnostic(item.message) ?? interrupted;
-                if (item.message.stopReason === "error")
-                    state = "failed";
+                lastAssistant = item.message;
+            }
+            if (lastAssistant !== undefined) {
+                interrupted = diagnostic(lastAssistant);
+                if (lastAssistant.stopReason === "error")
+                    state = "error";
+                else if (state === "error")
+                    state = "done";
             }
+            else {
+                interrupted = undefined;
+            }
+            return snapshot();
+        },
+        syncState(next) {
+            state = next;
             return snapshot();
         },
         snapshot,

package/dist/tool-activation.d.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SubagentManager } from "./manager.js";
+/** Interactive agent tools managed by dynamic activation. */
+export declare const INTERACTIVE_TOOL_NAMES: readonly ["spawn_agent", "send_agent", "get_agent", "stop_agent"];
+export type InteractiveToolName = (typeof INTERACTIVE_TOOL_NAMES)[number];
+export declare const SUBAGENT_LOADER_NAME = "subagent_enable";
+export declare const SUBAGENTS_LOADER_NAME = "subagent_enable";
+export declare function supportsDynamicTools(pi: ExtensionAPI): boolean;
+export interface RegisterInteractiveToolActivationOptions {
+    readonly pi: ExtensionAPI;
+    readonly manager: SubagentManager;
+    readonly context: ExtensionContext;
+}
+export interface InteractiveToolActivationHandle {
+    dispose(): void;
+    selectFromSession(ctx: ExtensionContext): Promise<void>;
+}
+export declare function registerInteractiveToolActivation(options: RegisterInteractiveToolActivationOptions): InteractiveToolActivationHandle;

package/dist/tool-activation.js

@@ -0,0 +1,227 @@
+import { buildSessionContext } from "@earendil-works/pi-coding-agent";
+import { getToolTui, isRecord, textToolResult } from "@hheei/pi-ext-core";
+import { Type } from "typebox";
+import { discoverAgents } from "./agent-resolver.js";
+import { builtinAgents } from "./builtin-agents.js";
+/** Interactive agent tools managed by dynamic activation. */
+export const INTERACTIVE_TOOL_NAMES = [
+    "spawn_agent",
+    "send_agent",
+    "get_agent",
+    "stop_agent",
+];
+export const SUBAGENT_LOADER_NAME = "subagent_enable";
+export const SUBAGENTS_LOADER_NAME = SUBAGENT_LOADER_NAME;
+const DESCRIPTION = "Enable interactive agent tools (spawn_agent, send_agent, get_agent, stop_agent) for running interactive subagents. Enabled tools are available on the next model request.";
+const SNIPPET = "Interactive subagents (spawn_agent, send_agent, get_agent, stop_agent) require activation. Call subagent_enable to activate them.";
+const emptySchema = Type.Object({}, { additionalProperties: false });
+export function supportsDynamicTools(pi) {
+    return (typeof pi.getAllTools === "function" &&
+        typeof pi.getActiveTools === "function" &&
+        typeof pi.setActiveTools === "function");
+}
+function hasToolDeclarations(messages) {
+    return messages.some((message) => isRecord(message) && ("toolsAdded" in message || "toolsRemoved" in message));
+}
+function currentTranscriptToolNames(messages) {
+    const tools = new Set();
+    for (const message of messages) {
+        if (!isRecord(message))
+            continue;
+        const declaration = message;
+        for (const tool of declaration.toolsRemoved ?? [])
+            tools.delete(tool.name);
+        for (const tool of declaration.toolsAdded ?? [])
+            tools.add(tool.name);
+    }
+    return [...tools];
+}
+const LEGACY_TOOL_NAMES = new Set([
+    "spawn_subagent",
+    "send_subagent",
+    "get_subagent",
+    "stop_subagent",
+    "list_subagents",
+    "subagents_enable",
+]);
+function branchHasSubagentCalls(messages, toolNames) {
+    const names = new Set([...toolNames, ...LEGACY_TOOL_NAMES]);
+    for (const msg of messages) {
+        if (!isRecord(msg))
+            continue;
+        if (msg.role === "assistant" && Array.isArray(msg.content)) {
+            for (const part of msg.content) {
+                if (isRecord(part) &&
+                    (part.type === "tool_use" || part.type === "toolCall") &&
+                    typeof part.name === "string") {
+                    if (part.name === SUBAGENT_LOADER_NAME || names.has(part.name))
+                        return true;
+                }
+            }
+        }
+        if (msg.role === "tool" &&
+            typeof msg.toolName === "string" &&
+            (msg.toolName === SUBAGENT_LOADER_NAME || names.has(msg.toolName))) {
+            return true;
+        }
+    }
+    return false;
+}
+export function registerInteractiveToolActivation(options) {
+    const { pi, manager, context } = options;
+    if (!supportsDynamicTools(pi)) {
+        return {
+            dispose() { },
+            selectFromSession: async () => { },
+        };
+    }
+    const names = INTERACTIVE_TOOL_NAMES;
+    const tui = getToolTui(pi);
+    const loaderTool = {
+        name: SUBAGENT_LOADER_NAME,
+        label: "Enable Interactive Subagents",
+        description: DESCRIPTION,
+        promptSnippet: SNIPPET,
+        parameters: emptySchema,
+        async execute(_id, _params, _signal, _onUpdate, execCtx) {
+            const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+            const unavailable = names.filter((name) => !registered.has(name));
+            if (unavailable.length > 0) {
+                throw new Error(`Cannot enable unavailable tools: ${unavailable.join(", ")}.`);
+            }
+            const cwd = execCtx !== undefined &&
+                typeof execCtx === "object" &&
+                "cwd" in execCtx &&
+                typeof execCtx.cwd === "string"
+                ? execCtx.cwd
+                : (context.cwd ?? process.cwd());
+            let allAgents;
+            try {
+                allAgents = await discoverAgents(cwd);
+            }
+            catch {
+                allAgents = builtinAgents();
+            }
+            const interactiveAgents = allAgents
+                .filter((agent) => agent.frontmatter.interactive === true && agent.frontmatter.hidden !== true)
+                .map((agent) => ({
+                name: agent.name,
+                description: typeof agent.frontmatter.description === "string" &&
+                    agent.frontmatter.description.trim() !== ""
+                    ? agent.frontmatter.description.trim()
+                    : "No description provided.",
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            const currentlyActive = new Set(pi.getActiveTools());
+            const alreadyActive = names.every((name) => currentlyActive.has(name));
+            if (!alreadyActive) {
+                try {
+                    pi.setActiveTools([...new Set([...pi.getActiveTools(), ...names])]);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Activation failed: ${message}.`);
+                }
+            }
+            const lines = [
+                alreadyActive
+                    ? `Interactive agent tools are already enabled: ${names.join(", ")}.`
+                    : `Enabled interactive agent tools: ${names.join(", ")}. They will be available on the next model request.`,
+            ];
+            if (interactiveAgents.length > 0) {
+                lines.push("");
+                lines.push("<interactive_agents>");
+                for (const agent of interactiveAgents) {
+                    lines.push(`- ${agent.name}: ${agent.description}`);
+                }
+                lines.push("</interactive_agents>");
+            }
+            return textToolResult(lines.join("\n"), {
+                enabled: [...names],
+                ...(interactiveAgents.length > 0 ? { interactiveAgents } : {}),
+            });
+        },
+    };
+    pi.registerTool(tui.frame(loaderTool, {
+        summary: () => "enable interactive subagents",
+        headerLine: "truncate",
+        footer: (result) => {
+            const details = result.details;
+            const count = details?.enabled?.length;
+            return count !== undefined
+                ? count === 1
+                    ? "1 tool enabled"
+                    : `${count} tools enabled`
+                : undefined;
+        },
+    }));
+    function loaderAvailable() {
+        return pi.getAllTools().some((tool) => tool.name === SUBAGENT_LOADER_NAME);
+    }
+    async function selectFromSession(ctx) {
+        if (!loaderAvailable())
+            return;
+        try {
+            let messages = [];
+            try {
+                const branch = ctx.sessionManager?.getBranch?.();
+                if (Array.isArray(branch) && branch.length > 0) {
+                    messages = buildSessionContext(branch).messages;
+                }
+            }
+            catch {
+                // branch or sessionManager may not be available in mock contexts
+            }
+            let hasLiveChildren = false;
+            try {
+                const children = await manager.list();
+                hasLiveChildren = children.some((child) => child.freshness === "live" || child.state === "running");
+            }
+            catch {
+                // manager may be recovering or unavailable
+            }
+            const recorded = hasToolDeclarations(messages)
+                ? new Set(currentTranscriptToolNames(messages))
+                : messages.length > 0 && branchHasSubagentCalls(messages, names)
+                    ? new Set(names)
+                    : new Set();
+            const shouldBeActive = hasLiveChildren || names.some((name) => recorded.has(name));
+            const heavy = new Set(names);
+            const active = pi.getActiveTools().filter((name) => !heavy.has(name));
+            if (shouldBeActive) {
+                for (const name of names)
+                    active.push(name);
+            }
+            pi.setActiveTools([...new Set([...active, SUBAGENT_LOADER_NAME])]);
+        }
+        catch (error) {
+            console.warn(`[pi-subagents] Subagent tool activation setup fallback: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const unbindSessionStart = pi.on("session_start", (_event, ctx) => {
+        void selectFromSession(ctx);
+    });
+    const unbindSessionTree = pi.on("session_tree", (_event, ctx) => {
+        void selectFromSession(ctx);
+    });
+    const unbindBeforeAgentStart = () => {
+        if (!loaderAvailable() || pi.getActiveTools().includes(SUBAGENT_LOADER_NAME))
+            return;
+        try {
+            pi.setActiveTools([...pi.getActiveTools(), SUBAGENT_LOADER_NAME]);
+        }
+        catch {
+            // Best effort
+        }
+    };
+    const unbindBeforeAgent = pi.on("before_agent_start", unbindBeforeAgentStart);
+    void selectFromSession(context);
+    return {
+        dispose() {
+            unbindSessionStart();
+            unbindSessionTree();
+            unbindBeforeAgent();
+        },
+        selectFromSession,
+    };
+}

package/dist/tools.d.ts

@@ -1,9 +1,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { ChildIdentity } from "./domain.js";
+import { type ChildIdentity } from "./domain.js";
 import type { SubagentManager } from "./manager.js";
 export declare function registerParentTools(pi: ExtensionAPI, manager: SubagentManager): void;
+/** Sends a child-initiated request over the bridge and resolves with the parent's answer. */
+export type ChildReport = (operation: string, payload: unknown, signal?: AbortSignal) => Promise<unknown>;
 export interface RegisterChildToolsOptions {
-    readonly onReport?: () => void;
+    /** The bridge connection to the parent; a child without one cannot report anything. */
+    readonly report: ChildReport;
     readonly isBound?: (sessionId: string) => boolean;
 }
-export declare function registerChildTools(pi: ExtensionAPI, identity: ChildIdentity, onReportOrOptions?: (() => void) | RegisterChildToolsOptions): void;
+export declare function registerChildTools(pi: ExtensionAPI, identity: ChildIdentity, options: RegisterChildToolsOptions): void;