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

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

@@ -5,6 +5,134 @@ 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.22.0] - 2026-07-26
+
+### Changed
+
+- Consolidated pure-call validation in `constants.validate_pure_call`, collapsed repeated `attempt`/`call` invocations in `runner.py` into local closures, eliminated `typing.Any` from `src`, and removed defensive `getattr`/`isinstance` hedges where the contract guarantees the type.
+
+### Removed
+
+- Removed the write-only `ReasoningCapability.supported_efforts` field and unused `STATUS_FILTER_ACTIVE`/`STATUS_FILTER_RECENT` constants.
+- Removed dead back-compat re-exports from `delegate_agent.cli`: `build_kimi_argv`, `build_opencode_argv`, `build_pi_argv`, `prefix_droid_safe_prompt`, `redacted_prompt_argv`, `KIMI_PROMPT_REDACTION`, `_grok_harness_bypass_enabled`, `_resolve_default_model`, and `block_external_symlinks`. These had no known consumers; the supported import surface is the CLI and `delegate --json` contracts.
+
+## [0.21.0] - 2026-07-26
+
+### Added
+
+- Added `delegate worktree gc --all`, which scans the machine-wide worktree
+  pool for worktrees whose source repository no longer exists. Such worktrees
+  were previously unreachable by any `gc` invocation, because reaping is driven
+  by the run registry inside each source repository and that registry dies with
+  the repository. The scan adds no catalog or persistent state: it reads each
+  worktree's Git backlink directly, and treats a backlink whose target is gone
+  as the sole orphan signal. The scan removes nothing at all, at any depth: a
+  missing source repository makes a worktree's uncommitted state impossible to
+  inspect, so orphans and empty pool directories alike are reported for
+  deliberate manual cleanup. Because that output invites manual deletion, every
+  uncertainty resolves away from an orphan verdict: a pointer file that cannot
+  be read, a path comparison the filesystem cannot answer, an entry too recently
+  modified to have settled, and a directory whose name does not match the pool's
+  own fingerprint contract are all reported as warnings rather than orphans.
+  That last rule is what keeps a scan of an arbitrary root from labelling
+  somebody else's directories. `--pool PATH` scans a different pool root, which
+  reaches pools stranded by an earlier `worktrees.dataHome`.
+- `capabilities refresh` and `setup` now name each harness on stderr as it is
+  probed, so a harness that hangs is identifiable rather than anonymous
+  silence. Progress output is suppressed under `--json`.
+
+### Changed
+
+- A launch now fails instead of proceeding when the configured binary for a
+  harness identifies itself as a *different* known harness. Delegate re-probes
+  `--version` when a cached capability record has refused a run, and during
+  `capabilities refresh` and `setup` (see Fixed); when that banner positively
+  names another harness — a Codex path replaced in place by Grok, say — the run
+  stops with `harness_identity_mismatch` and exit code 2, naming the configured
+  harness, the harness that answered, and the selector path.
+  Previously the launch continued against that same binary with the same Codex
+  argv, sandbox flags, and approval policy, and only the cached capability
+  metadata was discarded. This fires solely on a banner that NAMES another known
+  harness, never on uncertainty: a probe that errors, times out, exceeds its
+  output bound, or prints an unbranded banner still fails open and launches on
+  the cached record. An unbranded shape — a bare date-and-hash build ID is the
+  clearest case — is deliberately not identification, because wrapper prefixes
+  are a supported configuration and refusing a legitimate launch costs more than
+  carrying a stale record until the next refresh. The selector is scrubbed of
+  credentials before it reaches the message or the diagnostics, since a wrapper
+  prefix can carry a token inline or after a flag. Dry runs do not probe and are
+  unaffected. The refusal also names the discovery cache file for the active
+  auth profile, in its `cachePath` diagnostic and in a next action, because
+  `capabilities refresh` cannot clear this state: a refresh keeps the
+  last-known-good record whenever a probe fails, which is correct for a flaky
+  probe and wrong here, where the record itself is the problem. Without the
+  path, a wrong identification would refuse every launch with no documented way
+  out short of editing configuration.
+- A run whose cached capability record is discarded for version drift now says
+  so, naming `delegate capabilities refresh <engine>`. The record is dropped for
+  that run only and the superseded copy stays on disk, so every later launch
+  repeats the drop and loses the same discovery-sourced models and reasoning
+  levels — previously with no indication that a stale cache was the cause.
+  Selector drift stays silent, since `capabilities` already reports it under
+  `driftedHarnesses`.
+
+### Fixed
+
+- Discovery now detects a harness that was upgraded in place. Cached capability
+  records were invalidated only by comparing the configured selector, so an
+  upgrade behind an unchanged selector left stale capabilities cached
+  indefinitely and a newly supported reasoning level was rejected until a manual
+  `capabilities refresh`. Delegate now re-probes `--version` for the single
+  harness it is about to use and compares it against the version already stored
+  in the record, then rebuilds the run against the refreshed picture. The probe
+  runs only once the cached record has already cost the run something, never on
+  the ordinary path, which therefore spawns no extra process at all — and that
+  matters because the probe costs 26-668ms, worst on the Node and Bun harnesses
+  that are already slow to start. Two things trigger it: an explicit
+  `--reasoning-effort` the record refuses, and a `defaultReasoningEffort` the
+  record silently drops. The second is the one most likely to go unnoticed,
+  since a configured default degrades to a warning rather than failing the
+  launch, and it is set once and then never typed again. A probe that cannot
+  repair the default leaves the run exactly as it was: a launch that succeeded
+  is never turned into a failure. The check fails open — a probe that errors,
+  times out, or prints a banner nothing recognizes keeps the cached record, so a
+  failing probe can never prevent a launch. A banner that positively identifies
+  a *different* known harness is the exception, and it aborts the launch rather
+  than merely invalidating the record — see Changed. Each banner is matched
+  against the expected harness's own pattern before anyone else's, so a banner
+  mentioning more than one tool is read as the harness that was asked for
+  instead of whichever pattern happens to be declared earlier. Banners are read
+  with escape sequences stripped, so a colorized version line no longer freezes
+  a record permanently. A cached selector whose binary no longer exists is also
+  treated as drift.
+- Not covered, deliberately: a harness that *removes* a capability leaves its
+  cached record listing more than the harness now supports, which produces no
+  refusal and so no probe. The child rejects the effort it was handed, which is
+  loud; the one quiet case is Cursor's route table aiming a run at a superseded
+  model id. Catching either would cost a probe on every launch, which is the
+  trade this path exists to refuse. `capabilities refresh` remains the cure.
+- A dry run never probes the harness for its version. Dry run documents that it
+  neither launches a child runtime nor requires the real child binary, and the
+  drift probe is a child runtime; it now runs only on a real launch, leaving dry
+  run with the two filesystem-local checks.
+- A discovery cache carrying a newer schema than the running build is no longer
+  discarded and overwritten. It is left intact while the run degrades to
+  probing without persisting, so an older Delegate can no longer destroy a newer
+  cache. Losing that race mid-probe degrades the same way rather than failing the
+  command: `capabilities refresh` and `setup` both report `cacheWriteSkipped`,
+  `setup` additionally leaving `cacheState` at `unchanged`, and each exits
+  successfully, since only persistence was lost. The
+  schema is re-read immediately before the atomic replacement rather than before
+  the snapshot is serialized, which narrows the window in which a newer cache
+  could be published and then overwritten down to the `os.replace` call itself.
+  POSIX offers no compare-and-swap for a rename, so that last window remains.
+- The test suite no longer writes into the developer's real
+  `~/.delegate/worktrees`. Tests exercising persistent-worktree runs created
+  real pooled worktrees over temporary source repositories and orphaned them
+  permanently, because `worktrees_data_home` falls through to the user's home
+  directory with no seam a test could redirect. `HOME` is now redirected at test
+  collection time, which reaches every such resolver at once.
+
 ## [0.20.0] - 2026-07-25
 
 ### Added
