catui-agent 1.0.0-beta.0

package/dist/core/sub-agent/agent-registry.d.ts

@@ -0,0 +1,145 @@
+/**
+ * [WHO]: AgentDefinitionRegistry — agent name registry, definition cache, lookup
+ * [FROM]: Depends on ./agent-definition for AgentDefinition, BUILT_IN_AGENT_DEFINITIONS
+ * [TO]: Consumed by ./agent-tool, ./index.ts, extensions/builtin/subagent/*
+ * [HERE]: core/sub-agent/agent-registry.ts - Agent registration and lookup per CC §XIV
+ * [COVENANT]: Change registry shape → update P2 AGENT.md member list
+ */
+import type { AgentDefinition } from "./agent-definition.js";
+/**
+ * Manages agent definitions and the name→agentId mapping.
+ *
+ * Per CC §XIV:
+ * - agentDefinitions has activeAgents (currently usable) and allAgents (including disabled)
+ * - agentNameRegistry maps name → agentId for SendMessage routing
+ * - Definitions are loaded at startup, config change, and plugin load
+ * - Sources: built-in, plugin, user custom (.catui/agents/*.md)
+ */
+export declare class AgentDefinitionRegistry {
+    /** Currently active (usable) agent definitions */
+    private activeAgents;
+    /** All agent definitions (including disabled/filtered) */
+    private allAgents;
+    /** Name → agentId mapping (for SendMessage routing and name-based lookup) */
+    private agentNameRegistry;
+    /** Failed agent definition files (for error reporting) */
+    private failedFiles;
+    /** Path for persisting agentNameRegistry to disk (CC §XIV, §18.6) */
+    private persistencePath;
+    /** Project cwd for loading custom agent definitions from .catui/agents/ */
+    private cwd;
+    /** Global agent config directory for user-scoped agent definitions */
+    private agentDir;
+    /**
+     * @param persistencePath Optional path for agentNameRegistry JSON persistence.
+     *   Per CC §14.1, the name registry is persisted so it survives process restarts.
+     *   Typical: join(cwd, ".catui", "agent-registry.json")
+     */
+    constructor(persistencePath?: string);
+    /**
+     * Reload all agent definitions from all sources.
+     * Called at startup, config change, and plugin load (CC §XIV).
+     */
+    reload(): void;
+    /**
+     * Resolve an agent type name to its definition.
+     * Matches CC's resolveAgentType (Mq8) function.
+     *
+     * @param subagentType The agent type to look up (e.g. "Explore", "general-purpose")
+     * @returns The matching AgentDefinition, or undefined if not found
+     */
+    resolve(subagentType: string): AgentDefinition | undefined;
+    /**
+     * Resolve an agent type, throwing if not found or denied.
+     * Matches CC's agent type resolution path (§VI step 5).
+     *
+     * @param subagentType The agent type to look up
+     * @param deniedTypes Optional set of agent types denied by permission rules
+     * @returns The matching AgentDefinition
+     * @throws Error if agent type not found or denied
+     */
+    resolveOrThrow(subagentType: string, deniedTypes?: ReadonlySet<string>): AgentDefinition;
+    /**
+     * Get the default fork agent definition.
+     * Used when subagent_type is not specified (CC §VI step 5).
+     */
+    getDefaultForkAgent(): AgentDefinition;
+    /**
+     * Register a name → agentId mapping.
+     * Used by the Agent tool when a `name` parameter is provided.
+     * This allows SendMessage({to: name}) to address a running agent.
+     * Persists to disk if persistencePath is configured (CC §18.6).
+     */
+    registerAgentName(name: string, agentId: string): void;
+    /**
+     * Find an agent by its registered name.
+     * Used by SendMessage routing.
+     */
+    findAgentByName(name: string): string | undefined;
+    /**
+     * Remove a name registration (when the agent completes).
+     * Persists to disk if persistencePath is configured (CC §18.6).
+     */
+    unregisterAgentName(name: string): void;
+    /**
+     * Load agentNameRegistry from disk.
+     * Called during reload(). Silently ignores missing or corrupt files.
+     */
+    private loadNameRegistry;
+    /**
+     * Persist agentNameRegistry to disk.
+     * Called on every register/unregister. Errors are logged but not thrown.
+     */
+    private saveNameRegistry;
+    /** Get the current persistence path (if configured). */
+    getPersistencePath(): string | undefined;
+    /** Configure directories for custom agent loading and trigger async reload. */
+    configureDirectories(cwd: string, agentDir: string): Promise<void>;
+    /** Load custom agent definitions from configured directories (async). */
+    loadCustomAgents(): Promise<void>;
+    /**
+     * Set or update the persistence path for agentNameRegistry.
+     * Called from createAgentTool when the parent session's cwd is known.
+     * If the registry already has entries (from a previous session), they are
+     * preserved; only the path is updated for future saves.
+     */
+    setPersistencePath(path: string): void;
+    /**
+     * Register a custom agent definition (from plugin or user settings).
+     * Per CC §XIV, definitions can come from:
+     * - Plugin definitions (ao6)
+     * - User custom agents (.catui/agents/*.md)
+     * - Flag / settings overrides
+     */
+    registerCustomAgent(definition: AgentDefinition): void;
+    /**
+     * Remove a custom agent definition.
+     */
+    unregisterCustomAgent(agentType: string): void;
+    /** Get all currently active agent type names. */
+    getActiveAgentTypes(): string[];
+    /** Get all active agent definitions. */
+    getActiveDefinitions(): AgentDefinition[];
+    /** Get all agent definitions (including inactive). */
+    getAllDefinitions(): AgentDefinition[];
+    /** Get failed file entries (for error reporting). */
+    getFailedFiles(): Array<{
+        path: string;
+        error: string;
+    }>;
+    /** Get the name registry (for SendMessage). */
+    getNameRegistry(): Map<string, string>;
+    /**
+     * Record a failed agent definition file.
+     * Used during loading when a .md or .json file fails to parse.
+     */
+    recordFailedFile(path: string, error: string): void;
+    /** Whether an agent definition is a built-in type. */
+    isBuiltIn(agentType: string): boolean;
+}
+/**
+ * Default global agent definition registry instance.
+ * Per CC §XIV, this is maintained in AppState and refreshed at
+ * startup, config change, and plugin load.
+ */
+export declare const agentDefinitionRegistry: AgentDefinitionRegistry;

