@hydraharness/harness-subagent 0.1.1-rc.5

package/lib/invariant.js

@@ -0,0 +1,76 @@
+//#region lib/types/invariant.js
+/** Package-owned subagent registry and lifecycle invariants. @module @hydraharness/harness-subagent/invariant */
+const PACKAGE_NAME = "@hydraharness/harness-subagent";
+/** Cordis companion plugin name. */
+const name = "subagent-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Assert that a terminal lifecycle payload matches its start identity. */
+function validateRunEnd(start, end, fail) {
+	if (start.provider !== end.provider || start.id !== end.id || start.local !== end.local) fail(`subagent/end identity diverges from subagent/start for run ${JSON.stringify(end.runId)}`);
+}
+/** Install provider-registry and start/end pairing checks. */
+const install = Object.assign((ctx, fail) => {
+	const providers = new Set(ctx.subagents.list());
+	const runs = /* @__PURE__ */ new Map();
+	const stagedProviders = /* @__PURE__ */ new WeakSet();
+	const stagedRemovals = /* @__PURE__ */ new Set();
+	const stagedStarts = /* @__PURE__ */ new WeakSet();
+	const stagedEnds = /* @__PURE__ */ new WeakSet();
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName === "subagent/provider-added") {
+			const provider = args[0];
+			if (provider.name.length === 0) fail("subagent provider names must be non-empty");
+			if (providers.has(provider.name)) fail(`subagent/provider-added repeated ${JSON.stringify(provider.name)}`);
+			stagedProviders.add(provider);
+			return;
+		}
+		if (eventName === "subagent/provider-removed") {
+			const providerName = args[0];
+			if (!providers.has(providerName)) fail(`subagent/provider-removed names unknown provider ${JSON.stringify(providerName)}`);
+			stagedRemovals.add(providerName);
+			return;
+		}
+		if (eventName === "subagent/start") {
+			const info = args[0];
+			if (info.provider.length === 0 || String(info.runId).length === 0 || String(info.id).length === 0) fail("subagent/start provider, runId, and child id must be non-empty");
+			if (runs.has(info.runId)) fail(`subagent/start repeated run id ${JSON.stringify(info.runId)}`);
+			stagedStarts.add(info);
+			return;
+		}
+		if (eventName !== "subagent/end") return;
+		const info = args[0];
+		const start = runs.get(info.runId);
+		if (start === void 0) fail(`subagent/end has no matching subagent/start for run ${JSON.stringify(info.runId)}`);
+		validateRunEnd(start, info, fail);
+		stagedEnds.add(info);
+	}, { global: true });
+	ctx.on("subagent/provider-added", (provider) => {
+		/* v8 ignore next -- internal/dispatch stages the same provider object */
+		if (!stagedProviders.delete(provider)) return;
+		providers.add(provider.name);
+	}, { global: true });
+	ctx.on("subagent/provider-removed", (providerName) => {
+		/* v8 ignore next -- internal/dispatch stages the same provider name */
+		if (!stagedRemovals.delete(providerName)) return;
+		providers.delete(providerName);
+	}, { global: true });
+	ctx.on("subagent/start", (info) => {
+		/* v8 ignore next -- internal/dispatch stages the same lifecycle object */
+		if (!stagedStarts.delete(info)) return;
+		runs.set(info.runId, info);
+	}, { global: true });
+	ctx.on("subagent/end", (info) => {
+		/* v8 ignore next -- internal/dispatch stages the same lifecycle object */
+		if (!stagedEnds.delete(info)) return;
+		runs.delete(info.runId);
+	}, { global: true });
+}, { inject: ["subagents"] });
+/**
+* Register the subagent invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/activation-setup-registry.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Internal registry of deployment capabilities composed into every continuable
+ * child's unpublished creation context.
+ *
+ * A contribution grants a child-scoped capability without teaching the
+ * continuation manager which capabilities exist. The manager owns residency;
+ * this registry owns the join between plugin lifetime, unpublished setup, and
+ * Activation disposal, so no installation outlives either owner and no removed
+ * contribution can be installed after revocation reports completion.
+ *
+ * @module @hydraharness/harness-subagent/activation-setup-registry
+ */
+import type { Context } from '@hydraharness/cordis';
+import type { AgentSetupCommit } from '@hydraharness/harness-agent';
+/**
+ * One deployment capability installed into a continuable child's unpublished
+ * creation context. It composes synchronously before publication and returns
+ * the disposer for exactly that installation.
+ * @param childCtx - the child's unpublished scoped context.
+ * @returns the disposer revoking this installation.
+ */
+export type ContinuableSetupContribution = (childCtx: Context) => () => void;
+/**
+ * Owns continuable-child setup registrations, installations, rollback, child
+ * cleanup, and immediate live revocation.
+ */
+export declare class SubagentActivationSetupRegistry {
+    /** Live contributions in installation order. */
+    private readonly registrations;
+    /** Child context to its live installations. */
+    private readonly byChild;
+    /**
+     * Register one contribution.
+     * @param contribution - synchronous child-scope installer.
+     * @returns an idempotent registration undo.
+     * @throws after attempting every installation when any disposer fails.
+     */
+    register(contribution: ContinuableSetupContribution): () => void;
+    /**
+     * Install every live contribution into one unpublished child context.
+     * @param childCtx - the child's unpublished scoped context.
+     * @returns the provisioning commit consumed at Agent publication.
+     */
+    apply(childCtx: Context): AgentSetupCommit;
+    /** Release every remaining installation owned by one disposed child scope. */
+    private releaseChild;
+    /**
+     * Release a batch completely before reporting disposer failures.
+     * @param installations - records to release.
+     * @param during - operation name for diagnostics.
+     */
+    private releaseAll;
+    /** Drop one installation from both indices and dispose it exactly once. */
+    private release;
+}
+export default SubagentActivationSetupRegistry;
+//# sourceMappingURL=activation-setup-registry.d.ts.map

