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

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.

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