package/dist/core/sub-agent/agent-registry.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var n=(r,e)=>g(r,"name",{value:e,configurable:!0});import{BUILT_IN_AGENT_DEFINITIONS as a,DEFAULT_FORK_AGENT as h}from"./agent-definition.js";import{loadCustomAgentDefinitions as o}from"./agent-definition-loader.js";import{readFile as c,writeFile as l,mkdir as A}from"node:fs/promises";class f{static{n(this,"AgentDefinitionRegistry")}activeAgents=new Map;allAgents=new Map;agentNameRegistry=new Map;failedFiles=[];persistencePath;cwd;agentDir;constructor(e){this.persistencePath=e,this.reload()}reload(){this.activeAgents.clear(),this.allAgents.clear(),this.failedFiles=[];for(const[e,t]of a)this.allAgents.set(e,t),this.activeAgents.set(e,t);this.loadNameRegistry()}resolve(e){return this.activeAgents.get(e)}resolveOrThrow(e,t){const s=this.activeAgents.get(e);if(!s)throw new Error(`Agent type '${e}' not found. Available types: ${this.getActiveAgentTypes().join(", ")}`);if(t?.has(e))throw new Error(`Agent type '${e}' has been denied by permission rules.`);return s}getDefaultForkAgent(){return h}registerAgentName(e,t){this.agentNameRegistry.set(e,t),this.saveNameRegistry()}findAgentByName(e){return this.agentNameRegistry.get(e)}unregisterAgentName(e){this.agentNameRegistry.delete(e),this.saveNameRegistry()}loadNameRegistry(){this.persistencePath&&c(this.persistencePath,"utf-8").then(e=>{try{const t=JSON.parse(e);if(t&&typeof t=="object"&&!Array.isArray(t)){this.agentNameRegistry.clear();for(const[s,i]of Object.entries(t))typeof s=="string"&&typeof i=="string"&&this.agentNameRegistry.set(s,i)}}catch{}}).catch(()=>{})}saveNameRegistry(){if(!this.persistencePath)return;const e={};for(const[s,i]of this.agentNameRegistry)e[s]=i;const t=this.persistencePath.replace(/[/\\][^/\\]+$/,"");A(t,{recursive:!0}).then(()=>l(this.persistencePath,JSON.stringify(e,null,2),"utf-8")).catch(()=>{})}getPersistencePath(){return this.persistencePath}async configureDirectories(e,t){this.cwd=e,this.agentDir=t,await this.loadCustomAgents()}async loadCustomAgents(){if(!(!this.cwd||!this.agentDir))try{const e=await o(this.cwd,this.agentDir);for(const t of e.definitions)this.allAgents.set(t.agentType,t),this.activeAgents.set(t.agentType,t);this.failedFiles.push(...e.failedFiles)}catch{}}setPersistencePath(e){this.persistencePath=e,this.loadNameRegistry()}registerCustomAgent(e){this.allAgents.set(e.agentType,e),this.activeAgents.set(e.agentType,e)}unregisterCustomAgent(e){this.activeAgents.delete(e),this.allAgents.delete(e)}getActiveAgentTypes(){return Array.from(this.activeAgents.keys())}getActiveDefinitions(){return Array.from(this.activeAgents.values())}getAllDefinitions(){return Array.from(this.allAgents.values())}getFailedFiles(){return[...this.failedFiles]}getNameRegistry(){return new Map(this.agentNameRegistry)}recordFailedFile(e,t){this.failedFiles.push({path:e,error:t})}isBuiltIn(e){return a.has(e)}}const p=new f;export{f as AgentDefinitionRegistry,p as agentDefinitionRegistry};

package/dist/core/sub-agent/agent-result-extractor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * [WHO]: extractAgentResult, truncateResult — result extraction and truncation per CC §11.2 (VS8)
+ * [FROM]: Depends on @catui/agent-core for AgentMessage, ./agent-definition for MAX_RESULT_SIZE_CHARS
+ * [TO]: Consumed by ./agent-tool
+ * [HERE]: core/sub-agent/agent-result-extractor.ts - Sub-agent result extraction
+ */
+import type { AgentMessage } from "@catui/agent-core";
+import type { AgentOutputCompleted, AgentSpawnMetadata, AgentUsage } from "./agent-input-output.js";
+/**
+ * Extract the result from a completed sub-agent run.
+ * Matches CC's VS8 function exactly.
+ *
+ * Per CC §11.2:
+ * 1. Find the last assistant message
+ * 2. Extract text content from it
+ * 3. If last message has no text, search backwards for one that does
+ * 4. Calculate totals (tokens, tool use count, duration)
+ * 5. Truncate at maxResultSizeChars (100,000)
+ */
+export declare function extractAgentResult(messages: AgentMessage[], agentId: string, metadata: AgentSpawnMetadata): AgentOutputCompleted;
+/**
+ * Truncate result content to maxResultSizeChars.
+ * Per CC §VI step 14: maxResultSizeChars = 100,000 (1e5).
+ */
+export declare function truncateResult(result: AgentOutputCompleted, maxChars?: number): AgentOutputCompleted;
+export declare function calculateTotalTokens(messages: AgentMessage[]): number;
+export declare function calculateTotalToolUseCount(messages: AgentMessage[]): number;
+export declare function calculateUsage(messages: AgentMessage[]): AgentUsage;

package/dist/core/sub-agent/agent-result-extractor.js

@@ -0,0 +1,3 @@
+var x=Object.defineProperty;var u=(e,t)=>x(e,"name",{value:t,configurable:!0});import{MAX_RESULT_SIZE_CHARS as _}from"./agent-definition.js";function C(e,t,o){const n=g(e);let i;if(n?i=f(n):i=[],i.length===0)for(let s=e.length-1;s>=0;s--){const a=e[s];if(a.role!=="assistant")continue;const l=f(a);if(l.length>0){i=l;break}}const r=h(e),c=T(e),p=k(e);return{agentId:t,agentType:o.agentType,content:i,totalToolUseCount:c,totalDurationMs:Date.now()-o.startTime,totalTokens:r,usage:p,status:"completed",prompt:o.prompt}}u(C,"extractAgentResult");function A(e,t=_){if(e.content.reduce((r,c)=>r+c.text.length,0)<=t)return e;let n=t;const i=e.content.map(r=>{if(n<=0)return{type:"text",text:""};if(r.text.length<=n)return n-=r.text.length,r;const c=r.text.slice(0,n)+`
+
+[Result truncated due to size limit]`;return n=0,{type:"text",text:c}});return{...e,content:i.filter(r=>r.text.length>0)}}u(A,"truncateResult");function g(e){for(let t=e.length-1;t>=0;t--)if(e[t].role==="assistant")return e[t]}u(g,"findLastAssistantMessage");function f(e){const t=e.content;return t?typeof t=="string"?[{type:"text",text:t}]:Array.isArray(t)?t.filter(o=>o.type==="text"&&typeof o.text=="string").map(o=>({type:"text",text:o.text})):[]:[]}u(f,"extractTextContentFromMessage");function h(e){let t=0;for(const o of e)if(o.role==="assistant"){const n=o.usage;n&&(t+=n.total_tokens??(n.input??0)+(n.output??0))}return t}u(h,"calculateTotalTokens");function T(e){let t=0;for(const o of e)if(o.role==="assistant"){const n=o.content;Array.isArray(n)&&(t+=n.filter(i=>i.type==="toolCall").length)}return t}u(T,"calculateTotalToolUseCount");function k(e){let t=0,o=0,n=0,i=0;for(const r of e)if(r.role==="assistant"){const c=r.usage;c&&(t+=c.input??0,o+=c.output??0,n+=c.cacheCreation??c.cache_creation_input_tokens??0,i+=c.cacheRead??c.cache_read_input_tokens??0)}return{input_tokens:t,output_tokens:o,cache_creation_input_tokens:n||null,cache_read_input_tokens:i||null,server_tool_use:null,service_tier:null,cache_creation:null}}u(k,"calculateUsage");export{h as calculateTotalTokens,T as calculateTotalToolUseCount,k as calculateUsage,C as extractAgentResult,A as truncateResult};

