Docs: hooks.json timeout key is documented but runtime requires timeout_sec

Open
#35,382 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
58/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
rust
Domain
documentation

Research direction

Compare the examples and field descriptions in learn.chatgpt.com/docs/hooks.md with codex-rs/config/src/hook_config.rs, especially the serde definition and hooks_file_deserializes_existing_json_shape test. Reproduce parsing for both timeout spellings if the repository provides a suitable test entry point, then update the documentation or supported configuration shape so the published key matches the verified runtime behavior.

Written by the indexing model from the issue text.

Description

CLI config documentation hooks

The official Hooks documentation documents timeout as the key for hook command configurations:

{
  "type": "command",
  "command": "python3 ~/.codex/hooks/session_end.py",
  "timeout": 3
}

The docs also state:

timeout is in seconds.
If timeout is omitted, Codex uses 600 seconds for most hooks.

However, in practice, the timeout key is not accepted by the runtime. The key that actually works is timeout_sec.

This is a documentation bug -- the runtime field name does not match what is published.

Affected surfaces

  • ~/.codex/hooks.json
  • hooks.json in any .codex/ directory
  • Inline [hooks] tables in config.toml

Expected fix

Either:

  1. Update the docs to document timeout_sec as the correct key, or
  2. Add timeout_sec as an accepted alias if the runtime already supports both.

Source Code Evidence

The Codex Rust source confirms timeout is the only accepted JSON key.

File: codex-rs/config/src/hook_config.rs lines 147-150:

#[serde(default, rename = "timeout")]
timeout_sec: Option<u64>,

The rename = "timeout" serde attribute means the JSON field name is timeout. The Rust struct field is named timeout_sec — that's just an internal naming convention, not the JSON key.

This is the complete serde configuration for the timeout field: there is no alias attribute for timeout_sec, so timeout_sec as a JSON key is not accepted by the parser.

Test evidence: The same source includes a test hooks_file_deserializes_existing_json_shape that parses "timeout": 10 and asserts success — confirming this is the tested, supported shape.

Reference: https://learn.chatgpt.com/docs/hooks.md uses "timeout": 3 and "timeout": 30 in all examples, matching the runtime source.

Dominant language
Rust
Stars
125k
Forks
19.5k
Avg merge
1m
Merged PRs (30d)
1k

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openai/codex

All issues in openai/codex

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.