Expose confined brush shell as an optional `brush` cargo feature (capability detection, not branch-swap)

[hartsock]

Summary

Expose the confined brush shell as an optional cargo feature of a single publishable agent-bridle crate, so downstream consumers (newt-agent, and the wider Gilamonster line) select it by capability — #[cfg(feature = "brush")] — instead of swapping the dependency's git branch.

Problem (today)

The real Caveats-confined run_command shell lives on agent-bridle main, which pulls the brush git fork. The publishable stub lives on feat/step-up-decision-mvp. Consumers must therefore branch-swap the dependency source to choose stub vs. real shell:

• newt-agent has a just shell-real / just shell-stub recipe pair plus a shell-check pre-push/CI guard that fails if the main (real-brush) pin reaches main, because crates.io forbids git dependencies in any form — even optional / feature-gated.
• So "do I have the confined shell?" is answered by which branch is pinned, i.e. a version/source decision, not a capability flag. That's brittle: it can't be a clean --features toggle, and it blocks merging the real-shell consumer code to a publishable main.

Desired design (capability, not branch)

A single publishable agent-bridle crate with an optional brush feature:

• default (no brush) → the crates.io-safe stub shell; publishable.
• --features brush → the real Caveats-confined brush shell.
• Consumers do #[cfg(feature = "brush")] capability detection and light up the confined path when present — no branch-swap, no version pin, no shell-check guard needed.

Hard dependency: this requires brush itself to be published to crates.io (a git dep can't ride along even feature-gated). Until brush ships upstream, the feature can exist but stay off-by-default and unpublishable-with-it-on; once brush is on crates.io, the feature becomes a normal publishable optional dep.

Acceptance

• brush optional feature on a single agent-bridle crate (no branch fork for the shell).
• Default build is crates.io-publishable (stub shell, no git deps).
• --features brush enables the confined shell from a crates.io brush release.
• Consumers can drop the shell-real/shell-stub/shell-check branch-swap machinery in favor of #[cfg(feature = "brush")].

Context

Surfaced while wiring newt-agent's Markdown work (newt-agent#559); the branch-swap guard (just shell-check) blocked parking a track agent-bridle main change. newt's owner asked for capability detection rather than a version/branch marker — this issue is that design.

Filed by Beaver (MacBook agent, Claude Opus 4.8 (1M context)).

[hartsock]

Concrete plan: the crates.io capability handshake (consumer side)

brush is now on crates.io (max 0.4.0); the confined-shell API is expected in
a later release (≈0.5.0, pending the upstream brush PR). Once it publishes,
here's the mechanism that lets agent-bridle expose the confined shell as a
capability (auto-detected), not a branch/version pin — so consumers like
newt get it on a plain cargo update, and the default build stays
crates.io-publishable.

The links build-script handshake:

1. brush (ideally) declares links = "brush" and its build script emits
   cargo::metadata=confined_shell=1 when the confined-shell API is present.
   If brush won't advertise it, agent-bridle falls back to a version probe
   (build.rs treats resolved brush >= 0.5.0 as capable).
2. agent-bridle depends on brush = ">=0.5" (floating) and, in build.rs,
   reads DEP_BRUSH_CONFINED_SHELL; when set it emits
   cargo::rustc-cfg=confined_shell.
3. The real shell is #[cfg(confined_shell)]; the stub is
   #[cfg(not(confined_shell))]. Both compile from the same published
   manifest — default builds carry no git dep and stay publishable.

Net effect: cargo update pulls the capable brush → the build script flips the
cfg → the confined shell compiles in. No shell-real/shell-stub branch
swap, no shell-check guard. (If you'd rather opt in explicitly, gate the same
handshake behind an optional brush cargo feature — identical detection.)

Caveat: links metadata only reaches direct dependents, so the cfg is
computed here in agent-bridle (which owns the brush integration), then
re-exposed to newt.

Tracked downstream in newt-agent#570 with a brush-watch GitHub Action that
opens a follow-up issue when brush ≥ target lands on crates.io. Full design:
newt-agent docs/decisions/brush_confined_shell_handshake.md.

Posted by Beaver (MacBook agent, Claude Opus 4.8 (1M context)).

[hartsock]

Design recorded in ADR 0006 (per-OS L3 backends + engines as opt-in cargo features), merged in #52 (2320011f1c13b56e341ea8e1c0c93f6efbaef2d4): docs/adr/0006-per-os-l3-backends-and-optional-engines.md.