@qlzt/dsh-subagent 0.0.0-stage → 0.2.1-alpha.3

package/lib/types/catalog.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Parent-owned durable subagent catalog events and their chunked projection.
+ *
+ * @module @qlzt/dsh-subagent/catalog
+ */
+import { z } from 'zod';
+import type { ChunkedList } from '@qlzt/dsh-chunked-list';
+import type { Session, SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@qlzt/dsh-session';
+import type { SubagentCatalogEntry } from './projection-types.ts';
+/** Catalog payload version emitted by local child creation. */
+export declare const SUBAGENT_CATALOG_VERSION = 0;
+type KnownCatalogMode = {
+    readonly mode: 'one-shot';
+    readonly label?: string;
+} | {
+    readonly mode: 'continuable';
+    readonly label: string;
+};
+/** Parent catalog v0 records local modes, v1 adds unknown children, and v2 records external executions. */
+export type SubagentCatalogEvent = {
+    readonly childId: SessionId;
+    readonly childCreatedAt: number;
+} & (({
+    readonly version: 0;
+} & KnownCatalogMode) | ({
+    readonly version: 1;
+} & (KnownCatalogMode | {
+    readonly mode: 'unknown';
+    readonly label?: string;
+})) | {
+    readonly version: 2;
+    readonly mode: 'external';
+    readonly label?: string;
+});
+declare module '@qlzt/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * A direct child's identity and available discovery fields.
+         * @param data - versioned parent-owned catalog entry.
+         */
+        'subagent/catalog': SubagentCatalogEvent;
+    }
+}
+/** Host fold state for one parent catalog. */
+export interface SubagentCatalogState {
+    readonly inheritedEventCount: SessionLogOffset;
+    readonly head?: ChunkedList<SubagentCatalogEvent> | undefined;
+}
+declare module '@qlzt/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        subagentCatalog: SubagentCatalogState;
+    }
+}
+/**
+ * Materialize complete and unknown-mode child identities from parent catalog events.
+ * @param state - parent catalog fold state.
+ * @returns current direct-child rows in parent catalog event order.
+ */
+declare function subagentCatalogEntries(state: SubagentCatalogState): SubagentCatalogEntry[];
+/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
+export declare const subagentCatalogProjectionDefinition: {
+    key: "subagentCatalog";
+    stateSchema: z.ZodType<SubagentCatalogState, unknown, z.core.$ZodTypeInternals<SubagentCatalogState, unknown>>;
+    init: (_header: SessionHeader, inheritedEventCount: SessionLogOffset) => {
+        inheritedEventCount: SessionLogOffset;
+    };
+    apply: (state: NoInfer<SubagentCatalogState>, event: SessionEvent) => SubagentCatalogState;
+    stateVersion: number;
+    wire: {
+        viewSchema: z.ZodType<SubagentCatalogEntry[], unknown, z.core.$ZodTypeInternals<SubagentCatalogEntry[], unknown>>;
+        view: typeof subagentCatalogEntries;
+    };
+};
+/**
+ * Append a complete direct-child discovery fact to its parent Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param child - established child's immutable Session metadata.
+ * @param descriptor - mode-discriminated creation label frozen with the child.
+ */
+export declare function establishCatalogChild(parent: Session, child: SessionHeader, descriptor: {
+    readonly mode: 'continuable';
+    readonly label: string;
+}): void;
+/**
+ * Record an external execution without a local child Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param childId - identity returned by the external provider.
+ * @param label - display label assigned by the caller.
+ */
+export declare function establishExternalCatalogChild(parent: Session, childId: SessionId, label: string): void;
+export {};
+//# sourceMappingURL=catalog.d.ts.map

package/lib/types/catalog.js

