tackbox 0.1.98 → 0.1.99

package/README.md

@@ -646,6 +646,44 @@ failure is unverified, not a no-op.
 `uvx tackbox hook` runs the cached tackbox (no `@latest`): the hook is
 fast in-loop feedback, not the authoritative gate.
 
+### Codex
+
+Codex exposes its canonical file mutation as `apply_patch`. Wire the npm
+adapter once, globally, in `~/.codex/hooks.json`:
+
+Install the adapter once so hook execution does not depend on registry access:
+
+```bash
+npm install --global tackbox@latest
+```
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {"matcher": "apply_patch",
+       "hooks": [{"type": "command",
+                  "command": "tackbox-codex-hook"}]}
+    ],
+    "PostToolUse": [
+      {"matcher": "apply_patch",
+       "hooks": [{"type": "command",
+                  "command": "tackbox-codex-hook",
+                  "timeout": 120}]}
+    ]
+  }
+}
+```
+
+The adapter converts Codex's patch payload to `tackbox hook-protocol` and pins
+the Python wheel to the resolved npm package version. Codex does not support an
+`ask` decision from `PreToolUse`; an approval-gated edit therefore blocks with
+the reason instead of approving itself. Make that change in an interactive host
+that supports the prompt.
+Before a patch, any non-allow decision blocks. After a patch, verified findings
+replace the tool result; an unverified decision adds model-visible context that
+the mutation may already have landed and must not be repeated.
+
 ### Oh My Pi
 
 ```bash

package/bin/tackbox-codex-hook.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+'use strict'
+
+function fatal(error) {
+  process.exitCode = 2
+  process.stderr.write(`tackbox Codex hook: ${String((error && error.stack) || error)}\n`)
+}
+
+process.once('uncaughtException', fatal)
+process.once('unhandledRejection', fatal)
+require('../js/codex/hook').main()

package/js/codex/hook.js

@@ -0,0 +1,131 @@
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const manifest = require('../../package.json')
+const protocol = require('../omp/hook')
+const payload = require('../omp/payload')
+
+const PRE = 'PreToolUse'
+const POST = 'PostToolUse'
+const APPLY_PATCH = 'apply_patch'
+const APPROVAL_UNAVAILABLE =
+  'Codex hooks cannot present a Tackbox approval prompt, so this edit is blocked. ' +
+  'Make the approval-gated change in an interactive host that supports the prompt.'
+
+function requestFromEvent(event) {
+  if (event === null || typeof event !== 'object' || Array.isArray(event)) {
+    return { failure: 'Codex supplied a non-object hook event' }
+  }
+  const phase = event.hook_event_name === PRE
+    ? 'pre'
+    : event.hook_event_name === POST
+      ? 'post'
+      : null
+  if (phase === null) return { ignored: true }
+  if (event.tool_name !== APPLY_PATCH) return { ignored: true }
+  if (typeof event.cwd !== 'string' || !path.isAbsolute(event.cwd)) {
+    return { phase, failure: 'Codex supplied no absolute cwd' }
+  }
+  if (
+    event.tool_input === null ||
+    typeof event.tool_input !== 'object' ||
+    Array.isArray(event.tool_input) ||
+    typeof event.tool_input.command !== 'string'
+  ) {
+    return { phase, failure: 'Codex supplied apply_patch without a string tool_input.command' }
+  }
+  if (event.tool_input.command.trim() === '') {
+    return { phase, failure: 'Codex supplied an empty apply_patch command' }
+  }
+  const normalized = payload.normalize(
+    APPLY_PATCH,
+    { input: event.tool_input.command },
+    event.cwd,
+  )
+  if (normalized === null) return { ignored: true }
+  if (normalized.failure) return { phase, failure: normalized.failure }
+  if (phase === 'post') normalized.succeeded = true
+  return {
+    phase,
+    request: protocol.request(phase, event.cwd, normalized),
+  }
+}
+
+async function handle(event, options = {}) {
+  const built = requestFromEvent(event)
+  if (built.ignored) return { code: 0, stdout: '', stderr: '' }
+  const phase = built.phase || 'pre'
+  const decision = built.failure
+    ? protocol.unverified(built.failure)
+    : await (options.decide || protocol.decide)(built.request, {
+        env: options.env || process.env,
+        version: options.version || manifest.version,
+        timers: options.timers,
+      })
+  return render(phase, decision)
+}
+
+function render(phase, decision) {
+  const kind = decision && decision.kind
+  if (kind === protocol.ALLOW) return { code: 0, stdout: '', stderr: '' }
+  if (phase === 'pre') {
+    let reason
+    if (kind === protocol.ASK) {
+      reason = `${decision.reason}\n\n${APPROVAL_UNAVAILABLE}`
+    } else if (kind === protocol.BLOCK || kind === protocol.UNVERIFIED) {
+      reason = decision.reason
+    } else {
+      reason = `tackbox returned an unrecognized pre decision ${String(kind)}`
+    }
+    return {
+      code: 0,
+      stdout: `${JSON.stringify({ decision: 'block', reason })}\n`,
+      stderr: '',
+    }
+  }
+  if (kind === protocol.BLOCK) {
+    return {
+      code: 0,
+      stdout: `${JSON.stringify({ decision: 'block', reason: decision.reason })}\n`,
+      stderr: '',
+    }
+  }
+  const reason = kind === protocol.UNVERIFIED
+    ? decision.reason
+    : `tackbox returned an unrecognized post decision ${String(kind)}`
+  return {
+    code: 0,
+    stdout: `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: POST,
+        additionalContext: protocol.unverifiedPostMessage(reason),
+      },
+    })}\n`,
+    stderr: '',
+  }
+}
+
+async function main() {
+  const event = protocol.parseJson(fs.readFileSync(0, 'utf8'))
+  if (event.error !== null) {
+    process.stderr.write(`tackbox Codex hook: unreadable stdin: ${event.error}\n`)
+    process.exitCode = 2
+    return
+  }
+  const result = await handle(event.value)
+  if (result.stdout) process.stdout.write(result.stdout)
+  if (result.stderr) process.stderr.write(result.stderr)
+  process.exitCode = result.code
+}
+
+module.exports = {
+  APPLY_PATCH,
+  APPROVAL_UNAVAILABLE,
+  POST,
+  PRE,
+  handle,
+  main,
+  render,
+  requestFromEvent,
+}