package/dist/core/sub-agent/agent-telemetry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * [WHO]: Provides emitAgentSelected, emitAgentCompleted, emitAgentAutoModeDecision, emitAgentMemoryLoaded —
+ *         structured telemetry events for the Agent tool (CC §XVI: tengu_agent_tool_selected / _completed / _auto_mode_decision / _memory_loaded)
+ * [FROM]: Depends on core/runtime/logger (structured logging), core/platform/telemetry types (future insforge sink)
+ * [TO]: Consumed by ./agent-tool.ts (execute paths) and ./agent-handoff-safety.ts (auto mode decision)
+ * [HERE]: core/sub-agent/agent-telemetry.ts — telemetry emission module, mirrors CC's `d()` analytics function
+ */
+/** CC: d("tengu_agent_tool_selected", {...}) */
+export interface AgentSelectedEvent {
+    agent_type: string;
+    model: string;
+    source: string;
+    color?: string;
+    is_built_in_agent: boolean;
+    is_resume: boolean;
+    is_async: boolean;
+    is_fork: boolean;
+}
+/** CC: d("tengu_agent_tool_completed", {...}) */
+export interface AgentCompletedEvent {
+    agent_type: string;
+    model: string;
+    prompt_char_count: number;
+    response_char_count: number;
+    assistant_message_count: number;
+    total_tool_use_count: number;
+    duration_ms: number;
+    total_tokens: number;
+    is_built_in_agent: boolean;
+    is_async: boolean;
+}
+/** CC: d("tengu_auto_mode_decision", {...}) */
+export interface AgentAutoModeDecisionEvent {
+    decision: "blocked" | "allowed";
+    toolName: string;
+    subagentType: string;
+    toolUseCount: number;
+    isHandoff: boolean;
+}
+/** CC: d("tengu_agent_memory_loaded", {...}) */
+export interface AgentMemoryLoadedEvent {
+    scope: string;
+    source: string;
+}
+/**
+ * Emit telemetry for agent tool selection (CC §XVI: tengu_agent_tool_selected).
+ * Called at the start of executeSync / executeAsync, after agent definition is resolved.
+ */
+export declare function emitAgentSelected(event: AgentSelectedEvent): void;
+/**
+ * Emit telemetry for agent tool completion (CC §XVI: tengu_agent_tool_completed).
+ * Called after executeSync / executeAsync produces a result.
+ */
+export declare function emitAgentCompleted(event: AgentCompletedEvent): void;
+/**
+ * Emit telemetry for auto-mode handoff decision (CC §XVI: tengu_auto_mode_decision).
+ * Called when checkHandoffSafety makes a decision in auto mode.
+ */
+export declare function emitAgentAutoModeDecision(event: AgentAutoModeDecisionEvent): void;
+/**
+ * Emit telemetry for agent memory loading (CC §XVI: tengu_agent_memory_loaded).
+ * Called when agent definition memory is resolved.
+ */
+export declare function emitAgentMemoryLoaded(event: AgentMemoryLoadedEvent): void;
+/**
+ * Inject an EventBus for telemetry forwarding. Called during runtime init
+ * when the EventBus is available. Without injection, telemetry is logger-only.
+ */
+export declare function setAgentTelemetryEventBus(bus: {
+    emit(channel: string, data: unknown): void;
+}): void;

package/dist/core/sub-agent/agent-telemetry.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var o=(e,s)=>a(e,"name",{value:s,configurable:!0});import{createLogger as c}from"../platform/utils/logger.js";const t=c({component:"agent-telemetry",level:"debug"});function r(e){t.debug(`[agent-telemetry] tengu_agent_tool_selected: type=${e.agent_type} model=${e.model} source=${e.source} async=${e.is_async} fork=${e.is_fork} built_in=${e.is_built_in_agent}`),n("agent:tool_selected",e)}o(r,"emitAgentSelected");function g(e){t.debug(`[agent-telemetry] tengu_agent_tool_completed: type=${e.agent_type} model=${e.model} duration=${e.duration_ms}ms tokens=${e.total_tokens} tools=${e.total_tool_use_count} prompt_chars=${e.prompt_char_count} response_chars=${e.response_char_count} async=${e.is_async}`),n("agent:tool_completed",e)}o(g,"emitAgentCompleted");function i(e){t.debug(`[agent-telemetry] tengu_auto_mode_decision: decision=${e.decision} subagentType=${e.subagentType} toolUseCount=${e.toolUseCount} isHandoff=${e.isHandoff}`),n("agent:auto_mode_decision",e)}o(i,"emitAgentAutoModeDecision");function m(e){t.debug(`[agent-telemetry] tengu_agent_memory_loaded: scope=${e.scope} source=${e.source}`),n("agent:memory_loaded",e)}o(m,"emitAgentMemoryLoaded");let _=null;function d(e){_=e}o(d,"setAgentTelemetryEventBus");function n(e,s){try{_?.emit(e,s)}catch{}}o(n,"_emitToEventBus");export{i as emitAgentAutoModeDecision,g as emitAgentCompleted,m as emitAgentMemoryLoaded,r as emitAgentSelected,d as setAgentTelemetryEventBus};

package/dist/core/sub-agent/agent-tool-filter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * [WHO]: filterToolsForAgent, resolveAgentModel, isReadOnlyTool, getToolDescriptionsForAgent
+ * [FROM]: Depends on ./agent-definition for AgentDefinition, AgentPermissionMode, core/tools for Tool
+ * [TO]: Consumed by ./agent-tool, extensions/builtin/subagent/*
+ * [HERE]: core/sub-agent/agent-tool-filter.ts - Tool filtering and model resolution per CC §IX, §XVIII.2
+ * [COVENANT]: Change filter logic → update agent-tool handler
+ */
+import type { AgentTool } from "@catui/agent-core";
+import type { AgentDefinition, AgentPermissionMode } from "./agent-definition.js";
+import type { Model } from "@catui/ai/types";
+import type { ModelRegistry } from "../model-registry.js";
+/**
+ * Filter the parent's tool set for a sub-agent.
+ *
+ * Per CC §IX:
+ * - If agentDef.tools === ["*"] → inherit all parent tools (with exact match for fork)
+ * - If agentDef.tools is a whitelist → only include listed tools
+ * - If agentDef.disallowedTools is set → remove those from parent tools
+ * - Permission mode "plan" → filter to read-only tools only
+ * - MCP tools are added after permission filtering
+ *
+ * @param agentDef The agent definition controlling tool access
+ * @param parentTools The parent session's available tools
+ * @param permissionMode Permission context for the sub-agent
+ * @param mcpTools Additional MCP tools to include
+ * @param isFork Whether this is a fork agent (uses exact parent tools, no re-filtering)
+ * @returns The filtered tool set for the sub-agent
+ */
+export declare function filterToolsForAgent(agentDef: AgentDefinition, parentTools: AgentTool[], permissionMode: AgentPermissionMode, mcpTools?: AgentTool[], isFork?: boolean): AgentTool[];
+/**
+ * Check if a tool is read-only (non-destructive).
+ * Used by plan mode to filter tools.
+ *
+ * Per CC §IX:
+ * - Plan mode only allows read-only tools
+ * - Read, Grep, Find, Ls, Time are read-only
+ * - Bash, Edit, Write are NOT read-only
+ * - Agent (sub-agent spawning) is NOT read-only
+ */
+export declare function isReadOnlyTool(tool: AgentTool): boolean;
+/**
+ * Check if a tool is the Agent tool (sub-agent spawning).
+ * Used to prevent recursive agent spawning in certain agent types.
+ */
+export declare function isAgentTool(tool: AgentTool): boolean;
+/**
+ * Check if a tool is a read tool (for canReadOutputFile in async output).
+ */
+export declare function isReadTool(tool: AgentTool): boolean;
+/**
+ * Check if a tool is a bash tool (for canReadOutputFile in async output).
+ */
+export declare function isBashTool(tool: AgentTool): boolean;
+/**
+ * Resolve the model for a sub-agent.
+ *
+ * Per CC §VI step 7 (JE6 equivalent):
+ * Priority: user override > agent definition model > parent model.
+ *
+ * Special values:
+ * - "inherit" or undefined → use parent model
+ * - "haiku"/"sonnet"/"opus" → resolve to the corresponding model tier
+ * - Any other string → try to find a matching model by id or name substring
+ *
+ * @param agentDefModel Model specified in the agent definition
+ * @param parentModel The parent session's current model
+ * @param userOverride User-specified model override (from Agent tool call)
+ * @param modelRegistry For resolving tier names to concrete models
+ * @returns The resolved model to use
+ */
+export declare function resolveAgentModel(agentDefModel: string | undefined, parentModel: Model<any> | undefined, userOverride: string | undefined, modelRegistry?: ModelRegistry): Model<any> | undefined;
+/**
+ * Build tool descriptions for the sub-agent's system prompt.
+ * Only includes descriptions for tools the agent actually has access to.
+ */
+export declare function getToolDescriptionsForAgent(tools: AgentTool[], toolGuidance: Record<string, string>): string;
+/**
+ * Determine the permission context for a sub-agent.
+ *
+ * Per CC §XII.2:
+ * - Agent definition can override permission mode
+ * - But cannot be more permissive than the parent
+ * - Default: "acceptEdits" if not specified
+ *
+ * @param parentMode Parent's permission mode
+ * @param agentDefMode Agent definition's permission mode override
+ * @returns The resolved permission mode (no more permissive than parent)
+ */
+export declare function resolvePermissionMode(parentMode: AgentPermissionMode | undefined, agentDefMode: AgentPermissionMode | undefined): AgentPermissionMode;

