policy:
  allow_implicit_invocation: true

# Codex Hooks, App-server, and Trust

Use this reference for a question about Codex hooks, managed hooks, hook trust, or automating hook configuration. Fetch
and cite the live official source first:

- [Codex hooks](https://developers.openai.com/codex/hooks)
- [Codex app-server](https://developers.openai.com/codex/app-server)

## Official behavior

The hooks page is authoritative for supported events, configuration, managed-hook behavior, and the interactive `/hooks`
surface. It documents that managed hooks are centrally controlled. Do not present an app-server operation, config key,
or on-disk trust representation as official unless the current page says so.

The app-server page is authoritative for the public JSON-RPC/app-server contract. It documents the JSONL stdio
transport, `initialize`/`initialized` handshake, `hooks/list`, `config/read`, and atomic `config/batchWrite`. Treat
exact request and response fields as version-sensitive: check the installed `codex --version` and generated schema
before relying on fields absent from the live page.

`--dangerously-bypass-hook-trust` bypasses hook trust for one Codex invocation. It is not a persistent trust grant; do
not recommend it as a replacement for a narrowly authorized configuration update.

## Local implementation notes: Codex CLI 0.156.1

Everything in this section was verified against `codex-cli 0.156.1` and its generated app-server JSON Schema. It is not
a promise about older or newer versions.

Start the app-server over stdio and exchange JSONL. Send `initialize`, wait for its response, then send the
`initialized` notification before using the v2 methods below. Generate a fresh schema in an operating-system temporary
directory when exact request or response shapes matter:

```sh
codex app-server generate-json-schema --out "$TMPDIR/codex-app-server-schema"
```

The schema exposes:

- `hooks/list`, which returns hook metadata including `key`, `source`, `sourcePath`, `isManaged`, `currentHash`, and
  `trustStatus`.
- `config/read`, which can return effective config and layers.
- `config/batchWrite`, an atomic batch edit with `filePath` and `expectedVersion`.

For a task that creates or changes hooks, use `hooks/list` to identify precisely the hooks it owns. Require an enabled,
non-managed user command hook from the active hook source path, then match its event, command, matcher, timeout, and
additional-context limit exactly against the task's authorized hook definition. Reject missing, duplicate, malformed, or
merely similar hooks; never broaden the selection to every hook in the same event, source file, project, or config
layer.

The local user-config representation for a trusted hook is:

```toml
[hooks.state."<TOML-quoted key>"]
trusted_hash = "<server-reported currentHash>"
```

For `config/batchWrite`, express the edit as `hooks.state."<TOML-double-quoted-and-escaped key>".trusted_hash`. Quote
the complete server-reported `key` as one TOML key segment, including the surrounding double quotes and TOML escapes; do
not split or normalize it. Do not calculate the hash manually. Obtain `currentHash` from the same app-server hook record
and write only the owned hook's trust state.

Read config with layers, select the user layer whose `name.file` is the active `$CODEX_HOME/config.toml`, and retain its
`version`. Submit all owned-hook trust edits in one `config/batchWrite` using that path as `filePath` and the retained
version as `expectedVersion`; this is a compare-and-swap, not a blind overwrite. If discovery, write, or verification
observes a changed version or stale state, re-run both hook and config discovery from fresh state and retry the bounded
operation. Do not replay an edit derived from stale hook metadata.

After writing, verify in a fresh Codex process: initialize, send `initialized`, list hooks again, and confirm only the
task-owned hooks have the intended trust status and current hash. Bound failures and retries. Report configuration
conflicts, malformed config, unavailable protocol methods, or a nonconverging concurrent writer instead of widening
trust or bypassing it persistently.

Authorization is narrow: an agent may trust only hooks that its authorized task created or changed. Editing a trust
entry is a configuration write; obtain the required authorization before doing it. Managed hooks remain governed by
their managed configuration and should not be treated as locally trustable task output.

#!/bin/bash

set -euo pipefail

fresh_limit_seconds=86400
stale_limit_seconds=604800
lock_wait_seconds=35
stale_lock_seconds=60

usage() {
  cat >&2 <<'EOF'
Usage: fetch-doc.sh [--refresh] <codex-manual|codex-config-schema>

Reuse fresh cached artifacts and conditionally revalidate older fixed Codex documentation artifacts.
Prints the absolute cached file path on stdout.
EOF
}

die() {
  printf 'agents-docs: %s\n' "$1" >&2
  exit "${2:-1}"
}

refresh=false
if [ "${1:-}" = '--refresh' ]; then
  refresh=true
  shift
fi

if [ "$#" -ne 1 ]; then
  usage
  exit 64
fi

artifact=$1
case "$artifact" in
  codex-manual)
    source_url='https://developers.openai.com/codex/codex-manual.md'
    redirected_url='https://learn.chatgpt.com/docs/codex-manual.md'
    body_name='codex-manual.md'
    content_marker='title: "Codex Manual"'
    ;;
  codex-config-schema)
    source_url='https://developers.openai.com/codex/config-schema.json'
    redirected_url='https://learn.chatgpt.com/docs/config-schema.json'
    body_name='config-schema.json'
    content_marker="\"\$schema\":"
    ;;
  *)
    die "unknown artifact '$artifact'" 64
    ;;
