delegate-agent-cli 0.18.0__tar.gz → 0.20.0__tar.gz

{delegate_agent_cli-0.18.0 → delegate_agent_cli-0.20.0}/CHANGELOG.md

@@ -5,6 +5,155 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.20.0] - 2026-07-25
+
+### Added
+
+- Added typed child-failure reporting for usage/quota limits (including reset
+  details when present), expired or rejected auth tokens, and Codex thread/state
+  lookup loss. Run state, snapshots, listings, completion envelopes, and
+  synthesized reports now carry the specific error and message. The existing
+  generic public error remains `child_failed`; `usage_limit`, `auth_failed`, and
+  `codex_thread_lost` are additive typed codes. Classification reads only stderr
+  and normalized harness error/terminal events, never assistant/model output.
+- Added `delegate ps` as the first-class active-run view, equivalent to
+  `delegate runs --active`.
+- Added `delegate setup` for first-run harness discovery. It fingerprints all
+  supported installed harnesses, records available model/reasoning metadata in
+  a profile-scoped user cache, creates a minimal selector-only config when no
+  config exists, and reports discovery readiness separately from launchability.
+- Cached `models`/`capabilities` views now project profile discovery with source
+  and evidence metadata. `models <engine> --live` provides a non-persistent
+  one-off probe; `capabilities refresh` persists a full refresh for the selected
+  profile, and `capabilities refresh <engine> [...]` re-probes only the named
+  harnesses while the rest keep their last-known-good records.
+- Runtime model and reasoning metadata now distinguish the requested model,
+  argv-resolved model, capability-validation model, requested effort, resolved
+  effort, source, evidence strength, and transport.
+
+### Changed
+
+- Codex output schemas are now linted before launch. Delegate recursively
+  supplies missing `additionalProperties: false` on object schemas with a loud
+  warning, rejects partial `required` lists precisely, and passes a normalized
+  temporary copy without modifying the source schema. Object-bearing `allOf`,
+  `patternProperties`, and external or unresolvable `$ref` values fail closed
+  rather than being rewritten unsafely. Workflow Codex stages and direct
+  `--output-schema`/`outputSchema` launches share the same preflight. The
+  normalized copy preserves the source schema's property order, so
+  think-before-answer schemas keep their intended generation order.
+- On retry-safe paths, Codex thread/state lookup failures now retry once and,
+  only if the same typed failure repeats, retry through an ephemeral
+  `--ignore-user-config` launch. Retry-safe paths are read-only calls and
+  pre-tool attempts whose workspace remains unchanged; work mode also requires
+  a clean captured baseline. Envelopes and events record fallback engagement.
+- `--prompt-file /dev/stdin` and equivalent stdin descriptors now consume the
+  piped prompt once instead of conflicting with stdin as a second source.
+- Model and reasoning resolution now prefers explicit CLI/config choices and
+  exact discovered evidence before legacy workspace or bundled fallbacks.
+  Exact negative menus fail closed; partial harness evidence and Cursor inferred
+  routes remain visibly labeled rather than being promoted to model-exact facts.
+- Discovery refresh is last-known-good per harness. Successful records update
+  independently, failed probes retain the prior record and report staleness,
+  and selector drift invalidates only the affected harness without probing on
+  an ordinary launch.
+- `capabilities refresh` now writes the selected profile's private discovery
+  cache. The old workspace reasoning cache remains a lower-precedence read-only
+  compatibility source. The cached `capabilities` read reports the discovery
+  cache location in `cachePath`; the previous workspace path, when present, is
+  reported under `legacyWorkspaceCachePath`.
+- `reasoning.capabilities` config entries are now accepted for `grok` in
+  addition to `codex` and `droid`.
+- `--auth-profile` is now accepted on cached `capabilities` reads (previously
+  rejected as an invalid option combination) and on `models` and `setup`.
+- Cursor reasoning-effort routing now defers to a pinned selector when discovery
+  has no same-family route for it: the run proceeds on the pinned model and
+  records a bypass warning. When discovery does carry exact same-family routes,
+  the requested effort still routes to the matching selector, and a family that
+  omits the requested effort still fails closed.
+- Grok reasoning-effort support is once again governed by the documented CLI
+  enum (low, medium, high, xhigh, max); a bundled `grok-4.5` declaration that
+  narrowed it to low/medium/high was removed, since `grok --help` enumerates no
+  per-model efforts. Config, discovery-exact, and cached grok declarations
+  still take precedence.
+- Embedded Devin and Kimi `defaultModel` values are now `null`, deferring model
+  selection to each harness. The editable `config init` example may still pin
+  an explicit default.
+- Claude and Grok `defaultReasoningEffort` config values are now only
+  format-checked at load time instead of validated against the static enum; an
+  unsupported configured default degrades to a launch-time warning so that
+  discovery, not a hardcoded table, decides which levels are accepted.
+
+### Security
+
+- Discovery probes use fingerprinted allowlisted selectors, fixed argv with no
+  shell, closed stdin, neutral temporary working directories, bounded output,
+  timeouts, normalized cache schemas, atomic owner-only writes, and scrubbed
+  model/warning projections. Config and cache source paths remain intentionally
+  visible diagnostics. Automatic Devin discovery remains prompt-free; only the
+  explicitly requested `models devin --live` path uses its bounded prompt-like
+  invalid-model probe.
+- Setup never overwrites an existing config and refuses unsafe selectors,
+  final-component symlinks, and concurrent config races rather than mixing
+  discovery results across config states.
+
+### Fixed
+
+- Credentials appearing in a child harness quota or reset message are now
+  redacted before they reach `state.json`, `snapshot.json`, the completion
+  report, or the run envelope; Codex reports quota walls as stdout events,
+  which bypassed the stderr-tail redaction. The in-progress activity label is
+  likewise redacted when persisted, matching the progress heartbeat.
+- A Codex output schema that omits `required` entirely is now repaired to list
+  every property (in declaration order) instead of being rejected, matching how
+  a missing `additionalProperties` is handled. A partial `required` is still an
+  error.
+- The `primary` attempt banner is written once in the run's stderr log even
+  when several retry paths run in sequence.
+- `delegate ps` now reports argument errors in its own terms — unknown options,
+  `--limit`, `--harness`, and `--group` failures name `ps` instead of the
+  `runs` command it delegates to, and `ps --recent` gets the same tailored
+  redirect as `--running` and `--stale`.
+- `delegate capabilities refresh` exits 3 (missing binary) when no supported
+  harness is installed — including when an engine subset such as
+  `capabilities refresh codex` names only uninstalled harnesses — matching
+  `delegate setup` on identical machine state instead of returning the generic
+  usage code 2.
+- `delegate capabilities` no longer advertises harnesses whose configured
+  selector has drifted from the cached record, on both the cached read and
+  after a refresh — a subset refresh returns the full snapshot, so engines it
+  never probed could otherwise surface stale catalogs the launch path would
+  refuse. Excluded harnesses are named in a new `driftedHarnesses` payload
+  field and in the text output.
+- Pi catalog rows whose column count does not match the header are skipped
+  instead of being read by shifted column position, which could cache a
+  thinking-capable model as having no reasoning support (unrecoverable, since
+  Pi has no config override) or hand a non-thinking model the full effort enum.
+- A configured harness binary or argv prefix that no longer resolves while the
+  CLI is still on PATH is now reported as a stale config setting rather than an
+  uninstalled harness, and `delegate setup` names the config key and file to
+  fix instead of telling you to install a CLI you already have.
+- An unreadable `~/.factory/settings.json` (permissions or I/O error) is
+  reported as a read failure instead of being misreported as invalid JSON.
+- Two Cursor selectors that normalize to the same route family and effort now
+  drop just the ambiguous routes with a warning, instead of turning the entire
+  Cursor discovery record into an error record.
+- OpenCode catalog parsing resumes past a malformed entry's whole object, so a
+  `provider/model`-shaped line nested inside the rejected body can no longer be
+  re-read as a real selector.
+- `capabilities refresh` now hints "global options before the subcommand" for a
+  misplaced global option instead of mislabeling it `invalid_engine`, and a
+  subset refresh whose requested harnesses are all uninstalled reports
+  `requested_harnesses_not_installed` instead of the misleading
+  `no_harnesses_installed`.
+
+## [0.19.0] - 2026-07-20
+
+### Added
+
+- Codex `--reasoning-effort max` support for `gpt-5.6-sol`; other Codex models
+  still fail closed unless config or workspace capability-cache overrides opt them in.
+
 ## [0.18.0] - 2026-07-19
 
 ### Added
