delimit-cli 3.11.11 → 3.12.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [3.12.0] - 2026-03-26
+
+### Added
+- Cross-model hook system: session-start, pre-tool, and pre-commit hooks for Claude Code, Codex, and Gemini CLI
+- `delimit export` and `delimit import` commands for shareable governance config
+- `delimit hook <event>` commands for manual hook invocation
+- `delimit uninstall` removes hooks from all AI tools cleanly
+- Pre-push hooks for catching governance violations before remote push
+- Cursor and Codex adapters for native integration
+
+### Changed
+- "Keep Building." success message displayed on lint/diff/doctor pass
+- Zero-config action improvements for smoother CI integration
+
 ## [3.11.10] - 2026-03-24
 
 ### Added

package/bin/delimit-cli.js

@@ -9,6 +9,7 @@ const chalk = require('chalk');
 const inquirer = require('inquirer');
 const DelimitAuthSetup = require('../lib/auth-setup');
 const DelimitHooksInstaller = require('../lib/hooks-installer');
+const crossModelHooks = require('../lib/cross-model-hooks');
 
 const AGENT_URL = `http://127.0.0.1:${process.env.DELIMIT_AGENT_PORT || 7823}`;
 const program = new Command();
@@ -535,6 +536,36 @@ program
             changes.push({ target: '~/.delimit/shims/', action: 'Remove CLI shims directory' });
         }
 
+        // 8. Cross-model governance hooks (LED-202)
+        const claudeSettingsPath = path.join(HOME, '.claude', 'settings.json');
+        if (fs.existsSync(claudeSettingsPath)) {
+            try {
+                const cfg = JSON.parse(fs.readFileSync(claudeSettingsPath, 'utf8'));
+                if (cfg.hooks) {
+                    const hasDelimitHook = Object.values(cfg.hooks).some(arr =>
+                        Array.isArray(arr) && arr.some(h => h.command && h.command.includes('delimit-cli'))
+                    );
+                    if (hasDelimitHook) {
+                        changes.push({ target: '~/.claude/settings.json', action: 'Remove Delimit governance hooks' });
+                    }
+                }
+            } catch (e) {}
+        }
+        const codexInstructions = path.join(HOME, '.codex', 'instructions.md');
+        if (fs.existsSync(codexInstructions)) {
+            const content = fs.readFileSync(codexInstructions, 'utf8');
+            if (content.includes('delimit:hooks-start')) {
+                changes.push({ target: '~/.codex/instructions.md', action: 'Remove Delimit hook instructions' });
+            }
+        }
+        const geminiGovMd = path.join(HOME, '.gemini', 'GEMINI.md');
+        if (fs.existsSync(geminiGovMd)) {
+            const content = fs.readFileSync(geminiGovMd, 'utf8');
+            if (content.includes('Delimit Governance')) {
+                changes.push({ target: '~/.gemini/GEMINI.md', action: 'Remove Delimit governance file' });
+            }
+        }
+
         if (changes.length === 0) {
             console.log(chalk.green('\nNo Delimit integrations found. Nothing to remove.\n'));
             return;
@@ -625,6 +656,14 @@ program
             } catch (e) {}
         }
 
+        // Remove cross-model governance hooks (LED-202)
+        try {
+            const removedFrom = crossModelHooks.removeAllHooks();
+            if (removedFrom.length > 0) {
+                console.log(chalk.green(`✓ Removed governance hooks from: ${removedFrom.join(', ')}`));
+            }
+        } catch (e) { /* cross-model-hooks module not critical */ }
+
         console.log(chalk.green('\n  Delimit has been completely removed.'));
         console.log(chalk.gray(`  Backups saved to: ${backupDir}`));
         console.log(chalk.gray('  Your data in ~/.delimit/ has been preserved.'));
@@ -701,95 +740,86 @@ program
         await proxyAITool(tool, args);
     });
 
-// Hook handler (called by Git hooks)
-program
-    .command('hook <type>')
-    .description('Internal hook handler')
+// ---------------------------------------------------------------------------
+// LED-202: Cross-model hook commands
+// ---------------------------------------------------------------------------
 
