Key takeaways

• The current adapter gates recognized deploy-like Bash commands, or every Bash command with --all-bash.
• PreToolUse blocks the command before execution; non-matching commands remain under the normal Codex flow.
• Use approval requests for approve/reject decisions and contro1 ask for a human free-text response.
• A project hook is a convenience gate; managed hooks plus a protected credential boundary are required for enterprise enforcement.

When to add Contro1 to Codex

Use the adapter when a Codex shell action should wait for an accountable person: a production deployment, infrastructure mutation, database migration, release operation, or another organization-specific command. Production deployment is the quickstart example, not a claim that every Codex workflow is a deploy workflow.

The current adapter is intentionally thin. It handles the Bash tool, recognizes common deploy commands, creates a canonical Contro1 approval request, waits for the decision, and returns allow or deny to Codex. It does not yet gate apply_patch, arbitrary local tools, or MCP calls.

Install the CLI and connect your agent identity

Install the public Contro1 CLI, sign in with the safe agent profile, register the Codex agent, and verify connectivity before adding a hook. Agent credentials can create and wait for their own requests but cannot claim or answer operator requests.

curl -fsSL https://raw.githubusercontent.com/contro1-hq/contro1-cli/main/install.sh | sh

contro1 auth login --mode agent
contro1 init --name "Codex - Developer Laptop"
contro1 doctor

Contro1 CLI reference · Windows and release downloads

Developer setup: a project convenience hook

Put the hook in a trusted project at .codex/hooks.json, then open /hooks in Codex to inspect and trust the exact definition. Codex records trust against the hook hash, so a changed hook must be reviewed again.

This default setup gates recognized deploy-like Bash commands. A normal test, read, or local command produces no Contro1 decision and continues through the usual Codex flow.

{
  "description": "Contro1 approval for selected Codex shell actions.",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash
AI Control Plane for Enterprise AI Agents | Contro1
Control AI agents in production with human oversight built in. Contro1 routes approvals, escalations, and critical decisions to the right team by function, role, and shift.
What Contro1 does
Human-in-the-loop approvals for high-impact agent actions
Role-based routing to the right operator across departments
SLA timers and escalation paths for unresolved decisions
Signed webhook callbacks so workflows continue safely
Cross-framework coverage for modern AI agent stacks
Key links
Docs
Resource center
llms.txt
Security policy
quot;,
        "hooks": [
          {
            "type": "command",
            "command": "contro1 hooks codex --role cto --environment production --target billing-api --setup convenience",
            "timeout": 910,
            "statusMessage": "Waiting for human approval"
          }
        ]
      }
    ]
  }
}

Codex hooks reference · Complete convenience template

Choose which Bash commands require approval

The built-in policy recognizes common production mutations including npm, pnpm, or yarn deploy scripts; kubectl mutations; Helm changes; Terraform or OpenTofu apply and destroy; Pulumi up and destroy; production Vercel or Netlify deploys; selected cloud deployment commands; and deploy-oriented GitHub workflow runs.

Repeat --match to add an organization-specific regular expression. Use --all-bash only when every Codex shell command should be reviewed; it is deliberately broader and can add substantial operator friction.

# Add an organization-specific deploy command
contro1 hooks codex --role cto --match '(^|\s)ship-prod(\s|$)'

# Gate every Bash call instead of deploy-like commands only
contro1 hooks codex --role security --all-bash

Approval and Respond solve different problems

A gated action is an approval request: the reviewer approves or rejects the exact reviewed command. A policy-controlled decision comment can explain that decision, but it is not a replacement command and it is not a free-text response.

When Codex needs information rather than permission, create a free_text request with contro1 ask and wait for response.decision_type=respond. The returned string can be passed back into the agent workflow. Keeping these flows separate prevents an ambiguous Respond button from leaving a risky command without a terminal approve or reject decision.

contro1 ask "Which production region should I use?" \
  --role platform-owner \
  --wait \
  --format json

What the reviewer receives

The request contains the redacted command and tool input, hashes of the original values, working directory, branch, commit, workspace-state hash, environment, target, Codex session and tool identifiers, enforcement setup, risk, policy trigger, required role, quorum, separation of duties, and timeout behavior.

Machine-observed facts are kept separate from agent-reported justification. The agent cannot choose its reviewer or downgrade the request risk by changing prompt text.

Enforced enterprise setup

Distribute requirements.toml through a supported cloud, MDM, device, or system policy channel. Pin hooks on, allow only managed hooks, and install the Contro1 binary at the administrator-controlled absolute path referenced by the hook.

Managed Codex configuration protects the configured Codex path. To protect production itself, remove standing deployment credentials from developer machines and release short-lived credentials only inside protected CI or a deployment broker after the approval is verified.

allow_managed_hooks_only = true
allowed_approval_policies = ["on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

[features]
hooks = true

[hooks]
managed_dir = "/opt/contro1/hooks"
windows_managed_dir = 'C:\Program Files\Contro1\hooks'

[[hooks.PreToolUse]]
matcher = "^Bash
AI Control Plane for Enterprise AI Agents | Contro1
Control AI agents in production with human oversight built in. Contro1 routes approvals, escalations, and critical decisions to the right team by function, role, and shift.
What Contro1 does
Human-in-the-loop approvals for high-impact agent actions
Role-based routing to the right operator across departments
SLA timers and escalation paths for unresolved decisions
Signed webhook callbacks so workflows continue safely
Cross-framework coverage for modern AI agent stacks
Key links
Docs
Resource center
llms.txt
Security policy
quot;

[[hooks.PreToolUse.hooks]]
type = "command"
command = "/usr/local/bin/contro1 hooks codex --role cto --environment production --setup enterprise"
command_windows = 'C:\Program Files\Contro1\contro1.exe hooks codex --role cto --environment production --setup enterprise'
timeout = 910
statusMessage = "Waiting for enterprise approval"

Complete managed template · Production credential-boundary architecture

Know the enforcement boundary

• A project hook is a developer convenience gate and can be changed or removed by someone who controls the project configuration.
• A managed hook prevents ordinary user or project configuration from bypassing the governed Codex path.
• Codex hooks do not protect commands run from another terminal or client.
• A protected CI environment, deployment broker, or credential issuer is the final control point for a non-bypassable production path.
• The adapter records the approval decision; it does not provide cryptographic attestation that the approved command later completed.

Frequently asked questions

Can the current adapter gate every Codex tool?

No. The current public adapter handles Bash and can gate deploy-like commands or all Bash commands. Codex supports hooks for additional local tools, but the Contro1 adapter must add and test those mappings before we document them as supported.

Can a reviewer Respond instead of approving or rejecting?

Use Respond for a separate free_text request created with contro1 ask. A risky command still requires a terminal approve or reject decision; a decision comment can accompany either outcome.

Can the reviewer edit the command?

No. Reject the request and submit a new command so its input hash, policy evaluation, and decision history remain immutable and reviewable.

Is a project hook non-bypassable?

No. Use centrally managed hooks for the Codex path and protect the production credential behind CI or a deployment broker for target-side enforcement.

Related resources