Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat(plugin): Claude-scope the shared hooks payload (#3382)
Worktrunk Bot2677f05d0ce1
diff --git a/plugins/worktrunk/CLAUDE.md b/plugins/worktrunk/CLAUDE.mdindex 4314ae25d..a9d7e4154 100644--- a/plugins/worktrunk/CLAUDE.md+++ b/plugins/worktrunk/CLAUDE.md@@ -19,7 +19,9 @@ worktrunk/ ← repo root = marketplace root├── plugin.json ← Claude manifest (NO .claude-plugin/ wrapper —│ the wrapper is marketplace-root-only)├── .codex-plugin/plugin.json ← Codex manifest (Codex's required wrapper)- ├── hooks/hooks.json ← Claude activity + WorktreeCreate/Remove hooks+ ├── hooks/claude-hooks.json ← Claude activity + WorktreeCreate/Remove hooks+ │ (Claude-scoped name — a plain hooks/hooks.json+ │ would be auto-discovered by Codex, see #3362)├── hooks/wt.sh ← canonical hook shim; Claude reaches it via│ $CLAUDE_PLUGIN_ROOT, Codex via $PLUGIN_ROOT,│ Gemini via@@ -69,9 +71,9 @@ The 💬 transitions overlap deliberately: `Notification` covers the documented### Codex activity hooks (marker persists after session end)-The Claude manifest carries `hooks: "./hooks/hooks.json"` (a path); the Codex manifest carries `hooks` as an **inline object**, `{ "hooks": { … } }`, embedding a Codex-tailored hooks file directly. The distinction is deliberate:+The Claude manifest carries `hooks: "./hooks/claude-hooks.json"` (a path); the Codex manifest carries `hooks` as an **inline object**, `{ "hooks": { … } }`, embedding a Codex-tailored hooks file directly. The distinction is deliberate:-- **Why inline, not a path or an absent key.** Claude and Codex share one payload dir. If the Codex manifest omitted `hooks`, Codex would auto-discover `hooks/hooks.json` from the plugin root by convention (`DEFAULT_HOOKS_CONFIG_FILE`, the `None` branch of `load_plugin_hooks`) and surface Worktrunk's *Claude* events in a Codex session ([#3362](https://github.com/max-sixty/worktrunk/issues/3362)). An inline object takes Codex's `Some(Inline)` branch (`resolve_manifest_hooks` in `codex-rs/core-plugins/src/manifest.rs`), which overrides discovery — so the shared Claude file is never loaded and only these Codex-native events fire. Inline keeps the definition self-contained and avoids a second file that could collide with `hooks/hooks.json`.+- **Why inline, not a path or an absent key.** Claude and Codex share one payload dir, and Codex auto-discovers a `hooks/hooks.json` at the plugin root by convention (`DEFAULT_HOOKS_CONFIG_FILE`, the `None` branch of `load_plugin_hooks`). Historically the Claude hooks lived at exactly that path, so a Codex session surfaced Worktrunk's *Claude* events ([#3362](https://github.com/max-sixty/worktrunk/issues/3362)). Two independent things now keep a Codex session clean: (1) the Claude file is **Claude-scoped** — `hooks/claude-hooks.json`, not the conventional `hooks/hooks.json` — so Codex's discovery lookup finds nothing at the plugin root; and (2) the Codex manifest carries its own hooks **inline**, taking Codex's `Some(Inline)` branch (`resolve_manifest_hooks` in `codex-rs/core-plugins/src/manifest.rs`). The inline object is the functional definition of the Codex-native events *and* overrides discovery, so even if a `hooks/hooks.json` ever reappeared at the plugin root it would not be loaded. The Claude-scoped filename makes the #3362 collision structurally impossible; the inline manifest is what actually drives Codex's markers.- **Why `$PLUGIN_ROOT`, not `$CLAUDE_PLUGIN_ROOT`.** Codex exports both to hook commands (`PLUGIN_ROOT` native, `CLAUDE_PLUGIN_ROOT` as an OOTB-compat alias — `codex-rs/hooks/src/engine/discovery.rs`). The Codex file uses the native `$PLUGIN_ROOT` so nothing Claude-branded appears in a Codex session.The events (Codex's `HookEventsToml` vocabulary, verified against `codex-rs/config/src/hook_config.rs`):diff --git a/plugins/worktrunk/hooks/hooks.json b/plugins/worktrunk/hooks/claude-hooks.jsonsimilarity index 100%rename from plugins/worktrunk/hooks/hooks.jsonrename to plugins/worktrunk/hooks/claude-hooks.jsondiff --git a/plugins/worktrunk/plugin.json b/plugins/worktrunk/plugin.jsonindex 9c74683d7..e05663bfd 100644--- a/plugins/worktrunk/plugin.json+++ b/plugins/worktrunk/plugin.json@@ -4,7 +4,7 @@"author": {"name": "Worktrunk"},- "hooks": "./hooks/hooks.json",+ "hooks": "./hooks/claude-hooks.json","skills": ["./skills/worktrunk","./skills/wt-switch-create"diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rsindex f44dd7996..e60d64bec 100644--- a/tests/integration_tests/config_show.rs+++ b/tests/integration_tests/config_show.rs@@ -3848,13 +3848,16 @@ fn test_codex_plugin_metadata_is_valid_json() {"plugin.json interface.websiteURL must point at the canonical site");// The Codex plugin ships activity-marker hooks *inline* in its manifest- // (`hooks` object, not a path). This is deliberate: an absent `hooks` key- // makes Codex auto-discover the shared `hooks/hooks.json` (which is the- // *Claude* plugin's) and surface Claude-branded events in a Codex session- // (#3362). An inline object takes Codex's `Some(Inline)` branch, overriding- // discovery so only these Codex-native events fire. Codex added a `Stop`- // turn-end event (post codex-cli 0.130.0), so 🤖 returns to 💬 at turn end.- // See CLAUDE.md → "Plugin Layout".+ // (`hooks` object, not a path). This is the functional definition of its+ // Codex-native events, and it also overrides Codex's convention discovery+ // (an absent `hooks` key makes Codex auto-discover a `hooks/hooks.json` at+ // the plugin root). The Claude hooks file is Claude-scoped+ // (`hooks/claude-hooks.json`), so that discovery lookup finds nothing — the+ // #3362 collision (Codex surfacing the *Claude* file's events) is gone+ // structurally, and inline still overrides discovery should any file+ // reappear at the conventional path. Codex added a `Stop` turn-end event+ // (post codex-cli 0.130.0), so 🤖 returns to 💬 at turn end. See CLAUDE.md+ // → "Plugin Layout".let codex_hooks = plugin.get("hooks").and_then(|h| h.get("hooks"))@@ -3881,7 +3884,7 @@ fn test_codex_plugin_metadata_is_valid_json() {"Codex hooks must not reference the Claude-branded $CLAUDE_PLUGIN_ROOT alias");// Hooks are inline, so the wrapper dir still holds only plugin.json — no- // separate hooks file to collide with the Claude `hooks/hooks.json`.+ // separate hooks file to collide with the Claude `hooks/claude-hooks.json`.assert!(!project_root.join("plugins/worktrunk/.codex-plugin/hooks")@@ -3940,15 +3943,26 @@ fn test_plugin_layout_is_consolidated() {// Claude manifest at the plugin root (no wrapper); hooks relative to it.let claude = json("plugins/worktrunk/plugin.json");- assert_eq!(claude["hooks"], "./hooks/hooks.json");+ assert_eq!(claude["hooks"], "./hooks/claude-hooks.json");assert!(- root.join("plugins/worktrunk/hooks/hooks.json").exists()+ root.join("plugins/worktrunk/hooks/claude-hooks.json")+ .exists()&& root.join("plugins/worktrunk/hooks/wt.sh").exists(),"Claude hooks must live at the plugin root's hooks/");+ // The Claude hooks file is Claude-scoped (claude-hooks.json), NOT the+ // conventional hooks/hooks.json. A file at that conventional plugin-root+ // path would be auto-discovered by Codex's convention loader and resurface+ // the #3362 collision; the Claude-scoped name makes that impossible+ // structurally rather than only overriding it inline in the Codex manifest.assert!(- !read("plugins/worktrunk/hooks/hooks.json").contains(".claude-plugin/hooks/"),- "hooks.json must reference $CLAUDE_PLUGIN_ROOT/hooks/wt.sh, not the old wrapper path"+ !root.join("plugins/worktrunk/hooks/hooks.json").exists(),+ "the Claude hooks file must be Claude-scoped (hooks/claude-hooks.json), not the \+ conventional hooks/hooks.json that Codex would auto-discover (#3362)"+ );+ assert!(+ !read("plugins/worktrunk/hooks/claude-hooks.json").contains(".claude-plugin/hooks/"),+ "claude-hooks.json must reference $CLAUDE_PLUGIN_ROOT/hooks/wt.sh, not the old wrapper path");// The description is duplicated across the Claude marketplace pointer and@@ -4024,8 +4038,8 @@ fn test_plugin_layout_is_consolidated() {// `--force-delete` silently discards committed-but-unpushed work — the only// recovery path is `git fsck`. The safe default retains unmerged branches// and prints a `wt remove -D <branch>` hint for the user to act on.- let hooks = read("plugins/worktrunk/hooks/hooks.json");- let hooks_json = json("plugins/worktrunk/hooks/hooks.json");+ let hooks = read("plugins/worktrunk/hooks/claude-hooks.json");+ let hooks_json = json("plugins/worktrunk/hooks/claude-hooks.json");// Claude hands each hook command to the user's LOGIN shell before `bash`// launches, so the outer command line must parse under fish/zsh/bash. fish@@ -4103,7 +4117,7 @@ fn test_plugin_layout_is_consolidated() {fn test_claude_hook_commands_parse_in_all_shells() {let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));let hooks_json: serde_json::Value = serde_json::from_str(- &fs::read_to_string(root.join("plugins/worktrunk/hooks/hooks.json")).unwrap(),+ &fs::read_to_string(root.join("plugins/worktrunk/hooks/claude-hooks.json")).unwrap(),).unwrap();