@causyne/agent 1.10.17 → 1.10.18

package/src/decisionPolicy.ts

@@ -0,0 +1,106 @@
+export type DecisionKind = 'architecture' | 'product' | 'data' | 'security' | 'workflow' | 'other';
+
+export interface DecisionOption {
+  id: string;
+  label: string;
+  description: string;
+}
+
+export interface DecisionRequest {
+  id: string;
+  kind: DecisionKind;
+  header: string;
+  question: string;
+  reason: string;
+  options: DecisionOption[];
+  allowCustom: boolean;
+}
+
+export interface DecisionAnswer {
+  requestId: string;
+  optionId: string | null;
+  label: string;
+  custom: boolean;
+}
+
+export interface DecisionRequirement {
+  required: boolean;
+  kind: DecisionKind;
+  reason: string;
+}
+
+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: string, terms: readonly string[]): boolean {
+  return terms.some(term => text.includes(term));
+}
+
+export function assessDecisionRequirement(prompt: string): DecisionRequirement {
+  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: string, archetype = '', confidence = ''): boolean {
+  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: string, args: Record<string, unknown> = {}): boolean {
+  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;
+}

package/src/implementationPlan.js

@@ -0,0 +1,50 @@
+const MAX_STEPS = 24;
+function cleanText(value, name, limit) {
+    if (typeof value !== 'string')
+        throw new Error(`${name} must be a string`);
+    const cleaned = value.replace(/\s+/g, ' ').trim();
+    if (!cleaned)
+        throw new Error(`${name} must not be empty`);
+    if (cleaned.length > limit)
+        throw new Error(`${name} exceeds ${limit} characters`);
+    return cleaned;
+}
+export function normalizePlanUpdate(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Plan update must be an object');
+    const input = value;
+    if (!Array.isArray(input.plan) || input.plan.length === 0)
+        throw new Error('plan must contain at least one step');
+    if (input.plan.length > MAX_STEPS)
+        throw new Error(`plan may contain at most ${MAX_STEPS} steps`);
+    const ids = new Set();
+    let active = 0;
+    const plan = input.plan.map((raw, index) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new Error(`plan[${index}] must be an object`);
+        const item = raw;
+        const id = cleanText(item.id ?? `step-${index + 1}`, `plan[${index}].id`, 64);
+        const step = cleanText(item.step ?? item.content, `plan[${index}].step`, 240);
+        const status = item.status;
+        if (status !== 'pending' && status !== 'in_progress' && status !== 'completed') {
+            throw new Error(`plan[${index}].status must be pending, in_progress, or completed`);
+        }
+        if (ids.has(id))
+            throw new Error(`Duplicate plan step id: ${id}`);
+        ids.add(id);
+        if (status === 'in_progress')
+            active += 1;
+        return { id, step, status };
+    });
+    if (active > 1)
+        throw new Error('Only one plan step may be in_progress');
+    const explanation = typeof input.explanation === 'string'
+        ? input.explanation.replace(/\s+/g, ' ').trim().slice(0, 500)
+        : '';
+    return { explanation, plan };
+}
+export function summarizePlan(plan) {
+    const completed = plan.filter(item => item.status === 'completed').length;
+    const active = plan.find(item => item.status === 'in_progress');
+    return `${completed}/${plan.length} completed${active ? `; in progress: ${active.step}` : ''}`;
+}

package/src/implementationPlan.ts