esac

umask 077

if [ -n "${AGENTS_DOCS_CACHE_DIR:-}" ]; then
  cache_root=$AGENTS_DOCS_CACHE_DIR
elif [ -n "${XDG_CACHE_HOME:-}" ]; then
  cache_root=$XDG_CACHE_HOME/agents-docs
elif [ "$(uname -s)" = 'Darwin' ]; then
  [ -n "${HOME:-}" ] || die 'HOME is required to resolve the cache directory'
  cache_root=$HOME/Library/Caches/agents-docs
else
  [ -n "${HOME:-}" ] || die 'HOME is required to resolve the cache directory'
  cache_root=$HOME/.cache/agents-docs
fi

mkdir -p "$cache_root" || die "cannot create cache directory: $cache_root"
cache_root=$(cd "$cache_root" && pwd -P) || die "cannot resolve cache directory: $cache_root"

body_file=$cache_root/$body_name
metadata_file=$cache_root/$artifact.meta
lock_dir=$cache_root/$artifact.lock

headers_tmp=''
body_tmp=''
metadata_tmp=''
lock_owned=false

cleanup() {
  if [ -n "$headers_tmp" ]; then
    rm -f "$headers_tmp"
  fi
  if [ -n "$body_tmp" ]; then
    rm -f "$body_tmp"
  fi
  if [ -n "$metadata_tmp" ]; then
    rm -f "$metadata_tmp"
  fi
  if [ "$lock_owned" = true ]; then
    rmdir "$lock_dir" 2>/dev/null || true
  fi
}

trap cleanup EXIT
trap 'exit 129' HUP
trap 'exit 130' INT
trap 'exit 143' TERM

lock_attempt=0
while ! mkdir "$lock_dir" 2>/dev/null; do
  now_epoch=$(date -u +%s)
  lock_epoch=$(stat -f '%m' "$lock_dir" 2>/dev/null || stat -c '%Y' "$lock_dir" 2>/dev/null || printf '0\n')
  case "$lock_epoch" in
    ''|*[!0-9]*) lock_epoch=0 ;;
  esac

  if [ "$lock_epoch" -gt 0 ] && [ $((now_epoch - lock_epoch)) -gt "$stale_lock_seconds" ]; then
    if rmdir "$lock_dir" 2>/dev/null; then
      continue
    fi
  fi

  lock_attempt=$((lock_attempt + 1))
  if [ "$lock_attempt" -ge "$lock_wait_seconds" ]; then
    die "cache lock remained busy for $lock_wait_seconds seconds: $artifact"
  fi
  sleep 1
