Merge pull request #5 from gaelic-ghost/release/codex-hooks-v3-2-4

release: prepare v3.2.4

Author: gaelic-ghost

.codex/config.toml

@@ -1,7 +1,7 @@
 #:schema https://developers.openai.com/codex/config-schema.json
 
-[features]
-codex_hooks = true
-
 # Experimental probe: record whatever payload Codex sends to the notify command.
 notify = ["node", ".codex/hooks/notify-dump.mjs"]
+
+[features]
+codex_hooks = true

.codex/hooks/notify-dump.mjs

@@ -2,8 +2,10 @@
 
 import { mkdir, appendFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-const hookRoot = path.resolve(process.cwd(), ".codex");
+const scriptPath = fileURLToPath(import.meta.url);
+const hookRoot = path.resolve(path.dirname(scriptPath), "..");
 const logDir = path.join(hookRoot, "logs");
 const logPath = path.join(logDir, "notify-events.jsonl");
 

.codex/hooks/stop-tts.mjs

@@ -2,8 +2,10 @@
 
 import { mkdir, readFile, writeFile, appendFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-const hookRoot = path.resolve(process.cwd(), ".codex");
+const scriptPath = fileURLToPath(import.meta.url);
+const hookRoot = path.resolve(path.dirname(scriptPath), "..");
 const stateDir = path.join(hookRoot, "state");
 const logDir = path.join(hookRoot, "logs");
 const seenTurnsPath = path.join(stateDir, "stop-tts-seen-turns.json");

ROADMAP.md

@@ -185,3 +185,13 @@ Current note: this milestone turns the live-service reliability work into a pack
 - [x] Harden configuration and persisted runtime state handling, including precedence rules, atomic writes, corruption or repair behavior, runtime-configuration persistence, and test isolation for profile-root-sensitive state.
 - [x] Harden the HTTP and MCP transport surface with clearer readiness policy, stronger request validation and operator-facing errors, reusable smoke coverage, and release verification that proves the staged live service can answer both transport health checks.
 - [x] Finish the full hardening program with a package-wide review, quick fixes discovered during the passes, and a cleanup sweep across docs, tests, and maintainer tooling.
+
+## Milestone 17: Codex Hooks And Operator Workflow
+
+Current note: the repo already has a working local Codex hooks prototype for
+Stop-hook speech and notify payload inspection. This milestone tracks turning
+that into a more intentional operator-facing workflow instead of a one-off
+prototype.
+
+- [x] Re-check the repo-local Codex hook scripts against the current official Codex hooks event shapes and stable-path guidance.
+- [ ] Add a maintained repo-local "use this with Codex hooks" guide or skill so Gale can enable, understand, and validate the speech-hook workflow without reverse-engineering the prototype files.

docs/codex-hooks-tts.md

@@ -1,7 +1,7 @@
 # Codex Hooks TTS Prototype
 
-This worktree includes a small repo-local Codex prototype for speaking final
-assistant replies and inspecting Codex notification payloads.
+This worktree includes a small repo-local Codex hooks prototype for speaking
+final assistant replies and inspecting Codex notification payloads.
 
 ## Files
 
@@ -26,6 +26,11 @@ assistant replies and inspecting Codex notification payloads.
 - `.codex/state/stop-tts-seen-turns.json`
   Dedupe state keyed by `session_id + turn_id`.
 
+Both hook scripts now resolve their `.codex` state and log directories from the
+script location itself instead of from `process.cwd()`. That matches the
+official Codex hooks guidance to keep repo-local hook paths stable even when
+Codex is started from a subdirectory.
+
 ## Environment Overrides
 
 The `Stop` hook script accepts a few optional environment overrides:
@@ -42,10 +47,24 @@ The `Stop` hook script accepts a few optional environment overrides:
 
 ## Validation Notes
 
-The current prototype was validated with a synthetic `Stop` payload and queued a
-live speech request successfully against the local server.
+The current prototype was rechecked against the current official Codex hooks
+documentation:
+
+- `Stop` receives one JSON object on `stdin`, including `turn_id`,
+  `stop_hook_active`, and `last_assistant_message`.
+- `Stop` must not emit plain text on `stdout`.
+- repo-local hooks should resolve from the git root or another stable path, not
+  by assuming the session `cwd` is the repository root.
+
+The `Stop` hook script matches that current payload shape and was validated with
+a synthetic `Stop` payload plus real runtime requests queued through the local
+server.
+
+Observed current behavior in this repo's live Codex TUI runs:
+
+- the `Stop` hook payload arrives on `stdin`
+- the `notify` command currently arrives as one JSON command-line argument
+- the current notify runs observed here did not include any `stdin` payload
 
-The current `notify` probe was validated with synthetic JSON passed both as the
-documented command-line argument and over `stdin`. The current Codex docs say
-the notify command receives a single JSON argument, so the probe now logs both
-paths in case any Codex surface differs in practice.
+The `notify` probe still logs both the documented JSON argument and any `stdin`
+payload so future Codex surfaces can be compared without rewriting the hook.