@@ -0,0 +1,59 @@
+export type PlanStatus = 'pending' | 'in_progress' | 'completed';
+
+export interface PlanStep {
+  id: string;
+  step: string;
+  status: PlanStatus;
+}
+
+export interface PlanUpdate {
+  explanation: string;
+  plan: PlanStep[];
+}
+
+const MAX_STEPS = 24;
+
+function cleanText(value: unknown, name: string, limit: number): string {
+  if (typeof value !== 'string') throw new Error(`${name} must be a string`);
+  const cleaned = value.replace(/\s+/g, ' ').trim();
+  if (!cleaned) throw new Error(`${name} must not be empty`);
+  if (cleaned.length > limit) throw new Error(`${name} exceeds ${limit} characters`);
+  return cleaned;
+}
+
+export function normalizePlanUpdate(value: unknown): PlanUpdate {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Plan update must be an object');
+  const input = value as Record<string, unknown>;
+  if (!Array.isArray(input.plan) || input.plan.length === 0) throw new Error('plan must contain at least one step');
+  if (input.plan.length > MAX_STEPS) throw new Error(`plan may contain at most ${MAX_STEPS} steps`);
+
+  const ids = new Set<string>();
+  let active = 0;
+  const plan = input.plan.map((raw, index): PlanStep => {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error(`plan[${index}] must be an object`);
+    const item = raw as Record<string, unknown>;
+    const id = cleanText(item.id ?? `step-${index + 1}`, `plan[${index}].id`, 64);
+    const step = cleanText(item.step ?? item.content, `plan[${index}].step`, 240);
+    const status = item.status;
+    if (status !== 'pending' && status !== 'in_progress' && status !== 'completed') {
+      throw new Error(`plan[${index}].status must be pending, in_progress, or completed`);
+    }
+    if (ids.has(id)) throw new Error(`Duplicate plan step id: ${id}`);
+    ids.add(id);
+    if (status === 'in_progress') active += 1;
+    return { id, step, status };
+  });
+
+  if (active > 1) throw new Error('Only one plan step may be in_progress');
+  const explanation = typeof input.explanation === 'string'
+    ? input.explanation.replace(/\s+/g, ' ').trim().slice(0, 500)
+    : '';
+  return { explanation, plan };
+}
+
+export function summarizePlan(plan: readonly PlanStep[]): string {
+  const completed = plan.filter(item => item.status === 'completed').length;
+  const active = plan.find(item => item.status === 'in_progress');
+  return `${completed}/${plan.length} completed${active ? `; in progress: ${active.step}` : ''}`;
+}
+

package/src/provisioning/capabilityProvisioner.js

