External command support

[Soph]

Add kubectl-style external commands (entire-<name> → entire <name>)

When a user types entire command, look for an entire-command binary on $PATH and exec it with the remaining args. Stdio, signals, and exit codes pass through. External commands have no protocol, no JSON contract — just argv in, exit code out. Built-ins always win on name conflicts; entire-agent-* is reserved for the external agent protocol and skipped here.

Why kubectl-style and not gh-style

gh manages extensions through gh extension install and a dedicated install dir. That's heavier — version pinning, update notifications, an install registry. Kubectl-style PATH resolution is the lower-friction starting point and migrates cleanly to gh-style later if we ever want managed installs.

Design decisions worth reviewer attention

• Telemetry posture — names on a hardcoded officialPlugins allowlist (currently empty) emit cli_plugin_executed events; everything else runs silently. Mirrors gh's policy because third-party command names can carry sensitive identifiers (project, vendor). Gated on exit-0 to match Cobra's PersistentPostRun semantics.
• Post-hook parity — external commands bypass rootCmd.ExecuteContext, so MaybeRunPlugin runs versioncheck.CheckAndNotify itself. Without this, every external-command invocation would silently drop the version-update notice that built-ins receive.
• Non-executable detection — exec.LookPath conflates "not on PATH" with "found but not executable". The resolver distinguishes them: a 0644 entire-pgr surfaces as a launch error, not a fall-through to "unknown command".
• Signal handling — context cancellation sends SIGINT (with a 5s grace before SIGKILL via cmd.WaitDelay) so external commands can clean up rather than being force-killed.
• Cobra lazy-init for help / completion — MaybeRunPlugin calls Find before Execute, but Cobra adds the help and completion commands to the tree lazily inside Execute. Without priming them, Find(["help"]) returned an "unknown command" error and an entire-help binary on PATH would shadow the built-in. The resolver now calls InitDefaultHelpCmd and InitDefaultCompletionCmd before Find; both are idempotent and Execute calls them again later. Regression tests in plugin_test.go.
• Environment filtering — Plugins do not inherit the parent's full environment. Defense in depth: a plugin shouldn't see AWS_ACCESS_KEY_ID, GITHUB_TOKEN, or OPENAI_API_KEY unless it has a reason to. The allowlist covers POSIX basics, locale (LC_*), terminal/color (NO_COLOR, TERM, …), CI detection (CI, GITHUB_ACTIONS, …), proxies (both cases), SSH agent, and Windows essentials, plus the ENTIRE_*, LC_*, and XDG_* namespaces. Users opt names back in via ENTIRE_PLUGIN_ENV="AWS_*,GH_TOKEN". This is a deliberate divergence from kubectl and gh, which inherit unfiltered — neither treats env scrubbing as a security boundary, but the cost of doing it here is tiny and it makes the plugin contract explicit. Full list and rationale in docs/architecture/external-commands.md.

What's not in this PR

• No entire plugin list discovery command. Lazy resolution only.
• officialPlugins is empty for now
• No managed install dir.
• No auth callback (entire auth token) for plugins. If/when ENTIRE_AUTH_TOKEN exists, the gh-style pull pattern is the better fit and builds cleanly on top of the env filtering landed here.

Docs

• New: docs/architecture/external-commands.md — resolution rules, author contract, telemetry posture, environment filtering, side-by-side comparison with the agent protocol
• Updated: CLAUDE.md cross-link

---

Note

Medium Risk
Adds pre-Cobra dispatch that execs arbitrary entire-* binaries from PATH, changing CLI control flow, exit-code/signal behavior, and telemetry/version-check side effects. Risk is moderated by extensive unit/integration coverage, but failures could break command routing or process handling across platforms.

Overview
Adds kubectl-style external command support so entire <name> can resolve and exec an entire-<name> binary on PATH when no built-in subcommand matches, with stdio and exit codes passed through and reserved agent-* names explicitly skipped.

Introduces cli.MaybeRunPlugin/runPlugin with PATH resolution hardening (reject flags/path traversal, detect found-but-not-executable as a launch error), forwards ENTIRE_CLI_VERSION and (when available) ENTIRE_REPO_ROOT, and mirrors built-in behavior by running version-check notice and allowlist-only telemetry (cli_plugin_executed, no args/flags) on successful plugin runs.

Adds unit + end-to-end integration tests for routing precedence, arg passthrough, env forwarding, non-executable handling, and SIGINT propagation, plus docs in docs/architecture/external-commands.md and a small export of external.StripExeExt for cross-platform name handling.

^{Reviewed by Cursor Bugbot for commit e9b1392. Configure here.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Soph]

@BugBot review again

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e9b1392. Configure here.}