-    .action(async (type) => {
-        await ensureAgent();
-        
-        // Gather context
-        const context = {
-            command: type,
-            pwd: process.cwd(),
-            gitBranch: 'unknown',
-            files: [],
-            diff: ''
-        };
-        
-        // Try to get Git info, but don't fail if not in repo
+const hookCmd = program
+    .command('hook <event> [tool_name]')
+    .description('Governance hook handler (session-start | pre-tool | pre-commit)')
+    .action(async (event, toolName) => {
         try {
-            context.gitBranch = execSync('git branch --show-current 2>/dev/null').toString().trim() || 'unknown';
-        } catch (e) {
-            // Not in a Git repo or Git not available
-            context.gitBranch = 'unknown';
-        }
-        
-        if (type === 'pre-commit') {
-            try {
-                context.files = execSync('git diff --cached --name-only 2>/dev/null').toString().split('\n').filter(f => f);
-                context.diff = execSync('git diff --cached 2>/dev/null').toString();
-            } catch (e) {
-                // Not in a Git repo or no staged changes
-                context.files = [];
-                context.diff = '';
-            }
-        } else if (type === 'pre-push') {
-            try {
-                // Get commits to be pushed
-                context.files = execSync('git diff --name-only @{upstream}...HEAD 2>/dev/null').toString().split('\n').filter(f => f);
-                context.diff = execSync('git diff @{upstream}...HEAD 2>/dev/null').toString();
-            } catch (e) {
-                // No upstream or not in repo
-                context.files = [];
-                context.diff = '';
-            }
-        }
-        
-        // Query agent for decision
-        const { data: decision } = await axios.post(`${AGENT_URL}/evaluate`, context);
-        
-        // Display decision
-        if (decision.message) {
-            const color = decision.action === 'block' ? chalk.red :
-                         decision.action === 'prompt' ? chalk.yellow :
-                         chalk.blue;
-            console.log(color(decision.message));
-        }
-        
-        // Handle the decision
-        if (decision.action === 'block') {
-            if (decision.requiresOverride) {
-                console.log(chalk.red('Action blocked. Cannot override in enforce mode.'));
-                process.exit(1);
-            } else {
-                const { override } = await inquirer.prompt([{
-                    type: 'confirm',
-                    name: 'override',
-                    message: 'Override and continue?',
-                    default: false
-                }]);
-                
-                if (!override) {
-                    process.exit(1);
-                }
+            switch (event) {
+                case 'session-start':
+                    await crossModelHooks.hookSessionStart();
+                    break;
+                case 'pre-tool':
+                    await crossModelHooks.hookPreTool(toolName || 'unknown');
+                    break;
+                case 'pre-commit':
+                    await crossModelHooks.hookPreCommit();
+                    break;
+                default:
+                    // Legacy: fall back to agent-based hook evaluation
+                    await ensureAgent();
+                    const context = {
+                        command: event,
+                        pwd: process.cwd(),
+                        gitBranch: 'unknown',
+                        files: [],
+                        diff: ''
+                    };
+                    try {
+                        context.gitBranch = execSync('git branch --show-current 2>/dev/null').toString().trim() || 'unknown';
+                    } catch (e) { context.gitBranch = 'unknown'; }
+
+                    if (event === 'pre-push') {
+                        try {
+                            context.files = execSync('git diff --name-only @{upstream}...HEAD 2>/dev/null').toString().split('\n').filter(f => f);
+                            context.diff = execSync('git diff @{upstream}...HEAD 2>/dev/null').toString();
+                        } catch (e) {
+                            context.files = [];
+                            context.diff = '';
+                        }
+                    }
+
+                    const { data: decision } = await axios.post(`${AGENT_URL}/evaluate`, context);
+                    if (decision.message) {
+                        const color = decision.action === 'block' ? chalk.red :
+                                     decision.action === 'prompt' ? chalk.yellow :
+                                     chalk.blue;
+                        console.log(color(decision.message));
+                    }
+                    if (decision.action === 'block') {
+                        if (decision.requiresOverride) {
+                            console.log(chalk.red('Action blocked. Cannot override in enforce mode.'));
+                            process.exit(1);
+                        } else {
+                            const { override } = await inquirer.prompt([{
+                                type: 'confirm',
+                                name: 'override',
+                                message: 'Override and continue?',
+                                default: false
+                            }]);
+                            if (!override) process.exit(1);
+                        }
+                    } else if (decision.action === 'prompt') {
+                        const { proceed } = await inquirer.prompt([{
+                            type: 'confirm',
+                            name: 'proceed',
+                            message: 'Continue with this action?',
+                            default: false
+                        }]);
+                        if (!proceed) process.exit(1);
+                    }
+                    process.exit(0);
             }
-        } else if (decision.action === 'prompt') {
-            const { proceed } = await inquirer.prompt([{
-                type: 'confirm',
-                name: 'proceed',
-                message: 'Continue with this action?',
-                default: false
-            }]);
-            
-            if (!proceed) {
-                process.exit(1);
+        } catch (err) {
+            // Hooks must never block the AI tool -- fail open
+            if (process.env.DELIMIT_DEBUG) {
+                process.stderr.write(`[Delimit] Hook error: ${err.message}\n`);
             }
         }
-        
-        // Action allowed
-        process.exit(0);
     });
 
 // ═══════════════════════════════════════════════════════════════════════
@@ -1135,6 +1165,7 @@ program
         console.log('');
         if (fail === 0 && warn === 0) {
             console.log(chalk.green.bold('  All checks passed! Ready to lint.\n'));
+            console.log('Keep Building.\n');
         } else if (fail === 0) {
             console.log(chalk.yellow.bold(`  ${ok} passed, ${warn} warning(s). Setup looks good.\n`));
         } else {
@@ -1263,6 +1294,10 @@ program
                 console.log('');
             }
 
+            if (decision === 'pass') {
+                console.log('Keep Building.\n');
+            }
+
             process.exit(result.exit_code || 0);
         } catch (err) {
             console.error(chalk.red(`Error: ${err.message}`));
@@ -1295,6 +1330,10 @@ program
                 console.log(`  ${tag} ${c.message}`);
             });
             console.log('');
+
+            if (result.breaking_changes === 0) {
+                console.log('Keep Building.\n');
+            }
         } catch (err) {
             console.error(chalk.red(`Error: ${err.message}`));
             process.exit(1);
@@ -1428,6 +1467,187 @@ program
         console.log(chalk.dim('Tier: pro'));
     });
 
