@esso0428/pi-subagents 0.17.6 → 0.17.7

package/dist/model-scope.d.ts

@@ -0,0 +1,50 @@
+/**
+ * model-scope.ts — `scopeModels` policy, shared by the top-level Agent tool and
+ * the nested delegation tools so a nested spawn can't escape the allowlist the
+ * top-level path enforces.
+ *
+ * State lives here (rather than in an index.ts closure) for the same reason
+ * `disableDefaults` lives in agent-types.ts: both entry points need it.
+ */
+import { type ModelRegistryRef } from "./enabled-models.js";
+export declare function isScopeModelsEnabled(): boolean;
+export declare function setScopeModelsEnabled(enabled: boolean): void;
+export type ModelScopeVerdict = 
+/** In scope, or nothing to validate against (feature off / no allowlist). */
+{
+    kind: "ok";
+}
+/** Caller-supplied out-of-scope choice — refuse the spawn with this message. */
+ | {
+    kind: "error";
+    message: string;
+}
+/** Frontmatter-pinned or parent-inherited — proceed, but tell the user. */
+ | {
+    kind: "warn";
+    message: string;
+};
+/**
+ * Check the effective resolved model against the user's enabledModels list.
+ *
+ * scopeModels guards against *runtime* LLM choices, not user-level config:
+ *   - Caller-supplied out-of-scope → hard error (the orchestrator made an explicit
+ *     out-of-scope choice; surface it so it picks differently).
+ *   - Frontmatter-pinned or parent-inherited out-of-scope → warn but proceed (the
+ *     user authored/installed this agent or chose the parent's model; trust it).
+ */
+export declare function checkModelScope(args: {
+    model: {
+        provider: string;
+        id: string;
+    } | undefined;
+    cwd: string;
+    modelRegistry: ModelRegistryRef;
+    /** True when the model came from the tool call rather than frontmatter. */
+    callerSupplied: boolean;
+    /** Display name used in the warning toast. */
+    agentLabel: string;
+    /** The raw `model:` input, when there was one. */
+    modelInput?: string;
+}): ModelScopeVerdict;
+//# sourceMappingURL=model-scope.d.ts.map

package/dist/model-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-scope.d.ts","sourceRoot":"","sources":["../src/model-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAkB,KAAK,gBAAgB,EAA2C,MAAM,qBAAqB,CAAC;AAWrH,wBAAgB,oBAAoB,IAAI,OAAO,CAA+B;AAC9E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAkC;AAE/F,MAAM,MAAM,iBAAiB;AAC3B,6EAA6E;AAC3E;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE;AAChB,gFAAgF;GAC9E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACpC,2EAA2E;GACzE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,gBAAgB,CAAC;IAChC,2EAA2E;IAC3E,cAAc,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,iBAAiB,CAmBpB"}

package/dist/model-scope.js