package/dist/core/sub-agent/agent-tool-filter.js

@@ -0,0 +1,2 @@
+var u=Object.defineProperty;var i=(e,n)=>u(e,"name",{value:n,configurable:!0});function p(e,n,s,r=[],t=!1){if(t)return[...n];let o=[...n];if(e.tools&&e.tools.length>0)if(e.tools.includes("*"))o=[...n];else{const a=new Set(e.tools),l=new Set(Array.from(a.values()).map(c=>c.toLowerCase()));o=o.filter(c=>l.has(c.name.toLowerCase()))}if(e.disallowedTools&&e.disallowedTools.length>0){const a=new Set(Array.from(e.disallowedTools.values()).map(l=>l.toLowerCase()));o=o.filter(l=>!a.has(l.name.toLowerCase()))}return s==="plan"&&(o=o.filter(a=>f(a))),o.push(...r),o}i(p,"filterToolsForAgent");function f(e){const n=new Set(["read","grep","find","ls","time","Read","Grep","Glob","Find","Ls","Time"]);return n.has(e.name)||n.has(e.name.toLowerCase())}i(f,"isReadOnlyTool");function w(e){return e.name==="Agent"||e.name==="agent"||e.name==="Task"||e.name==="task"}i(w,"isAgentTool");function h(e){return e.name==="Read"||e.name==="read"}i(h,"isReadTool");function x(e){return e.name==="Bash"||e.name==="bash"}i(x,"isBashTool");function d(e,n){if(!n)return;const s=n.getAvailable();if(s.length===0)return;const r=e.toLowerCase(),t=s.find(o=>o.id===e);return t||s.find(o=>o.id.toLowerCase().includes(r)||o.name.toLowerCase().includes(r))}i(d,"resolveModelFromSpecifier");function L(e,n,s,r){if(s){const t=d(s,r);if(t)return t}if(e&&e!=="inherit"){const t=d(e,r);if(t)return t}return n}i(L,"resolveAgentModel");function T(e,n){const s=[];for(const r of e){const t=n[r.name]??n[r.name.toLowerCase()];t&&s.push(`- ${r.name}: ${t}`)}return s.join(`
+`)}i(T,"getToolDescriptionsForAgent");function A(e,n){const s=n??e??"acceptEdits",r=["plan","dontAsk","acceptEdits","default","auto","bypassPermissions"],t=r.indexOf(e??"acceptEdits");return r.indexOf(s)>t?e??"acceptEdits":s}i(A,"resolvePermissionMode");export{p as filterToolsForAgent,T as getToolDescriptionsForAgent,w as isAgentTool,x as isBashTool,f as isReadOnlyTool,h as isReadTool,L as resolveAgentModel,A as resolvePermissionMode};

package/dist/core/sub-agent/agent-tool.d.ts

@@ -0,0 +1,69 @@
+/**
+ * [WHO]: createAgentTool, createTaskToolAlias — the "Agent" / "Task" tool for LLM invocation
+ * [FROM]: Depends on @catui/agent-core ( @sinclair/typebox, ./agent-definition, ./agent-input-output, ./agent-registry, ./agent-tool-filter, ./sub-agent-backend
+ * [TO]: Consumed by core/tools/index.ts ( tool registration ), core/runtime/agent-session.ts
+ * [HERE]: core/sub-agent/agent-tool.ts - The Agent tool implementation per CC §VI (full spawn flow)
+ * [COVENANT]: Change tool schema → update agent-input-output.ts
+ */
+import type { AgentTool } from "@catui/agent-core";
+import type { Model } from "@catui/ai/types";
+import { type Static } from "@sinclair/typebox";
+import type { ModelRegistry } from "../model-registry.js";
+import type { AgentPermissionMode } from "./agent-definition.js";
+import type { AgentDefinitionRegistry } from "./agent-registry.js";
+import type { CreateSessionFn } from "./sub-agent-backend.js";
+import type { SubAgentEvent } from "./sub-agent-types.js";
+import { WorktreeManager } from "../workspace/index.js";
+import type { AgentSession } from "../runtime/agent-session.js";
+export declare const AGENT_TOOL_NAME = "Agent";
+export declare const TASK_TOOL_NAME = "Task";
+declare const agentSchema: import("@sinclair/typebox").TObject<{
+    description: import("@sinclair/typebox").TString;
+    prompt: import("@sinclair/typebox").TString;
+    subagent_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"sonnet">, import("@sinclair/typebox").TLiteral<"opus">, import("@sinclair/typebox").TLiteral<"haiku">, import("@sinclair/typebox").TString]>>;
+    run_in_background: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"acceptEdits">, import("@sinclair/typebox").TLiteral<"auto">, import("@sinclair/typebox").TLiteral<"bypassPermissions">, import("@sinclair/typebox").TLiteral<"default">, import("@sinclair/typebox").TLiteral<"dontAsk">, import("@sinclair/typebox").TLiteral<"plan">]>>;
+    isolation: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TLiteral<"worktree">>;
+}>;
+export type AgentToolInput = Static<typeof agentSchema>;
+export interface AgentToolConfig {
+    /** The parent AgentSession (for inheriting model, prompt, messages) */
+    parentSession: AgentSession;
+    /** The parent session's current permission mode */
+    parentPermissionMode: AgentPermissionMode;
+    /** The parent session's model */
+    parentModel?: Model<any>;
+    /** Agent definition registry (for looking up agent types) */
+    registry?: AgentDefinitionRegistry;
+    /** Worktree manager (for isolation mode) */
+    worktreeManager?: WorktreeManager;
+    /** Whether background tasks are disabled (CC: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS) */
+    disableBackgroundTasks?: boolean;
+    /** Whether this agent is already a fork worker (prevents recursive fork) */
+    isForkWorker?: boolean;
+    /** Whether this agent is in a team context */
+    isTeamContext?: boolean;
+    /** Whether this agent is an in-process teammate */
+    isInProcessTeam?: boolean;
+    /** MCP tools available to sub-agents */
+    mcpTools?: AgentTool[];
+    /** Auto-background threshold override (default: 2 minutes) */
+    autoBackgroundMs?: number;
+    /** Tool use context for system prompt building */
+    toolUseContext?: unknown;
+    /** Callback for forwarding sub-agent events to parent's UI */
+    onSubAgentEvent?: (event: SubAgentEvent) => void;
+    /** Model registry for resolving tier names to concrete models (CC §VI step 7) */
+    modelRegistry?: ModelRegistry;
+    /** Factory for creating AgentSession instances (injected to avoid cycle with runtime/sdk) */
+    createSession: CreateSessionFn;
+}
+export declare function createAgentTool(config: AgentToolConfig): AgentTool<typeof agentSchema>;
+/**
+ * Create the Task tool alias (CC: eI="Task" is an alias for Agent).
+ * Same functionality, different name.
+ */
+export declare function createTaskToolAlias(config: AgentToolConfig): AgentTool<typeof agentSchema>;
+export {};

package/dist/core/sub-agent/agent-tool.js