@@ -631,6 +759,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.22.0]: https://github.com/treygoff24/delegate-agent/compare/v0.21.0...v0.22.0
+[0.21.0]: https://github.com/treygoff24/delegate-agent/compare/v0.20.0...v0.21.0
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: delegate-agent-cli
-Version: 0.20.0
+Version: 0.22.0
 Summary: A tiny CLI for delegating bounded agent tasks across coding-agent runtimes.
 Author: Trey Goff
 License-Expression: MIT

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/docs/cli-reference.md

@@ -803,7 +803,31 @@ records independently. If one current probe fails, its last-known-good record
 is retained and the refresh response lists that harness in `staleHarnesses`.
 If the configured executable selector changes, cached reads mark that harness
 stale and ordinary launches ignore only that harness's record until refresh.
-Cached reads never run `--version` merely to test staleness.
+Cached reads never run `--version` merely to test staleness, and neither does an
+ordinary launch: a cached record can only be short of what the harness now
+supports, never claim more, so one that satisfies the run is used as-is.
+
+A launch re-probes `--version` for its own harness only when the cached record
+has already cost the run something: it refused an explicit `--reasoning-effort`,
+or it silently dropped a configured `defaultReasoningEffort` (a configured
+default degrades to a warning instead of failing the launch, so nothing else
+would signal it). An in-place upgrade behind an unchanged selector is the reason
+either can be wrong, so the probe compares the live banner against the version
+stored in the record, and a mismatch drops the record and rebuilds the run
+against config and bundled capabilities. If the refreshed picture cannot satisfy
+a configured default either, the run proceeds as it already had — a probe never
+turns a launch that succeeded into one that fails.
+
+The reverse case is not covered: a harness that *removes* a capability leaves
+its record listing more than the harness now supports, which produces no refusal
+and therefore no probe. Run `capabilities refresh` after an upgrade that narrows
+what a harness accepts. The result carries a warning naming
+`capabilities refresh <engine>`, because the superseded record stays on disk
+until a refresh rewrites it. The probe fails open — an error, a timeout, or an
+unrecognized banner leaves the original refusal standing — except when the
+banner positively names a *different* known harness, which fails the run with
+`harness_identity_mismatch` rather than handing one harness's argv and sandbox
+policy to another. Dry runs never probe at all.
 
 All automatic probes run with `shell=False`, stdin closed, a neutral temporary
 working directory, bounded output, and a timeout. They pass the active profile