done
lock_owned=true

metadata_value() {
  local key=$1
  local file=$2

  [ -f "$file" ] || return 1
  sed -n "s/^${key}=//p" "$file" | sed -n '1p'
}

validate_body() {
  local file=$1
  local byte_count

  [ -f "$file" ] || return 1
  byte_count=$(wc -c <"$file" | tr -d '[:space:]')
  case "$byte_count" in
    ''|*[!0-9]*) return 1 ;;
  esac
  [ "$byte_count" -ge 1024 ] || return 1
  grep -Fq -- "$content_marker" "$file"
}

allowed_effective_url() {
  [ "$1" = "$source_url" ] || [ "$1" = "$redirected_url" ]
}

final_header_value() {
  local header_name=$1
  local file=$2

  awk -v wanted="$header_name" '
    /^HTTP\// { value = "" }
    {
      line = $0
      sub(/\r$/, "", line)
      separator = index(line, ":")
      if (separator > 0 && tolower(substr(line, 1, separator - 1)) == tolower(wanted)) {
        value = substr(line, separator + 1)
        sub(/^[[:space:]]+/, "", value)
      }
    }
    END { print value }
  ' "$file"
}

write_metadata() {
  local effective_url=$1
  local etag=$2
  local last_modified=$3
  local validated_epoch=$4
  local validated_utc=$5

  metadata_tmp=$(mktemp "$cache_root/.fetch-doc.metadata.XXXXXX")
  {
    printf 'format=1\n'
    printf 'effective_url=%s\n' "$effective_url"
    printf 'etag=%s\n' "$etag"
    printf 'last_modified=%s\n' "$last_modified"
    printf 'validated_at_epoch=%s\n' "$validated_epoch"
    printf 'validated_at_utc=%s\n' "$validated_utc"
  } >"$metadata_tmp"
  mv -f "$metadata_tmp" "$metadata_file"
  metadata_tmp=''
}

current_format=$(metadata_value format "$metadata_file" 2>/dev/null || true)
current_effective_url=$(metadata_value effective_url "$metadata_file" 2>/dev/null || true)
current_etag=$(metadata_value etag "$metadata_file" 2>/dev/null || true)
current_last_modified=$(metadata_value last_modified "$metadata_file" 2>/dev/null || true)
current_validated_epoch=$(metadata_value validated_at_epoch "$metadata_file" 2>/dev/null || true)
current_validated_utc=$(metadata_value validated_at_utc "$metadata_file" 2>/dev/null || true)

have_valid_cache=false
if [ "$current_format" = 1 ] && [ -n "$current_validated_utc" ] && \
  allowed_effective_url "$current_effective_url" && validate_body "$body_file"; then
  case "$current_validated_epoch" in
    ''|*[!0-9]*) ;;
    *) have_valid_cache=true ;;
  esac
fi

cache_age=''
if [ "$have_valid_cache" = true ]; then
  now_epoch=$(date -u +%s)
  cache_age=$((now_epoch - current_validated_epoch))
fi

if [ "$refresh" = false ] && [ "$have_valid_cache" = true ] && \
  [ "$cache_age" -ge 0 ] && [ "$cache_age" -le "$fresh_limit_seconds" ]; then
  printf 'agents-docs: cached %s last validated at %s (%s)\n' \
    "$artifact" "$current_validated_utc" "$current_effective_url" >&2
  printf '%s\n' "$body_file"
  exit 0
fi

headers_tmp=$(mktemp "$cache_root/.fetch-doc.headers.XXXXXX")
body_tmp=$(mktemp "$cache_root/.fetch-doc.body.XXXXXX")

response_code=''
effective_url=''