+// ---------------------------------------------------------------------------
+// LED-187: Export governance config as shareable JSON
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a governance config bundle from the current project directory.
+ * Returns a plain object ready for JSON serialization.
+ */
+function buildConfigBundle(cwd) {
+    const bundle = {
+        delimit_config_version: 1,
+        created_at: new Date().toISOString(),
+        project: path.basename(cwd),
+        policies: null,
+        workflow: null,
+    };
+
+    // Read delimit.yml or .delimit/policies.yml
+    const candidates = [
+        path.join(cwd, 'delimit.yml'),
+        path.join(cwd, '.delimit.yml'),
+        path.join(cwd, '.delimit', 'policies.yml'),
+    ];
+    for (const p of candidates) {
+        if (fs.existsSync(p)) {
+            const raw = fs.readFileSync(p, 'utf-8');
+            bundle.policies = { path: path.relative(cwd, p), content: raw };
+            break;
+        }
+    }
+
+    // Read GitHub Action workflow if it exists
+    const workflowPath = path.join(cwd, '.github', 'workflows', 'api-governance.yml');
+    if (fs.existsSync(workflowPath)) {
+        bundle.workflow = {
+            path: '.github/workflows/api-governance.yml',
+            content: fs.readFileSync(workflowPath, 'utf-8'),
+        };
+    }
+
+    return bundle;
+}
+
+program
+    .command('export')
+    .description('Export governance config as shareable JSON')
+    .option('-o, --output <file>', 'Write to file instead of stdout')
+    .option('--url', 'Generate a delimit.ai/import share URL')
+    .action(async (options) => {
+        const cwd = process.cwd();
+        const bundle = buildConfigBundle(cwd);
+
+        if (!bundle.policies) {
+            console.error(chalk.red('No governance config found. Run "delimit init" first.'));
+            process.exit(1);
+        }
+
+        const json = JSON.stringify(bundle, null, 2);
+
+        if (options.url) {
+            const encoded = Buffer.from(json).toString('base64');
+            const shareUrl = `https://delimit.ai/import?config=${encoded}`;
+            console.log(chalk.green('Share URL:\n'));
+            console.log(shareUrl);
+            return;
+        }
+
+        if (options.output) {
+            fs.writeFileSync(options.output, json);
+            console.log(chalk.green(`Exported config to ${options.output}`));
+        } else {
+            console.log(json);
+        }
+    });
+
+// ---------------------------------------------------------------------------
+// LED-187: Import governance config from file, URL, or base64 string
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a config bundle from various sources: file path, base64 string,
+ * or a delimit.ai/import?config=... URL.
+ */
+function parseConfigSource(source) {
+    // URL form — extract base64 from query param
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        const url = new URL(source);
+        const encoded = url.searchParams.get('config');
+        if (!encoded) {
+            throw new Error('URL does not contain a config= parameter');
+        }
+        return JSON.parse(Buffer.from(encoded, 'base64').toString('utf-8'));
+    }
+
+    // File path
+    if (fs.existsSync(source)) {
+        return JSON.parse(fs.readFileSync(source, 'utf-8'));
+    }
+
+    // Assume base64
+    try {
+        return JSON.parse(Buffer.from(source, 'base64').toString('utf-8'));
+    } catch {
+        throw new Error('Could not parse source as file path, URL, or base64');
+    }
+}
+
+program
+    .command('import <source>')
+    .description('Import governance config from file, URL, or base64 string')
+    .option('--action', 'Also write the GitHub Action workflow')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(async (source, options) => {
+        let bundle;
+        try {
+            bundle = parseConfigSource(source);
+        } catch (err) {
+            console.error(chalk.red(`Failed to parse config: ${err.message}`));
+            process.exit(1);
+        }
+
+        if (!bundle.policies || !bundle.policies.content) {
+            console.error(chalk.red('Invalid config bundle: missing policies'));
+            process.exit(1);
+        }
+
+        const cwd = process.cwd();
+        const policyDest = path.join(cwd, bundle.policies.path || 'delimit.yml');
+
+        // Show what will change
+        console.log(chalk.blue.bold('\nConfig Import Preview\n'));
+        console.log(`  Project: ${chalk.bold(bundle.project || 'unknown')}`);
+        console.log(`  Created: ${bundle.created_at || 'unknown'}`);
+        console.log(`  Policy file: ${chalk.bold(policyDest)}`);
+        if (options.action && bundle.workflow) {
+            console.log(`  Workflow: ${chalk.bold(path.join(cwd, bundle.workflow.path))}`);
+        }
+
+        // Show diff if policy file already exists
+        if (fs.existsSync(policyDest)) {
+            const existing = fs.readFileSync(policyDest, 'utf-8');
+            if (existing === bundle.policies.content) {
+                console.log(chalk.yellow('\n  No changes -- imported config matches current config.'));
+                return;
+            }
+            console.log(chalk.yellow('\n  Policy file already exists and will be overwritten.'));
+        }
+
+        console.log('');
+
+        if (!options.yes) {
+            const { confirm } = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'confirm',
+                message: 'Apply this config?',
+                default: false,
+            }]);
+            if (!confirm) {
+                console.log(chalk.red('Import cancelled'));
+                return;
+            }
+        }
+
+        // Write policy file
+        const policyDir = path.dirname(policyDest);
+        fs.mkdirSync(policyDir, { recursive: true });
+        fs.writeFileSync(policyDest, bundle.policies.content);
+        console.log(chalk.green(`  Created ${policyDest}`));
+
+        // Optionally write workflow
+        if (options.action && bundle.workflow && bundle.workflow.content) {
+            const workflowDest = path.join(cwd, bundle.workflow.path);
+            const wfDir = path.dirname(workflowDest);
+            fs.mkdirSync(wfDir, { recursive: true });
+            fs.writeFileSync(workflowDest, bundle.workflow.content);
+            console.log(chalk.green(`  Created ${workflowDest}`));
+        }
+
+        console.log(chalk.green('\nConfig imported successfully.'));
+    });
+
 // Version subcommand alias (users type 'delimit version' not 'delimit -V')
 program
     .command('version')

