Run mandatory checks with hooks

Learning objective

Use a hook when a check must run at a defined point before or after a coding agent action. This lesson focuses on choosing and placing the hook, not on building a complete enterprise policy system.

Core idea

Treat a hook as a checkpoint in the agent lifecycle. The agent harness, not the model, invokes the checkpoint when the configured event occurs. This makes the check’s timing deterministic: the model does not decide whether to remember or run it.

Place the hook according to what the check must accomplish:

• Use a pre-action hook when the result must affect whether the action can start.
• Use a post-action hook when the check needs the action’s result or must record, format, or validate what happened.

The boundary matters. A pre-action hook can prevent a side effect. A post-action hook can detect or respond to a problem, but it cannot make the completed action never have happened.

How it works

Antigravity hooks run scripts or shell commands at configured execution-loop events. Its supported events include PreToolUse, PostToolUse, PreInvocation, PostInvocation, and Stop. Tool hooks can use a regular expression matcher to select tool names (Hooks). Choose the event closest to the boundary that owns the requirement.

For a tool action, the lifecycle is:

1. The model proposes a tool name and arguments.
2. A matching PreToolUse hook receives the proposed call.
3. The hook returns a decision, such as allow, deny, ask, or force_ask.
4. If permitted, the harness executes the tool.
5. A matching PostToolUse hook receives the executed call and any error.

The official contract sends hook input as JSON on standard input and expects JSON on standard output. PreToolUse receives toolCall.name and toolCall.args, so its decision can depend on the concrete proposal. By contrast, PostToolUse receives the completed call and its error status, and its documented output is an empty JSON object (hook input and output contract).

In Antigravity, place workspace hook configuration in .agents/hooks.json. The following configuration attaches a command checker to proposed shell commands:

{
  "command-safety": {
    "PreToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .agents/hooks/check_command.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

The checker parses the proposed command from its input and returns a decision. For example, it can return the following result for a production deployment:

{
  "decision": "force_ask",
  "reason": "Production deployment requires explicit approval."
}

Keep a blocking hook small, bounded by a timeout, and explicit about failure. Test its allow, deny, malformed-input, and unavailable-dependency paths. A deterministic trigger does not make the script correct: a bad matcher can miss an action, and a weak check can approve unsafe arguments.

Key distinctions and trade-offs

Hook versus instruction

An instruction or rule tells the model what it should do. The model interprets that guidance as part of reasoning. A hook attaches executable logic to an event. Use an instruction for judgment, conventions, and preferred behavior; use a hook when the check must not depend on the model remembering it.

For example, “explain risky commands” is useful guidance. “Every proposed run_command call must pass an argument validator” is a lifecycle requirement and belongs in a hook.

Pre-action versus post-action

Use a pre-action hook for authorization, argument validation, approval, or other checks whose failure must stop execution. Use a post-action hook for logging, diagnostics, formatting, or validation that requires the actual outcome. If a formatter runs after a file write, the write has already occurred. If a post-deployment check fails, recovery requires a compensating action such as rollback.

A failed pre-action check stops the action; a failed post-action check can only trigger a compensating action.

Local checkpoint versus independent enforcement

Hooks add latency and introduce dependencies on their scripts and runtime. They also apply only where that agent harness loads them. Google’s secure agentic coding codelab distinguishes agent hooks, which intercept actions mid-trajectory, from remote CI/CD controls that remain an independent security boundary (Secure an AI agent lifecycle). Use defense in depth for high-impact controls: an agent hook gives fast local feedback, while identity, sandbox, service-side authorization, and CI/CD policies protect the underlying system.

Architecture / decision scenario

A platform team lets a coding agent edit deployment manifests and run shell commands. The team has two requirements:

• A command that targets production must not run without an explicit approval.
• Every completed manifest write must produce a formatting result and an audit record.

The architect configures a PreToolUse hook for run_command. The checker examines the proposed arguments and returns force_ask for production targets or deny for prohibited commands. This is the correct boundary because the decision occurs before the command creates a side effect.

The architect configures a PostToolUse hook for file-writing tools. It records the completed call, notes any execution error, and runs the formatter on the affected file. This is the correct boundary because the formatter needs the written file. The team does not call this a preventive security gate: a failed post-action check reports a bad outcome and can trigger remediation, but it cannot erase the original write.

The platform also enforces deployment permissions at the service boundary and repeats validation in CI. The hook improves deterministic local behavior; it does not replace controls outside the agent process.

Common exam traps

• Choosing a rule that says “always run this check” when execution of the check must be guaranteed by the lifecycle.
• Choosing PostToolUse to stop a destructive action. By that event, the tool has already completed.
• Assuming every post-action check is useless because it cannot prevent the action. Post-action context is necessary for audit, formatting, diagnostics, and outcome validation.
• Assuming “deterministic” means the hook always reaches the correct decision. It means the configured checkpoint runs at the event; matcher coverage, script logic, dependencies, and failure handling still need engineering.
• Treating a local agent hook as the only security boundary. High-impact operations still need least privilege and independent enforcement.
• Matching every tool when only one risky boundary needs interception. Broad hooks increase latency, noise, and failure surface.

What to remember

• A hook is executable logic attached to a defined agent-lifecycle event.
• Use a pre-action hook when failure must block or require approval before the action starts.
• Use a post-action hook when the check requires the completed result, and plan remediation because the action has already occurred.
• Deterministic invocation does not guarantee correct hook logic or complete matcher coverage.
• Keep independent controls around high-impact operations; hooks are one layer.

Knowledge check

References

• Google Antigravity, Hooks
• Google Antigravity, Plugins and skills: Managing hooks
• Google Codelabs, Vibecode and Secure an AI Agent Lifecycle with Antigravity and TDD