@@ -0,0 +1,113 @@
+/**
+ * Parent-owned durable subagent catalog events and their chunked projection.
+ *
+ * @module @qlzt/dsh-subagent/catalog
+ */
+import { z } from 'zod';
+import { appendChunkedList, chunkedListSchema, iterateChunkedList } from '@qlzt/dsh-chunked-list';
+/** Catalog payload version emitted by local child creation. */
+export const SUBAGENT_CATALOG_VERSION = 0;
+const sessionIdSchema = z.string();
+const oneShotCatalogSchema = z.object({
+    version: z.union([z.literal(0), z.literal(1)]),
+    childId: sessionIdSchema,
+    childCreatedAt: z.number().int().nonnegative(),
+    mode: z.literal('one-shot'),
+    label: z.string().optional(),
+}).strict();
+const continuableCatalogSchema = z.object({
+    version: z.union([z.literal(0), z.literal(1)]),
+    childId: sessionIdSchema,
+    childCreatedAt: z.number().int().nonnegative(),
+    mode: z.literal('continuable'),
+    label: z.string(),
+}).strict();
+const externalCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(2), mode: z.literal('external') });
+const unknownCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(1), mode: z.literal('unknown') });
+const eventDataSchema = z.union([
+    oneShotCatalogSchema,
+    externalCatalogSchema,
+    continuableCatalogSchema,
+    unknownCatalogSchema,
+]);
+const viewSchema = z.array(z.union([
+    oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: oneShotCatalogSchema.shape.childCreatedAt,
+    }),
+    externalCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: externalCatalogSchema.shape.childCreatedAt,
+    }),
+    continuableCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: continuableCatalogSchema.shape.childCreatedAt,
+    }),
+    unknownCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: unknownCatalogSchema.shape.childCreatedAt,
+    }),
+]));
+const stateSchema = z.object({
+    inheritedEventCount: z.number().int().nonnegative(),
+    head: chunkedListSchema(eventDataSchema).optional(),
+}).strict();
+/**
+ * Materialize complete and unknown-mode child identities from parent catalog events.
+ * @param state - parent catalog fold state.
+ * @returns current direct-child rows in parent catalog event order.
+ */
+function subagentCatalogEntries(state) {
+    const entries = [];
+    for (const data of iterateChunkedList(state.head)) {
+        const { version: _version, childId, childCreatedAt, ...descriptor } = data;
+        entries.push({ id: childId, createdAt: childCreatedAt, ...descriptor });
+    }
+    return entries;
+}
+/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
+export const subagentCatalogProjectionDefinition = {
+    key: 'subagentCatalog',
+    stateSchema,
+    init: (_header, inheritedEventCount) => ({ inheritedEventCount }),
+    apply: (state, event) => {
+        if (event.type !== 'subagent/catalog' || event.seq < state.inheritedEventCount)
+            return state;
+        return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) };
+    },
+    stateVersion: 6,
+    wire: { viewSchema, view: subagentCatalogEntries },
+};
+/**
+ * Append a complete direct-child discovery fact to its parent Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param child - established child's immutable Session metadata.
+ * @param descriptor - mode-discriminated creation label frozen with the child.
+ */
+export function establishCatalogChild(parent, child, descriptor) {
+    parent.append('subagent/catalog', {
+        version: SUBAGENT_CATALOG_VERSION,
+        childId: child.id,
+        childCreatedAt: child.createdAt,
+        mode: descriptor.mode,
+        label: descriptor.label,
+    });
+}
+/** Catalog payload version emitted by external execution creation. */
+const EXTERNAL_SUBAGENT_CATALOG_VERSION = 2;
+/**
+ * Record an external execution without a local child Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param childId - identity returned by the external provider.
+ * @param label - display label assigned by the caller.
+ */
+export function establishExternalCatalogChild(parent, childId, label) {
+    parent.append('subagent/catalog', {
+        version: EXTERNAL_SUBAGENT_CATALOG_VERSION,
+        childId,
+        childCreatedAt: Date.now(),
+        mode: 'external',
+        label,
+    });
+}
+//# sourceMappingURL=catalog.js.map

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

