Skip to content

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.md
index 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 markers
diff --git a/plugins/worktrunk/.codex-plugin/plugin.json b/plugins/worktrunk/.codex-plugin/plugin.json
index 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.md
index 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 hooks
Claude'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 by
The 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.md
index 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 markers
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index 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 markers
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 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.
## Examples
diff --git a/src/commands/config/codex.rs b/src/commands/config/codex.rs
index 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.rs
index 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.snap
index 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: file
LANG: C
LC_ALL: C
LLVM_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: wt config plugins codex [OPTIONS] <COMMAND>[0
-y, --yes
Skip 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 wt list 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 wt list while a Codex session runs and clear the marker when it ends.
Examples