catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/plan/exit-plan-mode-tool.js

@@ -0,0 +1,13 @@
+var j=Object.defineProperty;var w=(a,i)=>j(a,"name",{value:i,configurable:!0});import{Type as f}from"@sinclair/typebox";import{Container as b,Text as p}from"@catui/tui";import{PLAN_CUSTOM_TYPE as P}from"./types.js";import{handlePlanModeExit as y}from"./plan-permissions.js";import{getPlanFilePath as I,getPlan as R,getPlansDirectory as A,serializePlanSessionState as h,writePlan as F}from"./plan-file-manager.js";import{getExitPlanModeApprovedResult as C}from"./plan-workflow-prompt.js";import{validatePlan as U,formatValidationMessage as _}from"./plan-validation.js";import{setPendingClearContextPlan as q}from"./clear-context-state.js";import{isInTeammateContext as k,submitPlanToLeader as N,formatPlanSubmittedMessage as W}from"./teammate-approval.js";const B=f.Object({plan:f.Optional(f.String({description:"Edited plan content from external editor (optional)"})),forceExit:f.Optional(f.Boolean({description:"Force exit even if plan validation fails (for trivial changes)"})),allowedPrompts:f.Optional(f.Array(f.Object({tool:f.String({description:"Tool name (e.g. 'Bash')"}),prompt:f.String({description:"Semantic description of the permitted action"})}),{description:"Pre-approved tool permission rules for the implementation phase"}))});function D(a,i){const t=new b;t.addChild(new p(i.fg("toolTitle",i.bold("ExitPlanMode")),0,0));const s=a,o="plan"in s&&typeof s.plan=="string"?s.plan:void 0;if(o){t.addChild(new p("",0,0)),t.addChild(new p(i.fg("accent","Plan preview:")+(o.length>1200?i.fg("muted"," (truncated)"):""),0,0));const d=o.slice(0,1200);for(const e of d.split(`
+`))t.addChild(new p(i.fg("text",`  ${e}`),0,0))}else t.addChild(new p(i.fg("muted","  Requesting plan approval..."),0,0));const c="allowedPrompts"in s&&Array.isArray(s.allowedPrompts)?s.allowedPrompts:void 0;if(c&&c.length>0){t.addChild(new p("",0,0)),t.addChild(new p(i.fg("accent","Requested permissions:"),0,0));for(const d of c)t.addChild(new p(i.fg("toolOutput",`  - ${d.tool}: ${d.prompt}`),0,0))}return t}w(D,"renderCallForExitPlanMode");function K(a,i,t){const s=new b,o=a.isError===!0,c=a.content?.filter(d=>d.type==="text").map(d=>d.type==="text"?d.text:"").join(`
+`);if(c)if(o)s.addChild(new p(t.fg("error",c),0,0));else{s.addChild(new p(t.fg("success","Plan approved"),0,0));const d=c.length>300?c.slice(0,300)+"...":c;s.addChild(new p(t.fg("toolOutput",d),0,0))}return s}w(K,"renderResultForExitPlanMode");function ee(a,i,t){return{name:"ExitPlanMode",label:"Exit Plan Mode",description:"Present your plan for approval and start coding. Only usable in plan mode after writing a plan.",parameters:B,renderCall:D,renderResult:K,execute:w(async(s,o,c,d,e)=>{A(e.getSettings().plansDirectory,e.cwd);const r=i();if(r.state.mode!=="plan")return{content:[{type:"text",text:"You are not in plan mode. This tool is only for exiting plan mode after writing a plan. If your plan was already approved, continue with implementation."}],isError:!0,details:null};const x="plan"in o&&typeof o.plan=="string"?o.plan:void 0,S="forceExit"in o&&o.forceExit===!0,m=I(a.events),M=R(a.events),n=x??M,v=x!==void 0;if(v&&n!==null&&await F(a.events,n),r.state.planSnapshot=n??void 0,!S){const l=U(n||"");if(!l.valid)return{content:[{type:"text",text:`Plan validation failed:
+
+${_(l)}
+
+Please add the missing sections and try again, or use forceExit: true for trivial changes.`}],isError:!0,details:null}}if(k()){if(!n||n.trim().length===0)throw new Error(`No plan file found at ${m}. Please write your plan to this file before calling ExitPlanMode.`);try{const{requestId:l}=await N(m,n||""),E=W(l,m);return r.state.mode="plan",a.appendEntry(P,h(r)),e.abort(),{content:[{type:"text",text:E}],details:null}}catch(l){console.error(`Failed to submit plan to leader: ${l}`)}}if(!e.hasUI)throw e.abort(),new Error("ExitPlanMode requires user approval, but no interactive UI is available. Stay in plan mode and ask the user to approve from an interactive session.");const u="allowedPrompts"in o&&Array.isArray(o.allowedPrompts)?o.allowedPrompts:void 0,T=n&&n.trim().length>0?n.trim().slice(0,1200):"No plan content was written.",O=u&&u.length>0?`
+Requested permissions:
+${u.map(l=>`  - ${l.tool}: ${l.prompt}`).join(`
+`)}
+`:"",g=await e.ui.select(["Plan ready for review:",`Plan file: ${m}`,"",T,n&&n.length>1200?`
+...(truncated)`:"",O,"Choose next action:"].join(`
+`),["Execute plan (standard)","Execute plan (elevated mode)","Execute plan (clear context + elevated)","Keep planning","Reject plan"]);if(g==="Keep planning")throw e.abort(),new Error("User chose to keep planning. Stay in plan mode, revise the plan file, and call ExitPlanMode again when ready.");if(g==="Reject plan")throw e.abort(),new Error("User rejected the plan. Stay in plan mode and revise the plan based on user feedback.");if(u&&(r.state.lastAllowedPrompts=u),g==="Execute plan (clear context + elevated)"){y(r),r.state.mode="bypassPermissions",a.appendEntry(P,h(r)),e.ui.setStatus("plan",void 0),e.ui.setWidget("plan-mode",void 0);const l=n?n.trim().slice(0,8e3):"(no plan content)";return q(l),await a.executeCommand("/new"),e.ui.notify("Plan approved. Starting fresh context with elevated permissions.","info"),{content:[{type:"text",text:"Plan approved. New context started with elevated permissions. The plan has been injected as the initial message."}],details:null}}if(g==="Execute plan (elevated mode)"){y(r),r.state.mode="bypassPermissions",a.appendEntry(P,h(r)),e.ui.setStatus("plan",void 0),e.ui.setWidget("plan-mode",void 0);const l=C(n,m,v,t(),u);return e.ui.notify("Plan approved. Elevated mode active.","info"),{content:[{type:"text",text:l}],details:null}}y(r),a.appendEntry(P,h(r)),e.ui.setStatus("plan",void 0),e.ui.setWidget("plan-mode",void 0);const $=C(n,m,v,t(),u);return e.ui.notify("Plan approved. Implementation mode active.","info"),{content:[{type:"text",text:$}],details:null}},"execute")}}w(ee,"createExitPlanModeTool");export{ee as createExitPlanModeTool};

package/dist/extensions/builtin/plan/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: planExtension - registers /plan command, EnterPlanMode/ExitPlanMode tools, plan mode state management, permission gating, and workflow prompt injection
+ * [FROM]: Depends on core/extensions-host/types, ./types, ./plan-file-manager, ./plan-permissions, ./plan-workflow-prompt, ./enter-plan-mode-tool, ./exit-plan-mode-tool, ./plan-agents
+ * [TO]: Auto-loaded by builtin-extensions.ts as a default extension
+ * [HERE]: extensions/builtin/plan/index.ts - main plan mode extension entry point
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+export default function planExtension(api: ExtensionAPI): Promise<void>;

package/dist/extensions/builtin/plan/index.js