@@ -137,7 +286,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   consistently across the CLI reference and worktree guidance.
 - Devin help and discovery surfaces now derive supported modes consistently and
   reject unknown modes before constructing executable arguments.
-
 ## [0.14.0] - 2026-07-15
 
 ### Added
@@ -483,6 +631,8 @@ Usage-audit fix wave: 82 sessions and 1,241 delegate invocations from one week o
 
 - Releases before 0.1.3 predate this changelog.
 
+[0.20.0]: https://github.com/treygoff24/delegate-agent/compare/v0.19.0...v0.20.0
+[0.19.0]: https://github.com/treygoff24/delegate-agent/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/treygoff24/delegate-agent/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/treygoff24/delegate-agent/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/treygoff24/delegate-agent/compare/v0.15.0...v0.16.0

{delegate_agent_cli-0.18.0 → delegate_agent_cli-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: delegate-agent-cli
-Version: 0.18.0
+Version: 0.20.0
 Summary: A tiny CLI for delegating bounded agent tasks across coding-agent runtimes.
 Author: Trey Goff
 License-Expression: MIT
@@ -130,22 +130,28 @@ Install OpenCode from [opencode.ai](https://opencode.ai). Its curl installer
 normally writes the binary to `~/.opencode/bin`, which may not be on `PATH`.
 Extend `PATH` or set `opencode.binary` to the absolute binary path.
 
-Initialize a starter config and replace placeholder Droid model IDs before real Droid runs:
+Let Delegate discover the supported harnesses already on your `PATH`:
 
 ```bash
-delegate config init
-$EDITOR ~/.delegate/config.json
+delegate setup
 ```
 
-`config init` also writes missing `~/.delegate/config.work.json` and
-`~/.delegate/config.personal.json` profile overlays. For an existing install,
-run `env -u AI_PROFILE delegate config sync-profiles` to materialize any missing
-overlays without overwriting ones you already edited.
+`setup` fingerprints installed harnesses, reads their model and reasoning metadata where
+the harness exposes it, and writes a private discovery cache for the active auth profile.
+On a clean install it creates only the absolute binary selectors needed to launch the
+detected harnesses. It never rewrites an existing config, installs a harness, logs in, or
+submits a model prompt.
+
+Use `delegate config init` instead when you want the editable example config and profile
+overlays. Replace its placeholder Droid model IDs before real Droid runs. For an existing
+install, `env -u AI_PROFILE delegate config sync-profiles` creates missing overlays without
+overwriting ones you already edited.
 
 Inspect what Delegate sees:
 
 ```bash
 delegate --version       # installed version — include this in bug reports
+delegate --json setup
 delegate --json describe --summary
 delegate --json models --summary
 delegate --json describe
@@ -156,9 +162,10 @@ delegate --json models opencode --live # query every model visible to OpenCode
 delegate --json models pi --live       # query every model visible to Pi
 delegate --json models omp --live      # query every model visible to Oh My Pi
 delegate --json capabilities
+delegate --json capabilities refresh   # refresh the active profile's discovery cache
 ```
 
-Discover commands as you go: `delegate <command> --help` prints focused help for any command path, and `delegate --json <command> --help` returns an agent-friendly spec of its usage, arguments, and options. For launch and `dry-run` commands, `--json` and `--isolation` may also appear before inline prompt text begins, for example `delegate codex work --prompt-file task.md --json`. `delegate --json describe` includes a `commands` catalog of the whole surface. `delegate --json capabilities` reports reasoning-effort support without launching a child runtime.
+Discover commands as you go: `delegate <command> --help` prints focused help for any command path, and `delegate --json <command> --help` returns an agent-friendly spec of its usage, arguments, and options. For launch and `dry-run` commands, `--json` and `--isolation` may also appear before inline prompt text begins, for example `delegate codex work --prompt-file task.md --json`. `delegate --json describe` includes a `commands` catalog of the whole surface. Cached `models` and `capabilities` reads launch no child process. `models <engine> --live` performs a one-off probe without updating the cache; rerun `delegate setup` or `delegate capabilities refresh` when ordinary launches should consume newly discovered models or effort levels.
 
 From this development checkout, use `python3 bin/delegate.py ...` instead of an installed `delegate` shim.
 
@@ -243,7 +250,12 @@ $EDITOR /tmp/delegate-task.json
 delegate --json run --input-json /tmp/delegate-task.json
 ```
 
-For Codex fan-outs that must return machine-parseable records, add `--output-schema` (or JSON `outputSchema`); Delegate suppresses completion-report injection so the schema owns the final message.
+For Codex fan-outs that must return machine-parseable records, add
+`--output-schema` (or JSON `outputSchema`); Delegate suppresses completion-report
+injection so the schema owns the final message. Codex schemas are
+strict-preflighted recursively: every property must be required, and a missing
+`additionalProperties: false` is supplied in a warned temporary copy without
+changing the source file.
 
 For a one-hop prompt that should not see the current repo or create a tracked
 run, use stateless `call` mode:
@@ -280,7 +292,16 @@ python3 bin/delegate.py workflow approve wf_0123abcdef45
 See [Delegate Workflows](docs/delegate-workflows.md) for the DSL, safety
 limits, config, and gate semantics.
 
-Reasoning effort is provider-aware. Unsupported combinations fail before launch. It changes only the requested model thinking depth/cost/latency; it does not change safe/work/call mode, sandboxing, approvals, or edit capability. Codex/Droid validate effort against model capability metadata, Cursor maps effort to configured model selection, Claude and Grok map to native `--effort`, OpenCode passes it through as `--variant`, and Pi/Oh My Pi map `low|medium|high|xhigh|max` directly to `--thinking`. Devin and Kimi do not expose a Delegate reasoning-effort flag. Explicit Codex effort can target the harness default model even when `codex.defaultModel` is unset:
+Reasoning effort is provider-aware. Unsupported combinations fail before launch.
+It changes only the requested model thinking depth/cost/latency; it does not
+change safe/work/call mode, sandboxing, approvals, or edit capability.
+Codex/Droid validate exact model metadata, Cursor selects an explicit configured
+or corroborated discovered effort route, Claude and Grok map to native
+`--effort`, OpenCode validates discovered exact variants when present and
+otherwise warns on pass-through, and Pi/Oh My Pi map to `--thinking` with
+evidence-aware validation. Devin and Kimi do not expose a Delegate
+reasoning-effort flag. Explicit Codex effort can target the harness default model
+even when `codex.defaultModel` is unset:
 
 ```bash
 delegate --json dry-run codex safe --reasoning-effort high "Review this repository. Do not edit files."
@@ -291,7 +312,9 @@ Codex model routing is deliberately model-first rather than aliasing every
 model/effort pair: define model aliases in `codex.models`, then set effort per
 run with `--reasoning-effort`. Per-model effort menus (including any efforts
 newer than the bundled data) belong in the private `reasoning.capabilities`
-config block, which overrides the bundled defaults.
+config block, which overrides the bundled defaults. Codex `max` is bundled only
+for `gpt-5.6-sol` as of 2026-07; other Codex models require an exact config or
+profile-discovery declaration, or legacy workspace-cache declaration.
 
 Fast mode is an independent per-run serving choice. `--fast` requests Codex's
 Fast service tier, `--no-fast` explicitly requests Standard, and omitting both
@@ -306,6 +329,7 @@ Inspect tracked output by alias:
 
 ```bash
 delegate runs --recent
+delegate ps                   # active and stale tracked runs
 delegate snapshot <alias-or-runId>
 delegate run-output <alias-or-runId>
 ```

{delegate_agent_cli-0.18.0 → delegate_agent_cli-0.20.0}/README.md

@@ -97,22 +97,28 @@ Install OpenCode from [opencode.ai](https://opencode.ai). Its curl installer
 normally writes the binary to `~/.opencode/bin`, which may not be on `PATH`.
 Extend `PATH` or set `opencode.binary` to the absolute binary path.
 
-Initialize a starter config and replace placeholder Droid model IDs before real Droid runs:
+Let Delegate discover the supported harnesses already on your `PATH`:
 
 ```bash
-delegate config init
-$EDITOR ~/.delegate/config.json
+delegate setup
 ```
 
-`config init` also writes missing `~/.delegate/config.work.json` and
-`~/.delegate/config.personal.json` profile overlays. For an existing install,
-run `env -u AI_PROFILE delegate config sync-profiles` to materialize any missing
-overlays without overwriting ones you already edited.
+`setup` fingerprints installed harnesses, reads their model and reasoning metadata where
+the harness exposes it, and writes a private discovery cache for the active auth profile.
+On a clean install it creates only the absolute binary selectors needed to launch the
+detected harnesses. It never rewrites an existing config, installs a harness, logs in, or
+submits a model prompt.
+
+Use `delegate config init` instead when you want the editable example config and profile
+overlays. Replace its placeholder Droid model IDs before real Droid runs. For an existing
+install, `env -u AI_PROFILE delegate config sync-profiles` creates missing overlays without
+overwriting ones you already edited.
 
 Inspect what Delegate sees:
 
 ```bash
 delegate --version       # installed version — include this in bug reports
+delegate --json setup
 delegate --json describe --summary
 delegate --json models --summary
 delegate --json describe
@@ -123,9 +129,10 @@ delegate --json models opencode --live # query every model visible to OpenCode
 delegate --json models pi --live       # query every model visible to Pi
 delegate --json models omp --live      # query every model visible to Oh My Pi
 delegate --json capabilities
+delegate --json capabilities refresh   # refresh the active profile's discovery cache
 ```
 
-Discover commands as you go: `delegate <command> --help` prints focused help for any command path, and `delegate --json <command> --help` returns an agent-friendly spec of its usage, arguments, and options. For launch and `dry-run` commands, `--json` and `--isolation` may also appear before inline prompt text begins, for example `delegate codex work --prompt-file task.md --json`. `delegate --json describe` includes a `commands` catalog of the whole surface. `delegate --json capabilities` reports reasoning-effort support without launching a child runtime.
+Discover commands as you go: `delegate <command> --help` prints focused help for any command path, and `delegate --json <command> --help` returns an agent-friendly spec of its usage, arguments, and options. For launch and `dry-run` commands, `--json` and `--isolation` may also appear before inline prompt text begins, for example `delegate codex work --prompt-file task.md --json`. `delegate --json describe` includes a `commands` catalog of the whole surface. Cached `models` and `capabilities` reads launch no child process. `models <engine> --live` performs a one-off probe without updating the cache; rerun `delegate setup` or `delegate capabilities refresh` when ordinary launches should consume newly discovered models or effort levels.
 
 From this development checkout, use `python3 bin/delegate.py ...` instead of an installed `delegate` shim.
 
@@ -210,7 +217,12 @@ $EDITOR /tmp/delegate-task.json
 delegate --json run --input-json /tmp/delegate-task.json
 ```
 
-For Codex fan-outs that must return machine-parseable records, add `--output-schema` (or JSON `outputSchema`); Delegate suppresses completion-report injection so the schema owns the final message.
+For Codex fan-outs that must return machine-parseable records, add
+`--output-schema` (or JSON `outputSchema`); Delegate suppresses completion-report
+injection so the schema owns the final message. Codex schemas are
+strict-preflighted recursively: every property must be required, and a missing
+`additionalProperties: false` is supplied in a warned temporary copy without
+changing the source file.
 
 For a one-hop prompt that should not see the current repo or create a tracked
 run, use stateless `call` mode:
@@ -247,7 +259,16 @@ python3 bin/delegate.py workflow approve wf_0123abcdef45
 See [Delegate Workflows](docs/delegate-workflows.md) for the DSL, safety
 limits, config, and gate semantics.
 
-Reasoning effort is provider-aware. Unsupported combinations fail before launch. It changes only the requested model thinking depth/cost/latency; it does not change safe/work/call mode, sandboxing, approvals, or edit capability. Codex/Droid validate effort against model capability metadata, Cursor maps effort to configured model selection, Claude and Grok map to native `--effort`, OpenCode passes it through as `--variant`, and Pi/Oh My Pi map `low|medium|high|xhigh|max` directly to `--thinking`. Devin and Kimi do not expose a Delegate reasoning-effort flag. Explicit Codex effort can target the harness default model even when `codex.defaultModel` is unset:
+Reasoning effort is provider-aware. Unsupported combinations fail before launch.
+It changes only the requested model thinking depth/cost/latency; it does not
+change safe/work/call mode, sandboxing, approvals, or edit capability.
+Codex/Droid validate exact model metadata, Cursor selects an explicit configured
+or corroborated discovered effort route, Claude and Grok map to native
+`--effort`, OpenCode validates discovered exact variants when present and
+otherwise warns on pass-through, and Pi/Oh My Pi map to `--thinking` with
+evidence-aware validation. Devin and Kimi do not expose a Delegate
+reasoning-effort flag. Explicit Codex effort can target the harness default model
+even when `codex.defaultModel` is unset:
 
 ```bash
 delegate --json dry-run codex safe --reasoning-effort high "Review this repository. Do not edit files."
@@ -258,7 +279,9 @@ Codex model routing is deliberately model-first rather than aliasing every
 model/effort pair: define model aliases in `codex.models`, then set effort per
 run with `--reasoning-effort`. Per-model effort menus (including any efforts
 newer than the bundled data) belong in the private `reasoning.capabilities`
-config block, which overrides the bundled defaults.
+config block, which overrides the bundled defaults. Codex `max` is bundled only
+for `gpt-5.6-sol` as of 2026-07; other Codex models require an exact config or
+profile-discovery declaration, or legacy workspace-cache declaration.
 
 Fast mode is an independent per-run serving choice. `--fast` requests Codex's
 Fast service tier, `--no-fast` explicitly requests Standard, and omitting both
@@ -273,6 +296,7 @@ Inspect tracked output by alias:
 
 ```bash
 delegate runs --recent
+delegate ps                   # active and stale tracked runs
 delegate snapshot <alias-or-runId>
 delegate run-output <alias-or-runId>
 ```

{delegate_agent_cli-0.18.0 → delegate_agent_cli-0.20.0}/bin/delegate-profile-shim

@@ -33,6 +33,75 @@ _delegate_subcommand() {
   done
 }
 
+_delegate_launch_help_request() {
+  _delegate_launch_cmd="${1:-}"
+  [ "$#" -gt 0 ] && shift
+
+  if [ "$_delegate_launch_cmd" = "dry-run" ]; then
+    case "${1:-}" in
+      --help|-h)
+        return 0
+        ;;
+    esac
+    _delegate_launch_cmd="${1:-}"
+    [ "$#" -gt 0 ] && shift
+  fi
+
+  case "$_delegate_launch_cmd" in
+    cursor|codex|kimi|claude|grok|devin|opencode|pi|omp)
+      # Parser parity: help is diagnostic only before the mode or immediately
+      # after it. Once inline prompt text starts, a later help token is data.
+      case "${1:-}" in
+        --help|-h)
+          return 0
+          ;;
+        safe|work|call)
+          case "${2:-}" in
+            --help|-h)
+              return 0
+              ;;
+          esac
+          ;;
+      esac
+      return 1
+      ;;
+    droid)
+      # Droid may place a model alias before the mode, so its last diagnostic
+      # help position is one token later than the modeless harnesses.
+      case "${1:-}" in
+        --help|-h)
+          return 0
+          ;;
+        safe|work|call)
+          case "${2:-}" in
+            --help|-h)
+              return 0
+              ;;
+          esac
+          ;;
+        *)
+          case "${2:-}" in
+            --help|-h)
+              return 0
+              ;;
+            safe|work|call)
+              case "${3:-}" in
+                --help|-h)
+                  return 0
+                  ;;
+              esac
+              ;;
+          esac
+          ;;
+      esac
+      return 1
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
 _delegate_is_readonly_request() {
   while [ "$#" -gt 0 ]; do
     case "$1" in
@@ -51,7 +120,29 @@ _delegate_is_readonly_request() {
   _cmd="${1:-}"
   [ "$#" -gt 0 ] && shift
   case "$_cmd" in
-    profiles|runs|run-output|describe|models|snapshot|agent-help|help|--help|-h|--version)
+    cursor|droid|codex|kimi|claude|grok|devin|opencode|pi|omp|dry-run)
+      _delegate_launch_help_request "$_cmd" "$@" && return 0
+      return 1
+      ;;
+  esac
+  # Non-launch command parsers treat help as diagnostic wherever accepted.
+  for _delegate_help_arg in "$@"; do
+    case "$_delegate_help_arg" in
+      --help|-h)
+        return 0
+        ;;
+    esac
+  done
+  case "$_cmd" in
+    profiles|runs|ps|run-output|describe|snapshot|agent-help|help|--help|-h|--version)
+      return 0
+      ;;
+    models)
+      for _delegate_model_arg in "$@"; do
+        if [ "$_delegate_model_arg" = "--live" ]; then
+          return 1
+        fi
+      done
       return 0
       ;;
     capabilities)

