skills/pbakaus_impeccable
1
0
Fork 0
mirror of https://github.com/pbakaus/impeccable.git synced 2026-09-12 06:06:37 +03:00
Code Issues Packages Projects Releases Wiki Activity

Fix: emit Codex Stop hook as decision/block (#603)

Browse Source 
Codex Stop rejects Claude's hookSpecificOutput shape. Detect Codex from
turn_id at runtime and emit { decision: "block", reason } so existing
installs keep working without rewriting hook commands.

AI-assisted change, prepared with Cursor Grok under maintainer direction.

Fixes #603
Fixes #643

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Abdul Wahab
2026-08-24 05:23:51 +05:00
co-authored by Cursor
parent c39b6425fa
commit c9e7cd8a64
3 changed files with 113 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skill/scripts/hook-lib.mjs
+36 -13
View File
@@ -1251,7 +1251,8 @@ export function resolveHarness(env = {}, event = null) {
const explicit = env?.IMPECCABLE_HOOK_HARNESS;
if (explicit === 'cursor') return 'cursor';
if (explicit === 'github') return 'github';
if (explicit === 'claude' || explicit === 'codex') return 'claude';
if (explicit === 'claude') return 'claude';
if (explicit === 'codex') return 'codex';
// GitHub Copilot's postToolUse event uses camelCase `toolName`/`toolArgs` and
// has no `tool_name`/`tool_input`. That shape is the discriminator.
if (event && typeof event === 'object'
@@ -1260,6 +1261,11 @@ export function resolveHarness(env = {}, event = null) {
return 'github';
}
if (typeof event?.conversation_id === 'string' && event.conversation_id) return 'cursor';
// Codex turn-scoped events carry `turn_id`. Claude Code does not. Detecting
// it here means an already-installed Codex hook emits the Codex Stop
// contract without rewriting the hook command to set IMPECCABLE_HOOK_HARNESS.
// https://developers.openai.com/codex/hooks#stop
if (typeof event?.turn_id === 'string' && event.turn_id) return 'codex';
return 'claude';
}
@@ -2163,8 +2169,11 @@ export const STOP_MAX_FILES = 20;
* { exitCode, stdout, audit, emission? }
*
* Never throws; exits silent (and fast) when the session touched no UI
* files. Output uses the Stop hookSpecificOutput channel: additionalContext
* is delivered to the model and the conversation continues so it can act.
* files. Output goes out on the harness's Stop continuation channel: Claude
* Code reads hookSpecificOutput.additionalContext, Codex takes a
* decision: "block" whose reason becomes the continuation prompt. Either
* way the findings reach the model and the conversation continues so it
* can act.
*/
export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), now = Date.now, detector } = {}) {
const audit = { ts: new Date(now()).toISOString(), event: 'Stop' };
@@ -2191,16 +2200,21 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
return result({ skipped: 'stdin-empty', durationMs: Date.now() - started });
}
// Claude Code's Stop-hook contract: `stop_hook_active` is true when this
// hook is being re-invoked only because a prior invocation kept the turn
// alive (here, via hookSpecificOutput.additionalContext). Re-scanning and
// re-blocking now would loop until Claude Code's consecutive-block cap
// force-ends the turn (issue #400). The prior fire already surfaced the
// findings; whether to act on them is the agent's call. Exit fast with no
// output before any scan. Only Claude Code sends this field; other
// harnesses omit it, so the strict `=== true` is a no-op for them. This
// guard makes the loop impossible regardless of the finding cache key's
// line-number sensitivity (out of scope here; see findingCacheKey).
// Stop-hook re-entry guard: `stop_hook_active` is true when this hook is
// being re-invoked only because a prior invocation kept the turn alive
// (Claude Code via hookSpecificOutput.additionalContext, Codex via a
// decision: "block" continuation). Re-scanning and re-blocking now could
// loop (issue #400). The prior fire already surfaced the findings;
// whether to act on them is the agent's call. Exit fast with no output
// before any scan. Claude Code and Codex both send this field: Codex
// mirrors the Claude contract (StopCommandInput in
// codex-rs/hooks/src/schema.rs) and latches it true for the rest of the
// turn once a block is honored (codex-rs/core/src/session/turn.rs), so
// this guard is also what caps the Codex deep pass at one continuation
// per turn. Cursor and GitHub Copilot omit the field, so the strict
// `=== true` is a no-op for them. The guard makes the loop impossible
// regardless of the finding cache key's line-number sensitivity (out of
// scope here; see findingCacheKey).
if (event.stop_hook_active === true) {
return result({ skipped: 'stop-hook-active', durationMs: Date.now() - started });
}
@@ -2337,6 +2351,15 @@ export function payload(text, eventName = 'PostToolUse', harness = 'claude') {
if (harness === 'github') {
return JSON.stringify({ additionalContext: text });
}
// Codex shares Claude Code's PostToolUse additional-context shape, but its
// Stop schema rejects unknown fields. Findings that should continue the
// turn must be a top-level blocking decision.
// https://developers.openai.com/codex/hooks#stop (schema of record:
// codex-rs/hooks/src/schema.rs, StopCommandOutputWire)
if (harness === 'codex' && eventName === 'Stop') {
if (!String(text ?? '').trim()) return '';
return JSON.stringify({ decision: 'block', reason: text });
}
return JSON.stringify({
hookSpecificOutput: { hookEventName: eventName, additionalContext: text },
});