@@ -0,0 +1,24 @@
+var U=Object.defineProperty;var u=(e,t)=>U(e,"name",{value:t,configurable:!0});import{getPlanSessionState as L,getPlanFilePath as h,getPlan as P,writePlan as M,getPlansDirectory as D,serializePlanSessionState as q}from"./plan-file-manager.js";import{handlePlanModeTransition as j,shouldAllowToolCall as V}from"./plan-permissions.js";import{getPlanModeInstructions as R,getPlanModeExitInstructions as H,getPlanModeReentryInstructions as b}from"./plan-workflow-prompt.js";import{createEnterPlanModeTool as W}from"./enter-plan-mode-tool.js";import{createExitPlanModeTool as k}from"./exit-plan-mode-tool.js";import{getAndClearPendingPlan as B}from"./clear-context-state.js";import{PLAN_CUSTOM_TYPE as J}from"./types.js";const $={TURNS_BETWEEN_ATTACHMENTS:3,FULL_REMINDER_EVERY_N:3},Y=[{value:"open",label:"open",description:"Edit the current plan"},{value:"exit",label:"exit",description:"Ask to leave plan mode"},{value:"validate",label:"validate",description:"Check the current plan"},{value:"approve",label:"approve",description:"Approve a teammate plan"}];function z(e,t){if(t&&t.tokenIndex>0)return null;const d=e.trim().toLowerCase(),p=Y.filter(m=>m.value.startsWith(d));return p.length>0?p.map(m=>({...m})):null}u(z,"getPlanArgumentCompletions");function G(e){return e.sessionManager.getBranch().filter(t=>{if(t.type!=="message"||t.message.role!=="user")return!1;const d=t.message.content;return typeof d=="string"?d.trim().length>0:d.some(p=>p.type==="text"&&p.text.trim().length>0)}).length}u(G,"countHumanTurns");function T(e){const t=e.getSettings();D(t.plansDirectory,e.cwd)}u(T,"preparePlansDirectory");function f(e,t){return L(e.events,t?.sessionManager.getSessionId(),t?.sessionManager.getEntries())}u(f,"getSessionState");function y(e,t){e.appendEntry(J,q(t))}u(y,"persistPlanState");function I(e,t){const d=h(t.events);e.ui.setStatus("plan","Plan mode"),e.ui.setWidget("plan-mode",["PLAN MODE",`Plan: ${d}`,"Read-only except the plan file","Use /plan open to edit; /plan exit requests approval"],{placement:"aboveEditor"})}u(I,"setPlanModeUi");async function K(e,t,d){T(t);const p=f(e,t),m=p.state.mode;j(p),p.state.prePlanMode=m,p.state.mode="plan",I(t,e),y(e,p),t.ui.notify("Enabled plan mode. Read-only except the plan file.","info"),d&&e.sendUserMessage(d,{deliverAs:"followUp"})}u(K,"enterPlanMode");function O(e,t){return e.getActiveTools().includes(t)}u(O,"hasTool");function Q(e,t){T(t);const d=h(e.events),p=P(e.events);if(!p){t.ui.notify("Already in plan mode. No plan written yet.","warning");return}const m=["Current Plan",`Path: ${d}`,"",p,"",process.env.VISUAL||process.env.EDITOR?`Use /plan open to edit this plan in ${process.env.VISUAL||process.env.EDITOR}.`:"Use /plan open to edit this plan."];t.ui.notify(m.join(`
+`),"info")}u(Q,"displayPlan");async function X(e){const t=W(e,()=>f(e),()=>!1),d=k(e,()=>f(e),()=>O(e,"Agent")||O(e,"Task"));e.registerTool(t),e.registerTool(d);const p=u(async(a,n)=>{if(T(n),f(e,n).state.mode!=="plan"){const s=a.trim(),i=s.length>0&&s!=="open"&&s!=="exit"?s:"";await K(e,n,i);return}const l=a.trim();if(l==="open"){const s=h(e.events);if(P(e.events)||await M(e.events,""),process.env.VISUAL||process.env.EDITOR){if(await n.ui.openExternalEditor(s,"Edit Plan")){const c=f(e,n);c.state.planSnapshot=P(e.events)??void 0,y(e,c),n.ui.notify(`Opened plan in editor: ${s}`,"info")}else n.ui.notify("Failed to open plan in external editor.","warning");return}const i=await n.ui.editor("Edit Plan",P(e.events)||"");if(i===void 0){n.ui.notify("Plan editing cancelled.","info");return}await M(e.events,i);const v=f(e,n);v.state.planSnapshot=i,y(e,v),n.ui.notify(`Plan saved to: ${s}`,"info");return}if(l==="exit"){try{await d.execute("plan-exit",{forceExit:!0},void 0,void 0,n)}catch(s){const i=s instanceof Error?s.message:String(s);n.ui.notify(i,"warning")}return}Q(e,n)},"handlePlanCommand"),m=u(async(a,n)=>{const{validatePlan:r,formatValidationMessage:o}=await import("./plan-validation.js"),l=h(e.events),s=P(e.events);if(!s){n.ui.notify("No plan found. Write a plan first using the write tool.","warning");return}const i=r(s),v=o(i);i.valid?n.ui.notify(`Plan validation passed:
+${v}`,"info"):n.ui.notify(`Plan validation failed:
+${v}`,"warning")},"handlePlanValidateCommand");e.registerCommand("plan:validate",{description:"Validate the current plan structure",handler:m});const N=u(async(a,n)=>{const r=await import("node:fs"),o=await import("node:os"),l=await import("node:path"),s=l.join(o.homedir(),".catui","agent","team-mail"),i=a.trim();if(!i){if(!r.existsSync(s)){n.ui.notify("No pending plan approval requests.","info");return}const w=r.readdirSync(s).filter(S=>S.startsWith("plan_approval-")&&S.endsWith(".json"));if(w.length===0){n.ui.notify("No pending plan approval requests.","info");return}const F=w.map(S=>{const A=r.readFileSync(l.join(s,S),"utf-8"),C=JSON.parse(A);return`- Request ID: ${C.requestId}
+  From: ${C.from}
+  Time: ${new Date(C.timestamp).toLocaleString()}`});n.ui.notify(`Pending plan approval requests:
+
+`+F.join(`
+
+`)+"\n\nUse `/plan:approve <request-id>` to approve.","info");return}const v=l.join(s,`${i}.json`);if(!r.existsSync(v)){n.ui.notify(`Request not found: ${i}`,"error");return}const g=r.readFileSync(v,"utf-8"),c=JSON.parse(g),E={type:"plan_approval_response",requestId:i,approved:!0,approvedBy:"leader",timestamp:new Date().toISOString()},_=l.join(s,`response-${i}.json`);r.writeFileSync(_,JSON.stringify(E,null,2),"utf-8"),n.ui.notify(`Plan approved for ${c.from}.
+
+Plan content:
+\`\`\`
+${c.planContent.slice(0,500)}${c.planContent.length>500?`
+...(truncated)`:""}
+\`\`\`
+
+The teammate can now proceed with implementation.`,"info")},"handlePlanApproveCommand");e.registerCommand("plan:approve",{description:"Approve a teammate's plan (for team leaders)",handler:N}),e.registerCommand("plan",{description:"Plan, edit, validate, approve, or exit the current session plan",getArgumentCompletions:z,handler:u(async(a,n)=>{const[r,...o]=a.trim().split(/\s+/);if(r==="validate"){await m("",n);return}if(r==="approve"){await N(o.join(" "),n);return}await p(a,n)},"handler")}),e.on("tool_call",a=>{if(f(e).state.mode!=="plan")return;const r={toolName:a.toolName,toolCallId:a.toolCallId,input:a.input},o=h(e.events),l=V(r,o,e.cwd);if(!l.allowed)return{block:!0,reason:l.reason}}),e.on("before_agent_start",async(a,n)=>{const r=B();if(r)return{appendSystemPrompt:`## Plan to Implement
+
+The user approved the following plan in a previous context. Implement it now:
+
+${r}`};T(n);const o=f(e,n),{mode:l,needsPlanModeExitAttachment:s,hasExitedPlanModeInSession:i,planAttachmentCount:v}=o.state;if(l!=="plan"&&s){o.state.needsPlanModeExitAttachment=!1,y(e,o);const g=h(e.events),c=P(e.events)!==null;return{appendSystemPrompt:H(g,c,o.state.lastAllowedPrompts)}}if(l==="plan"){I(n,e);const g=h(e.events),c=P(e.events),E=G(n);if(o.state.lastPlanAttachmentHumanTurn!==void 0&&E-o.state.lastPlanAttachmentHumanTurn<$.TURNS_BETWEEN_ATTACHMENTS)return;if(i&&c!==null){o.state.hasExitedPlanModeInSession=!1,o.state.lastPlanAttachmentHumanTurn=E,y(e,o);const S=b(g),A=R(o,g,c,"full");return{appendSystemPrompt:S+`
+
+`+A}}const w=v%$.FULL_REMINDER_EVERY_N===0?"full":"sparse";return o.state.planAttachmentCount+=1,o.state.lastPlanAttachmentHumanTurn=E,o.state.planSnapshot=c??void 0,y(e,o),{appendSystemPrompt:R(o,g,c,w)}}}),e.registerShortcut("alt+g",{description:"Open plan file in external editor",handler:u(async a=>{if(f(e,a).state.mode!=="plan"){a.ui.notify("Not in plan mode.","info");return}const r=h(e.events);if(P(e.events)||await M(e.events,""),process.env.VISUAL||process.env.EDITOR)if(await a.ui.openExternalEditor(r,"Edit Plan")){const l=f(e,a);l.state.planSnapshot=P(e.events)??void 0,y(e,l),a.ui.notify(`Opened plan in editor: ${r}`,"info")}else a.ui.notify("Failed to open plan in external editor.","warning");else a.ui.notify("No $VISUAL or $EDITOR set. Cannot open external editor.","warning")},"handler")}),e.on("session_start",(a,n)=>{T(n),f(e,n).state.mode==="plan"&&I(n,e)}),e.on("session_shutdown",()=>{})}u(X,"planExtension");export{X as default};

