@hheei/pi-subagents 0.2.3 → 0.3.0

package/dist/tool-presentation.js

@@ -0,0 +1,160 @@
+import { agentResultText, createToolPresentationRenderers, isRecord, } from "@hheei/pi-ext-core";
+function stringField(source, key) {
+    const value = source?.[key];
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function numberField(source, key) {
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function spawnPresentation(args, result) {
+    const record = isRecord(args) ? args : undefined;
+    const agent = stringField(record, "agent") ?? "agent";
+    const title = stringField(record, "title");
+    const task = stringField(record, "task");
+    const details = result !== undefined && isRecord(result.details) ? result.details : undefined;
+    const id = stringField(details, "id");
+    const path = stringField(details, "path");
+    const resultText = result === undefined ? undefined : agentResultText(result);
+    const rows = [
+        ...(id === undefined ? [] : [`id: ${id}`]),
+        ...(path === undefined ? [] : [`path: ${path}`]),
+    ];
+    const summaryParts = [agent];
+    if (title !== undefined && title.trim() !== "") {
+        summaryParts.push(title.trim());
+    }
+    if (id !== undefined && id.trim() !== "") {
+        summaryParts.push(id.trim());
+    }
+    return {
+        summary: summaryParts.join(" · "),
+        ...(task === undefined ? {} : { request: task }),
+        ...(task === undefined
+            ? {}
+            : {
+                copy: {
+                    primary: task,
+                    full: resultText === undefined ? task : `${task}\n---\n${resultText}`,
+                },
+            }),
+        ...(rows.length === 0 ? {} : { output: rows.join("\n") }),
+    };
+}
+function sendPresentation(args, result) {
+    const record = isRecord(args) ? args : undefined;
+    const id = stringField(record, "id") ?? "agent";
+    const mode = stringField(record, "mode") ?? "auto";
+    const message = stringField(record, "message");
+    const confirmation = result === undefined ? undefined : agentResultText(result);
+    const copy = message === undefined
+        ? undefined
+        : {
+            primary: message,
+            ...(confirmation === undefined ? {} : { full: `${message}\n${confirmation}` }),
+        };
+    return {
+        summary: `${id} · ${mode}`,
+        ...(message === undefined ? {} : { request: message }),
+        ...(confirmation === undefined ? {} : { output: confirmation }),
+        ...(copy === undefined ? {} : { copy }),
+    };
+}
+const PROGRESS_TEXT_KEYS = ["agent", "path", "presentation", "freshness", "activeTool"];
+const PROGRESS_NUMBER_KEYS = ["turns", "tokens"];
+/** Readable selected fields only; never restates the task or a terminal answer. */
+function detailLines(details) {
+    const lines = [];
+    const status = stringField(details, "status");
+    if (status !== undefined)
+        lines.push(`status: ${status}`);
+    const progress = isRecord(details.progress) ? details.progress : undefined;
+    if (progress !== undefined) {
+        for (const key of PROGRESS_TEXT_KEYS) {
+            const value = stringField(progress, key);
+            if (value !== undefined)
+                lines.push(`${key}: ${value}`);
+        }
+        for (const key of PROGRESS_NUMBER_KEYS) {
+            const value = numberField(progress, key);
+            if (value !== undefined)
+                lines.push(`${key}: ${value}`);
+        }
+        const summary = stringField(progress, "summary");
+        if (summary !== undefined)
+            lines.push(`summary: ${summary}`);
+    }
+    const diagnostic = stringField(details, "diagnostic");
+    if (diagnostic !== undefined)
+        lines.push(`diagnostic: ${diagnostic}`);
+    return lines;
+}
+function getCollapsedRow(details) {
+    const parts = [];
+    const status = stringField(details, "status");
+    if (status !== undefined)
+        parts.push(status);
+    const progress = isRecord(details.progress) ? details.progress : undefined;
+    if (progress !== undefined) {
+        const agent = stringField(progress, "agent");
+        if (agent !== undefined)
+            parts.push(agent);
+        const turns = numberField(progress, "turns");
+        if (turns !== undefined)
+            parts.push(`${turns} turn${turns === 1 ? "" : "s"}`);
+        const tokens = numberField(progress, "tokens");
+        if (tokens !== undefined) {
+            const tokStr = tokens >= 1000 ? `${(tokens / 1000).toFixed(1).replace(/\.0$/u, "")}k` : String(tokens);
+            parts.push(`${tokStr} tok`);
+        }
+        const activeTool = stringField(progress, "activeTool");
+        if (activeTool !== undefined) {
+            parts.push(activeTool);
+        }
+        else {
+            const summary = stringField(progress, "summary");
+            if (summary !== undefined)
+                parts.push(summary.replace(/\s+/gu, " ").trim());
+        }
+    }
+    const diagnostic = stringField(details, "diagnostic");
+    if (diagnostic !== undefined) {
+        parts.push(`diagnostic: ${diagnostic.replace(/\s+/gu, " ").trim()}`);
+    }
+    return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+function getPresentation(args, result) {
+    const record = isRecord(args) ? args : undefined;
+    const id = stringField(record, "id") ?? "agent";
+    const keys = stringField(record, "keys") ?? "status, progress";
+    const details = result !== undefined && isRecord(result.details) ? result.details : undefined;
+    const lines = details === undefined ? [] : detailLines(details);
+    const collapsedRow = details === undefined ? undefined : getCollapsedRow(details);
+    const resultText = result === undefined ? undefined : agentResultText(result);
+    return {
+        summary: id,
+        request: `keys: ${keys}`,
+        ...(lines.length === 0 ? {} : { output: lines.join("\n") }),
+        ...(collapsedRow === undefined ? {} : { collapsedRows: [collapsedRow] }),
+        ...(resultText === undefined ? {} : { copy: { primary: resultText } }),
+    };
+}
+function stopPresentation(args, result) {
+    const record = isRecord(args) ? args : undefined;
+    const id = stringField(record, "id") ?? "agent";
+    const confirmation = result === undefined ? undefined : agentResultText(result);
+    return {
+        summary: id,
+        ...(confirmation === undefined ? {} : { output: confirmation }),
+        ...(confirmation === undefined ? {} : { copy: { primary: confirmation } }),
+    };
+}
+/** One renderer set per tool, named exactly after its tool so nested calls resolve too. */
+export function parentToolRenderers(pi) {
+    return {
+        spawn: createToolPresentationRenderers(pi, "agent_spawn", spawnPresentation),
+        send: createToolPresentationRenderers(pi, "agent_send", sendPresentation),
+        get: createToolPresentationRenderers(pi, "agent_get", getPresentation),
+        stop: createToolPresentationRenderers(pi, "agent_stop", stopPresentation),
+    };
+}

package/dist/tools.d.ts

@@ -1,7 +1,11 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { DiscoveredAgent } from "./agent-resolver.js";
 import { type ChildIdentity } from "./domain.js";
 import type { SubagentManager } from "./manager.js";
-export declare function registerParentTools(pi: ExtensionAPI, manager: SubagentManager): void;
+export declare function formatAvailableAgents(agents: readonly DiscoveredAgent[]): string;
+declare const GET_KEYS: readonly ["status", "progress", "diagnostic"];
+export type AgentGetKey = (typeof GET_KEYS)[number];
+export declare function registerParentTools(pi: ExtensionAPI, manager: SubagentManager, agents: readonly DiscoveredAgent[]): 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 {
@@ -10,3 +14,4 @@ export interface RegisterChildToolsOptions {
     readonly isBound?: (sessionId: string) => boolean;
 }
 export declare function registerChildTools(pi: ExtensionAPI, identity: ChildIdentity, options: RegisterChildToolsOptions): void;
+export {};

package/dist/tools.js

@@ -1,26 +1,20 @@
-import { getToolTui, isRecord, registerToolTuiTrace, textToolResult } from "@hheei/pi-ext-core";
+import { textToolResult } from "@hheei/pi-ext-core";
 import { Type } from "typebox";
-import { discoverAgents } from "./agent-resolver.js";
-import { builtinAgents } from "./builtin-agents.js";
+import { Value } from "typebox/value";
 import { isOperationError } from "./domain.js";
+import { parentToolRenderers } from "./tool-presentation.js";
 const spawnSchema = Type.Object({
-    id: Type.Optional(Type.String({
-        description: "Optional subagent id (e.g. 'agent-1') to re-awaken an idle or completed subagent with a new task instead of creating a new one.",
-    })),
     task: Type.String({ minLength: 1 }),
     agent: Type.String({
         minLength: 1,
-        description: "Name of an agent defined in .pi/agents/*.md or ~/.pi/agent/agents/*.md",
+        description: "Agent name from <available_agents> in this tool description.",
     }),
     cwd: Type.Optional(Type.String()),
     title: Type.Optional(Type.String({
         maxLength: 60,
         description: "Short session title for this child, e.g. 'OVITO properties editor'. It becomes the child's Pi session title, prefixed with a robot marker so delegated sessions stay recognizable; omit it — or leave it blank — to derive one from the agent name and child id.",
     })),
-    forkFrom: Type.Optional(Type.String({
-        description: "Optional session or subagent id to reference context from: 'parent' (parent session), or a subagent id like 'agent-1' (including subagents that ended in 'error'). Does not inject past conversation into the prompt; provides the referenced session JSONL path in instructions so the subagent can inspect prior context on demand via read or grep. Cannot be 'current'.",
-    })),
-});
+}, { additionalProperties: false });
 const sendSchema = Type.Object({
     id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
     message: Type.String({ minLength: 1 }),
@@ -29,241 +23,203 @@ const sendSchema = Type.Object({
 const idSchema = Type.Object({
     id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
 });
+const getSchema = Type.Object({
+    id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
+    keys: Type.Optional(Type.String({
+        description: "Comma-separated fields to return. Defaults to 'status,progress'. Allowed: status, progress, diagnostic.",
+    })),
+});
 const contactSchema = Type.Object({
     message: Type.String({
         minLength: 1,
         description: "Explanation of what is blocking progress or the error encountered.",
     }),
     reason: Type.Optional(Type.Union([Type.Literal("blocked"), Type.Literal("error")], {
-        description: "Reason: 'blocked' if waiting for input/guidance (can be resumed via send_agent), or 'error' if fatal unrecoverable failure (cannot continue). Defaults to 'blocked'.",
+        description: "Reason: 'blocked' if waiting for input/guidance (can be resumed via agent_send), or 'error' if the turn failed (you may retry via agent_send or create a new child). Defaults to 'blocked'.",
     })),
 });
-const emptySchema = Type.Object({});
-function result(value) {
-    if (isOperationError(value))
-        throw new Error(JSON.stringify(value));
-    return textToolResult(typeof value === "string" ? value : JSON.stringify(value), value);
-}
 const SUBAGENTS_NAMESPACE = {
-    name: "subagents",
+    name: "agent",
+    aliases: ["agent", "agents", "subagent", "subagents"],
     description: "Subagent orchestration and delegation tools",
 };
-const SPAWN_DESCRIPTION = "Start an independent background RPC agent. PREFER REUSING EXISTING SUBAGENTS: For subtasks with identical or related functionality, prefer reusing an existing subagent via send_agent (even if in 'done' or 'blocked' state) rather than spawning a fresh subagent each time. Reusing subagents avoids redundant session initialization, preserves ongoing context, and maximizes prompt cache and pi-ext-memory efficiency. Only spawn a new agent when a distinct role or isolated fresh context is genuinely needed. Do NOT freeze, pause, or stop other sub-workers before spawning: idle subagents do not consume compute or interfere, so do not waste an agent turn freezing them. Do NOT poll get_agent or list_agents to wait for the child's work. Results are automatically captured when the child settles, and delivered as a subagent-report message to start your next turn; while you are idle, reports from several children may arrive together. After this tool returns, either end your turn or work on other independent tasks, including spawning more agents in parallel. Do not fabricate or assume the child's results.";
-const SPAWN_SNIPPET = "Start a background RPC agent. Prefer reusing existing subagents via send_agent for related work to preserve context and maximize memory/cache efficiency. No need to freeze/stop other workers. Results arrive as subagent-report; do not poll.";
-const SPAWN_GUIDELINES = [
-    "Prefer reusing existing subagents: for subtasks that have the same or related functionality, reuse an existing subagent via send_agent (which auto-resumes 'done' or 'blocked' agents) instead of spawning a new one. This preserves conversational continuity and maximizes prompt cache and memory efficiency.",
-    "Do not freeze, pause, or stop other subagents: idle subagents consume no compute and do not interfere. Do not waste a turn stopping them.",
-    "Do not poll get_agent or list_agents waiting for the child to finish.",
-    "Do not sleep, wait, or tail session/log files to detect completion. The harness delivers reports automatically.",
-    "After spawn returns, end your turn or do other independent work, including spawning more agents in parallel.",
-    "Do not fabricate, assume, or summarize the child's results before a report arrives.",
-];
-const SEND_DESCRIPTION = "Send a steer or follow-up message to one owned child. PREFERRED FOR SUBSEQUENT/RELATED TASKS: Prefer reusing existing subagents in 'done' or 'blocked' states via send_agent instead of spawning new subagents every time; 'blocked' and 'done' children automatically rebuild and resume with their conversation context intact, maximizing prompt cache and memory efficiency. Subagents in 'error' cannot be continued; use spawn_agent with forkFrom to reference their session context. Do NOT wait for or ask workers to 'freeze': idle subagents are completely dormant and touch nothing until sent to. Dispatch reviewers or follow-up tasks immediately without wasting turns on freeze ceremonies. Do NOT poll get_agent or list_agents afterwards. Child reports arrive as subagent-report messages that start your next turn.";
-const SEND_SNIPPET = "Send a message to one owned child (auto-resumes if finished/blocked). Prefer reusing existing agents for related tasks. Reports arrive as subagent-report; do not poll afterwards.";
-const GET_DESCRIPTION = "Inspect one owned child: state, presentation (panel or background), summary, usage, and whether the view is live or last-known. Use this when you need current identity or state, not to wait for the child to finish.";
-const LIST_DESCRIPTION = "List available interactive agent definitions and running or past subagents owned by this parent session with their state ('running', 'done', 'blocked', 'error'). Use this to inspect existing subagents that can be reused via send_agent before deciding to spawn a new agent, not to wait for work to finish. Reports still arrive as subagent-report messages.";
-const LIST_SNIPPET = "List available interactive agent definitions and running subagents.";
-const STOP_DESCRIPTION = "Persist a stopped intent, then end that child's runtime.";
+export function formatAvailableAgents(agents) {
+    const available = agents
+        .filter((agent) => agent.enabled !== false && agent.frontmatter.hidden !== true)
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((agent) => {
+        const description = agent.frontmatter.description;
+        return `- ${agent.name}: ${typeof description === "string" && description.trim() !== "" ? description.trim() : "No description provided."}`;
+    });
+    return [
+        "<available_agents>",
+        ...(available.length > 0 ? available : ["None."]),
+        "</available_agents>",
+    ].join("\n");
+}
+function getSpawnDescription(agents) {
+    return [
+        "Spawn an independent background subagent task to work on a goal asynchronously. Choose an agent from <available_agents> below.",
+        "Returns JSON { id, path }, where path is the absolute child session file path; the first write may still be pending.",
+        "Results are returned automatically to this parent session when the task finishes. After spawning, do independent work or end your turn; do not poll agent_get.",
+        "Related subagent tools: agent_send, agent_get, agent_stop.",
+        formatAvailableAgents(agents),
+    ].join("\n");
+}
+const SEND_DESCRIPTION = "Send input, steer, or follow-up instructions to an existing subagent (e.g. 'agent-1'), resuming its session when it is idle, blocked, done, or errored. Results are returned automatically when the task finishes; do not poll agent_get. Related subagent tools: agent_spawn, agent_get, agent_stop.";
+const GET_DESCRIPTION = "Inspect one subagent's status, progress, or diagnostic details by id (e.g. 'agent-1'). Use keys to choose fields; defaults to 'status,progress'. Results are returned automatically; use this for inspection, not completion polling. Related subagent tools: agent_spawn, agent_send, agent_stop.";
+const STOP_DESCRIPTION = "Stop a subagent's runtime by id (e.g. 'agent-1'). The child keeps its session, so a later agent_send can resume it. Related subagent tools: agent_spawn, agent_send, agent_get.";
 const CONTACT_DESCRIPTION = "Notify the parent session when you are BLOCKED and cannot continue without parent decision or intervention. Do NOT call this on success or task completion: simply output your final answer directly as normal text in your response, and the harness will automatically capture and report your result to the parent.";
 const CONTACT_SNIPPET = "Report a blocker to the parent. Do NOT call on success: write normal text to finish.";
 const CONTACT_GUIDELINES = [
     "Use contact_parent ONLY if you are blocked or urgently require a parent decision midway.",
     "Do NOT use contact_parent to deliver final findings or report success: output normal text instead.",
-    "After reporting a blocker, wait for a parent send_agent instruction.",
+    "After reporting a blocker, wait for a parent agent_send instruction.",
 ];
-function spawnFooter(result) {
-    const details = result.details;
-    const child = details?.child;
-    if (child !== undefined && typeof child.id === "string") {
-        const agent = child.displayName ?? child.agent;
-        return `#${child.id} · ${agent}`;
+const GET_KEYS = ["status", "progress", "diagnostic"];
+/** Parses the comma-separated `keys` argument; empty means the default view. */
+function parseAgentGetKeys(raw) {
+    if (raw === undefined)
+        return ["status", "progress"];
+    const keys = [];
+    for (const part of raw.split(",")) {
+        const key = part.trim();
+        if (key === "")
+            continue;
+        if (!GET_KEYS.includes(key)) {
+            throw new Error(`Unknown agent_get key "${key}". Allowed keys: ${GET_KEYS.join(", ")}.`);
+        }
+        if (!keys.includes(key))
+            keys.push(key);
     }
-    return undefined;
+    return keys.length > 0 ? keys : ["status", "progress"];
 }
-function childStateFooter(result) {
-    const details = result.details;
-    const child = details?.child;
-    if (child !== undefined && typeof child.id === "string") {
-        return `#${child.id} · ${child.state}`;
+function childAgentDetails(child, keys) {
+    const view = {};
+    if (keys.includes("status"))
+        view.status = child.state;
+    if (keys.includes("progress")) {
+        view.progress = {
+            agent: child.agent,
+            ...(child.path === undefined ? {} : { path: child.path }),
+            presentation: child.presentation,
+            freshness: child.freshness,
+            ...(child.activeTool === undefined ? {} : { activeTool: child.activeTool.slice(0, 200) }),
+            ...(child.state !== "running" || child.summary === undefined
+                ? {}
+                : { summary: child.summary.slice(0, 2000) }),
+            ...(child.usage === undefined
+                ? {}
+                : { turns: child.usage.turns, tokens: child.usage.inputTokens + child.usage.outputTokens }),
+        };
     }
-    return undefined;
-}
-function listFooter(result) {
-    const details = result.details;
-    if (isRecord(details) && Array.isArray(details.runningAgents)) {
-        const count = details.runningAgents.length;
-        if (count === 0)
-            return undefined;
-        return count === 1 ? "1 child" : `${count} children`;
-    }
-    if (Array.isArray(details)) {
-        const count = details.length;
-        if (count === 0)
-            return undefined;
-        return count === 1 ? "1 child" : `${count} children`;
+    if (keys.includes("diagnostic")) {
+        const diagnostic = child.interrupted ??
+            (child.state === "blocked" || child.state === "error" ? child.summary : undefined) ??
+            (child.freshness === "last_known" ? "Runtime disconnected; state is last known" : undefined);
+        if (diagnostic !== undefined)
+            view.diagnostic = diagnostic.slice(0, 2000);
     }
-    return undefined;
+    return view;
 }
-export function registerParentTools(pi, manager) {
-    registerToolTuiTrace(pi);
-    const tui = getToolTui(pi);
+export function registerParentTools(pi, manager, agents) {
+    const renderers = parentToolRenderers(pi);
+    const inspectedTasks = new Set();
+    function inspectionResult(id, text, details) {
+        const repeated = inspectedTasks.has(id);
+        inspectedTasks.add(id);
+        return textToolResult(repeated ? `${text}\nResults are returned automatically; do not poll agent_get.` : text, details);
+    }
     const spawn = {
-        name: "spawn_agent",
+        name: "agent_spawn",
         namespace: SUBAGENTS_NAMESPACE,
         label: "Spawn agent",
-        description: SPAWN_DESCRIPTION,
-        promptSnippet: SPAWN_SNIPPET,
-        promptGuidelines: [...SPAWN_GUIDELINES],
+        description: getSpawnDescription(agents),
         parameters: spawnSchema,
+        exposure: "deferred",
         defaultActive: false,
         annotations: {
             openWorldHint: true,
         },
         async execute(_id, params) {
-            return result(await manager.spawn(params));
+            if (!Value.Check(spawnSchema, params))
+                throw new Error("Invalid agent_spawn parameters");
+            const spawned = await manager.spawn(params);
+            if (isOperationError(spawned))
+                throw new Error(spawned.reason);
+            const { id } = spawned.child;
+            const { path } = spawned;
+            const details = { id, path };
+            return textToolResult(JSON.stringify(details), details);
         },
+        ...renderers.spawn,
     };
     const send = {
-        name: "send_agent",
+        name: "agent_send",
         namespace: SUBAGENTS_NAMESPACE,
         label: "Send to agent",
         description: SEND_DESCRIPTION,
-        promptSnippet: SEND_SNIPPET,
-        promptGuidelines: [
-            "Prefer reusing an existing subagent in 'done' or 'blocked' states via send_agent for subsequent or functionally identical/related subtasks instead of spawning a new subagent each time. This preserves context and maximizes memory and prompt cache efficiency.",
-            "Do not wait for or ask workers to 'freeze': idle subagents are dormant and touch nothing. Dispatch reviewers or follow-ups immediately.",
-            "Do not poll get_agent or list_agents afterwards.",
-            "Child reports arrive as subagent-report messages that start your next turn.",
-        ],
         parameters: sendSchema,
+        exposure: "deferred",
         defaultActive: false,
         annotations: {
             openWorldHint: true,
         },
         async execute(_id, params, signal) {
-            return result(await manager.send(params.id, params.message, params.mode, signal));
+            const sent = await manager.send(params.id, params.message, params.mode, signal);
+            if (isOperationError(sent))
+                throw new Error(sent.reason);
+            return textToolResult("Message sent.", undefined);
         },
+        ...renderers.send,
     };
     const get = {
-        name: "get_agent",
+        name: "agent_get",
         namespace: SUBAGENTS_NAMESPACE,
         label: "Get agent",
         description: GET_DESCRIPTION,
-        promptSnippet: GET_DESCRIPTION,
-        parameters: idSchema,
+        parameters: getSchema,
+        exposure: "deferred",
         defaultActive: false,
         annotations: {
             readOnlyHint: true,
             idempotentHint: true,
         },
         async execute(_id, params) {
-            return result(await manager.get(params.id));
-        },
-    };
-    const list = {
-        name: "list_agents",
-        namespace: SUBAGENTS_NAMESPACE,
-        label: "List agents",
-        description: LIST_DESCRIPTION,
-        promptSnippet: LIST_SNIPPET,
-        parameters: emptySchema,
-        annotations: {
-            readOnlyHint: true,
-            idempotentHint: true,
-        },
-        async execute(_id, _params, _signal, _onUpdate, ctx) {
-            const children = await manager.list();
-            const cwd = ctx !== undefined && typeof ctx === "object" && "cwd" in ctx && typeof ctx.cwd === "string"
-                ? ctx.cwd
-                : process.cwd();
-            let allAgents;
-            try {
-                allAgents = await discoverAgents(cwd);
-            }
-            catch {
-                allAgents = builtinAgents();
-            }
-            const visible = allAgents.filter((agent) => agent.enabled !== false && agent.frontmatter.hidden !== true);
-            const interactiveAgents = visible
-                .filter((agent) => agent.frontmatter.interactive === 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 lines = [];
-            if (interactiveAgents.length > 0) {
-                lines.push("<interactive_agents>");
-                for (const agent of interactiveAgents) {
-                    lines.push(`- ${agent.name}: ${agent.description}`);
-                }
-                lines.push("</interactive_agents>");
-            }
-            if (children.length > 0) {
-                if (lines.length > 0)
-                    lines.push("");
-                lines.push("<running_agents>");
-                for (const child of children) {
-                    const summaryPart = child.summary ? ` | summary: ${child.summary}` : "";
-                    lines.push(`- id: ${child.id} | agent: ${child.agent} | state: ${child.state}${summaryPart}`);
-                }
-                lines.push("</running_agents>");
-            }
-            if (lines.length === 0) {
-                lines.push("No active or available interactive subagents.");
-            }
-            return textToolResult(lines.join("\n"), {
-                ...(interactiveAgents.length > 0 ? { interactiveAgents } : {}),
-                runningAgents: children,
-            });
+            const keys = parseAgentGetKeys(params.keys);
+            const child = await manager.get(params.id);
+            if (isOperationError(child))
+                throw new Error(child.reason);
+            const view = childAgentDetails(child, keys);
+            return inspectionResult(params.id, JSON.stringify(view), view);
         },
+        ...renderers.get,
     };
     const stop = {
-        name: "stop_agent",
+        name: "agent_stop",
         namespace: SUBAGENTS_NAMESPACE,
         label: "Stop agent",
         description: STOP_DESCRIPTION,
         parameters: idSchema,
+        exposure: "deferred",
         defaultActive: false,
         annotations: {
             destructiveHint: true,
         },
         async execute(_id, params) {
-            return result(await manager.stop(params.id));
+            const stopped = await manager.stop(params.id);
+            if (isOperationError(stopped))
+                throw new Error(stopped.reason);
+            return textToolResult("Agent stopped.", undefined);
         },
+        ...renderers.stop,
     };
-    pi.registerTool(tui.frame(spawn, {
-        summary: (args) => args.agent,
-        headerLine: "truncate",
-        footer: spawnFooter,
-    }));
-    pi.registerTool(tui.frame(send, {
-        summary: (args) => args.id,
-        headerLine: "truncate",
-        footer: childStateFooter,
-    }));
-    pi.registerTool(tui.frame(get, {
-        summary: (args) => args.id,
-        headerLine: "truncate",
-        footer: childStateFooter,
-    }));
-    pi.registerTool(tui.frame(list, {
-        summary: () => "owned children",
-        headerLine: "truncate",
-        footer: listFooter,
-    }));
-    pi.registerTool(tui.frame(stop, {
-        summary: (args) => args.id,
-        headerLine: "truncate",
-        footer: childStateFooter,
-    }));
+    pi.registerTool(spawn);
+    pi.registerTool(send);
+    pi.registerTool(get);
+    pi.registerTool(stop);
 }
 export function registerChildTools(pi, identity, options) {
-    registerToolTuiTrace(pi);
-    const tui = getToolTui(pi);
     const tool = {
         name: "contact_parent",
         label: "Contact parent",
@@ -289,11 +245,8 @@ export function registerChildTools(pi, identity, options) {
             await options.report("contact_parent", details, signal);
             return textToolResult(reason === "error"
                 ? "Error report delivered to the parent."
-                : "Blocker report queued for the parent.", details);
+                : "Blocker report queued for the parent.", undefined);
         },
     };
-    pi.registerTool(tui.frame(tool, {
-        summary: (args) => args.message,
-        headerLine: "truncate",
-    }));
+    pi.registerTool(tool);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hheei/pi-subagents",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Independent background Pi subagent sessions with durable identity and RPC control.",
   "type": "module",
   "main": "dist/index.js",
@@ -35,16 +35,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@hheei/pi-ext-core": "^0.2.1"
+    "@hheei/pi-ext-core": "^0.3.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=1.0.0",
-    "@earendil-works/pi-tui": ">=1.0.0",
+    "@earendil-works/pi-coding-agent": ">=1.2.0",
+    "@earendil-works/pi-tui": ">=1.2.0",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.0.0",
-    "@earendil-works/pi-tui": "1.0.0"
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0"
   },
   "scripts": {
     "build": "node -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json"

package/dist/session-fork.d.ts

@@ -1,16 +0,0 @@
-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;