@causyne/agent 1.10.12 → 1.10.13

package/LICENSE

@@ -9,7 +9,7 @@ Parameters
 
 Licensor:             Ikbal Fadilah
 
-Licensed Work:        Causyne Agent 1.10.1
+Licensed Work:        Causyne Agent 1.10.13
                       The Licensed Work is (c) 2026 Ikbal Fadilah.
 
 Additional Use Grant: You may make use of the Licensed Work, provided that

package/docs/ARCHITECTURE.md

@@ -36,7 +36,7 @@ are application policies and require adversarial review.
 | Models | `providers/`, `modelCatalogue.js` |
 | Context and memory | `memory.js`, `memoryManager.js`, `contextManager.js`, `cortex/` |
 | Recovery | `checkpoints.js`, `gitSnapshot.js`, `sessionStore.js` |
-| Extensions | `mcpClient.js`, `skillsManager.js`, `toolPacks.js`, user skills and Tool Forge |
+| Extensions | `mcp/`, `plugins/`, `hooks.js`, `skillsManager.js`, `toolPacks.js` |
 | Readable interpreter source | `src/tool-scripts/` |
 
 The current implementation remains JavaScript/ESM on Node.js 24+. The accepted
@@ -44,6 +44,51 @@ language direction is incremental strict TypeScript. Runtime validation is
 still needed at model, filesystem, subprocess and extension boundaries.
 Rust is a possible narrow native worker later; no Rust rewrite is underway.
 
+## Tool and extension boundaries
+
+Tool schemas are assembled once from native tools, explicitly enabled plugins,
+and granted MCP servers. Denied tools are removed before the model sees them,
+native names win collisions, and large capability groups remain deferred until
+the task shape or `tool_search` makes them relevant.
+
+Local plugins use a static `plugin.json` manifest. Creating a plugin leaves it
+disabled. Enabling it pins a digest of every file the plugin process may read;
+any later manifest, source, helper or asset change revokes trust. Discovery
+validates static manifests and hashes bytes without importing JavaScript, so code cannot run
+during pre-trust initialization. A plugin tool runs in a separate Node process
+with the permission model enabled and only its declared workspace, network, or
+subprocess capabilities. Plugin calls still pass through Causyne's sandbox and
+approval gates.
+
+Hooks are user-owned argv arrays stored in the local Causyne configuration.
+They never pass through a shell and project repositories are not searched for
+startup hooks. `PreToolUse` runs after the built-in sandbox and before an
+approval prompt; exit code 2 denies, and any other failure fails closed.
+`PostToolUse` can annotate a result or reject it without rewriting history.
+
+Host execution remains the default because Causyne must work in the directory
+the user selected. Optional container isolation can be added as an execution
+profile later, but it must remain explicit: mounting a workspace into Docker is
+a different trust boundary and cannot silently replace native desktop access.
+
+## Plan cache and context pressure
+
+Completed multi-step runs teach argument-free plan templates. Lookup tries an
+indexed exact signature first, then bounded lexical similarity only for a task
+shape with enough confidence. Latency, hit type and recent hit rate are recorded;
+lookup temporarily cools down when a populated cache repeatedly misses while
+new successful plans may continue warming it. `/plans import` accepts sanitized
+offline samples for known workloads, and `/plans` exposes the measurements.
+`npm run benchmark:plan-cache` measures exact lookup, fuzzy lookup, misses and
+prewarming at bounded cache sizes in an isolated temporary state directory. It
+is a synthetic cache microbenchmark, not evidence for model accuracy, token
+cost, or end-to-end latency claims from the research paper.
+
+Context uses per-tool result budgets, oversized-result snipping, decay, a bounded
+sliding window, and structural summaries. Full tool output is spilled before it
+is shortened. Material compaction is recorded in the audit log, and summary
+collapse emits a quiet terminal notice so context loss is visible.
+
 ## Removed boundaries
 
 No active pairing, relay, WebRTC/P2P, mobile command surface, background daemon

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causyne/agent",
-  "version": "1.10.12",
+  "version": "1.10.13",
   "description": "Agentic AI for software, tools, and computer workflows",
   "main": "bin/causyne.js",
   "type": "module",
