@causyne/agent 1.10.17 → 1.10.18

package/docs/ARCHITECTURE.md

@@ -31,7 +31,7 @@ are application policies and require adversarial review.
 | Concern | Source |
 | --- | --- |
 | Invocation and local session | `entrypoint.js`, `cliMode.js`, `tui/` |
-| Orchestration and budgets | `agentLoop.js`, `agentProfiles.ts`, `subagentJournal.ts`, `modelRouter.js`, `tokenTracker.js` |
+| Orchestration and budgets | `agentLoop.js`, `decisionPolicy.ts`, `implementationPlan.ts`, `agentProfiles.ts`, `subagentJournal.ts`, `modelRouter.js`, `tokenTracker.js` |
 | Host execution | `tools/registry.js`, `sandbox.js`, `execSafe.js` |
 | Models | `providers/`, `modelCatalogue.js` |
 | Context and memory | `memory.js`, `memoryManager.js`, `contextManager.js`, `cortex/` |
@@ -49,6 +49,20 @@ Runtime validation is still required at model, filesystem, subprocess and
 extension boundaries. Rust is reserved for a measured, narrow native worker;
 no Rust rewrite is underway.
 
+## Planning and durable decisions
+
+Complex implementation uses `update_plan` to maintain a validated checklist in
+session state. The TUI keeps the current steps visible beside the input surface;
+plans are not written into the user's project. A mutating tool call on a complex
+task is held until the model has created this plan.
+
+`request_decision` handles choices with durable product, architecture, data,
+security, or workflow consequences. It presents two to four concrete options
+and a custom-answer path. This checkpoint is distinct from a tool permission:
+selecting a design never grants filesystem or command access. The checkpoint
+runs in the provider-independent agent loop, so Mode C can remove routine
+approval friction without silently choosing an unresolved architecture.
+
 ## Tool and extension boundaries
 
 Tool schemas are assembled once from native tools, explicitly enabled plugins,
@@ -92,16 +106,19 @@ browser OAuth is not implemented yet; an HTTP 401 is surfaced as
 
 Causyne's web foundation has two layers. Lightweight TypeScript search and
 fetch clients work without a browser runtime. Rendered navigation uses a
-dedicated in-process Camoufox adapter derived from the locally reviewed Camofox
-Browser source. The adapter is deliberately smaller than the reference service:
+dedicated in-process Causyne Browser adapter built from a locally reviewed
+upstream browser engine. Required upstream names and licenses remain in the
+third-party notices. The adapter is deliberately smaller than the reference
+service:
 it does not import an HTTP server, inbound port, cloud deployment layer, VNC,
 telemetry, remote WebSocket control, or OpenClaw integration.
 
-Camoufox and Playwright are exact-pinned optional capability packages installed
-into the user's private Causyne capability directory only after an explicit
-browser capability grant. Causyne does not download a browser binary. Advanced
-rendered browsing requires a separately installed Camoufox bundle selected by
-`CAUSYNE_CAMOFOX_EXECUTABLE` or discovered from a standard system location.
+The browser engine and Playwright are exact-pinned optional capability packages
+installed into the user's private Causyne capability directory only after an
+explicit browser capability grant. Causyne does not download a browser binary. Advanced
+rendered browsing requires a separately installed supported browser runtime
+selected by `CAUSYNE_BROWSER_EXECUTABLE` or discovered from a standard system
+location.
 The main npm package therefore stays small and web search remains useful when
 the optional rendered browser is absent.
 

package/docs/SECURITY_REVIEW.md

@@ -66,12 +66,12 @@ The active source takes a different architecture and distribution path:
   approval class. Curated assets are size-limited, constrained to catalog URLs,
   protected from output path traversal, and are not automatically extracted.
 - Web search uses bounded HTTP providers without requiring a browser binary.
-  Interactive rendered browsing uses an outbound, in-process Camoufox adapter.
-  Causyne does not run Camofox Browser's server, inbound port, remote control,
+  Interactive rendered browsing uses an outbound, in-process Causyne Browser adapter.
+  Causyne does not run an inbound browser-control server, inbound port, remote control,
   VNC, telemetry, cloud deployment, or OpenClaw integration. Optional launcher
   packages require an explicit capability grant. Causyne never downloads the
-  Camoufox browser binary; an existing external installation must be selected
-  through `CAUSYNE_CAMOFOX_EXECUTABLE` or a standard system location.
+  browser runtime; an existing external installation must be selected
+  through `CAUSYNE_BROWSER_EXECUTABLE` or a standard system location.
 - Browser navigation and subresources accept only public HTTP(S) destinations.
   Hostnames are resolved and checked against private, loopback, link-local,
   multicast, reserved, local, internal, and metadata ranges. Non-browser