{delegate_agent_cli-0.18.0 → delegate_agent_cli-0.20.0}/docs/agent-setup.md

@@ -47,18 +47,25 @@ This guide covers both human setup and non-interactive setup for agents or CI jo
 
    The Claude harness requires Claude Code 2.1.x or newer (verified on 2.1.181) for `--effort`, `--permission-mode auto`, and `--no-session-persistence`.
 
-4. Initialize and edit config:
+4. Discover installed harnesses and initialize Delegate:
 
    ```bash
-   delegate config init
-   $EDITOR ~/.delegate/config.json
+   delegate --json setup
    ```
 
-   Replace placeholder Droid model IDs. Use local aliases such as `reviewer` and `implementer`; the alias names are yours and do not need to reveal the provider.
-   `config init` also writes missing `config.work.json` and
-   `config.personal.json` profile overlays next to the base config. For an
-   existing install, run `env -u AI_PROFILE delegate config sync-profiles` to
-   create missing overlays without overwriting existing ones.
+   Setup checks all supported harnesses, records normalized model and reasoning
+   metadata in the active auth profile's private cache, and reports which
+   harnesses are launchable. If no config exists, it creates a minimal config
+   containing safe absolute binary selectors. It never changes an existing
+   config. Setup does not install or authenticate a harness, edit harness-native
+   config, or submit a model prompt.
+
+   Use `delegate config init` when you want the editable example config and
+   profile overlays instead. Replace its placeholder Droid model IDs. Local
+   alias names such as `reviewer` and `implementer` are yours and need not reveal
+   the provider. For an existing install, run
+   `env -u AI_PROFILE delegate config sync-profiles` to create missing overlays
+   without overwriting existing ones.
 
    In a development checkout, `cp config.example.json ~/.delegate/config.json`
    is still fine. Installed users should prefer `delegate config init`.
