> For the complete documentation index, see [llms.txt](https://handbook.harmonic.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://handbook.harmonic.security/handbook/2.-supply-chain-and-extensibility/2.6-ai-hooks-inference-controls-and-lifecycle-automation.md).

# 2.6 AI hooks: inference controls and lifecycle automation

How AI hooks work, which products support them, how Anthropic's inference hooks differ from lifecycle hooks, and how to use hooks for narrow control and useful runtime evidence.

*Last reviewed: August 18, 2026*

{% hint style="info" %}
Hooks can give you control and visibility, but only at the lifecycle points they actually cover. Treat every hook as code execution.
{% endhint %}

## Two different things called "hooks"

Anthropic uses the word "hooks" for two unrelated capabilities. They sit at different layers, are configured by different people, and solve different problems. Confusing them leads to wrong assumptions about what is covered.

**Inference hooks** are an organization-level security control for Claude Enterprise. An admin configures a single HTTPS endpoint, and every governed prompt passes through it before it reaches the model, across Claude.ai, Cowork, and Claude Code. Anthropic sends the conversation transcript to your security endpoint, and you return an allow or deny verdict (default timeout: 5 seconds). A denied prompt never reaches the model; the user sees a policy-blocked message. Three modes: off, shadow (log only), and enforcing. Configuration requires `organization:manage` permission in Claude Platform Admin settings. This is the layer for DLP, compliance, and org-wide prompt governance.

**Lifecycle hooks** are local automation inside Claude Code and the Agent SDK. They fire at specific agent-loop events such as PreToolUse, PostToolUse, SessionStart, and UserPromptSubmit, and run commands or callbacks that can block, modify, or log individual tool calls. They are configured in settings files, managed policy, plugins, or SDK callbacks. This is the layer for tool-level policy and runtime evidence.

|                   | Inference hooks                                   | Lifecycle hooks                                                  |
| ----------------- | ------------------------------------------------- | ---------------------------------------------------------------- |
| **Scope**         | Whole organization, every governed Claude surface | Individual Claude Code / Agent SDK sessions                      |
| **Fires**         | Before inference, on each submitted prompt        | At agent events: before/after tool calls, session start and stop |
| **Decision**      | Allow or deny the entire prompt                   | Block, modify, or log a specific tool call                       |
| **Configured by** | Org admin in Claude Platform Admin settings       | `settings.json`, managed settings, plugins, SDK callbacks        |
| **Best for**      | DLP, compliance, org-wide prompt governance       | Command-level policy, approvals, runtime telemetry               |

The simplest way to hold it: inference hooks gate the entire prompt at the org level before the model runs; lifecycle hooks control specific tool calls and events within a session.

The rest of this page covers lifecycle hooks. Inference hooks are documented separately: see Anthropic's [Inference hooks overview](https://platform.claude.com/docs/en/manage-claude/inference-hooks) and the [configuration guide](https://platform.claude.com/docs/en/manage-claude/inference-hooks-configuration).

## The short version

Lifecycle hooks are commands, HTTP calls, prompts, or tool calls that run automatically at defined moments in an AI session. Common trigger points include session start, user prompt submission, before a tool runs, when an approval is requested, after a tool runs, and when a turn stops.

Hooks give you **control** when they run before an action and can block, deny, require approval, or change the context. Hooks give you **visibility** when they log events, enrich telemetry, send notifications, or record policy decisions after something happens.

They are also a direct execution path. A hook stored in a repository, plugin, skill, or local config can run in the same sensitive moment as the agent. That makes hooks useful, but not casual. They belong in version control, code review, managed settings, and monitoring.

## What hooks give you

| Use                | Control or visibility | Examples                                                                                                                          |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Pre-action policy  | Control               | Block risky shell commands, force approval for production targets, stop writes to sensitive paths, deny unapproved network calls. |
| Approval shaping   | Control               | Require a ticket, classify the action, or force a human prompt before a tool can run.                                             |
| Context injection  | Control               | Add approved policy context, project metadata, data classification, or environment hints at session start.                        |
| Runtime logging    | Visibility            | Record tool name, target, working directory, command hash, rule ID, decision, and result.                                         |
| Notifications      | Visibility            | Send high-risk events to a queue, case system, Slack channel, or SIEM path.                                                       |
| Post-action review | Visibility            | Capture tool result metadata, failures, denials, and policy outcomes after the action completes.                                  |

The important limit: post-action hooks cannot prevent the action that already ran, and pre-action hooks only cover the tools and paths the product routes through that hook system. Use hooks with sandboxing, approvals, MCP governance, plugin review, and OTel. Do not use them as your only boundary.

## Product support

| Product       | Hook support                                                                                                                  | What security gets                                                                                                                                                                                                | Watch-outs                                                                                                                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Cowork | No Cowork-specific lifecycle hook surface in the reviewed docs. Org-level inference hooks do gate Cowork prompts (see above). | Use inference hooks for prompt-level governance, plus Cowork permissions, OTel, plugin review, MCP governance, browser controls, Computer Use policy, and scheduled-task governance.                              | If a Cowork workflow delegates into Claude Code or desktop extensibility, govern that underlying surface separately.                                                                         |
| Claude Code   | Yes (lifecycle hooks). Also covered by org-level inference hooks.                                                             | Lifecycle hooks using commands, HTTP endpoints, MCP tools, prompts, agents, managed policy, plugin or skill locations, and project or local settings. Pre-tool and permission hooks can block or shape decisions. | Hooks can arrive through project config, plugins, skills, and user settings. Managed-only hooks are the safer enterprise stance.                                                             |
| Claude Tag    | No user-defined hook surface in the reviewed docs.                                                                            | Use channel access, service-account scope, Agent Proxy allowlists, audit exports, Slack records, and connected-system logs.                                                                                       | Tag runs as a channel agent. Manage it through channel governance rather than hook policy.                                                                                                   |
| ChatGPT Codex | Yes, currently as an experimental hook system.                                                                                | Session and tool lifecycle hooks, deterministic checks, logging, notifications, and narrow pre-tool controls.                                                                                                     | Codex documents hooks as guardrails, not a complete enforcement boundary. Repo-local `.codex` config can carry hook behavior, and some specialized paths may not use the default hook route. |
| ChatGPT Work  | No native user-defined Work hook surface in the reviewed guides.                                                              | Use workspace access, app action controls, approvals, connector governance, scheduled-task controls, endpoint logs, Compliance Logs, and Codex OTel where applicable.                                             | Do not assume Work inherits every Codex local hook behavior, especially for hosted Work tasks.                                                                                               |

## How to use hooks technically

Use hooks for narrow, deterministic rules. A hook should make one decision clearly, log that decision, and fail in the safest direction for high-risk actions.

A good first hook program covers:

1. **High-risk shell commands.** Require approval or deny commands that push code, change infrastructure, delete broadly, alter credentials, or call external upload endpoints.
2. **Sensitive paths.** Deny reads or writes involving secrets, home directories, cloud drives, credential stores, and unrelated projects.
3. **Network egress.** Alert or deny unexpected external calls, especially where the sandbox cannot enforce an allowlist.
4. **Production targets.** Require ticket context before actions against production, customer data, finance systems, identity systems, or public publishing.
5. **Telemetry enrichment.** Add rule IDs, data classification, project owner, policy version, and decision fields to OTel or another evidence path.

A safe hook rule reads like this:

```yaml
event: PreToolUse
match: Bash
detect:
  - broad_delete
  - external_upload
  - production_change
  - credential_access
decision: deny_or_require_approval
log:
  - user
  - product
  - workspace
  - command_hash
  - rule_id
  - decision
  - timestamp
```

That example is intentionally a pattern, not a product-specific file. Use the vendor syntax for Claude Code or Codex, then keep the intent and logging fields stable across products.

For Claude Code, manage hooks through enterprise-managed settings where possible. Restrict unmanaged hooks, review project hooks before trusting a repository, and treat plugin and skill hooks as part of the plugin security review. Where the platform supports it, allow only managed hooks for normal users and keep user or project hooks for small expert groups.

For Codex, remember that hook behavior can come from config layers, including repo-local `.codex` files. Keep the experimental feature disabled for broad groups until you have reviewed the source, tested the rules, and confirmed which tool paths are actually covered.

## How to use hooks as a practitioner

A practitioner should start from risks, not from the excitement of having lifecycle automation.

For ChatGPT Work and Claude Cowork programs, the top concerns are prompt injection, local file access, connectors, browser or Computer Use, scheduled work, plugins, MCP servers, and gaps in action-level evidence. Lifecycle hooks help only where the product routes actions through a hookable runtime. That usually means Claude Code and Codex first. For prompt-level governance across every Claude surface, inference hooks are the right tool.

Use hooks when the rule is objective:

* Block or ask before a risky command.
* Require a ticket before production actions.
* Prevent writes outside an approved workspace.
* Alert when a repo carries hook configuration.
* Add a policy version and data-classification label to runtime telemetry.
* Send high-risk action metadata to the SIEM.

Do not use hooks for broad judgment calls such as "is this prompt safe" or "is this code secure." Those belong in policy, approvals, review workflows, model-side safety checks, and downstream scanners. Hooks are strongest when the condition is concrete and the decision is quick.

## Governance checklist

Before enabling hooks for a group, answer these questions:

| Question                  | Good answer                                                                       |
| ------------------------- | --------------------------------------------------------------------------------- |
| Who owns the hook?        | A named team, with a code owner and escalation path.                              |
| Where is the source?      | A reviewed repository, not an unmanaged local script.                             |
| Who can change it?        | A small group with change review and history.                                     |
| Where can it send data?   | Approved internal destinations only, with external URLs blocked or reviewed.      |
| What secrets can it read? | Ideally none. If needed, pass only scoped values through managed secret handling. |
| Does it fail closed?      | Yes for deny rules and high-risk controls.                                        |
| Is it logged?             | Yes, including source, trigger, target, result, and failure state.                |
| Is it tested?             | Yes, with canary prompts and commands before rollout and after changes.           |

## Review project-carried hooks like supply chain

Project hooks are convenient because a repository can define its own workflow. That is also the risk. A cloned repo can carry hook behavior that runs during an AI session, and reviewers may miss it because it looks like configuration rather than code.

For managed environments:

* Inventory hook files during repo intake.
* Alert on new or changed hook config.
* Block project hooks for normal users unless the repo is trusted and the hook owner is named.
* Review plugin, skill, MCP, and hook changes together, because they can combine into one execution path.
* Compare hook logs with OTel and sandbox denials. Mismatches usually mean either a coverage gap or a broken telemetry path.

## What to avoid

* Do not use hooks as a replacement for sandboxing. Hooks are conditional logic. Sandboxes are boundaries.
* Do not allow hooks to post prompts, files, or tool arguments to arbitrary URLs.
* Do not let repo-local hooks run for broad employee groups without review.
* Do not assume PostToolUse means prevention. It is after the action.
* Do not rely on hook logs alone for investigations. Join them with OTel, endpoint logs, provider audit records, and target-system logs.
* Do not assume lifecycle hooks give you org-wide prompt governance, and do not assume inference hooks give you tool-level control. They are different layers; most programs need both.

## Sources and related guidance

* [Securing ChatGPT Work: A Practitioner's Guide](https://www.harmonic.security/resources/securing-chatgpt-work-a-practitioners-guide)
* [Securing Claude Cowork: A Security Practitioner's Guide](https://www.harmonic.security/resources/securing-claude-cowork-a-security-practitioners-guide)
* [Inference hooks (Claude Platform)](https://platform.claude.com/docs/en/manage-claude/inference-hooks)
* [Configure inference hooks (Claude Platform)](https://platform.claude.com/docs/en/manage-claude/inference-hooks-configuration)
* [Claude Code hooks](https://code.claude.com/docs/en/hooks)
* [Claude Code permissions](https://code.claude.com/docs/en/permissions)
* [Claude Code settings](https://code.claude.com/docs/en/settings)
* [Codex hooks](https://developers.openai.com/codex/hooks)
* [Codex sandboxing](https://developers.openai.com/codex/concepts/sandboxing)
* [ChatGPT Work and Codex](https://help.openai.com/en/articles/20001275-chatgpt-work-and-codex)

## Related handbook guidance

* [2. Supply Chain & Extensibility](/handbook/2.-supply-chain-and-extensibility.md)
* [4.1 DLP for GenAI](/handbook/4.-data-protection-and-residency/4.1-dlp-for-genai.md)
* [1.7 Human-in-the-loop and approval policies](/handbook/1.-identity-and-access/1.7-human-in-the-loop-and-approval-policies.md)
* [6.2 OpenTelemetry for AI runtime visibility](/handbook/6.-observability-audit-and-evidence/6.2-opentelemetry-for-ai-runtime-visibility.md)
* [5.1 Prompt injection: the connective risk](/handbook/5.-threats-and-adversarial/5.1-prompt-injection-the-connective-risk.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://handbook.harmonic.security/handbook/2.-supply-chain-and-extensibility/2.6-ai-hooks-inference-controls-and-lifecycle-automation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.