@dsh-cc/subagent-task 0.5.0

package/lib/epoch-collector.js

@@ -0,0 +1,243 @@
+/**
+ * The dsh-cc epoch collector: inline first-epoch collection of a continuable
+ * subagent child with zero harness changes (normative design:
+ * `docs/plans/2026-09-10-epoch-collector-dsh-cc.md`).
+ *
+ * One shared `subagent/start` + `subagent/end` listener pair and one watch
+ * map (`Map<childId, { runId?, resolve }>`) serve every collector of the
+ * process. The reservation is placed BEFORE `startContinuable` so an
+ * immediate settle cannot fall between start and subscription; the runId is
+ * captured from the child's first `subagent/start` and the end event is
+ * matched by runId (a cold-resumed later epoch has a new runId and never
+ * satisfies a stale watcher). The shared listeners are disposed when the map
+ * empties.
+ *
+ * This module is the ONE-FILE swap seam (§7): when upstream later ships the
+ * collectable continuable handle, only this file's `collectFirstEpoch`
+ * implementation is replaced — the Task tool and TUI surfaces are untouched.
+ *
+ * @module @dsh-cc/subagent-task/epoch-collector
+ */
+/** The one shared watch map (per-process singleton, §3 "Parallel collects"). */
+const watches = new Map();
+/** The bus the shared listener pair is currently subscribed to. */
+let watchedBus;
+/** Disposer of the shared listener pair on {@link watchedBus}. */
+let disposeWatchers;
+function ensureWatchers(bus) {
+    if (disposeWatchers !== undefined && watchedBus === bus)
+        return;
+    // A collect on a different bus (never happens in production, where every
+    // collector shares the one cordis context) re-subscribes on the new bus.
+    if (disposeWatchers !== undefined)
+        disposeWatchers();
+    const offStart = bus.on('subagent/start', info => {
+        const entry = watches.get(String(info.id));
+        if (entry !== undefined && entry.runId === undefined)
+            entry.runId = String(info.runId);
+    });
+    const offEnd = bus.on('subagent/end', info => {
+        const runId = String(info.runId);
+        for (const [childId, entry] of watches) {
+            if (entry.runId !== runId)
+                continue;
+            watches.delete(childId);
+            const output = info.lastAssistantMessage;
+            entry.resolve({
+                stopReason: String(info.stopReason),
+                ...(output !== undefined ? { output } : {}),
+            });
+            if (watches.size === 0 && disposeWatchers !== undefined)
+                disposeWatchers();
+            return;
+        }
+    });
+    watchedBus = bus;
+    disposeWatchers = () => {
+        offStart?.();
+        offEnd?.();
+        watchedBus = undefined;
+    };
+}
+function release(childId) {
+    watches.delete(childId);
+    if (watches.size === 0 && disposeWatchers !== undefined)
+        disposeWatchers();
+}
+/** Instrumentation for tests and diagnostics: live watch entries. */
+export function epochWatchSize() {
+    return watches.size;
+}
+// ── Duplicate-notice suppression bookkeeping (§5) ─────────────────────────
+/**
+ * The pop-once "collected" set: senderSessionIds whose `subagent-settled`
+ * notice must be dropped because the epoch was consumed inline. Entries are
+ * popped by the suppression pre-step listener on first delivery, so a later
+ * epoch of the same child delivers normally.
+ */
+const collectedForSuppression = new Set();
+/** Mark a child's settlement notice for drop (done at collect reservation). */
+export function markCollectedForSuppression(childId) {
+    collectedForSuppression.add(childId);
+}
+/**
+ * Un-mark a child (a promoted child is never suppressed — its notice flows
+ * normally; Slice 3's `promote()` calls this).
+ */
+export function releaseCollectedForSuppression(childId) {
+    collectedForSuppression.delete(childId);
+}
+/** Whether a child's settlement notice is currently marked for drop. */
+export function isCollectedForSuppression(childId) {
+    return collectedForSuppression.has(childId);
+}
+const registrations = new Map();
+/** Registry key: parentSessionId + toolCallToken. */
+export function collectorKey(parentSessionId, toolCallToken) {
+    return `${parentSessionId}\u0000${toolCallToken}`;
+}
+export function registerCollector(key, handle) {
+    registrations.set(key, handle);
+}
+export function unregisterCollector(key) {
+    registrations.delete(key);
+}
+export function collectorFor(key) {
+    return registrations.get(key);
+}
+/**
+ * All live registrations of ONE parent session (the TUI busy-branch Ctrl+B
+ * query, F9): every armed collect whose compound key starts with the session
+ * prefix. A promoted/settled/aborted collect unregisters itself, so an
+ * armed entry here is exactly a promotable foreground wait.
+ */
+export function collectorsForSession(parentSessionId) {
+    const prefix = `${parentSessionId}\u0000`;
+    const found = [];
+    for (const [key, handle] of registrations) {
+        if (key.startsWith(prefix))
+            found.push(handle);
+    }
+    return found;
+}
+/** Instrumentation for tests and diagnostics: live registration count. */
+export function registeredCollectorCount() {
+    return registrations.size;
+}
+/**
+ * Collect a continuable child's first epoch inline. Never awaits the parent's
+ * inbound messages — only bus events (§3 deadlock rule).
+ */
+export async function collectFirstEpoch(deps) {
+    const { bus, childId, agent, signal, subagents, start } = deps;
+    markCollectedForSuppression(childId);
+    let resolveEntry;
+    const entry = { resolve: terminal => resolveEntry(terminal) };
+    const epochPromise = new Promise(resolve => {
+        resolveEntry = resolve;
+    });
+    let interrupted = false;
+    let promoted = false;
+    let settled = false;
+    let raceAbort;
+    const abortPromise = new Promise(resolve => {
+        raceAbort = resolve;
+    });
+    let resolvePromoted;
+    const promotedPromise = new Promise(resolve => {
+        resolvePromoted = resolve;
+    });
+    // The promotion-registry registration (§6): registered BEFORE start, so a
+    // Ctrl+B fired during the still-in-flight `startContinuable` finds the
+    // armed handle; unregistered on EVERY resolution path (settle, abort,
+    // promote, start-throw) — a resolved collect is never promotable.
+    const registrationKey = deps.parentSessionId !== undefined && deps.toolCallToken !== undefined
+        ? collectorKey(deps.parentSessionId, deps.toolCallToken)
+        : undefined;
+    const registration = {
+        childId,
+        promote() {
+            // Idempotent: a collect already resolved (settled) or already promoted
+            // never re-releases, re-un-suppresses, or re-resolves.
+            if (settled || promoted)
+                return;
+            promoted = true;
+            // Release the watch: the runId-matched `subagent/end` arriving later
+            // resolves nothing — the epoch is no longer awaited (§6).
+            release(childId);
+            // The promoted child's eventual settlement notice flows NORMALLY
+            // (exactly-once, un-suppressed).
+            releaseCollectedForSuppression(childId);
+            resolvePromoted();
+        },
+        abort() {
+            if (settled || interrupted)
+                return;
+            onAbort();
+        },
+    };
+    const onAbort = () => {
+        if (interrupted)
+            return;
+        interrupted = true;
+        // Interrupt exactly once (M5); an absent/settled target is an accepted
+        // no-op, and an admission throw must never block the prompt resolve.
+        if (subagents?.interrupt !== undefined) {
+            try {
+                subagents.interrupt(childId, { kind: 'ancestor', agent });
+            }
+            catch {
+                // Degraded: the prompt resolve below is still prompt and observable.
+            }
+        }
+        raceAbort?.({ kind: 'aborted', stopReason: 'aborted' });
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    // Reserve BEFORE start (§8 race register).
+    watches.set(childId, entry);
+    ensureWatchers(bus);
+    if (registrationKey !== undefined)
+        registerCollector(registrationKey, registration);
+    const finish = () => {
+        settled = true;
+        if (registrationKey !== undefined)
+            unregisterCollector(registrationKey);
+        signal.removeEventListener('abort', onAbort);
+    };
+    try {
+        await start();
+    }
+    catch (error) {
+        finish();
+        release(childId);
+        releaseCollectedForSuppression(childId);
+        throw error;
+    }
+    if (signal.aborted)
+        onAbort();
+    // Pre-acceptance promotion (§6): a promote() that fired while
+    // `startContinuable` was still in flight resolves the tool call AS SOON AS
+    // start resolves — the child is accepted, its id durable, the epoch never
+    // awaited. The watch was already released by promote(); the settled notice
+    // was already un-suppressed.
+    if (promoted) {
+        finish();
+        return { kind: 'promoted' };
+    }
+    const outcome = await Promise.race([
+        epochPromise.then((terminal) => ({ kind: 'epoch', ...terminal })),
+        abortPromise,
+        promotedPromise.then(() => ({ kind: 'promoted' })),
+    ]);
+    finish();
+    if (outcome.kind === 'aborted') {
+        // Keep the watch entry armed ONLY to drive suppression bookkeeping: the
+        // child's real `subagent/end` arrives later and releases the entry.
+        return outcome;
+    }
+    // Epoch end already released the entry (and disposed the shared listeners
+    // when the map emptied); the suppression mark stays until the pop-once
+    // listener consumes the duplicated settled notice.
+    return outcome;
+}
+//# sourceMappingURL=epoch-collector.js.map

package/lib/epoch-collector.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Claude Code-compatible Task tool and per-workspace subagent catalog for the
+ * DeepSeek Harness. Mounts:
+ * - the `subagent_fork` tool (CC display name `Task`) with `subagent_type`
+ *   dispatch over the session workspace's `.claude/agents` definitions;
+ * - the `Available subagents` system-prompt section rendered per workspace;
+ * - the reserved tool names that keep disabled harness rows restrictable;
+ * - a pre-step strip listener that removes the harness `agent-instructions`
+ *   workspace baseline from delegated children so each child keeps its own
+ *   persona instead of also loading the parent's CLAUDE.md / AGENTS.md.
+ *
+ * The `ccModelRoutes` service (from `@dsh-cc/model-aliases`) supplies
+ * the spawn-time alias resolver; when absent, every child inherits its
+ * parent's route (the builtin fallback).
+ *
+ * @module @dsh-cc/subagent-task
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ResumePinsConfig } from './resume-capture.ts';
+export { AgentRegistry } from './registry.ts';
+export { registerTaskTool, TASK_TOOL, MAX_LIVE_CONTINUABLE_CHILDREN, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS, backgroundTasksDisabled, } from './tool.ts';
+export { collectFirstEpoch, collectorFor, collectorKey, registerCollector, unregisterCollector, collectorsForSession, registeredCollectorCount, markCollectedForSuppression, releaseCollectedForSuppression, isCollectedForSuppression, } from './epoch-collector.ts';
+export type { CollectorRegistration, EpochOutcome, EpochTerminal, } from './epoch-collector.ts';
+export { mountAgentCatalog } from './catalog.ts';
+export { mountStripWorkspaceInstructions, isDelegated, isAgentInstructions, } from './strip-instructions.ts';
+export { isSubagentSettledNotice, mountSettledNoticeSuppression, } from './suppress-settled.ts';
+export type { ResumePinsConfig, CaptureInput } from './resume-capture.ts';
+export { SpawnPinCapture, overlayRoute, probeWorkspace } from './resume-capture.ts';
+/** Cordis plugin id. */
+export declare const name = "cc-subagent-task";
+/** Section name for the background-subagent contract. */
+export declare const BACKGROUND_SECTION_NAME = "cc:subagent-background";
+export declare const BACKGROUND_SECTION_TEXT: string;
+/**
+ * Register the static background-loop system-prompt section (same contract the
+ * Task tool description teaches, stated once so it survives description
+ * trimming). No-op when the system-prompt seam is absent.
+ * @param ctx - the plug context.
+ * @returns the section disposer, or undefined when the seam is absent.
+ */
+export declare function mountBackgroundSection(ctx: Context): (() => void) | undefined;
+/** Plugin configuration. */
+export interface TaskPluginConfig {
+    /**
+     * Spawn-time resume-pin capture (plan §4.3/§4.5) for continuable background
+     * children. Absent (default) → zero behavior change: no pin writes, no
+     * preflight, identical spawns.
+     */
+    readonly resumePins?: ResumePinsConfig;
+}
+/**
+ * Mount the Task tool, the agents catalog, and the workspace-instruction
+ * strip. Safe when either the tools or the system-prompt seam is absent
+ * (the corresponding mount skips); the pre-step listener only needs
+ * `ctx.on`, so it mounts regardless.
+ * @param ctx - the plug context.
+ * @param config - plugin configuration; omitted `resumePins` still arms capture
+ * when the resume-pins plugin's `resumePinStore` service is mounted (plan
+ * §4.10); with neither, capture is disabled.
+ */
+export declare function apply(ctx: Context, config?: TaskPluginConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAOlD,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAO5E,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,6BAA6B,EAC7B,oCAAoC,EACpC,uBAAuB,GACxB,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,2BAA2B,EAC3B,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,qBAAqB,EACrB,YAAY,EACZ,aAAa,GACd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,EACL,+BAA+B,EAC/B,WAAW,EACX,mBAAmB,GACpB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACzE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEnF,wBAAwB;AACxB,eAAO,MAAM,IAAI,qBAAqB,CAAA;AAEtC,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,2BAA2B,CAAA;AAK/D,eAAO,MAAM,uBAAuB,QAwBxB,CAAA;AAEZ;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAU7E;AAED,4BAA4B;AAC5B,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAA;CACvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,gBAAqB,GAAG,IAAI,CAuBvE"}

package/lib/index.js

@@ -0,0 +1,143 @@
+/**
+ * Claude Code-compatible Task tool and per-workspace subagent catalog for the
+ * DeepSeek Harness. Mounts:
+ * - the `subagent_fork` tool (CC display name `Task`) with `subagent_type`
+ *   dispatch over the session workspace's `.claude/agents` definitions;
+ * - the `Available subagents` system-prompt section rendered per workspace;
+ * - the reserved tool names that keep disabled harness rows restrictable;
+ * - a pre-step strip listener that removes the harness `agent-instructions`
+ *   workspace baseline from delegated children so each child keeps its own
+ *   persona instead of also loading the parent's CLAUDE.md / AGENTS.md.
+ *
+ * The `ccModelRoutes` service (from `@dsh-cc/model-aliases`) supplies
+ * the spawn-time alias resolver; when absent, every child inherits its
+ * parent's route (the builtin fallback).
+ *
+ * @module @dsh-cc/subagent-task
+ */
+import { PinStore } from '@dsh-cc/subagent-resume-pins';
+import { collectorFor, collectorsForSession, registeredCollectorCount, } from "./epoch-collector.js";
+import { SpawnPinCapture } from "./resume-capture.js";
+import { AgentRegistry } from "./registry.js";
+import { registerTaskTool } from "./tool.js";
+import { mountSettledNoticeSuppression } from "./suppress-settled.js";
+import { mountAgentCatalog } from "./catalog.js";
+import { mountStripWorkspaceInstructions } from "./strip-instructions.js";
+export { AgentRegistry } from "./registry.js";
+export { registerTaskTool, TASK_TOOL, MAX_LIVE_CONTINUABLE_CHILDREN, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS, backgroundTasksDisabled, } from "./tool.js";
+export { collectFirstEpoch, collectorFor, collectorKey, registerCollector, unregisterCollector, collectorsForSession, registeredCollectorCount, markCollectedForSuppression, releaseCollectedForSuppression, isCollectedForSuppression, } from "./epoch-collector.js";
+export { mountAgentCatalog } from "./catalog.js";
+export { mountStripWorkspaceInstructions, isDelegated, isAgentInstructions, } from "./strip-instructions.js";
+export { isSubagentSettledNotice, mountSettledNoticeSuppression, } from "./suppress-settled.js";
+export { SpawnPinCapture, overlayRoute, probeWorkspace } from "./resume-capture.js";
+/** Cordis plugin id. */
+export const name = 'cc-subagent-task';
+/** Section name for the background-subagent contract. */
+export const BACKGROUND_SECTION_NAME = 'cc:subagent-background';
+/** Order slot beside the catalog section (tool guidance owns 100–199). */
+const BACKGROUND_SECTION_ORDER = 112;
+export const BACKGROUND_SECTION_TEXT = [
+    '## Background subagents',
+    '',
+    '- Heuristic: if this turn\'s answer to the human depends on the child, omit `run_in_background`',
+    '  (foreground — the call waits for the final text). If the human can keep talking while the',
+    '  child works, pass `run_in_background: true`: the call returns promptly with a durable',
+    '  `agentId` once the child accepts its first turn. Synthesize on the wake; do not poll.',
+    '- A definition with `background: true` backgrounds on omit: the call returns',
+    '  `{ status: \'async_launched\' }` immediately and the real result arrives later as a wake',
+    '  message — there is NO inline result to use, so never compose on one. Pass',
+    '  `run_in_background: false` when this turn needs that child\'s result: it forces',
+    '  synchronous collection. Explicit true/false always win over the pin.',
+    '- A background child\'s report — or its finish notice when it ends without reporting — arrives',
+    '  as a waking message; do not poll.',
+    '- Control the child by that id: `list_agents` for status, `send_message` to continue the same',
+    '  conversation (only the agent that started the child may continue it), `interrupt_agent` to',
+    '  stop its current turn.',
+    '- A foreground wait may be user-promoted (Ctrl+B) to background while it runs: if a tool result',
+    '  carries `status: \'async_launched\'` with `backgroundedByUser: true`, treat it exactly like a',
+    '  background launch — the result arrives as a later wake; do not poll.',
+    '- `subagent_type: "fork"` cannot run in the background (upstream harness issue #2124); use a',
+    '  plain background spawn instead.',
+    '- Exiting your session drains a background child\'s in-flight turn; its persisted session',
+    '  survives and cold-resumes on the next `send_message`.',
+].join('\n');
+/**
+ * Register the static background-loop system-prompt section (same contract the
+ * Task tool description teaches, stated once so it survives description
+ * trimming). No-op when the system-prompt seam is absent.
+ * @param ctx - the plug context.
+ * @returns the section disposer, or undefined when the seam is absent.
+ */
+export function mountBackgroundSection(ctx) {
+    const seam = ctx.get('systemPrompt');
+    if (seam === undefined)
+        return undefined;
+    return seam.section({
+        name: BACKGROUND_SECTION_NAME,
+        order: BACKGROUND_SECTION_ORDER,
+        text: BACKGROUND_SECTION_TEXT,
+    });
+}
+/**
+ * Mount the Task tool, the agents catalog, and the workspace-instruction
+ * strip. Safe when either the tools or the system-prompt seam is absent
+ * (the corresponding mount skips); the pre-step listener only needs
+ * `ctx.on`, so it mounts regardless.
+ * @param ctx - the plug context.
+ * @param config - plugin configuration; omitted `resumePins` still arms capture
+ * when the resume-pins plugin's `resumePinStore` service is mounted (plan
+ * §4.10); with neither, capture is disabled.
+ */
+export function apply(ctx, config = {}) {
+    const registry = new AgentRegistry();
+    const pins = config.resumePins;
+    // Durability ordering (plan §4.6): when the resume-pins plugin is mounted
+    // its `resumePinStore` is THE store — gate, overlay, and capture must share
+    // one cache. Capture only falls back to its own config store/pinsRoot when
+    // no plugin-provided store exists (keeps the standalone config path working).
+    const sharedStore = ctx.get('resumePinStore');
+    // Production wiring (plan §4.10): the preset mounts the resume-pins plugin
+    // ahead of this row, so its service store arms capture with NO extra Task
+    // config. Explicit `resumePins` config still wins for standalone consumers.
+    const capture = pins === undefined
+        ? sharedStore !== undefined
+            ? new SpawnPinCapture(ctx, sharedStore)
+            : undefined
+        : new SpawnPinCapture(ctx, sharedStore ?? pins.store ?? new PinStore(pins.pinsRoot));
+    registerTaskTool(ctx, registry, capture);
+    mountAgentCatalog(ctx, registry);
+    mountBackgroundSection(ctx);
+    mountStripWorkspaceInstructions(ctx);
+    mountSettledNoticeSuppression(ctx);
+    publishCollectorRegistry(ctx);
+}
+/**
+ * Publish the Slice 3 promotion registry (collector doc §6) as the ROOT-realm
+ * `ccCollectorRegistry` service so the TUI busy-branch — a host-plane sibling
+ * that cannot resolve realm-interior mounts — queries the SAME live
+ * registration map the Task tool's collect path populates. Mirrors the
+ * command-agents `ccAgents` publication (CcPlugins pattern): first
+ * publication provides the name; a reclaim after an unload takes the slot
+ * back via `set`; the unload effect clears it so the TUI degrades to
+ * "nothing promotable" instead of holding a dead registry.
+ * @param ctx - the plug context.
+ */
+function publishCollectorRegistry(ctx) {
+    const root = ctx.root;
+    const registryService = {
+        collectorFor,
+        collectorsForSession,
+        registeredCollectorCount,
+    };
+    if (root.get('ccCollectorRegistry', false) === undefined) {
+        root.provide('ccCollectorRegistry', registryService);
+    }
+    else {
+        root.set('ccCollectorRegistry', registryService);
+    }
+    ctx.effect(() => () => {
+        if (root.get('ccCollectorRegistry', false) === registryService)
+            root.set('ccCollectorRegistry', undefined);
+    }, 'cc-subagent-task: clear host-realm ccCollectorRegistry publication on unload');
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/lib/preload-tools.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Spawn-time pre-activation of allow-listed deferred MCP tools for a Task
+ * child. A definition frontmatter naming an explicit deferred MCP tool
+ * (`mcp__<server>__<tool>`) leaves the child with a reserved-but-unregistered
+ * name; this module activates each such name through the duck-typed
+ * `ctx.toolSearch` seam BEFORE the child starts, so the tool is registered —
+ * process-globally — by the time the child's first tool assembly runs.
+ *
+ * Duck-typed so `src/` never imports `@dsh-cc/tool-search` — the
+ * package is a test-only devDependency; production stays pluggable (mirrors
+ * `packages/mcp/mcp-client/src/defer.ts`).
+ *
+ * @module @dsh-cc/subagent-task/preload-tools
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ToolRestriction } from '@dsh-cc/claude-code-agents';
+/** The structural subset of the `ctx.toolSearch` seam this module needs. */
+export interface ToolSearchActivateSeam {
+    activate(name: string, scope?: unknown): {
+        status: 'loaded' | 'already-loaded' | 'denied' | 'unknown';
+        name: string;
+        reason?: string;
+    };
+}
+/** A structural view of the tools registry used to skip registered names. */
+interface ToolsView {
+    get(name: string): unknown;
+}
+/** The outcome of one preload pass: what loaded and what did not (with why). */
+export interface PreloadSummary {
+    preloaded: string[];
+    notices: string[];
+}
+/**
+ * Pre-activate the explicit deferred MCP names a definition's `tools:` allows.
+ *
+ * Selection rule: iterate the RAW allow entries. An entry is a candidate iff
+ * it is an explicit exact name (not a wildcard form) that survived into the
+ * SANITIZED allow list, is not excluded by the sanitized deny list, and is not
+ * already registered (a registered name is eager — activation is pointless).
+ * Each candidate is activated for the CALLING agent scope; `loaded` and
+ * `already-loaded` are silent successes, `denied`/`unknown` collect a notice
+ * and warn. No-op when there is no raw allow list, no calling agent, no
+ * sanitized allow list, or (single warn) no toolSearch seam.
+ */
+export declare function preloadDeferredFilterTools(opts: {
+    /** The definition's RAW toolRestriction (undefined → no-op). */
+    raw?: ToolRestriction | undefined;
+    /** The SANITIZED toolFilter the child will actually receive. */
+    sanitized?: ToolRestriction | undefined;
+    /** The duck-typed `ctx.toolSearch` seam (undefined → single warn + no-op). */
+    toolSearch?: ToolSearchActivateSeam | undefined;
+    /** The calling agent (`exec.agent`, undefined → no-op). */
+    agent?: Agent | undefined;
+    /** The duck-typed tools view (`ctx.tools`) used to skip registered names. */
+    tools?: ToolsView | undefined;
+    /** The warn sink (the context logger). */
+    warn: (message: string) => void;
+}): PreloadSummary;
+/**
+ * Render the preload summary as the Task result-text lines. Empty string when
+ * nothing happened (nothing preloaded and no notices).
+ */
+export declare function renderPreloadLines(summary: PreloadSummary): string;
+export {};
+//# sourceMappingURL=preload-tools.d.ts.map

package/lib/preload-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preload-tools.d.ts","sourceRoot":"","sources":["../src/preload-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAKjE,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG;QACvC,MAAM,EAAE,QAAQ,GAAG,gBAAgB,GAAG,QAAQ,GAAG,SAAS,CAAA;QAC1D,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB,CAAA;CACF;AAED,6EAA6E;AAC7E,UAAU,SAAS;IACjB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAC3B;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAcD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,gEAAgE;IAChE,GAAG,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACjC,gEAAgE;IAChE,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACvC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAA;IAC/C,2DAA2D;IAC3D,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;IACzB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC7B,0CAA0C;IAC1C,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC,GAAG,cAAc,CAuCjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CASlE"}

package/lib/preload-tools.js

@@ -0,0 +1,101 @@
+/**
+ * Spawn-time pre-activation of allow-listed deferred MCP tools for a Task
+ * child. A definition frontmatter naming an explicit deferred MCP tool
+ * (`mcp__<server>__<tool>`) leaves the child with a reserved-but-unregistered
+ * name; this module activates each such name through the duck-typed
+ * `ctx.toolSearch` seam BEFORE the child starts, so the tool is registered —
+ * process-globally — by the time the child's first tool assembly runs.
+ *
+ * Duck-typed so `src/` never imports `@dsh-cc/tool-search` — the
+ * package is a test-only devDependency; production stays pluggable (mirrors
+ * `packages/mcp/mcp-client/src/defer.ts`).
+ *
+ * @module @dsh-cc/subagent-task/preload-tools
+ */
+/** The MCP public-name prefix every bridged MCP tool carries on `ctx.tools`. */
+const MCP_PUBLIC_PREFIX = 'mcp__';
+/**
+ * Decide whether a RAW allow entry is a wildcard form (`mcp__<server>` bare,
+ * `mcp__<anything>__*` postfix, or the bare `mcp__`). Wildcards are
+ * restrict-only: their expansions are preloaded by name, never via this
+ * module (the expansion set is the sanitize step's business).
+ */
+function isWildcardEntry(name) {
+    if (!name.startsWith(MCP_PUBLIC_PREFIX))
+        return false;
+    const rest = name.slice(MCP_PUBLIC_PREFIX.length);
+    return rest.length === 0 || rest.endsWith('__*') || !rest.includes('__');
+}
+/**
+ * Pre-activate the explicit deferred MCP names a definition's `tools:` allows.
+ *
+ * Selection rule: iterate the RAW allow entries. An entry is a candidate iff
+ * it is an explicit exact name (not a wildcard form) that survived into the
+ * SANITIZED allow list, is not excluded by the sanitized deny list, and is not
+ * already registered (a registered name is eager — activation is pointless).
+ * Each candidate is activated for the CALLING agent scope; `loaded` and
+ * `already-loaded` are silent successes, `denied`/`unknown` collect a notice
+ * and warn. No-op when there is no raw allow list, no calling agent, no
+ * sanitized allow list, or (single warn) no toolSearch seam.
+ */
+export function preloadDeferredFilterTools(opts) {
+    const { raw, sanitized, toolSearch, agent, tools, warn } = opts;
+    if (raw?.allow === undefined || raw.allow.length === 0)
+        return { preloaded: [], notices: [] };
+    if (agent === undefined)
+        return { preloaded: [], notices: [] };
+    if (toolSearch === undefined) {
+        warn('cc-task: no toolSearch service is mounted, so deferred MCP tools named explicitly in a '
+            + 'subagent toolFilter cannot be pre-activated at spawn; they stay searchable-only');
+        return { preloaded: [], notices: [] };
+    }
+    const sanitizedAllow = sanitized?.allow;
+    if (sanitizedAllow === undefined)
+        return { preloaded: [], notices: [] };
+    const sanitizedDeny = sanitized?.deny;
+    const preloaded = [];
+    const notices = [];
+    for (const name of raw.allow) {
+        // Deferred tools live on the toolSearch registry, which in this
+        // composition only ever holds MCP tools; a non-MCP harness name (read,
+        // bash, reserved rows) can never be a deferred entry, and probing it
+        // would only farm spurious "unknown" notices.
+        if (!name.startsWith(MCP_PUBLIC_PREFIX))
+            continue;
+        if (isWildcardEntry(name))
+            continue;
+        if (!sanitizedAllow.includes(name))
+            continue;
+        if (sanitizedDeny !== undefined && sanitizedDeny.includes(name))
+            continue;
+        if (tools !== undefined && tools.get(name) !== undefined)
+            continue;
+        const outcome = toolSearch.activate(name, agent);
+        if (outcome.status === 'loaded' || outcome.status === 'already-loaded') {
+            preloaded.push(name);
+            continue;
+        }
+        const reason = outcome.status === 'unknown'
+            ? 'unknown to the toolSearch registry'
+            : outcome.reason?.replace(/^"[^"]*" is /, '');
+        const notice = reason !== undefined ? `${name} (${reason})` : `${name}`;
+        notices.push(notice);
+        warn(`cc-task: could not pre-activate deferred tool "${name}" for a subagent: ${notice}`);
+    }
+    return { preloaded, notices };
+}
+/**
+ * Render the preload summary as the Task result-text lines. Empty string when
+ * nothing happened (nothing preloaded and no notices).
+ */
+export function renderPreloadLines(summary) {
+    const lines = [];
+    if (summary.preloaded.length > 0) {
+        lines.push(`Preloaded deferred tools for child: ${summary.preloaded.join(', ')}`);
+    }
+    if (summary.notices.length > 0) {
+        lines.push(`Not preloaded: ${summary.notices.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=preload-tools.js.map

package/lib/preload-tools.js.map

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