catui-agent 1.0.0-beta.0

package/dist/core/sub-agent/agent-definition-loader.d.ts

@@ -0,0 +1,96 @@
+/**
+ * [WHO]: loadAgentDefinitionsFromDirectory, parseMarkdownAgentDefinition, parseJsonAgentDefinition
+ * [FROM]: Depends on node:fs/promises, node:path, ./agent-definition for AgentDefinition types
+ * [TO]: Consumed by ./agent-registry (reload), extensions/builtin/subagent/*
+ * [HERE]: core/sub-agent/agent-definition-loader.ts - Custom agent definition loader per CC §XV (mM4/uM4)
+ * [COVENANT]: Change format → update agent-registry reload and agent-definition interface
+ */
+import type { AgentDefinition, AgentDefinitionSource } from "./agent-definition.js";
+/**
+ * Parse a markdown agent definition file.
+ * Matches CC's mM4() function for parsing .claude/agents/*.md
+ * (adapted to .catui/agents/*.md).
+ *
+ * Format (CC §15.1):
+ * ```markdown
+ * ---
+ * name: my-agent
+ * description: "A specialized agent for X"
+ * tools: ["Read", "Glob", "Grep"]
+ * disallowedTools: ["Write"]
+ * model: sonnet
+ * effort: high
+ * permissionMode: plan
+ * maxTurns: 10
+ * background: false
+ * memory: project
+ * isolation: worktree
+ * skills: ["skill-name"]
+ * initialPrompt: "..."
+ * appendSystemPrompt: true
+ * mcpServers: ["server-name"]
+ * ---
+ *
+ * You are a specialized agent for X.
+ * ```
+ */
+export declare function parseMarkdownAgentDefinition(content: string, filePath: string, source?: AgentDefinitionSource): AgentDefinition | null;
+/**
+ * Parse a JSON agent definition (plugin format).
+ * Matches CC's uM4() function for JSON agent definitions.
+ *
+ * Format (CC §15.2):
+ * ```json
+ * {
+ *   "agents": {
+ *     "my-agent": {
+ *       "description": "A specialized agent for X",
+ *       "tools": ["Read", "Glob", "Grep"],
+ *       "prompt": "You are a specialized agent for X...",
+ *       "model": "sonnet",
+ *       "permissionMode": "plan",
+ *       "maxTurns": 10,
+ *       "background": false,
+ *       "memory": "project",
+ *       "isolation": "worktree"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function parseJsonAgentDefinition(content: string, filePath: string, source?: AgentDefinitionSource): AgentDefinition[];
+/**
+ * Load all agent definitions from a directory.
+ * Scans for .md and .json files and parses them.
+ *
+ * Per CC §XIV:
+ * - Sources: built-in, plugin, user custom (.catui/agents/*.md)
+ * - Failed files are recorded for error reporting
+ *
+ * @param dirPath Directory to scan for agent definitions
+ * @param source Source classification for loaded definitions
+ * @returns Array of successfully parsed definitions and failed file entries
+ */
+export declare function loadAgentDefinitionsFromDirectory(dirPath: string, source?: AgentDefinitionSource): Promise<{
+    definitions: AgentDefinition[];
+    failedFiles: Array<{
+        path: string;
+        error: string;
+    }>;
+}>;
+/**
+ * Load custom agent definitions from the standard locations.
+ * Per CC §XIV:
+ * - .catui/agents/*.md (project-scoped)
+ * - ~/.catui/agents/<id>/agents/*.md (user-scoped)
+ *
+ * @param cwd Project root directory
+ * @param agentDir Global agent config directory
+ */
+export declare function loadCustomAgentDefinitions(cwd: string, agentDir: string): Promise<{
+    definitions: AgentDefinition[];
+    failedFiles: Array<{
+        path: string;
+        error: string;
+    }>;
+}>;

package/dist/core/sub-agent/agent-definition-loader.js

