Configuration

Runtime configuration lives at .codex/hooks/airs-config.json (project-level) or ~/.codex/hooks/airs-config.json (global). The config loader searches in this order:

1. cwd/.codex/hooks/airs-config.json, then each parent directory's .codex/hooks/airs-config.json (Codex may start hooks from a repo subdirectory)
2. ~/.codex/hooks/airs-config.json (global fallback)
3. cwd/airs-config.json (project root)

Full Config Example

{
  "endpoint": "${PRISMA_AIRS_API_ENDPOINT}",
  "apiKeyEnvVar": "PRISMA_AIRS_API_KEY",
  "profiles": {
    "prompt": "${PRISMA_AIRS_PROMPT_PROFILE}",
    "response": "${PRISMA_AIRS_RESPONSE_PROFILE}",
    "tool": "${PRISMA_AIRS_TOOL_PROFILE}"
  },
  "mode": "enforce",
  "fail_mode": "open",
  "timeout_ms": 3000,
  "retry": {
    "enabled": true,
    "max_attempts": 1,
    "backoff_base_ms": 200
  },
  "logging": {
    "path": "~/.codex/hooks/airs-scan.log",
    "include_content": false
  },
  "enforcement": {
    "prompt_injection": "block",
    "dlp": "block",
    "malicious_code": "block",
    "url_categorization": "block",
    "toxicity": "block",
    "custom_topic": "block"
  },
  "circuit_breaker": {
    "enabled": true,
    "failure_threshold": 5,
    "cooldown_ms": 60000
  },
  "content_limits": {
    "max_scan_bytes": 51200,
    "truncate_bytes": 20000
  }
}

Modes

Mode	Behavior
observe	Log scan results, never block. Start here to audit before enforcing.
enforce	Block prompts/MCP tool calls that AIRS flags; terminate the turn on flagged responses.
bypass	Skip scanning entirely. Useful for debugging.

Fail Mode

fail_mode controls what happens when scanning itself fails (AIRS unreachable, config errors):

Value	Behavior
open (default)	Never block the developer on infrastructure or config errors.
closed	Block prompts and MCP tool calls when the scan cannot complete.

Stop is always fail-open

The Stop hook scans the final response after it has already streamed. Blocking on error would be meaningless post-display, so response scanning fails open regardless of fail_mode.

Enforcement Actions

When mode is enforce, each detection service can be configured independently:

Action	Behavior
block	Prevent the prompt/tool call from passing through (or terminate the turn for responses)
mask	Replace sensitive content and allow through (DLP)
allow	Log the detection but allow through

Priority order

If multiple detection services trigger, the strictest action wins: block > mask > allow.

Environment Variable Resolution

Config values containing ${VAR_NAME} are resolved from environment variables at load time. If the variable is unset, defaults apply:

Config Field	Env Var	Fallback
endpoint	PRISMA_AIRS_API_ENDPOINT	https://service.api.aisecurity.paloaltonetworks.com
profiles.prompt	PRISMA_AIRS_PROMPT_PROFILE	PRISMA_AIRS_PROFILE_NAME → Codex CLI - Hooks
profiles.response	PRISMA_AIRS_RESPONSE_PROFILE	PRISMA_AIRS_PROFILE_NAME → Codex CLI - Hooks
profiles.tool	PRISMA_AIRS_TOOL_PROFILE	PRISMA_AIRS_PROFILE_NAME → Codex CLI - Hooks

Logging

Scan results are written as JSON Lines to the configured logging.path. Set include_content: true to include prompt/response text in logs (disabled by default for privacy).

Logs rotate automatically at 10MB, keeping the 5 most recent rotations.

Circuit Breaker

See Circuit Breaker for details on failure handling.