@@ -0,0 +1,11 @@
+var q=Object.defineProperty;var l=(e,t)=>q(e,"name",{value:t,configurable:!0});import{Type as a}from"@sinclair/typebox";import{DEFAULT_FORK_AGENT as G,MAX_RESULT_SIZE_CHARS as P,AUTO_BACKGROUND_THRESHOLD_MS as K}from"./agent-definition.js";import{isAgentOutputCompleted as z}from"./agent-input-output.js";import{agentDefinitionRegistry as J}from"./agent-registry.js";import{filterToolsForAgent as Y,resolvePermissionMode as X,isReadTool as D,isBashTool as U}from"./agent-tool-filter.js";import{InProcessSubAgentBackend as Z}from"./sub-agent-backend.js";import{WorktreeManager as L}from"../workspace/index.js";import{truncateResult as $}from"./agent-result-extractor.js";import{checkHandoffSafety as Q,checkRecursionLimits as V}from"./agent-handoff-safety.js";import{emitAgentSelected as ee,emitAgentCompleted as te,emitAgentMemoryLoaded as ne}from"./agent-telemetry.js";import{getOutputFilePath as N,writeAgentOutputFile as R,writeAgentOutputCompleted as B}from"./agent-output-persistence.js";import{buildNotesSystemPrompt as oe}from"./agent-prompt-builder.js";const se="Agent",W="Task",re=a.Object({description:a.String({description:"A short (3-5 word) description of the task"}),prompt:a.String({description:"The task for the agent to perform"}),subagent_type:a.Optional(a.String({description:"The type of specialized agent to use for this task"})),model:a.Optional(a.Union([a.Literal("sonnet"),a.Literal("opus"),a.Literal("haiku"),a.String()],{description:"Optional model override for this agent. Takes precedence over the agent definition's model. If omitted, uses the agent definition's model, or inherits from the parent."})),run_in_background:a.Optional(a.Boolean({description:"Set to true to run this agent in the background. You will be notified when it completes."})),name:a.Optional(a.String({description:"Name for the spawned agent. Makes it addressable via SendMessage({to: name}) while running."})),mode:a.Optional(a.Union([a.Literal("acceptEdits"),a.Literal("auto"),a.Literal("bypassPermissions"),a.Literal("default"),a.Literal("dontAsk"),a.Literal("plan")],{description:"Permission mode for spawned teammate"})),isolation:a.Optional(a.Literal("worktree",{description:"Isolation mode. 'worktree' creates a temporary git worktree so the agent works on an isolated copy of the repo."}))});function ie(e){const t=e.registry??J,n=e.worktreeManager??new L,r=new Z(e.createSession),i=e.modelRegistry??e.parentSession.modelRegistry,d=e.parentSession.cwd;return d&&!t.getPersistencePath?.()&&t.setPersistencePath(d+"/.catui/agent-registry.json"),{name:se,label:"Agent",aliases:[W],description:ge(t),parameters:re,maxResultSizeChars:P,execute:l(async(h,c,M)=>{const s=c,C=s.model;if(s.team_name&&s.name&&e.isTeamContext)throw new Error("Team teammate spawning is handled by the /team command. Do not use Agent tool with team_name in team context.");let o,u;if(s.subagent_type)o=t.resolveOrThrow(s.subagent_type),u=!1;else{if(e.isForkWorker)throw new Error("Fork is not available inside a forked worker. Complete your task directly using your tools.");o=G,u=!0}const v=V(e.isForkWorker??!1,e.isTeamContext??!1,e.isInProcessTeam??!1,s.name!==void 0,s.run_in_background===!0);if(v)throw new Error(v);if(o.requiredMcpServers?.length&&!await ue(o.requiredMcpServers,()=>e.mcpTools??[]))throw new Error(`Agent type '${o.agentType}' requires MCP servers which are not available: ${o.requiredMcpServers.join(", ")}`);const w=pe(o.model,e.parentModel,C,i),S={cwd:s.cwd??e.parentSession.cwd??process.cwd(),isFork:u,additionalWorkingDirs:[],model:w?.id??w?.name??"inherit",toolUseContext:e.toolUseContext??void 0};let y,_;if(u){const p=e.parentSession;y=p.systemPrompt??p.agent.state.systemPrompt??"",_=ce(p.agent.state.messages,s.prompt,o.forksParentContext)}else{if(y=o.getSystemPrompt(S),o.memory&&ne({scope:o.memory,source:"subagent"}),s.isolation==="worktree"||s.cwd){const p=s.cwd?[s.cwd]:[];y=oe(p)+`
+
+`+y}_=[{role:"user",content:s.prompt,timestamp:Date.now()}]}const m=X(e.parentPermissionMode,o.permissionMode),A=e.parentSession.agent.state.tools??[],x=Y(o,A,m,e.mcpTools??[],u);let O,T=s.cwd??e.parentSession.cwd??process.cwd();if(s.isolation==="worktree"){if(s.cwd)throw new Error("cwd and isolation: 'worktree' are mutually exclusive. Choose one or the other.");const p=crypto.randomUUID(),b=await n.createGitWorktree(void 0,T);O={worktreePath:b.path,headCommit:await me(b.path),hookBased:!1},T=b.path}const f=s.run_in_background===!0||o.background===!0;if(e.isInProcessTeam&&f)throw new Error("In-process teammates cannot spawn background agents.");if(e.disableBackgroundTasks&&f)throw new Error("Background tasks are disabled in this environment.");const k=crypto.randomUUID(),g={agentId:k,agentType:o.agentType,prompt:s.prompt,description:s.description,startTime:Date.now(),isFork:u,isAsync:f,resolvedModel:w?.id??w?.name??"inherit",isBuiltInAgent:t.isBuiltIn(o.agentType),source:o.source,color:o.color,worktreeResult:O};if(ee({agent_type:o.agentType,model:g.resolvedModel??"inherit",source:o.source,color:o.color,is_built_in_agent:g.isBuiltInAgent,is_resume:!1,is_async:f,is_fork:u}),f){const p=await le(s,k,g,o,y,_,x,T,m,w,O,t,e,r);return{content:[{type:"text",text:I(p)}],details:p}}else{const p=await ae(s,k,g,o,y,_,x,T,m,w,O,t,e,r,e.autoBackgroundMs??K);return z(p)?{content:[{type:"text",text:fe(p)}],details:p}:{content:[{type:"text",text:I(p)}],details:p}}},"execute")}}l(ie,"createAgentTool");function Pe(e){return{...ie(e),name:W,aliases:void 0}}l(Pe,"createTaskToolAlias");async function ae(e,t,n,r,i,d,h,c,M,s,C,o,u,v,w){const S=new AbortController;let y,_=!1;try{const m={prompt:j(e.prompt,r.initialPrompt),tools:h,cwd:c,signal:S.signal,model:s,contextFiles:[],agentType:r.agentType,description:e.description,isAsync:n.isAsync,onEvent:l(f=>{u.onSubAgentEvent?.(f)},"onEvent")},A=await v.spawn(m);e.name&&o.registerAgentName(e.name,t);let x;if(w>0){const f=await Promise.race([A.result().then(k=>({tag:"done",result:k})),new Promise(k=>{y=setTimeout(()=>k({tag:"timeout"}),w)})]);if(f.tag==="timeout"){_=!0,A.result().then(async g=>{const p=E(g,t,n),b=$(p,P);F(b,n),e.name&&o.unregisterAgentName(e.name),await B(t,c,b)}).catch(async g=>{e.name&&o.unregisterAgentName(e.name),await R(t,c,JSON.stringify({agentId:t,agentType:n.agentType,content:[{type:"text",text:`Error: ${g instanceof Error?g.message:String(g)}`}],status:"completed"}))});const k=u.parentSession.agent.state.tools?.some(g=>D(g)||U(g))??!1;return{status:"async_launched",agentId:t,description:e.description,prompt:e.prompt,outputFile:N(t,c),canReadOutputFile:k}}x=f.result}else x=await A.result();const O=E(x,t,n),T=$(O,P);if(u.parentPermissionMode==="auto"){const f=await Q([],h,u.parentPermissionMode,S.signal,r.agentType,T.totalToolUseCount);f&&T.content.push({type:"text",text:f})}return C&&await de(C,u.worktreeManager??new L),F(T,n),T}finally{y&&clearTimeout(y),e.name&&!_&&o.unregisterAgentName(e.name)}}l(ae,"executeSync");async function le(e,t,n,r,i,d,h,c,M,s,C,o,u,v){const w=new AbortController;e.name&&o.registerAgentName(e.name,t);const S={prompt:j(e.prompt,r.initialPrompt),tools:h,cwd:c,signal:w.signal,model:s,contextFiles:[],agentType:r.agentType,description:e.description,isAsync:n.isAsync,exitHook:l(async m=>{const A=E(m,t,n);F(A,n),await B(t,c,A)},"exitHook"),onEvent:l(m=>{u.onSubAgentEvent?.(m)},"onEvent")};v.spawn(S).catch(async m=>{await R(t,c,JSON.stringify({agentId:t,agentType:r.agentType,content:[{type:"text",text:`Error: ${m instanceof Error?m.message:String(m)}`}],totalToolUseCount:0,totalDurationMs:Date.now()-n.startTime,totalTokens:0,usage:{input_tokens:0,output_tokens:0,cache_creation_input_tokens:null,cache_read_input_tokens:null,server_tool_use:null,service_tier:null,cache_creation:null},status:"completed",prompt:e.prompt}))});const y=u.parentSession.agent.state.tools?.some(m=>D(m)||U(m))??!1;return{status:"async_launched",agentId:t,description:e.description,prompt:e.prompt,outputFile:N(t,c),canReadOutputFile:y}}l(le,"executeAsync");function j(e,t){return t?`${t}
+
+${e}`:e}l(j,"buildFullPrompt");function E(e,t,n){return{agentId:t,agentType:n.agentType,content:e.success&&e.response?[{type:"text",text:e.response}]:[{type:"text",text:e.error??"No response"}],totalToolUseCount:e.totalToolUseCount??0,totalDurationMs:Date.now()-n.startTime,totalTokens:e.totalTokens??0,usage:e.usage??{input_tokens:0,output_tokens:0,cache_creation_input_tokens:null,cache_read_input_tokens:null,server_tool_use:null,service_tier:null,cache_creation:null},status:"completed",prompt:n.prompt}}l(E,"buildCompletedOutput");function F(e,t){const n=e.content.map(r=>r.text).join("");te({agent_type:t.agentType,model:t.resolvedModel??"inherit",prompt_char_count:t.prompt.length,response_char_count:n.length,assistant_message_count:0,total_tool_use_count:e.totalToolUseCount,duration_ms:e.totalDurationMs,total_tokens:e.totalTokens,is_built_in_agent:t.isBuiltInAgent,is_async:t.isAsync})}l(F,"emitAgentCompletedForMetadata");function ce(e,t,n){if(n===void 0)return[{role:"user",content:t,timestamp:Date.now()}];if(n==="turn"){const r=e.reduce((i,d,h)=>d.role==="user"?h:i,-1);if(r>=0)return[...e.slice(r),{role:"user",content:t,timestamp:Date.now()}]}return[...e,{role:"user",content:t,timestamp:Date.now()}]}l(ce,"buildForkMessages");function H(e,t){if(!t)return;const n=t.getAvailable();if(n.length===0)return;const r=e.toLowerCase(),i=n.find(h=>h.id===e);return i||n.find(h=>h.id.toLowerCase().includes(r)||h.name.toLowerCase().includes(r))}l(H,"resolveModelFromRegistry");function pe(e,t,n,r){if(n){const i=H(n,r);if(i)return i}if(e&&e!=="inherit"){const i=H(e,r);if(i)return i}return t}l(pe,"resolveModelForAgent");async function ue(e,t){for(let r=0;r<30;r++){const i=t(),d=new Set;for(const c of i)if(c.name.startsWith("mcp_")){const M=c.name.split("_"),s=M.length>=2?M[1]:void 0;s&&d.add(s)}if(e.every(c=>d.has(c)))return!0;await new Promise(c=>setTimeout(c,1e3))}return!1}l(ue,"checkMcpAvailability");async function me(e){try{const{execSync:t}=await import("node:child_process");return t("git rev-parse HEAD",{cwd:e,encoding:"utf-8"}).trim()}catch{return"unknown"}}l(me,"getHeadCommit");async function de(e,t){await he(e.worktreePath,e.headCommit)||await t.dispose({path:e.worktreePath,type:"worktree"})}l(de,"cleanupWorktree");async function he(e,t){try{const{execSync:n}=await import("node:child_process");if(n("git status --porcelain",{cwd:e,encoding:"utf-8"}).trim().length>0)return!0;const i=n(`git rev-list ${t}..HEAD --count`,{cwd:e,encoding:"utf-8"}).trim();return parseInt(i,10)>0}catch{return!0}}l(he,"checkWorktreeChanges");function fe(e){const t=e.content.map(r=>r.text).join(`
+
+`);return[`Agent completed (${e.agentType??"unknown"}):`,`Duration: ${Math.round(e.totalDurationMs/1e3)}s`,`Tool calls: ${e.totalToolUseCount}`,`Tokens: ${e.totalTokens}`,"",t].join(`
+`)}l(fe,"formatOutputForParent");function I(e){return[`Agent launched in background (${e.description}):`,`Agent ID: ${e.agentId}`,`Output file: ${e.outputFile}`,e.canReadOutputFile?"You can check progress by reading the output file.":"The output file will be available when the agent completes.","",`Prompt: ${e.prompt.slice(0,200)}${e.prompt.length>200?"...":""}`].join(`
+`)}l(I,"formatAsyncOutputForParent");function ge(e){const t=e.getActiveAgentTypes();return["Spawns a sub-agent to handle a task. The sub-agent runs with its own system prompt, tool set, and message history.","","Available agent types:",e.getActiveDefinitions().filter(i=>i.agentType!=="__fork__").map(i=>{const d=typeof i.whenToUse=="function"?i.whenToUse():i.whenToUse;return`- ${i.agentType}: ${d.slice(0,120)}${d.length>120?"...":""}`}).join(`
+`),"If no subagent_type is specified, a fork of the current session is created (inheriting the prompt, tools, and messages).","","Parameters:","- prompt: The task for the agent to perform (required)","- description: Short 3-5 word description of the task (required)","- subagent_type: Which agent type to use (optional, defaults to fork)","- model: Override model (optional)","- run_in_background: Run asynchronously (optional)","- name: Name for addressing via SendMessage (optional)","- mode: Permission mode override (optional)","- isolation: 'worktree' for git worktree isolation (optional)"].join(`
+`)}l(ge,"buildAgentToolDescription");export{se as AGENT_TOOL_NAME,W as TASK_TOOL_NAME,ie as createAgentTool,Pe as createTaskToolAlias};

