A creature per agent session in the terminal — and a Codex hooks question I can't answer myself

[TevvvB]

I maintain a small Go tool that gives each agent session its own ASCII creature, so that
several sessions running across several git worktrees stop looking identical. It supports
Codex, and I have a question about that support I genuinely cannot answer myself.

https://github.com/TevvvB/termagitchi

pets install writes hooks for both Claude Code and Codex - SessionStart, PostToolUse
and Stop. The Claude Code path I use every day. The Codex path has never once run
against a real Codex, and the readme says so rather than implying otherwise.

Two things changed this week that make the question worth asking now. Registration used to
happen only from the status line, and Codex has no status-line support, so a Codex session
would have been invisible in pets den and pets party even if its hooks fired perfectly.
That was the actual bug, and it is fixed - every hook now registers, and session start also
refreshes state so the listing is populated from the first turn rather than the second.

So the remaining unknown is narrow: do the hooks fire at all?

What I think I know from reading codex-rs/hooks/: there is a PostToolUse event and a
hooks.json that gets read. But the config carries enabled and trusted_hash per hook,
which reads like a hook has to be trusted before it will run. If that is right then writing
the file is necessary but not sufficient, and the readme should say what the extra step is
instead of leaving people to find out.

If anyone here runs Codex and is willing to try pets install --harness=codex, the useful
answers are:

1. Does anything happen on a new session, or silently nothing?
2. If nothing, what makes it fire - and is that something an installer can do, or only
   something it can tell you to do?
3. Does the payload carry a per-session identifier? The whole model keys a creature on the
   session, so if Codex names sessions differently that is the interesting part.

An "it silently did nothing" report is a complete answer and more useful to me than a patch.
No Go required.

---

Renamed since posting: this is now termagitchi (https://github.com/TevvvB/termagitchi). The old URL redirects, and the binary is still pets.

[AdiedX]

I can confirm that Codex hooks can appear to be completely silent when the hook itself fails during session startup.

On one affected macOS installation, the SessionStart hook loaded a stale instruction path and required a Mandatory topic files section that did not exist in the canonical AGENTS.md. Directly invoking the hook returned:

continue: false

with:

Required instruction loading failed: AGENTS.md is missing the 'Mandatory topic files' section

The CLI then exited with status 0 but produced no assistant message. That made the symptom look like a model or Desktop prompt hang even though the actual failure happened before the agent turn began.

The most useful generic smoke test is to invoke the hook directly with a representative startup event and inspect the JSON response. A successful hook should return an additionalContext payload and no continue: false or stopReason. A failed hook may still exit with process status 0, so checking only the shell exit code is not enough.

The fix was to make the hook read the canonical instruction file directly, remove the obsolete required-section check, and make optional instruction files or sections non-fatal. After that change, both the standalone and ChatGPT-bundled Codex binaries passed 10/10 ephemeral trivial prompts.

I would also recommend that the hook documentation clearly distinguish:

• hook did not run;
• hook ran successfully but returned no context;
• hook failed and blocked the session;
• hook was not trusted or was disabled;
• the agent turn started but the Desktop renderer or app-server later became stuck.

Those states currently look too similar from the user’s perspective.

[TevvvB]

Thanks - your answer was the push I needed, and I have now gone and tested it rather than
asking you more questions. Answers below, on 0.149.0, in case they save someone else a
fortnight.

Untrusted hooks do not run, and that is indistinguishable from broken

This was my whole problem. My hooks had been sitting in ~/.codex/hooks.json since 11 August
and had never once executed. Nothing was wrong with them.

codex exec "..."                                    # hooks do not fire
codex exec --dangerously-bypass-hook-trust "..."    # SessionStart and Stop both fire

Same config, same binary, one flag apart. codex doctor reports no hooks section at all, so
there is nowhere to see that the hooks you installed are inert. This is precisely the state
your list is asking for: "was not trusted" currently looks exactly like "did not run", and
from the outside I could not tell it from "my tool is broken".

Non-JSON on stdout from SessionStart is tolerated

The question I asked you. Answer: no, it does not fail the turn. My SessionStart hook prints
a block of ASCII art - not JSON, no envelope - and the turn completed normally, ok and all.
So the risk I was worried about was not real, at least not on this version.

Related, from reading the binary's strings: the only invalid-JSON error is scoped to
PreToolUse ("hook returned invalid pre-tool-use JSON output"), which fits.

And systemMessage is in the hook output schema, alongside additionalContext,
stopReason, suppressOutput and hookSpecificOutput. So the Claude-Code-shaped
{"systemMessage": "..."} my Stop hook emits was valid here all along.

The payloads, since they are not documented anywhere I could find

SessionStart:

cwd, hook_event_name, model, permission_mode, session_id, source, transcript_path

Stop, additionally:

last_assistant_message, stop_hook_active, turn_id

Both carry session_id, which was the thing I actually needed - my tool keys everything on a
per-session identifier and I had no idea whether Codex supplied one. It does, and
transcript_path points at ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<session_id>.jsonl.
Note there is no workspace object, so anything relying on a harness-supplied worktree name
has to fall back to git.

What I am changing at my end

The bug was mine and it was not the one I thought. pets install --harness=codex writes the
hooks and then says nothing about trust, so it looks installed and does nothing. That is the
fix: tell people the hooks are pending trust, rather than leaving them to conclude the
integration is broken.