@sema-ai/core 1.275.1

package/dist/agents/subagent.d.ts

@@ -0,0 +1,441 @@
+import { Type } from "typebox";
+import type { Runner } from "../core/runner/runtask.js";
+import type { AgentDefinition, Model, ModelRef, TaskSpec, ToolSpec } from "../core/types.js";
+import { type ExecutionEnv } from "../internal/harness.js";
+import type { RunInternals } from "../core/runner/prepare-task.js";
+import type { TaskNotificationPayload } from "../core/task-notification.js";
+export type { SubagentStep, SubagentEditedFile } from "./subagent-steps.js";
+/**
+ * 🔴 design/77 §3 / §7 — skill→subagent manifest-scope PROPAGATION (fail-closed). Given the parent task's
+ * live skill-manifest snapshot (from `ctx.activeSkillScope()`), build the inherited-scope frames to thread
+ * into a spawned child via the trusted {@link RunInternals.inheritedManifestScope} channel, so the child's
+ * tool gate inherits the parent skill's deny-narrowing (a child of a manifested skill is at most as capable
+ * as the manifest — MONOTONIC).
+ *
+ * - Parent has NO active manifest (empty/absent snapshot) → return `undefined` (no inheritance; the child
+ *   behaves exactly as today, backward-compatible).
+ * - Parent HAS active manifest frames → return them verbatim (the child seeds them as the LIFO base; its
+ *   own skill loads can only intersect/narrow further).
+ * - Fail-closed: the snapshot is non-empty but its shape is not a recognizable frame array (a future/older
+ *   Runner, a tampered accessor) → return a SINGLE DENY-ALL `unresolved` frame, so the child runs under a
+ *   deny-all inherited scope rather than UNMANIFESTED. The safe path is the default.
+ */
+export declare function inheritedManifestScopeFor(snapshot: readonly unknown[] | undefined): RunInternals["inheritedManifestScope"];
+/** Default model-facing name of the delegation tool (CC 2.1.187 `Agent`; legacy alias `Task`). */
+export declare const DEFAULT_SUBAGENT_TOOL_NAME = "Agent";
+export declare const LEGACY_SUBAGENT_TOOL_NAME = "Task";
+/**
+ * CC206-B 欠账 — the Agent completed card's structured `toolStats` (CC 206:541193-541201 `sfd` schema:
+ * seven counters, `.optional()`; counting logic 206:540431-540491 `_my`). CC derives the counts from the
+ * child's transcript (assistant `tool_use` blocks) and FOLDS nested delegations' toolStats in via each
+ * user message's `toolUseResult.toolStats`; sema counts on the shared forward-event sink instead — the
+ * sink re-threads DESCENDANT events too (grandchildren bubble through, see subagent-steps.ts header), so
+ * the cumulative semantics match without a fold step. Delegation calls themselves are excluded from every
+ * bucket (CC excludes `gi`=Agent and `yU`=Task, 206:540453-540455). `linesAdded`/`linesRemoved` mirror CC
+ * `i3r` (206:399357-399375): LINE COUNTS OF THE EDIT ARGUMENTS (new/old_string, Write content, NotebookEdit
+ * new_source) — not a real diff; honest to CC's own approximation.
+ */
+export interface SubagentToolStats {
+    readCount: number;
+    searchCount: number;
+    bashCount: number;
+    editFileCount: number;
+    linesAdded: number;
+    linesRemoved: number;
+    otherToolCount: number;
+}
+/**
+ * design/135 §0 (Fork 收编) — the BUILT-IN `subagent_type` value that routes an `Agent` call to the fork
+ * execution path (CC-exact abstraction shape: fork lives in `Agent.subagent_type`'s value domain, not in a
+ * separate tool). Always present in the `subagent_type` enum — with or without `spec.agents` — UNLESS the
+ * deployment defines its own agent named "fork" (the definition wins; noted in the tool description).
+ */
+export declare const FORK_SUBAGENT_TYPE = "fork";
+/**
+ * F8 (CC 2.1.198 parity — 锚 pretty.js:225062-225073, fork definition `U3`: `maxTurns: 200,
+ * permissionMode: "bubble"`; byte-stable through 204/206 per CC-DRIFT-198-206-AGENT-TYPES 锚10): the
+ * fork arm's DEFAULT turn cap. sema's global `DEFAULT_MAX_TURNS` is 500 (1.261.0) and stays — this pin
+ * applies ONLY when `subagent_type: "fork"` runs without an explicit `limits.maxTurns` on the delegation
+ * tool (a deployment-configured `limits.maxTurns` still wins, like every other lane).
+ */
+export declare const FORK_DEFAULT_MAX_TURNS = 200;
+/**
+ * design/136 §6 盲点① (1.256) + §2.1.a (BREAKING batch) — the fork-GOVERNANCE predicate for the
+ * `Agent(subagent_type:"fork")` route (the ONLY fork face since the standalone `Fork` tool was retired,
+ * design/136 §2.1: the capability moved wholesale into `Agent.subagent_type`'s value domain — CC-exact shape).
+ *
+ * `TaskSpec.enableFork` is opt-OUT (design/136 §2.1.a default flip, matching CC — fork is available by
+ * default, bounded only by the durable session capability): only an EXPLICIT `enableFork:false` denies
+ * (`denied:"task"`); `runtimeCaps.allowFork:false` denies per-principal (`denied:"principal"` —
+ * tighten-only, mirrors allowWorkflows). Undefined on both axes ⇒ governance does not object; the
+ * capability three-checks in the execute path (insideFork / sessionId / hasSessionFork) still apply.
+ *
+ * prepare-task computes this once per run and threads it to the Agent tool as `ctx.forkAccess`
+ * (Runner-held, never a model argument). A denial is HONEST (`fork.disabled` result), never a silent
+ * downgrade to a clean delegation. A directly-constructed `createSubagentTool` outside a Runner has no
+ * `ctx.forkAccess` ⇒ capability checks only.
+ */
+export declare function forkGovernanceDenial(enableFork: boolean | undefined, allowFork: boolean | undefined): "task" | "principal" | undefined;
+/**
+ * design/135 — the trusted per-call worktree-isolation lane for the Agent tool (CC `isolation: "worktree"`).
+ * `mint` creates a detached git worktree under the task root via {@link addWorktree} (throws when the root is
+ * not a git repository — the caller surfaces the honest error text); `finish` implements CC's "auto-cleaned
+ * if unchanged": the worktree is removed when the child left `git status` clean, and KEPT (returning "kept")
+ * when the child made changes, so the parent can inspect/merge before removing it. Runner-filled onto
+ * {@link import("../core/types.js").ToolExecuteContext.worktreeIsolation}; never a model argument.
+ */
+export interface SubagentWorktreeIsolation {
+    /** Create a detached worktree for a child. Throws when the base root is not a git repository. */
+    mint(childId: string): Promise<{
+        worktreeDir: string;
+    }>;
+    /** CC "auto-cleaned if unchanged": remove the worktree when clean, keep it when the child made changes. */
+    finish(worktreeDir: string): Promise<"pruned" | "kept">;
+}
+/**
+ * Build the {@link SubagentWorktreeIsolation} helper over a base env + repo root. Called by `prepare-task`
+ * (closure over the run's ExecutionEnv/taskRootPath — trusted, mirrors the scheduler/fork mounts). The
+ * worktree-rooted env handed to {@link addWorktree} is a thin prototype view over the base env with `destroy`
+ * MASKED (an own `destroy: undefined`), so tearing the worktree down can never cascade into destroying the
+ * parent's own (possibly factory-owned) env.
+ */
+export declare function createSubagentWorktreeHelper(baseEnv: ExecutionEnv, repoRoot: string): SubagentWorktreeIsolation;
+/** design/129: the hard lifetime ceiling forced onto a SESSION-scoped background child when the spec gave no
+ *  `limits.timeoutSec` — bounds a child that outlives its turn even absent a deployment session-release reap. */
+export declare const SESSION_BG_DEFAULT_TIMEOUT_SEC: number;
+/** CC 2.1.201 parity — the machine-readable failure class stamped on a FAILED sub-agent report. */
+export type SubagentErrorKind = "rate_limit" | "overloaded" | "timeout" | "network" | "logic";
+/**
+ * CC 2.1.201 parity (追平批 α 项5) — classify a FAILED child run into a coarse `error_kind` +
+ * `retryable` pair so the PARENT model (and an orchestrating deployment) can react correctly without
+ * string-matching the report: a `rate_limit`/`overloaded`/`timeout`/`network` failure is transient
+ * (re-delegating the same subtask may succeed); a `logic` failure is not (auth/invalid_request/budget/
+ * output.* — re-delegating unchanged just burns tokens). Derived from the EXISTING taxonomy: the
+ * child's `TaskResult.errorCode` (assemble-result's priority chain — brain `[code]` prefixes lifted
+ * via `extractErrorCode`, `limit.timeout`, `budget.*`, …) plus a message sniff for the two classes our
+ * BrainError codes fold together ("server" covers overloaded_error/529 AND plain 5xx; "network"
+ * covers both timeouts and resets). Returns undefined for a non-failed child (no error to classify).
+ */
+export declare function classifySubagentError(child: {
+    status: string;
+    errorCode?: string;
+    errorMessage?: string;
+}): {
+    errorKind: SubagentErrorKind;
+    retryable: boolean;
+} | undefined;
+/**
+ * Blackboard 2026-07-03 (subagent steer verb) — the handle emitted to `RunInternals.onSubagentSpawn`
+ * when a deployment opts into steerable sub-agents. Mirrors {@link WorkflowAgentHandle}: `steer`
+ * injects fenced operator guidance into the RUNNING child and returns a correlation marker; it
+ * rejects with `steering.not_running` once the child ends. The handle never reaches the model.
+ */
+export interface SubagentSteerHandle {
+    /** The child run's unified task id (`spec.taskId ?? sessionId` fallback resolves post-start, so this
+     *  is the SPAWN-time identity: the parent's tool call id — stable, unique per delegation). */
+    parentToolCallId: string;
+    /** The child's display name (taskName / agent-type), when one was threaded. */
+    agentName?: string;
+    /** Inject fenced operator guidance into the running child; resolves to the correlation marker. */
+    steer: (content: string) => Promise<string>;
+    /** Resolves when the child settles (the tool's own await — exposed so a registry can auto-evict). */
+    settled: Promise<void>;
+    /**
+     * design/122 D1 — the retained child session id; present ONLY when the parent run enabled
+     * {@link import("../core/types.js").TaskSpec.retainSubagentSessions} AND this child was actually
+     * retained. ⚠️ Control-plane only (codex-B6): this is a continuation CAPABILITY — never expose it to
+     * clients; target children by the opaque `parentToolCallId` instead (codex-m3).
+     */
+    childSessionId?: string;
+    /**
+     * design/122 D2 — REVIVE the settled child with a new operator prompt (CC `dfe` resumeAgentBackground
+     * parity): the SAME session gains a fenced follow-up user turn and the child continues in the
+     * background from its full prior context. ALWAYS ASYNC (even when the original spawn was a synchronous
+     * delegation) — the caller is the operator/shell, not the parent model; the parent run's state is
+     * untouched and completion is announced ONLY through the deployment-level background-notify sink
+     * (never the parent-model `ctx.onTaskNotification` lane — r1-M5). Resolves to the correlation marker
+     * (same contract as {@link steer}). Rejections carry an `Error.code`: `steering.still_running` (the
+     * child — or a prior resume — is still in flight), `resume.retain_off` (the parent run did not retain
+     * this child), `resume.evicted` (TTL/max/parent-end evicted the retained session), `resume.cap`
+     * (per-child resume cap reached), `resume.session_not_found` (the session vanished from the store, or
+     * is empty — the r1-m1 create-on-miss dark door). `handle.settled` keeps FIRST-RUN semantics (D4
+     * ruling); each resume re-emits a FRESH handle (same `parentToolCallId`) to the spawn sink, whose own
+     * `settled` tracks the revived run — a registry keeps the newest handle per id.
+     */
+    resume?: (content: string) => Promise<string>;
+}
+/** design/122 D2 — per-child resume cap (default 8): a child can be revived at most this many times. */
+export declare const SUBAGENT_RESUME_CAP = 8;
+/**
+ * design/122 D1 — one RETAINED child ledger row. `specSnapshot` is a FROZEN plain value-copy of the spawn
+ * childSpec (r1-m5: retaining the live `ctx`/spec-builder closures would pin the parent run's whole prepare
+ * graph — harness ref, tool wrappers — in memory for up to ttl×max); `internalsSnapshot` is the spawn-time
+ * trusted internals copy (parentToolCallId / onForwardEvent / onSubagentSpawn — the grandchild chain stays
+ * unbroken on resume, D2). `release` captures the DELEGATION runner (deployment-scoped, allowed) and
+ * performs the unpin + explicit release that restores throwaway semantics.
+ */
+export interface SubagentRetainEntry {
+    childSessionId: string;
+    agentName?: string;
+    specSnapshot: Readonly<TaskSpec>;
+    internalsSnapshot: RunInternals;
+    /** True while the initial run OR a resume run is in flight (resume re-entry rejects `steering.still_running`). */
+    running: boolean;
+    /** True once the initial run settled at least once. */
+    settled: boolean;
+    /** Last settle timestamp (epoch ms) — the retain-TTL base. */
+    settledAt: number;
+    resumeCount: number;
+    /** The in-flight resume run's abort controller (parent-terminal cleanup aborts it — r1-M2). */
+    activeAbort?: AbortController;
+    /** Unpin + explicitly release the retained session (best-effort; the TTL reaper is the backstop). */
+    release: () => Promise<void>;
+}
+/**
+ * design/122 D1 — the parent-run-scoped RETAIN ledger (`TaskSpec.retainSubagentSessions`). Created by
+ * `prepareTask` when the spec opts in, threaded to delegation tools as the TRUSTED `ctx.subagentRetain`,
+ * and disposed by the Runner in the task's terminal `finally` (D4: abort in-flight resumes + unpin +
+ * release every retained session — retain is NOT durable; resume is reachable only while the parent run
+ * lives, codex-B3). Leaks are double-bounded by `max` + `ttlMs` (codex-B2).
+ */
+export declare class SubagentRetainLedger {
+    readonly ttlMs: number;
+    readonly max: number;
+    private entries;
+    /** Tombstones: ids that WERE (or would have been) retained but got evicted — their resume rejects `resume.evicted`. */
+    private evictedIds;
+    private isDisposed;
+    constructor(config: true | {
+        ttlMs?: number;
+        max?: number;
+    });
+    get disposed(): boolean;
+    get size(): number;
+    get(parentToolCallId: string): SubagentRetainEntry | undefined;
+    wasEvicted(parentToolCallId: string): boolean;
+    /** codex impl-review MAJOR-1 — LAZY TTL sweep (no timer): evict every settled idle entry whose retain
+     *  TTL elapsed (unpin + release + tombstone), so an expired session is freed at the NEXT ledger touch
+     *  (every spawn-registration and resume entry call this) rather than only when its own resume is tried.
+     *  The parent-terminal `disposeAll` stays the backstop. `evict` removes the row + tombstones
+     *  synchronously; the release itself is fire-and-forget best-effort. */
+    sweepExpired(now?: number): void;
+    /** Register a child at SPAWN (running until `markSettled`). Over `max`: the oldest settled idle entry is
+     *  evicted (unpin+release); when every slot is still running, the NEW child is NOT retained (tombstoned →
+     *  its resume rejects `resume.evicted`) and `undefined` is returned — the caller falls back to throwaway. */
+    register(parentToolCallId: string, entry: Omit<SubagentRetainEntry, "running" | "settled" | "settledAt" | "resumeCount" | "activeAbort">): SubagentRetainEntry | undefined;
+    /** Flip a child to settled (idle, resumable) — called when the initial run's stream drains. */
+    markSettled(parentToolCallId: string): void;
+    /** Drop a row WITHOUT releasing (durable-pause posture: a committed checkpoint owns the session/pin —
+     *  releasing here would orphan it, mirroring the delegation tool's own no-release guard). */
+    abandon(parentToolCallId: string): void;
+    /** Evict one row: abort its in-flight resume (if any), unpin + release the session, tombstone the id. */
+    evict(parentToolCallId: string): Promise<void>;
+    /** design/122 D4 — parent-run terminal cleanup: abort EVERY in-flight resume + unpin + release EVERY
+     *  retained session (throwaway semantics restored; no orphan run burns tokens — same posture as
+     *  `abortBackgroundAgentsForOwner`). Idempotent; further register/resume attempts are refused. */
+    disposeAll(): Promise<void>;
+}
+/** Look up (never create) the session-scoped retain ledger for `sessionId` — SendMessage's read side. */
+export declare function getSessionRetainLedger(sessionId: string): SubagentRetainLedger | undefined;
+/** Anchor ② — dispose the session's retain ledger (abort in-flight resumes, unpin + release every retained
+ *  child session) and drop it. Idempotent; wired to `TaskRegistry.onSessionReap` at retain time. */
+export declare function releaseSessionRetainLedger(sessionId: string): Promise<void>;
+/**
+ * design/122 D2 — the SINGLE resume-prompt builder: a constant TRUSTED frame core owns (operator authority +
+ * an unpredictable correlation marker) around the operator content, which stays fenced DATA (same posture as
+ * steer — content is never authority, and `delimitUntrusted` neutralizes fence/tag break-out sentinels).
+ */
+export declare function makeResumePrompt(marker: string, content: string): string;
+export interface SubagentToolOptions {
+    /** Runner used to execute child tasks. */
+    runner: Runner;
+    /**
+     * design/115 P3 — background sub-agents (CC `run_in_background`). When set, the tool exposes the
+     * `run_in_background` parameter: the call returns an `a*` task_id immediately, the child runs
+     * asynchronously, and completion fires ONE task-notification ("later" priority — CC posture: an agent
+     * completion doesn't derail active work). Poll/stop via TaskOutput/TaskStop. Absent ⇒ synchronous only.
+     */
+    background?: {
+        registry: import("../core/task-registry.js").TaskRegistry;
+        owner?: string;
+        scope?: string;
+        notify?: (n: import("../core/task-notification.js").TaskNotificationPayload, opts?: {
+            priority?: "now" | "next" | "later";
+        }) => void;
+    };
+    /** Model the child runs on. If omitted, the child resolves the `subagent` role (→ `default`). */
+    model?: ModelRef;
+    /**
+     * Declarative sub-agents the model can pick from (design/38 1B). When set, the tool exposes an `agent`
+     * parameter (enum of these names) and the chosen definition's config builds the child task — its
+     * `allowTools`/`denyTools` REPLACE the tool-level ones, `model` omitted = inherit the caller's model.
+     * design/141 件A: when OMITTED, defaults to the runner's deployment catalog (`RunnerDeps.agents`) —
+     * one Runner, one registry across the Agent-tool and workflow lanes. Pass explicitly to narrow.
+     */
+    agents?: AgentDefinition[];
+    /**
+     * F1 (CC 2.1.198 parity): offer the BUILT-IN read-only `Explore`/`Plan` agent types (CC `HCe`
+     * registry, GA default-on — pretty.js:487221-487240 + iAt :487127). Default `true` (CC posture);
+     * `false` removes them (the config-driven analog of CC's `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`).
+     * A deployment definition named "Explore"/"Plan" SHADOWS the built-in of the same name (definition
+     * wins — fork-shadowing precedent).
+     */
+    builtinAgents?: boolean;
+    /** Model catalog, used ONLY to validate an agent's string `model` ref at assembly time (fail-fast). */
+    models?: Record<string, Model>;
+    /** Tools available to the child (a deliberately narrowed subset). */
+    tools?: ToolSpec[];
+    /**
+     * Tool-level allowlist (design/38 1A), used when NO `agent` is selected (a selected agent definition's
+     * own `allowTools`/`denyTools` REPLACE these). When set, the child sees only these tools from `tools`
+     * (`["*"]` = all). Omit for the whole `tools` pool. Allowlist is the security-recommended shape.
+     * NOTE: this filters only the WORK tools — the nested delegation tool is governed by `maxDepth`, not
+     * allow/deny. To deny the child any further delegation, set `maxDepth: 1` (not a `denyTools` entry).
+     */
+    allowTools?: string[];
+    /** Tool-level denylist (design/38 1A), used when no `agent` is selected: names removed (a deny wins). */
+    denyTools?: string[];
+    /** System prompt / persona for the child. Default (1.259.0, CC 198 parity): the LEAN
+     *  {@link SUBAGENT_PROMPT} (agent persona + return contract), NOT the full default constitution role
+     *  base — pass `DEFAULT_SYSTEM_PROMPT` here explicitly to restore the pre-1.259 behavior. */
+    systemPrompt?: string;
+    /** Tool name exposed to the parent. Default "Agent". */
+    name?: string;
+    /** What the child is for (shown to the parent in the tool description). */
+    purpose?: string;
+    /** Child run limits. */
+    limits?: {
+        maxTurns?: number;
+        timeoutSec?: number;
+    };
+    /**
+     * Max nesting depth of delegation. A child at depth `d` only receives a delegation tool when
+     * `d + 1 < maxDepth`, so it cannot recurse past the limit. Default 5 — CC 2.1.201 parity (CC `Y4t`:
+     * 5 sub-agent levels below the main agent). Semantics pin (off-by-one checked): with the default,
+     * the main agent + children at depths 1-4 all carry a delegation tool, the depth-5 child is the
+     * STRUCTURAL leaf (no delegation tool mounted — sema's structural de-tooling, not a runtime throw),
+     * so "default behavior = CC default behavior": 5 delegation levels under main are reachable and a
+     * 6th is impossible by construction.
+     */
+    maxDepth?: number;
+}
+/**
+ * A system-prompt note you can append to the PARENT task so the model knows delegation exists.
+ * (The tool description below is the primary "explicit instruction"; this is an optional reinforcement.)
+ */
+export declare const SUBAGENT_SYSTEM_NOTE: string;
+/**
+ * G4 (CC 2.1.198 parity — 锚 pretty.js:225024 `Z4t` fork-boilerplate): the MESSAGE-LAYER instruction
+ * frame prepended to a fork child's directive. 198 keeps the fork's SYSTEM prompt byte-identical to the
+ * parent (prompt-cache) and carries the fork behavior contract in the messages instead — same posture
+ * here: this frame wraps the `prompt` (the child's objective/user turn) and never touches systemPrompt.
+ * 198-faithful verbatim (2026-07-10 realignment): the no-spawn line is now the full 198 text — the tool
+ * name matches (198 `is`="Agent" = our DEFAULT_SUBAGENT_TOOL_NAME) and our tool card carries its own
+ * fork guidance (:939) for the referent. An earlier adaptation dropped the "default to forking" clause
+ * as CC-specific; a live identity-confusion incident (a fork reading the parent's delegation record as
+ * "someone else is on it" and stopping) showed the parent/fork disambiguation clause is load-bearing —
+ * keep the anchor whole. (NOT the 88-era frame — 88's "STOP. READ THIS
+ * FIRST… Scope:/Result/Key files" format was rewritten shorter and softer in 198; parity follows 198.)
+ * Frame TAIL = the literal directive prefix `Your directive: ` (198 `ZDt`, pretty.js:35621; the Z4t
+ * assembly is `…</fork-boilerplate>\n\n${ZDt}${directive}`, :225038, and 198 strips the SAME prefix on
+ * read-back, :415673). 1.259.0 合车复审修①: an earlier transcription invented a `<directive-prefix>`
+ * tag here — that tag does not exist in 198; the anchor is the plain-text prefix.
+ */
+export declare const FORK_DIRECTIVE_FRAME = "<fork-boilerplate>\nYou are a worker fork. The transcript above is the parent's history \u2014 inherited reference, not your situation. You are NOT a continuation of that agent. Execute ONE directive, then stop.\n\nHard rules:\n- Do NOT spawn subagents with the Agent tool. The \"default to forking\" guidance is for the parent; you ARE the fork, execute directly.\n- One shot: report once and stop. No follow-up questions, no proposed next steps, no waiting for the user.\n\nGuidelines (your directive may override any of these):\n- Stay in scope. Other forks may be handling adjacent work; if you spot something outside your directive, note it in a sentence and move on.\n- Open with one line restating your task, so the parent can spot scope drift at a glance.\n- Be concise \u2014 as short as the answer allows, no shorter. Plain text, no preamble, no meta-commentary.\n- If you committed changes, list the paths and commit hashes in your report.\n</fork-boilerplate>\n\nYour directive: ";
+/**
+ * Build a tool that lets a parent task delegate a subtask to an **isolated** sub-agent run.
+ *
+ * The child runs synchronously in a fresh session (isolated context) with a narrowed tool set and
+ * its own model, and returns a structured, machine-readable handoff (status / result / blockedReason / stats).
+ */
+export declare function createSubagentTool(opts: SubagentToolOptions): ToolSpec;
+/**
+ * Render an agent definition's tool boundary for the roster listing line tail — CC `gHm` semantics
+ * (pretty.js:453014-453027): explicit allowlist ⇒ the list (minus denies; empty ⇒ "None"); only denies ⇒
+ * "All tools except …"; neither ⇒ "All tools". sema delta: `allowTools: ["*"]` is the documented
+ * allow-everything sentinel (AgentDefinition.allowTools) — treated as NO allowlist, not a literal list.
+ */
+export declare function agentToolsNote(def: {
+    allowTools?: string[];
+    denyTools?: string[];
+}): string;
+/**
+ * F4 (CC 2.1.198 `tIl` selection half — 锚 pretty.js:453029 `(t && e.whenToUseLean) || e.whenToUse`,
+ * `t = yg(mainLoopModel)` :479504): pick the roster guidance text for one agent definition. CC keys
+ * `lean` on its simple-system-prompt model predicate; sema runs the CC lean-prompt arm wholesale
+ * (provider-neutral engine, web.ts lean-card precedent), so every call site passes the default
+ * `lean = true` — a definition WITH `whenToUseLean` shows the lean text (exactly what modern CC main
+ * models see), one without is unchanged. Empty-string lean falls back like CC (`||`, not `??`).
+ */
+export declare function agentWhenToUseText(def: {
+    whenToUse?: string;
+    whenToUseLean?: string;
+}, lean?: boolean): string | undefined;
+/** Model-facing name of the background-agent continuation tool (CC 2.1.2xx `SendMessage`). */
+export declare const SEND_MESSAGE_TOOL_NAME = "SendMessage";
+export interface SendMessageToolOptions {
+    /** Runner used to execute the resumed child run (the design/122 resume face's delegation runner). */
+    runner: Runner;
+    /** The unified task registry the background Agent lane registered its a* handles in. */
+    registry: import("../core/task-registry.js").TaskRegistry;
+    /** design/122 D1 — the parent run's retain ledger (present only when `TaskSpec.retainSubagentSessions`
+     *  opted in). Absent ⇒ the tool stays mounted but every call returns the honest not-retained text. */
+    retain?: SubagentRetainLedger;
+    /** Registry access identity (mirrors TaskOutput's closure identity — the mount fills these). */
+    owner?: string;
+    scope?: string;
+    sessionId?: string;
+    /** Deployment-level background-notify sink — the resumed run's completion rides the existing chain. */
+    notify?: (n: TaskNotificationPayload, opts?: {
+        priority?: "now" | "next" | "later";
+    }) => void;
+    /** Steer-handle sink: the revived run re-emits a FRESH handle (design/122 risk-table contract). */
+    sink?: (handle: SubagentSteerHandle) => void;
+}
+/**
+ * 深挖 G3 — build the MODEL-VISIBLE **SendMessage** tool (CC schema `{to, summary, message}`): continue a
+ * previously spawned, already-completed BACKGROUND agent with its context intact, instead of cold-starting
+ * a new one. `to` is the a* task_id the Agent tool returned for `run_in_background: true`; execution goes
+ * through the design/122 resume face (`makeSubagentResume` — frozen spawn snapshot, fenced operator-resume
+ * prompt, cap/TTL/eviction contract), keyed by the spawn's toolUseId recorded on the registry handle.
+ *
+ * Honest-degrade posture (clay 拍: mount-always + honest text, never silent): with retain OFF (the
+ * `retainSubagentSessions` default) the tool is still mounted, and a call returns "session not retained;
+ * relaunch instead" — same for evicted/expired/cap-reached sessions (each maps its resume rejection code
+ * to plain guidance). The resumed child runs as a NEW background run on the SAME session; its completion
+ * is announced through the existing deployment background-notify chain (r1-M5 — never the parent-model
+ * notification lane), correlated by the returned `[resume-…]` marker.
+ */
+export declare function createSendMessageTool(opts: SendMessageToolOptions): import("../core/types.js").AgentTool<Type.TObject<{
+    to: Type.TString;
+    message: Type.TString;
+    summary: Type.TOptional<Type.TString>;
+}>, unknown>;
+/** Model-facing name of the child-transcript read tool (黑板 [558] C). */
+export declare const AGENT_TRANSCRIPT_TOOL_NAME = "AgentTranscript";
+export interface AgentTranscriptToolOptions {
+    /** Runner whose `sessions` store holds the child's persisted history. */
+    runner: Runner;
+    /** The unified registry the background Agent lane registered its a* handles in (scopes reads to lineage). */
+    registry: import("../core/task-registry.js").TaskRegistry;
+    /** Access identity (mirrors SendMessage/TaskOutput — the mount fills these). */
+    owner?: string;
+    scope?: string;
+    sessionId?: string;
+}
+/**
+ * 黑板 [558] C — build the MODEL-VISIBLE **AgentTranscript** tool: read the last N tool steps of a
+ * previously spawned background agent ON DEMAND (a PULL face — it does NOT inflate the parent's context
+ * the way an injected residual would). `id` is the a* task_id the Agent tool returned. This is the
+ * complement to the stop-time residual (which the notification already carries): use it to look deeper
+ * into a child's tail when the residual isn't enough.
+ *
+ * Safety: reads are bounded to the parent's OWN lineage — the same non-leaking registry access scope as
+ * SendMessage/TaskOutput (an unknown or out-of-scope id reads identically to "not found"). Only a
+ * RETAINED child's session survives to be read; a throwaway child returns an honest "not retained".
+ */
+export declare function createAgentTranscriptTool(opts: AgentTranscriptToolOptions): import("../core/types.js").AgentTool<Type.TObject<{
+    id: Type.TString;
+    lastN: Type.TOptional<Type.TInteger>;
+}>, unknown>;
+//# sourceMappingURL=subagent.d.ts.map

package/dist/agents/subagent.d.ts.map

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