package/lib/types/activation-setup-registry.js

@@ -0,0 +1,148 @@
+/**
+ * Internal registry of deployment capabilities composed into every continuable
+ * child's unpublished creation context.
+ *
+ * A contribution grants a child-scoped capability without teaching the
+ * continuation manager which capabilities exist. The manager owns residency;
+ * this registry owns the join between plugin lifetime, unpublished setup, and
+ * Activation disposal, so no installation outlives either owner and no removed
+ * contribution can be installed after revocation reports completion.
+ *
+ * @module @hydraharness/harness-subagent/activation-setup-registry
+ */
+import { errorChain } from '@hydraharness/harness-llm';
+import { SubagentError } from "./error.js";
+/** Re-read mutable removal state after a contribution may have revoked itself. */
+function isRemoved(registration) {
+    return registration.removed;
+}
+/**
+ * Owns continuable-child setup registrations, installations, rollback, child
+ * cleanup, and immediate live revocation.
+ */
+export class SubagentActivationSetupRegistry {
+    /** Live contributions in installation order. */
+    registrations = new Set();
+    /** Child context to its live installations. */
+    byChild = new Map();
+    /**
+     * Register one contribution.
+     * @param contribution - synchronous child-scope installer.
+     * @returns an idempotent registration undo.
+     * @throws after attempting every installation when any disposer fails.
+     */
+    register(contribution) {
+        const registration = { contribution, removed: false, installations: new Set() };
+        this.registrations.add(registration);
+        return () => {
+            if (registration.removed)
+                return;
+            // Close before disposal so a snapshotted apply() cannot install after
+            // revocation reports completion.
+            registration.removed = true;
+            this.registrations.delete(registration);
+            this.releaseAll([...registration.installations], 'contribution removal');
+        };
+    }
+    /**
+     * Install every live contribution into one unpublished child context.
+     * @param childCtx - the child's unpublished scoped context.
+     * @returns the provisioning commit consumed at Agent publication.
+     */
+    apply(childCtx) {
+        const state = { installations: [], invalidated: false };
+        try {
+            for (const registration of [...this.registrations]) {
+                /* v8 ignore next -- only a synchronous re-entrant revocation of an
+                 * already-snapshotted registration reaches this guard. */
+                if (registration.removed)
+                    continue;
+                const installation = {
+                    registration,
+                    childCtx,
+                    dispose: registration.contribution(childCtx),
+                    released: false,
+                    transaction: state,
+                };
+                registration.installations.add(installation);
+                state.installations.push(installation);
+                let indexed = this.byChild.get(childCtx);
+                if (indexed === undefined) {
+                    indexed = new Set();
+                    this.byChild.set(childCtx, indexed);
+                }
+                indexed.add(installation);
+                // An installer may revoke itself before its installation record exists.
+                // Dispose that escaped record and invalidate the provisioning batch.
+                if (isRemoved(registration))
+                    this.release(installation);
+            }
+        }
+        catch (error) {
+            // Keep the installer failure authoritative, but attempt every rollback.
+            try {
+                this.releaseAll([...state.installations], 'setup rollback');
+            }
+            catch (releaseFailure) {
+                /* v8 ignore next -- requires independent installer and rollback faults. */
+                void releaseFailure;
+            }
+            throw error;
+        }
+        childCtx.effect(() => () => { this.releaseChild(childCtx); }, 'subagents.activationSetup()');
+        return {
+            commit: () => {
+                if (state.invalidated) {
+                    throw new SubagentError('a continuable-subagent setup contribution was revoked while this child was being built; '
+                        + 'the child was not established', 'ACTIVATION_SETUP_REVOKED');
+                }
+                for (const installation of state.installations)
+                    installation.transaction = undefined;
+            },
+        };
+    }
+    /** Release every remaining installation owned by one disposed child scope. */
+    releaseChild(childCtx) {
+        const indexed = this.byChild.get(childCtx) ?? [];
+        this.releaseAll([...indexed], 'child scope disposal');
+    }
+    /**
+     * Release a batch completely before reporting disposer failures.
+     * @param installations - records to release.
+     * @param during - operation name for diagnostics.
+     */
+    releaseAll(installations, during) {
+        const failures = [];
+        for (const installation of installations) {
+            try {
+                this.release(installation);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length === 0)
+            return;
+        throw new SubagentError(`continuable-subagent setup ${during} failed to release ${failures.length} installation(s): `
+            + failures.map(failure => errorChain(failure)).join('; '), 'ACTIVATION_SETUP_RELEASE_FAILED');
+    }
+    /** Drop one installation from both indices and dispose it exactly once. */
+    release(installation) {
+        if (installation.released)
+            return;
+        installation.released = true;
+        installation.registration.installations.delete(installation);
+        const indexed = this.byChild.get(installation.childCtx);
+        /* v8 ignore next 4 -- every live installation is indexed until this method removes it. */
+        if (indexed !== undefined) {
+            indexed.delete(installation);
+            if (indexed.size === 0)
+                this.byChild.delete(installation.childCtx);
+        }
+        if (installation.transaction !== undefined)
+            installation.transaction.invalidated = true;
+        installation.dispose();
+    }
+}
+export default SubagentActivationSetupRegistry;
+//# sourceMappingURL=activation-setup-registry.js.map

package/lib/types/assistant-output.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Canonical selection of a child's final assistant output. Backend run results
+ * and `subagent/end.lastAssistantMessage` apply the same rule: select the last
+ * non-empty assistant message. An empty-content message records usage only
+ * when the loop appends it after a max-tokens step with no executable blocks,
+ * so it does not replace earlier output. If no non-empty message exists,
+ * select the accumulated assistant text. Selection is independent of the
+ * run's stop reason.
+ *
+ * @module @hydraharness/harness-subagent/assistant-output
+ */
+import type { ContentBlock } from '@hydraharness/harness-llm';
+import type { SessionEvent } from '@hydraharness/harness-session';
+/**
+ * Incremental fold of the selection rule, for backends that observe a child's
+ * output as it streams: session-event backends {@link push} each event, and
+ * transports without session events (ACP content chunks) {@link pushText} raw
+ * text into the same streamed fallback.
+ */
+export declare class AssistantOutputFold {
+    private message;
+    private partial;
+    /**
+     * Fold one session event: a non-empty assistant message becomes the
+     * candidate final answer, and a `text-delta` chunk extends the streamed
+     * fallback; every other event contributes nothing.
+     * @param event - the next observed session event.
+     */
+    push(event: SessionEvent): void;
+    /**
+     * Extend the streamed fallback with text observed outside session events.
+     * @param text - the next streamed text piece (an empty piece is a no-op).
+     */
+    pushText(text: string): void;
+    /**
+     * Select the final output folded so far.
+     * @returns the last non-empty assistant message, else the accumulated
+     *   streamed text, or `undefined` when the child produced neither.
+     */
+    collect(): ContentBlock[] | undefined;
+}
+/**
+ * Apply the selection rule to one complete child-owned event suffix.
+ * @param events - the child-owned events (after any seed or epoch boundary).
+ * @returns the selected output, or `undefined` when the child produced none.
+ */
+export declare function finalAssistantOutput(events: readonly SessionEvent[]): ContentBlock[] | undefined;
+//# sourceMappingURL=assistant-output.d.ts.map

package/lib/types/assistant-output.js

@@ -0,0 +1,72 @@
+/**
+ * Canonical selection of a child's final assistant output. Backend run results
+ * and `subagent/end.lastAssistantMessage` apply the same rule: select the last
+ * non-empty assistant message. An empty-content message records usage only
+ * when the loop appends it after a max-tokens step with no executable blocks,
+ * so it does not replace earlier output. If no non-empty message exists,
+ * select the accumulated assistant text. Selection is independent of the
+ * run's stop reason.
+ *
+ * @module @hydraharness/harness-subagent/assistant-output
+ */
+/**
+ * Incremental fold of the selection rule, for backends that observe a child's
+ * output as it streams: session-event backends {@link push} each event, and
+ * transports without session events (ACP content chunks) {@link pushText} raw
+ * text into the same streamed fallback.
+ */
+export class AssistantOutputFold {
+    message;
+    partial = [];
+    /**
+     * Fold one session event: a non-empty assistant message becomes the
+     * candidate final answer, and a `text-delta` chunk extends the streamed
+     * fallback; every other event contributes nothing.
+     * @param event - the next observed session event.
+     */
+    push(event) {
+        if (event.type === 'assistant/message') {
+            const content = event.data.message.content;
+            if (content.length > 0)
+                this.message = content;
+        }
+        else if (event.type === 'assistant/chunk' && event.data.chunk.type === 'text-delta') {
+            this.pushText(event.data.chunk.text);
+        }
+    }
+    /**
+     * Extend the streamed fallback with text observed outside session events.
+     * @param text - the next streamed text piece (an empty piece is a no-op).
+     */
+    pushText(text) {
+        if (text.length > 0)
+            this.partial.push(text);
+    }
+    /**
+     * Select the final output folded so far.
+     * @returns the last non-empty assistant message, else the accumulated
+     *   streamed text, or `undefined` when the child produced neither.
+     */
+    collect() {
+        if (this.message !== undefined)
+            return this.message;
+        const text = this.partial.join('');
+        return text.length > 0 ? [{ type: 'text', text }] : undefined;
+    }
+}
+/**
+ * Apply the selection rule to one complete child-owned event suffix.
+ * @param events - the child-owned events (after any seed or epoch boundary).
+ * @returns the selected output, or `undefined` when the child produced none.
+ */
+export function finalAssistantOutput(events) {
+    // TODO: this folds the complete suffix once per run/epoch settlement. If a
+    // long continuable epoch ever profiles hot here, scan backward with early
+    // exit for the last non-empty message and fold text deltas only on the
+    // no-message fallback.
+    const fold = new AssistantOutputFold();
+    for (const event of events)
+        fold.push(event);
+    return fold.collect();
+}
+//# sourceMappingURL=assistant-output.js.map

package/lib/types/budget.d.ts

@@ -0,0 +1,34 @@
+/** Durable delegation admissions and process-local capacity shared by one session tree. */
+import type { Context } from '@hydraharness/cordis';
+import type { Agent } from '@hydraharness/harness-agent';
+import type { Session } from '@hydraharness/harness-session';
+declare module '@hydraharness/harness-session/types' {
+    interface SessionEventMap {
+        /** One admitted child creation, charged to the delegation root before provider work starts. */
+        'subagent/admission': {
+            parentId: Session['id'];
+        };
+    }
+}
+/**
+ * Resolve the live root whose log owns a tree's cumulative budgets.
+ * @param ctx - context with the session store.
+ * @param agent - current caller.
+ * @returns the root session; refuses a detached child whose ancestry cannot be established.
+ */
+export declare function delegationRoot(ctx: Context, agent: Agent): Session;
+/** Tree admission bounds, supplied explicitly by the deployment. */
+export interface DelegationLimits {
+    /** Maximum simultaneous child residencies and pending starts per root. */
+    maxActivePerTree?: number;
+    /** Maximum cumulative child creation attempts per root session, including failed attempts. */
+    maxChildrenPerTree?: number;
+}
+/**
+ * Reserve capacity before asynchronous setup; a release belongs to the run's settlement.
+ * @param ctx - service context.
+ * @param limits - optional configured caps.
+ * @returns synchronous admission function with an idempotent release.
+ */
+export declare function delegationAdmission(ctx: Context, limits: DelegationLimits): (parent: Agent, creating: boolean) => () => void;
+//# sourceMappingURL=budget.d.ts.map

package/lib/types/budget.js

@@ -0,0 +1,54 @@
+import { SubagentError } from "./error.js";
+/**
+ * Resolve the live root whose log owns a tree's cumulative budgets.
+ * @param ctx - context with the session store.
+ * @param agent - current caller.
+ * @returns the root session; refuses a detached child whose ancestry cannot be established.
+ */
+export function delegationRoot(ctx, agent) {
+    let session = agent.session;
+    const visited = new Set();
+    while (session.header.origin === 'subagent') {
+        if (visited.has(session.id))
+            throw new SubagentError('cyclic delegation ancestry', 'BUDGET_ANCESTRY_UNAVAILABLE');
+        visited.add(session.id);
+        const parent = session.header.parentSession === undefined ? undefined : ctx.get('sessions')?.get(session.header.parentSession);
+        if (parent === undefined)
+            throw new SubagentError('delegation budget requires the live parent session', 'BUDGET_ANCESTRY_UNAVAILABLE');
+        session = parent;
+    }
+    return session;
+}
+/**
+ * Reserve capacity before asynchronous setup; a release belongs to the run's settlement.
+ * @param ctx - service context.
+ * @param limits - optional configured caps.
+ * @returns synchronous admission function with an idempotent release.
+ */
+export function delegationAdmission(ctx, limits) {
+    for (const value of Object.values(limits)) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
+            throw new Error('subagent limits must be positive safe integers');
+    }
+    const active = new WeakMap();
+    return (parent, creating) => {
+        if (limits.maxActivePerTree === undefined && limits.maxChildrenPerTree === undefined)
+            return () => { };
+        const root = delegationRoot(ctx, parent);
+        const slots = active.get(root) ?? new Set();
+        if (limits.maxActivePerTree !== undefined && slots.size >= limits.maxActivePerTree) {
+            throw new SubagentError('delegation tree is at its active child limit; wait for a child to settle', 'SUBAGENT_CAPACITY');
+        }
+        if (creating && limits.maxChildrenPerTree !== undefined) {
+            const used = root.events.filter(event => event.type === 'subagent/admission').length;
+            if (used >= limits.maxChildrenPerTree)
+                throw new SubagentError('delegation tree exhausted its child creation budget', 'SUBAGENT_BUDGET_EXHAUSTED');
+            root.append('subagent/admission', { parentId: parent.id });
+        }
+        const slot = {};
+        slots.add(slot);
+        active.set(root, slots);
+        return () => { slots.delete(slot); };
+    };
+}
+//# sourceMappingURL=budget.js.map