@@ -0,0 +1,154 @@
+/**
+ * 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 used by local activations.
+ *
+ * @module @qlzt/dsh-subagent/child-agent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentOptions, CreateAgentOptions } from '@qlzt/dsh-agent';
+import type { SandboxMode } from '@qlzt/dsh-sandbox';
+import type { Session, SessionId } from '@qlzt/dsh-session';
+import type { ToolRestriction } from '@qlzt/dsh-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 parent values inherited by a child. The latest request header
+ * owns provider, model, and reasoning effort after request-time selection;
+ * creation options remain the fallback before the first request and retain
+ * the configured output-token limit.
+ * @param parent - delegating parent Agent.
+ * @returns detached Agent options for child-option merging.
+ */
+export declare function parentAgentOptionsForDelegation(parent: Agent): AgentOptions;
+/**
+ * Resolve the child's `AgentOptions`: the parent's provider/model,
+ * reasoning-effort, and maxTokens values unless the request overrides them,
+ * stamped with the child's own delegation depth. Changing the route without
+ * naming an effort clears the parent's route-owned effort so the selected
+ * model resolves its own default.
+ * @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 isSeeded - whether this child inherits a parent-log prefix, including an explicitly empty one.
+ * @returns the `meta` for `ctx.agents.create()`.
+ */
+export declare function childSessionMeta(parent: Agent, childDepth: number, isSeeded: boolean): 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's current preset identity when it runs in Auto or Full access;
+     * the child keeps it under the pinned `never` approval policy.
+     */
+    readonly permissionPreset: 'auto' | 'danger-full-access' | undefined;
+    /** 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 permission state 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. Auto and Full access identities are
+ * inherited only through the in-process DSH path so either can replace a stale
+ * same-bundle fork value. 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

package/lib/types/child-agent.js

@@ -0,0 +1,211 @@
+/**
+ * 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 used by local activations.
+ *
+ * @module @qlzt/dsh-subagent/child-agent
+ */
+import { delegationDepthOf } from "./depth.js";
+/** Thrown when starting a child would exceed the requested depth cap. */
+export class SubagentDepthError extends Error {
+    attemptedDepth;
+    maxDepth;
+    constructor(attemptedDepth, maxDepth) {
+        super(`subagent depth ${attemptedDepth} exceeds maxDepth ${maxDepth}`);
+        this.attemptedDepth = attemptedDepth;
+        this.maxDepth = maxDepth;
+        this.name = 'SubagentDepthError';
+    }
+}
+/**
+ * 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 function resolveChildDepth(parent, maxDepth) {
+    const childDepth = delegationDepthOf(parent) + 1;
+    if (!Number.isSafeInteger(childDepth)) {
+        throw new RangeError('subagent child depth exceeds the safe-integer range');
+    }
+    if (maxDepth !== undefined && childDepth > maxDepth) {
+        throw new SubagentDepthError(childDepth, maxDepth);
+    }
+    return childDepth;
+}
+/**
+ * Resolve the parent values inherited by a child. The latest request header
+ * owns provider, model, and reasoning effort after request-time selection;
+ * creation options remain the fallback before the first request and retain
+ * the configured output-token limit.
+ * @param parent - delegating parent Agent.
+ * @returns detached Agent options for child-option merging.
+ */
+export function parentAgentOptionsForDelegation(parent) {
+    const requestConfig = parent.session.requestHeader()?.config;
+    if (requestConfig === undefined)
+        return { ...parent.options };
+    const { provider: _createdProvider, model: _createdModel, reasoningEffort: _createdReasoningEffort, ...createdOptions } = parent.options;
+    return {
+        ...createdOptions,
+        provider: requestConfig.provider,
+        model: requestConfig.model,
+        ...requestConfig.reasoningEffort === undefined
+            ? {}
+            : { reasoningEffort: requestConfig.reasoningEffort },
+    };
+}
+/**
+ * Resolve the child's `AgentOptions`: the parent's provider/model,
+ * reasoning-effort, and maxTokens values unless the request overrides them,
+ * stamped with the child's own delegation depth. Changing the route without
+ * naming an effort clears the parent's route-owned effort so the selected
+ * model resolves its own default.
+ * @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 function resolveChildAgentOptions(parent, requested, childDepth) {
+    const parentOptions = parentAgentOptionsForDelegation(parent);
+    const parentProvider = parentOptions.provider;
+    const parentModel = parentOptions.model;
+    const parentReasoningEffort = parentOptions.reasoningEffort;
+    const parentMaxTokens = parentOptions.maxTokens;
+    const resolved = {
+        ...parentProvider !== undefined ? { provider: parentProvider } : {},
+        ...parentModel !== undefined ? { model: parentModel } : {},
+        ...parentReasoningEffort !== undefined ? { reasoningEffort: parentReasoningEffort } : {},
+        ...parentMaxTokens !== undefined ? { maxTokens: parentMaxTokens } : {},
+        ...requested,
+        subagentDepth: childDepth,
+    };
+    const routeChanged = resolved.provider !== parentProvider || resolved.model !== parentModel;
+    if (routeChanged && requested?.reasoningEffort === undefined)
+        delete resolved.reasoningEffort;
+    return resolved;
+}
+/**
+ * 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 isSeeded - whether this child inherits a parent-log prefix, including an explicitly empty one.
+ * @returns the `meta` for `ctx.agents.create()`.
+ */
+export function childSessionMeta(parent, childDepth, isSeeded) {
+    const parentHeader = parent.session.header;
+    const agentPreset = parent.ctx.get('agentPresets')?.composedPreset(parent.ctx);
+    return {
+        ...parentHeader.cwd !== undefined ? { cwd: parentHeader.cwd } : {},
+        ...agentPreset === undefined ? {} : { agentPreset },
+        parentSession: parentHeader.id,
+        isSeeded,
+        // Navigation classification only; the descriptor remains the authority
+        // for mode and continuation capability.
+        origin: 'subagent',
+        // Durable: the recursion budget must survive persistence and resume.
+        delegationDepth: childDepth,
+    };
+}
+/**
+ * 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 const SUBAGENT_DELEGATION_CONTEXT = 'You are a delegated subagent: your permission scope was fixed when you were started and cannot be '
+    + 'widened from inside this session — operations that require approval are rejected automatically. '
+    + 'When the task needs access beyond that scope, do not retry the denied operation; state the '
+    + 'limitation in your reply so the delegating agent can handle it.';
+/**
+ * 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 function applyChildComposition(childCtx, parent, composition) {
+    childCtx.get('agentPresets')?.composeFrom(childCtx, parent.ctx);
+    childCtx.systemPrompt.context({
+        name: 'subagent:delegation',
+        order: childCtx.systemPrompt.getContextOrder('SUBAGENT_DELEGATION'),
+        text: SUBAGENT_DELEGATION_CONTEXT,
+    });
+    if (composition.persona !== undefined) {
+        childCtx.systemPrompt.section({
+            name: 'deployment:persona-prefix',
+            order: childCtx.systemPrompt.getSectionOrder('DEPLOYMENT_PERSONA_PREFIX'),
+            text: composition.persona,
+        });
+    }
+    if (composition.toolFilter !== undefined)
+        childCtx.tools.restrict(composition.toolFilter);
+}
+/**
+ * Capture the permission state 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. Auto and Full access identities are
+ * inherited only through the in-process DSH path so either can replace a stale
+ * same-bundle fork value. 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 function captureDelegatedPolicyOverrides(parent) {
+    const preset = parent.ctx.get('permissionPresets')?.current(parent.session);
+    return {
+        permissionPreset: preset === 'auto' || preset === 'danger-full-access' ? preset : undefined,
+        sandboxMode: parent.ctx.get('sandboxPolicy')?.overrideOf(parent.session),
+        approvalPolicy: parent.ctx.get('approval') === undefined ? undefined : 'never',
+    };
+}
+/**
+ * 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 function appendDelegatedPolicyOverrides(childSession, overrides) {
+    if (overrides.sandboxMode !== undefined) {
+        childSession.append('sandbox/mode', { mode: overrides.sandboxMode, source: 'delegation' });
+    }
+    if (overrides.approvalPolicy !== undefined) {
+        childSession.append('approval/policy', { policy: overrides.approvalPolicy, source: 'delegation' });
+    }
+    if (overrides.permissionPreset !== undefined) {
+        childSession.append('permission/preset', { preset: overrides.permissionPreset });
+    }
+}
+//# sourceMappingURL=child-agent.js.map

package/lib/types/client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser-safe subagent projection and control vocabulary.
+ *
+ * @module @qlzt/dsh-subagent/client
+ */
+export type * from './control-types.ts';
+export type { SubagentCatalogEntry, SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,7 @@
+/**
+ * Browser-safe subagent projection and control vocabulary.
+ *
+ * @module @qlzt/dsh-subagent/client
+ */
+export {};
+//# sourceMappingURL=client.js.map

package/lib/types/continuation-messages.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Model-visible messages owned by continuable-subagent orchestration.
+ *
+ * @module @qlzt/dsh-subagent/continuation-messages
+ */
+import type { Agent } from '@qlzt/dsh-agent';
+import { createUserMessage } from '@qlzt/dsh-llm';
+import type { ContentBlock } from '@qlzt/dsh-llm';
+import type { SessionId } from '@qlzt/dsh-session';
+import type { SubagentResult } from './types.ts';
+/** Durable attribution for one model-authored message between Agents. */
+export interface AgentMessageSource {
+    readonly kind: 'agent-message';
+    /** A message another agent addressed to this one (`relay` context form). */
+    readonly form: 'relay';
+    /** Session id of the Agent whose tool call produced the message. */
+    readonly senderSessionId: SessionId;
+}
+/**
+ * Durable attribution for the runtime's own account of a continuable child
+ * settling. Deliberately a different kind from
+ * {@link AgentMessageSource}: an Agent message is content the sender chose,
+ * while this message is the manager stating what became of the child, and a
+ * transcript that merged them would credit the child with words it never wrote.
+ */
+export interface SubagentSettledMessageSource {
+    readonly kind: 'subagent-settled';
+    /** A runtime account shown without expanding the row (`notice` context form). */
+    readonly form: 'notice';
+    /** One-line account of how the child ended. */
+    readonly summary: string;
+    /** Session id of the child that settled. */
+    readonly senderSessionId: SessionId;
+}
+declare module '@qlzt/dsh-llm' {
+    interface MessageSourceMap {
+        'agent-message': AgentMessageSource;
+        'subagent-settled': SubagentSettledMessageSource;
+    }
+}
+/**
+ * Build the model-visible and durable representation of one adjacent-Agent message.
+ * @param sender - exact live Agent that authored the message.
+ * @param content - model-visible message blocks supplied by the sender.
+ * @returns the durable user-message representation delivered to the recipient.
+ */
+export declare function createAgentMessage(sender: Agent, content: ContentBlock[]): ReturnType<typeof createUserMessage>;
+/**
+ * Append adjacent-Agent return guidance to a continuable child's initial task.
+ * @param parentId - durable parent session id named in the guidance.
+ * @param prompt - initial model-visible task blocks.
+ * @returns task blocks followed by the continuable return guidance.
+ */
+export declare function withContinuableReturnGuidance(parentId: SessionId, prompt: ContentBlock[]): ContentBlock[];
+/**
+ * Build the runtime-owned settlement notice from the child's nonempty closing text.
+ * @param childId - durable child session id named in the notice.
+ * @param terminal - recorded terminal state for the settled Activation.
+ * @param continuable - whether the child can accept another task.
+ * @returns the durable user-message representation delivered to the parent.
+ */
+export declare function createSettlementMessage(childId: SessionId, terminal: SubagentResult, continuable?: boolean): ReturnType<typeof createUserMessage>;
+//# sourceMappingURL=continuation-messages.d.ts.map