From 3ede3cbc33366361477afcaafab3338a976f3686 Mon Sep 17 00:00:00 2001 From: Tyce Herrman Date: Wed, 29 Jul 2026 17:36:41 -0400 Subject: [PATCH] Docs: use SessionEnd for Codex hook cleanup (#1733) * Docs: use SessionEnd for Codex hook cleanup * Docs: note legacy Codex Stop issue --- CHANGELOG.md | 1 + docs/02-usage/030_clients.md | 8 +++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 76021f64..8ba8a4e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,7 @@ Status of the `main` branch. Changes prior to the next official version change w * Hooks: - Add `serena-hooks --client=grok`, including Grok-native PreToolUse allow/deny output. + - Use `SessionEnd` for Codex 0.145.0+ cleanup hooks and document the known `Stop` compatibility issue affecting older Codex versions. - PreToolUse remind hook: coerce non-string shell command values instead of failing, and recognize `target_file`/`targetFile` file-path keys (shared payload parsing, applies to all hook clients). - Fix hook input parsing for clients that emit raw control characters in JSON string values #1743. diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index 3a7f2980..c6a51846 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -355,7 +355,7 @@ Then create `~/.codex/hooks.json` with the following content: ] } ], - "Stop": [ + "SessionEnd": [ { "hooks": [ { @@ -369,6 +369,12 @@ Then create `~/.codex/hooks.json` with the following content: } ``` +The `SessionEnd` cleanup hook requires Codex 0.145.0 or newer. Older Codex versions only support +`Stop` for cleanup, which currently has a [known compatibility issue](https://github.com/oraios/serena/issues/1533). +If you still configure it, replace `SessionEnd` with `Stop` in the example above. Configure cleanup +under exactly one of these events, never both: `Stop` runs after every turn, while `SessionEnd` runs +when Codex tears down the root thread. + The hooks will: - **`activate`**: Prompt the agent to activate the current project and read Serena's instructions