package/lib/types/child-agent.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Shared in-process child composition: the delegation-depth budget, the
+ * durable session metadata, the resolved child `AgentOptions`, the delegated
+ * policy seed, and the scoped setup a child agent needs. Both the one-shot
+ * provider driver and the continuation manager compose children this way, so
+ * depth accounting, lineage stamping, and delegation policy have one home.
+ *
+ * @module @hydraharness/harness-subagent/child-agent
+ */
+import type { Context } from '@hydraharness/cordis';
+import type { Agent, AgentOptions, CreateAgentOptions } from '@hydraharness/harness-agent';
+import type { SandboxMode } from '@hydraharness/harness-sandbox';
+import type { Session, SessionId } from '@hydraharness/harness-session';
+import type { ToolRestriction } from '@hydraharness/harness-tools';
+/** Thrown when starting a child would exceed the requested depth cap. */
+export declare class SubagentDepthError extends Error {
+    readonly attemptedDepth: number;
+    readonly maxDepth: number;
+    constructor(attemptedDepth: number, maxDepth: number);
+}
+/**
+ * Resolve the child's delegation depth from its parent and enforce an optional
+ * cap. The persisted parent header is the monotone floor, so a resumed parent
+ * cannot delegate as if it were top-level.
+ * @param parent - the delegating parent agent.
+ * @param maxDepth - optional absolute cap the resolved depth must not exceed.
+ * @returns the child's non-negative safe-integer depth.
+ * @throws {SubagentDepthError} when the resolved depth exceeds `maxDepth`.
+ * @throws {RangeError} when the resolved depth leaves the safe-integer range.
+ */
+export declare function resolveChildDepth(parent: Agent, maxDepth: number | undefined): number;
+/**
+ * Resolve the child's `AgentOptions`: the parent's provider/model/maxTokens
+ * route unless the request overrides it, stamped with the child's own
+ * delegation depth.
+ * @param parent - the delegating parent whose route the child inherits.
+ * @param requested - per-child overrides, if any.
+ * @param childDepth - the resolved delegation depth to stamp.
+ * @returns the resolved options for `ctx.agents.create()`.
+ */
+export declare function resolveChildAgentOptions(parent: Agent, requested: AgentOptions | undefined, childDepth: number): AgentOptions;
+/**
+ * Build the child session's durable creation metadata: the parent's workspace,
+ * its direct lineage, coarse product origin, the recursion budget that must
+ * survive persistence, the seed boundary that separates inherited parent
+ * history from child work, and the composition the child runs under.
+ *
+ * The preset is read from the parent's LIVE scope chain rather than from its
+ * header, because a parent that switched preset while blank runs on the newer
+ * composition and its header still names the older one. Recording it is what
+ * makes a child's history reconstructable: without it a cold read of the child
+ * resolves the deployment default and rebuilds turns under a tool set the
+ * child never had.
+ * @param parent - the delegating parent agent.
+ * @param childDepth - the resolved delegation depth to persist.
+ * @param lineageSeedLength - how many leading events came from the parent's log.
+ * @returns the `meta` for `ctx.agents.create()`.
+ */
+export declare function childSessionMeta(parent: Agent, childDepth: number, lineageSeedLength: number): NonNullable<CreateAgentOptions['meta']>;
+/** The scoped composition a child agent's creation window applies. */
+export interface ChildComposition {
+    /** Per-child persona shadowing the deployment persona. */
+    readonly persona?: string | undefined;
+    /** Per-child tool scoping. */
+    readonly toolFilter?: ToolRestriction | undefined;
+}
+/**
+ * Model-facing delegation-scope statement for every in-process child. A
+ * runtime-context contribution rather than a system-prompt section, so the
+ * deployment's system prompt stays uniform across parents and children.
+ */
+export declare const SUBAGENT_DELEGATION_CONTEXT: string;
+/**
+ * Compose one child inside its creation window: join its parent's preset,
+ * register the fixed delegation-scope statement, then apply the child's own
+ * shadowing persona section and tool restriction, all owned by the child's
+ * scope and therefore invisible to its parent and siblings. Creation and cold
+ * resume both pass through here.
+ *
+ * The join comes first and the child's own registrations second, which is the
+ * order the layering already implies — the nearest scope wins a name, and a
+ * per-child restriction intersects with everything its chain admits — but
+ * stating it here keeps the two steps from being read as independent.
+ *
+ * The join and the per-child registrations live in ONE call because a child
+ * composed without the join is exactly the defect this function exists to
+ * prevent: with every model-facing row on the agent plane, a child that joins
+ * no preset sees an empty tool registry and none of its parent's prompt
+ * sections. Taking the parent as a parameter is what makes that omission
+ * unrepresentable at the call sites.
+ * @param childCtx - the child agent's scoped creation context.
+ * @param parent - the delegating parent whose composition the child joins.
+ * @param composition - the per-child persona and tool filter to install.
+ */
+export declare function applyChildComposition(childCtx: Context, parent: Agent, composition: ChildComposition): void;
+/** Policy seeded onto a child session's log at the delegation boundary. */
+export interface DelegatedPolicyOverrides {
+    /** The parent session's explicit sandbox-mode override, or `undefined` without one. */
+    readonly sandboxMode: SandboxMode | undefined;
+    /**
+     * `'never'` whenever the approval capability is composed, `undefined`
+     * otherwise: a delegated child acts only within the sandbox scope fixed at
+     * delegation, so its asks are rejected deterministically.
+     */
+    readonly approvalPolicy: 'never' | undefined;
+}
+/**
+ * Capture the policy to seed into one delegation. Call synchronously before
+ * the child start's first await: a later parent switch belongs to the
+ * parent's future, not to this child. Only the parent session's explicit
+ * sandbox override is captured — never deployment defaults or one-shot
+ * grants — and the approval policy is pinned to `'never'` regardless of the
+ * parent's own policy.
+ * @param parent - the delegating parent agent.
+ * @returns the sandbox override (or `undefined` without one) and the approval pin.
+ */
+export declare function captureDelegatedPolicyOverrides(parent: Agent): DelegatedPolicyOverrides;
+/**
+ * Append the captured delegation policy onto the child's own log as
+ * `source: 'delegation'` events inside the unpublished creation window, so the
+ * child's effective policy is reconstructable from its log alone. Appends land
+ * after any fork seed, so fresh policy wins stale seed state; later child
+ * switches still win over these events.
+ * @param childSession - the unpublished child's session.
+ * @param overrides - the policy captured at delegation.
+ */
+export declare function appendDelegatedPolicyOverrides(childSession: Session, overrides: DelegatedPolicyOverrides): void;
+/** Identity and lineage inputs shared by every in-process child creation. */
+export interface ChildCreateInputs {
+    /** The child's reserved session id. */
+    readonly sessionId: SessionId;
+    /** The delegating parent agent. */
+    readonly parent: Agent;
+    /** The resolved delegation depth. */
+    readonly childDepth: number;
+    /** How many leading seed events came from the parent's log. */
+    readonly lineageSeedLength: number;
+}
+//# sourceMappingURL=child-agent.d.ts.map