package/dist/extensions/builtin/plan/plan-agents.d.ts

@@ -0,0 +1,23 @@
+/**
+ * [WHO]: createExploreAgentSpec(), createPlanAgentSpec(), getExploreAgentCount(), getPlanAgentCount()
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by model during plan mode workflow (via subagent spawning)
+ * [HERE]: extensions/builtin/plan/plan-agents.ts - Explore/Plan subagent definitions for plan mode
+ */
+export declare function getExploreAgentCount(): number;
+export declare function getPlanAgentCount(): number;
+/**
+ * Prompt for the Explore subagent.
+ * Focuses on codebase search and pattern identification.
+ */
+export declare function getExploreAgentPrompt(taskDescription: string, searchFocus: string): string;
+/**
+ * Prompt for the Plan subagent.
+ * Focuses on implementation design based on exploration results.
+ */
+export declare function getPlanAgentPrompt(taskDescription: string, explorationResults: string, contextFiles: string): string;
+/**
+ * List of tool names available to Explore/Plan subagents.
+ * Restricted to read-only operations.
+ */
+export declare const PLAN_SUBAGENT_TOOLS: string[];

package/dist/extensions/builtin/plan/plan-agents.js

@@ -0,0 +1,43 @@
+var s=Object.defineProperty;var o=(t,e)=>s(t,"name",{value:e,configurable:!0});function r(){const t=process.env.CATUI_PLAN_EXPLORE_AGENT_COUNT??process.env.NANOPENCIL_PLAN_EXPLORE_AGENT_COUNT;if(t){const e=parseInt(t,10);if(!isNaN(e)&&e>=1&&e<=10)return e}return 3}o(r,"getExploreAgentCount");function a(){const t=process.env.CATUI_PLAN_AGENT_COUNT??process.env.NANOPENCIL_PLAN_AGENT_COUNT;if(t){const e=parseInt(t,10);if(!isNaN(e)&&e>=1&&e<=10)return e}return 1}o(a,"getPlanAgentCount");function c(t,e){return`You are an Explore agent. Your job is to search the codebase to understand how to implement the following task:
+
+**Task**: ${t}
+
+**Your specific focus**: ${e}
+
+Instructions:
+1. Use read, grep, find, ls, and time tools to search the codebase
+2. Look for existing functions, tools, patterns, and architectural approaches that can be reused
+3. Search for related components, utilities, and modules
+4. Report your findings with specific file paths and function names
+5. Do NOT write or edit any files
+6. Do NOT run bash commands that modify the filesystem
+7. Do NOT call ExitPlanMode or EnterPlanMode
+8. Do NOT spawn other agents
+
+Be thorough but focused on your specific search area. Report concrete findings with file paths.`}o(c,"getExploreAgentPrompt");function p(t,e,n){return`You are a Plan agent (software architect). Your job is to design an implementation approach for the following task:
+
+**Task**: ${t}
+
+## Exploration Results from Phase 1:
+${e}
+
+## Relevant Context Files:
+${n}
+
+Instructions:
+1. Design a concrete implementation approach based on the exploration results
+2. Identify the key files that need to be modified
+3. Describe the approach step by step
+4. Reference specific existing functions and utilities that should be reused
+5. Consider trade-offs and potential risks
+6. Do NOT write or edit any files
+7. Do NOT run bash commands that modify the filesystem
+8. Do NOT call ExitPlanMode or EnterPlanMode
+9. Do NOT spawn other agents
+
+Your output should include:
+- Recommended approach with rationale
+- List of critical files to modify
+- Existing code to reuse
+- Step-by-step implementation strategy
+- Verification approach`}o(p,"getPlanAgentPrompt");const l=["read","grep","find","ls","time"];export{l as PLAN_SUBAGENT_TOOLS,r as getExploreAgentCount,c as getExploreAgentPrompt,a as getPlanAgentCount,p as getPlanAgentPrompt};

package/dist/extensions/builtin/plan/plan-file-manager.d.ts

@@ -0,0 +1,26 @@
+/**
+ * [WHO]: PlanFileManager class, getPlansDirectory(), getPlanFilePath(), getPlan(), getPlanSlug()
+ * [FROM]: Depends on node:fs, node:path, node:os, node:crypto, proper-lockfile, core/extensions-host/types (EventBus)
+ * [TO]: Consumed by plan extension tools, workflow prompts, permission gating
+ * [HERE]: extensions/builtin/plan/plan-file-manager.ts - plan file path management and I/O
+ */
+import { type PlanSessionState, type PlanStateEntryData } from "./types.js";
+import type { SessionEntry } from "../../../core/session/session-manager.js";
+export declare function getPlanSessionState(bus: unknown, sessionId?: string, entries?: SessionEntry[]): PlanSessionState;
+export declare function hydratePlanSessionState(sessionState: PlanSessionState, sessionId: string, entries: SessionEntry[]): void;
+export declare function serializePlanSessionState(sessionState: PlanSessionState): PlanStateEntryData;
+export declare function generatePlanSlug(): string;
+export declare function getPlansDirectory(settingsPlansDir?: string, cwd?: string): string;
+export declare function resetPlansDirectoryCache(): void;
+export declare function getPlanSlug(bus: unknown): string;
+export declare function setPlanSlug(bus: unknown, slug: string): void;
+export declare function clearPlanSlug(bus: unknown): void;
+export declare function clearAllPlanSlugs(): void;
+export declare function getPlanFilePath(bus: unknown, agentId?: string): string;
+export declare function getPlan(bus: unknown, agentId?: string): string | null;
+export declare function writePlan(bus: unknown, content: string, agentId?: string): Promise<boolean>;
+export declare function planExists(bus: unknown, agentId?: string): boolean;
+export declare function copyPlanForResume(sourceBus: unknown, targetBus: unknown): Promise<boolean>;
+export declare function copyPlanForFork(sourceBus: unknown, targetBus: unknown): Promise<boolean>;
+export declare function copyPlanFileToNewSlug(bus: unknown): Promise<boolean>;
+export declare function copyPlanFile(sourcePath: string, targetPath: string): boolean;

