feat: support Codex native plugin hooks

2026-05-16 22:19:05 +08:00 · 2026-05-12 17:34:16 -07:00
parent a57b6c5dc1
commit 51514f86c8
8 changed files with 504 additions and 58 deletions
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -21,6 +21,7 @@
    "workflow"
  ],
  "skills": "./skills/",
+  "hooks": "./hooks/hooks-codex.json",
  "interface": {
    "displayName": "Superpowers",
    "shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",
--- a/README.md
+++ b/README.md
@@ -86,6 +86,18 @@ Superpowers is available via the [official Codex plugin marketplace](https://git

 - Select `Install Plugin`.

+#### Automatic startup bootstrap
+
+Codex plugin hooks are still gated behind Codex's `plugin_hooks` feature. To opt in:
+
+```bash
+codex features enable plugin_hooks
+```
+
+Restart Codex, open `/hooks`, review the Superpowers `SessionStart` hook, and trust it. Codex may require you to re-review the hook after Superpowers updates if the hook definition changes.
+
+Fallback: if `plugin_hooks` is disabled, unavailable, or untrusted, Superpowers still installs as a normal Codex plugin and the skills remain available. The automatic startup bootstrap is the part that waits for the trusted hook.
+
 ### Cursor

 - In Cursor Agent chat, install from marketplace:
--- a/docs/windows/polyglot-hooks.md
+++ b/docs/windows/polyglot-hooks.md
@@ -1,75 +1,107 @@
-# Cross-Platform Polyglot Hooks for Claude Code
+# Cross-Platform Polyglot Hooks

-Claude Code plugins need hooks that work on Windows, macOS, and Linux. This document explains the polyglot wrapper technique that makes this possible.
+Superpowers plugin hooks need to work on Windows, macOS, and Linux across the
+agent harnesses that support startup hooks. This document explains the
+polyglot wrapper technique that makes this possible.

 ## The Problem

-Claude Code runs hook commands through the system's default shell:
+Hook commands may run through the system's default shell:
+
 - **Windows**: CMD.exe
 - **macOS/Linux**: bash or sh

 This creates several challenges:

-1. **Script execution**: Windows CMD can't execute `.sh` files directly - it tries to open them in a text editor
-2. **Path format**: Windows uses backslashes (`C:\path`), Unix uses forward slashes (`/path`)
-3. **Environment variables**: `$VAR` syntax doesn't work in CMD
-4. **No `bash` in PATH**: Even with Git Bash installed, `bash` isn't in the PATH when CMD runs
+1. **Script execution**: Windows CMD can't execute shell scripts directly.
+2. **Path format**: Windows uses backslashes (`C:\path`), Unix uses forward slashes (`/path`).
+3. **Environment variables**: `$VAR` syntax doesn't work in CMD.
+4. **No `bash` in PATH**: Even with Git Bash installed, `bash` isn't always in the PATH when CMD runs.

-## The Solution: Polyglot `.cmd` Wrapper
+## The Solution: Polyglot `run-hook.cmd` Wrapper

-A polyglot script is valid syntax in multiple languages simultaneously. Our wrapper is valid in both CMD and bash:
+A polyglot script is valid syntax in multiple languages simultaneously. Our
+wrapper is valid in both CMD and bash. Manifests point to `run-hook.cmd` and
+pass the extensionless hook script name:

 ```cmd
 : << 'CMDBLOCK'
@echo off
-"C:\Program Files\Git\bin\bash.exe" -l -c "\"$(cygpath -u \"$CLAUDE_PLUGIN_ROOT\")/hooks/session-start.sh\""
-exit /b
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+
+set "HOOK_DIR=%~dp0"
+
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+where bash >nul 2>nul
+if %ERRORLEVEL% equ 0 (
+    bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+exit /b 0
 CMDBLOCK

-# Unix shell runs from here
-"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+# Unix: run the named script directly
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
 ```

 ### How It Works

 #### On Windows (CMD.exe)

-1. `: << 'CMDBLOCK'` - CMD sees `:` as a label (like `:label`) and ignores `<< 'CMDBLOCK'`
-2. `@echo off` - Suppresses command echoing
-3. The bash.exe command runs with:
-   - `-l` (login shell) to get proper PATH with Unix utilities
-   - `cygpath -u` converts Windows path to Unix format (`C:\foo` → `/c/foo`)
-4. `exit /b` - Exits the batch script, stopping CMD here
-5. Everything after `CMDBLOCK` is never reached by CMD
+1. `: << 'CMDBLOCK'` - CMD sees `:` as a label and ignores `<< 'CMDBLOCK'`.
+2. `@echo off` - Suppresses command echoing.
+3. The bash.exe command runs the requested hook script next to the wrapper.
+4. `exit /b` - Exits the batch script, stopping CMD here.
+5. Everything after `CMDBLOCK` is never reached by CMD.

 #### On Unix (bash/sh)

-1. `: << 'CMDBLOCK'` - `:` is a no-op, `<< 'CMDBLOCK'` starts a heredoc
-2. Everything until `CMDBLOCK` is consumed by the heredoc (ignored)
-3. `# Unix shell runs from here` - Comment
-4. The script runs directly with the Unix path
+1. `: << 'CMDBLOCK'` - `:` is a no-op, `<< 'CMDBLOCK'` starts a heredoc.
+2. Everything until `CMDBLOCK` is consumed by the heredoc and ignored.
+3. `# Unix shell runs from here` - Comment.
+4. The requested hook script runs directly with the Unix path.

 ## File Structure

-```
+```text
 hooks/
-├── hooks.json           # Points to the .cmd wrapper
-├── session-start.cmd    # Polyglot wrapper (cross-platform entry point)
-└── session-start.sh     # Actual hook logic (bash script)
+|-- hooks.json
+|-- hooks-codex.json
+|-- hooks-cursor.json
+|-- run-hook.cmd
+`-- session-start
 ```

-### hooks.json
+### `hooks/hooks.json` (Claude Code)
+
+`hooks/hooks.json` is the Claude Code manifest:

 ```json
 {
  "hooks": {
    "SessionStart": [
      {
-        "matcher": "startup|resume|clear|compact",
+        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.cmd\""
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
          }
        ]
      }
@@ -78,41 +110,73 @@ hooks/
 }
 ```

-Note: The path must be quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces on Windows (e.g., `C:\Program Files\...`).
+### `hooks/hooks-codex.json` (Codex)
+
+`hooks/hooks-codex.json` is the Codex-specific manifest. Codex uses the
+verified `${PLUGIN_ROOT}` placeholder and the `startup|resume|clear` matcher:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Note: The path must be quoted because plugin roots may contain spaces on
+Windows, for example `C:\Program Files\...`.

 ## Requirements

 ### Windows
- **Git for Windows** must be installed (provides `bash.exe` and `cygpath`)
+
+- **Git for Windows** must be installed if no other Bash is available.
 - Default installation path: `C:\Program Files\Git\bin\bash.exe`
- If Git is installed elsewhere, the wrapper needs modification
+- If Git is installed elsewhere, `run-hook.cmd` also tries `bash` on PATH.

 ### Unix (macOS/Linux)
+
 - Standard bash or sh shell
- The `.cmd` file must have execute permission (`chmod +x`)
+- `run-hook.cmd` must have execute permission (`chmod +x`)

 ## Writing Cross-Platform Hook Scripts

-Your actual hook logic goes in the `.sh` file. To ensure it works on Windows (via Git Bash):
+Your actual hook logic goes in the extensionless hook script. To ensure it
+works on Windows via Git Bash:

 ### Do:
+
 - Use pure bash builtins when possible
 - Use `$(command)` instead of backticks
 - Quote all variable expansions: `"$VAR"`
 - Use `printf` or here-docs for output

 ### Avoid:
+
 - External commands that may not be in PATH (sed, awk, grep)
- If you must use them, they're available in Git Bash but ensure PATH is set up (use `bash -l`)
+- If you must use them, they're available in Git Bash but ensure PATH is set up

 ### Example: JSON Escaping Without sed/awk

 Instead of:
+
 ```bash
 escaped=$(echo "$content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
 ```

 Use pure bash:
+
 ```bash
 escape_for_json() {
    local input="$1"
@@ -135,26 +199,48 @@ escape_for_json() {

 ## Reusable Wrapper Pattern

-For plugins with multiple hooks, you can create a generic wrapper that takes the script name as an argument:
+For plugins with multiple hooks, use the generic wrapper with the script name
+as an argument:
+
+### `run-hook.cmd`

-### run-hook.cmd
 ```cmd
 : << 'CMDBLOCK'
@echo off
-set "SCRIPT_DIR=%~dp0"
-set "SCRIPT_NAME=%~1"
-"C:\Program Files\Git\bin\bash.exe" -l -c "cd \"$(cygpath -u \"%SCRIPT_DIR%\")\" && \"./%SCRIPT_NAME%\""
-exit /b
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+
+set "HOOK_DIR=%~dp0"
+
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+where bash >nul 2>nul
+if %ERRORLEVEL% equ 0 (
+    bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+exit /b 0
 CMDBLOCK

-# Unix shell runs from here
+# Unix: run the named script directly
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SCRIPT_NAME="$1"
 shift
-"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
 ```

-### hooks.json using the reusable wrapper
+### Manifest using the reusable wrapper
+
 ```json
 {
  "hooks": {
@@ -164,7 +250,7 @@ shift
        "hooks": [
          {
            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start"
          }
        ]
      }
@@ -175,7 +261,7 @@ shift
        "hooks": [
          {
            "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" validate-bash.sh"
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" validate-bash"
          }
        ]
      }
@@ -187,26 +273,37 @@ shift
 ## Troubleshooting

 ### "bash is not recognized"
-CMD can't find bash. The wrapper uses the full path `C:\Program Files\Git\bin\bash.exe`. If Git is installed elsewhere, update the path.
+
+CMD can't find bash. The wrapper checks common Git for Windows paths and then
+tries `bash` on PATH. If Bash is installed elsewhere, update the path.

 ### "cygpath: command not found" or "dirname: command not found"
-Bash isn't running as a login shell. Ensure `-l` flag is used.
+
+Bash isn't running in the environment you expected. Make sure the wrapper is
+calling the intended Bash installation.

 ### Path has weird `\/` in it
-`${CLAUDE_PLUGIN_ROOT}` expanded to a Windows path ending with backslash, then `/hooks/...` was appended. Use `cygpath` to convert the entire path.
+
+`${CLAUDE_PLUGIN_ROOT}` expanded to a Windows path ending with backslash, then
+`/hooks/...` was appended. Route through `run-hook.cmd` so the Windows branch
+uses the wrapper directory directly.

 ### Script opens in text editor instead of running
-The hooks.json is pointing directly to the `.sh` file. Point to the `.cmd` wrapper instead.
+
+The manifest is pointing directly to the shell script. Point to `run-hook.cmd`
+instead.

 ### Works in terminal but not as hook
+
 Claude Code may run hooks differently. Test by simulating the hook environment:
+
 ```powershell
 $env:CLAUDE_PLUGIN_ROOT = "C:\path\to\plugin"
-cmd /c "C:\path\to\plugin\hooks\session-start.cmd"
+cmd /c "C:\path\to\plugin\hooks\run-hook.cmd session-start"
 ```

 ## Related Issues

- [anthropics/claude-code#9758](https://github.com/anthropics/claude-code/issues/9758) - .sh scripts open in editor on Windows
+- [anthropics/claude-code#9758](https://github.com/anthropics/claude-code/issues/9758) - shell scripts open in editor on Windows
 - [anthropics/claude-code#3417](https://github.com/anthropics/claude-code/issues/3417) - Hooks don't work on Windows
 - [anthropics/claude-code#6023](https://github.com/anthropics/claude-code/issues/6023) - CLAUDE_PROJECT_DIR not found
--- a/hooks/hooks-codex.json
+++ b/hooks/hooks-codex.json
@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}
--- a/hooks/session-start
+++ b/hooks/session-start
@@ -7,11 +7,22 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"

+# Codex plugin hooks set Claude-compatible root env vars, so detect Codex
+# through its plugin data env before building platform-specific context.
+is_codex_hook=0
+if [ -n "${PLUGIN_DATA:-}" ] || [ -n "${CLAUDE_PLUGIN_DATA:-}" ]; then
+    is_codex_hook=1
+fi
+
 # Check if legacy skills directory exists and build warning
 warning_message=""
 legacy_skills_dir="${HOME}/.config/superpowers/skills"
 if [ -d "$legacy_skills_dir" ]; then
-    warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.claude/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
+    if [ "$is_codex_hook" -eq 1 ]; then
+        warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER: WARNING: Superpowers now uses your coding agent's native skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to a skills location supported by your coding agent. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
+    else
+        warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.claude/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
+    fi
 fi

 # Read using-superpowers content
--- a/scripts/sync-to-codex-plugin.sh
+++ b/scripts/sync-to-codex-plugin.sh
@@ -70,7 +70,6 @@ EXCLUDES=(
  "/commands/"
  "/docs/"
  "/evals/"
-  "/hooks/"
  "/lib/"
  "/scripts/"
  "/tests/"
@@ -420,7 +419,7 @@ if [[ $BOOTSTRAP -eq 1 ]]; then
  COMMIT_TITLE="bootstrap superpowers v$UPSTREAM_VERSION from upstream main @ $UPSTREAM_SHORT"
  PR_BODY="Initial bootstrap of the superpowers plugin from upstream \`main\` @ \`$UPSTREAM_SHORT\` (v$UPSTREAM_VERSION).

-Creates \`plugins/superpowers/\` by copying the tracked plugin files from upstream, including \`.codex-plugin/plugin.json\` and \`assets/\`.
+Creates \`plugins/superpowers/\` by copying the tracked plugin files from upstream, including \`.codex-plugin/plugin.json\`, \`assets/\`, and \`hooks/\`.

 Run via: \`scripts/sync-to-codex-plugin.sh --bootstrap\`
 Upstream commit: https://github.com/obra/superpowers/commit/$UPSTREAM_SHA
@@ -430,7 +429,7 @@ else
  COMMIT_TITLE="sync superpowers v$UPSTREAM_VERSION from upstream main @ $UPSTREAM_SHORT"
  PR_BODY="Automated sync from superpowers upstream \`main\` @ \`$UPSTREAM_SHORT\` (v$UPSTREAM_VERSION).

-Copies the tracked plugin files from upstream, including the committed Codex manifest and assets.
+Copies the tracked plugin files from upstream, including the committed Codex manifest, assets, and hooks.

 Run via: \`scripts/sync-to-codex-plugin.sh\`
 Upstream commit: https://github.com/obra/superpowers/commit/$UPSTREAM_SHA
--- a/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
+++ b/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
@@ -178,6 +178,7 @@ write_upstream_fixture() {
        "$repo/.private-journal" \
        "$repo/assets" \
        "$repo/evals/drill" \
+        "$repo/hooks" \
        "$repo/scripts" \
        "$repo/skills/example"

@@ -218,6 +219,36 @@ EOF
    printf 'png fixture\n' > "$repo/assets/app-icon.png"
    printf 'eval harness fixture\n' > "$repo/evals/drill/README.md"

+    cat > "$repo/hooks/hooks-codex.json" <<'EOF'
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+
+    cat > "$repo/hooks/session-start" <<'EOF'
+#!/usr/bin/env sh
+echo "session-start fixture"
+EOF
+
+    cat > "$repo/hooks/run-hook.cmd" <<'EOF'
+@echo off
+echo run-hook fixture
+EOF
+    chmod +x "$repo/hooks/session-start" "$repo/hooks/run-hook.cmd"
+
    cat > "$repo/skills/example/SKILL.md" <<'EOF'
 # Example Skill

@@ -236,6 +267,9 @@ EOF
        assets/app-icon.png \
        assets/superpowers-small.svg \
        evals/drill/README.md \
+        hooks/hooks-codex.json \
+        hooks/run-hook.cmd \
+        hooks/session-start \
        package.json \
        scripts/sync-to-codex-plugin.sh \
        skills/example/SKILL.md
@@ -293,6 +327,7 @@ write_synced_destination_fixture() {
        "$repo/plugins/superpowers/.codex-plugin" \
        "$repo/plugins/superpowers/.private-journal" \
        "$repo/plugins/superpowers/assets" \
+        "$repo/plugins/superpowers/hooks" \
        "$repo/plugins/superpowers/skills/example/agents" \
        "$repo/plugins/superpowers/skills/example"

@@ -309,6 +344,36 @@ EOF

    printf 'png fixture\n' > "$repo/plugins/superpowers/assets/app-icon.png"

+    cat > "$repo/plugins/superpowers/hooks/hooks-codex.json" <<'EOF'
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+
+    cat > "$repo/plugins/superpowers/hooks/session-start" <<'EOF'
+#!/usr/bin/env sh
+echo "session-start fixture"
+EOF
+
+    cat > "$repo/plugins/superpowers/hooks/run-hook.cmd" <<'EOF'
+@echo off
+echo run-hook fixture
+EOF
+    chmod +x "$repo/plugins/superpowers/hooks/session-start" "$repo/plugins/superpowers/hooks/run-hook.cmd"
+
    cat > "$repo/plugins/superpowers/skills/example/SKILL.md" <<'EOF'
 # Example Skill

@@ -327,6 +392,9 @@ EOF
        plugins/superpowers/.codex-plugin/plugin.json \
        plugins/superpowers/assets/app-icon.png \
        plugins/superpowers/assets/superpowers-small.svg \
+        plugins/superpowers/hooks/hooks-codex.json \
+        plugins/superpowers/hooks/run-hook.cmd \
+        plugins/superpowers/hooks/session-start \
        plugins/superpowers/skills/example/agents/openai.yaml \
        plugins/superpowers/skills/example/SKILL.md \
        plugins/superpowers/.private-journal/keep.txt
@@ -542,6 +610,9 @@ main() {
    assert_contains "$preview_section" ".codex-plugin/plugin.json" "Preview includes manifest path"
    assert_contains "$preview_section" "assets/superpowers-small.svg" "Preview includes SVG asset"
    assert_contains "$preview_section" "assets/app-icon.png" "Preview includes PNG asset"
+    assert_contains "$preview_section" "hooks/hooks-codex.json" "Preview includes Codex hook manifest"
+    assert_contains "$preview_section" "hooks/session-start" "Preview includes session-start hook"
+    assert_contains "$preview_section" "hooks/run-hook.cmd" "Preview includes hook command wrapper"
    assert_contains "$preview_section" ".private-journal/keep.txt" "Preview includes tracked ignored file"
    assert_not_contains "$preview_section" ".private-journal/leak.txt" "Preview excludes ignored untracked file"
    assert_not_contains "$preview_section" "ignored-cache/" "Preview excludes pure ignored directories"
--- a/tests/hooks/test-session-start.sh
+++ b/tests/hooks/test-session-start.sh
@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+HOOK_UNDER_TEST="$REPO_ROOT/hooks/session-start"
+WRAPPER_UNDER_TEST="$REPO_ROOT/hooks/run-hook.cmd"
+
+FAILURES=0
+TEST_ROOT="$(mktemp -d)"
+
+cleanup() {
+    rm -rf "$TEST_ROOT"
+}
+trap cleanup EXIT
+
+pass() {
+    echo "  [PASS] $1"
+}
+
+fail() {
+    echo "  [FAIL] $1"
+    FAILURES=$((FAILURES + 1))
+}
+
+make_home() {
+    local name="$1"
+    local home="$TEST_ROOT/$name/home"
+    mkdir -p "$home"
+    printf '%s\n' "$home"
+}
+
+assert_command_output() {
+    local description="$1"
+    local shape="$2"
+    local contains="$3"
+    local not_contains="$4"
+    local home="$5"
+    shift 5
+
+    local output
+    if ! output="$(env -i PATH="${PATH:-}" HOME="$home" "$@" 2>&1)"; then
+        fail "$description"
+        echo "    hook exited non-zero"
+        echo "$output" | sed 's/^/      /'
+        return
+    fi
+
+    if printf '%s' "$output" | \
+        EXPECT_SHAPE="$shape" \
+        EXPECT_CONTAINS="$contains" \
+        EXPECT_NOT_CONTAINS="$not_contains" \
+        node -e '
+const fs = require("fs");
+
+const input = fs.readFileSync(0, "utf8");
+let payload;
+try {
+  payload = JSON.parse(input);
+} catch (error) {
+  console.error(`invalid JSON: ${error.message}`);
+  process.exit(1);
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+const shape = process.env.EXPECT_SHAPE;
+let context;
+
+if (shape === "nested") {
+  if (!hasOwn(payload, "hookSpecificOutput")) {
+    fail("missing hookSpecificOutput");
+  }
+  if (hasOwn(payload, "additional_context") || hasOwn(payload, "additionalContext")) {
+    fail("nested output also included a top-level context field");
+  }
+  const hookOutput = payload.hookSpecificOutput;
+  if (!hookOutput || typeof hookOutput !== "object" || Array.isArray(hookOutput)) {
+    fail("hookSpecificOutput is not an object");
+  }
+  if (hookOutput.hookEventName !== "SessionStart") {
+    fail(`unexpected hookEventName: ${hookOutput.hookEventName}`);
+  }
+  context = hookOutput.additionalContext;
+} else if (shape === "cursor") {
+  if (hasOwn(payload, "hookSpecificOutput")) {
+    fail("cursor output included hookSpecificOutput");
+  }
+  if (!hasOwn(payload, "additional_context")) {
+    fail("cursor output missing additional_context");
+  }
+  if (hasOwn(payload, "additionalContext")) {
+    fail("cursor output included additionalContext");
+  }
+  context = payload.additional_context;
+} else if (shape === "sdk") {
+  if (hasOwn(payload, "hookSpecificOutput")) {
+    fail("sdk output included hookSpecificOutput");
+  }
+  if (!hasOwn(payload, "additionalContext")) {
+    fail("sdk output missing additionalContext");
+  }
+  if (hasOwn(payload, "additional_context")) {
+    fail("sdk output included additional_context");
+  }
+  context = payload.additionalContext;
+} else {
+  fail(`unknown expected shape: ${shape}`);
+}
+
+if (typeof context !== "string" || context.trim() === "") {
+  fail("injected context was empty");
+}
+
+const expectedText = process.env.EXPECT_CONTAINS || "";
+if (expectedText && !context.includes(expectedText)) {
+  fail(`context did not contain expected text: ${expectedText}`);
+}
+
+const forbiddenTexts = (process.env.EXPECT_NOT_CONTAINS || "")
+  .split("\u001f")
+  .filter(Boolean);
+for (const forbiddenText of forbiddenTexts) {
+  if (context.includes(forbiddenText)) {
+    fail(`context contained forbidden text: ${forbiddenText}`);
+  }
+}
+'; then
+        pass "$description"
+    else
+        fail "$description"
+        echo "    output:"
+        echo "$output" | sed 's/^/      /'
+    fi
+}
+
+echo "SessionStart hook output tests"
+
+claude_home="$(make_home claude-code)"
+assert_command_output \
+    "Claude Code emits nested SessionStart additionalContext" \
+    "nested" \
+    "" \
+    "" \
+    "$claude_home" \
+    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"
+assert_command_output \
+    "Codex plugin hooks emit nested SessionStart additionalContext" \
+    "nested" \
+    "" \
+    "" \
+    "$codex_home" \
+    PLUGIN_DATA="$codex_data" \
+    CLAUDE_PLUGIN_DATA="$codex_data" \
+    PLUGIN_ROOT="$REPO_ROOT" \
+    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+    bash "$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 emits nested SessionStart additionalContext" \
+    "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
+
+cursor_home="$(make_home cursor)"
+assert_command_output \
+    "Cursor emits top-level additional_context only" \
+    "cursor" \
+    "" \
+    "" \
+    "$cursor_home" \
+    CURSOR_PLUGIN_ROOT="$REPO_ROOT" \
+    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+    bash "$HOOK_UNDER_TEST"
+
+copilot_home="$(make_home copilot-cli)"
+assert_command_output \
+    "Copilot CLI emits top-level additionalContext only" \
+    "sdk" \
+    "" \
+    "" \
+    "$copilot_home" \
+    COPILOT_CLI=1 \
+    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+    bash "$HOOK_UNDER_TEST"
+
+claude_legacy_home="$(make_home claude-legacy-warning)"
+mkdir -p "$claude_legacy_home/.config/superpowers/skills"
+assert_command_output \
+    "Claude legacy warning points custom skills to ~/.claude/skills" \
+    "nested" \
+    "Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.claude/skills instead." \
+    "" \
+    "$claude_legacy_home" \
+    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+    bash "$HOOK_UNDER_TEST"
+
+codex_legacy_home="$(make_home codex-legacy-warning)"
+codex_legacy_data="$TEST_ROOT/codex-legacy-warning/data"
+mkdir -p "$codex_legacy_home/.config/superpowers/skills" "$codex_legacy_data"
+assert_command_output \
+    "Codex legacy warning uses harness-neutral custom-skill wording" \
+    "nested" \
+    "WARNING: Superpowers now uses your coding agent's native skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to a skills location supported by your coding agent. To make this message go away, remove ~/.config/superpowers/skills" \
+    "~/.claude/skills"$'\037'"Claude Code's skills system" \
+    "$codex_legacy_home" \
+    PLUGIN_DATA="$codex_legacy_data" \
+    CLAUDE_PLUGIN_DATA="$codex_legacy_data" \
+    PLUGIN_ROOT="$REPO_ROOT" \
+    CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+    bash "$HOOK_UNDER_TEST"
+
+if [[ "$FAILURES" -gt 0 ]]; then
+    echo "STATUS: FAILED ($FAILURES failure(s))"
+    exit 1
+fi
+
+echo "STATUS: PASSED"