docs(webhook): document --deliver-to and standing watches in the CLI help

[defangdevs]

Motivation

agent-box-webhook --help is stale: it predates the 0.9.0 dispatch shape (#164). usage() documented neither --deliver-to nor --ignore-sender, and the setup hint offered only session delivery — so the standing-watch shape was invisible to anyone reading the CLI rather than the guide.

The flags themselves work: the wrapper execs webhook.py, which owns flag parsing. This is docs-only. But --help is the only description of the CLI an agent gets, and an undocumented flag is an unusable one.

Changes

• usage() now lists --deliver-to session|subagent in the synopsis (both subscribe and unsubscribe) and explains the two delivery shapes: session delivery (per session, 1h TTL, --ttl 0 interrupts whatever session is active — avoid) vs. a subagent standing watch (spawns a fresh hook-* session per batch, shared, pinned by default, shown under dispatch in ls). --ignore-sender is documented too, including that CI-outcome events are delivered regardless.
• agent-box-webhook setup closes with the standing-watch subscribe form next to the session one.
• tests/webhook.nix asserts --help keeps mentioning --deliver-to subagent and --ignore-sender, so it cannot silently stale again.
• modules/agent-box.nix regenerated via nix run .#assemble.

User-visible / security effects

Help text only — no behavior, no new surface, no secrets touched. The wording steers agents away from pinning a session subscription (which hijacks the active session) and toward --deliver-to subagent for unowned events.

Checks run

nix build -L .#checks.aarch64-linux.{module-generated-up-to-date,module-single-file,webhook-route,multi-user} — all pass locally. The x86_64-only webhook VM test (which the new assertions live in) runs in CI.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PsqGhkpjsb4kKAdVz25xKN

[defangdevs]

Reviewed by a dispatched hook session (this PR's check_run.completed was the trigger). Docs-only, and every claim checks out against the pinned local-webhook 0.9.0 source — LGTM.

Accuracy check (each statement in the new help vs. local-webhook/webhook.py @ b80b7a2):

Claim	Verified
--deliver-to session|subagent on both subscribe and unsubscribe	run_cli accepts --deliver-to for every tool-backed command and rejects anything but those two values; webhook_unsubscribe's schema takes deliver_to
session delivery expires after 1h	DEFAULT_TTL_HOURS = 1
subagent is pinned by default	'ttlHours': (0 if dispatch else None) if raw_ttl is _MISSING else raw_ttl
shared across sessions	dispatch writes DISPATCH_FILE (filter.dispatch.json), not the per-session filter
spawns a FRESH session per event batch	dispatch_event → DISPATCHER.add(...) → LOCAL_WEBHOOK_SPAWN_CMD
bursts coalesce into one	fork-bomb control is per routing key: first event spawns immediately, further events inside SPAWN_WINDOW_S collapse into one follow-up batch
hook-* session names	webhookSpawn writes hook-* keys into sessions.json
ls shows these under "dispatch"	webhook_subscriptions emits a top-level dispatch object
"@self" is $LOCAL_WEBHOOK_SELF	SELF = ...os.environ.get('LOCAL_WEBHOOK_SELF'), resolved in route_event
CI-outcome events delivered regardless of --ignore-sender	ignore-sender filtering exempts CI-outcome events

The $LOCAL_WEBHOOK_SELF and backtick-ls bits sit inside the quoted <<'USAGE' heredoc, so they render literally rather than expanding — correct as written.

Checks run here (aarch64, natively):

nix build -L .#checks.aarch64-linux.{module-generated-up-to-date,module-single-file,webhook-route}

all pass, so the committed modules/agent-box.nix really is in sync with the template. CI's x86 webhook VM test built and ran, which means the two new --help | grep assertions passed against the actually-rendered wrapper help, not just the template text.

I also dedented and printed the generated heredoc: it wraps at ≤80 columns throughout. The one 86-column line ([--renew-on-event] [--ignore-sender LOGIN]...) predates this PR.

Nits, none blocking:

• --no-renew-on-event still isn't mentioned. Upstream's own CLI usage omits it too, so this PR isn't the place to fix the asymmetry.
• AGENT_BOX_HOOK_SESSION_MAX (the accumulation cap in webhookSpawn, default 4) is invisible from --help. An agent that hits the cap sees a spawn silently skipped with nothing in the CLI pointing at the knob — arguably worth a line under --deliver-to subagent, but it's agent-box's cap rather than a flag, so a follow-up is fine.