package/dist/extensions/builtin/plan/plan-file-manager.js

@@ -0,0 +1 @@
+var E=Object.defineProperty;var r=(e,t)=>E(e,"name",{value:t,configurable:!0});import{copyFileSync as b,existsSync as k,mkdirSync as i,readFileSync as w,renameSync as C,writeFileSync as T}from"node:fs";import{homedir as $}from"node:os";import{dirname as g,join as c,resolve as F,sep as I}from"node:path";import{PLAN_CUSTOM_TYPE as j}from"./types.js";const s=["gentle","swift","bright","calm","deep","eager","fair","grand","keen","light","bold","warm","wise","free","pure","rich","safe","sure","tall","vast","wild","zany","noble","proud","brave","clever","daring","elegant","fierce","graceful","humble","nimble","rapid","sharp","silent","solid","steady","strong","subtle","super","vivid","witty","active","agile","ample","brisk","cosmic","curious","digital","distant","divine","epic","famous","fancy","flying","galactic","golden","happy","holy","huge","jolly","jumpy","lively","lucky","magic","major","merry","mighty","modern","mystic","native","orange","peaceful","perfect","pink","polar","polite","prime","purple","quick","quiet","random","rare","real","red","royal","sacred","shiny","simple","sleek","smart","smooth","soft","sparse","speedy","stellar","sunny","sweet","tender","tiny","top","ultra","unique","urban","vital","white","wonder","young"],y=["engelbart","hopper","lovelace","turing","knuth","dijkstra","pascal","bayes","fourier","gauss","hilbert","neumann","boole","shannon","pearl","minsky","mccarthy","ritchie","thompson","torvalds","berners-lee","hamilton","lampson","kay","gosling","wall","matz","ikea","nova","echo","flux","prism","orbit","pulse","spark","drift","crest","peak","tide","wave","breeze","stone","forge","bridge","canyon","delta","ember","falcon","grove","harbor","ivory","jewel","knot","lunar","maple","nexus","oasis","phoenix","quest","raven","summit","trail","unity","vertex","willow","atlas","beacon","comet","dusk","eagle","flame","globe","horizon","iris","jade","kite","lotus","meteor","nebula","oak","panda","quartz","reef","star","tiger","umbra","vortex","wolf","zenith"],d=c($(),".catui","plans"),z=10,P=new WeakMap,x=new Set;function f(e,t,a){const n=e;let o=P.get(n);return o||(o={state:{mode:"default",prePlanMode:"default",needsPlanModeExitAttachment:!1,hasExitedPlanModeInSession:!1,planAttachmentCount:0,sessionId:t},planSlugCache:void 0},P.set(n,o),x.add(o)),t&&o.state.hydratedSessionId!==t&&N(o,t,a??[]),o}r(f,"getPlanSessionState");function N(e,t,a){e.state.hydratedSessionId=t,e.state.sessionId=t;for(let n=a.length-1;n>=0;n--){const o=a[n];if(o.type!=="custom"||o.customType!==j)continue;const l=o.data;if(!(!l||l.version!==1)&&!(l.sessionId&&l.sessionId!==t)){e.state.mode=l.mode??"default",e.state.prePlanMode=l.prePlanMode??"default",e.state.needsPlanModeExitAttachment=l.needsPlanModeExitAttachment??!1,e.state.hasExitedPlanModeInSession=l.hasExitedPlanModeInSession??!1,e.state.planAttachmentCount=l.planAttachmentCount??0,e.state.lastPlanAttachmentHumanTurn=l.lastPlanAttachmentHumanTurn,e.state.planSlug=l.planSlug,e.state.planSnapshot=l.planSnapshot,e.state.lastAllowedPrompts=l.lastAllowedPrompts,e.planSlugCache=l.planSlug;return}}e.state.mode="default",e.state.prePlanMode="default",e.state.needsPlanModeExitAttachment=!1,e.state.hasExitedPlanModeInSession=!1,e.state.planAttachmentCount=0,e.state.lastPlanAttachmentHumanTurn=void 0,e.state.planSlug=void 0,e.state.planSnapshot=void 0,e.state.lastAllowedPrompts=void 0,e.planSlugCache=void 0}r(N,"hydratePlanSessionState");function O(e){return{version:1,sessionId:e.state.sessionId,mode:e.state.mode,prePlanMode:e.state.prePlanMode,needsPlanModeExitAttachment:e.state.needsPlanModeExitAttachment,hasExitedPlanModeInSession:e.state.hasExitedPlanModeInSession,planAttachmentCount:e.state.planAttachmentCount,lastPlanAttachmentHumanTurn:e.state.lastPlanAttachmentHumanTurn,planSlug:e.planSlugCache??e.state.planSlug,planSnapshot:e.state.planSnapshot,lastAllowedPrompts:e.state.lastAllowedPrompts}}r(O,"serializePlanSessionState");function D(){const e=s[Math.floor(Math.random()*s.length)],t=s[Math.floor(Math.random()*s.length)],a=y[Math.floor(Math.random()*y.length)];return`${e}-${t}-${a}`}r(D,"generatePlanSlug");let u,m;function S(e,t){const a=`${t??""}\0${e??""}`;if(u&&!e&&!t||u&&m===a)return u;if(e&&t){const n=F(t,e);!n.startsWith(t+I)&&n!==t?(i(d,{recursive:!0}),u=d):(i(n,{recursive:!0}),u=n)}else i(d,{recursive:!0}),u=d;return m=a,u}r(S,"getPlansDirectory");function W(){u=void 0,m=void 0}r(W,"resetPlansDirectoryCache");function v(e){const t=f(e);if(t.planSlugCache)return t.planSlugCache;const a=S();let n;for(let o=0;o<z;o++){n=D();const l=c(a,`${n}.md`);if(!k(l))break}return n=n,t.planSlugCache=n,t.state.planSlug=n,n}r(v,"getPlanSlug");function _(e,t){const a=f(e);a.planSlugCache=t,a.state.planSlug=t}r(_,"setPlanSlug");function A(e){const t=f(e);t.planSlugCache=void 0,t.state.planSlug=void 0}r(A,"clearPlanSlug");function G(){for(const e of x)e.planSlugCache=void 0,e.state.planSlug=void 0}r(G,"clearAllPlanSlugs");function M(e,t){const a=v(e),n=S();return t?c(n,`${a}-agent-${t}.md`):c(n,`${a}.md`)}r(M,"getPlanFilePath");function p(e,t){const a=M(e,t);try{return w(a,"utf-8")}catch(n){return n.code==="ENOENT"||console.error(`Error reading plan file: ${n}`),null}}r(p,"getPlan");async function h(e,t,a){const n=M(e,a);try{const o=g(n);i(o,{recursive:!0});const l=n+".tmp."+process.pid;return T(l,t,"utf-8"),C(l,n),!0}catch(o){return console.error(`Error writing plan file: ${o}`),!1}}r(h,"writePlan");function J(e,t){return p(e,t)!==null}r(J,"planExists");async function K(e,t){const a=v(e);_(t,a);const n=p(e);return n!==null?(await h(t,n),!0):!1}r(K,"copyPlanForResume");async function V(e,t){const a=p(e);return a===null?!1:(A(t),await h(t,a),!0)}r(V,"copyPlanForFork");async function X(e){const t=p(e);return t===null?!1:(A(e),h(e,t))}r(X,"copyPlanFileToNewSlug");function Y(e,t){try{return i(g(t),{recursive:!0}),b(e,t),!0}catch{return!1}}r(Y,"copyPlanFile");export{G as clearAllPlanSlugs,A as clearPlanSlug,Y as copyPlanFile,X as copyPlanFileToNewSlug,V as copyPlanForFork,K as copyPlanForResume,D as generatePlanSlug,p as getPlan,M as getPlanFilePath,f as getPlanSessionState,v as getPlanSlug,S as getPlansDirectory,N as hydratePlanSessionState,J as planExists,W as resetPlansDirectoryCache,O as serializePlanSessionState,_ as setPlanSlug,h as writePlan};

