@bubblebrain-ai/bubble 0.0.20 → 0.0.22

package/dist/approval/controller.js

@@ -49,7 +49,9 @@ export class PermissionAwareApprovalController {
         if (mode === "default" && (req.type === "edit" || req.type === "write" || req.type === "patch")) {
             return finalize({ action: "approve" });
         }
-        if (mode === "plan") {
+        // Project profile trust is a user decision, not a destructive action:
+        // spawn_agent is legal in plan mode, so the gate prompts there too.
+        if (mode === "plan" && req.type !== "agent_profile") {
             return finalize({
                 action: "reject",
                 feedback: "Plan mode is active. Do not call destructive tools directly — propose your changes via exit_plan_mode and wait for user approval.",
@@ -83,6 +85,8 @@ export class PermissionAwareApprovalController {
                 return { tool: "Edit", path: req.path, cwd: this.options.cwd };
             case "lsp":
                 return { tool: "Lsp", path: req.path, cwd: this.options.cwd };
+            case "agent_profile":
+                return { tool: "AgentProfile" };
         }
     }
     checkRequestRules(req) {
@@ -170,6 +174,8 @@ function approvalTarget(req) {
             return "Edit";
         case "lsp":
             return "Lsp";
+        case "agent_profile":
+            return "AgentProfile";
     }
 }
 function summarizeApprovalRequest(req) {
@@ -184,5 +190,7 @@ function summarizeApprovalRequest(req) {
             return { type: req.type, path: req.path, paths: req.paths, files: req.files, diffLength: req.diff.length };
         case "lsp":
             return { type: req.type, path: req.path, operation: req.operation };
+        case "agent_profile":
+            return { type: req.type, name: req.name, path: req.path, contentHash: req.contentHash };
     }
 }

package/dist/approval/tool-helper.js

@@ -30,5 +30,7 @@ function approvalRequestLabel(req) {
             return `Bash command \`${req.command}\``;
         case "lsp":
             return `LSP ${req.operation} on ${req.path}`;
+        case "agent_profile":
+            return `Project agent profile "${req.name}"`;
     }
 }

package/dist/approval/types.d.ts

@@ -45,7 +45,23 @@ export interface LspApprovalRequest {
     path: string;
     operation: string;
 }
-export type ApprovalRequest = EditApprovalRequest | WriteApprovalRequest | PatchApprovalRequest | BashApprovalRequest | LspApprovalRequest;
+/**
+ * Trust gate for project-local agent profiles (.bubble/agents). The user —
+ * not the model — decides whether a repository's profile prompt may drive a
+ * subagent; approvals are remembered per content hash for the session.
+ */
+export interface AgentProfileApprovalRequest {
+    type: "agent_profile";
+    /** Profile name as referenced by spawn_agent. */
+    name: string;
+    /** Absolute path of the profile file inside the repository. */
+    path: string;
+    /** Content hash; a changed file re-prompts. */
+    contentHash: string;
+    /** First lines of the profile prompt so the user can judge it. */
+    promptPreview: string;
+}
+export type ApprovalRequest = EditApprovalRequest | WriteApprovalRequest | PatchApprovalRequest | BashApprovalRequest | LspApprovalRequest | AgentProfileApprovalRequest;
 export type ApprovalDecision = {
     action: "approve";
     feedback?: string;

package/dist/checkpoints.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Checkpoint store - pre-mutation file snapshots, keyed by conversation turn.
+ *
+ * Before the edit/write tools persist a change, they record the file's prior
+ * content here so /rewind can restore the workspace to the state it had just
+ * before a given user message. Changes made by bash commands are NOT tracked;
+ * checkpoints complement git, they do not replace it.
+ *
+ * On-disk layout (sibling of the session JSONL):
+ *   <session>.checkpoints/
+ *     blobs/<sha256>     full file content, content-addressed (deduplicated)
+ *     manifest.jsonl     one {turn, path, blob, timestamp} line per first
+ *                        capture of a file within a turn
+ *
+ * blob === null means the file did not exist before that turn, so rewinding
+ * deletes it.
+ */
+export interface CheckpointManifestEntry {
+    turn: string;
+    path: string;
+    blob: string | null;
+    timestamp: number;
+}
+export interface CheckpointRestoreResult {
+    /** Files whose pre-turn content was written back. */
+    restored: string[];
+    /** Files deleted because they were created during the rewound turns. */
+    deleted: string[];
+    /** Files that could not be restored (I/O errors). */
+    failed: string[];
+}
+export declare class CheckpointStore {
+    private readonly dir;
+    private readonly currentTurn;
+    private seen?;
+    constructor(dir: string, currentTurn: () => string);
+    /**
+     * Record a file's content before it is mutated. `priorContent` is the
+     * current on-disk content, or null when the file does not exist yet.
+     * Capturing must never break the mutation itself, so all errors are
+     * swallowed.
+     */
+    captureBefore(filePath: string, priorContent: string | null): Promise<void>;
+    listEntries(): CheckpointManifestEntry[];
+    /** Unique files first captured at or after the given turn. */
+    filesTouchedSince(turn: string): string[];
+    /** Unique files captured during exactly the given turn. */
+    filesTouchedAt(turn: string): string[];
+    /**
+     * Restore every tracked file to its content from just before `turn`.
+     * For each file the earliest capture at-or-after the cutoff wins (it holds
+     * the oldest pre-mutation content). Consumed manifest entries are pruned so
+     * a later rewind over reused turn ids cannot resurrect stale state.
+     */
+    restoreTo(turn: string): Promise<CheckpointRestoreResult>;
+    private loadSeen;
+}

package/dist/config.d.ts

@@ -30,6 +30,13 @@ export interface UserConfigData {
     providers?: ProviderProfile[];
     defaultProvider?: string;
     agentCategories?: AgentCategoriesConfig;
+    subagents?: SubagentsUserConfig;
+}
+export interface SubagentsUserConfig {
+    /** Global cap on concurrently running children. Default 8. */
+    maxActiveSubagents?: number;
+    /** Absolute per-child soft token cap. Default 200000. */
+    childTokenCap?: number;
 }
 export declare class UserConfig {
     private data;
@@ -56,6 +63,7 @@ export declare class UserConfig {
     setThemeMode(mode: ThemeMode): void;
     setThemeOverrides(overrides: Record<string, string>): void;
     getAgentCategories(): AgentCategoriesConfig;
+    getSubagents(): SubagentsUserConfig;
 }
 /** Mask an API key for safe display. */
 export declare function maskKey(key: string): string;

package/dist/config.js

@@ -37,6 +37,19 @@ function sanitizeDefaultModel(model) {
 function sanitizeDefaultProvider(providerId) {
     return isHiddenProviderId(providerId) ? undefined : providerId;
 }
+function sanitizeSubagentsConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const out = {};
+    if (typeof raw.maxActiveSubagents === "number" && Number.isFinite(raw.maxActiveSubagents)) {
+        out.maxActiveSubagents = Math.max(1, Math.floor(raw.maxActiveSubagents));
+    }
+    if (typeof raw.childTokenCap === "number" && Number.isFinite(raw.childTokenCap)) {
+        out.childTokenCap = Math.max(1_000, Math.floor(raw.childTokenCap));
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function sanitizeTheme(value) {
     if (value == null)
         return undefined;
@@ -89,6 +102,7 @@ export class UserConfig {
                 providers: sanitizeProviders(parsed.providers),
                 defaultProvider: sanitizeDefaultProvider(parsed.defaultProvider),
                 agentCategories: sanitizeAgentCategories(parsed.agentCategories),
+                subagents: sanitizeSubagentsConfig(parsed.subagents),
                 theme: sanitizeTheme(parsed.theme),
             };
         }
@@ -188,6 +202,9 @@ export class UserConfig {
     getAgentCategories() {
         return sanitizeAgentCategories(this.data.agentCategories);
     }
+    getSubagents() {
+        return sanitizeSubagentsConfig(this.data.subagents) ?? {};
+    }
 }
 /** Mask an API key for safe display. */
 export function maskKey(key) {

package/dist/feishu/agent-host/approval-card.js

@@ -46,6 +46,15 @@ export function formatApprovalRequest(req) {
                 title: `LSP 操作 (${req.operation})`,
                 body: `**path:** \`${truncate(req.path, PATH_PREVIEW_MAX)}\``,
             };
+        case "agent_profile":
+            return {
+                title: `使用项目 agent profile "${req.name}"`,
+                body: [
+                    `**path:** \`${truncate(req.path, PATH_PREVIEW_MAX)}\``,
+                    `\n**prompt preview:**\n\`\`\`\n${truncate(req.promptPreview, CONTENT_PREVIEW_MAX)}\n\`\`\``,
+                    "\n该 profile 来自仓库本地 `.bubble/agents`，其 prompt 会驱动一个子代理。仅在信任该仓库时批准。",
+                ].join("\n"),
+            };
     }
 }
 function truncate(s, max) {

package/dist/feishu/agent-host/run-driver.js

@@ -78,6 +78,7 @@ export class RunDriver {
             approvalController,
             lspService,
             fileStateTracker,
+            checkpoints: () => session.manager.getCheckpoints(),
             // questionController intentionally omitted — Feishu v1 doesn't surface
             // the question tool to the agent.
         });
@@ -139,6 +140,7 @@ export class RunDriver {
             memoryPrompt,
             fileStateTracker,
             agentCategories: this.opts.deps.userConfig.getAgentCategories(),
+            subagents: this.opts.deps.userConfig.getSubagents(),
             providerFactory: (route) => this.opts.deps.createProviderForRoute(route, promptCacheKey),
             externalHooks: hookController,
         });

package/dist/main.js

@@ -30,6 +30,10 @@ import { basename } from "node:path";
 import { normalizeSingleLine, truncateVisual } from "./text-display.js";
 import { BUBBLE_WORDMARK } from "./tui/wordmark.js";
 import { configureDebugTrace, summarizeAgentEventForTrace, summarizeTraceMessage, traceEvent, } from "./debug-trace.js";
+// OpenTUI is the default renderer. The React Ink implementation (alt-screen
+// viewport, src/tui-ink) is feature-complete but still maturing — opt in with
+// BUBBLE_TUI=ink.
+const USE_OPENTUI = process.env.BUBBLE_TUI !== "ink";
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (process.argv.includes("-h") || process.argv.includes("--help")) {
@@ -163,6 +167,8 @@ async function main() {
         toolSearchController,
         lspService,
         fileStateTracker,
+        // Lazy: sessionManager is resolved after tools are created.
+        checkpoints: () => sessionManager?.getCheckpoints(),
     });
     // Bring up MCP servers (if any). Failures are captured per-server and never
     // block the rest of startup; /mcp surfaces status at runtime.
@@ -225,7 +231,9 @@ async function main() {
             else {
                 preResolvedTheme = themeConfig.mode;
             }
-            const { runSessionPicker } = await import("./tui-opentui/run-session-picker.js");
+            const { runSessionPicker } = USE_OPENTUI
+                ? await import("./tui-opentui/run-session-picker.js")
+                : await import("./tui-ink/run-session-picker.js");
             const picked = await runSessionPicker({
                 currentCwd: args.cwd,
                 currentSessions,
@@ -304,7 +312,7 @@ async function main() {
         sessionFile: sessionManager?.getSessionFile(),
         provider: activeProviderId || "none",
         model: activeModel || "none",
-        renderer: printMode ? "print" : "opentui-core",
+        renderer: printMode ? "print" : USE_OPENTUI ? "opentui-core" : "ink",
     });
     if (traceInfo.enabled) {
         traceEvent("run_start", {
@@ -372,6 +380,7 @@ async function main() {
         memoryPrompt,
         fileStateTracker,
         agentCategories: userConfig.getAgentCategories(),
+        subagents: userConfig.getSubagents(),
         providerFactory: createProviderForRoute,
         externalHooks: hookController,
     });
@@ -503,8 +512,41 @@ async function main() {
         else {
             detectedTheme = themeConfig.mode;
         }
+        // In-place session switch for the /session picker: rebind every closure
+        // that persists to the session (onMessageAppend, markers, title updater)
+        // by reassigning the outer `sessionManager`, then replace the agent's
+        // history the same way startup resume does.
+        const switchSession = (sessionFile) => {
+            try {
+                const next = new SessionManager(sessionFile);
+                const history = next.getMessages();
+                sessionManager = next;
+                sessionPromptCacheKey = next.getOrCreatePromptCacheKey();
+                sessionTitleUpdater = createSessionTitleUpdater({
+                    sessionManager: next,
+                    complete: (messages, completeOptions) => agent.complete(messages, completeOptions),
+                });
+                next.updateMetadata({
+                    ...(agent.model ? { model: agent.model } : {}),
+                    cwd: args.cwd,
+                    thinkingLevel: agent.thinking,
+                    reasoningEffort: agent.thinking,
+                });
+                // Keep the live system/meta head (mode reminders survive the switch),
+                // mirroring the /rewind history-replacement pattern.
+                const head = agent.messages.filter((m) => m.role === "system" || m.role === "meta");
+                agent.messages = [...head, ...history];
+                agent.setTodos(next.getTodos());
+                agent.resetContextUsageAnchor();
+                return { manager: next };
+            }
+            catch (error) {
+                return { error: error instanceof Error ? error.message : String(error) };
+            }
+        };
         const commonOptions = {
             sessionManager,
+            switchSession,
             createProvider,
             registry,
             skillRegistry,
@@ -523,19 +565,37 @@ async function main() {
         };
         const { getStartupUpdateNotice } = await import("./update/index.js");
         const updateNotice = await getStartupUpdateNotice();
-        const { runTui } = await import("./tui/run.js");
-        await runTui(agent, args, {
-            ...commonOptions,
-            themeMode: themeConfig.mode,
-            themeOverrides: themeConfig.overrides,
-            detectedTheme,
-            onThemeModeChange: (mode) => userConfig.setThemeMode(mode),
-            updateNotice: updateNotice ?? undefined,
-        });
+        // Two explicit branches (not a dynamic ternary import) so TypeScript
+        // checks each renderer's RunTuiOptions shape independently.
+        let exitWallMs;
+        if (USE_OPENTUI) {
+            const { runTui } = await import("./tui/run.js");
+            await runTui(agent, args, {
+                ...commonOptions,
+                themeMode: themeConfig.mode,
+                themeOverrides: themeConfig.overrides,
+                detectedTheme,
+                onThemeModeChange: (mode) => userConfig.setThemeMode(mode),
+                updateNotice: updateNotice ?? undefined,
+            });
+        }
+        else {
+            const { runTui } = await import("./tui-ink/run.js");
+            const summary = await runTui(agent, args, {
+                ...commonOptions,
+                themeMode: themeConfig.mode,
+                themeOverrides: themeConfig.overrides,
+                detectedTheme,
+                onThemeModeChange: (mode) => userConfig.setThemeMode(mode),
+                updateNotice: updateNotice ?? undefined,
+            });
+            exitWallMs = summary?.wallMs;
+        }
         if (sessionManager) {
-            printOpenTuiExitSummary(sessionManager, {
+            printExitSummary(sessionManager, {
                 resumed: resumedExistingSession,
                 theme: detectedTheme,
+                wallMs: exitWallMs,
             });
         }
     }
@@ -545,7 +605,7 @@ async function main() {
         traceEvent("run_shutdown_end");
     }
 }
-function printOpenTuiExitSummary(sessionManager, options) {
+function printExitSummary(sessionManager, options) {
     if (!process.stdout.isTTY)
         return;
     const sessionName = basename(sessionManager.getSessionFile());
@@ -589,6 +649,21 @@ function printOpenTuiExitSummary(sessionManager, options) {
     console.log();
     console.log(`${label("Session")}${colors.value(sessionLabel)}`);
     console.log(`${label("Continue")}${colors.value(continueCommand)}`);
+    if (options.wallMs !== undefined) {
+        console.log(`${label("Duration")}${colors.value(formatWallDuration(options.wallMs))}`);
+    }
+}
+function formatWallDuration(ms) {
+    const totalSeconds = Math.max(0, Math.round(ms / 1000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes < 60)
+        return `${minutes}m ${seconds}s`;
+    const hours = Math.floor(minutes / 60);
+    const minutesRest = minutes % 60;
+    return `${hours}h ${minutesRest}m ${seconds}s`;
 }
 async function readPipedStdin() {
     if (process.stdin.isTTY)

package/dist/network/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Typed transport errors shared between providers and the subagent runtime.
+ *
+ * `RateLimitError` is the contract for 429 handling (design doc
+ * docs/subagent-runtime-design.md §4.5): under `rateLimitPolicy: "defer"` the
+ * transport performs no 429 backoff of its own and throws this error
+ * immediately so the subagent scheduler can be the single backoff layer.
+ */
+export declare class RateLimitError extends Error {
+    readonly isRateLimitError = true;
+    readonly status: number;
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+export declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * How a provider transport should treat HTTP 429 responses.
+ *
+ * - "handle": retry inside the transport with backoff (parent traffic default).
+ * - "defer":  do not retry 429 at all; throw RateLimitError immediately so the
+ *             caller (subagent scheduler) owns the backoff. Other retryable
+ *             statuses are unaffected.
+ */
+export type RateLimitPolicy = "handle" | "defer";

package/dist/network/errors.js

@@ -0,0 +1,24 @@
+/**
+ * Typed transport errors shared between providers and the subagent runtime.
+ *
+ * `RateLimitError` is the contract for 429 handling (design doc
+ * docs/subagent-runtime-design.md §4.5): under `rateLimitPolicy: "defer"` the
+ * transport performs no 429 backoff of its own and throws this error
+ * immediately so the subagent scheduler can be the single backoff layer.
+ */
+export class RateLimitError extends Error {
+    isRateLimitError = true;
+    status;
+    retryAfterMs;
+    constructor(message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "RateLimitError";
+        this.status = options?.status ?? 429;
+        this.retryAfterMs = options?.retryAfterMs;
+    }
+}
+export function isRateLimitError(error) {
+    return !!error
+        && typeof error === "object"
+        && error.isRateLimitError === true;
+}

package/dist/orchestrator/default-hooks.js

@@ -20,7 +20,11 @@ export function createDefaultHooks() {
                     input: ctx.input,
                     enabled: taskType === "repo_orientation",
                 });
-                const taskReminder = reminderForTaskType(taskType);
+                const taskReminder = reminderForTaskType(taskType, {
+                    // Only parent agents carry the delegation tools; the nudge must
+                    // never reach a child that cannot spawn anything.
+                    canDelegate: ctx.agent.hasToolAvailable("spawn_agent"),
+                });
                 if (taskReminder) {
                     ctx.queueReminder(taskReminder);
                 }

package/dist/prompt/compose.js

@@ -6,6 +6,7 @@ import { buildGeminiProviderPrompt } from "./provider-prompts/gemini.js";
 import { buildGlmProviderPrompt } from "./provider-prompts/glm.js";
 import { buildGptProviderPrompt } from "./provider-prompts/gpt.js";
 import { buildKimiProviderPrompt } from "./provider-prompts/kimi.js";
+import { buildDelegationPolicyPrompt } from "./delegation.js";
 import { buildEnvironmentPrompt, defaultToolNames } from "./environment.js";
 import { buildRuntimePrompt } from "./runtime.js";
 export function composeSystemPrompt(options = {}) {
@@ -25,10 +26,12 @@ export function composeSystemPrompt(options = {}) {
         mode: options.mode,
         guidelines: buildGuidelines(options.tools ?? defaultToolNames, options.guidelines ?? []),
     });
+    const delegationPrompt = buildDelegationPolicyPrompt(options.tools ?? defaultToolNames);
     return [
         providerPrompt,
         environmentPrompt,
         runtimePrompt,
+        delegationPrompt,
         options.agentProfilePrompt,
         options.memoryPrompt,
     ].filter(Boolean).join("\n\n");

package/dist/prompt/delegation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Delegation policy section for the parent agent's system prompt.
+ *
+ * Two-sided by design (review 2026-06-12): positive triggers are quantified
+ * and read-only-scoped, negative clauses get equal weight — the user's hard
+ * constraint is "proactive, but never delegate-everything". Gated on the
+ * delegation tools being present, so child agents (whose tool sets never
+ * include spawn_agent/agent_team) never see it.
+ */
+/**
+ * Returns the delegation policy section when the agent actually has the
+ * delegation tools; child agents and stripped-down tool sets get nothing.
+ */
+export declare function buildDelegationPolicyPrompt(tools: string[]): string | undefined;

package/dist/prompt/delegation.js

@@ -0,0 +1,64 @@
+/**
+ * Delegation policy section for the parent agent's system prompt.
+ *
+ * Two-sided by design (review 2026-06-12): positive triggers are quantified
+ * and read-only-scoped, negative clauses get equal weight — the user's hard
+ * constraint is "proactive, but never delegate-everything". Gated on the
+ * delegation tools being present, so child agents (whose tool sets never
+ * include spawn_agent/agent_team) never see it.
+ */
+const DELEGATION_POLICY = `## Delegation policy (subagents)
+
+You can delegate work to background subagents (spawn_agent) and batch
+fan-outs (agent_team). Delegate deliberately, not by default.
+
+Delegate when:
+- An investigation will clearly require more than four search or read
+  operations, or spans multiple files and patterns, and the conversation only
+  needs the conclusion — delegate to a subagent so the intermediate noise
+  stays out of the main context. Launch multiple subagents concurrently for
+  independent questions.
+- The task naturally splits into the same read-only investigation or
+  analysis (review, audit, summarize) over several independent items (files,
+  modules, endpoints) — use agent_team.
+- A side-investigation is independent of your current main-line work and can
+  run in the background while you continue.
+
+Briefing a subagent: it starts with zero context, so the task message must be
+a self-contained work order — state the goal, list everything you already
+know, and write known file paths or commands directly into the task. Never
+outsource knowledge you already hold: if the task hinges on a specific path
+or line number, pin it down yourself first and put it in the briefing. When
+earlier work lives in an existing subagent, prefer send_input to resume it
+over spawning a fresh one.
+
+Do NOT delegate when:
+- The task requires editing files or running state-changing commands.
+  Built-in subagents are read-only; do edits and writes yourself unless a
+  write-capable (write_worktree) profile is explicitly available.
+- The task takes one or two tool calls (reading a single file, looking up one
+  definition). The handoff overhead costs more than the task.
+- Doing it well depends on conversation context (preferences the user stated
+  this session, decisions made in this discussion). Subagents start without
+  the conversation, and fork_context is not the fix: it copies only a recent
+  slice of the history, re-pays it as child tokens, and still loses earlier
+  decisions — do context-heavy work yourself.
+- You already read the relevant files in this conversation; a subagent would
+  re-read everything from scratch.
+- You already delegated it. Never redo delegated work locally, and never
+  re-spawn the same task to a second subagent.
+
+When in doubt about a one-off task, do it yourself. When a task is clearly
+the same read-only operation over three or more independent items — where
+each item alone would take more than a couple of tool calls — prefer
+agent_team over doing them sequentially yourself. For just two small items,
+do them yourself with parallel tool calls.`;
+/**
+ * Returns the delegation policy section when the agent actually has the
+ * delegation tools; child agents and stripped-down tool sets get nothing.
+ */
+export function buildDelegationPolicyPrompt(tools) {
+    if (!tools.includes("spawn_agent"))
+        return undefined;
+    return DELEGATION_POLICY;
+}

package/dist/prompt/task-reminders.d.ts

@@ -1,2 +1,6 @@
 import type { TaskType } from "../agent/task-classifier.js";
-export declare function reminderForTaskType(taskType: TaskType): string | undefined;
+export interface TaskReminderOptions {
+    /** Whether this agent has the delegation tools (parent agents only). */
+    canDelegate?: boolean;
+}
+export declare function reminderForTaskType(taskType: TaskType, options?: TaskReminderOptions): string | undefined;

package/dist/prompt/task-reminders.js

@@ -1,5 +1,13 @@
 import { wrapInSystemReminder } from "./reminders.js";
-export function reminderForTaskType(taskType) {
+/**
+ * Delegation nudge for exploration-shaped tasks: injected at the decision
+ * point (start of turn), where it carries far more weight for weakly
+ * delegating models than the session-start system prompt. Task-type gating
+ * keeps it away from ordinary implementation/debugging turns, so it cannot
+ * amplify over-delegation.
+ */
+const DELEGATION_NUDGE = "- If answering needs scanning many files and only the conclusion matters, delegate to a background subagent (spawn_agent); when it is the same read-only question over several independent items, fan out with agent_team.";
+export function reminderForTaskType(taskType, options = {}) {
     switch (taskType) {
         case "debugging":
             return wrapInSystemReminder(`
@@ -39,7 +47,7 @@ Repository orientation workflow:
 - Start with the repo purpose and main execution paths.
 - Inspect README/package metadata plus core runtime files before summarizing.
 - Keep the first pass read-only unless the user asks for changes or runtime verification.
-`);
+${options.canDelegate ? `${DELEGATION_NUDGE}\n` : ""}`);
         case "product_discussion":
             return wrapInSystemReminder(`
 Product discussion workflow:

package/dist/provider-anthropic.js

@@ -1,4 +1,5 @@
 import { getAvailableThinkingLevels, normalizeThinkingLevel } from "./provider-transform.js";
+import { RateLimitError } from "./network/errors.js";
 import { isProviderTransportError, normalizeProviderNetworkError, providerFetch } from "./network/provider-transport.js";
 import { computeRetryDelayMs, getProviderMaxRetries, isRetryableHttpStatus, ProviderStreamInterruptedError, retryAfterMsFromResponse, sleepBeforeRetry, } from "./network/retry.js";
 const ANTHROPIC_VERSION = "2023-06-01";
@@ -32,6 +33,7 @@ export function createAnthropicMessagesProvider(options) {
             method: "POST",
             body: JSON.stringify(body),
             signal: chatOptions.abortSignal,
+            rateLimitPolicy: chatOptions.rateLimitPolicy,
         });
         yield* translateAnthropicStream(events);
         yield { type: "done" };
@@ -428,6 +430,27 @@ async function fetchAnthropicResponseWithRetry(options, request) {
         if (response.ok)
             return response;
         const detail = await readAnthropicErrorDetail(response);
+        // Rate-limit contract (design §4.5): under "defer" the transport performs
+        // no 429 backoff and throws the typed error immediately; under "handle"
+        // an exhausted 429 retry budget still surfaces as the typed error so the
+        // caller can recognize it without string matching.
+        if (response.status === 429) {
+            const retryAfterMs = retryAfterMsFromResponse(response);
+            if (request.rateLimitPolicy === "defer") {
+                throw new RateLimitError(`Anthropic Messages API rate limited (429): ${detail || response.statusText}`, {
+                    status: 429,
+                    retryAfterMs,
+                });
+            }
+            if (request.signal?.aborted || attempt >= maxRetries) {
+                throw new RateLimitError(`Anthropic Messages API rate limited (429) after ${attempt + 1} attempts: ${detail || response.statusText}`, {
+                    status: 429,
+                    retryAfterMs,
+                });
+            }
+            await sleepBeforeRetry(computeRetryDelayMs(attempt + 1, { retryAfterMs }), request.signal);
+            continue;
+        }
         const error = new Error(`Anthropic Messages API error ${response.status}: ${detail || response.statusText}`);
         if (request.signal?.aborted || attempt >= maxRetries || !isRetryableAnthropicHttpError(response.status, detail)) {
             throw error;