6 Commits

• [hooks] add non-streaming (non-stdin style) shell-only PostToolUse support (#15531)

  CHAINED PR - note that base is eternal/hooks-pretooluse-bash, not main
  -- so the following PR should be first
  
  Matching post-tool hook to the pre-tool functionality here:
  https://github.com/openai/codex/pull/15211
  
  So, PreToolUse calls for plain shell calls, allows blocking. This
  PostToolUse call runs after the command executed
  
  example run:
  
  ```
  › as a test, run in parallel the following commands:
    - echo 'one'
    - echo '[block-pre-tool-use]'
    - echo '[block-post-tool-use]'
  
  
  ⚠ MCP startup incomplete (failed: notion, linear)
  
  • Cruising through those three commands in parallel now, and I’ll share the exact outputs right after
    they land.
  
  • Running PreToolUse hook: checking the observatory runes
  
  • Running PreToolUse hook: checking the observatory runes
  
  • Running PreToolUse hook: checking the observatory runes
  
  PreToolUse hook (blocked)
    warning: wizard-tower PreToolUse demo blocked a Bash command on purpose.
    feedback: PreToolUse demo blocked the command. Remove [block-pre-tool-use] to continue.
  
  PreToolUse hook (completed)
    warning: wizard-tower PreToolUse demo inspected Bash: echo 'one'
  
  PreToolUse hook (completed)
    warning: wizard-tower PreToolUse demo inspected Bash: echo '[block-post-tool-use]'
  
  • Ran echo '[block-post-tool-use]'
    └ [block-post-tool-use]
  
  • Ran echo 'one'
    └ one
  
  • Running PostToolUse hook: reading the observatory aftermath
  
  • Running PostToolUse hook: reading the observatory aftermath
  
  PostToolUse hook (blocked)
    warning: wizard-tower PostToolUse demo blocked the Bash follow-through on purpose.
    feedback: PostToolUse demo blocked the result after execution. Remove [block-post-tool-use] to
  continue.
  
  PostToolUse hook (completed)
    warning: wizard-tower PostToolUse demo inspected Bash: echo 'one'
    hook context: PostToolUse demo saw the Bash result. Response preview: one
  
  ──────────────────────────────────────────────────────────────────────────────────────────────────────
  
  • Ran them in parallel. Little wave report:
  
    - echo 'one' completed and returned one.
    - echo '[block-pre-tool-use]' was blocked before execution by the PreToolUse hook.
    - echo '[block-post-tool-use]' ran, but its result was blocked afterward by the PostToolUse hook.
  
    The hook messages were:
  
    - PreToolUse demo blocked the command. Remove [block-pre-tool-use] to continue.
    - PostToolUse demo blocked the result after execution. Remove [block-post-tool-use] to continue.
  
  
  › for the blocked messages (correctly blocked in this test) did the tool output land back into
    context?
  
  
  • Yeah, from this run:
  
    - PreToolUse block: the command itself did not execute, so no command output landed in context. Only
      the block message did.
    - PostToolUse block: the command did execute, but the actual stdout did not come back into context.
      Only the post-tool block message did.
  
    So the blocked notifications landed in context, but the blocked command payloads themselves did not.
    Nice clean guardrail, aloha.
  ```

  Andrei Eternal · 2026-03-25 19:18:03 -07:00
  c4d9887f9a
• [hooks] add non-streaming (non-stdin style) shell-only PreToolUse support (#15211)

  - add `PreToolUse` hook for bash-like tool execution only at first
  - block shell execution before dispatch with deny-only hook behavior
  - introduces common.rs matcher framework for matching when hooks are run
  
  example run:
  
  ```
  › run three parallel echo commands, and the second one should echo "[block-pre-tool-use]" as a test
  
  
  • Running the three echo commands in parallel now and I’ll report the output directly.
  
  • Running PreToolUse hook: name for demo pre tool use hook
  
  • Running PreToolUse hook: name for demo pre tool use hook
  
  • Running PreToolUse hook: name for demo pre tool use hook
  
  PreToolUse hook (completed)
    warning: wizard-tower PreToolUse demo inspected Bash: echo "first parallel echo"
    
  PreToolUse hook (blocked)
    warning: wizard-tower PreToolUse demo blocked a Bash command on purpose.
    feedback: PreToolUse demo blocked the command. Remove [block-pre-tool-use] to continue.
  
  PreToolUse hook (completed)
    warning: wizard-tower PreToolUse demo inspected Bash: echo "third parallel echo"
  
  • Ran echo "first parallel echo"
    └ first parallel echo
  
  • Ran echo "third parallel echo"
    └ third parallel echo
  
  • Three little waves went out in parallel.
  
    1. printed first parallel echo
    2. was blocked before execution because it contained the exact test string [block-pre-tool-use]
    3. printed third parallel echo
  
    There was also an unrelated macOS defaults warning around the successful commands, but the echoes
    themselves worked fine. If you want, I can rerun the second one with a slightly modified string so
    it passes cleanly.
  ```

  Andrei Eternal · 2026-03-23 14:32:59 -07:00
  73bbb07ba8
• [hooks] turn_id extension for Stop & UserPromptSubmit (#15118)

  ## Description
  
  Adding an extension to the spec that exposes the turn_id to hook
  scripts. This is a codex-specific mechanic that allows connecting the
  hook runs with particular turns
  
  ## Testing
  
  hooks config / sample hooks to use. Extract this, rename codex ->
  .codex, and place this into a repo or your home folder. It includes:
  config.toml that enables hooks, hooks.json, and sample python hooks:
  
  
  [codex.zip](https://github.com/user-attachments/files/26102671/codex.zip)
  
  example run (note the turn_ids change between turns):
  
  ```
  › hello
  
  
  • Running SessionStart hook: lighting the observatory
  
  SessionStart hook (completed)
    warning: Hi, I'm a session start hook for wizard-tower (startup).
    hook context: Startup context: A wimboltine stonpet is an exotic cuisine from hyperspace
  
  • Running UserPromptSubmit hook: lighting the observatory lanterns
  
  UserPromptSubmit hook (completed)
    warning: wizard-tower UserPromptSubmit demo inspected: hello for turn: 019d036d-c7fa-72d2-b6fd-
  78878bfe34e4
    hook context: Wizard Tower UserPromptSubmit demo fired. For this reply only, include the exact
  phrase 'observatory lanterns lit' near the end.
  
  • Aloha! Grateful to be here and ready to build with you. Show me what you want to tackle in wizard-
    tower, and we’ll surf the next wave together. observatory lanterns lit
  
  • Running Stop hook: back to shore
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook reviewed the completed reply (170 chars) for turn: 019d036d-c7fa-
  72d2-b6fd-78878bfe34e4
  
  
  › what's a stonpet?
  
  
  • Running UserPromptSubmit hook: lighting the observatory lanterns
  
  UserPromptSubmit hook (completed)
    warning: wizard-tower UserPromptSubmit demo inspected: what's a stonpet? for turn: 019d036e-3164-
  72c3-a170-98925564c4fc
    hook context: Wizard Tower UserPromptSubmit demo fired. For this reply only, include the exact
  phrase 'observatory lanterns lit' near the end.
  
  • A stonpet isn’t a standard real-world word, brah. In our shared context here, a wimboltine stonpet
    is an exotic cuisine from hyperspace, so “stonpet” sounds like the dish or food itself.
  
    If you want, we can totally invent the lore for it next. observatory lanterns lit
  
  • Running Stop hook: back to shore
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook reviewed the completed reply (271 chars) for turn: 019d036e-3164-
  72c3-a170-98925564c4fc
  ```

  Andrei Eternal · 2026-03-18 21:48:31 -07:00
  42e932d7bf
• [hooks] userpromptsubmit - hook before user's prompt is executed (#14626)

  - this allows blocking the user's prompts from executing, and also
  prevents them from entering history
  - handles the edge case where you can both prevent the user's prompt AND
  add n amount of additionalContexts
  - refactors some old code into common.rs where hooks overlap
  functionality
  - refactors additionalContext being previously added to user messages,
  instead we use developer messages for them
  - handles queued messages correctly
  
  Sample hook for testing - if you write "[block-user-submit]" this hook
  will stop the thread:
  
  example run
  ```
  › sup
  
  
  • Running UserPromptSubmit hook: reading the observatory notes
  
  UserPromptSubmit hook (completed)
    warning: wizard-tower UserPromptSubmit demo inspected: sup
    hook context: Wizard Tower UserPromptSubmit demo fired. For this reply only, include the exact
  phrase 'observatory lanterns lit' exactly once near the end.
  
  • Just riding the cosmic wave and ready to help, my friend. What are we building today? observatory
    lanterns lit
  
  
  › and [block-user-submit]
  
  
  • Running UserPromptSubmit hook: reading the observatory notes
  
  UserPromptSubmit hook (stopped)
    warning: wizard-tower UserPromptSubmit demo blocked the prompt on purpose.
    stop: Wizard Tower demo block: remove [block-user-submit] to continue.
  ```
  
  .codex/config.toml
  ```
  [features]
  codex_hooks = true
  ```
  
  .codex/hooks.json
  ```
  {
    "hooks": {
      "UserPromptSubmit": [
        {
          "hooks": [
            {
              "type": "command",
              "command": "/usr/bin/python3 .codex/hooks/user_prompt_submit_demo.py",
              "timeoutSec": 10,
              "statusMessage": "reading the observatory notes"
            }
          ]
        }
      ]
    }
  }
  ```
  
  .codex/hooks/user_prompt_submit_demo.py
  ```
  #!/usr/bin/env python3
  
  import json
  import sys
  from pathlib import Path
  
  
  def prompt_from_payload(payload: dict) -> str:
      prompt = payload.get("prompt")
      if isinstance(prompt, str) and prompt.strip():
          return prompt.strip()
  
      event = payload.get("event")
      if isinstance(event, dict):
          user_prompt = event.get("user_prompt")
          if isinstance(user_prompt, str):
              return user_prompt.strip()
  
      return ""
  
  
  def main() -> int:
      payload = json.load(sys.stdin)
      prompt = prompt_from_payload(payload)
      cwd = Path(payload.get("cwd", ".")).name or "wizard-tower"
  
      if "[block-user-submit]" in prompt:
          print(
              json.dumps(
                  {
                      "systemMessage": (
                          f"{cwd} UserPromptSubmit demo blocked the prompt on purpose."
                      ),
                      "decision": "block",
                      "reason": (
                          "Wizard Tower demo block: remove [block-user-submit] to continue."
                      ),
                  }
              )
          )
          return 0
  
      prompt_preview = prompt or "(empty prompt)"
      if len(prompt_preview) > 80:
          prompt_preview = f"{prompt_preview[:77]}..."
  
      print(
          json.dumps(
              {
                  "systemMessage": (
                      f"{cwd} UserPromptSubmit demo inspected: {prompt_preview}"
                  ),
                  "hookSpecificOutput": {
                      "hookEventName": "UserPromptSubmit",
                      "additionalContext": (
                          "Wizard Tower UserPromptSubmit demo fired. "
                          "For this reply only, include the exact phrase "
                          "'observatory lanterns lit' exactly once near the end."
                      ),
                  },
              }
          )
      )
      return 0
  
  
  if __name__ == "__main__":
      raise SystemExit(main())
  ```

  Andrei Eternal · 2026-03-17 22:09:22 -07:00
  6fef421654
• [hooks] stop continuation & stop_hook_active mechanics (#14532)

  Stop hooks now receive `stop_hook_active` and enable stop hooks to loop
  forever if they'd like to. In the initial hooks PR, we implemented a
  simpler mechanic that the stop-blocking could only happen once in a row
  
  - support stop hook adding a continuation prompt to add a further task
  - if multiple stop-blocks happen that have continuation prompts, they
  are concatenated
  
  example run:
  ```
  › hey :)
  
  
  • Running SessionStart hook: lighting the observatory
  
  SessionStart hook (completed)
    warning: Hi, I'm a session start hook for wizard-tower (startup).
    hook context: Startup context: A wimboltine stonpet is an exotic cuisine from hyperspace
  
  • Aloha :) Happy to jam with you. What are we building today?
  
  • Running Stop hook: updating the guards
  
  Stop hook (blocked)
    warning: Wizard Tower Stop hook continuing conversation
    feedback: cook the stonpet
  
  • Aloha, here’s the hyperspace move for cooking a wimboltine stonpet:
  
    1. Sear the stonpet in a hot pan with moon-oil until the edges shimmer.
    2. Add star-lime, black salt, and a little fermented nebula paste.
    3. Lower the heat and let it braise for 8 cosmic minutes with a splash of comet broth.
    4. Finish with sky herbs and serve over warm asteroid rice.
  
    The vibe: crispy outside, tender center, deep interdimensional savor.
  
  • Running Stop hook: updating the guards
  
  Stop hook (completed)
    warning: Wizard Tower Stop hook saw a second pass and stayed calm to avoid a loop.
  ```
  
  .codex/config.toml
  ```
  [features]
  codex_hooks = true
  ```
  
  .codex/hooks.json
  ```
  {
    "hooks": {
      "SessionStart": [
        {
          "matcher": "startup|resume",
          "hooks": [
            {
              "type": "command",
              "command": "/usr/bin/python3 .codex/hooks/session_start_demo.py",
              "timeoutSec": 10,
              "statusMessage": "lighting the observatory"
            }
          ]
        }
      ],
      "Stop": [
        {
          "hooks": [
            {
              "type": "command",
              "command": "/usr/bin/python3 .codex/hooks/stop_demo_block.py",
              "timeoutSec": 10,
              "statusMessage": "updating the guards"
            }
          ]
        }
      ]
    }
  }
  ```
  
  .codex/hooks/session_start_demo.py
  ```
  #!/usr/bin/env python3
  
  import json
  import sys
  from pathlib import Path
  
  
  def main() -> int:
      payload = json.load(sys.stdin)
      cwd = Path(payload.get("cwd", ".")).name or "wizard-tower"
      source = payload.get("source", "startup")
      source_label = "resume" if source == "resume" else "startup"
      source_prefix = (
          "Resume context:"
          if source == "resume"
          else "Startup context:"
      )
  
      output = {
          "systemMessage": (
              f"Hi, I'm a session start hook for {cwd} ({source_label})."
          ),
          "hookSpecificOutput": {
              "hookEventName": "SessionStart",
              "additionalContext": (
                  f"{source_prefix} A wimboltine stonpet is an exotic cuisine from hyperspace"
              ),
          },
      }
      print(json.dumps(output))
      return 0
  
  
  if __name__ == "__main__":
      raise SystemExit(main())
  ```
  
  .codex/hooks/stop_demo_block.py
  ```
  #!/usr/bin/env python3
  
  import json
  import sys
  
  
  def main() -> int:
      payload = json.load(sys.stdin)
      stop_hook_active = payload.get("stop_hook_active", False)
      last_assistant_message = payload.get("last_assistant_message") or ""
      char_count = len(last_assistant_message.strip())
  
      if stop_hook_active:
          system_message = (
              "Wizard Tower Stop hook saw a second pass and stayed calm to avoid a loop."
          )
          print(json.dumps({"systemMessage": system_message}))
      else:
          system_message = (
              f"Wizard Tower Stop hook continuing conversation"
          )
          print(json.dumps({"systemMessage": system_message, "decision": "block", "reason": "cook the stonpet"}))
  
      return 0
  
  
  if __name__ == "__main__":
      raise SystemExit(main())
  ```

  Andrei Eternal · 2026-03-13 15:51:19 -07:00
  9a44a7e499
• start of hooks engine (#13276)

  (Experimental)
  
  This PR adds a first MVP for hooks, with SessionStart and Stop
  
  The core design is:
  
  - hooks live in a dedicated engine under codex-rs/hooks
  - each hook type has its own event-specific file
  - hook execution is synchronous and blocks normal turn progression while
  running
  - matching hooks run in parallel, then their results are aggregated into
  a normalized HookRunSummary
  
  On the AppServer side, hooks are exposed as operational metadata rather
  than transcript-native items:
  
  - new live notifications: hook/started, hook/completed
  - persisted/replayed hook results live on Turn.hookRuns
  - we intentionally did not add hook-specific ThreadItem variants
  
  Hooks messages are not persisted, they remain ephemeral. The context
  changes they add are (they get appended to the user's prompt)

  Andrei Eternal · 2026-03-10 04:11:31 +00:00
  244b2d53f4