@@ -0,0 +1,2 @@
+var k=Object.defineProperty;var c=(n,o)=>k(n,"name",{value:o,configurable:!0});import{readFile as g,readdir as h}from"node:fs/promises";import{join as u,basename as l,dirname as f}from"node:path";function x(n,o,i="projectSettings"){const s=n.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);if(!s)return{agentType:l(o,".md"),description:`Custom agent from ${o}`,whenToUse:`Use the ${l(o,".md")} agent for its specialized task.`,getSystemPrompt:c(()=>n.trim(),"getSystemPrompt"),source:i,baseDir:f(o),filename:o};const a=s[1],m=s[2].trim(),e=C(a),r=e.name??l(o,".md"),t=m||e.prompt||"";return{agentType:r,description:e.description??`Custom agent: ${r}`,whenToUse:e.whenToUse??`Use the ${r} agent for its specialized task.`,getSystemPrompt:c(()=>t,"getSystemPrompt"),tools:d(e.tools),disallowedTools:d(e.disallowedTools),model:e.model,effort:e.effort,permissionMode:e.permissionMode,isolation:e.isolation,background:e.background==="true"||e.background===!0,forksParentContext:e.forksParentContext,requiredMcpServers:p(e.requiredMcpServers),mcpServers:p(e.mcpServers),source:i,baseDir:f(o),color:e.color,maxTurns:typeof e.maxTurns=="number"?e.maxTurns:void 0,skills:p(e.skills),initialPrompt:e.initialPrompt,memory:e.memory,omitContextFiles:e.omitClaudeMd==="true"||e.omitClaudeMd===!0||e.omitContextFiles==="true"||e.omitContextFiles===!0,appendSystemPrompt:e.appendSystemPrompt==="true"||e.appendSystemPrompt===!0,hooks:e.hooks,filename:o}}c(x,"parseMarkdownAgentDefinition");function T(n,o,i="plugin"){let s;try{s=JSON.parse(n)}catch{return[]}const a=s.agents??s;if(typeof a!="object"||a===null)return[];const m=[];for(const[e,r]of Object.entries(a)){if(typeof r!="object"||r===null)continue;const t=r,S=t.prompt??"";m.push({agentType:e,description:t.description??`Custom agent: ${e}`,whenToUse:t.whenToUse??`Use the ${e} agent for its specialized task.`,getSystemPrompt:c(()=>S,"getSystemPrompt"),tools:d(t.tools),disallowedTools:d(t.disallowedTools),model:t.model,effort:t.effort,permissionMode:t.permissionMode,isolation:t.isolation,background:t.background===!0,forksParentContext:t.forksParentContext,requiredMcpServers:p(t.requiredMcpServers),mcpServers:p(t.mcpServers),source:i,baseDir:f(o),color:t.color,maxTurns:typeof t.maxTurns=="number"?t.maxTurns:void 0,skills:p(t.skills),initialPrompt:t.initialPrompt,memory:t.memory,omitContextFiles:t.omitClaudeMd===!0||t.omitContextFiles===!0,appendSystemPrompt:t.appendSystemPrompt===!0,hooks:t.hooks,filename:o})}return m}c(T,"parseJsonAgentDefinition");async function y(n,o="projectSettings"){const i=[],s=[];let a;try{a=await h(n)}catch{return{definitions:i,failedFiles:s}}for(const m of a){const e=u(n,m);if(m.endsWith(".md"))try{const r=await g(e,"utf-8"),t=x(r,e,o);t&&i.push(t)}catch(r){s.push({path:e,error:r instanceof Error?r.message:String(r)})}else if(m.endsWith(".json"))try{const r=await g(e,"utf-8"),t=T(r,e,o);i.push(...t)}catch(r){s.push({path:e,error:r instanceof Error?r.message:String(r)})}}return{definitions:i,failedFiles:s}}c(y,"loadAgentDefinitionsFromDirectory");async function F(n,o){const i=await y(u(n,".catui","agents"),"projectSettings"),s=await y(u(o,"agents"),"userSettings");return{definitions:[...i.definitions,...s.definitions],failedFiles:[...i.failedFiles,...s.failedFiles]}}c(F,"loadCustomAgentDefinitions");function C(n){const o={},i=n.split(`
+`);for(const s of i){const a=s.trim();if(!a||a.startsWith("#"))continue;const m=a.indexOf(":");if(m<0)continue;const e=a.slice(0,m).trim(),r=a.slice(m+1).trim();if(!r){o[e]=void 0;continue}try{o[e]=JSON.parse(r)}catch{const t=r.replace(/^["']|["']$/g,"");o[e]=t}}return o}c(C,"parseSimpleYamlFrontmatter");function d(n){if(n!=null){if(typeof n=="string")return n.includes(",")?n.split(",").map(o=>o.trim()):[n.trim()];if(Array.isArray(n))return n.map(o=>String(o).trim())}}c(d,"parseToolList");function p(n){return d(n)}c(p,"parseStringList");export{y as loadAgentDefinitionsFromDirectory,F as loadCustomAgentDefinitions,T as parseJsonAgentDefinition,x as parseMarkdownAgentDefinition};

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

@@ -0,0 +1,162 @@
+/**
+ * [WHO]: AgentDefinition interface, AgentDefinitionSource, AgentPermissionMode, built-in agent definitions
+ * [FROM]: Depends on @catui/agent-core for AgentMessage, @catui/ai for Model
+ * [TO]: Consumed by ./agent-tool, ./agent-registry, ./index.ts, extensions/builtin/subagent/*
+ * [HERE]: core/sub-agent/agent-definition.ts - Agent type definitions per CC Agent architecture (cc-agent-design §IV, §V)
+ * [COVENANT]: Add/remove fields → update P2 AGENT.md member list
+ */
+/** Where an agent definition comes from (CC: source field). */
+export type AgentDefinitionSource = "built-in" | "plugin" | "flagSettings" | "userSettings" | "projectSettings";
+/** Permission mode for spawned agents (CC: permissionMode field). */
+export type AgentPermissionMode = "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan";
+/** Isolation mode. Currently only "worktree" is supported. */
+export type AgentIsolationMode = "worktree";
+/** Memory scope for agent definitions. */
+export type AgentMemoryScope = "user" | "project" | "local";
+/** Effort level for reasoning. */
+export type AgentEffort = "low" | "medium" | "high" | number;
+/** Fork context inheritance mode (CC: forksParentContext). */
+export type ForksParentContext = true | "turn" | undefined;
+/** Maximum result size in characters (CC: maxResultSizeChars = 1e5). */
+export declare const MAX_RESULT_SIZE_CHARS = 100000;
+/** Auto-background threshold in milliseconds (CC: 120000 = 2 minutes). */
+export declare const AUTO_BACKGROUND_THRESHOLD_MS = 120000;
+/** Default timeout for MCP server availability checks (CC: 30 seconds). */
+export declare const MCP_AVAILABILITY_CHECK_TIMEOUT_MS = 30000;
+/**
+ * Full agent definition matching CC's AgentDefinition interface.
+ * Controls everything about a spawned sub-agent: tools, model, prompt, isolation, etc.
+ */
+export interface AgentDefinition {
+    /** Unique identifier for this agent type, e.g. "general-purpose", "Explore" */
+    agentType: string;
+    /** One-line description shown to the parent agent when choosing which sub-agent to use */
+    description: string;
+    /**
+     * When-to-use guidance for the parent agent.
+     * ⚠️ Can be a function reference (like CC's Explore agent) — runs at runtime to
+     * dynamically generate guidance based on context.
+     */
+    whenToUse: string | (() => string);
+    /**
+     * System prompt builder.
+     * Receives a context object and returns the full system prompt string.
+     * Fork mode uses the parent's renderedSystemPrompt directly instead.
+     */
+    getSystemPrompt: (ctx: AgentSystemPromptContext) => string;
+    /**
+     * Tool whitelist. ["*"] = inherit all parent tools.
+     * If undefined, falls through to disallowedTools (blacklist approach).
+     */
+    tools?: string[];
+    /**
+     * Tool blacklist. Listed tools are removed from the parent's tool set.
+     * E.g. Explore: ["Agent", "Edit", "Write"] prevents spawning + editing.
+     */
+    disallowedTools?: string[];
+    /** Model override: "sonnet" | "opus" | "haiku" | "inherit" | a specific model ID. "inherit" = use parent model. */
+    model?: string;
+    /** Reasoning effort level. */
+    effort?: AgentEffort;
+    /** Permission mode for the spawned agent. Inherits from parent if undefined. */
+    permissionMode?: AgentPermissionMode;
+    /** Isolation mode. "worktree" creates a git worktree so the agent works on an isolated copy. */
+    isolation?: AgentIsolationMode;
+    /**
+     * Agent definition-level background flag.
+     * ⚠️ Different from the run_in_background parameter — this controls whether
+     * the agent type itself defaults to background execution.
+     */
+    background?: boolean;
+    /**
+     * Controls which parent messages the fork inherits.
+     * true = inherit all parent messages
+     * "turn" = only inherit current turn's messages
+     * undefined = no inheritance (fresh start)
+     */
+    forksParentContext?: ForksParentContext;
+    /** MCP servers that must be available for this agent to function. Agent will error if missing. */
+    requiredMcpServers?: string[];
+    /** MCP servers associated with this agent. */
+    mcpServers?: string[];
+    /** Where this definition came from. */
+    source: AgentDefinitionSource;
+    /** Base directory for resolving relative paths in the definition. */
+    baseDir: string;
+    /** UI color identifier for status rendering. */
+    color?: string;
+    /** Maximum number of agent turns before forced completion. */
+    maxTurns?: number;
+    /** Skills associated with this agent definition. */
+    skills?: string[];
+    /** Initial prompt injected before the user's task prompt. */
+    initialPrompt?: string;
+    /** Memory scope: determines which memory context to load. */
+    memory?: AgentMemoryScope;
+    /** Whether to skip loading CLAUDE.md / AGENTS.md / .CATUI.md context files. */
+    omitContextFiles?: boolean;
+    /** Whether to append (rather than replace) the system prompt. */
+    appendSystemPrompt?: boolean;
+    /** Hook configuration for lifecycle events. */
+    hooks?: Record<string, unknown>;
+    /** Filename (for custom agents loaded from .md / .json files). */
+    filename?: string;
+}
+/**
+ * Context passed to AgentDefinition.getSystemPrompt().
+ * Mirrors CC's toolUseContext shape (simplified for Catui).
+ */
+export interface AgentSystemPromptContext {
+    /** The cwd for this agent run (may differ from parent if worktree/cwd override is used). */
+    cwd: string;
+    /** Whether the agent is running in fork mode (inherits parent prompt). */
+    isFork?: boolean;
+    /** Additional working directories (worktree paths, etc.) for Notes injection. */
+    additionalWorkingDirs?: string[];
+    /** Model name being used by this agent. */
+    model?: string;
+    /** Tool use context from parent (for permission checks, tool resolution). */
+    toolUseContext?: unknown;
+}
+/**
+ * general-purpose agent (CC §5.1)
+ * - tools: ["*"] — inherits all parent tools
+ * - System prompt: inherits parent agent's system prompt
+ */
+export declare const GENERAL_PURPOSE_AGENT: AgentDefinition;
+/**
+ * Explore agent (CC §5.2)
+ * - disallowedTools: ["Agent", "Edit", "Write"] — read-only, no recursion
+ * - model: "haiku" — fast and cheap
+ * - omitContextFiles: true — skip CLAUDE.md / AGENTS.md
+ */
+export declare const EXPLORE_AGENT: AgentDefinition;
+/**
+ * Plan agent (CC §5.3)
+ * - disallowedTools: ["Agent", "Edit", "Write"] — read-only, no recursion
+ * - model: "inherit" — uses parent model
+ * - omitContextFiles: true
+ */
+export declare const PLAN_AGENT: AgentDefinition;
+/**
+ * statusline-setup agent (CC §5.4)
+ * - tools: ["Read", "Edit"] — only read and edit, no Bash/Write
+ * - model: "sonnet"
+ * - color: "orange"
+ */
+export declare const STATUSLINE_SETUP_AGENT: AgentDefinition;
+/**
+ * Catui-guide agent (CC §5.5)
+ * - Conditional tools: Read, Grep, Glob, Agent (if web access), else Read, Grep, Glob
+ * - model: "haiku"
+ * - permissionMode: "dontAsk"
+ */
+export declare const CATUI_GUIDE_AGENT: AgentDefinition;
+/** All built-in agent definitions, keyed by agentType. */
+export declare const BUILT_IN_AGENT_DEFINITIONS: ReadonlyMap<string, AgentDefinition>;
+/**
+ * The default "fork" agent definition used when subagent_type is not specified.
+ * In CC, this creates an agent that inherits the parent's system prompt, messages,
+ * and tool set — effectively creating a "fork" of the parent session.
+ */
+export declare const DEFAULT_FORK_AGENT: AgentDefinition;

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

@@ -0,0 +1,6 @@
+var l=Object.defineProperty;var e=(t,n)=>l(t,"name",{value:n,configurable:!0});const m=1e5,y=12e4,b=3e4,o={agentType:"general-purpose",description:"General-purpose agent for complex multi-step tasks",whenToUse:"General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries, use this agent to perform the search for you.",tools:["*"],source:"built-in",baseDir:"built-in",getSystemPrompt:e(t=>u(t),"getSystemPrompt")},i={agentType:"Explore",description:"Read-only exploration agent for searching code and answering questions",whenToUse:e(()=>"Explore agent for searching code, finding files, and answering questions about the codebase. Use this when you need to search for a specific pattern, understand how code works, or find relevant files. This agent is read-only \u2014 it cannot edit files or spawn sub-agents.","whenToUse"),disallowedTools:["Agent","Edit","Write"],source:"built-in",baseDir:"built-in",model:"haiku",omitContextFiles:!0,getSystemPrompt:e(()=>c(),"getSystemPrompt")},s={agentType:"Plan",description:"Software architect agent for designing implementation plans",whenToUse:"Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.",disallowedTools:["Agent","Edit","Write"],source:"built-in",baseDir:"built-in",model:"inherit",omitContextFiles:!0,getSystemPrompt:e(()=>f(),"getSystemPrompt")},a={agentType:"statusline-setup",description:"Agent for configuring the TUI status line settings",whenToUse:"Use this agent to configure the user's Catui status line setting.",tools:["Read","Edit"],source:"built-in",baseDir:"built-in",model:"sonnet",color:"orange",getSystemPrompt:e(()=>g(),"getSystemPrompt")},r={agentType:"catui-guide",description:"Agent for answering questions about Catui features and usage",whenToUse:'Use this agent when the user asks questions ("Can Catui...", "Does Catui...", "How do I...") about: (1) Catui (the terminal AI coding agent) - features, slash commands, MCP servers, settings, extensions, keybindings, configuration; (2) the Agent SDK - building custom agents; (3) supported model APIs - usage, tool use. IMPORTANT: Before spawning a new agent, check if there is already a running or recently completed catui-guide agent that you can continue via SendMessage.',tools:["Read","Grep","Find"],source:"built-in",baseDir:"built-in",model:"haiku",permissionMode:"dontAsk",getSystemPrompt:e(()=>p(),"getSystemPrompt")},T=new Map([[o.agentType,o],[i.agentType,i],[s.agentType,s],[a.agentType,a],[r.agentType,r]]),w={agentType:"__fork__",description:"Fork of the current agent session",whenToUse:"Default fork mode \u2014 inherits parent session's prompt, tools, and messages",tools:["*"],source:"built-in",baseDir:"built-in",forksParentContext:!0,getSystemPrompt:e(t=>u(t),"getSystemPrompt")};function u(t){const n=["You are a sub-agent tasked with completing a specific assignment."];if(t.cwd&&n.push(`Working directory: ${t.cwd}`),t.additionalWorkingDirs?.length){n.push("Notes:");for(const d of t.additionalWorkingDirs)n.push(`- Working directory: ${d}`)}return t.model&&n.push(`Model: ${t.model}`),n.push(""),n.push("Complete your task thoroughly. When finished, provide a clear summary of your findings or actions."),n.join(`
+`)}e(u,"buildDefaultSubAgentPrompt");function c(){return["You are an exploration agent. Your role is to search and understand code without modifying it.","","Rules:","- You may only READ files, SEARCH for patterns, and LIST directories.","- You may NOT edit, write, or modify any files.","- You may NOT spawn additional sub-agents.","- Focus on thoroughness: examine multiple files, trace dependencies, understand the full picture.","- When done, provide a clear, organized summary of your findings.","","Available tools: read, grep, find, ls, time, bash (read-only commands only)."].join(`
+`)}e(c,"buildExploreAgentPrompt");function g(){return["You are a status line setup agent for Catui.","Your task is to help configure the user's terminal status line / TUI theme settings.","","You can read the current configuration and edit settings files.","When making changes, explain what you are changing and why.","After making changes, read the file back to confirm the changes were applied correctly."].join(`
+`)}e(g,"buildStatuslineSetupPrompt");function p(){return["You are a Catui documentation guide agent.","Your task is to answer questions about Catui features, configuration, and usage.","","You have access to:","- Read: to read documentation files, AGENTS.md, .CATUI.md, and source code","- Grep: to search for specific patterns in the codebase","- Find: to locate files by name or pattern","","When answering questions:","- Search the codebase and documentation for accurate information","- Provide specific file paths and line numbers when referencing features","- If you cannot find the answer, say so honestly rather than guessing","- Include practical examples when possible"].join(`
+`)}e(p,"buildCatuiGuidePrompt");function f(){return["You are a planning agent \u2014 a software architect who designs implementation strategies.","","Your responsibilities:","- Analyze the task and identify all files that need to be modified or created.","- Break the task into ordered implementation steps.","- Identify potential risks, edge cases, and architectural trade-offs.","- Consider dependencies between steps and suggest the optimal order.","","Rules:","- You may only READ files and SEARCH for patterns.","- You may NOT edit, write, or modify any files.","- You may NOT spawn additional sub-agents.","- Your output must be a concrete, actionable plan \u2014 not vague guidance.","- Include file paths, function names, and specific changes needed.","","Available tools: read, grep, find, ls, time, bash (read-only commands only)."].join(`
+`)}e(f,"buildPlanAgentPrompt");export{y as AUTO_BACKGROUND_THRESHOLD_MS,T as BUILT_IN_AGENT_DEFINITIONS,r as CATUI_GUIDE_AGENT,w as DEFAULT_FORK_AGENT,i as EXPLORE_AGENT,o as GENERAL_PURPOSE_AGENT,m as MAX_RESULT_SIZE_CHARS,b as MCP_AVAILABILITY_CHECK_TIMEOUT_MS,s as PLAN_AGENT,a as STATUSLINE_SETUP_AGENT};

package/dist/core/sub-agent/agent-handoff-safety.d.ts

@@ -0,0 +1,39 @@
+/**
+ * [WHO]: checkHandoffSafety — handoff classifier for auto mode sub-agent security review (CC §XII.1)
+ * [FROM]: Depends on @catui/agent-core for AgentMessage, ./agent-definition for AgentPermissionMode
+ * [TO]: Consumed by ./agent-tool (sync execution path, step 15)
+ * [HERE]: core/sub-agent/agent-handoff-safety.ts - Security review per CC §XII.1 (ES8)
+ * [COVENANT]: Change classifier → update agent-tool handler
+ */
+import type { AgentMessage } from "@catui/agent-core";
+import type { AgentTool } from "@catui/agent-core";
+import type { AgentPermissionMode } from "./agent-definition.js";
+/**
+ * Check whether a sub-agent's output is safe to hand back to the parent.
+ * Matches CC's ES8 function (handoff classifier) exactly.
+ *
+ * Per CC §XII.1:
+ * - Only runs in "auto" permission mode
+ * - Uses a classifier model to review sub-agent operations
+ * - If flagged → returns a SECURITY WARNING prefix
+ * - If classifier unavailable → returns warning but doesn't block
+ *
+ * @param agentMessages The sub-agent's message history
+ * @param tools The tools available to the sub-agent
+ * @param permissionMode The permission mode of the parent agent
+ * @param abortSignal Optional abort signal for the classifier call
+ * @param subagentType The type of sub-agent that was spawned
+ * @param totalToolUseCount Total tool calls made by the sub-agent
+ * @returns Security warning string if flagged, null if safe
+ */
+export declare function checkHandoffSafety(agentMessages: AgentMessage[], tools: AgentTool[], permissionMode: AgentPermissionMode, abortSignal?: AbortSignal, subagentType?: string, totalToolUseCount?: number): Promise<string | null>;
+/**
+ * Check if a fork can be spawned from the current context.
+ * Per CC §XII.3:
+ * - Fork workers cannot spawn forks (isForkWorker check)
+ * - Team teammates cannot spawn other teammates (isTeamContext + name check)
+ * - In-process teammates cannot spawn background agents (isInProcessTeam check)
+ *
+ * @returns Error message if blocked, null if allowed
+ */
+export declare function checkRecursionLimits(isForkWorker: boolean, isTeamContext: boolean, isInProcessTeam: boolean, hasName: boolean, wantsBackground: boolean): string | null;

package/dist/core/sub-agent/agent-handoff-safety.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var s=(e,n)=>f(e,"name",{value:n,configurable:!0});import{emitAgentAutoModeDecision as g}from"./agent-telemetry.js";async function b(e,n,o,r,a,i){if(o!=="auto")return null;const u="Sub-agent has finished and is handing back control to the main agent. Review the sub-agent's work based on the block rules and let the main agent know if any file is dangerous (the main agent will see the reason).";try{const t=await h([...e,{role:"user",content:[{type:"text",text:u}],timestamp:Date.now()}],n,o,r);return d({decision:t.shouldBlock?"blocked":"allowed",toolName:"Agent",subagentType:a,toolUseCount:i,isHandoff:!0}),t.shouldBlock?t.unavailable?"Note: The safety classifier was unavailable when reviewing this sub-agent's work. Please carefully verify the sub-agent's actions and output before acting on them.":`SECURITY WARNING: Sub-agent performed actions that may violate security policy. Reason: ${t.reason}. Review the sub-agent's actions carefully before acting on its output.`:null}catch{return"Note: The safety classifier was unavailable when reviewing this sub-agent's work. Please carefully verify the sub-agent's actions and output before acting on them."}}s(b,"checkHandoffSafety");async function h(e,n,o,r){const a=[/\/etc\/passwd/i,/\/\.ssh\//i,/\/\.env$/i,/curl\s+.*\|\s*sh/i,/wget\s+.*\|\s*sh/i,/rm\s+-rf\s+\//i,/nc\s+/i,/netcat/i];for(const i of e){if(i.role!=="assistant")continue;const u=i.content;if(Array.isArray(u)){for(const t of u)if(t.type==="toolCall"){const l=typeof t.args=="string"?t.args:JSON.stringify(t.args??{});for(const c of a)if(c.test(l))return{shouldBlock:!0,reason:`Sub-agent tool call matched a dangerous pattern: ${c.source}`}}}}return{shouldBlock:!1}}s(h,"runHandoffClassifier");function d(e){g({decision:e.decision,toolName:e.toolName,subagentType:e.subagentType??"unknown",toolUseCount:e.toolUseCount??0,isHandoff:e.isHandoff})}s(d,"logHandoffDecision");function p(e,n,o,r,a){return e?"Fork is not available inside a forked worker. Complete your task directly using your tools.":n&&r?"Teammates cannot spawn other teammates \u2014 the team roster is flat.":o&&a?"In-process teammates cannot spawn background agents.":null}s(p,"checkRecursionLimits");export{b as checkHandoffSafety,p as checkRecursionLimits};

package/dist/core/sub-agent/agent-input-output.d.ts

@@ -0,0 +1,143 @@
+/**
+ * [WHO]: AgentInput, AgentOutputCompleted, AgentOutputAsync, AgentOutput types + JSON schema
+ * [FROM]: Depends on ./agent-definition for AgentDefinitionSource, AgentPermissionMode, AgentIsolationMode
+ * [TO]: Consumed by ./agent-tool, ./agent-registry, extensions/builtin/subagent/*
+ * [HERE]: core/sub-agent/agent-input-output.ts - Agent tool input/output types per CC §III
+ * [COVENANT]: Change schema → update Agent tool handler
+ */
+import type { AgentDefinitionSource, AgentPermissionMode, AgentIsolationMode } from "./agent-definition.js";
+/**
+ * Input schema for the Agent tool (what the LLM sees).
+ * Matches CC's AgentInputSchema exactly, adapted for Catui tool naming.
+ *
+ * ⚠️ Note from CC source:
+ * - `cwd` is omitted from the schema sent to the LLM (internal use only)
+ * - `run_in_background` may be omitted when DISABLE_BACKGROUND_TASKS is set
+ */
+export interface AgentInput {
+    /** Short (3-5 word) description of the task */
+    description: string;
+    /** The task for the agent to perform */
+    prompt: string;
+    /** The type of specialized agent to use for this task */
+    subagent_type?: string;
+    /**
+     * Optional model override for this agent.
+     * Takes precedence over the agent definition's model frontmatter.
+     * If omitted, uses the agent definition's model, or inherits from the parent.
+     */
+    model?: "sonnet" | "opus" | "haiku" | string;
+    /** Set to true to run this agent in the background. You will be notified when it completes. */
+    run_in_background?: boolean;
+    /** Name for the spawned agent. Makes it addressable via SendMessage({to: name}) while running. */
+    name?: string;
+    /** Team name for spawning. Uses current team context if omitted. */
+    team_name?: string;
+    /**
+     * Permission mode for spawned teammate.
+     * e.g. "plan" to require plan approval.
+     */
+    mode?: AgentPermissionMode;
+    /**
+     * Isolation mode.
+     * "worktree" creates a temporary git worktree so the agent works on an isolated copy of the repo.
+     */
+    isolation?: AgentIsolationMode;
+    /**
+     * Absolute path to run the agent in.
+     * Overrides the working directory for all filesystem and shell operations within this agent.
+     * Mutually exclusive with isolation: "worktree".
+     * ⚠️ NOT shown to the LLM in CC (omitted from public schema).
+     */
+    cwd?: string;
+}
+export interface AgentUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens: number | null;
+    cache_read_input_tokens: number | null;
+    server_tool_use: {
+        web_search_requests: number;
+        web_fetch_requests: number;
+    } | null;
+    service_tier: ("standard" | "priority" | "batch") | null;
+    cache_creation: {
+        ephemeral_1h_input_tokens: number;
+        ephemeral_5m_input_tokens: number;
+    } | null;
+}
+/**
+ * Output when an agent completes synchronously.
+ * Matches CC's AgentOutputCompleted exactly.
+ */
+export interface AgentOutputCompleted {
+    /** Unique identifier for this agent run */
+    agentId: string;
+    /** The agent type that was used */
+    agentType?: string;
+    /** Text content blocks from the final assistant message */
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    /** Total number of tool calls made by this agent */
+    totalToolUseCount: number;
+    /** Total wall-clock time in milliseconds */
+    totalDurationMs: number;
+    /** Total tokens consumed */
+    totalTokens: number;
+    /** Token usage breakdown */
+    usage: AgentUsage;
+    /** Completion status — always "completed" for this type */
+    status: "completed";
+    /** The original prompt text */
+    prompt: string;
+}
+/**
+ * Output when an agent is launched asynchronously (background mode).
+ * Matches CC's AgentOutputAsync exactly.
+ */
+export interface AgentOutputAsync {
+    /** Status — always "async_launched" for this type */
+    status: "async_launched";
+    /** Unique identifier for this agent run */
+    agentId: string;
+    /** Short description of the task */
+    description: string;
+    /** The original prompt text */
+    prompt: string;
+    /** Path to the output file where results will be written */
+    outputFile: string;
+    /** Whether the parent agent has Read/Bash tools to check the output file */
+    canReadOutputFile?: boolean;
+}
+/** Output from the Agent tool — either completed synchronously or launched asynchronously. */
+export type AgentOutput = AgentOutputCompleted | AgentOutputAsync;
+/**
+ * Internal metadata tracked during an agent spawn.
+ * Not returned to the LLM — used internally for bookkeeping.
+ */
+export interface AgentSpawnMetadata {
+    agentId: string;
+    agentType: string;
+    prompt: string;
+    description: string;
+    startTime: number;
+    isFork: boolean;
+    isAsync: boolean;
+    resolvedModel?: string;
+    isBuiltInAgent: boolean;
+    source: AgentDefinitionSource;
+    color?: string;
+    worktreeResult?: WorktreeSpawnResult;
+}
+/** Result from worktree creation during agent spawn. */
+export interface WorktreeSpawnResult {
+    worktreePath: string;
+    worktreeBranch?: string;
+    headCommit: string;
+    gitRoot?: string;
+    hookBased?: boolean;
+}
+export declare function isAgentOutputCompleted(output: AgentOutput): output is AgentOutputCompleted;
+export declare function isAgentOutputAsync(output: AgentOutput): output is AgentOutputAsync;

package/dist/core/sub-agent/agent-input-output.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var e=(t,n)=>u(t,"name",{value:n,configurable:!0});function c(t){return t.status==="completed"}e(c,"isAgentOutputCompleted");function o(t){return t.status==="async_launched"}e(o,"isAgentOutputAsync");export{o as isAgentOutputAsync,c as isAgentOutputCompleted};

package/dist/core/sub-agent/agent-output-persistence.d.ts

@@ -0,0 +1,43 @@
+/**
+ * [WHO]: getOutputFilePath, writeAgentOutputFile, getTasksDir — file-based output persistence per CC §XI.3
+ * [FROM]: Depends on node:fs/promises, node:path for file I/O
+ * [TO]: Consumed by ./agent-tool (async execution path)
+ * [HERE]: core/sub-agent/agent-output-persistence.ts - Output file persistence per CC §XI.3 (lY/qR6)
+ * [COVENANT]: Change output path → update agent-input-output.ts outputFile field
+ */
+/**
+ * Get the tasks directory path.
+ * Matches CC's qR6() function: <project>/.claude/tasks/ → <project>/.catui/tasks/
+ *
+ * Per CC §19: Catui uses .catui/ instead of .claude/
+ */
+export declare function getTasksDir(cwd: string): string;
+/**
+ * Get the output file path for an agent.
+ * Matches CC's lY() function: qR6() + `<agentId>.output`
+ *
+ * Per CC §6.2 step 16: outputFile = lY(agentId)
+ */
+export declare function getOutputFilePath(agentId: string, cwd: string): string;
+/**
+ * Write the agent's output to a file.
+ * Per CC §11.3: async agent results are passed via filesystem.
+ * The output file contains the last assistant message's text.
+ *
+ * Matches CC's async output writing in LS8.
+ */
+export declare function writeAgentOutputFile(agentId: string, cwd: string, output: string): Promise<string>;
+/**
+ * Write a structured AgentOutputCompleted to the output file.
+ * Used when an async agent completes and writes its final result.
+ */
+export declare function writeAgentOutputCompleted(agentId: string, cwd: string, output: import("./agent-input-output.js").AgentOutputCompleted): Promise<string>;
+/**
+ * Read an agent's output file (for checking progress of background agents).
+ * Per CC §11.3: parent agent can use Read tool to check the outputFile.
+ */
+export declare function readAgentOutputFile(agentId: string, cwd: string): Promise<string | undefined>;
+/**
+ * Check if an agent's output file exists.
+ */
+export declare function agentOutputFileExists(agentId: string, cwd: string): Promise<boolean>;

package/dist/core/sub-agent/agent-output-persistence.js

@@ -0,0 +1,3 @@
+var s=Object.defineProperty;var r=(t,e)=>s(t,"name",{value:e,configurable:!0});import{mkdir as p,writeFile as f,readFile as l}from"node:fs/promises";import{join as o}from"node:path";function c(t){return o(t,".catui","tasks")}r(c,"getTasksDir");function a(t,e){return o(c(e),`${t}.output`)}r(a,"getOutputFilePath");async function x(t,e,n){const i=a(t,e),u=c(e);return await p(u,{recursive:!0}),await f(i,n,"utf-8"),i}r(x,"writeAgentOutputFile");async function d(t,e,n){const i=n.content.map(u=>u.text).join(`
+
+`);return x(t,e,i)}r(d,"writeAgentOutputCompleted");async function g(t,e){const n=a(t,e);try{return await l(n,"utf-8")}catch{return}}r(g,"readAgentOutputFile");async function y(t,e){const n=a(t,e);try{const{access:i}=await import("node:fs/promises");return await i(n),!0}catch{return!1}}r(y,"agentOutputFileExists");export{y as agentOutputFileExists,a as getOutputFilePath,c as getTasksDir,g as readAgentOutputFile,d as writeAgentOutputCompleted,x as writeAgentOutputFile};

package/dist/core/sub-agent/agent-prompt-builder.d.ts

@@ -0,0 +1,37 @@
+/**
+ * [WHO]: buildNotesSystemPrompt, buildWorktreeNotes — system prompt building per CC §X (Z18)
+ * [FROM]: Depends on ./agent-definition for AgentSystemPromptContext
+ * [TO]: Consumed by ./agent-tool
+ * [HERE]: core/sub-agent/agent-prompt-builder.ts - System prompt Notes injection per CC §X (Z18)
+ * [COVENANT]: Change prompt structure → update agent-tool handler
+ */
+/**
+ * Build the "Notes:" system prompt section that lists working directories.
+ * Matches CC's Z18() function exactly.
+ *
+ * Per CC §10.3:
+ * - Z18() prepends a "Notes:" section listing all working directories
+ * - Used when sub-agent has worktree/cwd override
+ * - The section starts with "Notes:" then lists all dirs
+ *
+ * Example output:
+ *   Notes:
+ *   - Working directory: /path/to/worktree
+ *   - Working directory: /path/to/original/project
+ */
+export declare function buildNotesSystemPrompt(additionalWorkingDirs: string[]): string;
+/**
+ * Build worktree-specific notes.
+ * Per CC §10.3: when isolation === "worktree" or cwd is overridden,
+ * Z18 injects working directory notes into the system prompt.
+ *
+ * The worktree path is the primary working dir.
+ * The original project root is listed as an additional reference dir.
+ */
+export declare function buildWorktreeNotes(worktreePath: string, originalProjectRoot?: string): string;
+/**
+ * Build cwd override notes.
+ * Per CC §10.3: when cwd is overridden (not worktree),
+ * Z18 injects the override cwd as a working directory note.
+ */
+export declare function buildCwdOverrideNotes(overrideCwd: string, originalCwd?: string): string;

package/dist/core/sub-agent/agent-prompt-builder.js

@@ -0,0 +1,2 @@
+var r=Object.defineProperty;var s=(t,e)=>r(t,"name",{value:e,configurable:!0});function u(t){return t.length?["Notes:",...t.map(n=>`- Working directory: ${n}`)].join(`
+`):""}s(u,"buildNotesSystemPrompt");function f(t,e){const n=[t];return e&&e!==t&&n.push(e),u(n)}s(f,"buildWorktreeNotes");function c(t,e){const n=[t];return e&&e!==t&&n.push(e),u(n)}s(c,"buildCwdOverrideNotes");export{c as buildCwdOverrideNotes,u as buildNotesSystemPrompt,f as buildWorktreeNotes};