@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/permissions/trust.js

@@ -0,0 +1,113 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+export function getPermissionTrustPath(options = {}) {
+    return join(options.bubbleHome ?? getBubbleHome(), "permissions-trust.json");
+}
+export function repoCapabilities(raw) {
+    const settings = isRecord(raw) ? raw : {};
+    const permissions = isRecord(settings.permissions) ? settings.permissions : {};
+    const allow = Array.isArray(permissions.allow)
+        ? permissions.allow.filter((rule) => typeof rule === "string")
+        : [];
+    const mcpServers = isRecord(settings.mcpServers) ? Object.keys(settings.mcpServers) : [];
+    const lspServers = isRecord(settings.lsp)
+        ? Object.entries(settings.lsp)
+            .filter(([, server]) => isRecord(server) && Object.keys(server).some((key) => key !== "disabled"))
+            .map(([id]) => id)
+        : [];
+    return { allow, mcpServers, lspServers };
+}
+/** Everything the given repository settings would enable, both scopes merged. */
+export function mergedRepoCapabilities(raw) {
+    const project = repoCapabilities(raw.project);
+    const local = repoCapabilities(raw.local);
+    return {
+        allow: [...project.allow, ...local.allow],
+        mcpServers: [...new Set([...project.mcpServers, ...local.mcpServers])],
+        lspServers: [...new Set([...project.lspServers, ...local.lspServers])],
+    };
+}
+export function describeRepoCapabilities(caps) {
+    return [
+        ...caps.allow.map((rule) => `allow rule   ${rule}`),
+        ...caps.mcpServers.map((name) => `MCP server   ${name} (Bubble starts it)`),
+        ...caps.lspServers.map((id) => `LSP server   ${id} (custom command, env or options)`),
+    ];
+}
+export function hasRepoCapabilities(raw) {
+    return [raw.project, raw.local].some((scope) => {
+        const caps = repoCapabilities(scope);
+        return caps.allow.length + caps.mcpServers.length + caps.lspServers.length > 0;
+    });
+}
+export function repoConfigFingerprint(cwd, raw) {
+    const pick = (scope) => {
+        const settings = isRecord(scope) ? scope : {};
+        const permissions = isRecord(settings.permissions) ? settings.permissions : {};
+        return { allow: permissions.allow ?? null, mcpServers: settings.mcpServers ?? null, lsp: settings.lsp ?? null };
+    };
+    return createHash("sha256")
+        .update(JSON.stringify({ cwd: safeRealpath(cwd), project: pick(raw.project), local: pick(raw.local) }))
+        .digest("hex");
+}
+/** True when the repository grants nothing, or the user trusted exactly this content. */
+export function isRepoConfigTrusted(cwd, raw, options = {}) {
+    if (!hasRepoCapabilities(raw))
+        return true;
+    return readStore(options).projects[safeRealpath(cwd)]?.fingerprint === repoConfigFingerprint(cwd, raw);
+}
+export function trustRepoConfig(cwd, raw, options = {}) {
+    const store = readStore(options);
+    store.projects[safeRealpath(cwd)] = {
+        fingerprint: repoConfigFingerprint(cwd, raw),
+        trustedAt: new Date().toISOString(),
+    };
+    const path = getPermissionTrustPath(options);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(store, null, 2) + "\n", "utf-8");
+}
+/** Reads both repository settings files; unparsable files count as absent. */
+export function readRepoSettings(cwd) {
+    const read = (path) => {
+        if (!existsSync(path))
+            return null;
+        try {
+            return JSON.parse(readFileSync(path, "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        project: read(join(cwd, ".bubble", "settings.json")),
+        local: read(join(cwd, ".bubble", "settings.local.json")),
+    };
+}
+function readStore(options) {
+    const path = getPermissionTrustPath(options);
+    if (!existsSync(path))
+        return { version: 1, projects: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed && typeof parsed.projects === "object" && parsed.projects !== null) {
+            return { version: 1, projects: parsed.projects };
+        }
+    }
+    catch {
+        // A corrupt store trusts nothing.
+    }
+    return { version: 1, projects: {} };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}

package/dist/permissions/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Permission rule system — types.
+ *
+ * A rule is one entry from the `allow` / `deny` arrays of a settings file:
+ *
+ *   "Bash"                      → any bash command
+ *   "Bash(git status)"          → exact command
+ *   "Bash(npm run:*)"           → prefix (anything starting with `npm run`)
+ *   "Read(./src/**)"            → glob on resolved path
+ *   "Read(~/.ssh/**)"           → tilde expanded
+ *   "WebFetch(domain:github.com)" → URL host match (suffix)
+ *   "*"                         → any tool
+ */
+export type ToolName = "Bash" | "Read" | "Write" | "Edit" | "Lsp" | "WebFetch" | "WebSearch" | string;
+export interface PermissionRule {
+    /** Tool this rule applies to, or "*" for all tools. */
+    tool: ToolName | "*";
+    /** Tool-specific pattern. Absent means "match any use of this tool". */
+    pattern?: string;
+    /** Original rule text as written in config, for display and diagnostics. */
+    source: string;
+}
+export interface PermissionRuleSet {
+    allow: PermissionRule[];
+    deny: PermissionRule[];
+}
+export type PermissionDecision = "allow" | "deny" | "ask";
+/**
+ * Discriminated input to the matcher. Tools only provide the fields they have.
+ */
+export type PermissionQuery = {
+    tool: "Bash";
+    command: string;
+} | {
+    tool: "Read" | "Write" | "Edit" | "Lsp";
+    path: string;
+    cwd: string;
+} | {
+    tool: "WebFetch";
+    url: string;
+} | {
+    tool: "WebSearch";
+} | {
+    tool: string;
+};
+export interface PermissionCheckResult {
+    decision: PermissionDecision;
+    /** Rule that produced the decision, if any. */
+    rule?: PermissionRule;
+}
+export interface RuleParseError {
+    source: string;
+    message: string;
+}
+export type ParsedRule = {
+    ok: true;
+    rule: PermissionRule;
+} | {
+    ok: false;
+    error: RuleParseError;
+};

package/dist/permissions/types.js

@@ -0,0 +1,14 @@
+/**
+ * Permission rule system — types.
+ *
+ * A rule is one entry from the `allow` / `deny` arrays of a settings file:
+ *
+ *   "Bash"                      → any bash command
+ *   "Bash(git status)"          → exact command
+ *   "Bash(npm run:*)"           → prefix (anything starting with `npm run`)
+ *   "Read(./src/**)"            → glob on resolved path
+ *   "Read(~/.ssh/**)"           → tilde expanded
+ *   "WebFetch(domain:github.com)" → URL host match (suffix)
+ *   "*"                         → any tool
+ */
+export {};

package/dist/print-output.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Structured output for print mode (`-p --output-format json`).
+ *
+ * Built for benchmark/CI adapters (Pier, terminal-bench): stdout carries
+ * exactly one JSON object; all human-facing noise goes to stderr. Field
+ * names follow the grok-build/Claude Code convention (text, stopReason,
+ * sessionId, usage.{input_tokens,...}, num_turns) so existing harness
+ * adapters port with minimal changes.
+ */
+import type { AgentEvent } from "./types.js";
+export type PrintOutputFormat = "plain" | "json";
+export declare function parseOutputFormat(raw: string | undefined): PrintOutputFormat | undefined;
+/**
+ * Anthropic's usage decomposition, which the field names already claimed to
+ * follow: the four token buckets are DISJOINT and sum to `total_tokens`.
+ *
+ *   input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+ *     + output_tokens === total_tokens
+ *
+ * `input_tokens` is therefore the uncached remainder only — it does NOT include
+ * cache reads. It used to carry the whole prompt total, which was harmless while
+ * cache reads were a flat few thousand tokens per turn, but message-level prompt
+ * caching makes reads 70-90% of the prompt, and a harness that priced
+ * `input_tokens` at the full input rate would then overstate cost ~2x.
+ */
+export interface PrintUsageSummary {
+    input_tokens: number;
+    cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
+    output_tokens: number;
+    reasoning_tokens: number;
+    total_tokens: number;
+}
+export interface PrintRunSummary {
+    /** Final answer: the last turn's streamed text. */
+    text: string;
+    num_turns: number;
+    num_tool_calls: number;
+    usage: PrintUsageSummary;
+    /**
+     * False when no turn carried provider usage (some endpoints — notably the
+     * Grok subscription proxy — omit it): zeros then mean "not reported",
+     * not "free". Mirrors the goal engine's markTokenUsageUnavailable and
+     * grok-build's usage_is_incomplete convention.
+     */
+    usage_reported: boolean;
+}
+export declare class PrintRunCollector {
+    private turnText;
+    private lastTurnText;
+    private turns;
+    private toolCalls;
+    private usageReported;
+    private readonly usage;
+    onEvent(event: AgentEvent): void;
+    private addUsage;
+    summary(): PrintRunSummary;
+}
+/**
+ * Harness-observed change footprint of the run (git ground truth). Printed
+ * by the harness, not the model — a run cannot omit or misstate what it
+ * touched ("no breaking changes" next to deleted test assertions).
+ */
+export interface PrintChangeSummary {
+    changed_files: number;
+    modified_existing_tests: Array<{
+        path: string;
+        deleted_lines: number;
+    }>;
+}
+/**
+ * Per-path counts of context compactions during the run. Lets benchmark
+ * harnesses correlate outcomes with "did the model ever lose sight of the
+ * full history" without access to the in-container session files.
+ */
+export interface PrintCompactionStats {
+    resident: number;
+    subturn: number;
+    llm: number;
+    overflow: number;
+    /** Successful compaction computations incl. rejected rewrites (churn signal). */
+    fired: number;
+    droppedMessages: number;
+}
+export declare function formatPrintJson(input: {
+    summary: PrintRunSummary;
+    sessionId?: string;
+    stopReason?: "end_turn" | "error" | "cancelled";
+    compaction?: PrintCompactionStats;
+    changes?: PrintChangeSummary;
+}): string;
+export declare function formatPrintJsonError(input: {
+    message: string;
+    summary?: PrintRunSummary;
+    sessionId?: string;
+    compaction?: PrintCompactionStats;
+    changes?: PrintChangeSummary;
+}): string;

package/dist/print-output.js

@@ -0,0 +1,117 @@
+/**
+ * Structured output for print mode (`-p --output-format json`).
+ *
+ * Built for benchmark/CI adapters (Pier, terminal-bench): stdout carries
+ * exactly one JSON object; all human-facing noise goes to stderr. Field
+ * names follow the grok-build/Claude Code convention (text, stopReason,
+ * sessionId, usage.{input_tokens,...}, num_turns) so existing harness
+ * adapters port with minimal changes.
+ */
+export function parseOutputFormat(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === "plain" || raw === "json")
+        return raw;
+    return undefined;
+}
+export class PrintRunCollector {
+    turnText = "";
+    lastTurnText = "";
+    turns = 0;
+    toolCalls = 0;
+    usageReported = false;
+    usage = {
+        input_tokens: 0,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+        output_tokens: 0,
+        reasoning_tokens: 0,
+        total_tokens: 0,
+    };
+    onEvent(event) {
+        switch (event.type) {
+            case "turn_start":
+                this.turns += 1;
+                this.turnText = "";
+                break;
+            case "text_delta":
+                this.turnText += event.content;
+                break;
+            case "provider_retry":
+                // The retried response supersedes the partial text.
+                this.turnText = "";
+                break;
+            case "tool_start":
+                this.toolCalls += 1;
+                break;
+            case "turn_end":
+                // Usage reaches AgentEvent only on turn_end (the stream-level
+                // "usage" chunk is aggregated into it by the agent loop).
+                if (this.turnText.trim())
+                    this.lastTurnText = this.turnText;
+                if (event.usage)
+                    this.addUsage(event.usage);
+                break;
+            default:
+                break;
+        }
+    }
+    addUsage(usage) {
+        this.usageReported = true;
+        const prompt = usage.promptTokens ?? 0;
+        const cacheRead = usage.promptCacheHitTokens ?? 0;
+        // promptCacheMissTokens already includes creation, so creation has to be
+        // netted out of the uncached remainder rather than added alongside it.
+        const cacheCreation = usage.cacheCreationTokens ?? 0;
+        const uncached = usage.promptCacheMissTokens !== undefined
+            ? Math.max(0, usage.promptCacheMissTokens - cacheCreation)
+            : Math.max(0, prompt - cacheRead - cacheCreation);
+        this.usage.input_tokens += uncached;
+        this.usage.cache_read_input_tokens += cacheRead;
+        this.usage.cache_creation_input_tokens += cacheCreation;
+        this.usage.output_tokens += usage.completionTokens ?? 0;
+        this.usage.reasoning_tokens += usage.reasoningTokens ?? 0;
+        this.usage.total_tokens += usage.totalTokens
+            ?? ((usage.promptTokens ?? 0) + (usage.completionTokens ?? 0));
+    }
+    summary() {
+        return {
+            text: (this.lastTurnText || this.turnText).trim(),
+            num_turns: this.turns,
+            num_tool_calls: this.toolCalls,
+            usage: { ...this.usage },
+            usage_reported: this.usageReported,
+        };
+    }
+}
+export function formatPrintJson(input) {
+    return JSON.stringify({
+        text: input.summary.text,
+        stopReason: input.stopReason ?? "end_turn",
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        num_turns: input.summary.num_turns,
+        num_tool_calls: input.summary.num_tool_calls,
+        usage: input.summary.usage,
+        usage_reported: input.summary.usage_reported,
+        ...(input.compaction ? { compaction: input.compaction } : {}),
+        ...(input.changes ? { changes: input.changes } : {}),
+    });
+}
+export function formatPrintJsonError(input) {
+    return JSON.stringify({
+        type: "error",
+        message: input.message,
+        stopReason: "error",
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(input.summary
+            ? {
+                text: input.summary.text,
+                num_turns: input.summary.num_turns,
+                num_tool_calls: input.summary.num_tool_calls,
+                usage: input.summary.usage,
+            }
+            : {}),
+        ...(input.compaction ? { compaction: input.compaction } : {}),
+        ...(input.changes ? { changes: input.changes } : {}),
+    });
+}

package/dist/prompt/compose.d.ts

@@ -0,0 +1,19 @@
+import type { PermissionMode, ThinkingLevel } from "../types.js";
+import { type EnvironmentPromptOptions } from "./environment.js";
+import type { SkillSummary } from "../skills/types.js";
+export interface ComposeSystemPromptOptions extends EnvironmentPromptOptions {
+    agentName?: string;
+    guidelines?: string[];
+    thinkingLevel?: ThinkingLevel;
+    mode?: PermissionMode;
+    /** Prompt-visible skills; when given (and `skill` is a tool), listed as a catalog. */
+    skills?: SkillSummary[];
+    /** Catalog budget in characters (default SKILL_CATALOG_CHARS); 0 falls back to search only. */
+    skillCatalogChars?: number;
+    memoryPrompt?: string;
+    agentProfilePrompt?: string;
+    /** Rendered subagent model-routing menu (design §4). Placed right after the
+     *  delegation policy and gated the same way: spawn_agent present. */
+    modelRoutingPrompt?: string;
+}
+export declare function composeSystemPrompt(options?: ComposeSystemPromptOptions): string;

package/dist/prompt/compose.js

@@ -0,0 +1,110 @@
+import { buildAnthropicProviderPrompt } from "./provider-prompts/anthropic.js";
+import { buildCodexProviderPrompt } from "./provider-prompts/codex.js";
+import { buildDefaultProviderPrompt } from "./provider-prompts/default.js";
+import { buildDeepSeekProviderPrompt } from "./provider-prompts/deepseek.js";
+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";
+import { buildSkillCatalog } from "../skills/format.js";
+export function composeSystemPrompt(options = {}) {
+    const agentName = options.agentName ?? "Bubble";
+    const providerPrompt = buildProviderPrompt(agentName, options.configuredProvider, options.configuredModelId, options.configuredModel);
+    const environmentPrompt = buildEnvironmentPrompt({
+        configuredProvider: options.configuredProvider,
+        configuredModel: options.configuredModel,
+        configuredModelId: options.configuredModelId,
+        workingDir: options.workingDir,
+        currentDate: options.currentDate,
+        tools: options.tools ?? defaultToolNames,
+        toolSnippets: options.toolSnippets,
+    });
+    const tools = options.tools ?? defaultToolNames;
+    // Level one of skill loading: names and one-line descriptions are always in
+    // context; bodies load on demand with `skill`. Last section, so the prefix
+    // above stays byte-identical while the skill set is unchanged.
+    const skillCatalog = options.skills && tools.includes("skill")
+        ? buildSkillCatalog(options.skills, {
+            budgetChars: options.skillCatalogChars,
+            searchable: tools.includes("skill_search"),
+        })
+        : undefined;
+    const runtimePrompt = buildRuntimePrompt({
+        thinkingLevel: options.thinkingLevel,
+        mode: options.mode,
+        guidelines: buildGuidelines(tools, options.guidelines ?? [], skillCatalog),
+    });
+    const delegationPrompt = buildDelegationPolicyPrompt(options.tools ?? defaultToolNames);
+    // Same gate as the delegation policy: children (no spawn_agent) never see the menu.
+    const modelRoutingPrompt = delegationPrompt ? options.modelRoutingPrompt : undefined;
+    return [
+        providerPrompt,
+        environmentPrompt,
+        runtimePrompt,
+        delegationPrompt,
+        modelRoutingPrompt,
+        options.agentProfilePrompt,
+        options.memoryPrompt,
+        skillCatalog?.text,
+    ].filter(Boolean).join("\n\n");
+}
+function buildProviderPrompt(agentName, providerId, modelId, modelName) {
+    const provider = providerId ?? "";
+    const rawModel = modelId ?? modelName ?? "";
+    const model = rawModel.includes(":") ? rawModel.split(":").slice(1).join(":") : rawModel;
+    const lowerModel = model.toLowerCase();
+    if (provider === "anthropic" || provider === "minimax" || provider.endsWith("-anthropic") || model.startsWith("claude")) {
+        return buildAnthropicProviderPrompt(agentName);
+    }
+    if (provider === "google" || model.startsWith("gemini")) {
+        return buildGeminiProviderPrompt(agentName);
+    }
+    if (provider === "openai-codex" || model.includes("codex") || model.startsWith("gpt-5")) {
+        return buildCodexProviderPrompt(agentName);
+    }
+    if (provider === "deepseek" || model.startsWith("deepseek")) {
+        return buildDeepSeekProviderPrompt(agentName);
+    }
+    if (["moonshot-cn", "moonshot-intl", "kimi-for-coding"].includes(provider) || lowerModel.includes("kimi") || lowerModel.includes("k2.")) {
+        return buildKimiProviderPrompt(agentName);
+    }
+    if (["zhipuai", "zhipuai-coding-plan", "zai", "zai-coding-plan"].includes(provider) || model.startsWith("glm")) {
+        return buildGlmProviderPrompt(agentName);
+    }
+    if (provider === "openai" || provider === "openrouter" || model.startsWith("gpt") || model.startsWith("o1")) {
+        return buildGptProviderPrompt(agentName);
+    }
+    return buildDefaultProviderPrompt(agentName);
+}
+function buildGuidelines(tools, extraGuidelines, skillCatalog) {
+    const guidelines = [];
+    const add = (item) => {
+        if (!guidelines.includes(item)) {
+            guidelines.push(item);
+        }
+    };
+    if (tools.includes("ls")) {
+        add("Use ls to list directory contents, including files and subdirectories");
+    }
+    if (tools.includes("grep")) {
+        add("Use grep to search file contents");
+    }
+    if (tools.includes("bash")) {
+        add("Use bash for file operations like ls, find, and rg when appropriate");
+    }
+    if (tools.includes("question")) {
+        add("When the user is explicitly discussing, brainstorming, or shaping an approach instead of asking for immediate execution, use the question tool for targeted clarification or preference choices when it would materially improve the discussion; do not use it for generic permission-to-proceed questions");
+    }
+    // With a catalog the Skills section itself says how to load; search remains
+    // the only route when the host gave no catalog or turned it off.
+    if (!skillCatalog?.listed && tools.includes("skill_search") && tools.includes("skill")) {
+        add("Skills may provide specialized workflows. When a task appears to match a specialized workflow, call skill_search to find relevant skills, then call skill with the exact name to load the selected skill before applying it");
+    }
+    for (const item of extraGuidelines) {
+        add(item);
+    }
+    return guidelines;
+}

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/run_workflow) 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,100 @@
+/**
+ * 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/run_workflow) never see it.
+ */
+const DELEGATION_POLICY = `## Delegation policy (subagents)
+
+You can delegate work two ways: a single background subagent (spawn_agent),
+or an orchestration script coordinating many subagents (run_workflow).
+Delegate deliberately, not by default.
+
+Explicit requests win, before any other rule: when the user names a
+coordinated multi-agent run in any phrasing — a workflow, an orchestration,
+an agent team, "fan out agents" — that means run_workflow, NOT a row of
+spawn_agent calls. When they ask for a subagent, spawn one. Only when the
+user has not named a mechanism do you choose by shape (below).
+
+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 fans out over many independent items (review, audit, summarize
+  across files, modules, endpoints) or needs staged orchestration — consider
+  run_workflow. Choose by shape, not by rule: a handful of subagents whose
+  results you want to read and react to individually favor spawn_agent; a
+  uniform sweep over many items, results that should be aggregated or
+  filtered before they reach this conversation, or control flow between
+  stages (pipelines, loops, retry rounds) favor a run_workflow script — each
+  member's full handoff stays out of your context and the script returns one
+  digested result. Inside parallel()/pipeline(), a failed agent() resolves to
+  null — report which items came back null instead of silently dropping them.
+  A bare "await agent(...)" outside those combinators PROPAGATES its error
+  and fails the whole run: keep must-not-die steps (a final synthesis, the
+  last aggregation) inside parallel([...]) or a try/catch so one member's
+  failure cannot discard every other member's finished work.
+- 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 edits are ENTANGLED — shared state, one file feeding the next, order
+  matters. Write delegation exists (the builtin "implementer" profile runs
+  in an isolated git worktree), but it only pays off for INDEPENDENT edit
+  groups with disjoint file sets. Worktree children fork from the last
+  commit and the parent reviews/applies their changes afterward; entangled
+  work through that contract only adds merge risk — do it yourself.
+- 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
+run_workflow over doing them sequentially yourself. For just two small items,
+do them yourself with parallel tool calls.
+
+Routing (model per child): match each child's model to its task, not to
+habit. Mechanical fan-out work — scanning, grepping, summarizing single
+files, format checks, data extraction — belongs on category "quick" or
+"explore", or an explicit fast-tier model from the routing menu; spawning
+many children that all inherit a strong parent model is waste. Judgment
+work — reviewing, adjudicating between findings, synthesizing a final
+answer, subtle debugging — keeps the parent's model: do NOT downgrade it
+to save cost. When unsure, inherit. Follow the routing menu's rules on
+which model ids are valid and whether cross-provider routing is available.
+Cross-provider (provider:model) is for a reason, not a habit: use it when
+the user names a provider or a task clearly plays to another provider's
+strength; tier labels do not compare across providers, so a cross-provider
+pick is a judgment call you should be able to justify. Same-provider is
+the default frame.`;
+/**
+ * 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/environment.d.ts

@@ -0,0 +1,12 @@
+export interface EnvironmentPromptOptions {
+    configuredProvider?: string;
+    configuredModel?: string;
+    configuredModelId?: string;
+    workingDir?: string;
+    currentDate?: string;
+    tools?: string[];
+    toolSnippets?: Record<string, string>;
+}
+export declare const defaultToolSnippets: Record<string, string>;
+export declare const defaultToolNames: string[];
+export declare function buildEnvironmentPrompt(options?: EnvironmentPromptOptions): string;