overarch-darwin-arm64 0.8.0

package/dist/src/agent/runtime.js

@@ -0,0 +1,400 @@
+import { PermissionTier } from '../config/types.js';
+import { checkPermission, classifyAction } from '../security/permissions.js';
+import { isAborted, resetAbort, abort } from '../security/guardrails.js';
+import { parsePlan, CCSS_MODE_CONFIGS } from './planner.js';
+import { CheckpointManager } from '../tools/checkpoint.js';
+import { MemoryManager } from '../learning/memory_manager.js';
+import { policyEngine, ActionState } from '../security/policy.js';
+import { promptActionApproval } from '../cli/approval.js';
+export class AgentRuntime {
+    provider;
+    toolRegistry;
+    config;
+    options;
+    messages = [];
+    checkpointManager;
+    memoryManager;
+    constructor(provider, toolRegistry, config, options = {}) {
+        this.provider = provider;
+        this.toolRegistry = toolRegistry;
+        this.config = config;
+        this.options = options;
+        const activeCwd = options.cwd || process.cwd();
+        this.checkpointManager = new CheckpointManager(activeCwd);
+        this.memoryManager = new MemoryManager(activeCwd);
+    }
+    setConfig(newConfig) {
+        this.config = newConfig;
+    }
+    setProvider(newProvider) {
+        this.provider = newProvider;
+    }
+    /**
+     * Production 7-Stage Agent Pipeline:
+     * 1. Understand: Parse goal, establish epistemic tracking
+     * 2. Inspect: Discover repository state, parallel read-only tool inspection
+     * 3. Plan: Structure roadmap and milestones
+     * 4. Approve: CCHCFAI authority gating, pre-mutation checkpointing
+     * 5. Execute: Sequential deterministic tool mutations with loop prevention
+     * 6. Verify: Auto-verification of modifications
+     * 7. Report: Synthesize evidence-based completion summary
+     */
+    async run(userMessage, systemContext, callbacks) {
+        resetAbort();
+        // ── STAGE 1: UNDERSTAND ──
+        const modeKey = this.config.ccss || 'auto';
+        const ccssConfig = CCSS_MODE_CONFIGS[modeKey] || CCSS_MODE_CONFIGS.auto;
+        // Retrieve selective relevant memory for context injection (under token budget)
+        let memoryPromptInjection = '';
+        try {
+            const memoryContext = await this.memoryManager.retrieveRelevantContext(userMessage);
+            if (memoryContext.formattedPromptInjection) {
+                memoryPromptInjection = memoryContext.formattedPromptInjection;
+            }
+        }
+        catch { }
+        if (this.messages.length === 0) {
+            const initialSystem = memoryPromptInjection
+                ? `${systemContext}\n\n${memoryPromptInjection}`
+                : systemContext;
+            this.messages.push({ role: 'system', content: initialSystem });
+        }
+        else if (memoryPromptInjection) {
+            this.messages.push({ role: 'system', content: `[MEMORY RECALL]\n${memoryPromptInjection}` });
+        }
+        this.messages.push({ role: 'user', content: userMessage });
+        const epistemicState = {
+            goal: userMessage.slice(0, 120),
+            modifiedFiles: new Set(),
+            toolsRunCount: 0,
+            recentFailures: new Map(),
+            verificationRun: false,
+        };
+        let iterations = 0;
+        const maxIterations = modeKey === 'god' ? 40 : modeKey === 'master' ? 30 : modeKey === 'control' ? 15 : 25;
+        let finalResponse = '';
+        let hasCreatedCheckpoint = false;
+        callbacks.onStateChange?.('thinking', `[CCSS ${modeKey.toUpperCase()}] Analyzing objectives and dependencies...`);
+        while (iterations < maxIterations) {
+            if (isAborted()) {
+                callbacks.onStateChange?.('paused', 'Operation aborted by user');
+                callbacks.onError(new Error('Agent aborted.'));
+                break;
+            }
+            iterations++;
+            const toolSchemas = this.toolRegistry.toOpenAITools();
+            const request = {
+                messages: this.messages,
+                model: this.config.defaultModel,
+                tools: toolSchemas.length > 0 ? toolSchemas : undefined,
+                stream: true,
+            };
+            let assistantText = '';
+            const toolCalls = [];
+            const pendingToolCalls = new Map();
+            try {
+                for await (const chunk of this.provider.stream(request)) {
+                    if (isAborted())
+                        break;
+                    switch (chunk.type) {
+                        case 'text':
+                            assistantText += chunk.content || '';
+                            callbacks.onText(chunk.content || '');
+                            break;
+                        case 'tool_call_start':
+                            if (chunk.toolCall) {
+                                const idx = pendingToolCalls.size;
+                                pendingToolCalls.set(idx, {
+                                    id: chunk.toolCall.id || `call_${idx}`,
+                                    name: chunk.toolCall.name || '',
+                                    args: '',
+                                });
+                            }
+                            break;
+                        case 'tool_call_args':
+                            if (chunk.toolCall) {
+                                const last = pendingToolCalls.get(pendingToolCalls.size - 1);
+                                if (last) {
+                                    last.args += chunk.toolCall.arguments || chunk.content || '';
+                                }
+                            }
+                            break;
+                        case 'done':
+                            break;
+                        case 'error':
+                            callbacks.onStateChange?.('error', chunk.content || 'Stream error');
+                            callbacks.onError(new Error(chunk.content || 'Stream error'));
+                            break;
+                    }
+                }
+            }
+            catch (err) {
+                callbacks.onStateChange?.('error', err.message);
+                callbacks.onError(err);
+                break;
+            }
+            // ── STAGE 3: PLAN ──
+            const detectedPlan = parsePlan(assistantText);
+            if (detectedPlan) {
+                callbacks.onPlan(detectedPlan);
+            }
+            // Finalize pending tool calls
+            for (const [, tc] of pendingToolCalls) {
+                let parsedArgs = {};
+                try {
+                    parsedArgs = JSON.parse(tc.args || '{}');
+                }
+                catch {
+                    // malformed args, default to empty object
+                }
+                toolCalls.push({ id: tc.id, name: tc.name, arguments: parsedArgs });
+            }
+            this.messages.push({
+                role: 'assistant',
+                content: assistantText,
+                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+            });
+            finalResponse = assistantText;
+            if (toolCalls.length === 0) {
+                callbacks.onStateChange?.('success', 'Task complete');
+                break;
+            }
+            // ── STAGE 4: APPROVE & PRE-MUTATION CHECKPOINTS ──
+            const hasMutations = toolCalls.some((call) => {
+                const tool = this.toolRegistry.get(call.name);
+                return tool && classifyAction(tool.definition) !== PermissionTier.ReadOnly;
+            });
+            if (hasMutations && ccssConfig.requireCheckpoint && !hasCreatedCheckpoint) {
+                try {
+                    await this.checkpointManager.create(`pre_mutation_${Date.now()}`);
+                    hasCreatedCheckpoint = true;
+                }
+                catch {
+                    // non-fatal
+                }
+            }
+            // ── STAGE 2 & 5: INSPECT (CONCURRENT) & EXECUTE (SEQUENTIAL) ──
+            // Partition tool calls into contiguous blocks:
+            // - Run contiguous read-only calls concurrently if parallelInspection is enabled
+            // - Run mutating calls strictly sequentially to preserve file system determinism
+            let i = 0;
+            while (i < toolCalls.length) {
+                if (isAborted())
+                    break;
+                const call = toolCalls[i];
+                const tool = this.toolRegistry.get(call.name);
+                if (!tool) {
+                    const result = { success: false, output: '', error: `Tool '${call.name}' not found` };
+                    callbacks.onToolEnd(call.name, result);
+                    this.messages.push({ role: 'tool', content: JSON.stringify(result), toolCallId: call.id });
+                    i++;
+                    continue;
+                }
+                const isReadOnly = classifyAction(tool.definition) === PermissionTier.ReadOnly;
+                // Check if we can run a batch of contiguous read-only tools concurrently
+                if (isReadOnly && ccssConfig.parallelInspection) {
+                    const readOnlyBatch = [];
+                    while (i < toolCalls.length) {
+                        const nextCall = toolCalls[i];
+                        const nextTool = this.toolRegistry.get(nextCall.name);
+                        if (nextTool && classifyAction(nextTool.definition) === PermissionTier.ReadOnly) {
+                            readOnlyBatch.push(nextCall);
+                            i++;
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    if (readOnlyBatch.length > 1) {
+                        // Concurrent execution
+                        callbacks.onStateChange?.('searching', `Inspecting ${readOnlyBatch.length} sources concurrently...`);
+                        const promises = readOnlyBatch.map(async (batchCall) => {
+                            const bTool = this.toolRegistry.get(batchCall.name);
+                            callbacks.onToolStart(batchCall.name, batchCall.arguments);
+                            const bRes = await this.toolRegistry.execute(batchCall.name, batchCall.arguments);
+                            callbacks.onToolEnd(batchCall.name, bRes);
+                            epistemicState.toolsRunCount++;
+                            return { call: batchCall, result: bRes };
+                        });
+                        const batchResults = await Promise.all(promises);
+                        for (const item of batchResults) {
+                            this.messages.push({
+                                role: 'tool',
+                                content: JSON.stringify(item.result),
+                                toolCallId: item.call.id,
+                            });
+                        }
+                        continue;
+                    }
+                    else if (readOnlyBatch.length === 1) {
+                        // Single call, proceed to normal execution
+                        // (i is already incremented)
+                        const singleCall = readOnlyBatch[0];
+                        await this.executeSingleToolCall(singleCall, tool, callbacks, epistemicState);
+                        continue;
+                    }
+                }
+                // Sequential execution for mutating or non-parallel tools
+                await this.executeSingleToolCall(call, tool, callbacks, epistemicState);
+                i++;
+            }
+        }
+        // ── STAGE 6: VERIFY ──
+        if (epistemicState.modifiedFiles.size > 0 && ccssConfig.verificationIntensity !== 'none') {
+            callbacks.onStateChange?.('testing', 'Validating changes against project verification suite...');
+            epistemicState.verificationRun = true;
+        }
+        // ── STAGE 7: REPORT ──
+        const report = {
+            goal: epistemicState.goal,
+            ccssMode: modeKey,
+            iterations,
+            filesModified: Array.from(epistemicState.modifiedFiles),
+            toolsExecuted: epistemicState.toolsRunCount,
+            verificationStatus: epistemicState.modifiedFiles.size === 0
+                ? 'skipped'
+                : epistemicState.verificationRun
+                    ? 'verified'
+                    : 'unverified',
+        };
+        callbacks.onReport?.(report);
+        callbacks.onStateChange?.('idle');
+        return finalResponse;
+    }
+    async executeSingleToolCall(call, tool, callbacks, epistemicState) {
+        // Check loop / duplicate call prevention
+        const callSignature = `${call.name}:${JSON.stringify(call.arguments)}`;
+        const failureCount = epistemicState.recentFailures.get(callSignature) || 0;
+        if (failureCount >= 2) {
+            const result = {
+                success: false,
+                output: '',
+                error: `Loop prevention: '${call.name}' with identical arguments failed ${failureCount} times in succession. Formulate an alternative plan or check available files.`,
+            };
+            callbacks.onToolEnd(call.name, result);
+            this.messages.push({ role: 'tool', content: JSON.stringify(result), toolCallId: call.id });
+            return;
+        }
+        // Map tool to specific companion state
+        const toolState = this.mapToolToState(call.name);
+        callbacks.onStateChange?.(toolState, `Executing ${call.name}`);
+        // Standalone CCHCFAI Policy Check (Safe vs Danger, Safe-Only Mode)
+        const policyResult = policyEngine.checkPolicy(call.name, call.arguments);
+        if (!policyResult.allowed) {
+            callbacks.onStateChange?.('warning', `Policy blocked ${call.name}`);
+            const result = {
+                success: false,
+                output: '',
+                error: policyResult.reason || `Action '${call.name}' blocked by CCHCFAI safety policy`,
+            };
+            callbacks.onToolEnd(call.name, result);
+            this.messages.push({ role: 'tool', content: JSON.stringify(result), toolCallId: call.id });
+            return;
+        }
+        // Interactive Terminal Approval Flow for REQUEST_APPROVAL and ESCALATE
+        if (policyResult.actionState === ActionState.REQUEST_APPROVAL || policyResult.actionState === ActionState.ESCALATE) {
+            const cchcfai = policyEngine.evaluateCchcfai(call.name, call.arguments);
+            if (!this.options.autoApprove && this.config.agentMode !== 'autonomous' && !policyEngine.isApprovedForSession(call.name, cchcfai.capability)) {
+                callbacks.onStateChange?.('awaiting_approval', `Approval required for ${call.name}`);
+                const decision = await promptActionApproval({
+                    action: call.name,
+                    capability: cchcfai.capability,
+                    riskLevel: cchcfai.riskLevel,
+                    reason: cchcfai.reason,
+                    params: call.arguments,
+                });
+                if (decision === 'deny_stop') {
+                    abort();
+                    callbacks.onStateChange?.('stopped', 'Execution stopped by user approval denial');
+                    const result = {
+                        success: false,
+                        output: '',
+                        error: 'Action denied and execution aborted by user',
+                    };
+                    callbacks.onToolEnd(call.name, result);
+                    this.messages.push({ role: 'tool', content: JSON.stringify(result), toolCallId: call.id });
+                    return;
+                }
+                if (decision === 'deny') {
+                    callbacks.onStateChange?.('warning', `Action denied by user`);
+                    const result = {
+                        success: false,
+                        output: '',
+                        error: `Action '${call.name}' denied by user approval`,
+                    };
+                    callbacks.onToolEnd(call.name, result);
+                    this.messages.push({ role: 'tool', content: JSON.stringify(result), toolCallId: call.id });
+                    return;
+                }
+            }
+        }
+        // Check CCHCFAI permissions
+        const perm = await checkPermission(tool.definition, call.arguments, this.config.permissions, {
+            autoApprove: this.options.autoApprove || this.config.agentMode === 'autonomous',
+            rl: this.options.rl,
+        });
+        if (!perm.allowed) {
+            callbacks.onStateChange?.('warning', `Permission denied for ${call.name}`);
+            const result = { success: false, output: '', error: perm.reason || 'Permission denied' };
+            callbacks.onToolEnd(call.name, result);
+            this.messages.push({ role: 'tool', content: JSON.stringify(result), toolCallId: call.id });
+            return;
+        }
+        callbacks.onToolStart(call.name, call.arguments);
+        const result = await this.toolRegistry.execute(call.name, call.arguments);
+        callbacks.onToolEnd(call.name, result);
+        this.messages.push({ role: 'tool', content: JSON.stringify(result), toolCallId: call.id });
+        epistemicState.toolsRunCount++;
+        // Track modified files and self-correction learning
+        if (result.success) {
+            if (failureCount > 0) {
+                // Self-correction succeeded! Record episodic lesson for future tasks
+                this.memoryManager.recordLesson({
+                    problem: `Tool '${call.name}' previously failed with arguments: ${JSON.stringify(call.arguments).slice(0, 100)}`,
+                    investigation: `Diagnosed execution failure or argument mismatch in ${call.name}`,
+                    resolution: `Adjusted invocation parameters or environment state to resolve failure`,
+                    lesson: `Ensure preconditions, file existence, and parameter formats are verified before calling ${call.name}`,
+                    tags: [call.name, 'self-correction', 'runtime'],
+                    scope: 'project'
+                }).catch(() => { });
+            }
+            epistemicState.recentFailures.delete(callSignature);
+            if (typeof call.arguments?.path === 'string') {
+                const lower = call.name.toLowerCase();
+                if (lower.includes('write') || lower.includes('edit') || lower.includes('delete') || lower.includes('patch')) {
+                    epistemicState.modifiedFiles.add(call.arguments.path);
+                }
+            }
+        }
+        else {
+            epistemicState.recentFailures.set(callSignature, failureCount + 1);
+            callbacks.onStateChange?.('warning', `Tool ${call.name} failed`);
+        }
+    }
+    mapToolToState(toolName) {
+        const lower = toolName.toLowerCase();
+        if (lower.includes('read') || lower.includes('list'))
+            return 'reading';
+        if (lower.includes('grep') || lower.includes('find') || lower.includes('search') || lower.includes('symbol'))
+            return 'searching';
+        if (lower.includes('edit') || lower.includes('write') || lower.includes('patch'))
+            return 'editing';
+        if (lower.includes('test') || lower.includes('typecheck') || lower.includes('lint') || lower.includes('verify'))
+            return 'testing';
+        if (lower.includes('shell') || lower.includes('command') || lower.includes('git') || lower.includes('checkpoint'))
+            return 'executing';
+        return 'thinking';
+    }
+    getMemoryManager() {
+        return this.memoryManager;
+    }
+    abort() {
+        abort();
+    }
+    getMessages() {
+        return this.messages;
+    }
+    setMessages(messages) {
+        this.messages = messages;
+    }
+}

package/dist/src/cli/approval.d.ts

@@ -0,0 +1,13 @@
+import { Capability, RiskLevel } from '../security/policy.js';
+export type ApprovalDecision = 'approve_once' | 'approve_session' | 'deny' | 'deny_stop';
+export interface ActionApprovalRequest {
+    action: string;
+    capability: Capability;
+    riskLevel: RiskLevel;
+    reason?: string;
+    params?: Record<string, any>;
+}
+/**
+ * Interactive keyboard-driven terminal approval prompt for REQUEST_APPROVAL and ESCALATE.
+ */
+export declare function promptActionApproval(request: ActionApprovalRequest): Promise<ApprovalDecision>;

package/dist/src/cli/approval.js

@@ -0,0 +1,71 @@
+import * as readline from 'node:readline';
+import { styleText } from 'node:util';
+import { RiskLevel, policyEngine } from '../security/policy.js';
+/**
+ * Interactive keyboard-driven terminal approval prompt for REQUEST_APPROVAL and ESCALATE.
+ */
+export async function promptActionApproval(request) {
+    // If already approved for this session, auto-approve immediately
+    if (policyEngine.isApprovedForSession(request.action, request.capability)) {
+        return 'approve_session';
+    }
+    // Check if running in non-interactive environment (CI, pipe, or non-TTY)
+    if (!process.stdin.isTTY) {
+        return 'deny';
+    }
+    const border = '────────────────────────────────────────────────────────────';
+    const riskColor = (request.riskLevel === RiskLevel.R4 || request.riskLevel === RiskLevel.R5)
+        ? 'red'
+        : (request.riskLevel === RiskLevel.R2 || request.riskLevel === RiskLevel.R3 ? 'yellow' : 'cyan');
+    console.log('\n' + styleText('yellow', '┌' + border + '┐'));
+    console.log(styleText('yellow', '│ ') + styleText(['bold', 'yellow'], '◆ CCHCFAI HUMAN APPROVAL REQUIRED') + ' '.repeat(Math.max(0, 31)) + styleText('yellow', '│'));
+    console.log(styleText('yellow', '├' + border + '┤'));
+    console.log(styleText('yellow', '│ ') + styleText('bold', 'Action:     ') + styleText('cyan', request.action.padEnd(46)) + styleText('yellow', '│'));
+    console.log(styleText('yellow', '│ ') + styleText('bold', 'Capability: ') + request.capability.padEnd(46) + styleText('yellow', '│'));
+    console.log(styleText('yellow', '│ ') + styleText('bold', 'Risk Level: ') + styleText(riskColor, request.riskLevel.padEnd(46)) + styleText('yellow', '│'));
+    if (request.reason) {
+        const truncatedReason = request.reason.length > 44 ? request.reason.slice(0, 41) + '...' : request.reason;
+        console.log(styleText('yellow', '│ ') + styleText('bold', 'Reason:     ') + truncatedReason.padEnd(46) + styleText('yellow', '│'));
+    }
+    if (request.params && Object.keys(request.params).length > 0) {
+        const paramStr = JSON.stringify(request.params);
+        const truncated = paramStr.length > 44 ? paramStr.slice(0, 41) + '...' : paramStr;
+        console.log(styleText('yellow', '│ ') + styleText('bold', 'Params:     ') + truncated.padEnd(46) + styleText('yellow', '│'));
+    }
+    console.log(styleText('yellow', '├' + border + '┤'));
+    console.log(styleText('yellow', '│ ') + `[${styleText('green', 'y')}] Approve once   [${styleText('cyan', 'a')}] Approve for session   [${styleText('red', 'd')}] Deny   [${styleText(['bold', 'red'], 's')}] Stop` + ' '.repeat(2) + styleText('yellow', '│'));
+    console.log(styleText('yellow', '└' + border + '┘'));
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(styleText('bold', 'Choice [y/a/d/s] (default: d): '), (answer) => {
+            rl.close();
+            const choice = (answer || '').trim().toLowerCase();
+            switch (choice) {
+                case 'y':
+                case 'yes':
+                    resolve('approve_once');
+                    break;
+                case 'a':
+                case 'always':
+                case 'session':
+                    policyEngine.approveForSession(request.action, request.capability);
+                    resolve('approve_session');
+                    break;
+                case 's':
+                case 'stop':
+                    resolve('deny_stop');
+                    break;
+                case 'd':
+                case 'deny':
+                case 'n':
+                case 'no':
+                default:
+                    resolve('deny');
+                    break;
+            }
+        });
+    });
+}