@@ -87,7 +94,22 @@ When running on Windows through WSL, treat Delegate as a Linux CLI:
    delegate --json worktree remove --help
    ```
 
-   `delegate --json capabilities` reports reasoning-effort support from config, workspace cache, and bundled fallback data without launching a child runtime. Run `delegate --json capabilities refresh` only when you explicitly want Delegate to call child CLIs and update the workspace-local `.delegate/capabilities/reasoning.json` cache.
+   `delegate --json capabilities` reports reasoning-effort support from config,
+   the active profile's discovery cache, the legacy workspace cache, and bundled
+   fallback data without launching a child runtime.
+
+   Rediscover after a harness upgrade, account change, or new model release:
+
+   ```bash
+   delegate --json models --summary
+   delegate --json models <engine> --live
+   delegate --json capabilities refresh
+   delegate --json capabilities
+   ```
+
+   `models <engine> --live` is a one-off view and never writes Delegate config or
+   cache. `capabilities refresh` and `setup` update the selected profile's cache,
+   preserving the last good record for a harness whose current probe fails.
 
 6. Run a dry-run smoke test. Dry-run does not require the real child binary and does not launch the runtime:
 
@@ -167,6 +189,10 @@ For an orchestrating agent, script, or CI job:
    a temporary `HOME` avoids inheriting nested maps such as user-level Droid
    aliases.
 
+   For a persistent user installation, run `delegate --json setup` once before
+   the first launch. Do not add setup to every CI invocation: it calls installed
+   harness metadata commands and writes the selected profile's user cache.
+
 4. Start with dry-run JSON:
 
    ```bash