package/bin/delimit-setup.js

@@ -567,8 +567,56 @@ echo "[Delimit] ${toolName} not found" >&2; exit 127
     }
     log('');
 
-    // Step 7: Local dashboard API server
-    step(7, 'Local dashboard API...');
+    // Step 7: Install cross-model governance hooks (LED-202)
+    step(7, 'Installing AI assistant hooks...');
+
+    try {
+        const crossModelHooks = require('../lib/cross-model-hooks');
+        const hookConfig = crossModelHooks.loadHookConfig();
+        const detected = crossModelHooks.detectAITools();
+
+        if (detected.length === 0) {
+            log(`  ${dim('  No AI assistants detected -- hooks will be installed when tools are found')}`);
+        } else {
+            log(`  ${dim('  Detected: ' + detected.map(t => t.name).join(', '))}`);
+
+            // Install hooks (auto-accept in non-interactive or prompt if TTY)
+            let installHooks = true;
+            const inq = (() => { try { return require('inquirer'); } catch { return null; } })();
+            if (inq && process.stdin.isTTY) {
+                try {
+                    const answer = await inq.prompt([{
+                        type: 'confirm',
+                        name: 'install',
+                        message: `Install governance hooks for ${detected.map(t => t.name).join(', ')}?`,
+                        default: true,
+                    }]);
+                    installHooks = answer.install;
+                } catch {
+                    installHooks = true;
+                }
+            }
+
+            if (installHooks) {
+                for (const tool of detected) {
+                    const result = crossModelHooks.installHooksForTool(tool, hookConfig);
+                    if (result.changes.length > 0) {
+                        log(`  ${green('✓')} ${tool.name}: ${result.changes.join(', ')}`);
+                    } else {
+                        log(`  ${dim('  ' + tool.name + ': hooks already installed')}`);
+                    }
+                }
+            } else {
+                log(`  ${dim('  Skipped. Install later: delimit hook install')}`);
+            }
+        }
+    } catch (e) {
+        log(`  ${dim('  Hook installation skipped: ' + e.message)}`);
+    }
+    log('');
+
+    // Step 8: Local dashboard API server
+    step(8, 'Local dashboard API...');
 
     const localServerPath = path.join(DELIMIT_HOME, 'server', 'ai', 'local_server.py');
     if (fs.existsSync(localServerPath)) {
@@ -580,8 +628,8 @@ echo "[Delimit] ${toolName} not found" >&2; exit 127
     }
     log('');
 