package/dist/extensions/builtin/plan/plan-permissions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * [WHO]: shouldAllowToolCall(), getPlanModeToolBlockReason()
+ * [FROM]: Depends on node:path, ./types, ./plan-file-manager
+ * [TO]: Consumed by plan extension index.ts (tool_call event handler)
+ * [HERE]: extensions/builtin/plan/plan-permissions.ts - tool call permission gating for plan mode
+ */
+import type { ToolCallInput, ToolPermissionResult } from "./types.js";
+import type { PlanSessionState } from "./types.js";
+/**
+ * Check if a tool call is allowed in plan mode.
+ * Returns { allowed: true } or { allowed: false, reason: string }.
+ */
+export declare function shouldAllowToolCall(toolCall: ToolCallInput, planFilePath: string, cwd?: string): ToolPermissionResult;
+export declare function handlePlanModeTransition(sessionState: PlanSessionState): void;
+export declare function handlePlanModeExit(sessionState: PlanSessionState): void;

package/dist/extensions/builtin/plan/plan-permissions.js

@@ -0,0 +1,12 @@
+var l=Object.defineProperty;var o=(t,n)=>l(t,"name",{value:n,configurable:!0});import{resolve as r}from"node:path";const d=new Set(["read","grep","find","ls","time","source","LSP","AskUserQuestion"]),f=new Set(["Explore","Plan","explore","plan"]),c=new Set(["notebookEdit","NotebookEdit","write_file","edit_file","replace","create_file","delete_file"]),u=["ls ","ls	",`ls
+`,"cat ","cat	","head ","head	","tail ","tail	","wc ","wc	","echo ","echo	",`echo
+`,"find ","find	","grep ","grep	","rg ","rg	","stat ","stat	","file ","file	","pwd",`pwd
+`,"pwd ","which ","which	","whoami",`whoami
+`,"date",`date
+`,"date ","uname ","uname	","git status","git log ",`git log
+`,"git log	","git diff ",`git diff
+`,"git diff	","git branch",`git branch
+`,"git branch	","git show ",`git show
+`,"git show	","git describe",`git describe
+`,"tree ","tree	",`tree
+`,"du ","du	","df ","df	"],p=[/>/,/\brm\s+/,/\bmv\s+/,/\bcp\s+/,/\bchmod\s+/,/\bchown\s+/,/\bcurl\s.*\|.*sh/,/\bwget\s.*\|.*sh/,/\bgit\s+(commit|push|reset\s+--hard|clean\s+-f)/,/\bnpm\s+(publish|install|update|add|remove|uninstall|ci)\b/,/\bpnpm\s+(publish|install|update|add|remove|uninstall)\b/,/\byarn\s+(publish|install|add|remove|upgrade)\b/,/\byarn\s+(publish)/,/\bpip\s+install/,/\btouch\s+/,/\bmkdir\s+/,/\btee\s+/,/\bsed\s+-i\b/,/\bsudo\s+/,/\bdd\s+/];function E(t,n,s=process.cwd()){const{toolName:e,input:a}=t;if(e==="ExitPlanMode")return{allowed:!0,classification:"plan"};if(e==="EnterPlanMode")return h(a)?{allowed:!1,classification:"agent",reason:"EnterPlanMode is not allowed from agent contexts."}:{allowed:!0,classification:"plan"};if(d.has(e))return{allowed:!0,classification:"read"};if(e==="write"||e==="edit"){const i=typeof a.path=="string"?a.path:"";return i&&g(i,n,s)?{allowed:!0,classification:"write"}:{allowed:!1,classification:"write",reason:`In plan mode, ${e} is only allowed for the plan file: ${n}`}}if(e==="Agent"||e==="Task")return w(a)?{allowed:!0,classification:"agent"}:{allowed:!1,classification:"agent",reason:"In plan mode, Agent/Task is only allowed for read-only Explore or Plan agents."};if(e==="bash"){const i=typeof a.command=="string"?a.command:"";return m(i)?{allowed:!0,classification:"read"}:{allowed:!1,classification:"write",reason:`In plan mode, only read-only bash commands are allowed. Command "${i.slice(0,80)}${i.length>80?"...":""}" appears to modify the filesystem.`}}return c.has(e)?{allowed:!1,classification:"write",reason:`${e} is not allowed in plan mode.`}:{allowed:!1,classification:"unknown",reason:`In plan mode, unknown tool "${e}" is blocked unless it is explicitly classified as read-only.`}}o(E,"shouldAllowToolCall");function m(t){const n=t.trim();if(!n)return!0;for(const e of p)if(e.test(n))return!1;for(const e of u)if(n.startsWith(e))return!0;const s=["pwd","whoami","date","uname"];for(const e of s)if(n===e||n.startsWith(e+" ")||n.startsWith(e+"	"))return!0;if(n.startsWith("git ")){const e=["status","log","diff","branch","show","describe","tag"];for(const a of e)if(n.startsWith(`git ${a}`))return!0;return!1}return!1}o(m,"isReadOnlyBashCommand");function g(t,n,s){if(t===n)return!0;try{const e=r(s,t),a=r(n);return e===a}catch{return!1}}o(g,"pathsMatch");function h(t){return typeof t.agentId=="string"||typeof t.parentAgentId=="string"}o(h,"isAgentContext");function w(t){const n=typeof t.agentType=="string"?t.agentType:typeof t.subagent_type=="string"?t.subagent_type:typeof t.type=="string"?t.type:"";if(n&&f.has(n))return!0;const s=typeof t.prompt=="string"?t.prompt:"";if(!s)return!1;const e=/\b(Explore|Plan) agent\b/i.test(s)||/\bread-only\b/i.test(s),a=/\b(write|edit|modify|delete|commit|apply)\b/i.test(s);return e&&!a}o(w,"isPlanSafeAgent");function A(t){t.state.needsPlanModeExitAttachment=!1,t.state.planAttachmentCount=0}o(A,"handlePlanModeTransition");function P(t){t.state.hasExitedPlanModeInSession=!0,t.state.needsPlanModeExitAttachment=!0,t.state.mode=t.state.prePlanMode,t.state.prePlanMode="default"}o(P,"handlePlanModeExit");export{P as handlePlanModeExit,A as handlePlanModeTransition,E as shouldAllowToolCall};

package/dist/extensions/builtin/plan/plan-validation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * [WHO]: validatePlan(), checkPlanStructure()
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by exit-plan-mode-tool.ts
+ * [HERE]: extensions/builtin/plan/plan-validation.ts - plan content validation
+ */
+/**
+ * Validate that a plan has the minimum required structure.
+ */
+export declare function validatePlan(planContent: string): {
+    valid: boolean;
+    missingSections: string[];
+    suggestions: string[];
+};
+/**
+ * Generate a validation message for the user.
+ */
+export declare function formatValidationMessage(result: ReturnType<typeof validatePlan>): string;

package/dist/extensions/builtin/plan/plan-validation.js