@@ -0,0 +1,49 @@
+/**
+ * model-scope.ts — `scopeModels` policy, shared by the top-level Agent tool and
+ * the nested delegation tools so a nested spawn can't escape the allowlist the
+ * top-level path enforces.
+ *
+ * State lives here (rather than in an index.ts closure) for the same reason
+ * `disableDefaults` lives in agent-types.ts: both entry points need it.
+ */
+import { isModelInScope, readEnabledModels, resolveEnabledModels } from "./enabled-models.js";
+/**
+ * When enabled, subagent model choices are validated against `enabledModels`
+ * from pi's settings — both global `<agentDir>/settings.json` and project-local
+ * `<cwd>/.pi/settings.json` (project overrides global). Off by default; opt-in
+ * via `/agents → Settings`. See the SubagentsSettings.scopeModels docstring for
+ * the hard-error vs warn-and-proceed policy and its rationale.
+ */
+let scopeModelsEnabled = false;
+export function isScopeModelsEnabled() { return scopeModelsEnabled; }
+export function setScopeModelsEnabled(enabled) { scopeModelsEnabled = enabled; }
+/**
+ * Check the effective resolved model against the user's enabledModels list.
+ *
+ * scopeModels guards against *runtime* LLM choices, not user-level config:
+ *   - Caller-supplied out-of-scope → hard error (the orchestrator made an explicit
+ *     out-of-scope choice; surface it so it picks differently).
+ *   - Frontmatter-pinned or parent-inherited out-of-scope → warn but proceed (the
+ *     user authored/installed this agent or chose the parent's model; trust it).
+ */
+export function checkModelScope(args) {
+    const { model, cwd, modelRegistry, callerSupplied, agentLabel, modelInput } = args;
+    if (!scopeModelsEnabled || !model)
+        return { kind: "ok" };
+    const allowed = resolveEnabledModels(readEnabledModels(cwd), modelRegistry, cwd);
+    if (!allowed || isModelInScope(model, allowed))
+        return { kind: "ok" };
+    if (callerSupplied) {
+        const list = [...allowed].sort().map(m => `  ${m}`).join("\n");
+        return {
+            kind: "error",
+            message: `Model not in scope: "${modelInput}".\n\nAllowed models (from enabledModels):\n${list}`,
+        };
+    }
+    const modelLabel = modelInput ?? `${model.provider}/${model.id}`;
+    return {
+        kind: "warn",
+        message: `Agent "${agentLabel}" using out-of-scope model "${modelLabel}"`,
+    };
+}
+//# sourceMappingURL=model-scope.js.map

package/dist/model-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-scope.js","sourceRoot":"","sources":["../src/model-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAyB,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAErH;;;;;;GAMG;AACH,IAAI,kBAAkB,GAAG,KAAK,CAAC;AAE/B,MAAM,UAAU,oBAAoB,KAAc,OAAO,kBAAkB,CAAC,CAAC,CAAC;AAC9E,MAAM,UAAU,qBAAqB,CAAC,OAAgB,IAAU,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;AAU/F;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,IAU/B;IACC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACnF,IAAI,CAAC,kBAAkB,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAEzD,MAAM,OAAO,GAAG,oBAAoB,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,aAAa,EAAE,GAAG,CAAC,CAAC;IACjF,IAAI,CAAC,OAAO,IAAI,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAEtE,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/D,OAAO;YACL,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,wBAAwB,UAAU,+CAA+C,IAAI,EAAE;SACjG,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,UAAU,IAAI,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;IACjE,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,UAAU,UAAU,+BAA+B,UAAU,GAAG;KAC1E,CAAC;AACJ,CAAC"}

package/dist/nested-tools.d.ts

@@ -0,0 +1,57 @@
+import type { Model } from "@earendil-works/pi-ai";
+import { type AgentSession, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AgentInvocation, AgentRecord, IsolationMode, ThinkingLevel } from "./types.js";
+export declare function getMaxSubagentDepth(): number;
+export declare function setMaxSubagentDepth(n: number): void;
+interface NestedSpawnOptions {
+    description: string;
+    model?: Model<any>;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    isBackground?: boolean;
+    isolation?: IsolationMode;
+    outputTranscript?: boolean;
+    invocation?: AgentInvocation;
+    signal?: AbortSignal;
+    onAssistantUsage?: (usage: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    }) => void;
+    onSessionCreated?: (session: AgentSession) => void;
+    depth: number;
+    parentAgentId: string;
+    maxSubagentDepth: number;
+    configCwd?: string;
+    rootSessionId?: string;
+}
+export interface NestedAgentManager {
+    spawn(pi: ExtensionAPI, ctx: ExtensionContext, type: string, prompt: string, options: NestedSpawnOptions): string;
+    /** Resolves once the spawned agent is running; rejects on a startup failure. */
+    awaitStartup(id: string): Promise<void>;
+    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: string, prompt: string, options: Omit<NestedSpawnOptions, "isBackground">, 
+    /** Fires synchronously after spawn, before the session exists — where the transcript is attached. */
+    onSpawned?: (id: string) => void): Promise<{
+        id: string;
+        record: AgentRecord;
+    }>;
+    getRecord(id: string): AgentRecord | undefined;
+    resume(id: string, prompt: string, signal?: AbortSignal): Promise<AgentRecord | undefined>;
+}
+export interface NestedToolContext {
+    manager: NestedAgentManager;
+    pi: ExtensionAPI;
+    parentAgentId: string;
+    depth: number;
+    maxSubagentDepth: number;
+    /** "all" = any enabled agent; string[] = only those types. Never empty. */
+    allowedSubagents: "all" | string[];
+    /** Root used for agent/config discovery; may differ from the agent's working directory. */
+    configCwd: string;
+}
+/** Build child-safe orchestration tools scoped to one parent agent instance. */
+export declare function createNestedSubagentTools(context: NestedToolContext): ToolDefinition[];
+export {};
+//# sourceMappingURL=nested-tools.d.ts.map