@@ -44,7 +44,7 @@ const GROUP_PACKAGES = {
 
 // than listing package names.
 export const GROUP_DESCRIPTIONS = {
-  browser: 'use an existing Camoufox installation for rendered navigation, extraction, and workspace-scoped downloads; Causyne never downloads the browser binary automatically',
+  browser: 'use the Causyne Browser runtime for rendered navigation, extraction, and workspace-scoped downloads; Causyne never downloads the browser binary automatically',
   vision: 'drive a browser and capture the screen, so the agent can look at what it built',
   ocr: 'read text out of images and screenshots',
   system: 'list running processes and read system load',

package/src/taskShape.js

@@ -49,7 +49,7 @@ const ARCHETYPES = {
             weak: ['app', 'aplikasi', 'project', 'proyek', 'tool', 'system', 'sistem']
         },
         phases: [
-            { name: 'Plan', tools: ['TodoWrite'], note: 'Break the build into atomic, verifiable steps before touching the filesystem.' },
+            { name: 'Plan', tools: ['update_plan'], note: 'Create a visible atomic implementation plan before touching the filesystem.' },
             { name: 'Scaffold', tools: ['fs_write', 'sysRun'], note: 'Create structure and install dependencies at verified current versions.' },
             { name: 'Implement', tools: ['fs_write', 'fs_edit', 'MultiEdit'], note: 'Write runnable code with every import and dependency present.' },
             { name: 'Verify', tools: ['code_verify_syntax', 'sysRun'], note: 'Build, lint and run it. Never assume code works.' }

package/src/taskShape.ts

@@ -70,7 +70,7 @@ const ARCHETYPES: Record<string, ArchetypeDefinition> = {
       weak: ['app', 'aplikasi', 'project', 'proyek', 'tool', 'system', 'sistem']
     },
     phases: [
-      { name: 'Plan', tools: ['TodoWrite'], note: 'Break the build into atomic, verifiable steps before touching the filesystem.' },
+      { name: 'Plan', tools: ['update_plan'], note: 'Create a visible atomic implementation plan before touching the filesystem.' },
       { name: 'Scaffold', tools: ['fs_write', 'sysRun'], note: 'Create structure and install dependencies at verified current versions.' },
       { name: 'Implement', tools: ['fs_write', 'fs_edit', 'MultiEdit'], note: 'Write runnable code with every import and dependency present.' },
       { name: 'Verify', tools: ['code_verify_syntax', 'sysRun'], note: 'Build, lint and run it. Never assume code works.' }

package/src/toolPacks.js

@@ -36,8 +36,8 @@ export const CORE_TOOLS = [
   'code_verify_syntax',
   'web_search',
   'web_fetch',
-  'TodoWrite',
   'update_plan',
+  'request_decision',
   'memory_write',
   'fs_read_skill',
   'skill_create',
@@ -130,9 +130,11 @@ export const PACK_NAMES = Object.keys(PACKS);
  *
  * WHAT IS IN, AND WHY EXACTLY THESE: read, write, edit, list and search cover
  * every file operation a first turn can need; `sysRun` is the escape hatch that
- * can reach anything the other seven cannot; `TodoWrite` is how a multi-step
- * task announces its plan on step one; `tool_search` is the door to the other
- * 62. With this set the agent is never stuck — worst case it spends one call
+ * can reach anything the other resident tools cannot; `update_plan` is how a
+ * multi-step task announces its plan on step one; `tool_search` is the door to
+ * deferred tools. `request_decision` is injected on the first turn only when
+ * task policy detects an unresolved durable choice. With this set the agent is
+ * never stuck — worst case it spends one call
  * discovering the tool it wants, and the tool it discovers stays loaded for the
  * rest of the task.
  *
@@ -147,7 +149,7 @@ export const RESIDENT_TOOLS = [
   'fs_list',
   'fs_search',
   'sysRun',
-  'TodoWrite',
+  'update_plan',
   'tool_search'
 ];
 

package/src/tools/browserAutomator.js

@@ -2,7 +2,7 @@ import { BrowserCapabilityError, causyneBrowser } from '../browser/causyneBrowse
 export const browserAct = {
     schema: {
         name: 'browser.act',
-        description: 'Use the dedicated Causyne Camoufox browser for resilient search, navigation, accessible snapshots, interaction, extraction, and workspace-scoped downloads. Take a snapshot before interacting by ref.',
+        description: 'Use the dedicated Causyne Browser for resilient search, navigation, accessible snapshots, interaction, extraction, and workspace-scoped downloads. Take a snapshot before interacting by ref.',
         parameters: {
             type: 'object',
             properties: {

package/src/tools/browserAutomator.ts

@@ -3,7 +3,7 @@ import { BrowserCapabilityError, causyneBrowser, type BrowserAction } from '../b
 export const browserAct = {
   schema: {
     name: 'browser.act',
-    description: 'Use the dedicated Causyne Camoufox browser for resilient search, navigation, accessible snapshots, interaction, extraction, and workspace-scoped downloads. Take a snapshot before interacting by ref.',
+    description: 'Use the dedicated Causyne Browser for resilient search, navigation, accessible snapshots, interaction, extraction, and workspace-scoped downloads. Take a snapshot before interacting by ref.',
     parameters: {
       type: 'object',
       properties: {

package/src/tools/manageLocalAiDependencies.js

@@ -55,7 +55,7 @@ export const manageLocalDependencies = {
       type: 'object',
       properties: {
         action: { type: 'string', enum: ['setup_venv', 'pipInst', 'check_and_setupEng', 'grant_capability', 'list_capabilities', 'grant_mcp_server', 'list_mcp_servers'] },
-        group: { type: 'string', description: 'Capability group for grant_capability: browser (dedicated Camoufox web runtime), vision (screen capture), ocr (read text from images), system (process and load inspection), desktop (clipboard, open, recycle bin), archive (zip and unzip).' },
+        group: { type: 'string', description: 'Capability group for grant_capability: browser (dedicated Causyne Browser runtime), vision (screen capture), ocr (read text from images), system (process and load inspection), desktop (clipboard, open, recycle bin), archive (zip and unzip).' },
         engine: { type: 'string', enum: ['godot', 'blender'], description: 'Engine to locate when action is check_and_setupEng' },
         simulateMissing: { type: 'boolean', description: 'Simulate missing binary to verify sovereign fallback cascade' },
         packages: { type: 'array', items: { type: 'string' }, description: 'Exact PyPI pins only, for example pillow==11.3.0. URLs, paths, VCS references and pip options are rejected.' }

package/src/tools/registry.js

@@ -12,7 +12,6 @@ import { processList } from './processList.js';
 import { procTerm } from './procTerm.js';
 import { webFetch } from './webFetch.js';
 import { desktopOpen } from './desktopOpen.js';
-import { todoWrite } from './todoWrite.js';
 import { multiEdit } from './multiEdit.js';
 import { codebaseSearch } from './codebaseSearch.js';
 import { browserAct } from './browserAutomator.js';
@@ -22,6 +21,7 @@ import { palmierAutomator } from './palmierAutomator.js';
 import { viewImage } from './viewImage.js';
 import { webSearch } from './webSearch.js';
 import { updatePlan } from './updatePlan.js';
+import { requestDecision } from './requestDecision.js';
 import { clipboard } from './clipboard.js';
 import { screenshot } from './screenshot.js';
 import { axSnapshot } from './axSnapshot.js';
@@ -106,9 +106,9 @@ const TOOL_MODULES = [
   sysRun, sysRunBg, fsRead, fsWrite,
   fsEdit, fsFind, fsSearch, fsList, fsMove,
   fsDelete, gitExec, processList, procTerm,
-  webFetch, desktopOpen, todoWrite, multiEdit,
+  webFetch, desktopOpen, multiEdit,
   codebaseSearch, browserAct, viewImage, webSearch,
-  updatePlan, clipboard, screenshot, axSnapshot, desktopAct, archive,
+  updatePlan, requestDecision, clipboard, screenshot, axSnapshot, desktopAct, archive,
   checkSystemSpecs, executeProceduralMedia, manageLocalAiDependencies,
   generateMediaViaApi, memoryWrite, printerPrint, printerList, printerStatus, toolForgeTool, pluginManagerTool,
   astryxOracle, pdfRead, codeVerifySyntax, codeListSymbols, blenderAct, resolveAutomator, palmierAutomator,
@@ -145,6 +145,7 @@ for (const module of TOOL_MODULES) {
 // a tool whose canonical schema name is different. Resolved only at execution
 // time — never advertised, so they cost no context.
 const TOOL_ALIASES = {
+  TodoWrite: 'update_plan',
   manage_local_ai_dependencies: 'manage_local_dependencies',
   procTerm: 'proc_term',
   gitExec: 'gitOp',

package/src/tools/requestDecision.js

@@ -0,0 +1,87 @@
+import crypto from 'node:crypto';
+const KINDS = new Set(['architecture', 'product', 'data', 'security', 'workflow', 'other']);
+function text(value, name, limit) {
+    if (typeof value !== 'string')
+        throw new Error(`${name} must be a string`);
+    const cleaned = value.replace(/\s+/g, ' ').trim();
+    if (!cleaned)
+        throw new Error(`${name} must not be empty`);
+    if (cleaned.length > limit)
+        throw new Error(`${name} exceeds ${limit} characters`);
+    return cleaned;
+}
+function normalizeRequest(args) {
+    const kind = String(args.kind ?? 'other');
+    if (!KINDS.has(kind))
+        throw new Error('kind is invalid');
+    if (!Array.isArray(args.options) || args.options.length < 2 || args.options.length > 4) {
+        throw new Error('options must contain 2-4 choices');
+    }
+    const ids = new Set();
+    const options = args.options.map((raw, index) => {
+        const option = (raw && typeof raw === 'object' ? raw : {});
+        const id = text(option.id ?? `option-${index + 1}`, `options[${index}].id`, 48);
+        if (ids.has(id))
+            throw new Error(`Duplicate option id: ${id}`);
+        ids.add(id);
+        return {
+            id,
+            label: text(option.label, `options[${index}].label`, 80),
+            description: text(option.description, `options[${index}].description`, 240)
+        };
+    });
+    return {
+        id: crypto.randomUUID(),
+        kind,
+        header: text(args.header, 'header', 48),
+        question: text(args.question, 'question', 500),
+        reason: text(args.reason, 'reason', 500),
+        options,
+        allowCustom: true
+    };
+}
+export const requestDecision = {
+    schema: {
+        name: 'request_decision',
+        description: 'Pause for a durable user decision when several materially different implementation directions are valid. Provide 2-4 concrete options; a custom answer is always available. This is a design decision, not a tool permission request.',
+        parameters: {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', enum: ['architecture', 'product', 'data', 'security', 'workflow', 'other'] },
+                header: { type: 'string', description: 'Short decision label, at most 48 characters.' },
+                question: { type: 'string', description: 'One specific decision the user must make.' },
+                reason: { type: 'string', description: 'Why this choice has durable consequences.' },
+                options: {
+                    type: 'array', minItems: 2, maxItems: 4,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            label: { type: 'string' },
+                            description: { type: 'string' }
+                        },
+                        required: ['id', 'label', 'description'],
+                        additionalProperties: false
+                    }
+                }
+            },
+            required: ['kind', 'header', 'question', 'reason', 'options'],
+            additionalProperties: false
+        }
+    },
+    async execute(args, context = {}) {
+        try {
+            if (!context.parentLoop || typeof context.parentLoop.requestDecision !== 'function') {
+                return { success: false, error: 'Structured decisions require an active Causyne session' };
+            }
+            const request = normalizeRequest(args);
+            const answer = await context.parentLoop.requestDecision(request);
+            if (!answer)
+                return { success: false, error: 'The user dismissed the decision without choosing an option' };
+            return { success: true, output: JSON.stringify(answer), decision: answer };
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+};

package/src/tools/requestDecision.ts

@@ -0,0 +1,107 @@
+import crypto from 'node:crypto';
+import type { DecisionKind, DecisionRequest } from '../decisionPolicy.js';
+
+interface ToolContext {
+  parentLoop?: {
+    requestDecision(request: DecisionRequest): Promise<unknown>;
+  };
+}
+
+interface RawOption {
+  id?: unknown;
+  label?: unknown;
+  description?: unknown;
+}
+
+interface RawInput {
+  kind?: unknown;
+  header?: unknown;
+  question?: unknown;
+  reason?: unknown;
+  options?: unknown;
+}
+
+const KINDS = new Set<DecisionKind>(['architecture', 'product', 'data', 'security', 'workflow', 'other']);
+
+function text(value: unknown, name: string, limit: number): string {
+  if (typeof value !== 'string') throw new Error(`${name} must be a string`);
+  const cleaned = value.replace(/\s+/g, ' ').trim();
+  if (!cleaned) throw new Error(`${name} must not be empty`);
+  if (cleaned.length > limit) throw new Error(`${name} exceeds ${limit} characters`);
+  return cleaned;
+}
+
+function normalizeRequest(args: RawInput): DecisionRequest {
+  const kind = String(args.kind ?? 'other') as DecisionKind;
+  if (!KINDS.has(kind)) throw new Error('kind is invalid');
+  if (!Array.isArray(args.options) || args.options.length < 2 || args.options.length > 4) {
+    throw new Error('options must contain 2-4 choices');
+  }
+  const ids = new Set<string>();
+  const options = args.options.map((raw, index) => {
+    const option = (raw && typeof raw === 'object' ? raw : {}) as RawOption;
+    const id = text(option.id ?? `option-${index + 1}`, `options[${index}].id`, 48);
+    if (ids.has(id)) throw new Error(`Duplicate option id: ${id}`);
+    ids.add(id);
+    return {
+      id,
+      label: text(option.label, `options[${index}].label`, 80),
+      description: text(option.description, `options[${index}].description`, 240)
+    };
+  });
+  return {
+    id: crypto.randomUUID(),
+    kind,
+    header: text(args.header, 'header', 48),
+    question: text(args.question, 'question', 500),
+    reason: text(args.reason, 'reason', 500),
+    options,
+    allowCustom: true
+  };
+}
+
+export const requestDecision = {
+  schema: {
+    name: 'request_decision',
+    description: 'Pause for a durable user decision when several materially different implementation directions are valid. Provide 2-4 concrete options; a custom answer is always available. This is a design decision, not a tool permission request.',
+    parameters: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['architecture', 'product', 'data', 'security', 'workflow', 'other'] },
+        header: { type: 'string', description: 'Short decision label, at most 48 characters.' },
+        question: { type: 'string', description: 'One specific decision the user must make.' },
+        reason: { type: 'string', description: 'Why this choice has durable consequences.' },
+        options: {
+          type: 'array', minItems: 2, maxItems: 4,
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              label: { type: 'string' },
+              description: { type: 'string' }
+            },
+            required: ['id', 'label', 'description'],
+            additionalProperties: false
+          }
+        }
+      },
+      required: ['kind', 'header', 'question', 'reason', 'options'],
+      additionalProperties: false
+    }
+  },
+
+  async execute(args: RawInput, context: ToolContext = {}) {
+    try {
+      if (!context.parentLoop || typeof context.parentLoop.requestDecision !== 'function') {
+        return { success: false, error: 'Structured decisions require an active Causyne session' };
+      }
+      const request = normalizeRequest(args);
+      const answer = await context.parentLoop.requestDecision(request);
+      if (!answer) return { success: false, error: 'The user dismissed the decision without choosing an option' };
+      return { success: true, output: JSON.stringify(answer), decision: answer };
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+};
+