@pikaa-ai/pikaa 0.3.18 → 0.3.20

package/dist/cli.js

@@ -3,7 +3,7 @@
 
 // src/cli/index.ts
 import { resolve as resolve21 } from "path";
-import { existsSync as existsSync22 } from "fs";
+import { existsSync as existsSync23 } from "fs";
 import { createInterface } from "readline";
 
 // src/auth/store.ts
@@ -235,12 +235,15 @@ class DefaultModelClientSession {
       };
       return;
     }
-    const messages = [
-      {
-        role: "system",
-        content: params.systemPrompt
-      }
-    ];
+    const enablePromptCache = params.enablePromptCache ?? this.config.enablePromptCache ?? true;
+    const systemMessage = {
+      role: "system",
+      content: params.systemPrompt
+    };
+    if (enablePromptCache) {
+      systemMessage.cache_control = { type: "ephemeral" };
+    }
+    const messages = [systemMessage];
     for (let i = 0;i < params.history.length; i++) {
       const item = params.history[i];
       if (item.type === "user_message") {
@@ -324,14 +327,27 @@ class DefaultModelClientSession {
       temperature: params.temperature ?? 0.2
     };
     if (toolsPayload && toolsPayload.length > 0) {
-      body.tools = toolsPayload;
+      if (enablePromptCache && toolsPayload.length > 0) {
+        const clonedTools = [...toolsPayload];
+        const lastIdx = clonedTools.length - 1;
+        if (clonedTools[lastIdx] && typeof clonedTools[lastIdx] === "object") {
+          clonedTools[lastIdx] = {
+            ...clonedTools[lastIdx],
+            cache_control: { type: "ephemeral" }
+          };
+        }
+        body.tools = clonedTools;
+      } else {
+        body.tools = toolsPayload;
+      }
       body.tool_choice = "auto";
     }
     const maxRetries = params.maxRetries ?? this.config.maxRetries ?? 10;
     let attempt = 0;
     let response = null;
     const headers = {
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      "anthropic-beta": "prompt-caching-2024-07-25"
     };
     if (apiKey) {
       headers["Authorization"] = `Bearer ${apiKey}`;
@@ -441,7 +457,8 @@ class DefaultModelClientSession {
               type: "done",
               inputTokens: usageMetrics.inputTokens,
               outputTokens: usageMetrics.outputTokens,
-              totalTokens: usageMetrics.totalTokens
+              totalTokens: usageMetrics.totalTokens,
+              cachedTokens: usageMetrics.cachedTokens
             };
             return;
           }
@@ -452,10 +469,12 @@ class DefaultModelClientSession {
             continue;
           }
           if (parsed.usage) {
+            const cached = parsed.usage.prompt_tokens_details?.cached_tokens ?? parsed.usage.cache_read_input_tokens ?? parsed.usage.cached_content_token_count ?? 0;
             usageMetrics = {
               inputTokens: parsed.usage.prompt_tokens,
               outputTokens: parsed.usage.completion_tokens,
-              totalTokens: parsed.usage.total_tokens
+              totalTokens: parsed.usage.total_tokens,
+              cachedTokens: cached > 0 ? cached : undefined
             };
           }
           const choice = parsed.choices?.[0];
@@ -673,6 +692,8 @@ class TurnAbortedError extends GroupyError {
 }
 
 // src/context/compactor.ts
+var DEFAULT_MAX_CONTEXT_TOKENS = 256000;
+var DEFAULT_AUTO_COMPACT_THRESHOLD_TOKENS = 180000;
 function estimateItemTokens(item) {
   const text = item.type === "user_message" ? item.content : item.type === "agent_message" ? item.content : item.type === "reasoning" ? item.content : item.type === "function_call" ? JSON.stringify(item.arguments) : item.type === "function_call_output" ? item.output : "";
   return Math.ceil(text.length / 4) + 4;
@@ -742,9 +763,11 @@ async function captureWorldState(cwd) {
   };
 }
 function formatWorldStatePrompt(state) {
+  const isWindows = process.platform === "win32";
+  const platformNote = isWindows ? `Platform: Windows (${state.os}). Shell is cmd.exe / PowerShell. POSIX commands (grep, find, cat, sed, awk) are NOT supported in shell. ALWAYS use native grep_search, find_files, and read_file tools.` : `Platform: ${state.os}`;
   const parts = [
     `Current Working Directory: ${state.cwd}`,
-    `Platform: ${state.os}`
+    platformNote
   ];
   if (state.gitBranch) {
     parts.push(`Git Branch: ${state.gitBranch}`);
@@ -884,80 +907,205 @@ class AgentsMdLoader {
 var globalAgentsMdLoader = new AgentsMdLoader;
 
 // src/context/instructions.ts
-function buildSystemPrompt(params) {
-  const sections = [];
+function wrapXmlTag(tag, content, attrs = {}) {
+  const attrStr = Object.entries(attrs).filter(([_, v]) => Boolean(v)).map(([k, v]) => ` ${k}="${v}"`).join("");
+  return `<${tag}${attrStr}>
+${content.trim()}
+</${tag}>`;
+}
+function buildStructuredSystemPrompt(params) {
   const cwd = params.cwd || process.cwd();
   const mode = params.collaborationMode || "default";
-  if (params.basePrompt) {
-    sections.push(params.basePrompt);
-  } else {
+  const blocks = [];
+  let baseContent = params.basePrompt;
+  if (!baseContent) {
     const templateName = params.basePromptTemplate || "base/groupy_prompt.md";
-    const baseContent = globalPromptLoader.loadTemplate(templateName, {}, cwd);
-    if (baseContent) {
-      sections.push(baseContent.trim());
-    } else {
-      sections.push("You are Groupy, an expert autonomous AI coding assistant. You think step-by-step, act surgically, and write clean, correct code.");
-    }
+    baseContent = globalPromptLoader.loadTemplate(templateName, {}, cwd) || "You are Groupy, an expert autonomous AI coding assistant. You think step-by-step, act surgically, and write clean, correct code.";
   }
+  blocks.push({
+    tag: "system_identity",
+    content: wrapXmlTag("system_identity", baseContent),
+    cacheable: true
+  });
   if (params.personality) {
     const personalityContent = globalPromptLoader.loadTemplate(`personalities/${params.personality}.md`, {}, cwd);
     if (personalityContent) {
-      sections.push(personalityContent.trim());
+      blocks.push({
+        tag: "personality",
+        content: wrapXmlTag("personality", personalityContent, { kind: params.personality }),
+        cacheable: true
+      });
     }
   }
   if (params.isOrchestrator) {
     const orchestratorContent = globalPromptLoader.loadTemplate("agents/orchestrator.md", {}, cwd);
     if (orchestratorContent) {
-      sections.push(orchestratorContent.trim());
+      blocks.push({
+        tag: "orchestrator_guidelines",
+        content: wrapXmlTag("orchestrator_guidelines", orchestratorContent),
+        cacheable: true
+      });
     }
   }
-  const modeTemplate = globalPromptLoader.loadTemplate(`modes/${mode}.md`, {
-    KNOWN_MODE_NAMES: "default, plan, review"
-  }, cwd);
+  const modeTemplate = globalPromptLoader.loadTemplate(`modes/${mode}.md`, { KNOWN_MODE_NAMES: "default, plan, review" }, cwd);
   if (modeTemplate) {
-    sections.push(modeTemplate.trim());
+    blocks.push({
+      tag: "collaboration_mode",
+      content: wrapXmlTag("collaboration_mode", modeTemplate, { name: mode }),
+      cacheable: true
+    });
   }
   if (params.sandboxMode) {
-    const sandboxTemplate = globalPromptLoader.loadTemplate(`permissions/sandbox_mode/${params.sandboxMode}.md`, {
-      network_access: params.networkAccess ? "enabled" : "disabled"
-    }, cwd);
+    const sandboxTemplate = globalPromptLoader.loadTemplate(`permissions/sandbox_mode/${params.sandboxMode}.md`, { network_access: params.networkAccess ? "enabled" : "disabled" }, cwd);
     if (sandboxTemplate) {
-      sections.push(sandboxTemplate.trim());
+      blocks.push({
+        tag: "sandbox_policy",
+        content: wrapXmlTag("sandbox_policy", sandboxTemplate, { mode: params.sandboxMode }),
+        cacheable: true
+      });
     }
   }
   if (params.approvalPolicy) {
     const approvalTemplate = globalPromptLoader.loadTemplate(`permissions/approval_policy/${params.approvalPolicy}.md`, {}, cwd);
     if (approvalTemplate) {
-      sections.push(approvalTemplate.trim());
+      blocks.push({
+        tag: "approval_policy",
+        content: wrapXmlTag("approval_policy", approvalTemplate, { policy: params.approvalPolicy }),
+        cacheable: true
+      });
     }
   }
   const projectInstructions = globalAgentsMdLoader.loadProjectInstructions(cwd);
   if (projectInstructions) {
-    sections.push(`## Project Instructions (AGENTS.md)
-
-${projectInstructions.content.trim()}`);
+    blocks.push({
+      tag: "project_instructions",
+      content: wrapXmlTag("project_instructions", projectInstructions.content, { source: "AGENTS.md" }),
+      cacheable: true
+    });
   }
   if (params.memoriesPrompt) {
-    sections.push(params.memoriesPrompt.trim());
+    blocks.push({
+      tag: "persistent_memories",
+      content: wrapXmlTag("persistent_memories", params.memoriesPrompt),
+      cacheable: true
+    });
   }
   if (params.skillsPrompt) {
-    sections.push(params.skillsPrompt.trim());
+    blocks.push({
+      tag: "domain_skills",
+      content: wrapXmlTag("domain_skills", params.skillsPrompt),
+      cacheable: true
+    });
   }
   if (params.mcpPrompt) {
-    sections.push(params.mcpPrompt.trim());
+    blocks.push({
+      tag: "mcp_servers",
+      content: wrapXmlTag("mcp_servers", params.mcpPrompt),
+      cacheable: true
+    });
   }
   if (params.developerInstructions) {
-    sections.push(`## Developer Instructions
-${params.developerInstructions}`);
+    blocks.push({
+      tag: "developer_instructions",
+      content: wrapXmlTag("developer_instructions", params.developerInstructions),
+      cacheable: true
+    });
   }
+  const dynamicBlocks = [];
   if (params.worldStatePrompt) {
-    sections.push(`## Environment Context
-${params.worldStatePrompt}`);
+    dynamicBlocks.push({
+      tag: "runtime_environment",
+      content: wrapXmlTag("runtime_environment", params.worldStatePrompt),
+      cacheable: false
+    });
   }
-  return sections.join(`
+  const staticPrefix = blocks.map((b) => b.content).join(`
 
 `);
+  const dynamicSuffix = dynamicBlocks.map((b) => b.content).join(`
+
+`);
+  const allBlocks = [...blocks, ...dynamicBlocks];
+  const text = allBlocks.map((b) => b.content).join(`
+
+`);
+  return {
+    text,
+    staticPrefix,
+    dynamicSuffix,
+    blocks: allBlocks
+  };
+}
+function buildSystemPrompt(params) {
+  return buildStructuredSystemPrompt(params).text;
+}
+
+// src/workspace/ephemeral.ts
+import { mkdirSync as mkdirSync3, rmSync, existsSync as existsSync5, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join4 } from "path";
+import { tmpdir } from "os";
+
+class EphemeralWorkspaceManager {
+  activeScratchpads = new Set;
+  createScratchpad(turnId) {
+    const uniqueId = `groupy_scratch_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const baseDir = join4(tmpdir(), "groupy-ephemeral", turnId ? `turn_${turnId}` : "general");
+    const scratchPath = join4(baseDir, uniqueId);
+    mkdirSync3(scratchPath, { recursive: true });
+    this.activeScratchpads.add(scratchPath);
+    return scratchPath;
+  }
+  cleanup(scratchPath) {
+    if (!scratchPath || !this.activeScratchpads.has(scratchPath))
+      return;
+    try {
+      if (existsSync5(scratchPath)) {
+        rmSync(scratchPath, { recursive: true, force: true });
+      }
+    } catch {} finally {
+      this.activeScratchpads.delete(scratchPath);
+    }
+  }
+  cleanupTurn(turnId) {
+    const turnDir = join4(tmpdir(), "groupy-ephemeral", `turn_${turnId}`);
+    try {
+      if (existsSync5(turnDir)) {
+        rmSync(turnDir, { recursive: true, force: true });
+      }
+    } catch {}
+  }
+  cleanRootResidue(cwd) {
+    const cleaned = [];
+    try {
+      const files = readdirSync2(cwd);
+      const tempPatterns = [
+        /^tmp_/i,
+        /^draft_/i,
+        /^scratch_/i,
+        /^temp_/i,
+        /^preview_.*\.html$/i,
+        /\.tmp$/i,
+        /\.bak$/i,
+        /~$/i
+      ];
+      for (const file of files) {
+        if (tempPatterns.some((p) => p.test(file))) {
+          const fullPath = join4(cwd, file);
+          const stat = statSync2(fullPath);
+          if (stat.isFile()) {
+            rmSync(fullPath, { force: true });
+            cleaned.push(file);
+          } else if (stat.isDirectory() && (file.startsWith("tmp_") || file.startsWith("scratch_") || file.startsWith("temp_"))) {
+            rmSync(fullPath, { recursive: true, force: true });
+            cleaned.push(file);
+          }
+        }
+      }
+    } catch {}
+    return cleaned;
+  }
 }
+var globalEphemeralWorkspace = new EphemeralWorkspaceManager;
 
 // src/session/turn.ts
 async function runTurn(session, turnContext, input) {
@@ -968,7 +1116,7 @@ async function runTurn(session, turnContext, input) {
   });
   const currentHistory = session.getHistory();
   const estimatedTokens = estimateTotalTokens(currentHistory);
-  const maxTokenLimit = 80000;
+  const maxTokenLimit = DEFAULT_AUTO_COMPACT_THRESHOLD_TOKENS;
   if (estimatedTokens > maxTokenLimit) {
     const compacted = compactHistory(currentHistory);
     session.setHistory(compacted);
@@ -1007,6 +1155,7 @@ async function runTurn(session, turnContext, input) {
   let iteration = 0;
   let accumulatedInputTokens = 0;
   let accumulatedOutputTokens = 0;
+  let accumulatedCachedTokens = 0;
   const clientSession = session.modelClient.newSession();
   try {
     while (iteration < turnContext.maxIterations) {
@@ -1023,7 +1172,8 @@ async function runTurn(session, turnContext, input) {
         systemPrompt: effectiveSystemPrompt,
         history: session.getHistory(),
         tools: turnContext.tools,
-        signal
+        signal,
+        enablePromptCache: true
       });
       for await (const chunk of stream) {
         if (signal.aborted) {
@@ -1049,6 +1199,8 @@ async function runTurn(session, turnContext, input) {
             iterInputTokens = chunk.inputTokens;
           if (chunk.outputTokens !== undefined)
             iterOutputTokens = chunk.outputTokens;
+          if (chunk.cachedTokens !== undefined)
+            accumulatedCachedTokens += chunk.cachedTokens;
         } else if (chunk.type === "error") {
           throw chunk.error;
         }
@@ -1160,7 +1312,10 @@ async function runTurn(session, turnContext, input) {
           session.addHistoryItem({
             id: `msg_nudge_${Date.now()}`,
             type: "user_message",
-            content: "Please proceed with executing the task. Provide your complete analysis or call the required tools now.",
+            content: `[Systematic ReAct Nudge]: No tool actions or answers were produced in this iteration.
+1. Review the user's objective and determine the immediate next action.
+2. If more context is required, invoke an exploration tool ('read_file', 'list_dir', 'grep_search', 'find_files').
+3. If ready to answer or implement, call the required mutating tool or deliver your full, concrete response now.`,
             createdAt: Date.now()
           });
           continue;
@@ -1169,13 +1324,14 @@ async function runTurn(session, turnContext, input) {
       break;
     }
     const totalContextTokens = estimateTotalTokens(session.getHistory()) + Math.ceil(effectiveSystemPrompt.length / 4);
-    const maxContextTokens = 128000;
+    const maxContextTokens = DEFAULT_MAX_CONTEXT_TOKENS;
     session.emitEvent({
       type: "TurnCompleted",
       turnId,
       inputTokens: accumulatedInputTokens,
       outputTokens: accumulatedOutputTokens,
       totalTokens: accumulatedInputTokens + accumulatedOutputTokens,
+      cachedTokens: accumulatedCachedTokens > 0 ? accumulatedCachedTokens : undefined,
       contextTokens: totalContextTokens,
       maxContextTokens
     });
@@ -1190,6 +1346,8 @@ async function runTurn(session, turnContext, input) {
     });
   } finally {
     session.clearActiveTurn(turnId);
+    globalEphemeralWorkspace.cleanupTurn(turnId);
+    globalEphemeralWorkspace.cleanRootResidue(turnContext.environment.cwd);
   }
 }
 
@@ -1289,9 +1447,9 @@ class ExecPolicy {
   shouldPromptFileEdit(filePath) {
     if (this.mode === "plan") {
       return {
-        prompt: false,
+        prompt: true,
         isPlanBlocked: true,
-        reason: "Plan Mode is active. Mutating files is not allowed while planning."
+        reason: `[Plan Mode Gate] Approval required to mutate '${filePath || "file"}' and proceed with implementation.`
       };
     }
     if (this.mode === "manual") {
@@ -1305,11 +1463,14 @@ class ExecPolicy {
   evaluate(command) {
     const trimmed = command.trim();
     if (this.mode === "plan") {
-      const isReadOnly = /^(git\s+(status|log|diff|branch|show)|ls|dir|cat|type|grep|rg|find|pwd|which|where)\b/i.test(trimmed);
+      const isReadOnly = /^(git\s+(status|log|diff|branch|show|rev-parse)|ls|dir|cat|type|grep|rg|find|pwd|which|where)\b/i.test(trimmed);
       if (isReadOnly) {
         return { decision: "allow", reason: "Read-only inspection allowed in Plan mode" };
       }
-      return { decision: "deny", reason: "Cannot execute mutating shell commands in Plan mode" };
+      return {
+        decision: "prompt",
+        reason: `[Plan Mode Gate] Approval required to execute shell command '${trimmed}' in Plan Mode`
+      };
     }
     if (this.mode === "manual") {
       return {
@@ -1580,9 +1741,9 @@ class Session {
   }
 }
 // src/tools/handlers/apply-patch.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
 import { resolve as resolve5, dirname as dirname3 } from "path";
-import { mkdirSync as mkdirSync3 } from "fs";
+import { mkdirSync as mkdirSync4 } from "fs";
 var applyPatchTool = {
   name: "apply_patch",
   description: "Apply precise multi-line modifications to an existing file or create a new file. TargetContent must match the file content exactly.",
@@ -1614,34 +1775,40 @@ var applyPatchTool = {
     const replacementContent = String(args.replacementContent ?? "");
     if (ctx.execPolicy) {
       const evalResult = ctx.execPolicy.shouldPromptFileEdit(rawPath);
-      if (evalResult.isPlanBlocked || ctx.mode === "plan") {
-        return {
-          output: "Error: Cannot mutate files while in Plan Mode. Please present the implementation plan first.",
-          isError: true
-        };
-      }
       if (evalResult.prompt && ctx.requestApproval) {
-        const approval = await ctx.requestApproval(`Apply patch to: ${rawPath}`, `apply_patch ${rawPath}`);
+        const approval = await ctx.requestApproval(evalResult.reason || `Apply patch to: ${rawPath}`, `apply_patch ${rawPath}`);
         const allowed = typeof approval === "object" ? approval.allowed : Boolean(approval);
         if (!allowed) {
-          return { output: `Action rejected by user: apply_patch '${rawPath}'`, isError: true };
+          return {
+            output: `[Plan Mode Gate]: File modification declined by user for '${rawPath}'. Please refine your implementation plan or ask the user for guidance.`,
+            isError: true
+          };
         }
+      } else if (evalResult.isPlanBlocked || ctx.mode === "plan") {
+        return {
+          output: `[Plan Mode Gate]: Cannot mutate '${rawPath}' while in Plan Mode without user approval. Please present your implementation plan first.`,
+          isError: true
+        };
       }
     }
-    if (!existsSync5(filePath)) {
+    if (!existsSync6(filePath)) {
       if (targetContent) {
         return {
-          output: `Error: Target file '${rawPath}' does not exist, but targetContent was provided.`,
+          output: `Error: Target file '${rawPath}' does not exist, but targetContent was provided.
+[Systematic Error Recovery Checklist]:
+1. Root Cause: Trying to patch a non-existent file with targetContent.
+2. Fix: For creating new files, leave 'targetContent' empty and provide full contents in 'replacementContent'.
+3. Alternatively, check if the file path '${rawPath}' was mistyped.`,
           isError: true
         };
       }
       try {
-        mkdirSync3(dirname3(filePath), { recursive: true });
+        mkdirSync4(dirname3(filePath), { recursive: true });
         writeFileSync2(filePath, replacementContent, "utf8");
         return { output: `Successfully created new file '${rawPath}'` };
       } catch (err) {
         return {
-          output: `Failed to create file: ${err instanceof Error ? err.message : String(err)}`,
+          output: `Failed to create file '${rawPath}': ${err instanceof Error ? err.message : String(err)}`,
           isError: true
         };
       }
@@ -1650,21 +1817,33 @@ var applyPatchTool = {
       const originalFileContent = readFileSync4(filePath, "utf8");
       if (!targetContent) {
         return {
-          output: `Error: File '${rawPath}' already exists. Specify targetContent to replace specific lines or use overwrite.`,
+          output: `Error: File '${rawPath}' already exists, but targetContent was empty.
+[Systematic Error Recovery Checklist]:
+1. Root Cause: An existing file requires targetContent to specify which lines to replace.
+2. Fix: Call 'read_file' on '${rawPath}', extract the exact target lines, and provide them in 'targetContent'.
+3. To overwrite the whole file, use the 'write_file' tool instead.`,
           isError: true
         };
       }
       const firstIndex = originalFileContent.indexOf(targetContent);
       if (firstIndex === -1) {
         return {
-          output: `Error: targetContent was not found in '${rawPath}'. Please verify file contents before editing.`,
+          output: `Error: targetContent was not found in '${rawPath}'.
+[Systematic Error Recovery Checklist]:
+1. Root Cause: The snippet in targetContent does not match the actual file content (differences in whitespace, indentation, line endings, or prior edits).
+2. Action: Call 'read_file' on '${rawPath}' to inspect current exact lines and indentation.
+3. Fix: Provide the exact matching lines (including leading spaces) or wider context, then retry 'apply_patch'.`,
           isError: true
         };
       }
       const secondIndex = originalFileContent.indexOf(targetContent, firstIndex + 1);
       if (secondIndex !== -1) {
         return {
-          output: `Error: targetContent matched multiple locations in '${rawPath}'. Provide more surrounding context lines to ensure uniqueness.`,
+          output: `Error: targetContent matched multiple locations in '${rawPath}'.
+[Systematic Error Recovery Checklist]:
+1. Root Cause: targetContent is ambiguous and occurs multiple times in the file.
+2. Action: Include 2-3 additional surrounding lines (before or after the target block) to make the target snippet uniquely identifiable.
+3. Fix: Re-run 'apply_patch' with the extended unique block.`,
           isError: true
         };
       }
@@ -1675,7 +1854,7 @@ var applyPatchTool = {
       };
     } catch (err) {
       return {
-        output: `Failed to apply patch: ${err instanceof Error ? err.message : String(err)}`,
+        output: `Failed to apply patch to '${rawPath}': ${err instanceof Error ? err.message : String(err)}`,
         isError: true
       };
     }
@@ -1762,7 +1941,7 @@ class WindowsSandbox {
 }
 
 // src/security/kernel/linux.ts
-import { existsSync as existsSync6 } from "fs";
+import { existsSync as existsSync7 } from "fs";
 
 class LinuxSandbox {
   hasBwrap = false;
@@ -1773,7 +1952,7 @@ class LinuxSandbox {
     if (process.platform !== "linux") {
       return;
     }
-    this.hasBwrap = existsSync6("/usr/bin/bwrap") || existsSync6("/bin/bwrap") || existsSync6("/usr/local/bin/bwrap");
+    this.hasBwrap = existsSync7("/usr/bin/bwrap") || existsSync7("/bin/bwrap") || existsSync7("/usr/local/bin/bwrap");
   }
   wrapCommand(cmd, profile) {
     if (!this.hasBwrap || profile.kind === "danger-unrestricted") {
@@ -1807,7 +1986,7 @@ class LinuxSandbox {
 }
 
 // src/security/kernel/macos.ts
-import { existsSync as existsSync7 } from "fs";
+import { existsSync as existsSync8 } from "fs";
 
 class MacOSSandbox {
   hasSandboxExec = false;
@@ -1818,7 +1997,7 @@ class MacOSSandbox {
     if (process.platform !== "darwin") {
       return;
     }
-    this.hasSandboxExec = existsSync7("/usr/bin/sandbox-exec");
+    this.hasSandboxExec = existsSync8("/usr/bin/sandbox-exec");
   }
   generateProfile(profile) {
     const rules = [
@@ -1928,7 +2107,7 @@ var globalKernelSandbox = new KernelSandboxManager;
 
 // src/storage/prefix-rules-store.ts
 import { Database } from "bun:sqlite";
-import { existsSync as existsSync8, mkdirSync as mkdirSync4 } from "fs";
+import { existsSync as existsSync9, mkdirSync as mkdirSync5 } from "fs";
 import { dirname as dirname4, resolve as resolve7 } from "path";
 class PrefixRulesStore {
   db;
@@ -1939,8 +2118,8 @@ class PrefixRulesStore {
       const effectivePath = dbOrPath || getPrefixRulesDbPath();
       if (effectivePath !== ":memory:") {
         const dir = dirname4(effectivePath);
-        if (!existsSync8(dir)) {
-          mkdirSync4(dir, { recursive: true });
+        if (!existsSync9(dir)) {
+          mkdirSync5(dir, { recursive: true });
         }
       }
       this.db = new Database(effectivePath);
@@ -2129,6 +2308,7 @@ function createShellTool(policy = new ExecPolicy) {
       const timeoutMs = typeof args.timeoutMs === "number" ? args.timeoutMs : 30000;
       const isWindows = process.platform === "win32";
       const baseCmd = isWindows ? ["cmd.exe", "/d", "/s", "/c", command] : ["/bin/sh", "-c", command];
+      const ephemeralScratchpad = globalEphemeralWorkspace.createScratchpad(ctx.turnId);
       const sandboxProfile = globalKernelSandbox.buildDefaultProfile(ctx.cwd);
       if (isEscalated) {
         sandboxProfile.allowNetwork = true;
@@ -2139,6 +2319,10 @@ function createShellTool(policy = new ExecPolicy) {
           cwd: ctx.cwd,
           env: {
             ...process.env,
+            TMPDIR: ephemeralScratchpad,
+            TEMP: ephemeralScratchpad,
+            TMP: ephemeralScratchpad,
+            GROUPY_SCRATCH_DIR: ephemeralScratchpad,
             ...ctx.proxyEnv
           },
           stdout: "pipe",
@@ -2175,9 +2359,14 @@ function createShellTool(policy = new ExecPolicy) {
         if (result.stderr)
           outputParts.push(`STDERR:
 ${result.stderr.trim()}`);
-        if (result.code !== 0)
+        if (result.code !== 0) {
           outputParts.push(`
-[Process exited with code ${result.code}]`);
+[Process exited with non-zero code ${result.code}]`);
+          outputParts.push(`[Systematic Error Recovery Checklist]:
+1. Inspect STDERR above to pinpoint syntax errors, failed test assertions, or missing dependencies.
+2. If this is a test failure, trace the failure in source code and fix the root cause before re-running.
+3. If this is a missing command/module, install or configure the prerequisite.`);
+        }
         const output = outputParts.join(`
 `) || "[Command completed with no output]";
         return {
@@ -2186,16 +2375,21 @@ ${result.stderr.trim()}`);
         };
       } catch (err) {
         return {
-          output: `Execution error: ${err instanceof Error ? err.message : String(err)}`,
+          output: `Execution error: ${err instanceof Error ? err.message : String(err)}
+[Systematic Error Recovery Checklist]:
+1. Verify command syntax, arguments, and executable availability in PATH.
+2. Check if the current working directory ('${ctx.cwd}') is valid.`,
           isError: true
         };
+      } finally {
+        globalEphemeralWorkspace.cleanup(ephemeralScratchpad);
       }
     }
   };
 }
 var shellTool = createShellTool();
 // src/tools/handlers/file-ops.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync5, writeFileSync as writeFileSync3, existsSync as existsSync9, statSync as statSync2, mkdirSync as mkdirSync5 } from "fs";
+import { readdirSync as readdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3, existsSync as existsSync10, statSync as statSync3, mkdirSync as mkdirSync6 } from "fs";
 import { resolve as resolve8, dirname as dirname5 } from "path";
 var readFileTool = {
   name: "read_file",
@@ -2209,7 +2403,7 @@ var readFileTool = {
   },
   async execute(args, ctx) {
     const filePath = resolve8(ctx.cwd, String(args.path || ""));
-    if (!existsSync9(filePath)) {
+    if (!existsSync10(filePath)) {
       return { output: `Error: File not found: '${args.path}'`, isError: true };
     }
     try {
@@ -2231,14 +2425,14 @@ var listDirTool = {
   },
   async execute(args, ctx) {
     const dirPath = resolve8(ctx.cwd, String(args.path || "."));
-    if (!existsSync9(dirPath)) {
+    if (!existsSync10(dirPath)) {
       return { output: `Error: Directory not found: '${args.path}'`, isError: true };
     }
     try {
-      const entries = readdirSync2(dirPath);
+      const entries = readdirSync3(dirPath);
       const formatted = entries.map((entry) => {
         const full = resolve8(dirPath, entry);
-        const isDir = statSync2(full).isDirectory();
+        const isDir = statSync3(full).isDirectory();
         return `${isDir ? "[DIR]" : "[FILE]"} ${entry}`;
       });
       return { output: formatted.join(`
@@ -2264,26 +2458,35 @@ var writeFileTool = {
     const filePath = resolve8(ctx.cwd, rawPath);
     if (ctx.execPolicy) {
       const evalResult = ctx.execPolicy.shouldPromptFileEdit(rawPath);
-      if (evalResult.isPlanBlocked || ctx.mode === "plan") {
-        return {
-          output: "Error: Cannot write or mutate files while in Plan Mode. Please present the implementation plan first.",
-          isError: true
-        };
-      }
       if (evalResult.prompt && ctx.requestApproval) {
-        const approval = await ctx.requestApproval(`Write file: ${rawPath}`, `write_file ${rawPath}`);
+        const approval = await ctx.requestApproval(evalResult.reason || `Write file: ${rawPath}`, `write_file ${rawPath}`);
         const allowed = typeof approval === "object" ? approval.allowed : Boolean(approval);
         if (!allowed) {
-          return { output: `Action rejected by user: write_file '${rawPath}'`, isError: true };
+          return {
+            output: `[Plan Mode Gate]: File creation declined by user for '${rawPath}'. Please refine your implementation plan or ask the user for guidance.`,
+            isError: true
+          };
         }
+      } else if (evalResult.isPlanBlocked || ctx.mode === "plan") {
+        return {
+          output: `[Plan Mode Gate]: Cannot write or mutate '${rawPath}' while in Plan Mode without user approval. Please present your implementation plan first.`,
+          isError: true
+        };
       }
     }
     try {
-      mkdirSync5(dirname5(filePath), { recursive: true });
+      mkdirSync6(dirname5(filePath), { recursive: true });
       writeFileSync3(filePath, String(args.content ?? ""), "utf8");
       return { output: `Successfully wrote to '${args.path}'` };
     } catch (err) {
-      return { output: `Failed to write file: ${err instanceof Error ? err.message : String(err)}`, isError: true };
+      return {
+        output: `Failed to write file '${rawPath}': ${err instanceof Error ? err.message : String(err)}
+[Systematic Error Recovery Checklist]:
+1. Check directory permissions and ensure the path is valid within the workspace.
+2. If the path contains non-existent nested folders, they should be auto-created.
+3. Verify that the file is not locked by another active process.`,
+        isError: true
+      };
     }
   }
 };
@@ -2402,8 +2605,8 @@ var updatePlanTool = {
   }
 };
 // src/search/engine.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync6, statSync as statSync3, existsSync as existsSync10 } from "fs";
-import { resolve as resolve9, relative, join as join4, extname } from "path";
+import { readdirSync as readdirSync4, readFileSync as readFileSync6, statSync as statSync4, existsSync as existsSync11 } from "fs";
+import { resolve as resolve9, relative, join as join5, extname } from "path";
 var DEFAULT_IGNORE_DIRS = new Set([
   ".git",
   "node_modules",
@@ -2449,7 +2652,7 @@ var BINARY_EXTENSIONS = new Set([
 class FileSearchEngine {
   grep(cwd, options) {
     const searchRoot = resolve9(cwd, options.path || ".");
-    if (!existsSync10(searchRoot)) {
+    if (!existsSync11(searchRoot)) {
       return { matches: [], totalMatches: 0, truncated: false };
     }
     const maxResults = options.maxResults || 50;
@@ -2499,7 +2702,7 @@ class FileSearchEngine {
   }
   findFiles(cwd, options) {
     const searchRoot = resolve9(cwd, options.path || ".");
-    if (!existsSync10(searchRoot))
+    if (!existsSync11(searchRoot))
       return [];
     const maxResults = options.maxResults || 100;
     const gitignoreRules = this.loadGitignoreRules(searchRoot);
@@ -2538,8 +2741,8 @@ class FileSearchEngine {
   }
   loadGitignoreRules(root) {
     const rules = new Set;
-    const gitignorePath = join4(root, ".gitignore");
-    if (existsSync10(gitignorePath)) {
+    const gitignorePath = join5(root, ".gitignore");
+    if (existsSync11(gitignorePath)) {
       try {
         const lines = readFileSync6(gitignorePath, "utf8").split(`
 `);
@@ -2556,7 +2759,7 @@ class FileSearchEngine {
   collectFiles(dir, root, gitignoreRules, includePattern) {
     const results = [];
     try {
-      const stat = statSync3(dir);
+      const stat = statSync4(dir);
       if (!stat.isDirectory()) {
         if (!this.isBinary(dir)) {
           results.push(dir);
@@ -2570,9 +2773,9 @@ class FileSearchEngine {
     while (queue.length > 0) {
       const currentDir = queue.shift();
       try {
-        const entries = readdirSync3(currentDir, { withFileTypes: true });
+        const entries = readdirSync4(currentDir, { withFileTypes: true });
         for (const entry of entries) {
-          const fullPath = join4(currentDir, entry.name);
+          const fullPath = join5(currentDir, entry.name);
           const relToRoot = relative(root, fullPath).replace(/\\/g, "/");
           if (this.isIgnored(entry.name, relToRoot, gitignoreRules)) {
             continue;
@@ -3271,8 +3474,8 @@ function createDefaultTools(options = {}) {
 }
 
 // src/agents/roles.ts
-import { existsSync as existsSync11, readdirSync as readdirSync4, readFileSync as readFileSync7 } from "fs";
-import { resolve as resolve10, join as join5 } from "path";
+import { existsSync as existsSync12, readdirSync as readdirSync5, readFileSync as readFileSync7 } from "fs";
+import { resolve as resolve10, join as join6 } from "path";
 
 class AgentRoleRegistry {
   roles = new Map;
@@ -3357,13 +3560,13 @@ class AgentRoleRegistry {
   }
   loadRolesFromDir(dirPath) {
     const fullPath = resolve10(dirPath);
-    if (!existsSync11(fullPath))
+    if (!existsSync12(fullPath))
       return;
-    const entries = readdirSync4(fullPath);
+    const entries = readdirSync5(fullPath);
     for (const entry of entries) {
       if (entry.endsWith(".json")) {
         try {
-          const content = readFileSync7(join5(fullPath, entry), "utf8");
+          const content = readFileSync7(join6(fullPath, entry), "utf8");
           const parsed = JSON.parse(content);
           if (parsed.name && parsed.systemPrompt) {
             this.registerRole(parsed);
@@ -3416,7 +3619,7 @@ function createAgentIdentity(parentId, harnessId = "groupy-harness-v1") {
 // src/agents/graph-store.ts
 import { Database as Database2 } from "bun:sqlite";
 import { resolve as resolve11 } from "path";
-import { existsSync as existsSync12, mkdirSync as mkdirSync6 } from "fs";
+import { existsSync as existsSync13, mkdirSync as mkdirSync7 } from "fs";
 class AgentGraphStore {
   db;
   constructor(dbPathOrDb) {
@@ -3426,8 +3629,8 @@ class AgentGraphStore {
       const dbPath = dbPathOrDb || getAgentGraphDbPath();
       if (dbPath !== ":memory:") {
         const dir = resolve11(dbPath, "..");
-        if (!existsSync12(dir)) {
-          mkdirSync6(dir, { recursive: true });
+        if (!existsSync13(dir)) {
+          mkdirSync7(dir, { recursive: true });
         }
       }
       this.db = new Database2(dbPath);
@@ -3851,8 +4054,8 @@ function registerMultiAgentTools(router2, spawner) {
 }
 
 // src/mcp/manager.ts
-import { existsSync as existsSync13, readFileSync as readFileSync8, writeFileSync as writeFileSync4, mkdirSync as mkdirSync7 } from "fs";
-import { resolve as resolve12, dirname as dirname6, join as join6 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync8, writeFileSync as writeFileSync4, mkdirSync as mkdirSync8 } from "fs";
+import { resolve as resolve12, dirname as dirname6, join as join7 } from "path";
 
 // src/mcp/client.ts
 class McpClient {
@@ -4468,7 +4671,7 @@ class McpManager {
   }
   async loadConfigFile(filePath) {
     const fullPath = resolve12(filePath);
-    if (!existsSync13(fullPath))
+    if (!existsSync14(fullPath))
       return;
     this.loadedConfigFiles.add(fullPath);
     try {
@@ -4723,11 +4926,11 @@ class McpManager {
   saveServerToConfigFile(filePath, name, config) {
     const fullPath = resolve12(filePath);
     const dir = dirname6(fullPath);
-    if (!existsSync13(dir)) {
-      mkdirSync7(dir, { recursive: true });
+    if (!existsSync14(dir)) {
+      mkdirSync8(dir, { recursive: true });
     }
     let existing = { mcpServers: {} };
-    if (existsSync13(fullPath)) {
+    if (existsSync14(fullPath)) {
       try {
         const content = readFileSync8(fullPath, "utf8");
         existing = JSON.parse(content);
@@ -4742,7 +4945,7 @@ class McpManager {
   }
   removeServerFromConfigFile(filePath, name) {
     const fullPath = resolve12(filePath);
-    if (!existsSync13(fullPath))
+    if (!existsSync14(fullPath))
       return false;
     try {
       const content = readFileSync8(fullPath, "utf8");
@@ -4772,11 +4975,11 @@ class McpManager {
     }
   }
   getDefaultConfigFile(cwd = process.cwd()) {
-    const workspaceConfig = join6(cwd, ".mcp.json");
-    if (existsSync13(workspaceConfig))
+    const workspaceConfig = join7(cwd, ".mcp.json");
+    if (existsSync14(workspaceConfig))
       return workspaceConfig;
-    const altConfig = join6(cwd, "mcp_config.json");
-    if (existsSync13(altConfig))
+    const altConfig = join7(cwd, "mcp_config.json");
+    if (existsSync14(altConfig))
       return altConfig;
     return workspaceConfig;
   }
@@ -4797,7 +5000,7 @@ class McpManager {
 
 // src/storage/sqlite-store.ts
 import { Database as Database3 } from "bun:sqlite";
-import { existsSync as existsSync14, mkdirSync as mkdirSync8 } from "fs";
+import { existsSync as existsSync15, mkdirSync as mkdirSync9 } from "fs";
 import { dirname as dirname7 } from "path";
 class SqliteThreadStore {
   db;
@@ -4805,8 +5008,8 @@ class SqliteThreadStore {
     const effectivePath = dbPath || this.getDefaultDbPath();
     if (effectivePath !== ":memory:") {
       const dir = dirname7(effectivePath);
-      if (!existsSync14(dir)) {
-        mkdirSync8(dir, { recursive: true });
+      if (!existsSync15(dir)) {
+        mkdirSync9(dir, { recursive: true });
       }
     }
     this.db = new Database3(effectivePath);
@@ -5040,8 +5243,8 @@ class SessionPersistenceManager {
 }
 
 // src/skills/loader.ts
-import { existsSync as existsSync15, readdirSync as readdirSync5, readFileSync as readFileSync9 } from "fs";
-import { resolve as resolve13, join as join7 } from "path";
+import { existsSync as existsSync16, readdirSync as readdirSync6, readFileSync as readFileSync9 } from "fs";
+import { resolve as resolve13, join as join8 } from "path";
 import { homedir as homedir3 } from "os";
 var __dirname = "/home/runner/work/agent-cli/agent-cli/src/skills";
 
@@ -5112,7 +5315,7 @@ class SkillsLoader {
         resolve13(cwd, "skills")
       ];
       for (const cand of candidates) {
-        if (existsSync15(cand) && !roots.includes(cand)) {
+        if (existsSync16(cand) && !roots.includes(cand)) {
           roots.push(cand);
         }
       }
@@ -5121,7 +5324,7 @@ class SkillsLoader {
       roots.push(getGlobalSkillsDir(), resolve13(homedir3(), ".gemini", "config", "skills"));
     }
     roots.push(...this.customRoots.map((r) => resolve13(r)));
-    return roots.filter((r) => existsSync15(r));
+    return roots.filter((r) => existsSync16(r));
   }
   discoverSkills(cwd, options) {
     return this.listSkills(cwd, options);
@@ -5137,12 +5340,12 @@ class SkillsLoader {
     const discovered = new Map;
     for (const root of roots) {
       try {
-        const entries = readdirSync5(root, { withFileTypes: true });
+        const entries = readdirSync6(root, { withFileTypes: true });
         for (const entry of entries) {
           if (entry.isDirectory()) {
-            const skillDir = join7(root, entry.name);
-            const skillFilePath = join7(skillDir, "SKILL.md");
-            if (existsSync15(skillFilePath)) {
+            const skillDir = join8(root, entry.name);
+            const skillFilePath = join8(skillDir, "SKILL.md");
+            if (existsSync16(skillFilePath)) {
               const meta = this.parseSkillFrontmatter(skillFilePath, entry.name, root, cwd);
               if (meta && !discovered.has(meta.name)) {
                 meta.enabled = !this.isSkillDisabled(meta.name);
@@ -5155,7 +5358,7 @@ class SkillsLoader {
         }
       } catch {}
     }
-    const result = Array.from(discovered.values());
+    const result = Array.from(discovered.values()).sort((a, b) => a.name.localeCompare(b.name));
     this.skillsCache.set(cacheKey, { timestamp: now, skills: result });
     return result;
   }
@@ -5244,10 +5447,10 @@ class SkillsLoader {
     const skills = this.listSkills(cwd, { includeDisabled: false });
     if (skills.length === 0)
       return "";
-    const workspaceSkills = skills.filter((s) => s.scope === "workspace");
-    const builtInSkills = skills.filter((s) => s.scope === "built-in");
-    const otherSkills = skills.filter((s) => s.scope !== "workspace" && s.scope !== "built-in");
-    const selectedSkills = [...workspaceSkills, ...builtInSkills, ...otherSkills].slice(0, 150);
+    const workspaceSkills = skills.filter((s) => s.scope === "workspace").sort((a, b) => a.name.localeCompare(b.name));
+    const builtInSkills = skills.filter((s) => s.scope === "built-in").sort((a, b) => a.name.localeCompare(b.name));
+    const otherSkills = skills.filter((s) => s.scope !== "workspace" && s.scope !== "built-in").sort((a, b) => a.name.localeCompare(b.name));
+    const selectedSkills = [...workspaceSkills, ...builtInSkills, ...otherSkills].slice(0, 300);
     const lines = selectedSkills.map((s) => {
       const desc = s.shortDescription || s.description;
       return `- **${s.name}**: ${desc}`;
@@ -5265,8 +5468,8 @@ When tackling complex specialized tasks that match any of these skills, autonomo
 }
 
 // src/memories/store.ts
-import { existsSync as existsSync16, readFileSync as readFileSync10, writeFileSync as writeFileSync5, mkdirSync as mkdirSync9, readdirSync as readdirSync6 } from "fs";
-import { resolve as resolve14, join as join8, basename, dirname as dirname8 } from "path";
+import { existsSync as existsSync17, readFileSync as readFileSync10, writeFileSync as writeFileSync5, mkdirSync as mkdirSync10, readdirSync as readdirSync7 } from "fs";
+import { resolve as resolve14, join as join9, basename, dirname as dirname8 } from "path";
 import { createHash } from "crypto";
 class MemoryStore {
   globalPath;
@@ -5278,7 +5481,7 @@ class MemoryStore {
   findProjectRoot(cwd) {
     let current = resolve14(cwd);
     while (true) {
-      if (existsSync16(join8(current, ".git"))) {
+      if (existsSync17(join9(current, ".git"))) {
         return current;
       }
       const parent = dirname8(current);
@@ -5297,24 +5500,24 @@ class MemoryStore {
   getProjectMemoryDir(cwd) {
     if (this.customWorkspacePath) {
       const dir2 = resolve14(this.customWorkspacePath);
-      if (!existsSync16(dir2)) {
+      if (!existsSync17(dir2)) {
         try {
-          mkdirSync9(dir2, { recursive: true });
+          mkdirSync10(dir2, { recursive: true });
         } catch {}
       }
       return dir2;
     }
     const slug = this.getProjectSlug(cwd);
-    const dir = join8(getProjectsDir(), slug, "memory");
-    if (!existsSync16(dir)) {
+    const dir = join9(getProjectsDir(), slug, "memory");
+    if (!existsSync17(dir)) {
       try {
-        mkdirSync9(dir, { recursive: true });
+        mkdirSync10(dir, { recursive: true });
       } catch {}
     }
     return dir;
   }
   getMemoryIndexPath(cwd) {
-    return join8(this.getProjectMemoryDir(cwd), "MEMORY.md");
+    return join9(this.getProjectMemoryDir(cwd), "MEMORY.md");
   }
   normalizeCategory(raw) {
     const cat = raw.toLowerCase().trim();
@@ -5333,7 +5536,7 @@ class MemoryStore {
     const sanitizedName = params.name.toLowerCase().trim().replace(/[^a-z0-9_-]/g, "_").replace(/^_+|_+$/g, "") || `note_${Date.now()}`;
     const memoryDir = this.getProjectMemoryDir(params.cwd);
     const fileName = `${type}_${sanitizedName}.md`;
-    const filePath = join8(memoryDir, fileName);
+    const filePath = join9(memoryDir, fileName);
     const nowIso = new Date().toISOString();
     const cleanContent = params.content.trim();
     const desc = (params.description || cleanContent.split(`
@@ -5368,17 +5571,17 @@ class MemoryStore {
   }
   readTopicMemory(topicNameOrFile, cwd) {
     const memoryDir = this.getProjectMemoryDir(cwd);
-    let targetPath = join8(memoryDir, topicNameOrFile);
-    if (!existsSync16(targetPath)) {
+    let targetPath = join9(memoryDir, topicNameOrFile);
+    if (!existsSync17(targetPath)) {
       if (!topicNameOrFile.endsWith(".md")) {
-        targetPath = join8(memoryDir, `${topicNameOrFile}.md`);
+        targetPath = join9(memoryDir, `${topicNameOrFile}.md`);
       }
     }
-    if (!existsSync16(targetPath)) {
-      const files = readdirSync6(memoryDir);
+    if (!existsSync17(targetPath)) {
+      const files = readdirSync7(memoryDir);
       const match = files.find((f) => f.includes(topicNameOrFile));
       if (match) {
-        targetPath = join8(memoryDir, match);
+        targetPath = join9(memoryDir, match);
       } else {
         return null;
       }
@@ -5439,12 +5642,12 @@ class MemoryStore {
   }
   syncMemoryIndex(cwd) {
     const memoryDir = this.getProjectMemoryDir(cwd);
-    const indexPath = join8(memoryDir, "MEMORY.md");
-    const files = existsSync16(memoryDir) ? readdirSync6(memoryDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md") : [];
+    const indexPath = join9(memoryDir, "MEMORY.md");
+    const files = existsSync17(memoryDir) ? readdirSync7(memoryDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md") : [];
     const items = [];
     for (const f of files) {
       try {
-        const full = join8(memoryDir, f);
+        const full = join9(memoryDir, f);
         const parsed = this.parseTopicFile(readFileSync10(full, "utf8"), full);
         items.push({
           type: parsed.type,
@@ -5471,7 +5674,7 @@ class MemoryStore {
   }
   loadMemoryIndex(cwd) {
     const indexPath = this.getMemoryIndexPath(cwd);
-    if (!existsSync16(indexPath))
+    if (!existsSync17(indexPath))
       return "";
     try {
       const raw = readFileSync10(indexPath, "utf8");
@@ -5487,13 +5690,13 @@ class MemoryStore {
   }
   listProjectMemories(cwd) {
     const memoryDir = this.getProjectMemoryDir(cwd);
-    if (!existsSync16(memoryDir))
+    if (!existsSync17(memoryDir))
       return [];
-    const files = readdirSync6(memoryDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md");
+    const files = readdirSync7(memoryDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md");
     const list = [];
     for (const f of files) {
       try {
-        const full = join8(memoryDir, f);
+        const full = join9(memoryDir, f);
         list.push(this.parseTopicFile(readFileSync10(full, "utf8"), full));
       } catch {}
     }
@@ -5545,8 +5748,8 @@ class MemoryStore {
 }
 
 // src/worktree/manager.ts
-import { resolve as resolve16, join as join9 } from "path";
-import { existsSync as existsSync17, mkdirSync as mkdirSync10, writeFileSync as writeFileSync6, readFileSync as readFileSync11 } from "fs";
+import { resolve as resolve16, join as join10 } from "path";
+import { existsSync as existsSync18, mkdirSync as mkdirSync11, writeFileSync as writeFileSync6, readFileSync as readFileSync11 } from "fs";
 
 // src/worktree/git.ts
 import { resolve as resolve15 } from "path";
@@ -5696,15 +5899,15 @@ class WorktreeManager {
     const branchName = options.branch || `groupy/${taskId}`;
     const targetDir = options.worktreePath || (this.baseStorageDir ? resolve16(this.baseStorageDir, branchName.replace(/\//g, "_")) : resolve16(repoRoot, ".groupy", "worktrees", branchName.replace(/\//g, "_")));
     const worktreeParent = resolve16(targetDir, "..");
-    if (!existsSync17(worktreeParent)) {
-      mkdirSync10(worktreeParent, { recursive: true });
+    if (!existsSync18(worktreeParent)) {
+      mkdirSync11(worktreeParent, { recursive: true });
     }
     const baseBranch = options.baseBranch || await getCurrentBranch(repoRoot);
     const result = await createWorktreeGit(repoRoot, targetDir, branchName, baseBranch);
     if (!result.success) {
       throw new Error(`Failed to create git worktree: ${result.error}`);
     }
-    const metaPath = join9(targetDir, "groupy-thread.json");
+    const metaPath = join10(targetDir, "groupy-thread.json");
     try {
       writeFileSync6(metaPath, JSON.stringify({
         version: 1,
@@ -5730,8 +5933,8 @@ class WorktreeManager {
       return [];
     const worktrees = await listWorktreesGit(repoRoot);
     return worktrees.map((wt) => {
-      const metaPath = join9(wt.path, "groupy-thread.json");
-      if (existsSync17(metaPath)) {
+      const metaPath = join10(wt.path, "groupy-thread.json");
+      if (existsSync18(metaPath)) {
         try {
           const raw = JSON.parse(readFileSync11(metaPath, "utf8"));
           return { ...wt, threadId: raw.ownerThreadId || raw.threadId };
@@ -6429,7 +6632,7 @@ function parsePatch(oldSrc, newSrc, contextLines = 3) {
 // package.json
 var package_default = {
   name: "@pikaa-ai/pikaa",
-  version: "0.3.18",
+  version: "0.3.20",
   description: "PIKAA CLI - AI coding agent that runs locally in your terminal.",
   main: "./dist/index.js",
   module: "./dist/index.js",
@@ -6804,7 +7007,12 @@ ${preview}${more}`);
     if (metrics.inputTokens !== undefined || metrics.outputTokens !== undefined) {
       const inStr = metrics.inputTokens !== undefined ? formatTokens(metrics.inputTokens) : "0";
       const outStr = metrics.outputTokens !== undefined ? formatTokens(metrics.outputTokens) : "0";
-      parts.push(`${style.cyan(`${inStr} in`)} ${style.dim("/")} ${style.cyan(`${outStr} out`)}`);
+      if (metrics.cachedTokens !== undefined && metrics.cachedTokens > 0) {
+        const cachedStr = formatTokens(metrics.cachedTokens);
+        parts.push(`${style.cyan(`${inStr} in`)} ${style.dim(`(${cachedStr} cached)`)} ${style.dim("/")} ${style.cyan(`${outStr} out`)}`);
+      } else {
+        parts.push(`${style.cyan(`${inStr} in`)} ${style.dim("/")} ${style.cyan(`${outStr} out`)}`);
+      }
     } else if (metrics.totalTokens !== undefined && metrics.totalTokens > 0) {
       parts.push(`${style.dim(`${formatTokens(metrics.totalTokens)} tokens`)}`);
     }
@@ -7921,8 +8129,8 @@ async function promptInteractiveList(config) {
 }
 
 // src/security/scanner.ts
-import { existsSync as existsSync18, readdirSync as readdirSync7, readFileSync as readFileSync12, statSync as statSync4 } from "fs";
-import { join as join10, relative as relative2, resolve as resolve17 } from "path";
+import { existsSync as existsSync19, readdirSync as readdirSync8, readFileSync as readFileSync12, statSync as statSync5 } from "fs";
+import { join as join11, relative as relative2, resolve as resolve17 } from "path";
 var SECURITY_RULES = [
   {
     id: "SEC-001",
@@ -8060,21 +8268,21 @@ async function runSecurityScan(targetDir, options = {}) {
   const findings = [];
   let scannedCount = 0;
   function walk(current) {
-    if (scannedCount >= maxFiles || !existsSync18(current))
+    if (scannedCount >= maxFiles || !existsSync19(current))
       return;
     let entries;
     try {
-      entries = readdirSync7(current);
+      entries = readdirSync8(current);
     } catch {
       return;
     }
     for (const entry of entries) {
       if (scannedCount >= maxFiles)
         break;
-      const fullPath = join10(current, entry);
+      const fullPath = join11(current, entry);
       let stat;
       try {
-        stat = statSync4(fullPath);
+        stat = statSync5(fullPath);
       } catch {
         continue;
       }
@@ -8179,8 +8387,8 @@ var __dirname = "/home/runner/work/agent-cli/agent-cli/src/mcp/servers/sqlite";
 var SQLITE_MCP_SERVER_PATH = resolve20(__dirname, "server.ts");
 
 // src/init/project-analyzer.ts
-import { existsSync as existsSync19, readFileSync as readFileSync13, readdirSync as readdirSync8 } from "fs";
-import { join as join11, basename as basename3 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync13, readdirSync as readdirSync9 } from "fs";
+import { join as join12, basename as basename3 } from "path";
 
 class ProjectAnalyzer {
   cwd;
@@ -8198,8 +8406,8 @@ class ProjectAnalyzer {
     const architectureNotes = [];
     const codeConventions = [];
     let description = readmeInfo.description;
-    const pkgPath = join11(this.cwd, "package.json");
-    if (existsSync19(pkgPath)) {
+    const pkgPath = join12(this.cwd, "package.json");
+    if (existsSync20(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync13(pkgPath, "utf8"));
         if (!description && pkg.description)
@@ -8272,8 +8480,8 @@ class ProjectAnalyzer {
         }
       } catch {}
     }
-    const tsconfigPath = join11(this.cwd, "tsconfig.json");
-    if (existsSync19(tsconfigPath)) {
+    const tsconfigPath = join12(this.cwd, "tsconfig.json");
+    if (existsSync20(tsconfigPath)) {
       try {
         const tsconfig = JSON.parse(readFileSync13(tsconfigPath, "utf8"));
         if (tsconfig.compilerOptions?.strict) {
@@ -8284,8 +8492,8 @@ class ProjectAnalyzer {
         }
       } catch {}
     }
-    const cargoPath = join11(this.cwd, "Cargo.toml");
-    if (existsSync19(cargoPath)) {
+    const cargoPath = join12(this.cwd, "Cargo.toml");
+    if (existsSync20(cargoPath)) {
       try {
         commands.dev = commands.dev || "cargo run";
         commands.build = commands.build || "cargo build";
@@ -8294,8 +8502,8 @@ class ProjectAnalyzer {
         frameworks.push("Rust Cargo");
       } catch {}
     }
-    const goModPath = join11(this.cwd, "go.mod");
-    if (existsSync19(goModPath)) {
+    const goModPath = join12(this.cwd, "go.mod");
+    if (existsSync20(goModPath)) {
       try {
         commands.dev = commands.dev || "go run .";
         commands.build = commands.build || "go build ./...";
@@ -8304,37 +8512,37 @@ class ProjectAnalyzer {
         frameworks.push("Go Modules");
       } catch {}
     }
-    const pyprojectPath = join11(this.cwd, "pyproject.toml");
-    const requirementsPath = join11(this.cwd, "requirements.txt");
-    if (existsSync19(pyprojectPath) || existsSync19(requirementsPath)) {
+    const pyprojectPath = join12(this.cwd, "pyproject.toml");
+    const requirementsPath = join12(this.cwd, "requirements.txt");
+    if (existsSync20(pyprojectPath) || existsSync20(requirementsPath)) {
       commands.test = commands.test || "pytest";
       commands.lint = commands.lint || "ruff check .";
-      if (existsSync19(join11(this.cwd, "uv.lock"))) {
+      if (existsSync20(join12(this.cwd, "uv.lock"))) {
         frameworks.push("uv");
         commands.test = "uv run pytest";
-      } else if (existsSync19(join11(this.cwd, "poetry.lock"))) {
+      } else if (existsSync20(join12(this.cwd, "poetry.lock"))) {
         frameworks.push("Poetry");
         commands.test = "poetry run pytest";
       }
     }
-    if (existsSync19(join11(this.cwd, "Dockerfile"))) {
+    if (existsSync20(join12(this.cwd, "Dockerfile"))) {
       infrastructure.push("Docker");
       const sanitizedName = projectName.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
       commands.dockerBuild = `docker build -t ${sanitizedName || "app"} .`;
     }
-    if (existsSync19(join11(this.cwd, "nginx.conf"))) {
+    if (existsSync20(join12(this.cwd, "nginx.conf"))) {
       infrastructure.push("Nginx");
     }
-    if (existsSync19(join11(this.cwd, "src/api.ts")) || existsSync19(join11(this.cwd, "src/api"))) {
+    if (existsSync20(join12(this.cwd, "src/api.ts")) || existsSync20(join12(this.cwd, "src/api"))) {
       architectureNotes.push("Backend API endpoints and network client logic are centralized in `src/api`.");
     }
-    if (existsSync19(join11(this.cwd, "src/components"))) {
+    if (existsSync20(join12(this.cwd, "src/components"))) {
       architectureNotes.push("Reusable UI presentation components live in `src/components/`.");
     }
-    if (existsSync19(join11(this.cwd, "src/types.ts")) || existsSync19(join11(this.cwd, "src/types"))) {
+    if (existsSync20(join12(this.cwd, "src/types.ts")) || existsSync20(join12(this.cwd, "src/types"))) {
       architectureNotes.push("Shared TypeScript data models and interfaces are defined in `src/types`.");
     }
-    if (existsSync19(join11(this.cwd, ".env.example"))) {
+    if (existsSync20(join12(this.cwd, ".env.example"))) {
       architectureNotes.push("Environment configuration template is in `.env.example`.");
     }
     if (commands.typecheck || commands.lint || commands.test) {
@@ -8351,7 +8559,7 @@ class ProjectAnalyzer {
     let hasExistingInstructions = false;
     let existingInstructionFile;
     for (const f of instructionFiles) {
-      if (existsSync19(join11(this.cwd, f))) {
+      if (existsSync20(join12(this.cwd, f))) {
         hasExistingInstructions = true;
         existingInstructionFile = f;
         break;
@@ -8432,8 +8640,8 @@ class ProjectAnalyzer {
   extractReadmeMetadata() {
     const readmeFiles = ["README.md", "readme.md", "README.MD"];
     for (const file of readmeFiles) {
-      const fullPath = join11(this.cwd, file);
-      if (existsSync19(fullPath)) {
+      const fullPath = join12(this.cwd, file);
+      if (existsSync20(fullPath)) {
         try {
           const content = readFileSync13(fullPath, "utf8");
           const lines = content.split(`
@@ -8458,8 +8666,8 @@ class ProjectAnalyzer {
     return {};
   }
   detectProjectName() {
-    const pkgPath = join11(this.cwd, "package.json");
-    if (existsSync19(pkgPath)) {
+    const pkgPath = join12(this.cwd, "package.json");
+    if (existsSync20(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync13(pkgPath, "utf8"));
         if (pkg.name && pkg.name !== "frontend" && pkg.name !== "backend" && pkg.name !== "app") {
@@ -8467,16 +8675,16 @@ class ProjectAnalyzer {
         }
       } catch {}
     }
-    const cargoPath = join11(this.cwd, "Cargo.toml");
-    if (existsSync19(cargoPath)) {
+    const cargoPath = join12(this.cwd, "Cargo.toml");
+    if (existsSync20(cargoPath)) {
       try {
         const match = readFileSync13(cargoPath, "utf8").match(/name\s*=\s*"([^"]+)"/);
         if (match?.[1])
           return match[1];
       } catch {}
     }
-    const goModPath = join11(this.cwd, "go.mod");
-    if (existsSync19(goModPath)) {
+    const goModPath = join12(this.cwd, "go.mod");
+    if (existsSync20(goModPath)) {
       try {
         const match = readFileSync13(goModPath, "utf8").match(/module\s+([^\s]+)/);
         if (match?.[1])
@@ -8487,53 +8695,53 @@ class ProjectAnalyzer {
   }
   detectLanguages() {
     const langs = new Set;
-    if (existsSync19(join11(this.cwd, "tsconfig.json")) || this.hasFileWithExtension(".ts", ".tsx")) {
+    if (existsSync20(join12(this.cwd, "tsconfig.json")) || this.hasFileWithExtension(".ts", ".tsx")) {
       langs.add("TypeScript");
     }
-    if (existsSync19(join11(this.cwd, "package.json")) || this.hasFileWithExtension(".js", ".jsx", ".mjs")) {
+    if (existsSync20(join12(this.cwd, "package.json")) || this.hasFileWithExtension(".js", ".jsx", ".mjs")) {
       langs.add("JavaScript");
     }
-    if (existsSync19(join11(this.cwd, "Cargo.toml")) || this.hasFileWithExtension(".rs")) {
+    if (existsSync20(join12(this.cwd, "Cargo.toml")) || this.hasFileWithExtension(".rs")) {
       langs.add("Rust");
     }
-    if (existsSync19(join11(this.cwd, "go.mod")) || this.hasFileWithExtension(".go")) {
+    if (existsSync20(join12(this.cwd, "go.mod")) || this.hasFileWithExtension(".go")) {
       langs.add("Go");
     }
-    if (existsSync19(join11(this.cwd, "pyproject.toml")) || existsSync19(join11(this.cwd, "requirements.txt")) || this.hasFileWithExtension(".py")) {
+    if (existsSync20(join12(this.cwd, "pyproject.toml")) || existsSync20(join12(this.cwd, "requirements.txt")) || this.hasFileWithExtension(".py")) {
       langs.add("Python");
     }
-    if (existsSync19(join11(this.cwd, "pom.xml")) || existsSync19(join11(this.cwd, "build.gradle")) || this.hasFileWithExtension(".java")) {
+    if (existsSync20(join12(this.cwd, "pom.xml")) || existsSync20(join12(this.cwd, "build.gradle")) || this.hasFileWithExtension(".java")) {
       langs.add("Java");
     }
-    if (existsSync19(join11(this.cwd, "CMakeLists.txt")) || this.hasFileWithExtension(".cpp", ".c", ".h", ".hpp")) {
+    if (existsSync20(join12(this.cwd, "CMakeLists.txt")) || this.hasFileWithExtension(".cpp", ".c", ".h", ".hpp")) {
       langs.add("C/C++");
     }
     return Array.from(langs);
   }
   detectPackageManager() {
-    if (existsSync19(join11(this.cwd, "bun.lockb")) || existsSync19(join11(this.cwd, "bun.lock")))
+    if (existsSync20(join12(this.cwd, "bun.lockb")) || existsSync20(join12(this.cwd, "bun.lock")))
       return "bun";
-    if (existsSync19(join11(this.cwd, "pnpm-lock.yaml")))
+    if (existsSync20(join12(this.cwd, "pnpm-lock.yaml")))
       return "pnpm";
-    if (existsSync19(join11(this.cwd, "yarn.lock")))
+    if (existsSync20(join12(this.cwd, "yarn.lock")))
       return "yarn";
-    if (existsSync19(join11(this.cwd, "package-lock.json")))
+    if (existsSync20(join12(this.cwd, "package-lock.json")))
       return "npm";
-    if (existsSync19(join11(this.cwd, "Cargo.lock")) || existsSync19(join11(this.cwd, "Cargo.toml")))
+    if (existsSync20(join12(this.cwd, "Cargo.lock")) || existsSync20(join12(this.cwd, "Cargo.toml")))
       return "cargo";
-    if (existsSync19(join11(this.cwd, "uv.lock")))
+    if (existsSync20(join12(this.cwd, "uv.lock")))
       return "uv";
-    if (existsSync19(join11(this.cwd, "poetry.lock")))
+    if (existsSync20(join12(this.cwd, "poetry.lock")))
       return "poetry";
-    if (existsSync19(join11(this.cwd, "go.sum")) || existsSync19(join11(this.cwd, "go.mod")))
+    if (existsSync20(join12(this.cwd, "go.sum")) || existsSync20(join12(this.cwd, "go.mod")))
       return "go";
-    if (existsSync19(join11(this.cwd, "package.json")))
+    if (existsSync20(join12(this.cwd, "package.json")))
       return "npm";
     return;
   }
   hasFileWithExtension(...exts) {
     try {
-      const entries = readdirSync8(this.cwd);
+      const entries = readdirSync9(this.cwd);
       return entries.some((e) => exts.some((ext) => e.endsWith(ext)));
     } catch {
       return false;
@@ -8541,16 +8749,16 @@ class ProjectAnalyzer {
   }
 }
 // src/init/init-command.ts
-import { existsSync as existsSync20, writeFileSync as writeFileSync7 } from "fs";
-import { join as join12 } from "path";
+import { existsSync as existsSync21, writeFileSync as writeFileSync7 } from "fs";
+import { join as join13 } from "path";
 function runProjectInit(options = {}) {
   const cwd = options.cwd || process.cwd();
   const filename = options.filename || "AGENTS.md";
-  const targetPath = join12(cwd, filename);
+  const targetPath = join13(cwd, filename);
   const analyzer = new ProjectAnalyzer(cwd);
   const analysis = analyzer.analyze();
   const content = analyzer.generateAgentsMarkdown(analysis);
-  const alreadyExists = existsSync20(targetPath);
+  const alreadyExists = existsSync21(targetPath);
   writeFileSync7(targetPath, content, "utf8");
   return {
     success: true,
@@ -9324,7 +9532,7 @@ function printSessionStats(ctx) {
   const turns = ctx.repl?.turnCount ?? 0;
   const history = ctx.session.getHistory();
   const historyTokens = estimateTotalTokens(history);
-  const maxTokens = 128000;
+  const maxTokens = DEFAULT_MAX_CONTEXT_TOKENS;
   const contextPct = Math.round(historyTokens / maxTokens * 100);
   const colorFn = contextPct < 50 ? style.green : contextPct < 80 ? style.yellow : style.red;
   const agents = ctx.spawner?.listAgents() || [];
@@ -10015,9 +10223,9 @@ class MarkdownHighlighter {
 }
 
 // src/cli/update-checker.ts
-import { existsSync as existsSync21, mkdirSync as mkdirSync11, readFileSync as readFileSync14, writeFileSync as writeFileSync8 } from "fs";
+import { existsSync as existsSync22, mkdirSync as mkdirSync12, readFileSync as readFileSync14, writeFileSync as writeFileSync8 } from "fs";
 import { homedir as homedir5 } from "os";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 var CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
 function parseSemver(v) {
   const clean = v.replace(/^v/, "").trim();
@@ -10038,8 +10246,8 @@ function isNewerVersion(current, remote) {
   return remPatch > curPatch;
 }
 function getUpdateCachePath() {
-  const baseDir = process.env.PIKAA_HOME || process.env.GROUPY_HOME || join13(homedir5(), ".pikaa");
-  return join13(baseDir, "update-cache.json");
+  const baseDir = process.env.PIKAA_HOME || process.env.GROUPY_HOME || join14(homedir5(), ".pikaa");
+  return join14(baseDir, "update-cache.json");
 }
 async function fetchLatestNpmVersion(packageName, timeoutMs = 1500) {
   const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`;
@@ -10072,7 +10280,7 @@ async function checkForUpdates(options = {}) {
   const cachePath = options.cachePath || getUpdateCachePath();
   const now = Date.now();
   let cached = null;
-  if (!options.force && existsSync21(cachePath)) {
+  if (!options.force && existsSync22(cachePath)) {
     try {
       const raw = JSON.parse(readFileSync14(cachePath, "utf8"));
       if (raw && typeof raw.lastChecked === "number" && typeof raw.latestVersion === "string") {
@@ -10102,9 +10310,9 @@ async function checkForUpdates(options = {}) {
     return null;
   }
   try {
-    const parentDir = join13(cachePath, "..");
-    if (!existsSync21(parentDir)) {
-      mkdirSync11(parentDir, { recursive: true });
+    const parentDir = join14(cachePath, "..");
+    if (!existsSync22(parentDir)) {
+      mkdirSync12(parentDir, { recursive: true });
     }
     const cacheData = {
       lastChecked: now,
@@ -10268,6 +10476,7 @@ class CliRepl {
             inputTokens: msg.inputTokens,
             outputTokens: msg.outputTokens || (this.turnCharsOut > 0 ? Math.round(this.turnCharsOut / 3.8) : undefined),
             totalTokens: msg.totalTokens,
+            cachedTokens: msg.cachedTokens,
             contextTokens: msg.contextTokens,
             maxContextTokens: msg.maxContextTokens,
             sessionUptimeMs,
@@ -10526,7 +10735,7 @@ async function main() {
     resolve21(cwd, "mcp_config.json")
   ].filter(Boolean);
   for (const cfg of candidateConfigs) {
-    if (existsSync22(cfg)) {
+    if (existsSync23(cfg)) {
       try {
         await mcpManager.loadConfigFile(cfg);
         mcpManager.registerToolsIntoRouter(tools4);