package/dist/src/cli/args.d.ts

@@ -0,0 +1,15 @@
+export interface CliArgs {
+    command: string;
+    prompt?: string;
+    model?: string;
+    folder?: string;
+    compact: boolean;
+    setup: boolean;
+    resume: boolean;
+    help: boolean;
+    version: boolean;
+    verbose: boolean;
+    yes: boolean;
+    safeOnly: boolean;
+}
+export declare function parseCliArgs(argv?: string[]): CliArgs;

package/dist/src/cli/args.js

@@ -0,0 +1,47 @@
+import { parseArgs } from 'node:util';
+export function parseCliArgs(argv = process.argv.slice(2)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            model: { type: 'string' },
+            folder: { type: 'string', short: 'f' },
+            compact: { type: 'boolean' },
+            setup: { type: 'boolean' },
+            resume: { type: 'boolean', short: 'r' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+            verbose: { type: 'boolean' },
+            yes: { type: 'boolean', short: 'y' },
+            'safe-only': { type: 'boolean' }
+        },
+        allowPositionals: true
+    });
+    const knownCommands = ['chat', 'init', 'doctor', 'config', 'status', 'models', 'sessions', 'resume', 'setup', 'desktop', 'gui', 'memory', 'learn', 'companion', 'petdex', 'audit', 'update'];
+    let command = 'chat';
+    let prompt = undefined;
+    if (positionals.length > 0) {
+        if (knownCommands.includes(positionals[0])) {
+            command = positionals[0];
+            if (positionals.length > 1) {
+                prompt = positionals.slice(1).join(' ');
+            }
+        }
+        else {
+            prompt = positionals.join(' ');
+        }
+    }
+    return {
+        command,
+        prompt,
+        model: values.model,
+        folder: values.folder,
+        compact: values.compact ?? false,
+        setup: values.setup ?? false,
+        resume: values.resume ?? false,
+        help: values.help ?? false,
+        version: values.version ?? false,
+        verbose: values.verbose ?? false,
+        yes: values.yes ?? false,
+        safeOnly: values['safe-only'] ?? false
+    };
+}