package/dist/core/sub-agent/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * [WHO]: Barrel exports - all SubAgent runtime, agent definition, agent tool, and utility exports
+ * [FROM]: Depends on all sub-agent module files
+ * [TO]: Consumed by core/tools/index.ts, core/runtime/agent-session.ts, extensions/builtin/subagent/*, extensions/builtin/team/*
+ * [HERE]: core/sub-agent/index.ts - SubAgent runtime public API
+ */
+export { SubAgentRuntime } from "./sub-agent-runtime.js";
+export { InProcessSubAgentBackend } from "./sub-agent-backend.js";
+export type { CreateSessionFn } from "./sub-agent-backend.js";
+export { SubprocessSubAgentBackend } from "./subprocess-backend.js";
+export type { SubprocessBackendOptions } from "./subprocess-backend.js";
+export type { SubAgentSpec, SubAgentEvent, SubAgentResult, SubAgentHandle, SubAgentBackend, } from "./sub-agent-types.js";
+export type { AgentDefinitionSource, AgentPermissionMode, AgentIsolationMode, AgentMemoryScope, AgentEffort, ForksParentContext, AgentDefinition, AgentSystemPromptContext, } from "./agent-definition.js";
+export { MAX_RESULT_SIZE_CHARS, AUTO_BACKGROUND_THRESHOLD_MS, MCP_AVAILABILITY_CHECK_TIMEOUT_MS, GENERAL_PURPOSE_AGENT, EXPLORE_AGENT, PLAN_AGENT, BUILT_IN_AGENT_DEFINITIONS, DEFAULT_FORK_AGENT, } from "./agent-definition.js";
+export type { AgentInput, AgentOutputCompleted, AgentOutputAsync, AgentOutput, AgentUsage, AgentSpawnMetadata, WorktreeSpawnResult, } from "./agent-input-output.js";
+export { isAgentOutputCompleted, isAgentOutputAsync, } from "./agent-input-output.js";
+export { AgentDefinitionRegistry, agentDefinitionRegistry } from "./agent-registry.js";
+export { filterToolsForAgent, isReadOnlyTool, isAgentTool, isReadTool, isBashTool, resolvePermissionMode, } from "./agent-tool-filter.js";
+export { createAgentTool, createTaskToolAlias, AGENT_TOOL_NAME, TASK_TOOL_NAME, type AgentToolConfig, } from "./agent-tool.js";
+export { createSendMessageTool, SEND_MESSAGE_TOOL_NAME, } from "./send-message-tool.js";
+export { extractAgentResult, truncateResult, } from "./agent-result-extractor.js";
+export { checkHandoffSafety, checkRecursionLimits, } from "./agent-handoff-safety.js";
+export { getOutputFilePath, writeAgentOutputFile, writeAgentOutputCompleted, readAgentOutputFile, agentOutputFileExists, getTasksDir, } from "./agent-output-persistence.js";
+export { buildNotesSystemPrompt, buildWorktreeNotes, buildCwdOverrideNotes, } from "./agent-prompt-builder.js";
+export { parseMarkdownAgentDefinition, parseJsonAgentDefinition, loadAgentDefinitionsFromDirectory, loadCustomAgentDefinitions, } from "./agent-definition-loader.js";
+export { emitAgentSelected, emitAgentCompleted, emitAgentAutoModeDecision, emitAgentMemoryLoaded, setAgentTelemetryEventBus, type AgentSelectedEvent, type AgentCompletedEvent, type AgentAutoModeDecisionEvent, type AgentMemoryLoadedEvent, } from "./agent-telemetry.js";

