Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
fix(codex): clear activity marker on session end (#3660)
Maximilian Rooscfd6f099bcf6
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.mdindex c7093a673..1ed929d8d 100644--- a/docs/content/claude-code.md+++ b/docs/content/claude-code.md@@ -16,7 +16,7 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de| Worktree isolation | ✓ | | | || `/wt-switch-create` command | ✓ | | | |-The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own turn-end (`Stop`) hook, but has no session-exit event, so a marker persists after a Codex session ends until the next session or a manual `wt config state marker clear`.+The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own `Stop` and `SessionEnd` hooks.## Installation@@ -83,7 +83,7 @@ The Claude Code, Codex, OpenCode, and Gemini plugins track agent sessions with s- 🤖 — agent is working- 💬 — agent is waiting or idle-The Claude Code, OpenCode, and Gemini plugins clear the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs. Codex exposes no session-exit event, so its marker always persists after a session ends. In every case, `wt config state marker clear` removes a marker manually.+All four plugins clear the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs. In every case, `wt config state marker clear` removes a marker manually.### Manual status markersdiff --git a/plugins/worktrunk/.codex-plugin/plugin.json b/plugins/worktrunk/.codex-plugin/plugin.jsonindex 300eb4fab..0378314fa 100644--- a/plugins/worktrunk/.codex-plugin/plugin.json+++ b/plugins/worktrunk/.codex-plugin/plugin.json@@ -41,6 +41,17 @@}]}+ ],+ "SessionEnd": [+ {+ "hooks": [+ {+ "type": "command",+ "command": "bash \"$PLUGIN_ROOT/hooks/wt.sh\" config state marker clear || true",+ "timeout": 3+ }+ ]+ }]}},diff --git a/plugins/worktrunk/CLAUDE.md b/plugins/worktrunk/CLAUDE.mdindex 18b8ff59f..9abd5fc81 100644--- a/plugins/worktrunk/CLAUDE.md+++ b/plugins/worktrunk/CLAUDE.md@@ -126,7 +126,7 @@ The 💬 transitions overlap deliberately: `Notification` covers the documented**Tracking**: [claude-code#9516](https://github.com/anthropics/claude-code/issues/9516)-### Codex activity hooks (marker persists after session end)+### Codex activity hooksClaude's hooks live in the standalone `hooks/hooks.json` its loader discovers by convention (see Directory Layout above); the Codex manifest carries `hooks` as an **inline object**, `{ "hooks": { … } }`, embedding a Codex-tailored hooks file directly. The inline form is deliberate:@@ -136,10 +136,9 @@ Claude's hooks live in the standalone `hooks/hooks.json` its loader discovers byThe events (Codex's `HookEventsToml` vocabulary, verified against `codex-rs/config/src/hook_config.rs`):- `UserPromptSubmit` → 🤖 (working)- `PermissionRequest`, `Stop` → 💬 (waiting for input)+- `SessionEnd` → clears the marker-`Stop` fires at turn-end (Codex added it after codex-cli 0.130.0, which had no turn-end event), so 🤖 correctly returns to 💬 when a turn completes — the transition the earlier "no turn-end event" limitation lacked.--**Limitation — marker persists after the session ends.** Codex's `HookEventsToml` has **no `SessionEnd`/session-exit event**, so there is no hook to *clear* the marker when a Codex session exits. The resting state after a normal exit is 💬 (set by the last `Stop`), which reads as "waiting for input" and lingers until the next session or a manual `wt config state marker clear`. This is the same class of limitation already documented above for Claude ("Status persists after user interrupt") — an accepted tradeoff, not a regression. If Codex later adds a session-exit event, add a `marker clear` handler for it here.+`Stop` fires at turn-end, so 🤖 returns to 💬 when a turn completes. `SessionEnd` clears the marker when the main thread ends.### Accepted tradeoff: shared `skills/` exposes `wt-switch-create`diff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.mdindex 839a78757..19ee77156 100644--- a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md+++ b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md@@ -9,7 +9,7 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de| Worktree isolation | ✓ | | | || `/wt-switch-create` command | ✓ | | | |-The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own turn-end (`Stop`) hook, but has no session-exit event, so a marker persists after a Codex session ends until the next session or a manual `wt config state marker clear`.+The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own `Stop` and `SessionEnd` hooks.## Installation@@ -85,7 +85,7 @@ $ wt list- 🤖 — agent is working- 💬 — agent is waiting or idle-The Claude Code, OpenCode, and Gemini plugins clear the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs. Codex exposes no session-exit event, so its marker always persists after a session ends. In every case, `wt config state marker clear` removes a marker manually.+All four plugins clear the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs. In every case, `wt config state marker clear` removes a marker manually.### Manual status markersdiff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.mdindex 839a78757..19ee77156 100644--- a/skills/worktrunk/reference/claude-code.md+++ b/skills/worktrunk/reference/claude-code.md@@ -9,7 +9,7 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de| Worktree isolation | ✓ | | | || `/wt-switch-create` command | ✓ | | | |-The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own turn-end (`Stop`) hook, but has no session-exit event, so a marker persists after a Codex session ends until the next session or a manual `wt config state marker clear`.+The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks and `/wt-switch-create` needs session working-directory switching — both Claude Code-only, so Codex, OpenCode, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own `Stop` and `SessionEnd` hooks.## Installation@@ -85,7 +85,7 @@ $ wt list- 🤖 — agent is working- 💬 — agent is waiting or idle-The Claude Code, OpenCode, and Gemini plugins clear the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs. Codex exposes no session-exit event, so its marker always persists after a session ends. In every case, `wt config state marker clear` removes a marker manually.+All four plugins clear the marker when a session ends. A stale marker can remain if the agent process is killed before its session-end hook runs. In every case, `wt config state marker clear` removes a marker manually.### Manual status markersdiff --git a/src/cli/config.rs b/src/cli/config.rsindex 0dca5fbe1..d793e5ae1 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -305,7 +305,7 @@ $ wt config plugins claude install-statusline/// Codex plugin#[command(- after_long_help = r#"Bundles a configuration skill — documentation Codex can read to help set up LLM commits, project hooks, and worktree paths — plus activity-marker hooks that show 🤖/💬 in `wt list` while a Codex session runs. Codex has no session-exit event, so a marker persists after a session ends.+ after_long_help = r#"Bundles a configuration skill — documentation Codex can read to help set up LLM commits, project hooks, and worktree paths — plus activity-marker hooks that show 🤖/💬 in `wt list` while a Codex session runs and clear the marker when it ends.## Examplesdiff --git a/src/commands/config/codex.rs b/src/commands/config/codex.rsindex 6b89156ba..6d44b7483 100644--- a/src/commands/config/codex.rs+++ b/src/commands/config/codex.rs@@ -39,10 +39,9 @@ pub fn handle_codex_install(yes: bool) -> Result<()> {hint_message("Next, run /plugins in Codex and install Worktrunk from the marketplace"));// The Codex plugin ships activity-marker hooks inline in its manifest- // (`hooks` key in .codex-plugin/plugin.json), using Codex's native `Stop`- // turn-end event to return 🤖 → 💬. Codex has no session-exit event, so the- // marker persists after a session ends (documented tradeoff). See CLAUDE.md- // → "Plugin Layout".+ // (`hooks` key in .codex-plugin/plugin.json), using `Stop` to return+ // 🤖 → 💬 and `SessionEnd` to clear the marker. See CLAUDE.md → "Plugin+ // Layout".eprintln!("{}",hint_message(cformat!(diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rsindex 898653b1c..3b6c4e3b3 100644--- a/tests/integration_tests/config_show.rs+++ b/tests/integration_tests/config_show.rs@@ -4081,22 +4081,37 @@ fn test_codex_plugin_metadata_is_valid_json() {// the plugin root). The Claude hooks file sits at that same conventional// `hooks/hooks.json` (Claude's loader discovers it there — #3417), but the// inline Codex override means Codex never loads it, so the #3362 collision- // (Codex surfacing the *Claude* file's events) stays closed. Codex added a- // `Stop` turn-end event (post codex-cli 0.130.0), so 🤖 returns to 💬 at- // turn end. See CLAUDE.md → "Plugin Layout".+ // (Codex surfacing the *Claude* file's events) stays closed. `Stop`+ // returns 🤖 to 💬 at turn end, and `SessionEnd` clears the marker when+ // the main thread ends. See CLAUDE.md → "Plugin Layout".let codex_hooks = plugin.get("hooks").and_then(|h| h.get("hooks")).expect("Codex manifest must carry an inline `hooks` object");- // Exactly the Codex-native events — no `Notification`/`SessionEnd`/- // `WorktreeCreate`/`WorktreeRemove`, which are Claude-only and would be- // silently dropped by Codex.- for event in ["UserPromptSubmit", "PermissionRequest", "Stop"] {- assert!(- codex_hooks.get(event).is_some(),- "Codex hooks must define the {event} event"- );- }+ // Exactly the Codex-native events — no Claude-only `Notification`,+ // `WorktreeCreate`, or `WorktreeRemove`.+ let mut events = codex_hooks+ .as_object()+ .unwrap()+ .keys()+ .map(String::as_str)+ .collect::<Vec<_>>();+ events.sort_unstable();+ assert_eq!(+ events,+ [+ "PermissionRequest",+ "SessionEnd",+ "Stop",+ "UserPromptSubmit"+ ]+ );+ let session_end = &codex_hooks["SessionEnd"][0]["hooks"][0];+ assert_eq!(+ session_end["command"],+ r#"bash "$PLUGIN_ROOT/hooks/wt.sh" config state marker clear || true"#+ );+ assert_eq!(session_end["timeout"], 3);// Commands use Codex's native `$PLUGIN_ROOT`, never the Claude-branded// `$CLAUDE_PLUGIN_ROOT` compat alias — nothing Claude-branded in a Codex// session (#3362).diff --git a/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snap b/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snapindex 2cf1691ff..7b3272fb9 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_plugins_codex.snap@@ -10,6 +10,7 @@ info:env:CLICOLOR_FORCE: "1"COLUMNS: "500"+ GIT_ALLOW_PROTOCOL: fileLANG: CLC_ALL: CLLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"@@ -26,6 +27,7 @@ info:WORKTRUNK_TEST_GEMINI_INSTALLED: "0"WORKTRUNK_TEST_NUSHELL_ENV: "0"WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"+ WORKTRUNK_TEST_PARENT_SHELL: ""WORKTRUNK_TEST_POWERSHELL_ENV: "0"WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"@@ -62,7 +64,7 @@ Usage: [1m[36mwt config plugins codex[0m [36m[OPTIONS][0m [36m<COMMAND>[0[1m[36m-y[0m, [1m[36m--yes[0mSkip approval prompts-Bundles a configuration skill — documentation Codex can read to help set up LLM commits, project hooks, and worktree paths — plus activity-marker hooks that show 🤖/💬 in [2mwt list[0m while a Codex session runs. Codex has no session-exit event, so a marker persists after a session ends.+Bundles a configuration skill — documentation Codex can read to help set up LLM commits, project hooks, and worktree paths — plus activity-marker hooks that show 🤖/💬 in [2mwt list[0m while a Codex session runs and clear the marker when it ends.[1m[32mExamples[0m