package/docs/THIRD_PARTY_NOTICES.md

@@ -27,6 +27,9 @@ No dependency in the reviewed main lockfile was marked with an install script.
 Optional capability dependencies are installed only after approval into a
 separate local environment and are not covered by the main lockfile review.
 
+The product-facing browser capability is **Causyne Browser**. Upstream names
+below are used only for required attribution and exact dependency identifiers.
+
 The optional browser capability installs `camoufox-js` 0.11.5 under MPL-2.0
 and `playwright-core` 1.58.0 under Apache-2.0. They remain separate packages in
 the user's local capability directory and are not copied into Causyne Agent's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causyne/agent",
-  "version": "1.10.17",
+  "version": "1.10.18",
   "description": "Agentic AI for software, tools, and computer workflows",
   "main": "bin/causyne.js",
   "type": "module",

package/src/agentLoop.js

@@ -20,6 +20,7 @@ import { analyzeTask, buildTaskBrief, packsFromShape } from './taskShape.js';
 import { lookupPlan, recordPlan, recordMiss, renderPlanHint, toStep } from './planCache.js';
 import { routedConfig } from './modelRouter.js';
 import { assessStep, isThrashing } from './uncertainty.js';
+import { assessDecisionRequirement, isMutatingToolCall, requiresImplementationPlan } from './decisionPolicy.js';
 import { VFETracker } from './vfeTracker.js';
 import {
   routePacks,
@@ -75,11 +76,15 @@ Specifically, you excel at:
 - **No Chitchat**: Tools are for actions, text output is *only* for communication. Do not add explanatory comments within tool calls or code blocks.
 - **File Paths**: ALWAYS output the absolute path of any file you create, modify, or generate so the user knows exactly where it is.
 
-# Task Management & Planning (TodoWrite)
-- ALWAYS use the TodoWrite tool to track and manage tasks before starting implementation. Create atomic, verb-led, clear outcome items.
+# Task Management & Planning
+- Use update_plan to create a visible implementation checklist before complex implementation. Create atomic, verb-led, verifiable steps and keep exactly one step in progress.
 - Check off completed TODOs immediately before reporting progress. Do not batch up multiple task completions.
 - Reconcile and close the todo list when all goal tasks are done. If the user asks you to implement, do not output a separate text-based plan. Just build and display the todo list.
 
+# Durable Decisions
+- Use request_decision when multiple materially different architecture, product, data, security, or workflow directions are valid. Give 2-4 concrete options with consequences; the UI adds a custom-answer choice.
+- A decision is separate from permission. Do not ask for routine implementation details that can be resolved from the repository. Even in Mode C, pause for an unresolved durable architecture decision before changing the system.
+
 # Maximize Parallel Tool Calls (Speed is Key)
 - CRITICAL INSTRUCTION: For maximum efficiency, whenever you perform multiple operations, invoke all relevant tools concurrently (in parallel) rather than sequentially. 
 - Searching for different patterns (imports, usage, definitions) MUST happen in parallel. Reading multiple files MUST happen in parallel. 
@@ -344,6 +349,12 @@ export class AgentLoop {
     this.circuitBreakerUnlocked = false;
     this.stopRequested = false;
     this.pendingApprovals = new Map(); // Maps toolCallId -> resolve function
+    this.waitForDecision = async () => null;
+    this._decisionAnswers = new Map();
+    this._decisionRequirement = { required: false, kind: 'architecture', reason: '' };
+    this._decisionResolved = true;
+    this._implementationPlan = [];
+    this._implementationPlanRequired = false;
     // A delegated subagent can tighten these two ceilings. They are applied
     // after every config refresh so run() cannot accidentally replace a
     // worker's declared bounds with the parent tier defaults.
@@ -700,6 +711,58 @@ export class AgentLoop {
     }
   }
 
+  updateImplementationPlan(update) {
+    this._implementationPlan = update.plan.map(item => ({ ...item }));
+    this.emitEvent({
+      type: 'agent_plan',
+      explanation: update.explanation || '',
+      plan: this._implementationPlan.map(item => ({ status: item.status, text: item.step, id: item.id }))
+    });
+    auditLog.log({
+      event: 'implementation_plan_updated', taskId: this.taskId,
+      steps: this._implementationPlan.length,
+      completed: this._implementationPlan.filter(item => item.status === 'completed').length
+    });
+  }
+
+  async requestDecision(request) {
+    const fingerprint = createHash('sha256')
+      .update(JSON.stringify({ kind: request.kind, question: request.question, options: request.options.map(option => option.id) }))
+      .digest('hex');
+    const remembered = this._decisionAnswers.get(fingerprint);
+    if (remembered) return remembered;
+
+    this.emitEvent({ type: 'decision_request', request });
+    auditLog.log({ event: 'decision_requested', taskId: this.taskId, kind: request.kind, optionCount: request.options.length });
+    const answer = await this.waitForDecision(request);
+    if (!answer || typeof answer.label !== 'string' || !answer.label.trim()) {
+      this.emitEvent({ type: 'decision_result', request, answer: null });
+      return null;
+    }
+    const normalized = {
+      requestId: request.id,
+      optionId: typeof answer.optionId === 'string' ? answer.optionId : null,
+      label: answer.label.trim(),
+      custom: answer.custom === true
+    };
+    this._decisionAnswers.set(fingerprint, normalized);
+    if (request.kind === 'architecture') this._decisionResolved = true;
+    this.emitEvent({ type: 'decision_result', request, answer: normalized });
+    auditLog.log({ event: 'decision_answered', taskId: this.taskId, kind: request.kind, custom: normalized.custom });
+    return normalized;
+  }
+
+  mutationCheckpoint(functionName, args = {}) {
+    if (!isMutatingToolCall(functionName, args)) return null;
+    if (this._decisionRequirement.required && !this._decisionResolved) {
+      return 'ARCHITECTURE_DECISION_REQUIRED: Before changing the system, call request_decision with kind "architecture", 2-4 concrete options, their consequences, and a clear reason. Do not ask about routine details; this checkpoint exists because the current request crosses a durable architecture boundary.';
+    }
+    if (this._implementationPlanRequired && this._implementationPlan.length === 0) {
+      return 'IMPLEMENTATION_PLAN_REQUIRED: Call update_plan with atomic, verifiable steps and exactly one in_progress step before mutating this complex task.';
+    }
+    return null;
+  }
+
   updateTierLimits() {
     this.config = loadConfig();
     if (typeof this.initializeProvider === 'function') {
@@ -816,10 +879,26 @@ export class AgentLoop {
     this._lessonSimilarity = 0;
     this._lastToolResult = null;
     this._paradigmShiftPending = false;
+    this._implementationPlan = [];
+    this._decisionAnswers = new Map();
+    this._decisionRequirement = assessDecisionRequirement(this.userPrompt || '');
+    this._decisionResolved = !this._decisionRequirement.required;
+    this._implementationPlanRequired = false;
     if (this.vfeTracker) this.vfeTracker.reset();
 
     if (this.userPrompt) {
       this.taskShape = analyzeTask(this.userPrompt, this.workspaceContext);
+      this._implementationPlanRequired = requiresImplementationPlan(
+        this.userPrompt,
+        this.taskShape?.archetype || '',
+        this.taskShape?.confidence || ''
+      );
+      // request_decision is comparatively large and most tasks never need it.
+      // On providers without server-side schema deferral, expose it from the
+      // first model call only when the deterministic task policy found an
+      // unresolved durable choice. This keeps the resident prompt within its
+      // measured budget without making the checkpoint undiscoverable.
+      if (this._decisionRequirement.required) this.unlockedTools.add('request_decision');
 
       // Scored routing, with the regex router as a safety net so a pack can
       // never be missed just because it scored below threshold.
@@ -1077,9 +1156,8 @@ export class AgentLoop {
         // `tool_search_tool_regex`) keep the whole core in context for free —
         // the API holds the schemas server-side and expands them on demand,
         // with no discovery round trip. Every OTHER provider was serialising
-        // all 24 core schemas into every request: 3,341 tokens to advertise
-        // tools a typical turn never calls. There, ship the resident 8 (1,059
-        // tokens) and let `tool_search` — the same mechanism that already
+        // all 24 core schemas into every request. There, ship the small resident
+        // set and let `tool_search` — the same mechanism that already
         // unlocks packs — fetch the rest.
         const residentOnly = this.llm.supportsToolSearch?.() !== true;
         let dynamicTools = await getDynamicTools(this.config.autonomyMode, this.llm.supportsVision, {
@@ -1408,18 +1486,6 @@ export class AgentLoop {
         this.messages.push(assistantMsg);
         
         if (response.content) {
-          // V5: Parse TodoWrite checklist for visual plan display
-          const planRegex = /-\s*\[([ xX\/])\]\s*(.*)/g;
-          const planMatch = [...response.content.matchAll(planRegex)];
-          if (planMatch.length > 0) {
-            const planTasks = planMatch.map(m => {
-              const marker = m[1].toLowerCase();
-              const status = marker === 'x' ? 'completed' : (marker === '/' ? 'in_progress' : 'pending');
-              return { status, text: m[2].trim() };
-            });
-            this.emitEvent({ type: 'agent_plan', plan: planTasks });
-          }
-          
           this.emitEvent({ type: 'agent_message', content: response.content });
         }
 
@@ -1549,7 +1615,7 @@ export class AgentLoop {
             let webGuardMsg = '';
 
             if (!browserReady && !browserDeclined) {
-              webGuardMsg = `[ANTI-SLOP CHECK: You are building a Web/UI project and must inspect it before finishing, but the dedicated browser capability is not enabled yet. Call \`manage_local_dependencies\` with action "grant_capability" and group "browser" to request the Causyne Camoufox runtime. If the user declines, read the final compiled HTML/CSS instead. This check fires once.]`;
+              webGuardMsg = `[ANTI-SLOP CHECK: You are building a Web/UI project and must inspect it before finishing, but the dedicated browser capability is not enabled yet. Call \`manage_local_dependencies\` with action "grant_capability" and group "browser" to request the Causyne Browser runtime. If the user declines, read the final compiled HTML/CSS instead. This check fires once.]`;
             } else if (hasVision && !visionReady && !visionDeclined) {
               webGuardMsg = `[ANTI-SLOP CHECK: The browser is available, but desktop screen capture is not enabled. Call \`manage_local_dependencies\` with action "grant_capability" and group "vision" to request it, or use \`browser_act\` snapshots and its workspace-scoped screenshot action. This check fires once.]`;
             } else if (hasVision && visionReady && !this.webVerificationState.screenshotTaken) {
@@ -1803,6 +1869,20 @@ export class AgentLoop {
             continue;
           }
 
+          const checkpointError = this.mutationCheckpoint(functionName, args);
+          if (checkpointError) {
+            this.messages.push({
+              role: 'tool',
+              tool_call_id: toolCall.id,
+              name: functionName,
+              content: JSON.stringify({
+                success: false,
+                error: checkpointError
+              })
+            });
+            continue;
+          }
+
           // 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.
@@ -2266,7 +2346,7 @@ export class AgentLoop {
             //
             // Only payloads worth the trade are folded. A small `{"success":true}`
             // ack costs less than the pointer that would replace it, and every
-            // TodoWrite would otherwise collide with every other TodoWrite.
+            // Plan updates would otherwise collide with unrelated plan updates.
             const OBSERVATION_FOLD_FLOOR = 600;
             if (resultString.length >= OBSERVATION_FOLD_FLOOR) {
               const digest = createHash('sha256').update(resultString).digest('hex');

package/src/browser/{camofoxRuntime.js → browserRuntime.js}

@@ -4,7 +4,7 @@ import path from 'node:path';
 function assertExecutable(candidate) {
     const stat = statSync(candidate);
     if (!stat.isFile() && !stat.isSymbolicLink()) {
-        throw new Error(`Camoufox executable is not a file: ${candidate}`);
+        throw new Error(`Causyne Browser executable is not a file: ${candidate}`);
     }
     if (process.platform !== 'win32')
         accessSync(candidate, constants.X_OK);
@@ -61,33 +61,28 @@ function resourceDirectoryFor(executablePath) {
     }
     return path.dirname(executablePath);
 }
-export function resolveCamoufoxRuntime() {
-    const configured = process.env.CAUSYNE_CAMOFOX_EXECUTABLE?.trim();
-    const configuredHome = process.env.CAMOUFOX_INSTALL_DIR?.trim();
-    const candidates = configured
-        ? [path.resolve(configured)]
-        : configuredHome
-            ? [expectedExecutable(path.resolve(configuredHome))]
-            : candidateExecutables();
+export function resolveBrowserRuntime() {
+    const configured = process.env.CAUSYNE_BROWSER_EXECUTABLE?.trim();
+    const candidates = configured ? [path.resolve(configured)] : candidateExecutables();
     const executablePath = candidates.find(existsSync);
     if (!executablePath) {
-        throw new Error('Camoufox is not installed. Causyne does not download browser binaries automatically. ' +
-            'Install a trusted Camoufox build separately, then set CAUSYNE_CAMOFOX_EXECUTABLE to its executable path.');
+        throw new Error('Causyne Browser runtime is not installed. Causyne does not download browser binaries automatically. ' +
+            'Install a supported browser runtime separately, then set CAUSYNE_BROWSER_EXECUTABLE to its executable path.');
     }
     assertExecutable(executablePath);
     const resolvedExecutable = realpathSync(executablePath);
     const installDirectory = findInstallDirectory(resolvedExecutable);
     if (!installDirectory) {
-        throw new Error(`Camoufox at ${resolvedExecutable} is not inside a complete distribution. ` +
-            'Keep the distribution version.json beside its platform bundle and point CAUSYNE_CAMOFOX_EXECUTABLE at that bundle.');
+        throw new Error(`Causyne Browser runtime at ${resolvedExecutable} is not a complete distribution. ` +
+            'Keep version.json beside its platform bundle and point CAUSYNE_BROWSER_EXECUTABLE at that bundle.');
     }
     const resourceDirectory = resourceDirectoryFor(resolvedExecutable);
     if (!existsSync(path.join(resourceDirectory, 'properties.json'))) {
-        throw new Error(`Camoufox properties.json was not found in ${resourceDirectory}.`);
+        throw new Error(`Causyne Browser runtime metadata was not found in ${resourceDirectory}.`);
     }
     return {
         installDirectory,
         resourceDirectory,
-        source: configured || configuredHome ? 'environment' : 'system'
+        source: configured ? 'environment' : 'system'
     };
 }

package/src/browser/{camofoxRuntime.ts → browserRuntime.ts}

@@ -6,7 +6,7 @@ import path from 'node:path';
 // discovery at commit 2c0036a8b18bf9cd983376751ff4d52dfd9add0f. Causyne
 // keeps this integration layer in TypeScript and never downloads a browser.
 
-export interface PreparedCamoufoxRuntime {
+export interface PreparedBrowserRuntime {
   installDirectory: string;
   resourceDirectory: string;
   source: 'environment' | 'system';
@@ -15,7 +15,7 @@ export interface PreparedCamoufoxRuntime {
 function assertExecutable(candidate: string): void {
   const stat = statSync(candidate);
   if (!stat.isFile() && !stat.isSymbolicLink()) {
-    throw new Error(`Camoufox executable is not a file: ${candidate}`);
+    throw new Error(`Causyne Browser executable is not a file: ${candidate}`);
   }
   if (process.platform !== 'win32') accessSync(candidate, constants.X_OK);
 }
@@ -74,19 +74,14 @@ function resourceDirectoryFor(executablePath: string): string {
   return path.dirname(executablePath);
 }
 
-export function resolveCamoufoxRuntime(): PreparedCamoufoxRuntime {
-  const configured = process.env.CAUSYNE_CAMOFOX_EXECUTABLE?.trim();
-  const configuredHome = process.env.CAMOUFOX_INSTALL_DIR?.trim();
-  const candidates = configured
-    ? [path.resolve(configured)]
-    : configuredHome
-      ? [expectedExecutable(path.resolve(configuredHome))]
-      : candidateExecutables();
+export function resolveBrowserRuntime(): PreparedBrowserRuntime {
+  const configured = process.env.CAUSYNE_BROWSER_EXECUTABLE?.trim();
+  const candidates = configured ? [path.resolve(configured)] : candidateExecutables();
   const executablePath = candidates.find(existsSync);
   if (!executablePath) {
     throw new Error(
-      'Camoufox is not installed. Causyne does not download browser binaries automatically. ' +
-      'Install a trusted Camoufox build separately, then set CAUSYNE_CAMOFOX_EXECUTABLE to its executable path.'
+      'Causyne Browser runtime is not installed. Causyne does not download browser binaries automatically. ' +
+      'Install a supported browser runtime separately, then set CAUSYNE_BROWSER_EXECUTABLE to its executable path.'
     );
   }
 
@@ -95,18 +90,18 @@ export function resolveCamoufoxRuntime(): PreparedCamoufoxRuntime {
   const installDirectory = findInstallDirectory(resolvedExecutable);
   if (!installDirectory) {
     throw new Error(
-      `Camoufox at ${resolvedExecutable} is not inside a complete distribution. ` +
-      'Keep the distribution version.json beside its platform bundle and point CAUSYNE_CAMOFOX_EXECUTABLE at that bundle.'
+      `Causyne Browser runtime at ${resolvedExecutable} is not a complete distribution. ` +
+      'Keep version.json beside its platform bundle and point CAUSYNE_BROWSER_EXECUTABLE at that bundle.'
     );
   }
   const resourceDirectory = resourceDirectoryFor(resolvedExecutable);
   if (!existsSync(path.join(resourceDirectory, 'properties.json'))) {
-    throw new Error(`Camoufox properties.json was not found in ${resourceDirectory}.`);
+    throw new Error(`Causyne Browser runtime metadata was not found in ${resourceDirectory}.`);
   }
 
   return {
     installDirectory,
     resourceDirectory,
-    source: configured || configuredHome ? 'environment' : 'system'
+    source: configured ? 'environment' : 'system'
   };
 }

package/src/browser/causyneBrowser.js

@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { capabilityDirectory, ensureCapability, loadCapabilityPackage } from '../provisioning/capabilityProvisioner.js';
-import { resolveCamoufoxRuntime } from './camofoxRuntime.js';
+import { resolveBrowserRuntime } from './browserRuntime.js';
 import { assertPublicWebUrl } from './urlPolicy.js';
 import { windowSnapshot } from './snapshotWindow.js';
 const NAVIGATION_TIMEOUT_MS = 30_000;
@@ -113,7 +113,7 @@ const SEARCH_EXTRACT_SCRIPT = `(() => {
 export class CausyneBrowser {
     workspace;
     ensureBrowserCapability;
-    loadCamoufox;
+    loadBrowserEngine;
     resolveRuntime;
     profileDirectory;
     visible;
@@ -129,8 +129,8 @@ export class CausyneBrowser {
     constructor(options = {}) {
         this.workspace = path.resolve(options.workspace ?? process.cwd());
         this.ensureBrowserCapability = options.ensureBrowserCapability ?? (() => ensureCapability('browser'));
-        this.loadCamoufox = options.loadCamoufox ?? (async () => await loadCapabilityPackage('camoufox-js'));
-        this.resolveRuntime = options.resolveRuntime ?? resolveCamoufoxRuntime;
+        this.loadBrowserEngine = options.loadBrowserEngine ?? (async () => await loadCapabilityPackage('camoufox-js'));
+        this.resolveRuntime = options.resolveRuntime ?? resolveBrowserRuntime;
         this.profileDirectory = path.resolve(options.profileDirectory ?? path.join(capabilityDirectory(), 'browser-profile'));
         this.visible = options.visible ?? process.env.CAUSYNE_BROWSER_VISIBLE === '1';
         this.validateUrl = options.validateUrl ?? assertPublicWebUrl;
@@ -215,9 +215,9 @@ export class CausyneBrowser {
             const runtime = this.resolveRuntime();
             process.env.CAMOUFOX_INSTALL_DIR = runtime.installDirectory;
             await fs.mkdir(this.profileDirectory, { recursive: true, mode: 0o700 });
-            const module = await this.loadCamoufox();
+            const module = await this.loadBrowserEngine();
             if (!module || typeof module.Camoufox !== 'function')
-                throw new Error('The Camoufox capability has no usable launcher');
+                throw new Error('Causyne Browser has no usable launcher');
             this.session = await module.Camoufox({
                 headless: !this.visible,
                 user_data_dir: this.profileDirectory,

package/src/browser/causyneBrowser.ts

@@ -7,7 +7,7 @@ import {
   ensureCapability,
   loadCapabilityPackage
 } from '../provisioning/capabilityProvisioner.js';
-import { resolveCamoufoxRuntime, type PreparedCamoufoxRuntime } from './camofoxRuntime.js';
+import { resolveBrowserRuntime, type PreparedBrowserRuntime } from './browserRuntime.js';
 import { assertPublicWebUrl } from './urlPolicy.js';
 import { windowSnapshot, type SnapshotWindow } from './snapshotWindow.js';
 
@@ -76,7 +76,7 @@ interface BrowserSession {
   on?(event: 'page', handler: (page: BrowserPage) => void): void;
 }
 
-interface CamoufoxModule {
+interface BrowserEngineModule {
   Camoufox(options: Record<string, unknown>): Promise<BrowserSession>;
 }
 
@@ -132,8 +132,8 @@ export interface BrowserActionResult {
 interface RuntimeOptions {
   workspace?: string;
   ensureBrowserCapability?: () => Promise<{ ok: boolean; reason?: string; requiresConsent?: boolean }>;
-  loadCamoufox?: () => Promise<CamoufoxModule>;
-  resolveRuntime?: () => PreparedCamoufoxRuntime;
+  loadBrowserEngine?: () => Promise<BrowserEngineModule>;
+  resolveRuntime?: () => PreparedBrowserRuntime;
   profileDirectory?: string;
   visible?: boolean;
   validateUrl?: (value: string) => Promise<URL>;
@@ -240,7 +240,7 @@ const SEARCH_EXTRACT_SCRIPT = `(() => {
 export class CausyneBrowser {
   private readonly workspace: string;
   private readonly ensureBrowserCapability: NonNullable<RuntimeOptions['ensureBrowserCapability']>;
-  private readonly loadCamoufox: NonNullable<RuntimeOptions['loadCamoufox']>;
+  private readonly loadBrowserEngine: NonNullable<RuntimeOptions['loadBrowserEngine']>;
   private readonly resolveRuntime: NonNullable<RuntimeOptions['resolveRuntime']>;
   private readonly profileDirectory: string;
   private readonly visible: boolean;
@@ -257,8 +257,8 @@ export class CausyneBrowser {
   constructor(options: RuntimeOptions = {}) {
     this.workspace = path.resolve(options.workspace ?? process.cwd());
     this.ensureBrowserCapability = options.ensureBrowserCapability ?? (() => ensureCapability('browser'));
-    this.loadCamoufox = options.loadCamoufox ?? (async () => await loadCapabilityPackage('camoufox-js') as CamoufoxModule);
-    this.resolveRuntime = options.resolveRuntime ?? resolveCamoufoxRuntime;
+    this.loadBrowserEngine = options.loadBrowserEngine ?? (async () => await loadCapabilityPackage('camoufox-js') as BrowserEngineModule);
+    this.resolveRuntime = options.resolveRuntime ?? resolveBrowserRuntime;
     this.profileDirectory = path.resolve(options.profileDirectory ?? path.join(capabilityDirectory(), 'browser-profile'));
     this.visible = options.visible ?? process.env.CAUSYNE_BROWSER_VISIBLE === '1';
     this.validateUrl = options.validateUrl ?? assertPublicWebUrl;
@@ -340,8 +340,8 @@ export class CausyneBrowser {
       const runtime = this.resolveRuntime();
       process.env.CAMOUFOX_INSTALL_DIR = runtime.installDirectory;
       await fs.mkdir(this.profileDirectory, { recursive: true, mode: 0o700 });
-      const module = await this.loadCamoufox();
-      if (!module || typeof module.Camoufox !== 'function') throw new Error('The Camoufox capability has no usable launcher');
+      const module = await this.loadBrowserEngine();
+      if (!module || typeof module.Camoufox !== 'function') throw new Error('Causyne Browser has no usable launcher');
       this.session = await module.Camoufox({
         headless: !this.visible,
         user_data_dir: this.profileDirectory,

package/src/cliMode.js

@@ -12,7 +12,7 @@ import { getPackageVersion } from './version.js';
 import { resolveCharPool } from './contextManager.js';
 import { PRIMARY_ACTIONS, homeStatusLine, homeHint, moreLayer, configureInPrompt, mcpPicker, PROVIDERS } from './tui/home.js';
 import { SelectLayer } from './tui/dialogs.js';
-import { askSelect, askText, askConfirm } from './tui/ask.js';
+import { askSelect, askText, askConfirm, askDecision } from './tui/ask.js';
 import { renderReport } from './reporting.js';
 import { grantAlways } from './approvalGrants.js';
 import { auditLog } from './auditLog.js';
@@ -151,6 +151,15 @@ function makeApprovalHandler(conn, dialogs = null) {
   };
 }
 
+/** Keep implementation choices distinct from tool permission decisions. */
+function makeDecisionHandler(conn, dialogs = null) {
+  return async (request) => {
+    conn.stopSpinner();
+    if (dialogs && typeof dialogs.decide === 'function') return await dialogs.decide(request);
+    return await askDecision(request);
+  };
+}
+
 /** Muted one-liner for menu feedback that is not success and not an error. */
 function dimNotice(text) { return paint('muted', text); }
 
@@ -263,6 +272,7 @@ export async function runTask(task) {
   
   // Local human-in-the-loop, showing WHAT is being approved (see L6).
   loop.waitForApproval = makeApprovalHandler(conn);
+  loop.waitForDecision = makeDecisionHandler(conn);
 
   await loop.run();
   console.log('\n\x1b[32m[DONE]\x1b[0m Task completed.\n');
@@ -322,6 +332,7 @@ export async function chatMode({ home = false } = {}) {
   });
   
   loop.waitForApproval = makeApprovalHandler(conn);
+  loop.waitForDecision = makeDecisionHandler(conn);
 
   // The prompt owns the keyboard so the chat can offer history, completion and
   // typing while a turn runs. It is skipped when stdin is not a terminal (piped
@@ -378,6 +389,7 @@ export async function chatMode({ home = false } = {}) {
       // prompt. The panel shows the risk, the arguments and a scrollable diff in
       // one frame, and dismissing it denies.
       loop.waitForApproval = makeApprovalHandler(conn, prompt);
+      loop.waitForDecision = makeDecisionHandler(conn, prompt);
       // From here the modal asks the question, so the renderer must stop
       // printing the full request into the transcript as well — see
       // ChatRenderer.onApprovalRequest().

package/src/decisionPolicy.js

@@ -0,0 +1,68 @@
+const ARCHITECTURE_TERMS = [
+    'architecture', 'arsitektur',
+    'framework', 'runtime', 'database', 'storage', 'authentication', 'authorization',
+    'deployment', 'hosting', 'protocol', 'plugin system', 'sandbox', 'license',
+    'typescript', 'javascript', 'python', 'rust', 'kotlin', 'swift'
+];
+const CHANGE_TERMS = [
+    'change', 'replace', 'switch', 'choose', 'decide', 'redesign', 'restructure',
+    'rewrite', 'rebuild', 'migration', 'migrate',
+    'ubah', 'ganti', 'pilih', 'tentukan', 'rombak', 'beralih', 'migrasi'
+];
+const EXPLICIT_CHOICE_PATTERNS = [
+    /\b(?:i|we)\s+(?:choose|chose|selected?|decided? (?:on|to use))\s+[a-z0-9@._+-]+/i,
+    /\b(?:must use|will use|switch to|rewrite (?:to|in)|migrate to)\s+[a-z0-9@._+-]+/i,
+    /\b(?:saya pilih|aku pilih|kita pilih|harus memakai|beralih ke|ubah ke|ganti ke)\s+[a-z0-9@._+-]+/i,
+    /^(?:please\s+)?(?:use|choose|gunakan|pilih)\s+[a-z0-9@._+-]+/i,
+    /\b(?:do not|don't|jangan)\s+(?:use|gunakan|pakai)\s+[a-z0-9@._+-]+/i
+];
+const MUTATING_TOOLS = new Set([
+    'fs_write', 'fs_edit', 'MultiEdit', 'fs_delete', 'fs_move', 'sysRun', 'sysRunBg',
+    'gitOp', 'manage_local_dependencies', 'plugin_manage', 'tool_forge', 'create_skill'
+]);
+function containsAny(text, terms) {
+    return terms.some(term => text.includes(term));
+}
+export function assessDecisionRequirement(prompt) {
+    const raw = String(prompt ?? '').trim();
+    const text = raw.toLowerCase();
+    const architectural = containsAny(text, ARCHITECTURE_TERMS);
+    const change = containsAny(text, CHANGE_TERMS);
+    const alternatives = /\b(?:or|versus|vs\.?|atau|dibanding(?:kan)? dengan)\b/i.test(raw);
+    const asksForChoice = /\b(?:which|what should|should we|mana|apakah sebaiknya|bagaimana sebaiknya)\b/i.test(raw);
+    const delegatesBroadRedesign = /\b(?:redesign|restructure|rombak)\s+(?:the\s+)?(?:architecture|system|runtime|database|arsitektur|sistem)\b/i.test(raw);
+    const explicit = EXPLICIT_CHOICE_PATTERNS.some(pattern => pattern.test(raw));
+    if (!architectural || explicit || (!alternatives && !asksForChoice && !(change && delegatesBroadRedesign))) {
+        return { required: false, kind: 'architecture', reason: '' };
+    }
+    return {
+        required: true,
+        kind: 'architecture',
+        reason: 'The request reaches a durable architecture boundary with more than one plausible implementation.'
+    };
+}
+export function requiresImplementationPlan(prompt, archetype = '', confidence = '') {
+    const text = String(prompt ?? '').toLowerCase();
+    if (archetype === 'build_app' || archetype === 'integrate')
+        return true;
+    if (confidence === 'high' && /\b(?:implement|build|create|migrate|rewrite|refactor|integrate|buat|bangun|ubah)\b/i.test(text)) {
+        return true;
+    }
+    return containsAny(text, ARCHITECTURE_TERMS) && containsAny(text, CHANGE_TERMS);
+}
+export function isMutatingToolCall(toolName, args = {}) {
+    if (MUTATING_TOOLS.has(toolName)) {
+        if (toolName === 'sysRun' || toolName === 'sysRunBg') {
+            const command = String(args.command ?? '');
+            return !/^\s*(?:pwd|ls|find|rg|grep|cat|sed|head|tail|git\s+(?:status|diff|log|show)|npm\s+(?:view|audit|test)|node\s+--check)\b/i.test(command);
+        }
+        if (toolName === 'gitOp') {
+            const action = String(args.action ?? args.command ?? args.operation ?? '');
+            return !/^(?:status|diff|log|show|branch|remote)$/i.test(action.trim());
+        }
+        return true;
+    }
+    if (toolName.startsWith('plugin__') || toolName.startsWith('mcp__'))
+        return false;
+    return false;
+}