fix(codex): ship hook release safely

Move Codex native hook metadata under the Codex-only plugin directory so Claude keeps using only its inline `bd prime` hooks.

Leave release version bumps to the maintainer release flow while documenting hook metadata isolation under Unreleased.

Refs #3924.

_codex-gpt-5.5-medium on behalf of matt wilkie_
This commit is contained in:
Chris DiMartino 2026-05-27 16:19:41 -04:00 • committed by GitHub
commit 0afd3d5b94
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 20 additions and 5 deletions

View file

@ -39,6 +39,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
- **Codex hook metadata isolation** - Codex hook metadata now lives under
`.codex-plugin/hooks/`, preventing Claude from loading Codex-only hooks from
the shared plugin root while keeping Codex setup pointed at `bd codex-hook`.
([#3924](https://github.com/gastownhall/beads/issues/3924))
- **JSONL auto-export shrink guard** - when opt-in `export.auto` is enabled,
auto-export now refuses to overwrite an existing `.beads/issues.jsonl` that
contains records outside the auto-export scope (memories, infrastructure

View file

@ -55,7 +55,8 @@ func TestPluginLayoutUsesSharedBeadsRoot(t *testing.T) {
requireRepoFile(t, root, "plugins", "beads", "skills", "beads", "agents", "openai.yaml")
requireRepoFile(t, root, "plugins", "beads", "agents", "task-agent.md")
requireRepoFile(t, root, "plugins", "beads", "skills", "beads", "commands", "ready.md")
requireRepoFile(t, root, "plugins", "beads", "hooks", "hooks.json")
requireRepoFile(t, root, "plugins", "beads", ".codex-plugin", "hooks", "hooks.json")
requireNoRepoPath(t, root, "plugins", "beads", "hooks", "hooks.json")
}
func readJSONFile(t *testing.T, path string, dest interface{}) {
@ -78,3 +79,13 @@ func requireRepoFile(t *testing.T, root string, parts ...string) {
t.Fatalf("expected file %s, got directory", path)
}
}
func requireNoRepoPath(t *testing.T, root string, parts ...string) {
t.Helper()
path := filepath.Join(append([]string{root}, parts...)...)
if _, err := os.Stat(path); err == nil {
t.Fatalf("expected path %s not to exist", path)
} else if !os.IsNotExist(err) {
t.Fatalf("stat %s: %v", path, err)
}
}

View file

@ -19,7 +19,7 @@ Global setup uses `bd setup codex --global` and writes under `$CODEX_HOME` when
## Plugin-Managed Hooks
The bundled Codex plugin declares `"hooks": "./hooks/hooks.json"` in `plugins/beads/.codex-plugin/plugin.json`. On Codex 0.129.0+, use `/hooks` to inspect or toggle these handlers.
The bundled Codex plugin keeps its hook config at `plugins/beads/.codex-plugin/hooks/hooks.json`; `plugins/beads/.codex-plugin/plugin.json` declares it as `"hooks": "./hooks/hooks.json"`. On Codex 0.129.0+, use `/hooks` to inspect or toggle these handlers.
The plugin and `bd setup codex` fallback install the same lifecycle:

View file

@ -7,12 +7,12 @@ This is the shared Claude/Codex plugin package for Beads. Claude and Codex use s
- `.codex-plugin/plugin.json` describes the Codex plugin.
- `.claude-plugin/plugin.json` describes the Claude plugin.
- `skills/beads/` contains the plugin-owned Beads skill.
- `hooks/hooks.json` contains Codex native lifecycle hooks for startup and compaction-aware context refresh.
- `.codex-plugin/hooks/hooks.json` contains Codex-only lifecycle hooks for startup and compaction-aware context refresh.
- The Claude marketplace entry lives at `.claude-plugin/marketplace.json`.
## Codex Hooks
The Codex plugin exposes native hooks through `.codex-plugin/plugin.json`.
The Codex plugin exposes native hooks through `.codex-plugin/plugin.json`, which points at `.codex-plugin/hooks/hooks.json`.
With Codex 0.129.0+, `/hooks` shows these lifecycle handlers:
- `SessionStart` runs `bd codex-hook SessionStart` for `startup|resume|clear` and injects full `bd prime` output.

View file

@ -24,4 +24,4 @@ Codex 0.129.0+ supports `/hooks`, compact lifecycle hooks, and hook-provided dev
`PreCompact` alone does not inject context because Codex ignores plain stdout from compact hooks. The post-compact marker plus first-prompt refresh is the reliable recovery path.
The Beads Codex plugin declares `"hooks": "./hooks/hooks.json"`. Without the plugin, `bd setup codex` installs the same hook config in `.codex/hooks.json` and enables `[features].hooks = true`.
The Beads Codex plugin stores hooks at `plugins/beads/.codex-plugin/hooks/hooks.json` and declares them as `"hooks": "./hooks/hooks.json"`. Without the plugin, `bd setup codex` installs the same hook config in `.codex/hooks.json` and enables `[features].hooks = true`.