-    // Step 8: Post-install config validation (LED-098)
-    step(8, 'Validating config integrity...');
+    // Step 9: Post-install config validation (LED-098)
+    step(9, 'Validating config integrity...');
 
     let validationIssues = 0;
     const configFiles = [
@@ -670,7 +718,7 @@ echo "[Delimit] ${toolName} not found" >&2; exit 127
     log('');
 
     // Step 9: Done
-    step(9, 'Done!');
+    step(10, 'Done!');
     log('');
     log(`  ${green('Delimit is installed.')} Your AI now has persistent memory and governance.`);
     log('');

package/lib/cross-model-hooks.js

@@ -0,0 +1,706 @@
+#!/usr/bin/env node
+
+/**
+ * LED-202: Cross-Model Hook System
+ *
+ * Detects installed AI coding assistants (Claude Code, Codex, Gemini CLI)
+ * and installs Delimit governance hooks into each one's native config format.
+ *
+ * Hook commands:
+ *   delimit hook session-start   -- ledger context + gov health
+ *   delimit hook pre-tool <name> -- lint/test checks before edits
+ *   delimit hook pre-commit      -- repo diagnostics before commits
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const os = require('os');
+
+// Use process.env.HOME to allow test overrides; fall back to os.homedir()
+function getHome() { return process.env.HOME || os.homedir(); }
+function getDelimitHome() { return path.join(getHome(), '.delimit'); }
+
+// ---------------------------------------------------------------------------
+// Hook configuration (user-overridable via delimit.yml)
+// ---------------------------------------------------------------------------
+
+function loadHookConfig() {
+    const defaults = {
+        session_start: true,
+        pre_tool: true,
+        pre_commit: true,
+        deliberate_on_commit: false,
+        show_strategy_items: true,
+    };
+
+    // Check project-level delimit.yml, then global
+    const candidates = [
+        path.join(process.cwd(), 'delimit.yml'),
+        path.join(process.cwd(), '.delimit.yml'),
+        path.join(getDelimitHome(), 'delimit.yml'),
+    ];
+
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) {
+            try {
+                const yaml = require('js-yaml');
+                const doc = yaml.load(fs.readFileSync(candidate, 'utf-8'));
+                if (doc && doc.hooks) {
+                    return { ...defaults, ...doc.hooks };
+                }
+            } catch { /* ignore parse errors */ }
+        }
+    }
+    return defaults;
+}
+
+// ---------------------------------------------------------------------------
+// AI tool detection
+// ---------------------------------------------------------------------------
+
+function detectAITools() {
+    const detected = [];
+
+    // Claude Code
+    const claudeSettings = path.join(getHome(), '.claude', 'settings.json');
+    const claudeSettingsLocal = path.join(getHome(), '.claude', 'settings.local.json');
+    let hasClaude = fs.existsSync(claudeSettings) || fs.existsSync(claudeSettingsLocal);
+    if (!hasClaude) {
+        try {
+            execSync('claude --version 2>/dev/null', { stdio: 'pipe' });
+            hasClaude = true;
+        } catch { /* not installed */ }
+    }
+    if (hasClaude) {
+        detected.push({
+            id: 'claude',
+            name: 'Claude Code',
+            configPath: claudeSettings,
+            format: 'claude-hooks',
+        });
+    }
+
+    // Codex CLI
+    const codexDir = path.join(getHome(), '.codex');
+    let hasCodex = fs.existsSync(codexDir);
+    if (!hasCodex) {
+        try {
+            execSync('codex --version 2>/dev/null', { stdio: 'pipe' });
+            hasCodex = true;
+        } catch { /* not installed */ }
+    }
+    if (hasCodex) {
+        detected.push({
+            id: 'codex',
+            name: 'Codex CLI',
+            configPath: path.join(codexDir, 'config.json'),
+            instructionsPath: path.join(codexDir, 'instructions.md'),
+            format: 'codex',
+        });
+    }
+
+    // Gemini CLI
+    const geminiDir = path.join(getHome(), '.gemini');
+    let hasGemini = fs.existsSync(geminiDir);
+    if (!hasGemini) {
+        try {
+            execSync('gemini --version 2>/dev/null', { stdio: 'pipe' });
+            hasGemini = true;
+        } catch { /* not installed */ }
+    }
+    if (hasGemini) {
+        detected.push({
+            id: 'gemini',
+            name: 'Gemini CLI',
+            configPath: path.join(geminiDir, 'settings.json'),
+            format: 'gemini-mcp',
+        });
+    }
+
+    return detected;
+}
+
+// ---------------------------------------------------------------------------
+// Hook installers per tool
+// ---------------------------------------------------------------------------
+
+/**
+ * Install hooks into Claude Code's ~/.claude/settings.json
+ * Claude Code supports native hooks: SessionStart, PreToolUse, PostToolUse, etc.
+ */
+function installClaudeHooks(tool, hookConfig) {
+    const configPath = tool.configPath;
+    const configDir = path.dirname(configPath);
+    fs.mkdirSync(configDir, { recursive: true });
+
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        } catch { config = {}; }
+    }
+
+    if (!config.hooks) {
+        config.hooks = {};
+    }
+
+    const npxCmd = 'npx delimit-cli';
+    const changes = [];
+
+    // SessionStart hook
+    if (hookConfig.session_start) {
+        const sessionHook = {
+            type: 'command',
+            command: `${npxCmd} hook session-start`,
+        };
+        if (!config.hooks.SessionStart) {
+            config.hooks.SessionStart = [];
+        }
+        // Check if already installed
+        const existing = config.hooks.SessionStart.find(
+            h => h.command && h.command.includes('delimit-cli hook session-start')
+        );
+        if (!existing) {
+            config.hooks.SessionStart.push(sessionHook);
+            changes.push('SessionStart');
+        }
+    }
+
+    // PreToolUse hook for file edits
+    if (hookConfig.pre_tool) {
+        const preToolHook = {
+            type: 'command',
+            command: `${npxCmd} hook pre-tool`,
+            matcher: 'Edit|Write|Bash',
+        };
+        if (!config.hooks.PreToolUse) {
+            config.hooks.PreToolUse = [];
+        }
+        const existing = config.hooks.PreToolUse.find(
+            h => h.command && h.command.includes('delimit-cli hook pre-tool')
+        );
+        if (!existing) {
+            config.hooks.PreToolUse.push(preToolHook);
+            changes.push('PreToolUse');
+        }
+    }
+
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    return changes;
+}
+
+/**
+ * Install hooks for Codex CLI.
+ * Codex uses instructions.md for session-start equivalent and config.json for settings.
+ * We add governance instructions and a pre-commit hook reference.
+ */
+function installCodexHooks(tool, hookConfig) {
+    const changes = [];
+    const codexDir = path.dirname(tool.configPath);
+    fs.mkdirSync(codexDir, { recursive: true });
+
+    // Codex instructions.md -- acts as the session-start equivalent
+    if (hookConfig.session_start) {
+        const instructionsPath = tool.instructionsPath || path.join(codexDir, 'instructions.md');
+        const delimitBlock = `<!-- delimit:hooks-start -->
+## Delimit Governance
+
+On every session start, run this command to check governance status:
+\`\`\`
+npx delimit-cli hook session-start
+\`\`\`
+
+Before committing changes, run:
+\`\`\`
+npx delimit-cli hook pre-commit
+\`\`\`
+
+After editing OpenAPI specs, run:
+\`\`\`
+npx delimit-cli hook pre-tool Edit
+\`\`\`
+<!-- delimit:hooks-end -->`;
+
+        let content = '';
+        if (fs.existsSync(instructionsPath)) {
+            content = fs.readFileSync(instructionsPath, 'utf-8');
+        }
+
+        if (content.includes('delimit:hooks-start')) {
+            // Replace existing block
+            content = content.replace(
+                /<!-- delimit:hooks-start -->[\s\S]*?<!-- delimit:hooks-end -->/,
+                delimitBlock
+            );
+        } else {
+            content = content ? content + '\n\n' + delimitBlock : delimitBlock;
+        }
+
+        fs.writeFileSync(instructionsPath, content);
+        changes.push('instructions.md');
+    }
+
+    // Codex config.json -- add hook commands
+    let config = {};
+    if (fs.existsSync(tool.configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(tool.configPath, 'utf-8'));
+        } catch { config = {}; }
+    }
+
+    if (!config.hooks) {
+        config.hooks = {};
+    }
+
+    if (hookConfig.pre_commit && !config.hooks['pre-commit']) {
+        config.hooks['pre-commit'] = 'npx delimit-cli hook pre-commit';
+        changes.push('pre-commit hook');
+    }
+
+    fs.writeFileSync(tool.configPath, JSON.stringify(config, null, 2));
+    return changes;
+}
+
+/**
+ * Install hooks for Gemini CLI.
+ * Gemini CLI uses MCP (already handled by setup) but we add governance
+ * instructions to settings.json and a GEMINI.md equivalent.
+ */
+function installGeminiHooks(tool, hookConfig) {
+    const changes = [];
+    const geminiDir = path.dirname(tool.configPath);
+    fs.mkdirSync(geminiDir, { recursive: true });
+
+    // Update settings.json with custom instructions
+    let config = {};
+    if (fs.existsSync(tool.configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(tool.configPath, 'utf-8'));
+        } catch { config = {}; }
+    }
+
+    const govInstructions = [
+        'Delimit governance is active.',
+        'On session start, run: npx delimit-cli hook session-start',
+        'Before committing, run: npx delimit-cli hook pre-commit',
+        'After editing API specs, run: npx delimit-cli hook pre-tool Edit',
+        'Call delimit_ledger_context and delimit_gov_health via MCP when available.',
+    ].join(' ');
+
+    if (!config.customInstructions || !config.customInstructions.includes('delimit-cli hook')) {
+        config.customInstructions = govInstructions;
+        changes.push('customInstructions');
+    }
+
+    fs.writeFileSync(tool.configPath, JSON.stringify(config, null, 2));
+
+    // Write a GEMINI.md governance file (equivalent of CLAUDE.md)
+    const geminiMd = path.join(geminiDir, 'GEMINI.md');
+    if (!fs.existsSync(geminiMd) || !fs.readFileSync(geminiMd, 'utf-8').includes('delimit')) {
+        const content = `# Delimit Governance
+
+On every session start:
+1. Run \`npx delimit-cli hook session-start\` to check open tasks and governance status
+
+After editing code:
+- After editing API specs: run \`npx delimit-cli hook pre-tool Edit\`
+- After editing tests: run \`npx delimit-cli hook pre-tool Edit\`
+
+Before committing:
+- Run \`npx delimit-cli hook pre-commit\` to check for issues
+`;
+        fs.writeFileSync(geminiMd, content);
+        changes.push('GEMINI.md');
+    }
+
+    return changes;
+}
+
+/**
+ * Install hooks for a detected tool.
+ * Returns { tool, changes } describing what was installed.
+ */
+function installHooksForTool(tool, hookConfig) {
+    switch (tool.id) {
+        case 'claude':
+            return { tool, changes: installClaudeHooks(tool, hookConfig) };
+        case 'codex':
+            return { tool, changes: installCodexHooks(tool, hookConfig) };
+        case 'gemini':
+            return { tool, changes: installGeminiHooks(tool, hookConfig) };
+        default:
+            return { tool, changes: [] };
+    }
+}
+
+/**
+ * Install hooks for all detected AI tools.
+ */
+function installAllHooks(hookConfig) {
+    const tools = detectAITools();
+    const results = [];
+    for (const tool of tools) {
+        results.push(installHooksForTool(tool, hookConfig));
+    }
+    return { tools, results };
+}
+
+// ---------------------------------------------------------------------------
+// Hook removal (for uninstall)
+// ---------------------------------------------------------------------------
+
+function removeClaudeHooks() {
+    const configPath = path.join(getHome(), '.claude', 'settings.json');
+    if (!fs.existsSync(configPath)) return false;
+
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        if (!config.hooks) return false;
+
+        let changed = false;
+
+        for (const event of ['SessionStart', 'PreToolUse', 'PostToolUse']) {
+            if (Array.isArray(config.hooks[event])) {
+                const before = config.hooks[event].length;
+                config.hooks[event] = config.hooks[event].filter(
+                    h => !(h.command && h.command.includes('delimit-cli'))
+                );
+                if (config.hooks[event].length === 0) {
+                    delete config.hooks[event];
+                }
+                if (config.hooks[event] === undefined || config.hooks[event].length < before) {
+                    changed = true;
+                }
+            }
+        }
+
+        if (Object.keys(config.hooks).length === 0) {
+            delete config.hooks;
+        }
+
+        if (changed) {
+            fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+        }
+        return changed;
+    } catch {
+        return false;
+    }
+}
+
+function removeCodexHooks() {
+    let changed = false;
+
+    // Remove from instructions.md
+    const instructionsPath = path.join(getHome(), '.codex', 'instructions.md');
+    if (fs.existsSync(instructionsPath)) {
+        let content = fs.readFileSync(instructionsPath, 'utf-8');
+        if (content.includes('delimit:hooks-start')) {
+            content = content.replace(
+                /\n*<!-- delimit:hooks-start -->[\s\S]*?<!-- delimit:hooks-end -->\n*/,
+                ''
+            );
+            fs.writeFileSync(instructionsPath, content);
+            changed = true;
+        }
+    }
+
+    // Remove hooks from config.json
+    const configPath = path.join(getHome(), '.codex', 'config.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (config.hooks) {
+                for (const [key, val] of Object.entries(config.hooks)) {
+                    if (typeof val === 'string' && val.includes('delimit-cli')) {
+                        delete config.hooks[key];
+                        changed = true;
+                    }
+                }
+                if (Object.keys(config.hooks).length === 0) {
+                    delete config.hooks;
+                }
+                if (changed) {
+                    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+                }
+            }
+        } catch { /* ignore */ }
+    }
+
+    return changed;
+}
+
+function removeGeminiHooks() {
+    let changed = false;
+
+    // Remove custom instructions referencing delimit
+    const configPath = path.join(getHome(), '.gemini', 'settings.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (config.customInstructions && config.customInstructions.includes('delimit-cli hook')) {
+                delete config.customInstructions;
+                fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+                changed = true;
+            }
+        } catch { /* ignore */ }
+    }
+
+    // Remove GEMINI.md if it's ours
+    const geminiMd = path.join(getHome(), '.gemini', 'GEMINI.md');
+    if (fs.existsSync(geminiMd)) {
+        const content = fs.readFileSync(geminiMd, 'utf-8');
+        if (content.includes('Delimit Governance')) {
+            fs.unlinkSync(geminiMd);
+            changed = true;
+        }
+    }
+
+    return changed;
+}
+
+function removeAllHooks() {
+    const results = [];
+
+    if (removeClaudeHooks()) {
+        results.push('Claude Code');
+    }
+    if (removeCodexHooks()) {
+        results.push('Codex CLI');
+    }
+    if (removeGeminiHooks()) {
+        results.push('Gemini CLI');
+    }
+
+    return results;
+}
+
+// ---------------------------------------------------------------------------
+// Hook execution commands
+// ---------------------------------------------------------------------------
+
+/**
+ * session-start: Show ledger context and governance health.
+ * Output goes to stdout for the AI tool to read.
+ */
+async function hookSessionStart() {
+    const config = loadHookConfig();
+    if (!config.session_start) {
+        return;
+    }
+
+    const lines = [];
+    lines.push('[Delimit] Governance check');
+    lines.push('');
+
+    // Check for delimit.yml or .delimit.yml
+    const cwd = process.cwd();
+    const hasPolicy = fs.existsSync(path.join(cwd, 'delimit.yml'))
+        || fs.existsSync(path.join(cwd, '.delimit.yml'))
+        || fs.existsSync(path.join(cwd, '.delimit', 'policies.yml'));
+
+    if (hasPolicy) {
+        lines.push('[Delimit] Policy file found -- governance active');
+    } else {
+        lines.push('[Delimit] No policy file found -- run "delimit init" to set up governance');
+    }
+
+    // Check for OpenAPI specs
+    const specPatterns = ['openapi.yaml', 'openapi.yml', 'openapi.json', 'swagger.yaml', 'swagger.json'];
+    const foundSpecs = [];
+    for (const pattern of specPatterns) {
+        const specPath = path.join(cwd, pattern);
+        if (fs.existsSync(specPath)) {
+            foundSpecs.push(pattern);
+        }
+    }
+    // Also check api/ and specs/ directories
+    for (const dir of ['api', 'specs', 'spec']) {
+        const dirPath = path.join(cwd, dir);
+        if (fs.existsSync(dirPath)) {
+            try {
+                const files = fs.readdirSync(dirPath);
+                for (const f of files) {
+                    if (/\.(yaml|yml|json)$/.test(f) && /openapi|swagger/i.test(f)) {
+                        foundSpecs.push(path.join(dir, f));
+                    }
+                }
+            } catch { /* ignore */ }
+        }
+    }
+
+    if (foundSpecs.length > 0) {
+        lines.push(`[Delimit] OpenAPI specs detected: ${foundSpecs.join(', ')}`);
+    }
+
+    // Check ledger
+    const ledgerDir = path.join(getDelimitHome(), 'ledger');
+    if (fs.existsSync(ledgerDir)) {
+        try {
+            const ledgerFiles = fs.readdirSync(ledgerDir).filter(f => f.endsWith('.json'));
+            let openItems = 0;
+            for (const f of ledgerFiles) {
+                try {
+                    const items = JSON.parse(fs.readFileSync(path.join(ledgerDir, f), 'utf-8'));
+                    if (Array.isArray(items)) {
+                        openItems += items.filter(i => i.status === 'open' || i.status === 'in_progress').length;
+                    }
+                } catch { /* ignore */ }
+            }
+            if (openItems > 0) {
+                lines.push(`[Delimit] Ledger: ${openItems} open item(s)`);
+            } else {
+                lines.push('[Delimit] Ledger: no open items');
+            }
+        } catch {
+            lines.push('[Delimit] Ledger: empty');
+        }
+    }
+
+    // Git branch info
+    try {
+        const branch = execSync('git branch --show-current 2>/dev/null', { encoding: 'utf-8' }).trim();
+        if (branch) {
+            lines.push(`[Delimit] Branch: ${branch}`);
+        }
+    } catch { /* not in git repo */ }
+
+    lines.push('');
+    process.stdout.write(lines.join('\n') + '\n');
+}
+
+/**
+ * pre-tool: Check before file edits.
+ * If editing an OpenAPI spec, run a quick lint.
+ * If editing a test file, note it.
+ */
+async function hookPreTool(toolName) {
+    const config = loadHookConfig();
+    if (!config.pre_tool) {
+        return;
+    }
+
+    // The tool name comes from the AI tool (e.g., "Edit", "Write", "Bash")
+    // We check the DELIMIT_TOOL_INPUT env or just do lightweight checks
+    const cwd = process.cwd();
+
+    // Check if there are staged OpenAPI spec changes
+    try {
+        const stagedFiles = execSync('git diff --cached --name-only 2>/dev/null', {
+            encoding: 'utf-8',
+            timeout: 2000,
+        }).split('\n').filter(Boolean);
+
+        const specFiles = stagedFiles.filter(f =>
+            /openapi|swagger/i.test(f) && /\.(yaml|yml|json)$/.test(f)
+        );
+
+        if (specFiles.length > 0) {
+            process.stderr.write(`[Delimit] Warning: OpenAPI spec(s) staged for commit: ${specFiles.join(', ')}\n`);
+            process.stderr.write('[Delimit] Run "delimit lint" before committing to check for breaking changes.\n');
+        }
+
+        const testFiles = stagedFiles.filter(f =>
+            /\.(test|spec)\.(js|ts|py|rb)$/.test(f) || /test_.*\.py$/.test(f)
+        );
+
+        if (testFiles.length > 0) {
+            process.stderr.write(`[Delimit] Test files staged: ${testFiles.join(', ')}\n`);
+            process.stderr.write('[Delimit] Consider running tests before committing.\n');
+        }
+    } catch {
+        // Not in a git repo or no staged changes -- that is fine
+    }
+}
+
+/**
+ * pre-commit: Run repo diagnostics before committing.
+ */
+async function hookPreCommit() {
+    const config = loadHookConfig();
+    if (!config.pre_commit) {
+        return;
+    }
+
+    const cwd = process.cwd();
+    const warnings = [];
+
+    // Check for staged OpenAPI spec changes
+    try {
+        const stagedFiles = execSync('git diff --cached --name-only 2>/dev/null', {
+            encoding: 'utf-8',
+            timeout: 2000,
+        }).split('\n').filter(Boolean);
+
+        const specFiles = stagedFiles.filter(f =>
+            /openapi|swagger/i.test(f) && /\.(yaml|yml|json)$/.test(f)
+        );
+
+        if (specFiles.length > 0) {
+            // Try to find a previous version to diff against
+            for (const specFile of specFiles) {
+                try {
+                    // Get the HEAD version
+                    const oldContent = execSync(`git show HEAD:${specFile} 2>/dev/null`, {
+                        encoding: 'utf-8',
+                        timeout: 3000,
+                    });
+                    if (oldContent) {
+                        warnings.push(`[Delimit] OpenAPI spec changed: ${specFile}`);
+                        warnings.push('[Delimit] Run "delimit diff <old> <new>" to review API changes before committing.');
+                    }
+                } catch {
+                    // New file, no previous version
+                }
+            }
+        }
+
+        // Check for secrets patterns in staged files
+        const sensitivePatterns = [
+            /password\s*[:=]\s*['"][^'"]+['"]/i,
+            /api[_-]?key\s*[:=]\s*['"][^'"]+['"]/i,
+            /secret\s*[:=]\s*['"][^'"]+['"]/i,
+        ];
+
+        for (const file of stagedFiles) {
+            if (/\.(env|key|pem|p12|pfx)$/.test(file)) {
+                warnings.push(`[Delimit] WARNING: Potentially sensitive file staged: ${file}`);
+            }
+        }
+    } catch {
+        // Not in git repo
+    }
+
+    // Check for policy file
+    const hasPolicy = fs.existsSync(path.join(cwd, 'delimit.yml'))
+        || fs.existsSync(path.join(cwd, '.delimit.yml'));
+
+    if (!hasPolicy) {
+        warnings.push('[Delimit] No governance policy found. Run "delimit init" to create one.');
+    }
+
+    if (warnings.length > 0) {
+        process.stderr.write(warnings.join('\n') + '\n');
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+    detectAITools,
+    installHooksForTool,
+    installAllHooks,
+    installClaudeHooks,
+    installCodexHooks,
+    installGeminiHooks,
+    removeAllHooks,
+    removeClaudeHooks,
+    removeCodexHooks,
+    removeGeminiHooks,
+    loadHookConfig,
+    hookSessionStart,
+    hookPreTool,
+    hookPreCommit,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "delimit-cli",
   "mcpName": "io.github.delimit-ai/delimit-mcp-server",
-  "version": "3.11.11",
+  "version": "3.12.0",
   "description": "Unify Claude Code, Codex, Cursor, and Gemini CLI with persistent context, governance, and multi-model debate.",
   "main": "index.js",
   "files": [
@@ -20,7 +20,7 @@
   },
   "scripts": {
     "postinstall": "echo '\\nRun: npx delimit-cli setup\\n'",
-    "test": "node --test tests/setup-onboarding.test.js tests/setup-matrix.test.js"
+    "test": "node --test tests/setup-onboarding.test.js tests/setup-matrix.test.js tests/config-export-import.test.js tests/cross-model-hooks.test.js"
   },
   "keywords": [
     "openapi",