feat(hooks): lifecycle hooks and documentation

[am-will]

This is Claude Code Hooks (with a bonus: Post Compact Hook!), and they are well integrated directly into EveryCode,including the option to turn them on/off in the /settings menu, as well as the option on which model/provider to use.

Summary

• add project lifecycle hooks across session, tool, file, stop, compact, and notification events
• honor hook decisions (allow/ask/deny, updated input, system messages) and add hook event tests
• document hook configuration, payloads, outputs, and local testing workflow
• update example hook scripts to read CODE_HOOK_PAYLOAD and parse command payloads

What this feature is

Project lifecycle hooks let operators run local commands at well-defined points in a Codex session (prompt submit, tool exec, file writes, compaction, turn completion, sub-agent completion, notifications). Hooks run in the same sandbox/approval mode as the session, appear as exec cells (unless run_in_background), and can gate or rewrite inputs through a JSON response contract.

How to use it

Define hooks per project in config.toml:

[projects."/Users/me/src/my-app"]
trust_level = "trusted"

[[projects."/Users/me/src/my-app".hooks]]
name = "bootstrap"
event = "session.start"
run = ["./scripts/bootstrap.sh"]
timeout_ms = 60000

[[projects."/Users/me/src/my-app".hooks]]
name = "lint-changed"
event = "tool.after"
run = "npm run lint -- --changed"

Where hooks live

• Config: config.toml under CODE_HOME (project-scoped via [projects."<path>"]).
• Examples: hooks/ask_user_prompt.py, hooks/check_shell.py + scripts/run-hooks-test.sh in this repo.

Available hook events

session.start, session.end, user.prompt_submit, tool.before, tool.after,
file.before_write, file.after_write, pre.compact, post.compact, stop,
subagent.stop, notification.

Payload + control JSON highlights

• Payload arrives in CODE_HOOK_PAYLOAD (JSON string) + stdin fallback.
• Common env: CODE_HOOK_EVENT, CODE_HOOK_TRIGGER, CODE_HOOK_CALL_ID, CODE_HOOK_SUB_ID, CODE_HOOK_INDEX, CODE_SESSION_CWD, CODE_HOOK_NAME, CODE_HOOK_SOURCE_CALL_ID.
• Hooks may return JSON with:
  • permissionDecision (allow|ask|deny) or hookSpecificOutput.permissionDecision
  • updatedInput (rewrite prompt/command)
  • systemMessage (Chat API only)
  • continue: false (stop remaining hooks for that event)

Testing

• ./build-fast.sh
• scripts/run-hooks-test.sh (configures the example hooks)

Try:

• prompt hook: please summarize this repo
• a shell command containing rm -rf to trigger the guard

[chatgpt-codex-connector]

💡 Codex Review

code/code-rs/core/src/codex/streaming.rs

Lines 1883 to 1887 in 29f66bb

	// Choose between local and remote compact based on auth mode,
	// matching upstream codex-rs behavior
	if compact::should_use_remote_compact_task(&sess).await {
	let _ = run_inline_remote_auto_compact_task(
	Arc::clone(&sess),

Run pre.compact hooks before auto compaction

In the token-limit auto-compaction branch, the code jumps straight into run_inline_*_auto_compact_task without invoking ProjectHookEvent::PreCompact, so any hooks configured for pre.compact will never run during automatic compaction (the most common case when the context window is exceeded). This means gates/logging meant to run before compaction won’t fire for auto compacts. Consider running the pre-compact hook (with reason "auto") before this branch executes.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".