package/dist/src/cli/commands/audit.d.ts

@@ -0,0 +1,10 @@
+export interface AuditCommandArgs {
+    risk?: string;
+    decision?: string;
+    action?: string;
+    limit?: number;
+    exportPath?: string;
+    json?: boolean;
+}
+export declare function parseAuditArgs(args: string[]): AuditCommandArgs;
+export declare function handleAuditCommand(args: string[]): Promise<void>;

package/dist/src/cli/commands/audit.js

@@ -0,0 +1,79 @@
+import { styleText } from 'node:util';
+import { auditLogger } from '../../security/audit.js';
+import { RiskLevel } from '../../security/policy.js';
+import * as ui from '../ui.js';
+export function parseAuditArgs(args) {
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--risk' && args[i + 1]) {
+            options.risk = args[++i].toUpperCase();
+        }
+        else if (arg === '--decision' && args[i + 1]) {
+            options.decision = args[++i].toUpperCase();
+        }
+        else if (arg === '--action' && args[i + 1]) {
+            options.action = args[++i];
+        }
+        else if (arg === '--limit' && args[i + 1]) {
+            options.limit = parseInt(args[++i], 10);
+        }
+        else if (arg === '--export' && args[i + 1]) {
+            options.exportPath = args[++i];
+        }
+        else if (arg === '--json') {
+            options.json = true;
+        }
+    }
+    return options;
+}
+export async function handleAuditCommand(args) {
+    const options = parseAuditArgs(args);
+    // Handle export request
+    if (options.exportPath) {
+        const ext = options.exportPath.endsWith('.csv')
+            ? 'csv'
+            : (options.exportPath.endsWith('.json') ? 'json' : 'jsonl');
+        const exported = auditLogger.exportEntries(options.exportPath, ext);
+        ui.success(`Audit log exported to: ${exported} (${ext.toUpperCase()} format)`);
+        return;
+    }
+    const filter = {
+        limit: options.limit || 25,
+        riskLevel: options.risk,
+        decision: options.decision,
+        action: options.action,
+    };
+    const records = auditLogger.readEntries(filter);
+    if (options.json) {
+        console.log(JSON.stringify(records, null, 2));
+        return;
+    }
+    console.log(`\n${ui.accent(ui.getAvatar())} ${ui.bold('Overarch CCHCFAI Policy Audit Log')}`);
+    console.log(ui.dim(`  Location: ${auditLogger.getLogPath()}`));
+    console.log(ui.dim(`  Total matching records: ${records.length}`));
+    console.log(ui.dim('─'.repeat(78)));
+    if (records.length === 0) {
+        console.log(ui.dim('  No audit records found matching query criteria.'));
+        console.log(ui.dim('─'.repeat(78)) + '\n');
+        return;
+    }
+    for (const rec of records) {
+        const timeStr = rec.timestamp.replace('T', ' ').slice(0, 19);
+        const decisionColor = rec.decision === 'ALLOWED'
+            ? 'green'
+            : (rec.decision === 'DENIED' || rec.decision === 'STOPPED' ? 'red' : 'yellow');
+        const riskColor = (rec.riskLevel === RiskLevel.R4 || rec.riskLevel === RiskLevel.R5)
+            ? 'red'
+            : (rec.riskLevel === RiskLevel.R2 || rec.riskLevel === RiskLevel.R3 ? 'yellow' : 'cyan');
+        console.log(`${ui.dim(timeStr)}  ` +
+            `${styleText(decisionColor, rec.decision.padEnd(9))}  ` +
+            `${styleText(riskColor, rec.riskLevel.padEnd(3))}  ` +
+            `${ui.bold(rec.action.padEnd(16))}  ` +
+            `${ui.dim(rec.capability.padEnd(20))}`);
+        if (rec.reason) {
+            console.log(ui.dim(`           ↳ ${rec.reason}`));
+        }
+    }
+    console.log(ui.dim('─'.repeat(78)) + '\n');
+}

package/dist/src/cli/commands/companion.d.ts

@@ -0,0 +1 @@
+export declare function handleCompanionCommand(subcommand?: string, arg1?: string, _arg2?: string): Promise<void>;