Fix Codex hook compatibility and quiet advisory warnings

Author: carlkibler

bin/tl-hook.mjs

@@ -124,15 +124,21 @@ function loadSeen(p) {
   } catch { return {}; }
 }
 
-function nudgeOnce(key, message, ttl = NUDGE_TTL_MS) {
+function codexWarningsEnabled() {
+  const value = (process.env.TOKENLEAN_CODEX_WARNINGS || '').toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes' || value === 'on';
+}
+
+function nudgeOnce(key, message, ttl = NUDGE_TTL_MS, format = 'claude') {
+  if (format === 'codex' && !codexWarningsEnabled()) return;
   const p = getSeenPath();
   if (p) {
     const seen = loadSeen(p);
     if (seen[key] && (Date.now() - seen[key]) < ttl) return;
     seen[key] = Date.now();
     writeFileSync(p, JSON.stringify(seen), 'utf8');
   }
-  console.log(makeNudge(message));
+  console.log(makeNudge(message, format));
 }
 
 // --- Hook runner ---
@@ -154,13 +160,21 @@ function detectHookFormat(data) {
   if (process.env.PI_CODING_AGENT) return 'pi';
   if (process.env.CLAUDE_CONFIG_DIR || process.env.CLAUDE_PROJECT_DIR) return 'claude';
   if (process.env.CODEX_THREAD_ID || process.env.CODEX_CI) return 'codex';
+  if (data?.hook_event_name && data?.turn_id && data?.permission_mode && data?.session_id) {
+    return 'codex';
+  }
   // Detect codex from payload transcript path when env vars aren't set
   if (data?.transcript_path?.includes('/.codex/')) return 'codex';
   return 'claude';
 }
 
-function makeNudge(message) {
-  // Both Claude Code and Codex use the same hookSpecificOutput format
+function makeNudge(message, format = 'claude') {
+  if (format === 'codex') {
+    return JSON.stringify({
+      systemMessage: message,
+    });
+  }
+
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
@@ -232,6 +246,7 @@ async function runHook() {
   const format = detectHookFormat(data);
   const toolName = data.tool_name;
   const toolInput = data.tool_input || {};
+  const nudge = (key, message, ttl = NUDGE_TTL_MS) => nudgeOnce(key, message, ttl, format);
 
   // --- Read on large files ---
   if (toolName === 'Read') {
@@ -245,15 +260,15 @@ async function runHook() {
 
     // Large JSON/YAML — worth flagging even though they're data files
     if (size > LARGE_JSON_BYTES && (ext === 'json' || ext === 'yaml' || ext === 'yml')) {
-      nudgeOnce('read-large-json', `[tl] ${Math.round(size / 1024)}KB ${ext} — use -j flag or tl-snippet to extract a specific path`, TTL_HIGH);
+      nudge('read-large-json', `[tl] ${Math.round(size / 1024)}KB ${ext} — use -j flag or tl-snippet to extract a specific path`, TTL_HIGH);
       return;
     }
 
     if (NON_CODE_EXTS.has(ext)) return;
 
     if (size > LARGE_FILE_BYTES) {
       const savedKb = Math.round(size * 0.85 / 1024);
-      nudgeOnce('read-large', `[tl] ${Math.round(size / 1024)}KB — tl-symbols + tl-snippet saves ~${savedKb}KB`, TTL_HIGH);
+      nudge('read-large', `[tl] ${Math.round(size / 1024)}KB — tl-symbols + tl-snippet saves ~${savedKb}KB`, TTL_HIGH);
     }
     return;
   }
@@ -267,34 +282,34 @@ async function runHook() {
 
     // Build/test commands
     if (BUILD_TEST_PATTERNS.some(p => p.test(cmd))) {
-      nudgeOnce('bash-test', `[tl] wrap with tl-run`, TTL_LOW);
+      nudge('bash-test', `[tl] wrap with tl-run`, TTL_LOW);
       return;
     }
 
     // Tail commands
     if (TAIL_PATTERNS.some(p => p.test(cmd))) {
-      nudgeOnce('bash-tail', `[tl] use tl-tail instead`, TTL_LOW);
+      nudge('bash-tail', `[tl] use tl-tail instead`, TTL_LOW);
       return;
     }
 
     // grep/rg/ag — nudge to built-in search tool
     if (/^\s*(grep|rg|ag)\s/.test(cmd)) {
       const grepTool = format === 'pi' ? 'grep tool' : 'Grep tool';
-      nudgeOnce('bash-grep', `[tl] use ${grepTool}, not bash`, TTL_MEDIUM);
+      nudge('bash-grep', `[tl] use ${grepTool}, not bash`, TTL_MEDIUM);
       return;
     }
 
     // head — nudge to Read with limit
     if (/^\s*head\s/.test(cmd)) {
       const readTool = format === 'pi' ? 'read tool' : 'Read tool';
-      nudgeOnce('bash-head', `[tl] use ${readTool} with offset/limit`, TTL_MEDIUM);
+      nudge('bash-head', `[tl] use ${readTool} with offset/limit`, TTL_MEDIUM);
       return;
     }
 
     // Writes via bash (heredocs, redirects) — nudge to Write tool
     if (WRITE_VIA_BASH_PATTERNS.some(p => p.test(cmd))) {
       const writeTool = format === 'pi' ? 'write tool' : 'Write tool';
-      nudgeOnce('bash-write', `[tl] use ${writeTool} instead of writing via bash`, TTL_MEDIUM);
+      nudge('bash-write', `[tl] use ${writeTool} instead of writing via bash`, TTL_MEDIUM);
       return;
     }
 
@@ -308,39 +323,39 @@ async function runHook() {
       if (fp && !fp.startsWith('-')) {
         try { sizeHint = ` (${Math.round(statSync(fp).size / 1024)}KB)`; } catch {}
       }
-      nudgeOnce('bash-cat', `[tl] use ${readTool}${sizeHint}, not cat`, TTL_HIGH);
+      nudge('bash-cat', `[tl] use ${readTool}${sizeHint}, not cat`, TTL_HIGH);
       return;
     }
 
     // find/fd — nudge to Glob/find tool
     if (/^\s*(find|fd)\s/.test(cmd)) {
       const findTool = format === 'pi' ? 'find tool' : 'Glob tool';
-      nudgeOnce('bash-find', `[tl] use ${findTool}, not bash`, TTL_MEDIUM);
+      nudge('bash-find', `[tl] use ${findTool}, not bash`, TTL_MEDIUM);
       return;
     }
 
     // ls -R / ls -la / tree — verbose directory listing
     if (LS_TREE_PATTERNS.some(p => p.test(cmd))) {
-      nudgeOnce('bash-ls-tree', `[tl] use tl-structure or Glob for directory exploration`, TTL_MEDIUM);
+      nudge('bash-ls-tree', `[tl] use tl-structure or Glob for directory exploration`, TTL_MEDIUM);
       return;
     }
 
     // git log / git diff / git show without truncation
     if (GIT_VERBOSE_PATTERNS.some(p => p.test(cmd))) {
-      nudgeOnce('bash-git-verbose', `[tl] use tl-diff or tl-history for token-efficient git output`, TTL_MEDIUM);
+      nudge('bash-git-verbose', `[tl] use tl-diff or tl-history for token-efficient git output`, TTL_MEDIUM);
       return;
     }
 
     // sed -i / awk > file — in-place edits via bash
     if (SED_AWK_EDIT_PATTERNS.some(p => p.test(cmd))) {
       const editTool = format === 'pi' ? 'edit tool' : 'Edit tool';
-      nudgeOnce('bash-sed-awk', `[tl] use ${editTool} for targeted edits`, TTL_MEDIUM);
+      nudge('bash-sed-awk', `[tl] use ${editTool} for targeted edits`, TTL_MEDIUM);
       return;
     }
 
     // curl on URLs (skip API calls with -X, -d, --data, -H with auth)
     if (/^\s*curl\s/.test(cmd) && !/(-X\s|--data|--header.*auth|-d\s)/i.test(cmd)) {
-      nudgeOnce('bash-curl', `[tl] use tl-browse instead`, TTL_HIGH);
+      nudge('bash-curl', `[tl] use tl-browse instead`, TTL_HIGH);
       return;
     }
   }
@@ -349,7 +364,7 @@ async function runHook() {
   if (toolName === 'WebFetch') {
     const url = toolInput.url || '';
     if (url) {
-      nudgeOnce('webfetch', `[tl] use tl-browse instead`, TTL_HIGH);
+      nudge('webfetch', `[tl] use tl-browse instead`, TTL_HIGH);
     }
     return;
   }

src/tl-hook.test.mjs

@@ -0,0 +1,74 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '..');
+
+function runHook(payload, env = {}) {
+  return spawnSync(process.execPath, ['bin/tl-hook.mjs', 'run'], {
+    cwd: repoRoot,
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      ...env,
+    },
+  });
+}
+
+describe('tl-hook codex compatibility', () => {
+  it('stays silent for Codex advisory nudges by default', () => {
+    const result = runHook({
+      session_id: 's1',
+      turn_id: 't1',
+      permission_mode: 'default',
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Bash',
+      tool_input: { command: 'rg foo .' },
+      tool_use_id: 'u1',
+    });
+
+    assert.strictEqual(result.status, 0);
+    assert.strictEqual(result.stdout.trim(), '');
+  });
+
+  it('can emit Codex systemMessage nudges when explicitly enabled', () => {
+    const result = runHook({
+      session_id: 's1',
+      turn_id: 't1',
+      permission_mode: 'default',
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Bash',
+      tool_input: { command: 'rg foo .' },
+      tool_use_id: 'u1',
+    }, {
+      TOKENLEAN_CODEX_WARNINGS: '1',
+    });
+
+    assert.strictEqual(result.status, 0);
+    assert.deepStrictEqual(JSON.parse(result.stdout), {
+      systemMessage: '[tl] use Grep tool, not bash',
+    });
+  });
+
+  it('preserves Claude hookSpecificOutput nudges', () => {
+    const result = runHook({
+      tool_name: 'Bash',
+      tool_input: { command: 'rg foo .' },
+    }, {
+      TOKENLEAN_HOOK_FORMAT: 'claude',
+    });
+
+    assert.strictEqual(result.status, 0);
+    assert.deepStrictEqual(JSON.parse(result.stdout), {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        permissionDecisionReason: '[tl] use Grep tool, not bash',
+      },
+    });
+  });
+});