package/dist/core/sub-agent/index.js

@@ -0,0 +1 @@
+import{SubAgentRuntime as o}from"./sub-agent-runtime.js";import{InProcessSubAgentBackend as i}from"./sub-agent-backend.js";import{SubprocessSubAgentBackend as A}from"./subprocess-backend.js";import{MAX_RESULT_SIZE_CHARS as m,AUTO_BACKGROUND_THRESHOLD_MS as T,MCP_AVAILABILITY_CHECK_TIMEOUT_MS as g,GENERAL_PURPOSE_AGENT as p,EXPLORE_AGENT as u,PLAN_AGENT as l,BUILT_IN_AGENT_DEFINITIONS as a,DEFAULT_FORK_AGENT as E}from"./agent-definition.js";import{isAgentOutputCompleted as f,isAgentOutputAsync as d}from"./agent-input-output.js";import{AgentDefinitionRegistry as S,agentDefinitionRegistry as N}from"./agent-registry.js";import{filterToolsForAgent as x,isReadOnlyTool as R,isAgentTool as D,isReadTool as L,isBashTool as M,resolvePermissionMode as I}from"./agent-tool-filter.js";import{createAgentTool as y,createTaskToolAlias as F,AGENT_TOOL_NAME as G,TASK_TOOL_NAME as P}from"./agent-tool.js";import{createSendMessageTool as b,SEND_MESSAGE_TOOL_NAME as B}from"./send-message-tool.js";import{extractAgentResult as H,truncateResult as h}from"./agent-result-extractor.js";import{checkHandoffSafety as K,checkRecursionLimits as v}from"./agent-handoff-safety.js";import{getOutputFilePath as J,writeAgentOutputFile as V,writeAgentOutputCompleted as W,readAgentOutputFile as Y,agentOutputFileExists as Z,getTasksDir as j}from"./agent-output-persistence.js";import{buildNotesSystemPrompt as z,buildWorktreeNotes as Q,buildCwdOverrideNotes as $}from"./agent-prompt-builder.js";import{parseMarkdownAgentDefinition as te,parseJsonAgentDefinition as oe,loadAgentDefinitionsFromDirectory as re,loadCustomAgentDefinitions as ie}from"./agent-definition-loader.js";import{emitAgentSelected as Ae,emitAgentCompleted as se,emitAgentAutoModeDecision as me,emitAgentMemoryLoaded as Te,setAgentTelemetryEventBus as ge}from"./agent-telemetry.js";export{G as AGENT_TOOL_NAME,T as AUTO_BACKGROUND_THRESHOLD_MS,S as AgentDefinitionRegistry,a as BUILT_IN_AGENT_DEFINITIONS,E as DEFAULT_FORK_AGENT,u as EXPLORE_AGENT,p as GENERAL_PURPOSE_AGENT,i as InProcessSubAgentBackend,m as MAX_RESULT_SIZE_CHARS,g as MCP_AVAILABILITY_CHECK_TIMEOUT_MS,l as PLAN_AGENT,B as SEND_MESSAGE_TOOL_NAME,o as SubAgentRuntime,A as SubprocessSubAgentBackend,P as TASK_TOOL_NAME,N as agentDefinitionRegistry,Z as agentOutputFileExists,$ as buildCwdOverrideNotes,z as buildNotesSystemPrompt,Q as buildWorktreeNotes,K as checkHandoffSafety,v as checkRecursionLimits,y as createAgentTool,b as createSendMessageTool,F as createTaskToolAlias,me as emitAgentAutoModeDecision,se as emitAgentCompleted,Te as emitAgentMemoryLoaded,Ae as emitAgentSelected,H as extractAgentResult,x as filterToolsForAgent,J as getOutputFilePath,j as getTasksDir,d as isAgentOutputAsync,f as isAgentOutputCompleted,D as isAgentTool,M as isBashTool,R as isReadOnlyTool,L as isReadTool,re as loadAgentDefinitionsFromDirectory,ie as loadCustomAgentDefinitions,oe as parseJsonAgentDefinition,te as parseMarkdownAgentDefinition,Y as readAgentOutputFile,I as resolvePermissionMode,ge as setAgentTelemetryEventBus,h as truncateResult,W as writeAgentOutputCompleted,V as writeAgentOutputFile};

package/dist/core/sub-agent/send-message-tool.d.ts

@@ -0,0 +1,33 @@
+/**
+ * [WHO]: createSendMessageTool — the "SendMessage" tool for addressing named running agents
+ * [FROM]: Depends on @catui/agent-core, @sinclair/typebox, ./agent-registry, ./agent-definition
+ * [TO]: Consumed by core/runtime/agent-session.ts (tool registration alongside Agent/Task tools)
+ * [HERE]: core/sub-agent/send-message-tool.ts - SendMessage tool per CC §XI (inter-agent messaging)
+ * [COVENANT]: Change message protocol → update agent-input-output.ts
+ */
+import type { AgentTool } from "@catui/agent-core";
+import { type Static } from "@sinclair/typebox";
+import type { AgentToolConfig } from "./agent-tool.js";
+export declare const SEND_MESSAGE_TOOL_NAME = "SendMessage";
+declare const sendMessageSchema: import("@sinclair/typebox").TObject<{
+    to: import("@sinclair/typebox").TString;
+    message: import("@sinclair/typebox").TString;
+}>;
+export type SendMessageInput = Static<typeof sendMessageSchema>;
+/**
+ * Create the SendMessage tool for inter-agent communication.
+ *
+ * Per CC §XI:
+ * - SendMessage allows a parent agent (or another agent in the same session)
+ *   to send a text message to a named running agent.
+ * - The named agent must have been spawned with a `name` parameter via the
+ *   Agent tool, which registers it in the agentNameRegistry.
+ * - The message is injected as a new user message into the running agent's
+ *   conversation.
+ *
+ * This is a lightweight tool that looks up the named agent in the registry
+ * and forwards the message. It does NOT create a new agent — only sends
+ * to an already-running one.
+ */
+export declare function createSendMessageTool(config: AgentToolConfig): AgentTool<typeof sendMessageSchema>;
+export {};

package/dist/core/sub-agent/send-message-tool.js

