Yes, Codex has hooks. A Codex hook is a command listed in .codex/hooks.json (or ~/.codex/hooks.json) that Codex runs on an event such as PreToolUse or Stop, and it can deny a shell command or send Codex back to work. Codex skips every new or changed hook until you trust it in /hooks.
Codex facts checked against OpenAI's hooks reference on 21 Nov 2026. Skylos facts and output are for Skylos 5.7.0.
This page covers the events, a hooks.json you can write by hand, the six hooks skylos agent install-hooks --codex adds, the JSON each one returned in a test repository, what no hook can stop, and the CI check that decides the merge. For Claude Code and Cursor configs, see AI coding agent hooks.
What are Codex hooks and which events exist?
A Codex hook is a script, or a call to a tool on an MCP server Codex is already connected to, that Codex runs at a fixed point in its loop. Codex sends the hook one JSON object on stdin (session_id, cwd, hook_event_name and fields for the event) and reads JSON or an exit code back. OpenAI's reference listed these events on 21 Nov 2026:
| Event | When it runs | What a hook can do |
|---|---|---|
SessionStart | A session starts, resumes, clears, compacts or forks | Add context for the model |
SubagentStart | A subagent starts | Add context for the subagent |
UserPromptSubmit | Before your prompt is sent | Block the prompt, or add context |
PreToolUse | Before a Bash command, an apply_patch edit, an MCP tool or another local tool | Deny the call, or rewrite its input |
PermissionRequest | When Codex is about to ask you for approval | Allow or deny the request |
PostToolUse | After a tool returns | Replace the result with feedback. It can't undo what the tool did |
PreModelRequest, PostModelRequest | Around each model request attempt | Log. Output can't change the request |
PreCompact, PostCompact | Before and after the chat is compacted | Stop before compacting, or stop after it |
SubagentStop | A subagent finishes | Send the subagent back for another pass |
Stop | The turn ends | Make Codex continue, with your reason as the next prompt |
Interrupt | You interrupt a running turn | Record it. It can't prevent the interruption |
SessionEnd | The main thread ends | Save notes or clean up. Advisory |
A few defaults from the same reference: timeout is in seconds and is 600 for most hooks when you leave it out (SessionEnd and Interrupt get 1 second, at most 3). Hooks are on by default. Matching hooks from every file run, and matching command hooks for the same event start at the same time, so one hook can't stop another from starting. Hosted tools such as web search don't go through PreToolUse or PostToolUse at all.
Where does Codex look for hooks.json?
| Scope | File |
|---|---|
| System, macOS and Linux | /etc/codex/hooks.json |
| System, Windows | %ProgramData%\OpenAI\Codex\hooks.json |
| User | $CODEX_HOME/hooks.json, which is ~/.codex/hooks.json when CODEX_HOME is unset |
| Trusted project | .codex/hooks.json, in each .codex folder from the project root down to the working directory |
| Plugin | hooks/hooks.json in the plugin root, or the path its manifest names |
Each of these directories can declare the same hooks inline in config.toml instead:
[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = 'python3 "$(git rev-parse --show-toplevel)/.codex/hooks/no_force_push.py"'
timeout = 10
If one directory has both a hooks.json and [hooks] in config.toml, Codex loads both and warns at startup, so pick one format per directory. Codex combines hooks across sources, which means a command registered in two files can run twice.
To turn hooks off:
[features]
hooks = false
codex_hooks still works as a deprecated name for the same switch. An administrator can force hooks off, or allow managed hooks alone with allow_managed_hooks_only = true, in requirements.toml.
How do you write a Codex hook by hand?
Two files. This hook refuses force pushes. It is small on purpose, so you can see the whole contract.
.codex/hooks.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "^Bash$",
"hooks": [
{
"type": "command",
"command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/no_force_push.py\"",
"timeout": 10,
"statusMessage": "Checking for force push"
}
]
}
]
}
}
.codex/hooks/no_force_push.py:
#!/usr/bin/env python3
"""Codex PreToolUse hook: refuse force pushes."""
import json
import re
import sys
event = json.load(sys.stdin)
command = event.get("tool_input", {}).get("command", "")
if re.search(r"\bgit\b.*\bpush\b.*(--force\b|\s-f\b)", command):
print(json.dumps({
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Force pushes are off in this repo. Push a new commit instead.",
}
}))
sys.exit(0)
What each part does:
matcheris a regular expression on the tool name. Shell commands match asBash. File edits match asapply_patch,EditorWrite. MCP tools match by name, such asmcp__filesystem__read_file.- Codex runs the command from the session's working directory, which may be a subfolder. OpenAI recommends resolving the script from the Git root, as above, instead of a relative
.codex/hooks/...path. - For Bash, the command string is in
tool_input.command. Printing nothing and exiting 0 lets the call run.
You can test a hook without Codex by piping it a payload. From a subfolder of the repository:
echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git push --force origin main"}}' \
| python3 "$(git rev-parse --show-toplevel)/.codex/hooks/no_force_push.py"
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Force pushes are off in this repo. Push a new commit instead."}}
Command in tool_input.command | Hook output |
|---|---|
git push --force origin main | deny |
git push -f | deny |
git push origin main | nothing (allowed) |
git commit -m 'force fix' | nothing (allowed) |
Run on 21 Nov 2026, Python 3.13. It is a pattern match: a push from inside a script, or through a Git alias, gets past it. The next section explains why it still won't run in Codex yet.
Why doesn't a new Codex hook run?
Because you haven't trusted it. OpenAI's reference, 21 Nov 2026: "Codex records trust against the hook's current hash, so new or changed hooks are marked for review and skipped until trusted." When hooks need review, Codex prints a warning at startup that tells you to open /hooks.
If a hook still does nothing, check these in order:
- Trust. Open
/hooksin the Codex CLI, review the entry and trust it. Editing the hook later changes its hash, so it needs review again. - Project trust. Codex loads
.codex/hooks.jsonfrom trusted project layers alone. User and system hooks still load in an untrusted project. - The switch.
hooks = falseunder[features], in yourconfig.tomlor an administrator'srequirements.toml, turns all of them off.allow_managed_hooks_only = trueskips user, project, session and plugin hooks. - The matcher.
UserPromptSubmitandStopignore matchers. For tools, match the tool name Codex reports:Bash,apply_patch(orEdit,Write), or the MCP tool name. - The output. A
Stophook must print JSON when it exits 0. Plain text is invalid for that event.
For automation that vets hook sources some other way, --dangerously-bypass-hook-trust (on codex and codex exec, codex-cli 0.169.0) runs enabled hooks without stored trust for that one run.
Trust matters when the agent touches its own hooks. A hook the agent edits becomes a changed hook, so Codex skips it and asks for review at the next start: the edited command doesn't run quietly, and neither does the original until you review it. The reference does not describe review for a hook that was deleted, so don't count on /hooks to tell you one is gone.
How do you install Skylos hooks for Codex?
pip install skylos
cd your-project
skylos agent install-hooks --codex --skylos-bin skylos
Real output in a scratch repository on 21 Nov 2026 (paths shortened):
Installed 6 Skylos hook(s) in .../codex-demo/.codex/hooks.json (skylos 5.7.0).
Added .skylos/cache/, .skylos/agent-session.*, .skylos/hook.log*, .skylos/receipts/, .skylos/agent-traces/ to .../codex-demo/.gitignore.
.codex/hooks.json is usually committed. The hook command uses this machine's Skylos path; on a machine without it the hooks do nothing (they never block). Teammates who want the checks run `skylos agent install-hooks` themselves, or install with `--skylos-bin skylos` to use PATH.
Codex skips new hooks until you trust them: open /hooks in Codex and trust the Skylos entries.
Large repo? Run `skylos agent warm-cache` once so the first edit check does not build the project index.
With --skylos-bin skylos the file runs the bare skylos on each machine's PATH, which suits a committed file. The third line is printed either way. Without the flag, the file names the absolute path of the Skylos that ran the installer. The installer merges into an existing hooks.json and keeps your other hooks.
This is the file it wrote, identical to what --dry-run printed:
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "skylos hook session-start --client codex || exit 0",
"timeout": 30,
"statusMessage": "Skylos: recording the starting checkout"
}
]
}
],
"PreToolUse": [
{
"matcher": "^Bash$",
"hooks": [
{
"type": "command",
"command": "skylos hook pre-bash --client codex || exit 0",
"timeout": 30,
"statusMessage": "Skylos: checking packages and git hooks"
}
]
},
{
"matcher": "apply_patch|Edit|Write",
"hooks": [
{
"type": "command",
"command": "skylos hook pre-edit --client codex || exit 0",
"timeout": 30,
"statusMessage": "Skylos: capturing edit baseline"
}
]
}
],
"PostToolUse": [
{
"matcher": "apply_patch|Edit|Write",
"hooks": [
{
"type": "command",
"command": "skylos hook post-edit --client codex || exit 0",
"timeout": 120,
"statusMessage": "Skylos: verifying edit"
}
]
},
{
"matcher": "^Bash$",
"hooks": [
{
"type": "command",
"command": "skylos hook post-bash --client codex || exit 0",
"timeout": 30,
"statusMessage": "Skylos: recording command changes"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "skylos hook stop --client codex || echo '{}'",
"timeout": 9060,
"statusMessage": "Skylos: checking session edits"
}
]
}
]
}
}
| Codex event and matcher | Skylos hook | What it does on Codex (docs/agent-hooks.md, v5.7.0) |
|---|---|---|
UserPromptSubmit | session-start | Records the starting checkout, so stop can tell the agent's changes from yours. Reports agent-config changes it did not see the agent make. Never blocks |
PreToolUse on ^Bash$ | pre-bash | Denies installs of packages that don't exist, one-edit look-alikes of popular packages, versions reported as malware and versions younger than 48 hours. Denies commands that would print a secret, and Git hook bypasses such as --no-verify |
PreToolUse on apply_patch|Edit|Write | pre-edit | Denies edits to agent configs that add unpinned MCP servers, add hooks, or remove Skylos's own hooks |
PostToolUse on apply_patch|Edit|Write | post-edit | Checks the lines the patch added (from the + lines of the apply_patch envelope) and sends blocking findings back to Codex |
PostToolUse on ^Bash$ | post-bash | Records files a shell command changed. Never blocks |
Stop | stop | Blocks the stop while issues this session added are open. With a committed [tool.skylos.done] table it also runs your tests and checks for deleted or skipped tests |
Every command ends in || exit 0 (or || echo '{}' for Stop, because Codex requires JSON from a Stop hook), so a Skylos that is missing or broken never blocks Codex. Skylos itself always exits 0 and puts its decision in JSON. The long Stop timeout covers the test run and the reruns the Done gate allows.
Codex has no Skylos pre-read hook, unlike Claude Code and Cursor. Codex reads files through shell commands, so pre-bash does that job (below).
skylos setup is the one-command alternative: it installs the Claude Code and Codex hooks and writes the [tool.skylos.done] table when it finds pytest, Vitest or Jest tests.
To check the hooks still answer, skylos doctor sends pre-bash two test payloads. Real output, same repository:
Agent hooks
-- Claude Code: not installed (optional: skylos agent install-hooks)
OK Codex: 6 of 6 hooks in .codex/hooks.json (project) → .../bin/skylos
Self-test (passed): pre-bash allowed `ls` (0.1 s) and blocked `cat .env` of a file with a token (0.2 s)
Doctor cannot see whether Codex has loaded or trusted the hooks. Check /hooks in Codex for that.
Can a Codex hook block a hallucinated package install?
Yes. We checked that fastapi-authz-middleware-pro returned 404 from PyPI, then sent pre-bash the payload Codex documents for a Bash call (cwd shortened):
{
"session_id": "codex-demo-1",
"transcript_path": null,
"cwd": "/path/to/codex-demo",
"hook_event_name": "PreToolUse",
"permission_mode": "default",
"turn_id": "turn-1",
"tool_name": "Bash",
"tool_use_id": "call-install",
"tool_input": {
"command": "pip install fastapi-authz-middleware-pro"
}
}
skylos hook pre-bash --client codex answered:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Skylos blocked this install: 1 package looks hallucinated or typosquatted.\n- PyPI package 'fastapi-authz-middleware-pro' does not exist on PyPI (likely hallucinated; an attacker can register it).\nCheck the real package name (docs, registry search) and retry. If the package is internal, install it with your private index/registry flag and ask the user to list that registry in trusted_registries under [tool.skylos.hooks]. If this package is correct, add it to [tool.skylos] hooks_allow_packages in pyproject.toml."
}
}
Per OpenAI's reference, Codex does not run a denied call. The reason is written for the agent, so it says what to try instead.
Other commands from the same run:
| Command | pre-bash answer |
|---|---|
pip install requests | nothing (allowed after the registry lookup) |
pytest -q | nothing (no install, no lookup) |
git commit -m wip --no-verify, in a repo with a pre-commit hook | deny: "it skips this repository's git hooks (--no-verify). Hooks that would not run: pre-commit." |
git commit -m wip --no-verify, in a repo without Git hooks | nothing (there is no hook to skip) |
One run each on 21 Nov 2026 took 0.91 s for the uncached PyPI lookup and 0.25 s for pytest -q (/usr/bin/time, Skylos 5.7.0, Apple M4).
What the install check covers, per docs/agent-hooks.md v5.7.0: PyPI installs and runners (pip, uv, uvx, poetry, pdm, pipenv, pipx), npm (npm, npx, pnpm, yarn, bun, deno with npm:), JSR (deno with jsr:) and Go modules (go get, go install, go run pkg@version). Lockfile installs such as npm ci and pip install -r get the malware check over every locked package. A package name that an AI model invented is a risk because someone can register it later. The hook makes sure an install of a name that does not exist never runs.
On Claude Code, an install Skylos cannot verify (a Git URL, an unknown registry, a failed lookup) asks you. Codex does not support ask from PreToolUse yet: OpenAI's reference says Codex marks such a hook run as failed and runs the tool. So on Codex, Skylos denies those installs and says why. Allow your own package names in pyproject.toml:
[tool.skylos]
hooks_allow_packages = ["internal-pkg", "npm:my-reactt"]
How do you stop Codex printing secrets from .env?
With a PreToolUse hook on Bash, since that is how Codex reads files. The test repository had a Git-ignored .env with a PORT setting on line 1 and a GitHub-style token, generated at random for the test, on line 2. Fed cat .env, skylos hook pre-bash --client codex answered:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Skylos blocked this command: it would print 1 likely secret(s) (github secret) from .env line(s) 2. Command output goes to the model provider. List variable names without values (cut -d= -f1 .env), print only the lines you need (sed -n '10,40p', grep, head/tail) skipping those lines, check a variable is set without printing it (test -n \"$NAME\" && echo set), or ask the user."
}
}
The message names the file, the line and the kind of secret, never the value.
| Command | Result | Why |
|---|---|---|
cat .env | deny | line 2 would be printed |
grep PORT .env | allowed | the printed line holds no secret |
python3 -c "print(open('.env').read())" | allowed | a program that opens the file itself is not followed |
Run on 21 Nov 2026, Skylos 5.7.0. The third row is the limit that matters. Per docs/agent-hooks.md v5.7.0, pre-bash follows the commands agents usually write: cat, less, head, tail, grep, rg, sed, awk, cut, base64, env, printenv, echo $NAME and similar, through pipes, globs, loops and bash -c. It does not follow find ... -exec cat, ... | xargs cat, git show HEAD:.env, docker compose config, a copy read back under another name, or files the secrets scanner does not read, such as .npmrc and ~/.aws/credentials. Reads through MCP tools are not checked, because Skylos does not use Codex's MCP tool hooks. The answer to a determined read is the sandbox and keeping secrets out of the working tree.
Can a Codex Stop hook catch a deleted test?
Yes, when the repository commits a [tool.skylos.done] table. Skylos reads it from the base commit, so the agent can't loosen it mid-session. The test repository had a three-test pytest suite and this in pyproject.toml:
[tool.skylos.done]
test_command = "pytest -q"
We then played the agent through the hooks: a prompt to session-start ("divide() is too defensive, simplify it and make sure the tests pass"), an apply_patch that removed the ValueError guard from divide(), and a second apply_patch that deleted the test for that guard, test_divide_by_zero. The two tests left passed. The Stop payload:
{"session_id": "codex-demo-2", "transcript_path": null, "cwd": "/path/to/codex-demo", "permission_mode": "default", "hook_event_name": "Stop", "turn_id": "turn-1", "stop_hook_active": false, "last_assistant_message": "Simplified divide() and cleaned up the tests. All tests pass."}
skylos hook stop --client codex answered, in 2.88 s:
{
"decision": "block",
"reason": "Skylos Done: change is fail.\n- tests_pass: Not run because an earlier required check needs attention\n- tests/test_calc.py:14 SKY-A110: test_divide_by_zero was deleted; no test with the same body exists now\nFix these problems, then recheck: skylos done --session codex-demo-2.\nReceipt: .skylos/receipts/latest.json"
}
Per OpenAI's reference, decision: block on Stop does not reject the turn. Codex continues and uses the reason as the next prompt, so Codex gets the deleted test's name and the recheck command.
It doesn't loop forever. We sent the same Stop event again with stop_hook_active: true and nothing changed. It blocked twice more (three blocks is the default max_stop_blocks), then let Codex stop with a warning for you:
{
"systemMessage": "Skylos Done remains fail after 3 stop blocks. The agent may stop; the receipt is not passing (.skylos/receipts/latest.json). Recheck: skylos done --session codex-demo-2."
}
Putting the test back without the guard ran the tests and found the real problem:
{
"decision": "block",
"reason": "Skylos Done: change is fail.\n1 failing test is new in this change: tests/test_calc.py::test_divide_by_zero. Fix the 1 new failure before saying you are done.\n- tests/test_calc.py:14 SKY-A113: tests/test_calc.py::test_divide_by_zero failed (introduced by this change: passes on the session start (0bbfee8)): ZeroDivisionError: division by zero\nFix these problems, then recheck: skylos done --session codex-demo-2.\nReceipt: .skylos/receipts/latest.json"
}
With the guard restored too, the stop hook answered {} and Codex could stop. Without a Done table, stop runs no tests. It rechecks the issues post-edit recorded in the session and nothing else. The Claude Code Stop hook page shows why a hook that just runs the tests passes when the failing test is deleted.
What can't Codex hooks do?
From OpenAI's reference and docs/agent-hooks.md at v5.7.0:
- They are not a sandbox. OpenAI: "Treat tool hooks as a useful guardrail, not a complete enforcement boundary." Some tool paths can opt out of the hook path, and hosted tools never use it. Skylos's hooks don't confine what an allowed command does, which files it touches or what the network reaches. A command that downloads and runs code in a way Skylos does not parse (a script that calls
pip, annpm runscript that installs,curl ... | sh) is not checked. - They fail open. If a
PreToolUsehook returns a field Codex doesn't support, Codex marks the run as failed and continues the tool call. If Skylos crashes, it allows the action and says so in asystemMessage. If Skylos isn't installed, the|| exit 0wrapper makes the hook a silent no-op. - They can't ask you. Wherever Skylos would ask on Claude Code (an unverifiable install, a new hook command, an MCP config it can't read), it denies on Codex.
- They can't undo an edit.
PostToolUseruns after the patch is written. It tells Codex what to fix. - They judge added lines.
post-editreports problems on lines the patch added. A deletion that removes a sanitizer elsewhere in the file is not attributed to the edit. - They don't check shell edits at edit time (
sed -i, heredocs).stopstill rechecks files that earlier edits recorded, and the Done gate compares the whole tree with the session's start. - They don't follow every install.
cargo,gem,composerandcondainstalls, dependencies declared inside a script (uv run script.pywith inline metadata) and package managers' lifecycle scripts are not checked. Lockfile installs get the malware check, not the existence or release-age checks. An exact pin on an MCP server freezes that package, not its dependencies. - They stay inside the project. Files outside the project root are not checked.
- An agent can try to turn them off. On Codex, an
apply_patchthat deletes the Skylos Stop entry got this frompre-edit:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Skylos needs your approval for this edit to .codex/hooks.json:\n- .codex/hooks.json: removes Skylos's own hooks or weakens them (event, matcher or timeout).\nApprove only if you asked for this change. (Codex hooks cannot ask the user, so Skylos blocks instead.)"
}
}
A python3 -c command that rewrote .codex/hooks.json was denied by pre-bash too ("It writes .codex (via python3 code) directly, so Skylos cannot check what it adds"). Both are pattern checks inside the loop the agent runs in. A script that writes the file without naming it is not detected. That is why the merge check below exists.
For the boundary itself, use Codex's sandbox. skylos agent harden prints a suggested ~/.codex/config.toml and writes nothing for Codex:
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = false
Those keys are in Codex's config reference, and OpenAI's sandboxing page calls workspace-write with on-request "the lower-risk local automation preset" (both read 21 Nov 2026). Skylos enforces none of it.
How do you add a merge check that Codex cannot edit?
Hooks give Codex feedback while it works. The pull request needs a check that runs whether or not anyone installed or trusted the hooks:
skylos cicd init --no-upload
Real output in the test repository (the "Next" steps it prints after this are left out):
Workflow written to .github/workflows/skylos.yml
Pull requests
Skylos Quality Gate scans the changed lines; fails when the gate fails
Skylos Done runs your tests ([tool.skylos.done] test_command is set)
installs: python -I -m pip install -e . pytest
edit that step in the workflow if your tests need more
Skylos PR summary posts the one pull request comment: verdicts, what blocks,
what to read first; not a required check
No origin/HEAD, so pushes to main or master trigger it; use --default-branch to change.
--no-upload leaves out the Skylos Cloud upload job, so it needs no account. The Done job runs skylos done --base against the pull request's base. Make Skylos Quality Gate and Skylos Done required status checks on your default branch, and protect the workflow file itself.
The same check runs locally. On a branch where Codex removed the guard and deleted its test, skylos done --base main exited 1:
Skylos done · base 5397acc (merge base) · head 2c51813
UNFINISHED Tests pass when Skylos runs them: Earlier required checks failed or were incomplete
FAIL No tests deleted, skipped or weakened: 1 test change(s) weaken what the tests check
tests/test_calc.py:14 SKY-A110 test_divide_by_zero was deleted; no test with the same body exists now
tests/test_calc.py:15 SKY-A101 (advice) Exception assertion was removed
Fix: Put back the removed or skipped tests and the original assertions and settings.
PASS Skylos settings and hooks left alone: Skylos settings, hooks and protected paths unchanged
PASS No secrets added: No secrets added
PASS Every package and import is real: Every added import and package resolves
WARN Tests check the changed lines: Earlier required checks failed or were incomplete
PASS Code doesn't special-case the tests: No code special-cases the tests (1 changed file(s) read)
PASS Linters, type checkers, scanners and CI not silenced: No linter, type-checker, scanner or CI settings weakened
PASS Security controls checked for removals: No security control removals detected (2 changed source file(s) compared)
PASS AI-reviewer settings and scanner markers left alone: AI-reviewer settings unchanged; no scanner suppression markers added
PASS No code left without callers: No code left without callers
OFF No introduced type errors: Off in [tool.skylos.done]
Verdict: FAIL: tests were deleted, skipped or weakened. The tests were not run because of this
Receipt: .skylos/receipts/2c518137c0ad-5397acc97761.json
See what to read and what is proven unchanged: skylos done map --base main
See every run stage by stage: skylos open, then the Pipeline tab
On a second branch that deleted the Skylos Stop entry from .codex/hooks.json, it failed on that instead (trimmed):
FAIL Skylos settings and hooks left alone: 1 change(s) to Skylos settings or hooks
.codex/hooks.json SKY-A114 changes .codex/hooks.json, which is protected (.codex/hooks.json in protected_paths)
Fix: Undo the changes to those files. A person should make changes there.
Verdict: FAIL: Skylos settings or hooks were changed. The tests were not run because of this
.codex/hooks.json and .codex/config.toml are in the default protected_paths, next to the Claude Code and Cursor hook files.
Where do the Skylos hooks fall short?
- False positives happen. An internal package missing from public PyPI or npm looks hallucinated. Point the install at your registry and list it in
trusted_registriesunder[tool.skylos.hooks], or allow the name inhooks_allow_packages. A Done check you disagree with can be set toadviseunder[tool.skylos.done.checks]on the base branch. - Codex gets less than Claude Code. No per-edit notes for non-blocking findings, no "Done passed" message, no
ask, and nopre-readhook. - Depth differs by language.
post-editruns the fullskylos verifyset on Python, TypeScript/JavaScript, Java, Go, PHP, Rust and Dart files, among others, and the secrets scanner alone on config files such as.env, YAML and TOML. The Done gate compares Python and JavaScript/TypeScript tests. Its changed-line test check (SKY-A120) covers Python code, not JavaScript or TypeScript. - No live Codex run on this page. The payloads follow Codex's documented fields and were piped to Skylos by hand. If your Codex version sends something different,
skylos doctorand.skylos/hook.logare where to look.
Turn one hook off, or remove all of them:
export SKYLOS_HOOKS_DISABLE=pre-bash # or pre-edit,stop, or all
skylos agent install-hooks --codex --uninstall
Uninstall removes the entries whose command runs skylos hook <event> and leaves your other hooks. Run it yourself: when Codex ran the same command in our test, pre-bash denied it ("It removes Skylos's own agent hooks").
Setup in 60 seconds
pip install skylos
cd your-project
skylos agent install-hooks --codex --skylos-bin skylos
skylos cicd init --no-upload
Then start Codex in the project, open /hooks and trust the six Skylos entries. Commit .codex/hooks.json, the [tool.skylos.done] table and the workflow, and make the two jobs required. No account or API key is needed. The hooks run locally and source stays on your machine. Package names from install commands, MCP servers and new imports go to the public registries and OSV.
Changelog
- 21 Nov 2026: First version. Skylos 5.7.0. Codex hooks reference, sandboxing page and config reference read the same day.
Related
- Claude Code hooks examples for security (Codex and Cursor too)
- Claude Code Stop hook: block "done" until tests pass
- AI agent says the tests pass? How to verify AI-generated code before merge
- Your AI agent just tried to install a package that doesn't exist
- Testwashing: when coding agents delete tests to pass CI
- AI coding agent security checklist
- GitHub Actions PR gate for AI-generated code
References
- Codex hooks (OpenAI), served from learn.chatgpt.com/docs/hooks, read 21 Nov 2026
- Codex sandboxing (OpenAI), read 21 Nov 2026
- Codex config reference (OpenAI), read 21 Nov 2026
- Skylos agent hooks reference, v5.7.0
- Skylos Done gate reference, v5.7.0