Markdownkeyboard_arrow_down

content_copyCopy Markdown

open_in_newView Markdown

Hooks

Hooks allow you to run custom scripts or shell commands at specific points during Antigravity’s execution loop. This is powerful for enforcing custom rules, running linters, or capturing diagnostics automatically.

Configuration

Hooks are configured in a hooks.json file located in your customization directory (e.g., .agents/ in your workspace or ~/.gemini/config/).

Schema and File Format

The hooks.json file maps hook names to their event configurations.

{
  "my-linter-hook": {
    "PostToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/lint.sh",
            "timeout": 10
          }
        ]
      }
    ]
  },
  "safety-gate": {
    "enabled": false,
    "PreToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "command": "./scripts/safety-check.sh"
          }
        ]
      }
    ]
  },
  "reminder": {
    "PreInvocation": [
      {
        "type": "command",
        "command": "./scripts/reminder.sh"
      }
    ]
  }
}

Hook Definition Fields

Supported Events

Matcher

For PreToolUse and PostToolUse, you can use a regular expression in the matcher field to specify which tools trigger the hook:

• "" or "*": Match all tools.
• "run_command": Match exactly run_command.
• "run_command|view_file": Match either tool.
• "browser_.*": Match any tool starting with browser_.

Supported Tools

For PreToolUse and PostToolUse matchers, you can match against standard tool names, grouped by category:

File and Directory Operations

• view_file: View the contents of a file.
  • Arguments: AbsolutePath, StartLine (optional), EndLine (optional), IsSkillFile (optional)
• write_to_file: Create new files.
  • Arguments: TargetFile, Overwrite, CodeContent, Description, IsArtifact (optional), ArtifactMetadata (optional)
• replace_file_content: Edit a single contiguous block of text in a file.
  • Arguments: TargetFile, Instruction, Description, AllowMultiple, TargetContent, ReplacementContent, StartLine, EndLine, TargetLintErrorIds (optional)
• multi_replace_file_content: Make multiple, non-contiguous edits to the same file.
  • Arguments: TargetFile, Instruction, Description, ReplacementChunks (array of chunks), TargetLintErrorIds (optional), ArtifactMetadata (optional)
• list_dir: List the contents of a directory.
  • Arguments: DirectoryPath
• find_by_name: Search for files and directories using glob patterns.
  • Arguments: SearchDirectory, Pattern, Type (optional), Excludes (optional), Extensions (optional), FullPath (optional), MaxDepth (optional)

Search and Research

• grep_search: Fast text searches within specific paths.
  • Arguments: SearchPath, Query, IsRegex (optional), CaseInsensitive (optional), Includes (optional), MatchPerLine (optional)
• search_web: Perform a general web search.
  • Arguments: query, domain (optional)
• read_url_content: Fetch text content of a public URL.
  • Arguments: Url

System and Execution

• run_command: Propose a bash command to run.
  • Arguments: CommandLine, Cwd, WaitMsBeforeAsync, RunPersistent (optional), RequestedTerminalID (optional)
• manage_task: Interact with background tasks.
  • Arguments: Action ('list', 'kill', 'status', 'send_input'), TaskId (optional), Input (optional)
• schedule: Set timers or recurring cron jobs.
  • Arguments: DurationSeconds (optional), CronExpression (optional), MaxIterations (optional), Prompt
• list_permissions: View current resource access grants.
  • Arguments: None
• ask_permission: Request additional scoped permissions.
  • Arguments: Action, Target, Reason

Agent Collaboration

• invoke_subagent: Spawn specialized sub-agents.
  • Arguments: Subagents (array of specs with Prompt, Role, TypeName, Workspace (optional))
• define_subagent: Create a custom sub-agent.
  • Arguments: name, description, system_prompt, enable_mcp_tools (optional), enable_write_tools (optional), enable_subagent_tools (optional)
• send_message: Communicate with other agents.
  • Arguments: Recipient, Message
• manage_subagents: List or terminate active sub-agents.
  • Arguments: Action ('list', 'kill', 'kill_all'), ConversationIds (optional)

Interaction and Media

• ask_question: Ask multiple-choice questions.
  • Arguments: questions (array of questions with question, options, is_multi_select)
• generate_image: Create or edit images.
  • Arguments: Prompt, ImageName, ImagePaths (optional)