@@ -1079,11 +1103,13 @@ delegate worktree show <handle>
 delegate worktree show --latest HARNESS
 delegate worktree remove <handle|--group NAME> [--discard-uncommitted] [--force-branch] [--force] [--keep-branch]
 delegate worktree prune [--merged] [--older-than DAYS] [--harness HARNESS] [--group NAME] [--include-detached] [--dry-run] [--discard-uncommitted] [--force-branch] [--force]
-delegate worktree gc [--dry-run]
+delegate worktree gc [--dry-run] [--all] [--pool PATH]
 ```
 
 `worktree show --latest HARNESS` selects the latest persistent worktree for the harness, not merely the latest run overall. `worktree list` JSON includes a `summary` with status counts, registry drift counts, warning counts, `autoPruneMode`, and whether the returned operation was read-only; `summary.totalPersistentWorktrees` is always registry-wide, while `allStatusCounts` is scoped to the `--harness` / `--group` filters (pre-status-filter) and `statusCounts` to the visible entries. `worktree remove --group NAME` removes all matching persistent worktrees with the same safety checks as single-handle removal. `worktree prune --group NAME` limits prune candidates to the group. `worktree gc --dry-run` reports `wouldPruneSourceRoots` and structured orphan reasons; `worktree gc` JSON also includes `mode`, `effects`, per-entry `action`, and orphan `safeAction` fields. `gc` never deletes worktree directories.
 
+`worktree gc --all` additionally scans the machine-wide worktree pool (`worktrees.dataHome`, default `~/.delegate/worktrees`) and adds a `pool` object with `dataHome`, `scannedWorktrees`, `orphans`, `emptyFingerprintDirs`, and `warnings`. A pool orphan is a pooled worktree whose Git admin directory no longer serves it, classified `source_root_missing` or `worktree_metadata_missing` with the same `safeAction` vocabulary as registry orphans, plus `worktreePath`, `fingerprint`, `sourceGitRoot`, and `gitdir` (null when the backlink is absent). This is the only way to see worktrees whose source repository was deleted along with its `.delegate/` registry, so `--all` is accepted outside a Delegate registry. The pool scan removes nothing at all: orphans are reported because uncommitted work in them is undetectable once the source repository is gone, and empty fingerprint directories are reported for the same hand-clearing rather than reclaimed. Only a settled absence produces an orphan — metadata that could not be read (a symlinked, non-regular, oversized, or unreadable `.git` entry, or an admin directory that could not be inspected) is treated as live and reported in `pool.warnings`, and so is any pool entry modified within the last 15 minutes, since worktree creation writes the directory before its metadata and a concurrent scan would otherwise call a worktree being born an orphan (`worktree_unsettled`, `fingerprint_dir_unsettled`). `pool.warnings` also covers first-level directories whose names are not repository fingerprints, fingerprint directories that hold loose files rather than being empty, and unlistable fingerprint directories. `--pool PATH` scans a specific pool root instead of the configured one, which finds pools left behind by an earlier `worktrees.dataHome`; an explicit `--pool` path that is missing, not a directory, or unreadable is an `invalid_pool_root` error.
+
 List/show entry fields include `branchMergedIntoSource` (branch graph only), `mergedIntoSource` (backward-compatible branch graph state), `fullyIntegrated` (branch merged and worktree clean), `hasUncommittedChanges`, `integrationStatus`, and `uncommittedChangesIntegrated`. `workSummary` is included on `worktree show` and run completion payloads when Delegate can inspect the worktree; `worktree list` omits the deep summary for responsiveness. Consumers that need safe retirement should require `fullyIntegrated: true` or inspect `integrationStatus`. When `integrationStatus` is `branch-merged-worktree-dirty`, merge/cherry-pick suggestions are suppressed because commit integration is already complete and only uncommitted edits remain.
 
 Unknown persistent-worktree handles return suggestions scoped to persistent

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/docs/worktrees.md

@@ -216,6 +216,28 @@ delegate worktree gc
 
 In dry-run mode, `gc` reports `wouldPruneSourceRoots` and classifies un-prunable worktrees with reasons such as `source_root_missing`, `worktree_metadata_missing`, `branch_missing`, and `detached_backlink`. Without `--dry-run`, it may update Delegate registry status (for example, marking missing paths as `missing` or inconsistent metadata as `unknown`) and may run `git worktree prune` to clean Git administrative metadata for already-missing paths, but it does not delete worktree directories. JSON output includes an `effects` object that makes those mutation boundaries explicit.
 
+## Find pooled worktrees whose repository is gone
+
+```bash
+delegate worktree gc --all
+delegate worktree gc --all --dry-run
+delegate worktree gc --pool ~/.delegate/worktrees
+```
+
+Persistent worktrees live in a machine-global pool under `worktrees.dataHome` (default `~/.delegate/worktrees`), but they are tracked in a run registry inside the source repository. Delete the source repository and its registry goes with it, leaving a pooled worktree that no per-repository `gc` can reach. `--all` finds these by walking the pool directly and reading each worktree's `.git` backlink file as text — the ordinary Git-based checks cannot classify them, because every `git` command fails inside a worktree whose repository is gone. Because a live worktree always has a live backlink, the walk is safe to run across every repository on the machine at once. `--all` works outside a Delegate registry for the same reason.
+
+The scan adds a `pool` object to the JSON with `dataHome`, `scannedWorktrees`, `orphans`, `emptyFingerprintDirs`, and `warnings`. Each orphan carries `worktreePath`, `fingerprint`, the recovered `sourceGitRoot` (null when the layout does not reveal it), `gitdir` (null when the worktree has no `.git` backlink), a `reason`, and a `safeAction`.
+
+A worktree counts as an orphan only when two things are settled. Its `.git` backlink must be definitely gone or definitely unusable — absent, or readable and holding no usable `gitdir:` line. And its Git admin directory must no longer serve it: the admin directory must exist and hold a `gitdir` backfile naming this worktree. Anything that merely *could not be checked* — a `.git` entry that is a symlink, a directory, a FIFO, oversized, or unreadable; an admin directory that could not be inspected — is reported as live and surfaced in `warnings` with reason `worktree_metadata_unverifiable`. A false orphan invites someone to delete real work by hand, while a false live only under-reports, so every unresolved case resolves toward live.
+
+Absence also has to have lasted. Creating a persistent worktree is several steps — Delegate makes the fingerprint directory, then `git worktree add` creates the worktree directory, its `.git` pointer, and the admin directory's backfile — and a scan that lands inside that window sees exactly what a deleted repository leaves behind. Since the scan runs in a different process from the one creating the worktree, and often for a different repository, it has nothing to wait on and judges by age instead: a pool entry modified within the last 15 minutes is reported in `warnings` (`worktree_unsettled`, or `fingerprint_dir_unsettled` for an empty directory) and classified on a later run. An entry whose age cannot be read at all is treated the same way. This delays reporting a genuine orphan by one run at most, since a real orphan's metadata never comes back.
+
+Only first-level directories named like a repository fingerprint (12 lowercase hex characters, as written by `plan_worktree_path`) are treated as Delegate's. The root is whatever you passed, so anything else is skipped without being descended, and is summarized in `warnings` with reason `not_a_pool_fingerprint_dir` — pointing `--pool` at an ordinary directory yields warnings, never orphans or cleanup candidates.
+
+The pool scan removes nothing. With the source repository gone there is no way to tell whether an orphan holds uncommitted work, so removal is a deliberate manual decision — inspect the reported path, rescue anything you need, then delete it yourself. Empty fingerprint directories, left behind when a fingerprint's last worktree was removed, are reported in `emptyFingerprintDirs` for the same hand-clearing; `gc` does not remove those either. "Empty" means the directory holds nothing at all: a fingerprint directory with loose files in it is reported in `warnings` (`fingerprint_dir_not_empty`) instead. Fingerprint directories that could not be listed also appear in `warnings` rather than being reported as empty.
+
+Use `--pool PATH` to scan a pool root that is no longer the configured `dataHome`. An explicitly named `--pool` path must exist and be a readable directory; anything else is an `invalid_pool_root` error rather than a successful scan of nothing, including a root that becomes unreadable between validation and the walk. A configured `dataHome` that does not exist yet is not an error — it just means no pool has been created — and is reported in `pool.warnings`.
+
 ## Security boundary
 
 Worktree isolation is source-checkout isolation, not a full sandbox. The child process may still use credentials, network access, external tools, and absolute paths according to its runtime and host permissions. See [Security model](security-model.md).

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "delegate-agent-cli"
-version = "0.20.0"
+version = "0.22.0"
 description = "A tiny CLI for delegating bounded agent tasks across coding-agent runtimes."
 readme = "README.md"
 requires-python = ">=3.11"

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/src/delegate_agent/__init__.py

@@ -1,5 +1,5 @@
 """Delegate Agent CLI package."""
 
-VERSION = "0.20.0"
+VERSION = "0.22.0"
 
 __all__ = ["VERSION"]

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/src/delegate_agent/capability_commands.py

@@ -138,9 +138,12 @@ def _refresh_payload(
     *,
     profile: profiles.ProfileResolution,
     engines: tuple[str, ...] | None = None,
+    progress: harness_discovery.ProgressCallback | None = None,
 ) -> JsonObject:
     try:
-        result = harness_discovery.refresh_discovery(config, profile=profile, engines=engines)
+        result = harness_discovery.refresh_discovery(
+            config, profile=profile, engines=engines, progress=progress
+        )
     except OSError as exc:
         raise CapabilitiesError(
             "capability_refresh_failed",
@@ -215,6 +218,8 @@ def _refresh_payload(
     }
     if drifted_harnesses:
         payload["driftedHarnesses"] = drifted_harnesses
+    if result.get("futureSchemaCache") is True:
+        payload["cacheWriteSkipped"] = harness_discovery.FUTURE_SCHEMA_CACHE_WARNING
     _add_legacy_cache_fields(payload, legacy_path, reasoning_payload)
     return redaction.scrub_public_projection(payload)
 
@@ -229,6 +234,7 @@ def emit(
     profile: profiles.ProfileResolution | None = None,
     discovery: JsonObject | None = None,
     stdout: TextIO,
+    stderr: TextIO | None = None,
 ) -> int:
     active_profile = profile or profiles.resolve_active_profile(
         config,
@@ -236,8 +242,16 @@ def emit(
         cli_override=auth_profile_override,
     )
     if command.refresh:
+        # JSON callers get a clean stdout document and a quiet stderr; the
+        # per-harness line exists for a human watching a cold refresh.
         payload = _refresh_payload(
-            config, workspace, profile=active_profile, engines=command.engines
+            config,
+            workspace,
+            profile=active_profile,
+            engines=command.engines,
+            progress=(
+                None if command.json_mode else harness_discovery.stderr_probe_progress(stderr)
+            ),
         )
     else:
         payload = capabilities_payload(
@@ -252,6 +266,9 @@ def emit(
         delegate_rendering.print_json(payload, stdout)
     else:
         print(f"reasoning capabilities: {payload['cachePath']}", file=stdout)
+        skipped = payload.get("cacheWriteSkipped")
+        if isinstance(skipped, str):
+            print(skipped, file=stdout)
         drifted = payload.get("driftedHarnesses")
         if isinstance(drifted, list) and drifted:
             print(

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/src/delegate_agent/cli.py

@@ -40,20 +40,14 @@ from delegate_agent import runner as delegate_runner
 from delegate_agent.argv_builders import (  # noqa: F401  # re-exported for tests / back-compat
     SAFE_REVIEW_PREFIX_BY_ENGINE,
     _claude_harness_bypass_enabled,
-    _grok_harness_bypass_enabled,
     build_claude_argv,
     build_codex_argv,
     build_cursor_argv,
     build_devin_argv,
     build_droid_argv,
     build_grok_argv,
-    build_kimi_argv,
     build_omp_argv,
-    build_opencode_argv,
-    build_pi_argv,
     prefix_cursor_safe_prompt,
-    prefix_droid_safe_prompt,
-    redacted_prompt_argv,
 )
 from delegate_agent.argv_utils import public_argv
 from delegate_agent.cli_parser import (  # noqa: F401  # re-exported for tests / back-compat
@@ -98,7 +92,6 @@ from delegate_agent.prompt_transport import (  # noqa: F401  # CURSOR_PROMPT_RED
     DEVIN_AGENT_CONFIG_DISPLAY,
     DROID_PROMPT_FILE_ARG_PLACEHOLDER,
     DROID_PROMPT_FILE_DISPLAY,
-    KIMI_PROMPT_REDACTION,
     PROMPT_FILE_ARG_PLACEHOLDER,
     PROMPT_FILE_DISPLAY,
     PROMPT_TRANSPORT_ARGV,
@@ -109,7 +102,6 @@ from delegate_agent.request_build import (  # noqa: F401  # re-exported for test
     CALL_TEMP_CWD_PLACEHOLDER,
     RUN_INPUT_KEYS,
     _load_input_json_object,
-    _resolve_default_model,
     build_request,
     effective_prompt,
     load_config,
@@ -136,7 +128,6 @@ from delegate_agent.safe_workspace import (  # noqa: F401  # re-exported for tes
     SAFE_BLOCKED_SYMLINK_PLACEHOLDER,
     SAFE_EXTERNAL_SYMLINK_WARNING_PREFIX,
     SAFE_UNBORN_GIT_WARNING,
-    block_external_symlinks,
     cleanup_safe_isolated_workspace,
     create_directory_safe_workspace,
     create_git_safe_workspace,
@@ -332,7 +323,6 @@ def dry_run_payload(request: Request) -> JsonObject:
     if request.profile_resolution.name is not None:
         payload["profileEnv"] = redaction.redact_env_map(request.profile_resolution.env)
 
-    # Structured isolation fields from the isolation context.
     if request.isolation_context is not None:
         ctx = request.isolation_context
 
@@ -515,7 +505,6 @@ def make_run_context(
         if request.isolation_context is not None
         else False
     )
-    # Extract isolation metadata from the isolation context.
     iso_ctx = request.isolation_context
     if iso_ctx is not None:
         isolation_mode = iso_ctx.isolation_mode
@@ -860,7 +849,7 @@ def execute_request(
         profiles.preflight_codex_request(request, config.get("codex", {}))
     ctx = request.isolation_context
 
-    # --- Persistent worktree path (work + worktree) ---
+    # Persistent worktree runs (work + worktree) hand off to worktree_execution.
     if ctx is not None and ctx.isolation_lifecycle == "persistent":
         try:
             return worktree_execution.execute_persistent_worktree(
@@ -1022,7 +1011,6 @@ def pre_read_run_json_for_config(
     if json_cwd is not None and not isinstance(json_cwd, str):
         raise DelegateError("invalid_cwd", "cwd must be a string.")
 
-    # Reject explicit null isolation in the JSON pre-read.
     if "isolation" in raw and raw["isolation"] is None:
         raise DelegateError(
             "invalid_isolation",
@@ -1087,6 +1075,7 @@ def main(
                 json_mode=global_options.json_mode,
                 auth_profile_override=global_options.auth_profile,
                 stdout=stdout,
+                stderr=stderr,
             )
 
         # For run --input-json, pre-read the JSON to discover config from the
@@ -1177,6 +1166,7 @@ def main(
                 profile=discovery_profile,
                 discovery=discovery_snapshot,
                 stdout=stdout,
+                stderr=stderr,
             )
 
         if parsed.subcommand in {
@@ -1278,8 +1268,8 @@ def main(
             DelegateError(
                 exc.error,
                 exc.message,
-                diagnostics=getattr(exc, "diagnostics", None),
-                next_actions=getattr(exc, "next_actions", None),
+                diagnostics=exc.diagnostics,
+                next_actions=exc.next_actions,
             ),
             json_mode,
             stdout,

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/src/delegate_agent/cli_parser.py

@@ -32,10 +32,9 @@ from delegate_agent.constants import (
     ENGINES_PROSE,
     KNOWN_ENGINES,
     MODELESS_ENGINES,
-    PURE_CALL_ENGINES,
     VALID_MODES,
-    pure_call_supported,
     validate_mode,
+    validate_pure_call,
 )
 from delegate_agent.errors import DelegateError
 from delegate_agent.request_models import (
@@ -647,10 +646,6 @@ def corrected_global_argv(argv: list[str]) -> list[str]:
     return [*globals_out, *rest]
 
 
-def corrected_global_command(argv: list[str]) -> str:
-    return _shell_command(corrected_global_argv(argv))
-
-
 def raise_misplaced_global_option(message: str, argv: list[str] | None = None) -> NoReturn:
     guidance = (
         "Move global options before the subcommand "
@@ -1320,22 +1315,7 @@ def _validate_pure_options(
         return
     if mode != "call":
         raise DelegateError("unsupported_pure_call", "--pure only applies to call mode.")
-    if group is not None:
-        raise DelegateError(
-            "pure_conflicts_group",
-            "--pure cannot be combined with --group; pure call is a stateless one-hop completion.",
-        )
-    if read_only:
-        raise DelegateError(
-            "pure_conflicts_read_only", "--pure cannot be combined with --read-only."
-        )
-    if not pure_call_supported(engine):
-        supported = ", ".join(PURE_CALL_ENGINES)
-        raise DelegateError(
-            "unsupported_pure_call",
-            f"{engine} does not support pure call mode.",
-            next_actions=[f"Use --pure with one of: {supported}."],
-        )
+    validate_pure_call(engine, pure=pure, read_only=read_only, group=group)
 
 
 def parse_snapshot(rest: list[str], json_mode: bool, cwd: str | None) -> ParsedCommand:
@@ -1982,6 +1962,10 @@ def _require_option_value(rest: list[str], index: int, option: str) -> str:
 
 WorktreeOptionSpec = tuple[str, str]
 
+# Parsed worktree option values: flags store True, "str"/"group"/"status" kinds
+# store the validated string, and the int kinds store a parsed int.
+WorktreeOptionValue = str | int | bool
+
 WORKTREE_OPTION_SPECS: dict[str, dict[str, WorktreeOptionSpec]] = {
     "list": {
         "--harness": ("str", "harness"),
@@ -2013,12 +1997,14 @@ WORKTREE_OPTION_SPECS: dict[str, dict[str, WorktreeOptionSpec]] = {
     },
     "gc": {
         "--dry-run": ("flag", "dry_run"),
+        "--all": ("flag", "all_pools"),
+        "--pool": ("str", "pool"),
     },
 }
 
 
 def _apply_worktree_option(
-    options: dict[str, object],
+    options: dict[str, WorktreeOptionValue],
     args: list[str],
     index: int,
     option: str,
@@ -2067,7 +2053,7 @@ def parse_worktree(rest: list[str], json_mode: bool, cwd: str | None) -> ParsedC
         return help_command(json_mode, topic)
     if action not in WORKTREE_OPTION_SPECS:
         raise DelegateError("unknown_worktree_action", f"Unknown worktree action: {action}")
-    options: dict[str, object] = {}
+    options: dict[str, WorktreeOptionValue] = {}
     positional: list[str] = []
     i = 0
     action_specs = WORKTREE_OPTION_SPECS[action]
@@ -2090,6 +2076,8 @@ def parse_worktree(rest: list[str], json_mode: bool, cwd: str | None) -> ParsedC
         raise DelegateError(
             "unexpected_argument", f"worktree {action} does not accept positional arguments."
         )
+    if action == "gc" and options.get("pool") == "":
+        raise DelegateError("invalid_option_value", "worktree gc --pool requires a path.")
     if action == "show":
         if options.get("latest_harness") is not None:
             if positional:

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/src/delegate_agent/command_errors.py

@@ -10,6 +10,8 @@ class CommandError(Exception):
         super().__init__(message)
         self.error = error
         self.message = message
+        self.diagnostics: dict | None = None
+        self.next_actions: list[str] | None = None
 
 
 def resolve_run_target(

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/src/delegate_agent/command_help.py

@@ -1408,19 +1408,36 @@ COMMAND_SPECS: dict[str, CommandSpec] = {
     "worktree gc": CommandSpec(
         name="worktree gc",
         summary="Garbage-collect orphaned worktree metadata and stale registry entries.",
-        usage=("delegate [--cwd PATH] [--json] worktree gc [--dry-run]",),
+        usage=("delegate [--cwd PATH] [--json] worktree gc [--dry-run] [--all] [--pool PATH]",),
         options=(
             OptionSpec(
                 "--dry-run",
                 None,
                 "Report source roots that would be pruned and un-prunable worktree reasons without changing anything.",
             ),
+            OptionSpec(
+                "--all",
+                None,
+                "Also scan the machine-wide worktree pool for worktrees whose source repository is gone. Reports them; never removes them.",
+            ),
+            OptionSpec(
+                "--pool",
+                "PATH",
+                "Scan this worktree pool root instead of the configured worktrees.dataHome (finds pools left behind by an earlier dataHome). The path must exist and be a readable directory.",
+            ),
         ),
         examples=(
             "delegate worktree gc",
             "delegate worktree gc --dry-run",
+            "delegate worktree gc --all",
+            "delegate worktree gc --all --dry-run",
+        ),
+        notes=(
+            "GC reconciles registry and Git metadata; it never removes worktree paths.",
+            "--all works outside a Delegate registry, since pooled worktrees outlive the repositories that created them.",
+            "Pool orphans are reported, never removed: their uncommitted state cannot be inspected once the source repository is gone.",
+            "The pool scan removes nothing at all, including empty pool directories — it reports them so you can clear them yourself.",
         ),
-        notes=("GC reconciles registry and Git metadata; it never removes worktree paths.",),
         see_also=("worktree list", "worktree prune", "worktree remove"),
         unsupported_global_options=("--isolation", "--auth-profile"),
     ),

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/src/delegate_agent/config.py

@@ -821,11 +821,9 @@ def _reject_opencode_flag_like_value(
 def _reject_pi_family_flag_like_value(value: JsonValue, *, path: str, error: str) -> None:
     if value is None:
         return
-    if not isinstance(value, str) or not value.strip() or value.startswith("-"):
-        raise ConfigError(
-            error,
-            f"{path} must be a non-empty string that does not start with '-'.",
-        )
+    _reject_opencode_flag_like_value(value, path=path, error=error)
+    if not isinstance(value, str):
+        return
     if ":" in value:
         raise ConfigError(
             error,

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/src/delegate_agent/config_commands.py

@@ -23,10 +23,14 @@ class ConfigCommand:
 PROFILE_CONFIG_NAMES = delegate_config.PROFILE_CONFIG_NAMES
 
 
-def _target_path() -> Path:
+def target_config_path() -> Path:
+    """Resolve the config path, rejecting Windows-style paths under WSL."""
     raw = delegate_config.config_path()
     if wsl.should_reject_windows_path(str(raw)):
-        raise DelegateError("windows_path", wsl.windows_path_message("DELEGATE_CONFIG", str(raw)))
+        raise DelegateError(
+            "windows_path",
+            wsl.windows_path_message(delegate_config.CONFIG_ENV, str(raw)),
+        )
     return raw
 
 
@@ -94,7 +98,7 @@ def _validated_effective_config(config: JsonObject) -> JsonObject:
 def emit(command: ConfigCommand, stdout: TextIO) -> int:
     if command.action not in {"init", "sync-profiles"}:
         raise DelegateError("invalid_config_command", f"Unknown config action: {command.action}")
-    path = _target_path()
+    path = target_config_path()
     if command.action == "sync-profiles":
         if not path.exists():
             raise DelegateError(

{delegate_agent_cli-0.20.0 → delegate_agent_cli-0.22.0}/src/delegate_agent/constants.py

@@ -53,6 +53,30 @@ def pure_call_supported(engine: str) -> bool:
     return engine == "claude"
 
 
+def validate_pure_call(
+    engine: str, *, pure: bool, read_only: bool, group: str | None = None
+) -> None:
+    """Reject --pure combinations that conflict with its stateless one-hop contract."""
+    if not pure:
+        return
+    if group is not None:
+        raise DelegateError(
+            "pure_conflicts_group",
+            "--pure cannot be combined with --group; pure call is a stateless one-hop completion.",
+        )
+    if read_only:
+        raise DelegateError(
+            "pure_conflicts_read_only", "--pure cannot be combined with --read-only."
+        )
+    if not pure_call_supported(engine):
+        supported = ", ".join(PURE_CALL_ENGINES)
+        raise DelegateError(
+            "unsupported_pure_call",
+            f"{engine} does not support pure call mode.",
+            next_actions=[f"Use --pure with one of: {supported}."],
+        )
+
+
 # Public harness capability contract. Request validation and describe output both
 # derive from this map so enabling a capability cannot drift between the two.
 ENGINE_CAPABILITIES = {