@@ -0,0 +1,5 @@
+var g=Object.defineProperty;var n=(e,i)=>g(e,"name",{value:i,configurable:!0});const m=[/^#{1,3}\s*(Context|Background|Why)/im,/^#{1,3}\s*(Approach|Implementation|Plan)/im,/^#{1,3}\s*(Files?|Changes?|Steps?)/im,/^#{1,3}\s*(Test|Verification|Validate)/im];function l(e){if(!e||e.trim().length===0)return{valid:!1,missingSections:["Empty plan"],suggestions:["Write a plan with Context, Approach, Files, and Verification sections"]};const i=[],s=[],t=[{pattern:/^#{1,3}\s*(Context|Background|Why)/im,name:"Context"},{pattern:/^#{1,3}\s*(Approach|Implementation|Plan|Design)/im,name:"Approach"},{pattern:/^#{1,3}\s*(Files?|Changes?|Steps?|Files to Modify)/im,name:"Files to modify"},{pattern:/^#{1,3}\s*(Test|Verification|Validate|Testing)/im,name:"Verification"}];for(const{pattern:o,name:a}of t)o.test(e)||i.push(a);return e.length<200&&s.push("Plan seems too short - consider adding more detail"),(e.match(/```/g)||[]).length===0&&e.length>500&&s.push("Consider including code examples or pseudocode"),{valid:i.length===0,missingSections:i,suggestions:s}}n(l,"validatePlan");function d(e){return e.valid?e.suggestions.length>0?["Plan structure looks good!","","Suggestions:",...e.suggestions.map(i=>`- ${i}`)].join(`
+`):"Plan structure is complete.":["Plan is missing required sections:",...e.missingSections.map(i=>`- ${i}`),"","Please add these sections before exiting plan mode.","",e.suggestions.length>0?`Suggestions:
+`+e.suggestions.map(i=>`- ${i}`).join(`
+`):""].join(`
+`)}n(d,"formatValidationMessage");export{d as formatValidationMessage,l as validatePlan};

package/dist/extensions/builtin/plan/plan-workflow-prompt.d.ts

@@ -0,0 +1,18 @@
+/**
+ * [WHO]: getPlanModeInstructions(), getPlanModeExitInstructions(), getPlanModeReentryInstructions()
+ * [FROM]: Depends on ./plan-file-manager, ./types
+ * [TO]: Consumed by plan extension index.ts (before_agent_start event handler)
+ * [HERE]: extensions/builtin/plan/plan-workflow-prompt.ts - workflow prompt generation for plan mode
+ */
+import type { PlanModeConfig, PlanSessionState } from "./types.js";
+export declare function getPlanModeInstructions(sessionState: PlanSessionState, planFilePath: string, existingPlan: string | null, reminderType: "full" | "sparse", config?: PlanModeConfig): string;
+export declare function getPlanModeExitInstructions(planFilePath: string, planExists: boolean, allowedPrompts?: Array<{
+    tool: string;
+    prompt: string;
+}>): string;
+export declare function getPlanModeReentryInstructions(planFilePath: string): string;
+export declare function getEnterPlanModeToolResult(): string;
+export declare function getExitPlanModeApprovedResult(plan: string | null, filePath: string, planWasEdited: boolean, hasAgentTool: boolean, allowedPrompts?: Array<{
+    tool: string;
+    prompt: string;
+}>): string;

package/dist/extensions/builtin/plan/plan-workflow-prompt.js

@@ -0,0 +1,102 @@
+var l=Object.defineProperty;var a=(t,n)=>l(t,"name",{value:n,configurable:!0});function f(t,n,i,e,s){const o=s?.interviewPhaseEnabled||(process.env.CATUI_PLAN_INTERVIEW??process.env.NANOPENCIL_PLAN_INTERVIEW)==="true";return e==="sparse"?o?p(n,i!==null):u(n,i!==null):o?h(n,i!==null?!0:null):d(n,i!==null?!0:null)}a(f,"getPlanModeInstructions");function u(t,n){return[`Plan mode still active (see full instructions earlier in conversation). Read-only except plan file (${t}).`,n?`Continue editing your plan at ${t}.`:`Create your plan at ${t}.`,"End turns with AskUserQuestion (for clarifications) or ExitPlanMode (for plan approval). Never ask about plan approval via text or AskUserQuestion."].join(`
+`)}a(u,"getSparseReminder");function d(t,n){const i=n!==null,e=[];return e.push("Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received."),i?e.push(`A plan file already exists at ${t}. You can read it and make incremental edits using FileEdit.`):e.push(`No plan file exists yet. You should create your plan at ${t} using the FileWrite tool.`),e.push(`
+## Plan Workflow
+
+### Phase 1: Initial Understanding
+Goal: Gain a comprehensive understanding of the user's request by reading through code and asking them questions.
+
+1. Focus on understanding the user's request and the code associated with their request. Actively search for existing functions, utilities, and patterns that can be reused -- avoid proposing new code when suitable implementations already exist.
+
+2. **Launch up to 3 Explore subagents IN PARALLEL** (single message, multiple tool calls) to efficiently explore the codebase.
+   - Use 1 agent when the task is isolated to known files, the user provided specific file paths, or you're making a small targeted change.
+   - Use multiple agents when: the scope is uncertain, multiple areas of the codebase are involved, or you need to understand existing patterns before planning.
+   - Quality over quantity - 3 agents maximum, but try to use the minimum number of agents necessary (usually just 1)
+   - If using multiple agents: Provide each agent with a specific search focus. Example: One agent searches for existing implementations, another explores related components, a third investigating testing patterns`),e.push(`
+### Phase 2: Design
+Goal: Design an implementation approach.
+
+Launch Plan subagent(s) to design the implementation based on the user's intent and your exploration results from Phase 1.
+
+You can launch up to 1 Plan subagent(s) in parallel.
+
+**Guidelines:**
+- **Default**: Launch at least 1 Plan agent for most tasks - it helps validate your understanding and consider alternatives
+- **Skip agents**: Only for truly trivial tasks (typo fixes, single-line changes, simple renames)
+
+In the agent prompt:
+- Provide comprehensive background context from Phase 1 exploration including filenames and code path traces
+- Describe requirements and constraints
+- Request a detailed implementation plan`),e.push(`
+### Phase 3: Review
+Goal: Review the plan(s) from Phase 2 and ensure alignment with the user's intentions.
+1. Read the critical files identified by agents to deepen your understanding
+2. Ensure that the plans align with the user's original request
+3. Use AskUserQuestion to clarify any remaining questions with the user`),e.push(`
+### Phase 4: Final Plan
+Goal: Write your final plan to the plan file (the only file you can edit).
+- Begin with a **Context** section: explain why this change is being made -- the problem or need it addresses, what prompted it, and the intended outcome
+- Include only your recommended approach, not all alternatives
+- Ensure that the plan file is concise enough to scan quickly, but detailed enough to execute effectively
+- Include the paths of critical files to be modified
+- Reference existing functions and utilities you found that should be reused, with their file paths
+- Include a verification section describing how to test the changes end-to-end (run the code, use MCP tools, run tests)`),e.push(`
+### Phase 5: Call ExitPlanMode
+At the very end of your turn, once you have asked the user questions and are happy with your final plan file - you should always call ExitPlanMode to indicate to the user that you are done planning.
+This is critical - your turn should only end with either using the AskUserQuestion tool OR calling ExitPlanMode. Do not stop unless it's for these 2 reasons
+
+**Important:** Use AskUserQuestion ONLY to clarify requirements or choose between approaches. Use ExitPlanMode to request plan approval. Do NOT ask about plan approval in any other way - no text questions, no AskUserQuestion. Phrases like "Is this plan okay?", "Should I proceed?", "How does this plan look?", "Any changes before we start?", or similar MUST use ExitPlanMode.
+
+NOTE: At any point in time through this workflow you should feel free to ask the user questions or clarifications using the AskUserQuestion tool. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.`),e.join(`
+
+`)}a(d,"getFullWorkflow");function h(t,n){const i=n!==null,e=[];return e.push("Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received."),i?e.push(`A plan file already exists at ${t}. You can read it and make incremental edits using FileEdit.`):e.push(`No plan file exists yet. You should create your plan at ${t} using the FileWrite tool.`),e.push(`## Iterative Planning Workflow
+
+You are pair-planning with the user. Explore the code to build context, ask the user questions when you hit decisions you can't make alone, and write your findings into the plan file as you go. The plan file (above) is the ONLY file you may edit -- it starts as a rough skeleton and gradually becomes the final plan.
+
+### The Loop
+
+Repeat this cycle until the plan is complete:
+
+1. **Explore** -- Use read-only tools (Read, Grep, Find, Bash with read-only commands) to read code. Look for existing functions, utilities, and patterns to reuse. You can use the Explore agent type to parallelize complex searches without filling your context, though for straightforward queries direct tools are simpler.
+2. **Update the plan file** -- After each discovery, immediately capture what you learned. Don't wait until the end.
+3. **Ask the user** -- When you hit an ambiguity or decision you can't resolve from code alone, use AskUserQuestion. Then go back to step 1.
+
+### First Turn
+
+Start by quickly scanning a few key files to form an initial understanding of the task scope. Then write a skeleton plan (headers and rough notes) and ask the user your first round of questions. Don't explore exhaustively before engaging the user.
+
+### Asking Good Questions
+
+- Never ask what you could find out by reading the code
+- Batch related questions together (use multi-question AskUserQuestion calls)
+- Focus on things only the user can answer: requirements, preferences, tradeoffs, edge case priorities
+- Scale depth to the task -- a vague feature request needs many rounds; a focused bug fix may need one or none
+
+### Plan File Structure
+
+Your plan file should be divided into clear sections using markdown headers, based on the request. Fill out these sections as you go.
+- Begin with a **Context** section: explain why this change is being made
+- Include only your recommended approach, not all alternatives
+- Ensure that the plan file is concise enough to scan quickly, but detailed enough to execute effectively
+- Include the paths of critical files to be modified
+- Reference existing functions and utilities you found that should be reused, with their file paths
+- Include a verification section describing how to test the changes end-to-end
+
+### When to Converge
+
+Your plan is ready when you've addressed all ambiguities and it covers: what to change, which files to modify, what existing code to reuse (with file paths), and how to verify the changes. Call ExitPlanMode when the plan is ready for approval.
+
+### Ending Your Turn
+
+Your turn should only end by either:
+- Using AskUserQuestion to gather more information
+- Calling ExitPlanMode when the plan is ready for approval
+
+**Important:** Use ExitPlanMode to request plan approval. Do NOT ask about plan approval via text or AskUserQuestion. Phrases like "Is this plan okay?", "Should I proceed?", "How does this plan look?" MUST use ExitPlanMode.`),e.join(`
+
+`)}a(h,"getInterviewWorkflow");function p(t,n){return[`Plan mode still active (iterative workflow). Read-only except plan file (${t}).`,n?`Continue exploring codebase, updating plan, and interviewing user at ${t}.`:`Start by scanning key files, write a skeleton plan at ${t}, then ask your first questions.`,"End turns with AskUserQuestion (for clarifications) or ExitPlanMode (for plan approval). Never ask about plan approval via text or AskUserQuestion."].join(`
+`)}a(p,"getInterviewSparseReminder");function g(t,n,i){const e=["## Exited Plan Mode","","You have exited plan mode. You can now make edits, run tools, and take actions."];if(n?e.push(`The plan file is located at ${t} if you need to reference it.`):e.push("No plan was written during plan mode."),i&&i.length>0){e.push(""),e.push("The following tool permissions were pre-approved by the user during plan approval:");for(const s of i)e.push(`- ${s.tool}: ${s.prompt}`)}return e.join(`
+`)}a(g,"getPlanModeExitInstructions");function y(t){return["You are returning to plan mode after having previously exited it.",`A plan file exists at ${t}.`,"","Before proceeding:","1. Read existing plan","2. Compare current request with the existing plan","3. If this is a different task -> overwrite the plan file","4. If this is the same task -> modify and clean up stale parts","5. Always edit the plan file before calling ExitPlanMode"].join(`
+`)}a(y,"getPlanModeReentryInstructions");function m(){return["Entered plan mode. You should now focus on exploring the codebase and designing an implementation approach.","","In plan mode, you should:","1. Thoroughly explore the codebase to understand existing patterns","2. Identify similar features and architectural approaches","3. Consider multiple approaches and their trade-offs","4. Use AskUserQuestion if you need to clarify the approach","5. Design a concrete implementation strategy","6. When ready, use ExitPlanMode to present your plan for approval","","Remember: DO NOT write or edit any files yet. This is a read-only exploration and planning phase."].join(`
+`)}a(m,"getEnterPlanModeToolResult");function w(t,n,i,e,s){const o=[];if(!t||t.trim().length===0)return o.push("User has approved exiting plan mode. You can now proceed."),o.join(`
+`);if(o.push("User has approved your plan. You can now start coding. Start with updating your todo list if applicable"),o.push(""),o.push(`Your plan has been saved to: ${n}`),o.push("You can refer back to it if needed during implementation."),o.push(""),o.push(i?"## Approved Plan (edited by user):":"## Approved Plan:"),o.push(t),s&&s.length>0){o.push(""),o.push("## Pre-approved permissions:");for(const r of s)o.push(`- ${r.tool}: ${r.prompt}`)}return e&&(o.push(""),o.push("You can now use Agent subagents to parallelize implementation if appropriate.")),o.join(`
+`)}a(w,"getExitPlanModeApprovedResult");export{m as getEnterPlanModeToolResult,w as getExitPlanModeApprovedResult,g as getPlanModeExitInstructions,f as getPlanModeInstructions,y as getPlanModeReentryInstructions};

package/dist/extensions/builtin/plan/teammate-approval.d.ts

@@ -0,0 +1,49 @@
+/**
+ * [WHO]: isInTeammateContext(), submitPlanToLeader(), checkPlanApproval()
+ * [FROM]: No external dependencies (team extension integration)
+ * [TO]: Consumed by exit-plan-mode-tool.ts
+ * [HERE]: extensions/builtin/plan/teammate-approval.ts - teammate plan approval flow
+ *
+ * @deprecated MVP implementation — uses filesystem-based mailbox (team-mail dir).
+ *   TODO(v2): Replace with TeamMailbox.post() from team extension when stable.
+ */
+/**
+ * Check if the current context is a teammate.
+ * This is a simplified check - in full implementation this would
+ * integrate with the team extension's TeamRuntime.
+ */
+export declare function isInTeammateContext(): boolean;
+/**
+ * Get the current teammate identity.
+ */
+export declare function getTeammateIdentity(): {
+    id: string;
+    name: string;
+} | null;
+/**
+ * Get the team name if in a team context.
+ */
+export declare function getTeamName(): string | null;
+/**
+ * Submit a plan approval request to the leader.
+ * @deprecated MVP: uses filesystem-based mailbox. Replace with TeamMailbox.post().
+ */
+export declare function submitPlanToLeader(planFilePath: string, planContent: string): Promise<{
+    requestId: string;
+    status: "submitted";
+}>;
+/**
+ * Check if a plan approval has been received.
+ */
+export declare function checkPlanApproval(requestId: string): Promise<{
+    approved: boolean;
+    feedback?: string;
+} | null>;
+/**
+ * Format the message shown when plan is submitted to leader.
+ */
+export declare function formatPlanSubmittedMessage(requestId: string, planFilePath: string): string;
+/**
+ * Format the message shown when waiting for leader approval.
+ */
+export declare function formatWaitingForApprovalMessage(requestId: string): string;

package/dist/extensions/builtin/plan/teammate-approval.js

@@ -0,0 +1,3 @@
+var m=Object.defineProperty;var n=(e,t)=>m(e,"name",{value:t,configurable:!0});function v(){return process.env.CATUI_TEAMMATE_ID!==void 0}n(v,"isInTeammateContext");function l(){const e=process.env.CATUI_TEAMMATE_ID,t=process.env.CATUI_TEAMMATE_NAME;return e?{id:e,name:t||e}:null}n(l,"getTeammateIdentity");function h(){return process.env.CATUI_TEAM_NAME||null}n(h,"getTeamName");async function I(e,t){const o=l();if(!o)throw new Error("Not in teammate context");const a=d("plan_approval",o.name),s={type:"plan_approval_request",from:o.name,timestamp:new Date().toISOString(),planFilePath:e,planContent:t,requestId:a},r=await import("node:fs"),p=await import("node:os"),i=await import("node:path"),c=i.join(p.homedir(),".catui","agent","team-mail"),u=i.join(c,`${a}.json`);return r.mkdirSync(c,{recursive:!0}),r.writeFileSync(u,JSON.stringify(s,null,2),"utf-8"),{requestId:a,status:"submitted"}}n(I,"submitPlanToLeader");async function T(e){const t=await import("node:os"),o=await import("node:path"),a=await import("node:fs"),s=o.join(t.homedir(),".catui","agent","team-mail"),r=o.join(s,`response-${e}.json`);if(!a.existsSync(r))return null;try{const p=a.readFileSync(r,"utf-8"),i=JSON.parse(p);return{approved:i.approved,feedback:i.feedback}}catch{return null}}n(T,"checkPlanApproval");function d(e,t){const o=Date.now().toString(36),a=Math.random().toString(36).slice(2,8);return`${e}-${t}-${o}-${a}`}n(d,"generateRequestId");function w(e,t){return["Your plan has been submitted to the team lead for approval.","",`Plan file: ${t}`,"","What happens next:","1. Wait for the team lead to review your plan","2. You will receive a message in your inbox with approval/rejection","3. If approved, you can proceed with implementation","4. If rejected, refine your plan based on the feedback","","Important: Do NOT proceed until you receive approval.","",`Request ID: ${e}`].join(`
+`)}n(w,"formatPlanSubmittedMessage");function y(e){return["Waiting for team lead approval...",`Request ID: ${e}`,"","The leader will approve or reject via `/team:approve ${requestId}`"].join(`
+`)}n(y,"formatWaitingForApprovalMessage");export{T as checkPlanApproval,w as formatPlanSubmittedMessage,y as formatWaitingForApprovalMessage,h as getTeamName,l as getTeammateIdentity,v as isInTeammateContext,I as submitPlanToLeader};

package/dist/extensions/builtin/plan/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * [WHO]: PlanModeState, PlanModeAttachment types, PlanModeConfig
+ * [FROM]: Depends on core/extensions-host/types (EventBus reference)
+ * [TO]: Consumed by all plan extension modules
+ * [HERE]: extensions/builtin/plan/types.ts - type definitions for plan mode
+ */
+import type { EventBus } from "../../../core/runtime/event-bus.js";
+export declare const PLAN_CUSTOM_TYPE = "plan_state";
+export type PlanModePermissionMode = "default" | "plan" | "auto" | "acceptEdits" | "bypassPermissions";
+export interface PlanModeState {
+    /** Current permission mode */
+    mode: PlanModePermissionMode;
+    /** Mode before entering plan mode, restored on exit */
+    prePlanMode: PlanModePermissionMode;
+    /** Whether to inject plan mode exit attachment on next turn */
+    needsPlanModeExitAttachment: boolean;
+    /** Whether the user has exited plan mode in this session (for reentry detection) */
+    hasExitedPlanModeInSession: boolean;
+    /** Count of plan mode attachments sent (for throttling) */
+    planAttachmentCount: number;
+    /** Last session id this in-memory state was hydrated from */
+    hydratedSessionId?: string;
+    /** Number of human turns seen when the last plan attachment was injected */
+    lastPlanAttachmentHumanTurn?: number;
+    /** Current session id, when available */
+    sessionId?: string;
+    /** Current plan slug, persisted for resume/fork recovery */
+    planSlug?: string;
+    /** Last known plan file snapshot for recovery */
+    planSnapshot?: string;
+    /** Pre-approved tool permissions from the last ExitPlanMode call */
+    lastAllowedPrompts?: Array<{
+        tool: string;
+        prompt: string;
+    }>;
+}
+export interface PlanSessionState {
+    state: PlanModeState;
+    planSlugCache: string | undefined;
+}
+export type PlanStateMap = WeakMap<EventBus, PlanSessionState>;
+export interface PlanFileInfo {
+    slug: string;
+    path: string;
+    content: string | null;
+    exists: boolean;
+}
+export type PlanAttachmentType = "plan_mode" | "plan_mode_exit" | "plan_mode_reentry" | "plan_file_reference";
+export interface PlanModeAttachment {
+    type: "plan_mode";
+    reminderType: "full" | "sparse";
+    isSubAgent: boolean;
+    planFilePath: string;
+    planExists: boolean;
+}
+export interface PlanModeReentryAttachment {
+    type: "plan_mode_reentry";
+    planFilePath: string;
+}
+export interface PlanModeExitAttachment {
+    type: "plan_mode_exit";
+    planFilePath: string;
+    planExists: boolean;
+}
+export interface PlanFileReferenceAttachment {
+    type: "plan_file_reference";
+    planFilePath: string;
+    planContent: string;
+}
+export type PlanAttachment = PlanModeAttachment | PlanModeReentryAttachment | PlanModeExitAttachment | PlanFileReferenceAttachment;
+export type ToolPermissionResult = {
+    allowed: true;
+    classification?: "read" | "write" | "plan" | "agent";
+} | {
+    allowed: false;
+    reason: string;
+    classification?: "write" | "unknown" | "agent";
+};
+export interface PlanStateEntryData {
+    version: 1;
+    sessionId?: string;
+    mode: PlanModePermissionMode;
+    prePlanMode: PlanModePermissionMode;
+    needsPlanModeExitAttachment: boolean;
+    hasExitedPlanModeInSession: boolean;
+    planAttachmentCount: number;
+    lastPlanAttachmentHumanTurn?: number;
+    planSlug?: string;
+    planSnapshot?: string;
+    lastAllowedPrompts?: Array<{
+        tool: string;
+        prompt: string;
+    }>;
+}
+export interface PlanModeConfig {
+    /** Plan file directory override */
+    plansDirectory?: string;
+    /** Number of turns between full plan mode reminders */
+    turnsBetweenFullReminder: number;
+    /** Every N attachments, inject a full reminder instead of sparse */
+    fullReminderEveryN: number;
+    /** Maximum number of Explore subagents */
+    maxExploreAgents: number;
+    /** Maximum number of Plan subagents */
+    maxPlanAgents: number;
+    /** Use iterative interview workflow instead of sequential 5-phase */
+    interviewPhaseEnabled?: boolean;
+}
+export declare const DEFAULT_PLAN_CONFIG: PlanModeConfig;
+export interface ToolCallInput {
+    toolName: string;
+    toolCallId: string;
+    input: Record<string, unknown>;
+}
+export interface PlanApprovalRequest {
+    type: "plan_approval_request";
+    from: string;
+    timestamp: string;
+    planFilePath: string;
+    planContent: string;
+    requestId: string;
+}
+export interface PlanApprovalResponse {
+    type: "plan_approval_response";
+    requestId: string;
+    approved: boolean;
+    feedback?: string;
+}
+export interface PlanValidationResult {
+    valid: boolean;
+    missingSections: string[];
+}
+export declare const REQUIRED_PLAN_SECTIONS: readonly ["Context", "context"];

package/dist/extensions/builtin/plan/types.js

@@ -0,0 +1 @@
+const e="plan_state",t={turnsBetweenFullReminder:3,fullReminderEveryN:3,maxExploreAgents:3,maxPlanAgents:1,interviewPhaseEnabled:!1},n=["Context","context"];export{t as DEFAULT_PLAN_CONFIG,e as PLAN_CUSTOM_TYPE,n as REQUIRED_PLAN_SECTIONS};