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.

Connect first

This page is for an organization that runs Codex: choosing which shell commands wait for a person, what the reviewer receives, and a managed requirements.toml that users cannot remove.

Connect Codex first. contro1 connect codex makes Codex on the computer its own agent, with you as its owner and its key in the Contro1 service, and adds the Contro1 MCP server for company apps. The desktop app, the CLI and the IDE extension share that MCP server. Signing Codex in with contro1 mcp login instead also works; Codex then acts as you, and every call is recorded as yours.

Connect Codex: every step

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.

The project hook, and what it gates

The connect page puts the hook in a project at .codex/hooks.json and has you trust it with /hooks. Codex records trust against the hook hash, so a changed hook must be reviewed again. Whoever controls the project configuration can change or remove it, which makes it a convenience gate rather than enforcement.

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

Without --role the request goes to the agent's reviewer (its owner) or the Action's approval policy, and a request from an agent with no owner goes to the admin routing inbox. Add --role <role> only to require a reviewer role somebody in your organization holds, and --target <name> to name the system the command changes.

Add the hook: the connect step · Complete convenience template · Codex hooks reference

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 --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 (when --role is set), 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 --environment production --setup enterprise"
command_windows = 'C:\Program Files\Contro1\contro1.exe hooks codex --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.
• OpenAI documents reviewing and trusting hooks with /hooks in the Codex CLI. Before you rely on the gate in the desktop app or the IDE extension, test it there.
• 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