Hook Handler Configuration

Each item in the hooks array supports:

Input/Output Contract

Hooks receive input via stdin as JSON and should return output via stdout as JSON. Field names use camelCase.

Common Input Fields

All hooks receive the following system metadata fields in their input payload on stdin:

[TABLE]

PreToolUse

Fires before a tool is executed.

Schema

Input Fields (stdin):

Output Fields (stdout):

[TABLE]

Example

• Input (stdin):

{
  "toolCall": {
    "name": "run_command",
    "args": {
      "CommandLine": "npm test",
      "Cwd": "/workspace/project",
      "WaitMsBeforeAsync": 5000
    }
  },
  "stepIdx": 19,
  "conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
  "workspacePaths": ["/workspace/project"],
  "transcriptPath": "~/.gemini/antigravity/brain/ec33ebf9-0cba-4100-8142-c61503f6c587/.system_generated/logs/transcript.jsonl",
  "artifactDirectoryPath": "~/.gemini/antigravity/brain/ec33ebf9-0cba-4100-8142-c61503f6c587",
  "modelName": "gemini-3.6-flash-medium"
}

• Output (stdout):

{
  "decision": "ask",
  "reason": "Requires confirmation for test execution.",
  "permissionOverrides": ["command(npm test)"]
}

PostToolUse

Fires after a tool completes.

Schema

Input Fields (stdin):

Output Fields (stdout): Returns an empty JSON object {}.

Example

• Input (stdin):

{
  "toolCall": {
    "name": "run_command",
    "args": {
      "CommandLine": "npm test",
      "Cwd": "/workspace/project",
      "WaitMsBeforeAsync": 5000
    }
  },
  "stepIdx": 5,
  "error": "exit status 1",
  "conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
  "workspacePaths": ["/workspace/project"],
  "transcriptPath": "~/.gemini/antigravity/brain/ec33ebf9-0cba-4100-8142-c61503f6c587/.system_generated/logs/transcript.jsonl",
  "artifactDirectoryPath": "~/.gemini/antigravity/brain/ec33ebf9-0cba-4100-8142-c61503f6c587",
  "modelName": "gemini-3.6-flash-medium"
}

• Output (stdout): {}

PreInvocation

Fires before the model is called.

Schema

Input Fields (stdin):

Output Fields (stdout):

Injected Step Schema: Each object in the injectSteps array can have one of the following fields:

• toolCall (object): A tool call to execute.
• userMessage (string): A message from the user.
• ephemeralMessage (string): A transient system message.

Example

• Input (stdin):

{
  "invocationNum": 3,
  "initialNumSteps": 10,
  "conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
  "workspacePaths": ["/workspace/project"],
  "transcriptPath": "~/.gemini/antigravity/brain/ec33ebf9-0cba-4100-8142-c61503f6c587/.system_generated/logs/transcript.jsonl",
  "artifactDirectoryPath": "~/.gemini/antigravity/brain/ec33ebf9-0cba-4100-8142-c61503f6c587",
  "modelName": "gemini-3.6-flash-medium"
}

• Output (stdout):

{
  "injectSteps": [{"ephemeralMessage": "Remember to lint"}]
}

PostInvocation

Fires immediately after each model invocation completes.

Schema

Input Fields (stdin): Same as PreInvocation input fields (invocationNum and initialNumSteps).

Output Fields (stdout):

[TABLE]

Example

• Input (stdin): Same as PreInvocation
• Output (stdout):

{
  "injectSteps": [],
  "terminationBehavior": ""
}

Stop

Fires when the execution loop terminates.

Schema

Input Fields (stdin):

Output Fields (stdout):

Example

• Input (stdin):

{
  "executionNum": 1,
  "terminationReason": "model_stop",
  "error": "",
  "fullyIdle": true,
  "conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
  "workspacePaths": ["/workspace/project"],
  "transcriptPath": "~/.gemini/antigravity/brain/ec33ebf9-0cba-4100-8142-c61503f6c587/.system_generated/logs/transcript.jsonl",
  "artifactDirectoryPath": "~/.gemini/antigravity/brain/ec33ebf9-0cba-4100-8142-c61503f6c587",
  "modelName": "gemini-3.6-flash-medium"
}

• Output (stdout):

{
  "decision": "continue",
  "reason": "Not done yet"
}

Last updated Oct 08, 2026