An agentic skills framework & software development methodology that works.
chore(codex): remove orphaned session-start-codex hook + refresh hook docs
Drew Ritter28b96af905db
diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.mdindex d74b1c64f..986cf5613 100644--- a/docs/porting-to-a-new-harness.md+++ b/docs/porting-to-a-new-harness.md@@ -227,18 +227,20 @@ you may **not** do is bridge a gap by editing the user's global config.The harness has a hook system that runs a shell command at session start andreads JSON from its stdout. The configured command runs `run-hook.cmd`, apolyglot wrapper that just locates bash and dispatches the named script; the-script (`hooks/session-start`, or a harness-specific variant like-`hooks/session-start-codex`) is what reads `using-superpowers/SKILL.md` and-prints a JSON object whose **field name and nesting differ per harness**.+script (`hooks/session-start`, or a harness-specific variant) is what reads+`using-superpowers/SKILL.md` and prints a JSON object whose **field name and+nesting differ per harness**.-- Reference: `hooks/session-start` (and `hooks/session-start-codex`),- `hooks/run-hook.cmd`, and the per-harness hook config `hooks/hooks.json`- (Claude Code), `hooks/hooks-codex.json` (Codex), `hooks/hooks-cursor.json`+- Reference: `hooks/session-start`, `hooks/run-hook.cmd`, and the per-harness+ hook config `hooks/hooks.json` (Claude Code) and `hooks/hooks-cursor.json`(Cursor).-- Manifests: `.codex-plugin/plugin.json`, `.cursor-plugin/plugin.json` point the- harness at `./skills/` and the right `hooks-*.json`. (Claude Code's- `.claude-plugin/plugin.json` sets neither field — it auto-discovers `skills/`- and `hooks/hooks.json` by convention.)+- Manifests: `.cursor-plugin/plugin.json` points the harness at `./skills/` and+ the right `hooks-*.json`. (Claude Code's `.claude-plugin/plugin.json` sets+ neither field — it auto-discovers `skills/` and `hooks/hooks.json` by+ convention. Codex's `.codex-plugin/plugin.json` ships skills but declares an+ empty `hooks` object: Codex auto-discovers `hooks/hooks.json` when the field+ is absent, so the empty object suppresses that — Codex surfaces skills+ natively and runs no session-start hook.)> **A hook *system* is not a session-start *event*.** A harness can have a> `hooks.json` mechanism — and even contain the literal string `SessionStart` in@@ -287,7 +289,7 @@ part of the installed extension** — never substitute "edit the user's global| If the harness… | Use shape | Copy from ||---|---|---|-| runs a shell command at session start and reads its stdout | A (shell-hook) | Codex (`hooks/session-start-codex` + `hooks/hooks-codex.json` + `.codex-plugin/`) |+| runs a shell command at session start and reads its stdout | A (shell-hook) | Cursor (`hooks/session-start` + `hooks/hooks-cursor.json` + `.cursor-plugin/`) || is a JS/TS plugin host with session/message lifecycle callbacks | B (in-process) | OpenCode (`.opencode/`) — or pi (`.pi/`) if it has no native skill tool || ships an extension-declared context file it always loads | C (instructions-file) | Gemini (`gemini-extension.json` + `GEMINI.md` + `references/gemini-tools.md`) || has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |@@ -375,25 +377,24 @@ both double-injects). Find theexact field, nesting, and event-matcher values your harness expects. Thendecide: add a fourth branch to `hooks/session-start`, or — if the harness needsa different bootstrap message or env contract — add a dedicated-`hooks/session-start-<harness>` script, the way Codex did. If you add a branch+`hooks/session-start-<harness>` script. If you add a branchand your harness *also* sets an env var an earlier branch keys on (some harnessesset `CLAUDE_PLUGIN_ROOT` too), order your branch before the one that wouldotherwise shadow it. Match the harness's-own event-matcher strings (Claude Code uses `startup|clear|compact`, Codex-`startup|resume|clear`, Cursor `sessionStart`); wrong matchers mean the hook-silently never fires.+own event-matcher strings (Claude Code uses `startup|clear|compact`, Cursor+`sessionStart`); wrong matchers mean the hook silently never fires.The **hook-config schema itself varies per harness** — don't assume the-Claude/Codex shape is universal. Compare `hooks/hooks.json`,-`hooks/hooks-codex.json`, and `hooks/hooks-cursor.json`: Cursor's uses+Claude Code shape is universal. Compare `hooks/hooks.json` and+`hooks/hooks-cursor.json`: Cursor's uses`"version": 1`, a lowercase `sessionStart` key, a relative-`./hooks/run-hook.cmd` command, and omits the `matcher`/`type`/`async` fields the-others use. Match your `hooks-<harness>.json` to whichever existing file is+`./hooks/run-hook.cmd` command, and omits the `matcher`/`type`/`async` fields+Claude Code uses. Match your `hooks-<harness>.json` to whichever existing file isclosest, not to a single canonical template.The hook **command string references a harness-provided plugin-root variable**,and its name differs per harness: `hooks.json` uses `${CLAUDE_PLUGIN_ROOT}`,-`hooks-codex.json` uses `${PLUGIN_ROOT}`, Cursor uses a relative path. Use+`hooks-cursor.json` uses a relative path. Usewhatever your harness exports. (The `session-start` script re-derives the rootitself via `dirname`, so the script body doesn't depend on this — but thecommand in the manifest does.)@@ -784,7 +785,7 @@ Use this as the live index; when in doubt, read the files, not this table.| Harness | Entry point | Bootstrap mechanism | Tool mapping | Tests | Distribution ||---|---|---|---|---|---|| Claude Code | `.claude-plugin/plugin.json` + `hooks/hooks.json` | shell hook → `hooks/session-start` (`hookSpecificOutput.additionalContext`) | native `Skill` tool; `references/claude-code-tools.md` | `tests/hooks/` | marketplace |-| Codex | `.codex-plugin/plugin.json` + `hooks/hooks-codex.json` | shell hook → `hooks/session-start-codex` | `references/codex-tools.md` | `tests/codex-plugin-sync/`, `tests/hooks/` | fork sync (`scripts/sync-to-codex-plugin.sh`) |+| Codex | `.codex-plugin/plugin.json` (declares empty `hooks`) | native skill discovery (no session-start hook) | `references/codex-tools.md` | `tests/codex/`, `tests/codex-plugin-sync/` | fork sync (`scripts/sync-to-codex-plugin.sh`) || Cursor | `.cursor-plugin/plugin.json` + `hooks/hooks-cursor.json` | shell hook → `hooks/session-start` (`additional_context`) | `references/claude-code-tools.md` | `tests/hooks/` | hand-authored || Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | `references/copilot-tools.md` | `tests/hooks/` | — || Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |@@ -799,10 +800,10 @@ Use this as the live index; when in doubt, read the files, not this table.- **Wrong JSON field → silent failure or double injection.** Shape A only.Confirm the exact field/nesting; Claude Code reads two fields without dedup.- **Hook-config schema varies per harness.** Shape A. Cursor's `hooks-cursor.json`- looks nothing like the Claude/Codex one (`version`, lowercase `sessionStart`,+ looks nothing like the Claude Code one (`version`, lowercase `sessionStart`,relative command, no `matcher`/`type`/`async`). Match the closest existing file.- **Plugin-root env var differs per harness.** Shape A. The hook command uses- `${CLAUDE_PLUGIN_ROOT}` (Claude), `${PLUGIN_ROOT}` (Codex), or a relative path+ `${CLAUDE_PLUGIN_ROOT}` (Claude) or a relative path(Cursor). Use what your harness exports; the script re-derives the root itself.- **System-message injection.** Shape B injects a *user* message on purpose(#750, #894). Don't "fix" it to a system message.diff --git a/docs/windows/polyglot-hooks.md b/docs/windows/polyglot-hooks.mdindex ca597c3ab..8b84f2717 100644--- a/docs/windows/polyglot-hooks.md+++ b/docs/windows/polyglot-hooks.md@@ -140,7 +140,7 @@ Check that the script filename is **extensionless** in `hooks.json`. A command l### Hook doesn't fire at all-Verify the `matcher` in `hooks.json` matches the event type your harness emits. Claude Code uses `startup|clear|compact`; Codex uses `startup|resume|clear`. Check `hooks-codex.json` for the Codex variant.+Verify the `matcher` in `hooks.json` matches the event type your harness emits. Claude Code uses `startup|clear|compact`; Cursor uses `sessionStart`. Check `hooks-cursor.json` for the Cursor variant.## Related Issuesdiff --git a/hooks/session-start-codex b/hooks/session-start-codexdeleted file mode 100755index f25ea0846..000000000--- a/hooks/session-start-codex+++ /dev/null@@ -1,26 +0,0 @@-#!/usr/bin/env bash-# Codex SessionStart hook for superpowers plugin--set -euo pipefail--SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"-PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"--using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")--escape_for_json() {- local s="$1"- s="${s//\\/\\\\}"- s="${s//\"/\\\"}"- s="${s//$'\n'/\\n}"- s="${s//$'\r'/\\r}"- s="${s//$'\t'/\\t}"- printf '%s' "$s"-}--using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")-session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, follow the Codex skill-loading instructions in that skill:**\n\n${using_superpowers_escaped}\n</EXTREMELY_IMPORTANT>"--printf '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context" | cat--exit 0diff --git a/tests/hooks/test-session-start.sh b/tests/hooks/test-session-start.shindex 989d72c65..b027f3c65 100755--- a/tests/hooks/test-session-start.sh+++ b/tests/hooks/test-session-start.sh@@ -4,7 +4,6 @@ set -euo pipefailSCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"HOOK_UNDER_TEST="$REPO_ROOT/hooks/session-start"-CODEX_HOOK_UNDER_TEST="$REPO_ROOT/hooks/session-start-codex"WRAPPER_UNDER_TEST="$REPO_ROOT/hooks/run-hook.cmd"FAILURES=0@@ -154,35 +153,15 @@ assert_command_output \CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \bash "$HOOK_UNDER_TEST"-codex_home="$(make_home codex-plugin-hooks)"-codex_data="$TEST_ROOT/codex-plugin-hooks/data"-mkdir -p "$codex_data"+wrapper_home="$(make_home run-hook-wrapper)"assert_command_output \- "Codex plugin hooks use dedicated script and emit nested SessionStart additionalContext" \+ "run-hook.cmd wrapper dispatches to the named session-start script" \"nested" \"" \"" \- "$codex_home" \- PLUGIN_DATA="$codex_data" \- CLAUDE_PLUGIN_DATA="$codex_data" \- PLUGIN_ROOT="$REPO_ROOT" \+ "$wrapper_home" \CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \- bash "$CODEX_HOOK_UNDER_TEST"--codex_wrapper_home="$(make_home codex-wrapper)"-codex_wrapper_data="$TEST_ROOT/codex-wrapper/data"-mkdir -p "$codex_wrapper_data"-assert_command_output \- "Codex wrapper path dispatches to dedicated script" \- "nested" \- "" \- "" \- "$codex_wrapper_home" \- PLUGIN_DATA="$codex_wrapper_data" \- CLAUDE_PLUGIN_DATA="$codex_wrapper_data" \- PLUGIN_ROOT="$REPO_ROOT" \- CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \- bash "$WRAPPER_UNDER_TEST" session-start-codex+ bash "$WRAPPER_UNDER_TEST" session-startcursor_home="$(make_home cursor)"assert_command_output \@@ -217,21 +196,6 @@ assert_command_output \CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \bash "$HOOK_UNDER_TEST"-codex_legacy_home="$(make_home codex-legacy-warning-removed)"-codex_legacy_data="$TEST_ROOT/codex-legacy-warning-removed/data"-mkdir -p "$codex_legacy_home/.config/superpowers/skills" "$codex_legacy_data"-assert_command_output \- "Codex SessionStart omits obsolete legacy custom-skill warning" \- "nested" \- "" \- "Superpowers now uses"$'\037'"~/.config/superpowers/skills"$'\037'"~/.claude/skills"$'\037'"legacy" \- "$codex_legacy_home" \- PLUGIN_DATA="$codex_legacy_data" \- CLAUDE_PLUGIN_DATA="$codex_legacy_data" \- PLUGIN_ROOT="$REPO_ROOT" \- CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \- bash "$CODEX_HOOK_UNDER_TEST"-if [[ "$FAILURES" -gt 0 ]]; thenecho "STATUS: FAILED ($FAILURES failure(s))"exit 1