qlogicagent 2.13.3 → 2.13.5

package/dist/orchestration/solo-persistence.js

@@ -0,0 +1,67 @@
+/**
+ * Solo Persistence — read/write Solo Mode state to disk.
+ *
+ * State is stored at `<project>/.qlogicagent/solos/<soloId>/solo-state.json`.
+ * Mirrors the product-persistence.ts pattern.
+ */
+import { join } from "node:path";
+import { mkdir, readdir } from "node:fs/promises";
+import { readJsonFile, writeJsonFile } from "../runtime/infra/disk-storage.js";
+import { getDefaultPathService } from "../runtime/infra/default-path-service.js";
+function resolvePathService(options) {
+    return options?.pathService ?? getDefaultPathService();
+}
+function resolveProjectRoot(cwd, pathService) {
+    return cwd ?? pathService.getActiveProjectRoot();
+}
+function getSolosDir(cwd, options) {
+    const pathService = resolvePathService(options);
+    return join(pathService.getProjectAgentDir(resolveProjectRoot(cwd, pathService)), "solos");
+}
+function getSoloDir(soloId, cwd, options) {
+    return join(getSolosDir(cwd, options), soloId);
+}
+function getStatePath(soloId, cwd, options) {
+    return join(getSoloDir(soloId, cwd, options), "solo-state.json");
+}
+// ── Public API ──────────────────────────────────────────────
+/** Save solo state to disk. */
+export async function saveSoloState(state, cwd, options) {
+    const dir = getSoloDir(state.soloId, cwd, options);
+    await mkdir(dir, { recursive: true });
+    await writeJsonFile(getStatePath(state.soloId, cwd, options), state);
+}
+/** Load solo state from disk. Returns undefined if not found. */
+export async function loadSoloState(soloId, cwd, options) {
+    return readJsonFile(getStatePath(soloId, cwd, options));
+}
+/** List all solo session IDs with their persisted state. */
+export async function listSoloSessions(cwd, options) {
+    const dir = getSolosDir(cwd, options);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const sessions = [];
+    for (const entry of entries) {
+        const state = await loadSoloState(entry, cwd, options);
+        if (state)
+            sessions.push(state);
+    }
+    return sessions;
+}
+/** Delete solo state from disk. */
+export async function deleteSoloState(soloId, cwd, options) {
+    const { rm } = await import("node:fs/promises");
+    const dir = getSoloDir(soloId, cwd, options);
+    try {
+        await rm(dir, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/orchestration/solo-spec-builder.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Solo Spec Builder — 小智(qlogicagent)主持的「一轮澄清 + 轻量 spec」过程。
+ *
+ * 路径选择:走 runForkedAgent(进程内推理 agent,同 team-delegate/dream),而非 solo 竞赛的
+ * processManager.spawn(ACP 子进程)。理由:spec 阶段是交互式推理(分析→ask-user 澄清→产 spec),
+ * 不改文件、不需 worktree,且需要 ask-user 交互 —— 这正是 runForkedAgent 的场景。
+ *
+ * 本模块是纯编排:askUser 后端 + ask_user 工具定义由调用方(Cut3 RPC handler)注入,
+ * 这样模块本身不依赖全局 ask-user 回调或 toolCatalog。
+ */
+import type { ForkedAgentRunnerFactory } from "../runtime/ports/agent-execution-contracts.js";
+import type { LLMTransport } from "../runtime/ports/index.js";
+import type { ToolDefinition, AgentLogger } from "../agent/types.js";
+import type { SoloSpec } from "../protocol/wire/acp-agent-management.js";
+import { type AskUserQuestion } from "../skills/tools/ask-user-tool.js";
+/** R3 多轮对话式 spec 的单轮入参。history 含到本轮为止的完整对话(末条为用户最新消息)。 */
+export interface SpecChatDeps {
+    rawTask: string;
+    history: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+    transport: LLMTransport;
+    apiKey: string;
+    model: string;
+    createAgentRunner: ForkedAgentRunnerFactory;
+    askUserToolDef: ToolDefinition;
+    askUser: (questions: AskUserQuestion[], signal?: AbortSignal) => Promise<Record<string, string> | null>;
+    log: AgentLogger;
+    parentSignal?: AbortSignal;
+}
+/** R3 多轮对话式 spec:agent 通过此工具产出/更新结构化规格(类比 plan_mode 的 plan 入参)。 */
+export declare const SET_SPEC_TOOL_NAME = "set_spec";
+export declare const SET_SPEC_TOOL_DEF: ToolDefinition;
+/**
+ * R3 单轮对话式 spec(无状态:每轮带全量 history 重跑 forked agent)。受限工具 = ask_user + set_spec,
+ * 纯推理不改文件(plan-mode 式)。返回本轮自然语言 reply + 最新 SoloSpec(set_spec 未调时回退解析文本)。
+ * 失败(LLM/连接级)会抛 —— 由调用方降级。
+ */
+export declare function runSpecChatRound(deps: SpecChatDeps): Promise<{
+    reply: string;
+    spec: SoloSpec;
+}>;
+/** 解析小智的标记块文本 → SoloSpec。带兜底,绝不抛(降级:goal=rawTask、acceptance 可空)。 */
+export declare function parseSpecResponse(text: string, rawTask: string, clarifications?: {
+    question: string;
+    answer: string;
+}[]): SoloSpec;

package/dist/orchestration/solo-spec-builder.js

@@ -0,0 +1,139 @@
+/**
+ * Solo Spec Builder — 小智(qlogicagent)主持的「一轮澄清 + 轻量 spec」过程。
+ *
+ * 路径选择:走 runForkedAgent(进程内推理 agent,同 team-delegate/dream),而非 solo 竞赛的
+ * processManager.spawn(ACP 子进程)。理由:spec 阶段是交互式推理(分析→ask-user 澄清→产 spec),
+ * 不改文件、不需 worktree,且需要 ask-user 交互 —— 这正是 runForkedAgent 的场景。
+ *
+ * 本模块是纯编排:askUser 后端 + ask_user 工具定义由调用方(Cut3 RPC handler)注入,
+ * 这样模块本身不依赖全局 ask-user 回调或 toolCatalog。
+ */
+import { runForkedAgent } from "../runtime/execution/forked-agent.js";
+import { ASK_USER_TOOL_NAME } from "../skills/tools/ask-user-tool.js";
+/** R3 多轮对话式 spec:agent 通过此工具产出/更新结构化规格(类比 plan_mode 的 plan 入参)。 */
+export const SET_SPEC_TOOL_NAME = "set_spec";
+export const SET_SPEC_TOOL_DEF = {
+    type: "function",
+    function: {
+        name: SET_SPEC_TOOL_NAME,
+        description: "产出或更新本次 Solo 竞赛的规格(目标/约束/验收)。每当规格有变化就调用它。",
+        parameters: {
+            type: "object",
+            properties: {
+                goal: { type: "string", description: "一句话竞赛目标" },
+                constraints: { type: "array", items: { type: "string" }, description: "关键约束(0-5 条)" },
+                acceptance: { type: "array", items: { type: "string" }, description: "可客观判定的验收标准(3-5 条)" },
+            },
+            required: ["goal", "acceptance"],
+        },
+    },
+};
+const SPEC_CHAT_SYSTEM_PROMPT = `你是 Solo 竞赛的"规格制定主持人"(中立,不参赛),正在与用户多轮对话,逐步明确一份竞赛规格。
+每一轮:
+1. 理解用户最新意图。
+2. 必要时调用 ${ASK_USER_TOOL_NAME} 抛 2-4 个澄清问题(能给选项就给 2-4 个;已足够清晰则不必问)。
+3. 调用 ${SET_SPEC_TOOL_NAME} 产出/更新规格:goal(一句话目标)、constraints(0-5 条关键约束)、acceptance(3-5 条、每条可客观判定)。每当规格有变化都要调用它。
+4. 用简短自然语言回复用户:说明本轮规格变化或追问;不要整段复述规格(规格在右侧面板展示)。
+约束:只产出规格,绝不修改任何文件。用户满意后会自行点击"启动竞赛"。`;
+/**
+/** 取 forked agent 的最终文本:end 事件 content,退化到拼 delta 文本。 */
+function extractFinalText(res) {
+    return res.events
+        .filter((e) => e.type === "end" && "content" in e)
+        .map((e) => e.content ?? "")
+        .join("")
+        || res.events
+            .filter((e) => e.type === "delta" && "text" in e)
+            .map((e) => e.text)
+            .join("");
+}
+/**
+ * R3 单轮对话式 spec(无状态:每轮带全量 history 重跑 forked agent)。受限工具 = ask_user + set_spec,
+ * 纯推理不改文件(plan-mode 式)。返回本轮自然语言 reply + 最新 SoloSpec(set_spec 未调时回退解析文本)。
+ * 失败(LLM/连接级)会抛 —— 由调用方降级。
+ */
+export async function runSpecChatRound(deps) {
+    const clarifications = [];
+    let lastSpec = null;
+    const toolInvoker = {
+        invoke: async (_turnId, name, args, signal) => {
+            if (name === ASK_USER_TOOL_NAME) {
+                let questions = [];
+                try {
+                    questions = JSON.parse(args).questions ?? [];
+                }
+                catch {
+                    return { result: "Invalid ask_user arguments.", error: "parse_error" };
+                }
+                const answers = await deps.askUser(questions, signal);
+                if (!answers)
+                    return { result: "User declined to answer the clarifying questions." };
+                const lines = ["User answered:"];
+                for (const q of questions) {
+                    const answer = answers[q.question] ?? "(no answer)";
+                    lines.push(`- ${q.header}: ${answer}`);
+                    clarifications.push({ question: q.question, answer });
+                }
+                return { result: lines.join("\n") };
+            }
+            if (name === SET_SPEC_TOOL_NAME) {
+                try {
+                    const a = JSON.parse(args);
+                    lastSpec = {
+                        goal: (a.goal ?? "").trim() || deps.rawTask.trim().slice(0, 200),
+                        constraints: Array.isArray(a.constraints) ? a.constraints.filter(Boolean).slice(0, 5) : [],
+                        acceptance: Array.isArray(a.acceptance) ? a.acceptance.filter(Boolean).slice(0, 5) : [],
+                        rawTask: deps.rawTask,
+                        clarifications: clarifications.length ? [...clarifications] : undefined,
+                    };
+                    return { result: "规格已更新" };
+                }
+                catch {
+                    return { result: "Invalid set_spec arguments.", error: "parse_error" };
+                }
+            }
+            return { result: `Tool ${name} is not available in the spec phase.` };
+        },
+    };
+    const promptMessages = deps.history.map((h) => ({ role: h.role, content: h.content }));
+    const res = await runForkedAgent({
+        promptMessages,
+        systemPrompt: SPEC_CHAT_SYSTEM_PROMPT,
+        tools: [deps.askUserToolDef, SET_SPEC_TOOL_DEF],
+        transport: deps.transport,
+        toolInvoker,
+        createAgentRunner: deps.createAgentRunner,
+        apiKey: deps.apiKey,
+        model: deps.model,
+        log: deps.log,
+        forkLabel: "solo-spec-chat",
+        maxTurns: 6,
+        parentSignal: deps.parentSignal,
+    });
+    const text = extractFinalText(res);
+    // set_spec 未调用 → 回退解析标记块文本;仍不完整时 parseSpecResponse 兜底 goal=rawTask。
+    const spec = lastSpec ?? parseSpecResponse(text, deps.rawTask, clarifications);
+    const reply = text.trim() || (lastSpec ? "已更新规格(见右侧面板)。" : "已记录,请继续补充,或点击启动竞赛。");
+    return { reply, spec };
+}
+/** 解析小智的标记块文本 → SoloSpec。带兜底,绝不抛(降级:goal=rawTask、acceptance 可空)。 */
+export function parseSpecResponse(text, rawTask, clarifications = []) {
+    const goal = text.match(/GOAL:\s*(.+)/i)?.[1]?.trim() || rawTask.trim().slice(0, 200);
+    const constraints = extractBullets(text, /CONSTRAINTS:\s*([\s\S]*?)(?:\n\s*ACCEPTANCE:|$)/i);
+    const acceptance = extractBullets(text, /ACCEPTANCE:\s*([\s\S]*?)$/i);
+    return {
+        goal,
+        constraints,
+        acceptance,
+        rawTask,
+        clarifications: clarifications.length ? clarifications : undefined,
+    };
+}
+function extractBullets(text, blockRe) {
+    const block = text.match(blockRe)?.[1] ?? "";
+    return block
+        .split("\n")
+        .map((l) => l.replace(/^\s*[-*]\s?/, "").trim())
+        .filter(Boolean)
+        .slice(0, 5);
+}

package/dist/orchestration/subagent/agent-registry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Built-in Agent Registry — CC-aligned agent definitions for fork/subagent.
+ *
+ * Each built-in agent defines a role with constrained tools, system prompt,
+ * and execution budget. The LLM can invoke these via the AgentTool.
+ */
+import type { PermissionRole, IsolationMode } from "./task-types.js";
+export interface AgentDefinition {
+    /** Unique identifier for the agent (kebab-case). */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** Short description (appears in tool_search / LLM prompt). */
+    description: string;
+    /** Maximum turns this agent can execute before forced stop. */
+    maxTurns: number;
+    /** Tool capability profile. This is not a user permission mode. */
+    toolCapabilityProfile: "all_tools" | "read_tools" | "no_tools";
+    /** Explicit allowed tool names (if empty, uses toolCapabilityProfile filter). */
+    allowedTools?: string[];
+    /** Whether this agent can fork sub-agents itself. */
+    canFork: boolean;
+    /** System prompt override for this agent. */
+    systemPromptSuffix?: string;
+    /** Permission role context (CC: interactive/coordinator/worker). Default: "worker". */
+    permissionRole?: PermissionRole;
+    /** Isolation mode (CC: shared/worktree/container). Default: "shared". */
+    isolation?: IsolationMode;
+}
+/**
+ * Get the full list of built-in agent definitions.
+ */
+export declare function getBuiltInAgents(): AgentDefinition[];
+/**
+ * Look up a built-in agent by name.
+ */
+export declare function getBuiltInAgent(name: string): AgentDefinition | undefined;
+/**
+ * Check if a given agent name is a built-in agent.
+ */
+export declare function isBuiltInAgent(name: string): boolean;
+/**
+ * Resolve tool access for an agent definition.
+ * Returns the set of tool names the agent is allowed to use.
+ */
+export declare function resolveAgentToolSet(agent: AgentDefinition, availableTools: string[]): string[];

package/dist/orchestration/subagent/agent-registry.js

@@ -0,0 +1,129 @@
+/**
+ * Built-in Agent Registry — CC-aligned agent definitions for fork/subagent.
+ *
+ * Each built-in agent defines a role with constrained tools, system prompt,
+ * and execution budget. The LLM can invoke these via the AgentTool.
+ */
+/** General-purpose sub-agent for delegated tasks. */
+const GENERAL_PURPOSE_AGENT = {
+    name: "general",
+    label: "General Purpose",
+    description: "A general-purpose sub-agent that can perform any task with full tool access.",
+    maxTurns: 200,
+    toolCapabilityProfile: "all_tools",
+    canFork: false,
+};
+/** Explore agent — read-only exploration (code search, file reading, analysis). */
+const EXPLORE_AGENT = {
+    name: "explore",
+    label: "Explore",
+    description: "Fast read-only codebase exploration. Search files, read code, analyze structure. Cannot write or execute.",
+    maxTurns: 50,
+    toolCapabilityProfile: "read_tools",
+    allowedTools: ["read_file", "search", "web_search", "web_fetch", "memory", "tool_search"],
+    canFork: false,
+    systemPromptSuffix: "You are READ-ONLY: never attempt to modify files or run mutating commands. " +
+        "Locate and understand code, then report concrete findings with file:line references. " +
+        "Read excerpts rather than whole files; surface conclusions, not raw dumps.",
+};
+/** Plan agent — read-only planning mode (explore + propose, no execution). */
+const PLAN_AGENT = {
+    name: "plan",
+    label: "Plan",
+    description: "Planning mode. Explore, analyze, and produce a structured plan. Cannot write files or execute commands.",
+    maxTurns: 80,
+    toolCapabilityProfile: "read_tools",
+    allowedTools: ["read_file", "search", "web_search", "web_fetch", "memory", "task", "tool_search"],
+    canFork: false,
+    systemPromptSuffix: "You PLAN but do not execute: never write files or run commands. " +
+        "Investigate enough to ground the plan in the real code, then return a concrete, " +
+        "step-by-step implementation plan naming the specific files and changes involved.",
+};
+/** Code agent — full execution capability for code tasks. */
+const CODE_AGENT = {
+    name: "code",
+    label: "Code",
+    description: "A coding sub-agent with full tool access for implementation tasks.",
+    maxTurns: 200,
+    toolCapabilityProfile: "all_tools",
+    canFork: true,
+    systemPromptSuffix: "Implement the task directly by editing files. Read existing code before changing it, " +
+        "match the surrounding conventions, and verify your change compiles/passes where possible.",
+};
+/** Research agent — web research and information gathering. */
+const RESEARCH_AGENT = {
+    name: "research",
+    label: "Research",
+    description: "Web research and information gathering. Searches the web, fetches pages, and synthesizes findings.",
+    maxTurns: 30,
+    toolCapabilityProfile: "read_tools",
+    allowedTools: ["web_search", "web_fetch", "read_file", "search", "memory"],
+    canFork: false,
+    systemPromptSuffix: "Gather information from multiple sources before concluding. Distinguish facts from " +
+        "inferences, cite where each claim comes from, and synthesize — do not just dump search results.",
+};
+/** Verification agent — runs tests and validates changes. */
+const VERIFY_AGENT = {
+    name: "verify",
+    label: "Verify",
+    description: "Verification agent. Runs tests, checks build output, validates changes are correct.",
+    maxTurns: 40,
+    toolCapabilityProfile: "all_tools",
+    allowedTools: ["exec", "read_file", "search"],
+    canFork: false,
+    systemPromptSuffix: "Verify by RUNNING things (tests, builds, type-checks) and reading the actual output — " +
+        "do not assume. Report a clear verdict (pass/fail) with the evidence that supports it.",
+};
+const BUILT_IN_AGENTS = [
+    GENERAL_PURPOSE_AGENT,
+    EXPLORE_AGENT,
+    PLAN_AGENT,
+    CODE_AGENT,
+    RESEARCH_AGENT,
+    VERIFY_AGENT,
+];
+/**
+ * Get the full list of built-in agent definitions.
+ */
+export function getBuiltInAgents() {
+    return [...BUILT_IN_AGENTS];
+}
+/**
+ * Look up a built-in agent by name.
+ */
+export function getBuiltInAgent(name) {
+    return BUILT_IN_AGENTS.find((a) => a.name === name);
+}
+/**
+ * Check if a given agent name is a built-in agent.
+ */
+export function isBuiltInAgent(name) {
+    return BUILT_IN_AGENTS.some((a) => a.name === name);
+}
+/**
+ * Resolve tool access for an agent definition.
+ * Returns the set of tool names the agent is allowed to use.
+ */
+export function resolveAgentToolSet(agent, availableTools) {
+    if (agent.allowedTools && agent.allowedTools.length > 0) {
+        const allowed = new Set(agent.allowedTools);
+        return availableTools.filter((t) => allowed.has(t));
+    }
+    if (agent.toolCapabilityProfile === "no_tools")
+        return [];
+    if (agent.toolCapabilityProfile === "read_tools") {
+        const writeTools = new Set([
+            "file_edit", "create_file", "write_file", "replace_string_in_file",
+            "multi_replace_string_in_file", "create_directory", "delete_file",
+            "rename_file", "move_file", "exec", "run_in_terminal", "run_command",
+            "git_commit", "git_push", "patch",
+        ]);
+        return availableTools.filter((t) => !writeTools.has(t));
+    }
+    // all_tools: a non-forking agent cannot spawn sub-agents or teams. The tool
+    // names are "agent" and "team" (the old "agent_tool"/"team_create" never matched).
+    if (!agent.canFork) {
+        return availableTools.filter((t) => t !== "agent" && t !== "team");
+    }
+    return [...availableTools];
+}

package/dist/orchestration/subagent/fork-subagent.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Fork Sub-Agent — CC-aligned fork mechanism for spawning child agents.
+ *
+ * Core design principles (aligned with Claude Code):
+ * 1. Child agent shares parent's message prefix (prompt cache hit)
+ * 2. Fork uses placeholder results to ensure byte-identical prefix across children
+ * 3. Child has independent tool context (doesn't pollute parent state)
+ * 4. Results flow back via AsyncGenerator (streaming backflow)
+ * 5. Depth control via in-memory counter (not DB-based)
+ */
+import type { AgentDefinition } from "./agent-registry.js";
+import { MAX_FORK_DEPTH } from "../../runtime/config/tunable-defaults.js";
+/** Sentinel tag injected into fork children to prevent recursive forking. */
+export declare const FORK_SENTINEL_TAG = "<fork-child-context>";
+/** Placeholder text used for all tool_results in shared prefix (ensures byte-identical prefix). */
+export declare const FORK_PLACEHOLDER_RESULT = "Fork started \u2014 processing in background";
+export { MAX_FORK_DEPTH };
+export interface ForkContext {
+    /** Parent's full message history (becomes shared prefix for cache). */
+    parentMessages: unknown[];
+    /** Parent's rendered system prompt (byte-exact for cache hit). */
+    systemPrompt: string;
+    /** Parent's full tool pool (useExactTools=true pattern). */
+    parentTools: string[];
+    /** Current fork depth (0 = root). */
+    depth: number;
+    /** Abort signal from parent. */
+    abortSignal?: AbortSignal;
+    /** Parent's agent ID for lineage tracking. */
+    parentAgentId: string;
+    /** Isolated worktree path for this fork child (CC team worktree parity). */
+    worktreePath?: string;
+}
+export interface ForkChildConfig {
+    /** The agent definition to run. */
+    agent: AgentDefinition;
+    /** Task-specific prompt for this child (the unique part after shared prefix). */
+    taskPrompt: string;
+    /** Optional override for max turns. */
+    maxTurns?: number;
+    /** Whether to run in background (async). */
+    isAsync?: boolean;
+}
+export interface ForkChildMessage {
+    role: "assistant" | "user" | "system";
+    content: unknown;
+    toolCalls?: unknown[];
+}
+export interface ForkResult {
+    /** Whether the fork completed successfully. */
+    ok: boolean;
+    /** Child's final output text (summary). */
+    output: string;
+    /** Messages produced by the child (for result backflow). */
+    messages: ForkChildMessage[];
+    /** Total tokens consumed by the child. */
+    tokensUsed: number;
+    /** Whether the child hit its turn limit. */
+    maxTurnsReached: boolean;
+    /** Child's agent ID. */
+    childAgentId: string;
+}
+/**
+ * Check if current context is inside a fork child (prevents recursive forking).
+ */
+export declare function isInForkChild(messages: unknown[]): boolean;
+/**
+ * Check if fork depth allows spawning another child.
+ */
+export declare function canForkAtDepth(currentDepth: number): boolean;
+/**
+ * Build forked messages that ensure byte-identical prefix across all fork children.
+ *
+ * Strategy (aligned with CC's buildForkedMessages):
+ * 1. Keep full parent message history (all tool_use blocks, thinking, text)
+ * 2. Replace all pending tool_results with FORK_PLACEHOLDER_RESULT
+ * 3. Append a single user message with the child-specific directive
+ * → All children share the same prefix up to the directive → maximum cache hits.
+ */
+export declare function buildForkedMessages(context: ForkContext, childConfig: ForkChildConfig): unknown[];
+/**
+ * Build placeholder tool results for the shared prefix.
+ * When parent has pending tool_calls, replace them all with identical placeholder text
+ * so all fork children produce byte-identical API request prefix.
+ */
+export declare function buildForkPlaceholderResults(pendingToolCallIds: string[]): Array<{
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+}>;
+/**
+ * Resolve the effective tool set for a fork child.
+ * CC pattern: useExactTools=true → child gets parent's full tool pool,
+ * then filtered by agent definition.
+ */
+export declare function resolveForkChildTools(parentTools: string[], agent: AgentDefinition): string[];
+/**
+ * Generate a unique agent ID for a fork child.
+ */
+export declare function generateForkChildAgentId(parentAgentId: string, agentName: string, depth: number): string;

package/dist/orchestration/subagent/fork-subagent.js

@@ -0,0 +1,101 @@
+/**
+ * Fork Sub-Agent — CC-aligned fork mechanism for spawning child agents.
+ *
+ * Core design principles (aligned with Claude Code):
+ * 1. Child agent shares parent's message prefix (prompt cache hit)
+ * 2. Fork uses placeholder results to ensure byte-identical prefix across children
+ * 3. Child has independent tool context (doesn't pollute parent state)
+ * 4. Results flow back via AsyncGenerator (streaming backflow)
+ * 5. Depth control via in-memory counter (not DB-based)
+ */
+import { MAX_FORK_DEPTH } from "../../runtime/config/tunable-defaults.js";
+/** Sentinel tag injected into fork children to prevent recursive forking. */
+export const FORK_SENTINEL_TAG = "<fork-child-context>";
+/** Placeholder text used for all tool_results in shared prefix (ensures byte-identical prefix). */
+export const FORK_PLACEHOLDER_RESULT = "Fork started \u2014 processing in background";
+export { MAX_FORK_DEPTH };
+/**
+ * Check if current context is inside a fork child (prevents recursive forking).
+ */
+export function isInForkChild(messages) {
+    return JSON.stringify(messages).includes(FORK_SENTINEL_TAG);
+}
+/**
+ * Check if fork depth allows spawning another child.
+ */
+export function canForkAtDepth(currentDepth) {
+    return currentDepth < MAX_FORK_DEPTH;
+}
+/**
+ * Build forked messages that ensure byte-identical prefix across all fork children.
+ *
+ * Strategy (aligned with CC's buildForkedMessages):
+ * 1. Keep full parent message history (all tool_use blocks, thinking, text)
+ * 2. Replace all pending tool_results with FORK_PLACEHOLDER_RESULT
+ * 3. Append a single user message with the child-specific directive
+ * → All children share the same prefix up to the directive → maximum cache hits.
+ */
+export function buildForkedMessages(context, childConfig) {
+    const messages = [...context.parentMessages];
+    // Inject fork sentinel + child task as the unique tail.
+    // If the child has an isolated worktree, include cwd context so file operations
+    // resolve relative to the worktree (CC team worktree parity).
+    const worktreeCtx = context.worktreePath
+        ? `\n\nYour working directory is: ${context.worktreePath}\nAll file paths should be relative to this directory.`
+        : "";
+    const childDirective = {
+        role: "user",
+        content: [
+            { type: "text", text: `${FORK_SENTINEL_TAG}\n\nYou are the "${childConfig.agent.name}" agent.${worktreeCtx}\n\n${childConfig.taskPrompt}` },
+        ],
+    };
+    messages.push(childDirective);
+    return messages;
+}
+/**
+ * Build placeholder tool results for the shared prefix.
+ * When parent has pending tool_calls, replace them all with identical placeholder text
+ * so all fork children produce byte-identical API request prefix.
+ */
+export function buildForkPlaceholderResults(pendingToolCallIds) {
+    return pendingToolCallIds.map((id) => ({
+        role: "tool",
+        tool_call_id: id,
+        content: FORK_PLACEHOLDER_RESULT,
+    }));
+}
+/**
+ * Resolve the effective tool set for a fork child.
+ * CC pattern: useExactTools=true → child gets parent's full tool pool,
+ * then filtered by agent definition.
+ */
+export function resolveForkChildTools(parentTools, agent) {
+    if (agent.allowedTools && agent.allowedTools.length > 0) {
+        const allowed = new Set(agent.allowedTools);
+        return parentTools.filter((t) => allowed.has(t));
+    }
+    if (agent.toolCapabilityProfile === "no_tools")
+        return [];
+    if (agent.toolCapabilityProfile === "read_tools") {
+        const writeTools = new Set([
+            "file_edit", "create_file", "write_file", "replace_string_in_file",
+            "multi_replace_string_in_file", "create_directory", "delete_file",
+            "rename_file", "move_file", "exec", "run_in_terminal", "run_command",
+            "git_commit", "git_push", "patch",
+        ]);
+        return parentTools.filter((t) => !writeTools.has(t));
+    }
+    // all_tools: a non-forking child cannot spawn further sub-agents OR teams
+    // (both would recurse/fan-out resources past the intended single-level fork).
+    if (!agent.canFork) {
+        return parentTools.filter((t) => t !== "agent" && t !== "team");
+    }
+    return [...parentTools];
+}
+/**
+ * Generate a unique agent ID for a fork child.
+ */
+export function generateForkChildAgentId(parentAgentId, agentName, depth) {
+    const ts = Date.now().toString(36);
+    return `${parentAgentId}:fork:${agentName}:d${depth}:${ts}`;
+}

package/dist/orchestration/subagent/task-types.d.ts

@@ -0,0 +1 @@
+export * from "../../runtime/tasks/task-types.js";

package/dist/orchestration/subagent/task-types.js

@@ -0,0 +1 @@
+export * from "../../runtime/tasks/task-types.js";