@@ -24,6 +24,7 @@
     "start": "node ./bin/causyne.js",
     "test": "node --test --import ./tests/helpers/isolateState.js \"tests/**/*.test.js\"",
     "build": "node scripts/compile_skills.js",
+    "benchmark:plan-cache": "node src/benchmarks/planCache.js",
     "check:release": "node scripts/check_release.js",
     "check:public": "npm run check:release && node scripts/check_public_release.js",
     "prepublishOnly": "npm run check:public && npm test && npm run typecheck:strict",

package/src/agentLoop.js

@@ -7,6 +7,7 @@ import { TaskBuffer } from './taskBuffer.js';
 import { TOOL_DEFINITIONS, getDynamicTools, resolveTool, canonicalToolName } from './tools/registry.js';
 import { Sandbox } from './sandbox.js';
 import { auditLog } from './auditLog.js';
+import { hasMatchingHook, runConfiguredHooks } from './hooks.js';
 import { loadConfig } from './config.js';
 import { isDevEmulator } from './devMode.js';
 import { TokenTracker } from './tokenTracker.js';
@@ -14,7 +15,7 @@ import { TokenTracker } from './tokenTracker.js';
 import { getMemoryContextString } from './memory.js';
 import { MemoryManager } from './memoryManager.js';
 import { cortexDb } from './cortex/vectorDb.js';
-import { condenseAndSave } from './cortex/autoCondenser.js';
+import { buildStructuralSummary, condenseAndSave } from './cortex/autoCondenser.js';
 import { analyzeTask, buildTaskBrief, packsFromShape } from './taskShape.js';
 import { lookupPlan, recordPlan, recordMiss, renderPlanHint, toStep } from './planCache.js';
 import { routedConfig } from './modelRouter.js';