fetch_once() {
  local conditional=$1
  local curl_output
  local curl_rc
  local curl_args

  : >"$headers_tmp"
  : >"$body_tmp"

  curl_args=(
    --connect-timeout 10
    --dump-header "$headers_tmp"
    --fail
    --location
    --max-time 30
    --output "$body_tmp"
    --proto '=https'
    --proto-redir '=https'
    --show-error
    --silent
    --write-out '%{http_code}\n%{url_effective}\n'
  )

  if [ "$conditional" = true ] && [ -n "$current_etag" ]; then
    curl_args+=(--header "If-None-Match: $current_etag")
  elif [ "$conditional" = true ] && [ -n "$current_last_modified" ]; then
    curl_args+=(--header "If-Modified-Since: $current_last_modified")
  fi

  set +e
  curl_output=$(curl "${curl_args[@]}" "$source_url")
  curl_rc=$?
  set -e
  if [ "$curl_rc" -ne 0 ]; then
    return 1
  fi

  response_code=$(printf '%s\n' "$curl_output" | sed -n '1p')
  effective_url=$(printf '%s\n' "$curl_output" | sed -n '2p')
  return 0
}

print_success() {
  local cache_state=$1
  local validated_utc=$2
  local final_url=$3

  printf 'agents-docs: %s %s at %s (%s)\n' "$cache_state" "$artifact" "$validated_utc" "$final_url" >&2
  printf '%s\n' "$body_file"
}

use_stale_cache() {
  local now_epoch
  local cache_age

  [ "$refresh" = false ] || return 1
  [ "$have_valid_cache" = true ] || return 1

  now_epoch=$(date -u +%s)
  cache_age=$((now_epoch - current_validated_epoch))
  [ "$cache_age" -ge 0 ] || return 1
  [ "$cache_age" -le "$stale_limit_seconds" ] || return 1

  printf 'agents-docs: stale %s last validated at %s (%s); live retrieval failed\n' \
    "$artifact" "$current_validated_utc" "$current_effective_url" >&2
  printf '%s\n' "$body_file"
  return 0
}

conditional=false
if [ "$refresh" = false ] && [ "$have_valid_cache" = true ]; then
  if [ -n "$current_etag" ] || [ -n "$current_last_modified" ]; then
    conditional=true
  fi
fi

if ! fetch_once "$conditional"; then
  if [ "$refresh" = true ]; then
    die "forced refresh failed for $artifact"
  fi
  if use_stale_cache; then
    exit 0
  fi
  die "could not retrieve $artifact and no cache validated within seven days is available"
fi

if ! allowed_effective_url "$effective_url"; then
  die "refused unexpected final URL for $artifact: $effective_url"
fi

if [ "$response_code" = 304 ]; then
  if [ "$have_valid_cache" != true ]; then
    if ! fetch_once false; then
      die "received 304 for unusable $artifact cache and unconditional retrieval failed"
    fi
    if ! allowed_effective_url "$effective_url"; then
      die "refused unexpected final URL for $artifact: $effective_url"
    fi
  else
    validated_epoch=$(date -u +%s)
    validated_utc=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
    write_metadata "$effective_url" "$current_etag" "$current_last_modified" "$validated_epoch" "$validated_utc"
    print_success revalidated "$validated_utc" "$effective_url"
    exit 0
  fi
fi

if [ "$response_code" != 200 ]; then
  die "unexpected HTTP status for $artifact: $response_code"
fi

if ! validate_body "$body_tmp"; then
  die "retrieved invalid content for $artifact"
fi

new_etag=$(final_header_value ETag "$headers_tmp")
new_last_modified=$(final_header_value Last-Modified "$headers_tmp")
validated_epoch=$(date -u +%s)
validated_utc=$(date -u '+%Y-%m-%dT%H:%M:%SZ')

mv -f "$body_tmp" "$body_file"
body_tmp=''
write_metadata "$effective_url" "$new_etag" "$new_last_modified" "$validated_epoch" "$validated_utc"
print_success fetched "$validated_utc" "$effective_url"