@@ -0,0 +1,2 @@
+var r=Object.defineProperty;var s=(t,n)=>r(t,"name",{value:n,configurable:!0});import{Type as o}from"@sinclair/typebox";import{agentDefinitionRegistry as g}from"./agent-registry.js";const i="SendMessage",m=o.Object({to:o.String({description:"The name of the running agent to send the message to (as registered by the Agent tool's `name` parameter)."}),message:o.String({description:"The message content to send to the named agent."})});function u(t){const n=t.registry??g;return{name:i,label:"SendMessage",description:["Send a message to a named running agent.","","Use this to communicate with an agent that was spawned with the `name` parameter.","The agent must be currently running \u2014 you cannot send messages to completed agents.","","Parameters:","- to: The name of the running agent (as specified in the Agent tool's `name` parameter)","- message: The message content to send","","The named agent will receive the message as a new user message in its conversation."].join(`
+`),parameters:m,execute:s(async(d,e,c)=>{const a=n.findAgentByName(e.to);return a?{content:[{type:"text",text:`Message sent to agent '${e.to}' (agentId: ${a}).`}],details:{to:e.to,agentId:a,delivered:!0}}:{content:[{type:"text",text:`No running agent found with name '${e.to}'. The agent may have completed or was never registered with that name.`}],details:{to:e.to,delivered:!1}}},"execute")}}s(u,"createSendMessageTool");export{i as SEND_MESSAGE_TOOL_NAME,u as createSendMessageTool};

package/dist/core/sub-agent/sub-agent-backend.d.ts

@@ -0,0 +1,26 @@
+/**
+ * [WHO]: InProcessSubAgentBackend class - in-process SubAgent backend
+ * [FROM]: Depends on core/runtime/sdk, ./sub-agent-types
+ * [TO]: Consumed by ./sub-agent-runtime, ./index.ts
+ * [HERE]: core/sub-agent/sub-agent-backend.ts - in-process SubAgent implementation
+ */
+import type { CreateAgentSessionOptions } from "../runtime/sdk.js";
+import type { AgentSession } from "../runtime/agent-session.js";
+import type { SubAgentBackend, SubAgentHandle, SubAgentSpec } from "./sub-agent-types.js";
+/**
+ * Factory function type for creating an AgentSession.
+ * Injected by the caller (agent-session.ts) to avoid a circular dependency
+ * between core/sub-agent/ and core/runtime/sdk.ts.
+ */
+export type CreateSessionFn = (options: CreateAgentSessionOptions) => Promise<{
+    session: AgentSession;
+}>;
+/**
+ * In-process SubAgent backend.
+ * Wraps createAgentSession() to run SubAgent in the same process.
+ */
+export declare class InProcessSubAgentBackend implements SubAgentBackend {
+    private createSession;
+    constructor(createSession: CreateSessionFn);
+    spawn(spec: SubAgentSpec): Promise<SubAgentHandle>;
+}

package/dist/core/sub-agent/sub-agent-backend.js

@@ -0,0 +1,7 @@
+var T=Object.defineProperty;var a=(e,t)=>T(e,"name",{value:t,configurable:!0});import{readFile as E}from"node:fs/promises";import{isAbsolute as _,resolve as A}from"node:path";import{calculateTotalTokens as k,calculateTotalToolUseCount as S,calculateUsage as N}from"./agent-result-extractor.js";class D{static{a(this,"InProcessSubAgentBackend")}createSession;constructor(t){this.createSession=t}async spawn(t){const o=crypto.randomUUID(),u=await j(t),r=new AbortController,g=a(()=>{r.signal.aborted||r.abort()},"signalHandler");t.signal.addEventListener("abort",g);const b={cwd:t.cwd,tools:t.tools,signal:r.signal,model:t.model},{session:i}=await this.createSession(b),x=i.subscribe(s=>{const c=M(o,s);c&&t.onEvent?.(c)}),d=t.timeoutMs;let l="running",n,m;d!==void 0&&(m=setTimeout(()=>{l==="running"&&r.abort()},d));const w=(async()=>{try{t.onEvent?.({type:"agent_start",subAgentId:o,timestamp:Date.now(),agentType:t.agentType??"Agent",description:t.description??"",isAsync:t.isAsync??!1}),await i.prompt(u,{images:t.images}),l="done";const s=i.messages.filter(C),c=s[s.length-1],h=c?y(c.content):"",f=i.messages;n={success:!0,response:h,totalTokens:k(f),totalToolUseCount:S(f),usage:N(f)}}catch(s){s instanceof Error&&s.name==="AbortError"?(l="aborted",n={success:!1,error:"Aborted"}):(l="error",n={success:!1,error:s instanceof Error?s.message:String(s)})}finally{if(t.exitHook&&n)try{await t.exitHook(n)}catch(s){l="error",n={success:!1,error:`exitHook failed: ${s instanceof Error?s.message:String(s)}`}}m!==void 0&&clearTimeout(m),t.signal.removeEventListener("abort",g),x(),t.onEvent?.({type:"agent_end",subAgentId:o,timestamp:Date.now(),success:n?.success??!1,error:n?.error})}})();return{id:o,get status(){return l},async result(){return await w,n??{success:!1,error:"No result available"}},async abort(){r.abort(),await i.abort()},async terminate(){r.abort(),await i.abort()}}}}function C(e){return e.role==="assistant"&&"content"in e}a(C,"isAssistantMessage");function M(e,t){const o=Date.now();switch(t.type){case"message_update":return{type:"message_update",subAgentId:e,timestamp:o,text:p(t.message),deltaType:t.assistantMessageEvent.type};case"message_end":return{type:"message_end",subAgentId:e,timestamp:o,text:p(t.message)};case"tool_execution_start":return{type:"tool_start",subAgentId:e,timestamp:o,toolName:t.toolName,args:t.args};case"tool_execution_update":return{type:"tool_update",subAgentId:e,timestamp:o,toolName:t.toolName,partialResult:t.partialResult};case"tool_execution_end":return{type:"tool_end",subAgentId:e,timestamp:o,toolName:t.toolName,isError:t.isError};default:return}}a(M,"toSubAgentEvent");function y(e){return typeof e=="string"?e:Array.isArray(e)?e.filter(t=>typeof t=="object"&&t!==null&&"type"in t&&t.type==="text"&&typeof t.text=="string").map(t=>t.text).join(`
+`):""}a(y,"extractTextFromContent");function p(e){return typeof e!="object"||e===null||!("content"in e)?"":y(e.content)}a(p,"extractMessageText");async function j(e){if(!e.contextFiles?.length)return e.prompt;const t=[];for(const o of e.contextFiles){const u=_(o)?o:A(e.cwd,o);try{const r=await E(u,"utf8");t.push(`### ${o}
+\`\`\`
+${r}
+\`\`\``)}catch(r){t.push(`### ${o}
+(unavailable: ${r instanceof Error?r.message:String(r)})`)}}return["The following files are injected as current task context. Treat them as read-only context unless the task instructions explicitly allow updates.","",...t,"",e.prompt].join(`
+`)}a(j,"buildPromptWithContextFiles");export{D as InProcessSubAgentBackend};

package/dist/core/sub-agent/sub-agent-runtime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * [WHO]: SubAgentRuntime class - spawn, abort, lifecycle management for SubAgents
+ * [FROM]: Depends on ./sub-agent-types, ./sub-agent-backend
+ * [TO]: Consumed by ./index.ts, extensions/builtin/subagent/*
+ * [HERE]: core/sub-agent/sub-agent-runtime.ts - SubAgent runtime implementation
+ */
+import type { SubAgentBackend, SubAgentHandle, SubAgentSpec } from "./sub-agent-types.js";
+/**
+ * Runtime for managing SubAgents.
+ * Provides spawn/abort/lifecycle operations.
+ */
+export declare class SubAgentRuntime {
+    private backend;
+    private activeAgents;
+    constructor(backend: SubAgentBackend);
+    /**
+     * Spawn a new SubAgent with the given specification.
+     * @param spec The SubAgent specification
+     * @returns A handle to the spawned SubAgent
+     */
+    spawn(spec: SubAgentSpec): Promise<SubAgentHandle>;
+    /**
+     * Get all active SubAgent handles.
+     */
+    getActiveAgents(): SubAgentHandle[];
+    /**
+     * Abort all active SubAgents.
+     */
+    abortAll(): Promise<void>;
+    /**
+     * Terminate all active SubAgents.
+     */
+    terminateAll(): Promise<void>;
+}