@@ -497,18 +498,9 @@ export class AgentLoop {
     // once per task rather than once per step.
     let planHint = '';
     try {
-      const match = lookupPlan({
-        prompt: this.currentTaskPrompt || this.userPrompt,
-        archetype: this.taskShape ? this.taskShape.archetype : ''
-      });
-      if (match) {
-        planHint = renderPlanHint(match);
-        this._offeredPlanId = match.template.id;
-        this._planSimilarity = match.similarity;
-        this.debugLog(`plan cache hit ${(match.similarity * 100).toFixed(0)}% (${match.template.steps.length} steps)`);
-      }
+      planHint = renderPlanHint(this._planMatch);
     } catch (e) {
-      this.debugLog(`plan cache lookup skipped: ${e.message}`);
+      this.debugLog(`plan cache hint skipped: ${e.message}`);
     }
 
     return { lessonsLearned, designContext, antiRepeatDirective, universalSkillsContext, planHint };
@@ -601,6 +593,10 @@ export class AgentLoop {
     for (const toolCall of toolCalls) {
       const functionName = canonicalToolName(toolCall.function.name);
       if (!AgentLoop.READ_ONLY_TOOLS.has(functionName)) continue;
+      // Prefetch begins before the serial dispatch path. If this tool has a
+      // PreToolUse hook, running it here would create a temporal pre-trust
+      // window where the read happens before the hook can deny it.
+      if (hasMatchingHook(this.config.hooks, 'PreToolUse', functionName)) continue;
 
       let args;
       try {
@@ -800,6 +796,7 @@ export class AgentLoop {
     this._planSteps = [];
     this._offeredPlanId = null;
     this._planSimilarity = 0;
+    this._planMatch = null;
     this._lessonSimilarity = 0;
     this._lastToolResult = null;
     this._paradigmShiftPending = false;
@@ -816,6 +813,36 @@ export class AgentLoop {
         this.unlockPack(pack);
       }
 
+      // Reuse a known route before the first model call. Exact keyword-set
+      // matches are always eligible; fuzzy reuse requires at least medium task
+      // classification confidence because APC's threshold study shows that
+      // aggressive fuzzy hits trade accuracy for speed.
+      try {
+        this._planMatch = lookupPlan({
+          prompt: this.userPrompt,
+          archetype: this.taskShape ? this.taskShape.archetype : '',
+          allowFuzzy: this.taskShape?.confidence !== 'low'
+        });
+        if (this._planMatch) {
+          this._offeredPlanId = this._planMatch.template.id;
+          this._planSimilarity = this._planMatch.similarity;
+          for (const step of this._planMatch.template.steps || []) {
+            if (!step.ok || !resolveTool(step.tool)) continue;
+            this.unlockedTools.add(step.tool);
+            const pack = packForTool(step.tool);
+            if (pack) this.unlockPack(pack);
+          }
+          this.debugLog(
+            `plan cache ${this._planMatch.matchType || 'fuzzy'} hit `
+              + `${(this._planMatch.similarity * 100).toFixed(0)}% `
+              + `(${this._planMatch.template.steps.length} steps, `
+              + `${this._planMatch.telemetry?.lookupMs?.toFixed(2) || '0.00'} ms)`
+          );
+        }
+      } catch (e) {
+        this.debugLog(`plan cache lookup skipped: ${e.message}`);
+      }
+
       this.debugLog(`task shape: ${this.taskShape.archetype} (${this.taskShape.confidence} confidence)`);
     }
 
@@ -972,6 +999,13 @@ export class AgentLoop {
         });
         if (compaction.totalReclaimed > 0) {
           this.debugLog(`progressive compaction reclaimed ${(compaction.totalReclaimed / 1024).toFixed(1)} KB [${compaction.stagesFired.join(', ')}]`);
+          auditLog.log({
+            event: 'context_compaction', taskId: this.taskId,
+            kind: 'progressive', stages: compaction.stagesFired,
+            reclaimedChars: compaction.totalReclaimed,
+            finalChars: compaction.finalChars,
+            limitChars: MAX_CHAR_POOL
+          });
         }
 
         const { window: slidingWindow, splitIndex } = buildWindow(this.messages, MAX_CHAR_POOL);
@@ -996,9 +1030,17 @@ export class AgentLoop {
         if (splitIndex >= 1) {
           const dropped = this.messages.slice(1, splitIndex + 1);
           if (dropped.length > 0) {
-            const removed = compactInPlace(this.messages, splitIndex, describeDroppedMessages(dropped));
+            const compactSummary = buildStructuralSummary(dropped) || describeDroppedMessages(dropped);
+            const removed = compactInPlace(this.messages, splitIndex, compactSummary);
             this._lastCompactionIndex = null;
             this.debugLog(`compacted ${removed} messages out of the live context`);
+            auditLog.log({
+              event: 'context_compaction', taskId: this.taskId,
+              kind: 'summary', removedMessages: removed,
+              retainedSummaryChars: compactSummary.length,
+              limitChars: MAX_CHAR_POOL
+            });
+            this.notice(`Context compacted: ${removed} earlier messages condensed into a reviewable summary.`);
 
             // V5 Cortex tiered condensation. Tier 1 (structural, free) always
             // runs so the Digital Brain keeps learning on every provider. Tier 2
@@ -1029,6 +1071,8 @@ export class AgentLoop {
           unlockedTools: this.unlockedTools,
           unlockOrder: this.unlockOrder,
           grantAllTools: this.config.grantAllTools === true,
+          allowedTools: this.sandbox.allowedTools,
+          deniedTools: this.config.deniedTools,
           residentOnly
         });
         // A delegated subagent runs with a declared toolScope. Enforcing it
@@ -1699,58 +1743,10 @@ export class AgentLoop {
           
           this.consecutiveBlockedActions = 0; // Reset counter on allowed action
 
-          // Approval flow for dangerous actions (Mode A/B) or ALWAYS for heavy AI downloads
-          // The schema name is manage_local_dependencies. Comparing against the
-          // old alias meant this consent gate never fired and multi-GB model
-          // downloads ran unannounced.
-          const isHeavyAiDownload = functionName === 'manage_local_dependencies' &&
-            ['pipInst', 'fetchBin', 'fetchMod'].includes(args.action);
-          // A standing approval from "Allow always" lifts the gate for this
-          // tool until the process restarts. It is checked HERE rather than
-          
-          // asking and then auto-answering would still interrupt the user,
-          // which is the entire thing they were trying to stop.
-          //
-          // Nothing else is bypassed: the sandbox has already run above, so a
-          // FORBIDDEN command is still refused and a path outside the workspace
-          // is still blocked. This waives the QUESTION, not the guard.
-          const standingApproval = isAlwaysAllowed(functionName);
-          if (standingApproval) {
-            auditLog.log({
-              event: 'approval_auto_granted', taskId: this.taskId,
-              tool: functionName, risk: validation.risk, reason: 'allow_always'
-            });
-          }
-
-          if (!standingApproval && (
-              validation.risk === 'extreme' ||
-              isHeavyAiDownload ||
-              (this.config.autonomyMode !== 'C' && validation.risk === 'dangerous') ||
-              this.config.autonomyMode === 'A')) {
-            
-            // Wait for local approval
-            this.emitEvent({ type: 'approval_request', toolCallId: toolCall.id, tool: functionName, args, risk: validation.risk });
-
-            const approved = await this.waitForApproval(toolCall.id);
-            
-            if (!approved) {
-              this.messages.push({
-                role: 'tool',
-                tool_call_id: toolCall.id,
-                name: functionName,
-                content: JSON.stringify({ success: false, error: 'User denied this action' })
-              });
-              continue;
-            }
-          }
-
-          // Execute
+          // Resolve and validate before asking the user for approval. Unknown or
+          // malformed calls should self-correct without creating approval fatigue.
           const tool = resolveTool(functionName);
-
-          // GUARD: Prevent crash if LLM hallucinates a non-existent tool name
           if (!tool || typeof tool.execute !== 'function') {
-            // Only advertise what is currently in context. Listing all 69 names
-            // here re-bloated the very context progressive disclosure protects.
             this.messages.push({
               role: 'tool',
               tool_call_id: toolCall.id,
@@ -1763,10 +1759,6 @@ export class AgentLoop {
             continue;
           }
 
-          // AUTO-UNLOCK RECOVERY: the model named a real tool whose pack is not
-          // loaded yet (it remembered it from an earlier task, or guessed well).
-          // Unlock the pack and run it rather than dead-ending — capability is
-          // deferred, never removed.
           if (!isCoreTool(functionName) && !this.unlockedTools.has(functionName)) {
             const pack = packForTool(functionName);
             if (this.unlockPack(pack)) {
@@ -1775,26 +1767,29 @@ export class AgentLoop {
             this.unlockedTools.add(functionName);
           }
 
-          // V5: Tool Call Argument Validation Layer
           const validationErrors = this.validateToolArgs(functionName, args);
           if (validationErrors) {
             this.messages.push({
               role: 'tool',
               tool_call_id: toolCall.id,
               name: functionName,
-              content: JSON.stringify({ 
-                success: false, 
-                error: `Invalid arguments: ${validationErrors}. Please fix and retry.` 
+              content: JSON.stringify({
+                success: false,
+                error: `Invalid arguments: ${validationErrors}. Please fix and retry.`
               })
             });
             continue;
           }
 
-          // Stage 3 seam: PreToolUse hook. A no-op that always allows today; when
-          // hooks are configured it can deny a call before it runs, returned as an
-          // is_error tool result so the model self-corrects (never thrown).
+          // A policy hook runs after the built-in sandbox but before any user
+          // approval prompt, so a deterministic denial never asks the user to
+          // approve work that will be rejected anyway.
           const preHook = await this.runPreToolUse(functionName, args, toolCall.id);
           if (preHook && preHook.denied) {
+            auditLog.log({
+              event: 'hook_denied', taskId: this.taskId, hookEvent: 'PreToolUse',
+              tool: functionName, reason: preHook.reason || 'hook denied'
+            });
             this.messages.push({
               role: 'tool',
               tool_call_id: toolCall.id,
@@ -1808,6 +1803,51 @@ export class AgentLoop {
             continue;
           }
 
+          // Approval flow for dangerous actions (Mode A/B) or ALWAYS for heavy AI downloads
+          // The schema name is manage_local_dependencies. Comparing against the
+          // old alias meant this consent gate never fired and multi-GB model
+          // downloads ran unannounced.
+          const isHeavyAiDownload = functionName === 'manage_local_dependencies' &&
+            ['pipInst', 'fetchBin', 'fetchMod'].includes(args.action);
+          // A standing approval from "Allow always" lifts the gate for this
+          // tool until the process restarts. It is checked HERE rather than
+
+          // asking and then auto-answering would still interrupt the user,
+          // which is the entire thing they were trying to stop.
+          //
+          // Nothing else is bypassed: the sandbox has already run above, so a
+          // FORBIDDEN command is still refused and a path outside the workspace
+          // is still blocked. This waives the QUESTION, not the guard.
+          const standingApproval = isAlwaysAllowed(functionName);
+          if (standingApproval) {
+            auditLog.log({
+              event: 'approval_auto_granted', taskId: this.taskId,
+              tool: functionName, risk: validation.risk, reason: 'allow_always'
+            });
+          }
+
+          if (!standingApproval && (
+              validation.risk === 'extreme' ||
+              isHeavyAiDownload ||
+              (this.config.autonomyMode !== 'C' && validation.risk === 'dangerous') ||
+              this.config.autonomyMode === 'A')) {
+
+            // Wait for local approval
+            this.emitEvent({ type: 'approval_request', toolCallId: toolCall.id, tool: functionName, args, risk: validation.risk });
+
+            const approved = await this.waitForApproval(toolCall.id);
+
+            if (!approved) {
+              this.messages.push({
+                role: 'tool',
+                tool_call_id: toolCall.id,
+                name: functionName,
+                content: JSON.stringify({ success: false, error: 'User denied this action' })
+              });
+              continue;
+            }
+          }
+
           // P2: snapshot the files this call is about to change, before it runs.
           // Only the mutating fs tools match; everything else returns immediately.
           // Fail-open by contract — this can never block or fail a tool call.
@@ -2393,26 +2433,32 @@ export class AgentLoop {
     return hints[errorType] || hints['unknown_error'];
   }
 
-  // V5: Validate tool call arguments before execution
-  /**
-   * PreToolUse / PostToolUse seams (Stage 3 fills these in).
-   *
-   * Today they are no-ops that always allow, so the dispatch behaviour is exactly
-   * what it was. When `.causyne/settings.json` gains a `hooks` block (Stage 3),
-   * these run the user's shell hooks with the exit-code protocol
-   * (0 allow / 2 deny / else warn) and return { denied, messages }. The loop
-   * already branches on `denied`, so Stage 3 is a fill-in here, not another edit
-   * to the dispatch path. See src/tools/toolDispatch.js for the discipline these
-   * plug into.
-   */
-  async runPreToolUse(_toolName, _args, _toolCallId) {
-    return { denied: false, messages: [] };
+  async runPreToolUse(toolName, args, toolCallId) {
+    return runConfiguredHooks({
+      hooks: this.config?.hooks,
+      event: 'PreToolUse',
+      toolName,
+      args,
+      taskId: this.taskId,
+      toolCallId,
+      workspacePaths: this.sandbox?.workspacePaths
+    });
   }
 
-  async runPostToolUse(_toolName, _args, _result) {
-    return { denied: false, messages: [] };
+  async runPostToolUse(toolName, args, result) {
+    return runConfiguredHooks({
+      hooks: this.config?.hooks,
+      event: 'PostToolUse',
+      toolName,
+      args,
+      result,
+      taskId: this.taskId,
+      workspacePaths: this.sandbox?.workspacePaths
+    });
   }
 
+  // V5: Validate tool call arguments before execution
+
   validateToolArgs(toolName, args) {
     // Check for common LLM mistakes
     

package/src/benchmarks/planCache.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+// Never inspect or mutate a user's real plan cache. utils/paths.js resolves the
+// state root at module initialization, so set it before importing planCache.js.
+const benchmarkHome = fs.mkdtempSync(path.join(os.tmpdir(), 'causyne-plan-cache-bench-'));
+process.env.CAUSYNE_HOME = benchmarkHome;
+
+const {
+  forgetPlans,
+  lookupPlan,
+  planStats,
+  prewarmPlans
+} = await import('../planCache.js');
+
+const sizes = [1, 10, 20, 50, 100, 200];
+const hitIterations = 500;
+// Production deliberately cools down after a sustained low hit rate. Staying
+// below that threshold measures a real miss scan instead of the cheap bypass.
+const missIterations = 16;
+
+function sample(index) {
+  const key = `taskkey${String(index).padStart(3, '0')}`;
+  return {
+    prompt: `benchmark workflow ${key} inspect validate artifact`,
+    archetype: 'benchmark',
+    steps: [
+      { tool: 'fs_search', action: 'inspect', ok: true },
+      { tool: 'sys_run', action: 'validate', ok: true }
+    ]
+  };
+}
+
+function percentile(values, fraction) {
+  const sorted = [...values].sort((left, right) => left - right);
+  if (sorted.length === 0) return 0;
+  return sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * fraction))];
+}
+
+function measure(iterations, operation) {
+  const values = [];
+  for (let index = 0; index < iterations; index++) {
+    const startedAt = performance.now();
+    operation(index);
+    values.push(performance.now() - startedAt);
+  }
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return {
+    iterations,
+    averageMs: total / values.length,
+    medianMs: percentile(values, 0.5),
+    p95Ms: percentile(values, 0.95),
+    maxMs: Math.max(...values)
+  };
+}
+
+function fixed(value) {
+  return Number(value.toFixed(4));
+}
+
+function compactMeasurement(measurement) {
+  return {
+    iterations: measurement.iterations,
+    averageMs: fixed(measurement.averageMs),
+    medianMs: fixed(measurement.medianMs),
+    p95Ms: fixed(measurement.p95Ms),
+    maxMs: fixed(measurement.maxMs)
+  };
+}
+
+function prewarmInBatches(seeds) {
+  const combined = { accepted: 0, rejected: 0, errors: [] };
+  for (let offset = 0; offset < seeds.length; offset += 100) {
+    const batch = prewarmPlans(seeds.slice(offset, offset + 100));
+    combined.accepted += batch.accepted;
+    combined.rejected += batch.rejected;
+    combined.errors.push(...batch.errors);
+  }
+  return combined;
+}
+
+const results = [];
+
+try {
+  for (const size of sizes) {
+    forgetPlans();
+    const seeds = Array.from({ length: size }, (_, index) => sample(index));
+    const prewarmStartedAt = performance.now();
+    const prewarm = prewarmInBatches(seeds);
+    const prewarmMs = performance.now() - prewarmStartedAt;
+    const target = sample(Math.floor(size / 2));
+
+    // Warm filesystem and in-memory index before measuring lookup paths.
+    lookupPlan({ prompt: target.prompt, archetype: target.archetype, allowFuzzy: true });
+
+    const exact = measure(hitIterations, () => {
+      const match = lookupPlan({
+        prompt: target.prompt,
+        archetype: target.archetype,
+        allowFuzzy: true
+      });
+      if (!match || match.matchType !== 'exact') {
+        throw new Error(`Exact lookup failed at cache size ${size}`);
+      }
+    });
+
+    const fuzzyPrompt = target.prompt.replace('validate artifact', 'validate repaired artifact');
+    const fuzzy = measure(hitIterations, () => {
+      const match = lookupPlan({
+        prompt: fuzzyPrompt,
+        archetype: target.archetype,
+        allowFuzzy: true
+      });
+      if (!match || match.matchType !== 'fuzzy') {
+        throw new Error(`Fuzzy lookup failed at cache size ${size}`);
+      }
+    });
+
+    const miss = measure(missIterations, (index) => {
+      const match = lookupPlan({
+        prompt: `unrelated cold miss ${size} ${index} quantum orchard telescope`,
+        archetype: 'different-archetype',
+        allowFuzzy: true
+      });
+      if (match) throw new Error(`Unexpected cache hit at cache size ${size}`);
+    });
+
+    results.push({
+      cacheSize: size,
+      acceptedSeeds: prewarm.accepted,
+      prewarmMs: fixed(prewarmMs),
+      exact: compactMeasurement(exact),
+      fuzzy: compactMeasurement(fuzzy),
+      miss: compactMeasurement(miss),
+      telemetry: planStats()
+    });
+  }
+
+  const report = {
+    benchmark: 'Causyne Agent plan cache lookup',
+    generatedAt: new Date().toISOString(),
+    runtime: { node: process.version, platform: process.platform, arch: process.arch },
+    method: {
+      cacheSizes: sizes,
+      hitIterations,
+      missIterations,
+      note: 'Synthetic microbenchmark. It measures Causyne cache operations only; it does not reproduce paper task accuracy, model cost, or end-to-end agent latency.'
+    },
+    results
+  };
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} finally {
+  fs.rmSync(benchmarkHome, { recursive: true, force: true });
+}

package/src/commands.js

@@ -425,6 +425,89 @@ export const COMMANDS = [
     }
   },
 
+  {
+    name: 'plans',
+    scope: 'local',
+    usage: '/plans [import <json-file> | forget]',
+    description: 'Inspect, pre-warm, or clear reusable task plans',
+    dialogTitle: 'Plan cache',
+    run: async (args = []) => {
+      const cache = await import('./planCache.js');
+      const verb = String(args[0] || '').toLowerCase();
+
+      if (verb === 'forget') {
+        const removed = cache.forgetPlans();
+        return ok(`Forgot ${removed} cached plan${removed === 1 ? '' : 's'}.`);
+      }
+
+      if (verb === 'import') {
+        const requested = args.slice(1).join(' ').trim();
+        if (!requested) return fail('Usage: /plans import <json-file>');
+        const file = path.resolve(requested.replace(/^~(?=\/)/, os.homedir()));
+        try {
+          const stat = fs.statSync(file);
+          if (!stat.isFile() || stat.size > 1024 * 1024) {
+            return fail('Plan seed must be one JSON file no larger than 1 MB.');
+          }
+          const outcome = cache.prewarmPlans(JSON.parse(fs.readFileSync(file, 'utf8')));
+          const detail = outcome.errors.length > 0 ? `\n${outcome.errors.join('\n')}` : '';
+          return outcome.accepted > 0
+            ? ok(`Imported ${outcome.accepted} plan${outcome.accepted === 1 ? '' : 's'}; rejected ${outcome.rejected}.${detail}`)
+            : fail(`No plans were imported.${detail}`);
+        } catch (error) {
+          return fail(`Could not import plan seeds: ${error.message}`);
+        }
+      }
+
+      const stats = cache.planStats();
+      return ok([
+        `${stats.count} cached plan${stats.count === 1 ? '' : 's'}`,
+        `Hits: ${stats.hits}/${stats.lookups} (${(stats.hitRate * 100).toFixed(1)}%) — exact ${stats.exactHits}, fuzzy ${stats.fuzzyHits}`,
+        `Average lookup: ${stats.averageLookupMs.toFixed(3)} ms; max ${stats.maxLookupMs.toFixed(3)} ms`,
+        stats.disabled
+          ? `Lookup cooling down until ${new Date(stats.disabledUntil).toISOString()} after persistent misses.`
+          : 'Lookup active.',
+        '',
+        'Pre-warm with /plans import <json-file>. Clear with /plans forget.'
+      ].join('\n'));
+    }
+  },
+
+  {
+    name: 'plugins',
+    scope: 'local',
+    usage: '/plugins [enable <name> | disable <name>]',
+    description: 'Inspect or change trust for local plugins',
+    dialogTitle: 'Plugins',
+    run: async (args = []) => {
+      const manager = await import('./plugins/pluginManager.js');
+      const verb = String(args[0] || '').toLowerCase();
+      const name = String(args[1] || '');
+      if (verb === 'enable') {
+        if (!name) return fail('Usage: /plugins enable <name>');
+        const result = manager.enablePlugin(name);
+        return result.ok
+          ? ok(`Enabled ${name} at manifest digest ${result.digest}. Changes will revoke trust automatically.`)
+          : fail(`Could not enable ${name}: ${result.error}`);
+      }
+      if (verb === 'disable') {
+        if (!name) return fail('Usage: /plugins disable <name>');
+        const result = manager.disablePlugin(name);
+        return result.ok ? ok(`Disabled ${name}.`) : fail(`Could not disable ${name}: ${result.error}`);
+      }
+
+      const rows = manager.listPlugins();
+      if (rows.length === 0) return ok(`No local plugins. Plugin root: ${manager.PLUGIN_ROOT}`);
+      return ok(rows.map((plugin) => {
+        const state = plugin.invalid ? 'invalid' : plugin.modified ? 'modified; trust revoked' : plugin.enabled ? 'enabled' : 'disabled';
+        const capabilities = Array.isArray(plugin.capabilities) && plugin.capabilities.length > 0
+          ? plugin.capabilities.join(', ')
+          : 'none';
+        return `  ${plugin.name} ${plugin.version || ''} — ${state}; capabilities: ${capabilities}`;
+      }).join('\n') + `\n\nPlugin root: ${manager.PLUGIN_ROOT}`);
+    }
+  },
+
   {
     name: 'sessions',
     aliases: ['session'],