feat(run): collapse sandbox flags into --mode + Advanced help section#33
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
`agent-gate run --help` had three issues from a dogfood pass:
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:
```
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
What does NOT change (and why)
Test plan
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.