package/dist/nested-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-tools.d.ts","sourceRoot":"","sources":["../src/nested-tools.ts"],"names":[],"mappings":"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"}

package/dist/nested-tools.js

@@ -0,0 +1,301 @@
+import { defineTool, } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { abortable } from "./abortable.js";
+import { buildAgentRegistry, getAgentConfigIn, getAvailableTypesIn, resolveEnabledTypeIn, resolveTypeIn, } from "./agent-types.js";
+import { loadCustomAgents } from "./custom-agents.js";
+import { isolationParam, resolveAgentInvocationConfig } from "./invocation-config.js";
+import { resolveModel } from "./model-resolver.js";
+import { checkModelScope } from "./model-scope.js";
+import { createOutputFilePath, getOutputTranscriptDefault, streamToOutputFile, writeInitialEntry, } from "./output-file.js";
+import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
+import { addUsage } from "./usage.js";
+import { isWorktreeIsolationEnabled } from "./worktree.js";
+/**
+ * Hard ceiling on nesting for every branch: main session = 0, its subagents = 1,
+ * their children = 2. `0`/`1` disables nesting entirely. Set from
+ * `subagents.json` (`maxSubagentDepth`). Read when a subagent session is built,
+ * so a change applies to sessions started after it.
+ */
+let maxSubagentDepth = 2;
+export function getMaxSubagentDepth() { return maxSubagentDepth; }
+export function setMaxSubagentDepth(n) { maxSubagentDepth = Math.max(0, Math.floor(n)); }
+const NESTED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError, details: {} };
+}
+function ownsRecord(record, parentAgentId) {
+    return record?.parentAgentId === parentAgentId;
+}
+function formatRecord(record, position) {
+    if (record.status === "error") {
+        return `Agent failed: ${record.error ?? "unknown error"}${partialOutputSuffix(record)}`;
+    }
+    if (record.status === "queued" || record.status === "running") {
+        return `Agent ${record.id} is ${record.status}.`;
+    }
+    // A truncated run must not read as a finished one. The top-level path carries
+    // this in its result headline; a nested result has no headline, so the note
+    // leads — appended, it would look like part of the child's own output.
+    const text = record.result?.trim() || record.error?.trim() || "No output.";
+    const note = position === "inline"
+        ? getForegroundOutcomeNote(record.status)
+        : getStatusNote(record.status);
+    return note ? `Nested agent${note}.\n\n${text}` : text;
+}
+/** Build child-safe orchestration tools scoped to one parent agent instance. */
+export function createNestedSubagentTools(context) {
+    // Agents resolve from a registry built for THIS branch's config root (under
+    // worktree isolation, the copy). Never via registerAgents — that is
+    // process-global state shared with the main session and every other agent.
+    const loadRegistry = () => buildAgentRegistry(loadCustomAgents(context.configCwd));
+    const allowedTypesIn = (registry) => context.allowedSubagents === "all"
+        ? undefined
+        : new Set(context.allowedSubagents.map(name => resolveTypeIn(registry, name) ?? name));
+    const availableIn = (registry) => {
+        const allowed = allowedTypesIn(registry);
+        return getAvailableTypesIn(registry).filter(name => allowed === undefined || allowed.has(name));
+    };
+    const agentTool = defineTool({
+        name: NESTED_TOOL_NAMES[0],
+        label: "Agent",
+        description: "Launch a child-safe nested subagent for bounded delegated work. " +
+            "Only use agent types allowed by this parent agent; nesting is depth-limited.",
+        parameters: Type.Object({
+            prompt: Type.String({ description: "Self-contained task for the nested agent." }),
+            description: Type.String({ description: "Short 3-5 word task description." }),
+            subagent_type: Type.String({ description: `Allowed nested agent type. Available: ${availableIn(loadRegistry()).join(", ") || "none"}.` }),
+            model: Type.Optional(Type.String({ description: "Optional provider/model override." })),
+            thinking: Type.Optional(Type.String({ description: "Optional thinking level." })),
+            max_turns: Type.Optional(Type.Number({ minimum: 1 })),
+            run_in_background: Type.Optional(Type.Boolean({
+                description: "Defaults to false for nested spawns — the call blocks and returns the child's result inline. Set true only for work you will collect later with get_subagent_result; a detached child is stopped when you finish.",
+            })),
+            resume: Type.Optional(Type.String({ description: "Resume a nested agent owned by this parent." })),
+            isolated: Type.Optional(Type.Boolean()),
+            inherit_context: Type.Optional(Type.Boolean()),
+            ...isolationParam(isWorktreeIsolationEnabled()),
+        }),
+        execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
+            if (params.resume) {
+                const existing = context.manager.getRecord(params.resume);
+                if (!ownsRecord(existing, context.parentAgentId)) {
+                    return textResult(`Nested agent not found or not owned by this parent: "${params.resume}".`, true);
+                }
+                const resumed = await context.manager.resume(params.resume, params.prompt, signal);
+                return resumed
+                    ? textResult(formatRecord(resumed, "inline"), resumed.status === "error")
+                    : textResult(`Failed to resume nested agent "${params.resume}".`, true);
+            }
+            if (context.depth >= context.maxSubagentDepth) {
+                return textResult(`Nested subagent call blocked (depth=${context.depth}, max=${context.maxSubagentDepth}). Complete the task directly.`, true);
+            }
+            // Reloaded per call so new agent files are picked up without a restart.
+            const registry = loadRegistry();
+            const rawType = params.subagent_type;
+            // Strict resolve, never the fallback policy: a project-level
+            // `fallbackSubagent` must not hand a nested caller an agent its allowlist
+            // never named. The list stays allowlist-filtered so a typo can't enumerate
+            // agents this parent may not reach.
+            const resolvedType = resolveEnabledTypeIn(registry, rawType);
+            if (resolvedType === undefined) {
+                return textResult(`Unknown or disabled nested agent type: "${rawType}". Allowed: ${availableIn(registry).join(", ") || "none"}.`, true);
+            }
+            const allowed = allowedTypesIn(registry);
+            if (allowed !== undefined && !allowed.has(resolvedType)) {
+                return textResult(`Nested agent type "${resolvedType}" is not allowed for this parent. Allowed: ${[...allowed].join(", ")}.`, true);
+            }
+            const config = getAgentConfigIn(registry, resolvedType);
+            // Foreground regardless of `backgroundByDefault` — see the reasoning on
+            // ResolveOptions. An explicit `true` here still opts in.
+            const invocation = resolveAgentInvocationConfig(config, params, {
+                worktreeAllowed: isWorktreeIsolationEnabled(),
+                defaultRunInBackground: false,
+            });
+            let model = ctx.model;
+            if (invocation.modelInput) {
+                const resolvedModel = resolveModel(invocation.modelInput, ctx.modelRegistry);
+                if (typeof resolvedModel === "string") {
+                    if (invocation.modelFromParams)
+                        return textResult(resolvedModel, true);
+                }
+                else {
+                    model = resolvedModel;
+                }
+            }
+            // Same scopeModels policy as the top-level Agent tool — a nested spawn
+            // must not escape the allowlist. A "warn" verdict proceeds silently:
+            // child sessions have no UI surface to toast to.
+            const scopeVerdict = checkModelScope({
+                model,
+                cwd: context.configCwd,
+                modelRegistry: ctx.modelRegistry,
+                callerSupplied: invocation.modelFromParams,
+                agentLabel: config?.displayName ?? resolvedType,
+                modelInput: invocation.modelInput,
+            });
+            if (scopeVerdict.kind === "error")
+                return textResult(scopeVerdict.message, true);
+            // The whole branch shares the root session's transcript directory; read it
+            // off the owning parent rather than this child session's own id.
+            const rootSessionId = context.manager.getRecord(context.parentAgentId)?.rootSessionId;
+            const childDepth = context.depth + 1;
+            const options = {
+                description: params.description,
+                model,
+                maxTurns: invocation.maxTurns,
+                isolated: invocation.isolated,
+                inheritContext: invocation.inheritContext,
+                thinkingLevel: invocation.thinking,
+                isolation: invocation.isolation,
+                outputTranscript: config?.outputTranscript ?? getOutputTranscriptDefault(),
+                invocation: {
+                    thinking: invocation.thinking,
+                    maxTurns: invocation.maxTurns,
+                    isolated: invocation.isolated,
+                    inheritContext: invocation.inheritContext,
+                    runInBackground: invocation.runInBackground,
+                    isolation: invocation.isolation,
+                },
+                // Nested children are hidden from every reporting surface, so their spend
+                // would otherwise be unattributable. Fold it into every ancestor's record:
+                // the top-level one appears in lifecycle events, completion notifications,
+                // and `/agents`, and those all read `lifetimeUsage`. The whole chain is
+                // walked, not just the immediate parent — a spawn callback only fires for
+                // that child's OWN turns, so stopping at one level would hide a
+                // great-grandchild from the only record anyone can see. (The live
+                // widget/fleet counters read their own per-agent activity tracker, which
+                // still sees only the top-level agent's own turns.)
+                onAssistantUsage: (usage) => {
+                    for (let id = context.parentAgentId; id !== undefined;) {
+                        const ancestor = context.manager.getRecord(id);
+                        if (!ancestor)
+                            break;
+                        addUsage(ancestor.lifetimeUsage, usage);
+                        id = ancestor.parentAgentId;
+                    }
+                },
+                depth: childDepth,
+                parentAgentId: context.parentAgentId,
+                maxSubagentDepth: context.maxSubagentDepth,
+                configCwd: context.configCwd,
+                rootSessionId,
+            };
+            // Transcript wiring, same gate as the top-level path: the child's
+            // `output_transcript` frontmatter wins, else the project default. Without
+            // it a nested run leaves no artifact but the string it returned — the
+            // parent's own transcript records the call and the answer, never the tool
+            // calls in between, which is exactly what a misbehaving child needs to
+            // explain itself. Filed under the ROOT session and this branch's config
+            // root, so a nested transcript lands in the same `tasks/` directory as its
+            // ancestors' rather than in a directory of its own.
+            const transcriptSessionId = rootSessionId !== undefined && (config?.outputTranscript ?? getOutputTranscriptDefault())
+                ? rootSessionId
+                : undefined;
+            let childId;
+            const attachTranscript = (id) => {
+                childId = id;
+                if (transcriptSessionId === undefined)
+                    return;
+                const rec = context.manager.getRecord(id);
+                if (!rec)
+                    return;
+                rec.outputFile = createOutputFilePath(context.configCwd, id, transcriptSessionId);
+                writeInitialEntry(rec.outputFile, id, params.prompt, ctx.cwd);
+            };
+            options.onSessionCreated = (session) => {
+                const rec = childId === undefined ? undefined : context.manager.getRecord(childId);
+                if (rec?.outputFile && childId !== undefined) {
+                    rec.outputCleanup = streamToOutputFile(session, rec.outputFile, childId, ctx.cwd, undefined);
+                }
+            };
+            // `ctx` is forwarded to the manager unmodified, never captured at tool-build
+            // time: each AgentSession builds its own ExtensionRunner from that session's
+            // cwd/sessionManager/modelRegistry, so this is the CHILD's context. Capturing
+            // one earlier would silently give a grandchild the wrong worktree base, the
+            // wrong conversation under inherit_context, and the wrong inherited model.
+            //
+            // spawn() throws on strict worktree-isolation failure and cwd validation —
+            // report it as a tool error, like the top-level Agent tool does, instead of
+            // letting it escape into the child's turn.
+            try {
+                if (invocation.runInBackground) {
+                    const id = context.manager.spawn(context.pi, ctx, resolvedType, params.prompt, {
+                        ...options,
+                        isBackground: true,
+                    });
+                    // Synchronous, before the event loop yields — onSessionCreated fires
+                    // asynchronously inside runAgent, so the file is attached in time.
+                    attachTranscript(id);
+                    // Worktree isolation starts the agent asynchronously; surface its
+                    // failure as a tool error, like the synchronous throw used to.
+                    await context.manager.awaitStartup(id);
+                    return textResult(`Nested agent started in background. Agent ID: ${id}`);
+                }
+                const { record } = await context.manager.spawnAndWait(context.pi, ctx, resolvedType, params.prompt, { ...options, signal }, attachTranscript);
+                return textResult(formatRecord(record, "inline"), record.status === "error");
+            }
+            catch (err) {
+                return textResult(err instanceof Error ? err.message : String(err), true);
+            }
+        },
+    });
+    const resultTool = defineTool({
+        name: NESTED_TOOL_NAMES[1],
+        label: "Get Nested Agent Result",
+        description: "Check or wait for a background nested agent owned by this parent.",
+        parameters: Type.Object({
+            agent_id: Type.String(),
+            wait: Type.Optional(Type.Boolean()),
+        }),
+        execute: async (_toolCallId, params, signal) => {
+            const record = context.manager.getRecord(params.agent_id);
+            if (!ownsRecord(record, context.parentAgentId)) {
+                return textResult(`Nested agent not found or not owned by this parent: "${params.agent_id}".`, true);
+            }
+            // Wait for completion if requested. Cancellation (e.g. the parent's tool
+            // call is aborted) stops only this wait; the nested child keeps running and
+            // stays unconsumed. Queued records have no promise until the manager starts
+            // them, so poll — abortably — until they leave the queue, then await.
+            if (params.wait && (record.status === "queued" || record.status === "running")) {
+                while (record.status === "queued") {
+                    await abortable(new Promise(resolve => setTimeout(resolve, 250)), signal);
+                }
+                if (record.promise)
+                    await abortable(record.promise, signal);
+            }
+            return textResult(formatRecord(record, "fetched"), record.status === "error");
+        },
+    });
+    const steerTool = defineTool({
+        name: NESTED_TOOL_NAMES[2],
+        label: "Steer Nested Agent",
+        description: "Send guidance to a running nested agent owned by this parent.",
+        parameters: Type.Object({
+            agent_id: Type.String(),
+            message: Type.String(),
+        }),
+        execute: async (_toolCallId, params) => {
+            const record = context.manager.getRecord(params.agent_id);
+            if (!ownsRecord(record, context.parentAgentId) || record.status !== "running") {
+                return textResult(`Running nested agent not found or not owned by this parent: "${params.agent_id}".`, true);
+            }
+            // Session not ready yet — queue the steer. The manager flushes pending
+            // steers when the session is created (same contract as the top-level tool).
+            if (!record.session) {
+                if (!record.pendingSteers)
+                    record.pendingSteers = [];
+                record.pendingSteers.push(params.message);
+                return textResult(`Steering message queued for nested agent ${params.agent_id}.`);
+            }
+            try {
+                await record.session.steer(params.message);
+            }
+            catch (err) {
+                return textResult(`Failed to steer nested agent: ${err instanceof Error ? err.message : String(err)}`, true);
+            }
+            return textResult(`Steering message sent to nested agent ${params.agent_id}.`);
+        },
+    });
+    return [agentTool, resultTool, steerTool];
+}
+//# sourceMappingURL=nested-tools.js.map

package/dist/nested-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-tools.js","sourceRoot":"","sources":["../src/nested-tools.ts"],"names":[],"mappings":"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"}

package/dist/output-file.d.ts

@@ -5,6 +5,8 @@
  * matching Claude Code's task output file format.
  */
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+export declare function getOutputTranscriptDefault(): boolean;
+export declare function setOutputTranscriptDefault(b: boolean): void;
 /**
  * Encode a cwd path as a filesystem-safe directory name. Handles:
  *   - POSIX:   "/home/user/project"        → "home-user-project"
@@ -12,14 +14,31 @@ import type { AgentSession } from "@earendil-works/pi-coding-agent";
  *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
  */
 export declare function encodeCwd(cwd: string): string;
-/** Create the output file path, ensuring the directory exists.
- *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
+/**
+ * The per-session scratch directory, created if missing.
+ * Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks
+ *
+ * Shared with the workflow tool, which persists each invocation's script here so
+ * iterating on one is edit-file-then-rerun — the same convention, one directory.
+ */
+export declare function sessionTaskDir(cwd: string, sessionId: string): string;
+/** Create the output file path, ensuring the directory exists. */
 export declare function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string;
+/**
+ * Ensure a transcript file exists without disturbing what is already in it.
+ *
+ * A resume reuses the agent's existing transcript (same deterministic path), so
+ * it must never call `writeInitialEntry` — that truncates, discarding turns the
+ * completion notification still points the user at, and any history the session
+ * has since compacted away is gone for good. Appending nothing creates the file
+ * when this is the agent's first transcript and is a no-op when it is not.
+ */
+export declare function ensureOutputFile(path: string): void;
 /** Write the initial user prompt entry. */
 export declare function writeInitialEntry(path: string, agentId: string, prompt: string, cwd: string): void;
 /**
  * Subscribe to session events and flush new messages to the output file on each turn_end.
  * Returns a cleanup function that does a final flush and unsubscribes.
  */
-export declare function streamToOutputFile(session: AgentSession, path: string, agentId: string, cwd: string, historyPath?: string): () => void;
+export declare function streamToOutputFile(session: AgentSession, path: string, agentId: string, cwd: string, startIndexOrHistoryPath?: number | string, historyPath?: string): () => void;
 //# sourceMappingURL=output-file.d.ts.map

package/dist/output-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-file.d.ts","sourceRoot":"","sources":["../src/output-file.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,iCAAiC,CAAC;AAEvF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK7C;AAED;yGACyG;AACzG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAc5F;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAUlG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,IAAI,CA+CZ"}
+{"version":3,"file":"output-file.d.ts","sourceRoot":"","sources":["../src/output-file.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,iCAAiC,CAAC;AAavF,wBAAgB,0BAA0B,IAAI,OAAO,CAAoC;AACzF,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAiC;AAE7F;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAcrE;AAED,kEAAkE;AAClE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAInD;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAUlG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,uBAAuB,CAAC,EAAE,MAAM,GAAG,MAAM,EACzC,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,IAAI,CA8DZ"}