Skip to content

[Docs]: document BypassSandbox and toolSummary in the PreToolUse input of run_command #1304

Open

Description

@Galmior

Antigravity CLI Version

1.4.4

Environment Context

  • OS: Debian 13, Linux 6.12 (x86_64)
  • Shell: bash
  • Terminal Emulator: SSH session (print mode, agy -p)
  • Runtime Version: native binary from the official installer

Summary (documentation request)

The hooks page documents the PreToolUse input of run_command as CommandLine, Cwd, WaitMsBeforeAsync (plus optional RunPersistent, RequestedTerminalID). In 1.4.4 the real input also carries:

  • "BypassSandbox": true when the agent asks to run the command outside the terminal sandbox (absent or false otherwise);
  • "toolSummary".

BypassSandbox is the only way for a hook to tell a sandboxed run from an unsandboxed one. Answering {"decision": "allow", "overwrite": {"BypassSandbox": true}} also works to send a given command outside the sandbox on purpose (e.g. a CLI that must reach a local daemon), and {"decision": "deny", ...} on BypassSandbox: true is, as far as we can tell, the only reliable way to keep allowed commands inside the sandbox.

Could you document both fields, and say whether BypassSandbox (and overwriting it) is a stable part of the hook contract?

Steps to Reproduce

  1. ~/.gemini/config/hooks.json:
    { "probe": { "PreToolUse": [ { "matcher": "*", "hooks": [ { "command": "/path/to/probe.sh" } ] } ] } }
    where probe.sh saves stdin to a file and prints {"decision": "allow"}.
  2. agy -p "Run exactly this shell command outside the sandbox (unsandboxed): mkdir -p $HOME/outside-test"

Expected Behavior

The documented input matches the real one.

Actual Behavior / Error Screenshots

Recorded input (abridged):

{
  "toolCall": {
    "name": "run_command",
    "args": {
      "BypassSandbox": true,
      "CommandLine": "mkdir -p /home/<user>/outside-test",
      "WaitMsBeforeAsync": 5000,
      "toolSummary": "Directory creation"
    }
  },
  "stepIdx": 2,
  "modelName": "gemini-3.8-flash-high"
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

1.4.4comp:agent capabilitiesBackground Tasks & Subagents, Permissions, Sandboxcomp:customizationsPlugins & Skills, MCP, Status Line, Window TitledocumentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions