Skip to content

feat(run): collapse sandbox flags into --mode + Advanced help section#33

Merged
WZ merged 2 commits into
mainfrom
chore/hijack-help-text
May 7, 2026
Merged

feat(run): collapse sandbox flags into --mode + Advanced help section#33
WZ merged 2 commits into
mainfrom
chore/hijack-help-text

Conversation

@WZ
Copy link
Copy Markdown
Owner

@WZ WZ commented May 7, 2026

Why

`agent-gate run --help` had three issues from a dogfood pass:

  1. The `--hijack-host` example pointed at `chatgpt.com` — exactly the case where it doesn't work. Anyone following the example would get empty 101 captures and assume agent-gate was broken.
  2. The two sandbox-related flags (`--permissive`, `--airtight-fail`) presented as independent booleans, when they really name three states of one knob.
  3. The advanced-but-niche flags (`--hijack-host`, `--upstream-ca`, `--upstream-insecure-skip-verify`) sat alphabetically interleaved with the everyday ones, making the everyday case noisier than it needed to be.

What changes

`--mode` replaces `--permissive` and `--airtight-fail`

```
--mode How to force the target's egress through the proxy.
DEFAULT: airtight (recommended for most users). Choose one of:

                airtight        Spawn the target inside the per-OS network jail
                                (macOS sandbox-exec / Linux netns). Falls back to
                                permissive with a stderr warning if unsupported.

                airtight-strict Same as airtight, but refuse to fall back. Abort
                                if the jail is unavailable. Use in CI.

                permissive      Skip the jail; just set HTTPS_PROXY env vars.
                                Agent CAN bypass capture. Use only when you
                                trust the agent or the platform can't jail.

```

The internal launcher surface is unchanged — `parseRunMode` translates the string to the same `(Mode, AirtightFail)` pair the runtime already understood.

Advanced Flags section

New `cmd/agent-gate/usage.go` adds a small custom UsageFunc that splits flags into a primary `Flags:` block and a trailing `Advanced Flags:` block, based on a flag annotation. `--hijack-host`, `--upstream-ca`, and `--upstream-insecure-skip-verify` move into Advanced.

Cleaner hijack-host copy

Now that the section heading does the heavy lifting, the description drops the redundant "Advanced — most users don't need this" preamble and just describes when the flag actually helps.

Boomerang updates

  • README support matrix: `--airtight-fail` → `--mode=airtight-strict`, `--permissive` → `--mode=permissive`
  • README `### Flags` block: rewritten to match the new layout
  • `internal/e2e/airtight_test.go`: `--airtight-fail` → `--mode airtight-strict`
  • `internal/launcher/sandbox_windows.go`: error string updated

What does NOT change (and why)

  • `--enforce-allowlist` stays a separate flag. It controls a different dimension (proxy 403-on-non-allowlisted) than `--mode` (sandbox enforcement). Folding them would either multiply mode values to 6+ or eliminate combinations users legitimately need (`airtight` + enforce, `permissive` + enforce, etc.). `--enforce-allowlist` also has tri-state semantics today (nil = config decides) that a fixed mode value can't preserve.

Test plan

  • `agent-gate run --help` renders the new layout cleanly (verified locally)
  • `go test ./...` clean
  • `go vet ./...` clean
  • `gofmt -l .` clean
  • e2e airtight test still works with the renamed flag (Linux netns path)

Breaking changes

`--permissive` and `--airtight-fail` are removed. Anyone scripting `agent-gate run` with those flags must migrate to `--mode permissive` or `--mode airtight-strict`. Acceptable for a v0.x project per the project's existing CLI evolution pattern.

WZ added 2 commits May 7, 2026 15:58
The flag's --help example pointed users at `--hijack-host chatgpt.com`,
which is exactly the case where it does NOT work — codex 0.128.0 pins
TLS on its WebSocket transport so the hijack handshake fails. Anyone
following the example would get empty 101 captures and assume agent-gate
was broken. The actual codex traffic on that host arrives via an HTTP
fallback that's already captured without the flag.

New help text steers users toward the case the flag DOES help (non-pinned
WS upstreams, typically internal/custom agents) and explicitly calls out
the chatgpt.com pinning footnote, so reading the inline `--help` is
enough to know whether to reach for it.

The flag was also missing from the README's `### Flags` block under
`agent-gate run` since v0.3.0. Added there with the same don't-confuse-
chatgpt.com framing.
…anced Flags section

Two CLI surface changes that share a goal: reduce the cognitive load
of `agent-gate run --help`.

* The two boolean sandbox flags (`--permissive`, `--airtight-fail`)
  collapse into a single `--mode <value>` with three values: `airtight`
  (default; auto-fallback), `airtight-strict` (require jail, abort on
  unsupported), `permissive` (skip jail). The help text leads with
  "DEFAULT: airtight (recommended for most users)" so the safe choice
  is unambiguous at a glance, then describes each value in plain
  English with a 3-line behavioral summary. The internal launcher
  surface is unchanged — `parseRunMode` translates the string to the
  same `(Mode, AirtightFail)` pair the runtime already understood.

* `--hijack-host`, `--upstream-ca`, `--upstream-insecure-skip-verify`
  move into a new "Advanced Flags:" section that prints after the
  primary flag block. New helper `cmd/agent-gate/usage.go` annotates
  flags with a category and supplies a custom UsageFunc that splits
  rendering. Cobra has no native section support; the helper is small
  and self-contained.

The hijack-host description gets one more revision: the old "Advanced
— most users don't need this" prefix is now redundant because the
section heading already says it. Copy is leaner as a result.

Internal e2e tests, the Windows fallback message, and the README's
support matrix + ### Flags block all updated to reference --mode.
@WZ WZ changed the title docs: tighten --hijack-host help and add it to README flags feat(run): collapse sandbox flags into --mode + Advanced help section May 7, 2026
@WZ WZ merged commit c0821bc into main May 7, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant