The compaction re-injection hook previously required users to hand-merge
an example into user-level ~/.codex/hooks.json — which renders in the
Codex hooks UI as an anonymous, unattributed "Hook 1" and puts the
install burden on every user. Restore the plugin-provided delivery this
repo used before "Remove Codex hooks" (640ce6c0): the Codex manifest
points hooks at hooks/hooks-codex.json, which runs session-start-codex
via ${PLUGIN_ROOT}/hooks/run-hook.cmd with matcher "compact".
Unlike the removed hook, this one never fires at session start — Codex
surfaces skills natively there, which is why the old startup-injecting
hook was removed. The matcher plus the script's own source gate restrict
it to post-compaction re-starts. The explicit manifest pointer also
keeps suppressing Codex's hooks/hooks.json auto-discovery fallback,
which the previous empty-object declaration existed for (7d8d3d4b).
The Codex portal archive now ships hooks/hooks-codex.json,
hooks/run-hook.cmd, and hooks/session-start-codex; other-harness hook
files stay excluded.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codex 0.145 re-fires SessionStart with source:"compact" after every
context compaction, and injects hook stdout into the live model context
(both verified with sentinel probes on codex-cli 0.145.0). Compaction
replaces the transcript with a summary that sheds the using-superpowers
bootstrap and the active skill's instructions; in instrumented SDD runs
the first post-compaction dispatch that lacked a freshly printed
reminder reverted to harness defaults (fork_turns=all, inherited
frontier model) and the drift then self-perpetuated. Claude Code never
exhibits this because its SessionStart matcher (startup|clear|compact)
re-injects the bootstrap at the same moment — this hook restores that
parity on Codex.
On source:"startup" the hook emits nothing: the native plugin path owns
session-start injection, and duplicating it would recreate the
redundancy that led to the original session-start-codex removal. Output
is plain text (Codex consumes raw stdout, unlike the JSON envelopes
hooks/session-start emits for other harnesses), and every failure path
is fail-open: bad stdin, missing skill file, or any error yields empty
output and exit 0 so a hook problem can never break a session.
Ships with hooks-codex.json.example for the user-level ~/.codex/hooks.json
merge and tests covering source filtering, whitespace-tolerant matching,
decoy fields, and fail-open behavior.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The SessionStart command string starts with a quoted path, which breaks
both Windows shells Claude Code may hand it to: PowerShell parses the
leading quoted string as an expression and dies on the next bareword
('Unexpected token session-start', #1751), and cmd.exe's /c quote rule
drops the outer quotes when the path contains a metacharacter, so a
profile dir like C:\Users\Name(External) truncates the command at the
'(' (#1918). Either way the bootstrap silently never loads.
Declare shell: "bash" on the hook. Claude Code >= 2.1.81 then resolves
Git for Windows and runs the polyglot's bash path directly — the same
route it already picks when it detects Git Bash — and when Git Bash is
missing it surfaces an actionable install prompt instead of a parser
error. Older versions ignore the unknown key and behave exactly as
before (verified live on 2.0.77 and 2.1.80).
Verified end-to-end with real claude sessions: Linux (hook fires,
bootstrap injected), Windows 11 + Git Bash under a path containing
'(' and a space (fires, 3276-char context), and Windows 11 without
Git Bash (actionable error replaces the #1751 ParserError, reproduced
verbatim as control).
Fixes#1751Fixes#1918
hooks/session-start-codex has had no caller since "Remove Codex hooks"
(#1845) deleted hooks-codex.json and its manifest registration; the
Codex manifest now declares an empty hooks object so Codex registers no
session-start hook at all. The script is Codex-specific dead code —
nothing executes it on Codex or any other harness.
- Delete hooks/session-start-codex.
- tests/hooks/test-session-start.sh: drop the two Codex cases that are
redundant with the generic session-start tests (nested-format and the
legacy-warning omission are already covered by the Claude Code cases).
Re-point the "wrapper dispatches" case to the live `session-start`
script so run-hook.cmd dispatch coverage — used by Claude Code and
Cursor in production — is preserved rather than lost.
- docs/porting-to-a-new-harness.md: Codex is no longer a Shape A
(shell-hook) harness, so re-anchor that worked example to Cursor (a
live shell-hook harness that demonstrates the same per-harness field,
schema, and matcher variance) and mark Codex as native skill discovery
with no session-start hook. Clears the references to the deleted
hooks-codex.json.
- docs/windows/polyglot-hooks.md: the "check hooks-codex.json" pointer
referenced a file deleted in #1845; re-point to hooks-cursor.json.
RELEASE-NOTES.md keeps its historical mention of hooks-codex.json (it
accurately records what that release did). The tests/codex-plugin-sync
fixtures build their own synthetic session-start-codex and test the sync
mechanism generically, so they are intentionally left as-is.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