package/js/omp/hook.js

@@ -182,6 +182,21 @@ function unverified(reason) {
   }
 }
 
+function unverifiedPostMessage(reason) {
+  const text = typeof reason === 'string' ? reason : String(reason)
+  if (
+    text.includes('The mutation may already have landed.') &&
+    text.includes('Do not repeat the mutation; dev.py check remains required.')
+  ) {
+    return text
+  }
+  return [
+    'The mutation may already have landed.',
+    `Tackbox verification did not complete: ${text}`,
+    'Do not repeat the mutation; dev.py check remains required.',
+  ].join('\n')
+}
+
 function firstLine(text) {
   for (const line of String(text || '').split('\n')) {
     if (line.trim() !== '') return line.trim()
@@ -209,5 +224,7 @@ module.exports = {
   request,
   resolveArgv,
   asDecision,
+  parseJson,
   unverified,
+  unverifiedPostMessage,
 }

package/js/omp/index.js

@@ -67,33 +67,18 @@ function applyPost(decision, event) {
   }
   if (kind === hook.UNVERIFIED) {
     return {
-      content: appended(event, unverifiedPostMessage(decision.reason)),
+      content: appended(event, hook.unverifiedPostMessage(decision.reason)),
     }
   }
   if (kind === hook.ALLOW) return undefined
   return {
     content: appended(
       event,
-      unverifiedPostMessage(`tackbox returned an unrecognized post decision ${String(kind)}`),
+      hook.unverifiedPostMessage(`tackbox returned an unrecognized post decision ${String(kind)}`),
     ),
   }
 }
 
-function unverifiedPostMessage(reason) {
-  const text = typeof reason === 'string' ? reason : String(reason)
-  if (
-    text.includes('The mutation may already have landed.') &&
-    text.includes('Do not repeat the mutation; dev.py check remains required.')
-  ) {
-    return text
-  }
-  return [
-    'The mutation may already have landed.',
-    `Tackbox verification did not complete: ${text}`,
-    'Do not repeat the mutation; dev.py check remains required.',
-  ].join('\n')
-}
-
 function appended(event, text) {
   const content = Array.isArray(event && event.content) ? event.content : []
   return [...content, { type: 'text', text }]

package/js/omp/payload.js

@@ -4,6 +4,7 @@ const path = require('node:path')
 
 const TAGGED = /^\[(.+)#[0-9A-Fa-f]{4}\]\s*$/
 const ENVELOPE = /^\*\*\* (?:Begin|End) Patch\s*$/
+const EOF_SENTINEL = /^\*\*\* End of File\s*$/
 const FILE_SENTINEL = /^\*\*\* (Update|Add|Delete) File:\s*(.+?)\s*$/
 const MOVE_SENTINEL = /^\*\*\* Move to:\s*(.+?)\s*$/
 const MV_OP = /^MV\s+(.+?)\s*$/
@@ -256,7 +257,7 @@ function parsePatchText(tool, text, cwd) {
       continue
     }
     flush()
-    if (line.trim() === '' || ENVELOPE.test(line) || HUNK.test(line)) continue
+    if (line.trim() === '' || ENVELOPE.test(line) || EOF_SENTINEL.test(line) || HUNK.test(line)) continue
     const tagged = TAGGED.exec(line)
     if (tagged !== null) {
       open(tagged[1])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tackbox",
-  "version": "0.1.98",
+  "version": "0.1.99",
   "description": "ESLint and Markdown lint plugins, an Oh My Pi extension, plus direct error-reporting helpers for JavaScript and TypeScript.",
   "license": "MIT",
   "main": "./js/eslint-plugin.js",
@@ -9,6 +9,7 @@
     "./report": "./js/report.js"
   },
   "bin": {
+    "tackbox-codex-hook": "./bin/tackbox-codex-hook.js",
     "tackbox-eslint": "./bin/tackbox-eslint.js",
     "tackbox-mdlint": "./bin/tackbox-mdlint.js"
   },
@@ -22,6 +23,7 @@
     "js/report.js",
     "js/rules/",
     "js/markdownlint-rules/",
+    "js/codex/",
     "js/omp/index.mjs",
     "js/omp/index.js",
     "js/omp/hook.js",