Hooks

Hooks allow you to run custom scripts or shell commands at specific points during Antigravity’s execution loop to enforce rules, execute linters, or capture diagnostics.

/hooks

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"
      }
    ]
  }
}

Each hook definition supports the following fields:

Antigravity supports the following hook events:

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_.

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

The following tools manage files and directories:

• 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)

The following tools search files and the web:

• grep_search: Run 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

The following tools execute commands and manage permissions:

• 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

The following tools coordinate subagents:

• invoke_subagent: Spawn specialized subagents.
  • Arguments: Subagents (array of specs with Prompt, Role, TypeName, Workspace (optional))
• define_subagent: Create a custom subagent.
  • 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 subagents.
  • Arguments: Action ('list', 'kill', 'kill_all'), ConversationIds (optional)

The following tools handle user interaction and media generation:

• 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)

Each item in the hooks array supports the following fields:

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

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

Fires before a tool is executed.

Input fields (stdin):

Output fields (stdout):

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)"]
}

Fires after a tool completes.

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): {}

Fires before the model is called.

Input fields (stdin):

Output fields (stdout):

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 you.
• 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"}]
}

Fires immediately after each model invocation completes.

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

Output fields (stdout):

Example:

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

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

Fires when the execution loop terminates.

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"
}