delegation-layer 0.1.27 → 0.1.29

package/README.md

@@ -1,9 +1,11 @@
 # Delegation Layer
 
 <p align="center">
-  <a href="#install"><img src="docs/assets/delegation-layer-hero.jpg" alt="A lead AI model coordinating several specialist coding agents through Delegation Layer" width="1400"></a>
+  <a href="#install"><img src="docs/assets/delegation-layer-hero.jpg" alt="One lead AI sends briefs through Delegate to three specialist agents and collects their findings" width="1400"></a>
 </p>
 
+Briefs out. Findings back. One place to track the work.
+
 Give your lead AI agent a reliable way to delegate bounded coding work to the
 provider that fits the task.
 
@@ -25,9 +27,11 @@ already use instead of replacing them.
 - **Resumable turns** — a durable timeout can continue the exact provider
   session through a linked successor task.
 - **Runtime compatibility** — the selected provider's executable and advertised
-  capabilities are checked when the task is prepared.
+  capabilities are checked before provider execution.
 - **Model choice when needed** — native model and effort discovery is available
   without turning discovery into an admission allowlist.
+- **Optional retained worktrees** — independent Git writes can use a managed
+  worktree with explicit capture and Lead-controlled release.
 - **Native authentication** — provider login stays with the provider CLI; task
   state does not contain copied credentials.
 
@@ -205,9 +209,11 @@ delegate --root "$HOME/delegation-state" collect TASK_ID --watch 5s --json
 Use `delegate providers --json` for the compiled provider catalog and
 `delegate capabilities --provider PROFILE --json` for a provider-neutral
 capability response. `delegate preflight --provider PROFILE --cwd ABS --json`
-checks static admission without creating a task. Dispatch still performs the
-host-specific runtime probe; catalog discovery alone does not prove
-authentication or supervisor readiness.
+checks static admission without creating a task. Managed runtime-only tasks
+perform the fresh runtime probe inside their supervised worker before provider
+execution; inspection-backed paths retain admission checks. See
+[architecture](docs/architecture.md#ownership-boundaries). Catalog discovery
+alone does not prove authentication or supervisor readiness.
 
 When an explicit model or effort choice is needed, query the implemented native
 discovery command:
@@ -229,19 +235,36 @@ Discovery exits `0` for `available` or `partial`, `2` for `blocked` or
 `unavailable`, and `1` for `failed`.
 
 For Codex's native read-only review command, select `codex:review` and make
-the Git state explicit:
+the Git state explicit. Run this from an existing Git checkout outside the
+Delegate state root, with the changes you want reviewed:
 
 ```sh
-delegate --root "$HOME/delegation-state" dispatch \
+(
+REVIEW_WORKSPACE="$(git rev-parse --show-toplevel)" || exit 1
+REVIEW_BRIEF="$(mktemp)" || exit 1
+REVIEW_RESPONSE="$(mktemp)" || exit 1
+printf '%s\n' 'Review the uncommitted changes in this Git checkout.' >"$REVIEW_BRIEF"
+if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch \
   --provider codex:review \
   --review-target uncommitted \
-  --brief "$PWD/review-brief.txt" \
-  --cwd "$HOME/delegation-workspace" \
+  --brief "$REVIEW_BRIEF" \
+  --cwd "$REVIEW_WORKSPACE" \
   --permission read-only \
-  --budget 30m \
-  --json
+  --budget 1h \
+  --json >"$REVIEW_RESPONSE"; then
+  review_exit=0
+else
+  review_exit=$?
+fi
+cat "$REVIEW_RESPONSE"
+printf '\nDispatch exit: %s; saved response: %s\n' "$review_exit" "$REVIEW_RESPONSE"
+)
 ```
 
+When that response says `task_record: "created"`, observe its exact `task_id`
+with the `status` and `collect` commands above, using the same state root.
+Otherwise follow the returned failure; do not dispatch again to recover output.
+
 Use `base:BRANCH` or `commit:SHA` for a different review target. Review tasks
 are persisted as read-only tasks and do not support continuation or active-turn
 interaction. The brief is retained in the task evidence; Codex's explicit
@@ -259,6 +282,25 @@ delegate --root "$HOME/delegation-state" continue \
 The successor receives a new task ID and is observed with the same `status` and
 `collect` commands.
 
+### Optional managed Git workspaces
+
+Ordinary delegation is unchanged. For independent parallel writes, use a
+managed worktree unless the user explicitly chooses shared coordination:
+
+```sh
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --auto \
+  --brief /absolute/brief.txt --cwd /absolute/git/source \
+  --permission workspace-write --isolation git-worktree \
+  --base HEAD --workspace-budget 5m --budget 30m --json
+```
+
+The committed base is authoritative; dirty and untracked source changes are
+excluded. The worktree remains retained until the Lead reviews the captured
+Git-content evidence and explicitly releases it. Use the [managed workspace
+reference](skills/agent-integration/references/workspaces.md) for attachment,
+continuation, verification, review scope, release, and forgetting. This
+feature does not automatically apply, commit, branch, or merge worker changes.
+
 ## Documentation
 
 - [Getting started](docs/getting-started.md) — install and run a first task.
@@ -268,14 +310,16 @@ The successor receives a new task ID and is observed with the same `status` and
   behavior.
 - [Provider guide](docs/providers.md) — profiles and runtime compatibility.
 - [Architecture](docs/architecture.md) — lifecycle and ownership boundaries.
-- [System components](diagrams/components.html) — interactive Archify view.
-- [Task lifecycle](diagrams/lead-interface.html) — interactive lifecycle view.
+- [System components](diagrams/components.html) — interactive Archify view; [SVG](diagrams/components.light.svg) · [PNG](diagrams/components.light.png).
+- [Task lifecycle](diagrams/lead-interface.html) — interactive lifecycle view; [SVG](diagrams/lead-interface.light.svg) · [PNG](diagrams/lead-interface.light.png).
 - [Security](docs/security.md) — isolation, policy, and result integrity.
 - [Troubleshooting](docs/troubleshooting.md) — common setup and runtime
   failures.
 - [Agent integration skill](skills/agent-integration/SKILL.md) — the
   provider-neutral instructions installed into an agent harness.
-- [Contributing](CONTRIBUTING.md) — development and review guidance.
+- [Managed workspaces](skills/agent-integration/references/workspaces.md) —
+  optional Git checkout, capture, and retention policy.
+- [Contributing](docs/contributing.md) — development and review guidance.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delegation-layer",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Multi-provider AI agent delegation CLI and Agent Skill for running bounded coding tasks across provider CLIs.",
   "keywords": [
     "ai-agents",
@@ -27,7 +27,8 @@
     "skills/agent-integration/",
     "plugins/delegation-layer/",
     "scripts/install-agent-integration.mjs",
-    "scripts/install-cli.mjs"
+    "scripts/install-cli.mjs",
+    "scripts/installer/"
   ],
   "engines": {
     "node": ">=18"

package/plugins/delegation-layer/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "delegation-layer",
   "displayName": "Delegation Layer",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Consult external AI harnesses and CCR-configured models for reviews, research, implementation, and debate through the resumable Delegate CLI.",
   "author": {
     "name": "Hesham Karam",

package/plugins/delegation-layer/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "delegation-layer",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Consult external AI harnesses and CCR-configured models for reviews, research, implementation, and debate through the resumable Delegate CLI.",
   "author": {
     "name": "Hesham Karam",

package/plugins/delegation-layer/skills/agent-integration/SKILL.md

@@ -34,7 +34,7 @@ Do not inspect, authenticate, install, or repair provider CLIs to bypass a
 Delegate blocker.
 
 A reported blocker is a valid final response to a delegation request. It does
-not turn that request into an environment-repair task. The one lifecycle
+not turn that request into an environment-repair task. The supervisor recovery
 exception is `failure.code: "supervisor_upgrade_required"` with
 `next_action: "run_supervisor_migrate"`: run Delegate's own
 `supervisor migrate` command once with the exact same state root, then retry the
@@ -47,6 +47,9 @@ not Pueue administration. Never run `pueue`, `pueued`, socket inspection,
 process searches, root deletion, or a provider CLI during recovery. Executable
 path or hash drift alone is handled by normal adoption and does not require
 this command.
+Managed admission also permits the two explicit `watch_workspace` responses
+in the task-record table below. They keep the exact admission command and
+inputs, including `continue`; they do not authorize environment repair.
 When a response says `failure.next_action: "stop_and_report"`, that attempt is
 finished. Include its failure in your final response without opening a
 clarification dialog to choose a fallback. For `task_record: not_created`,
@@ -72,7 +75,9 @@ tasks may proceed; the failed attempt must remain reported as failed or blocked.
 3. Give every turn an absolute workspace, an explicit permission mode, and a
    finite budget. Keep the state root outside the workspace. Reuse a supplied
    `DELEGATE_ROOT` for all providers and tasks; do not invent per-provider or
-   per-task state roots. Task IDs separate work within that root.
+   per-task state roots. Task IDs separate work within that root. Managed Git
+   workspaces are optional; read [managed workspace guidance](references/workspaces.md)
+   before creating or attaching one.
 4. Use `--json` and save each response separately with its requested destination,
    model, effort, workspace, and returned `task_id`. Never merge concurrent
    responses into an unlabeled output stream. Read `admission`, `liveness`,
@@ -119,8 +124,10 @@ tasks may proceed; the failed attempt must remain reported as failed or blocked.
 11. The model chooses ordinary-task fan-out by issuing independent `dispatch`
     commands concurrently. The private supervisor does not impose a task-count
     or CPU-based limit. Use this for independent investigation, debate, review,
-    or provider comparison. Concurrent write tasks must use separate workspaces
-    or explicit coordination to avoid file conflicts.
+    or provider comparison. For independent parallel writes, choose
+    `--isolation git-worktree` automatically unless the user explicitly chooses
+    shared coordination; the model chooses fan-out and task scope. A read-only
+    review may attach a retained workspace with `--workspace ID`.
 
 For an explicit Codex code review, use the discoverable `codex:review` profile
 with one persisted target: `--review-target uncommitted`,
@@ -131,6 +138,13 @@ provider to edit files; the review profile is for Codex's native review
 operation and keeps the reviewed Git state explicit. The brief is retained as
 task evidence; the review target supplies Codex's review scope because its
 native command does not accept a prompt with the target flag.
+For a complete managed-workspace turn, review the recorded initial base against
+its captured tree through an ordinary read-only task. Include both sealed refs
+and an explicit `git diff BASE TREE` scope. A native `uncommitted` review covers
+current staged, unstaged, and untracked changes; it excludes worker commits.
+Do not pass a tree as a native branch target. Preserve an explicitly requested
+native review target and state its narrower scope. See [workspace review
+guidance](references/workspaces.md#recovery-and-review-scope).
 
 ## Operating procedure
 
@@ -152,7 +166,7 @@ If no destination was named, use automatic selection directly. If the user
 named a harness (for example, “Codex”), resolve its exact provider ID from:
 
 ```sh
-delegate providers --json
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" providers --json
 ```
 
 Use the matching catalog ID with `--provider`; do not silently substitute
@@ -287,6 +301,7 @@ for **each attempt**, including requests issued together:
 | Usage error, no JSON response | Correct the reported syntax using Delegate help or `providers --json`, then invoke that request again. Parsing failed before admission. |
 | `task_record: not_created`, `failure.code: supervisor_upgrade_required`, and `failure.next_action: run_supervisor_migrate` | Run `delegate --root "<the exact absolute state root used by the failed command>" supervisor migrate --json` once. Retry the exact original admission argv once only after `supervisor_control.state: migrated` and `supervisor_control.next_action: retry_dispatch`; otherwise stop and report the migration response. Preserve an explicit custom root exactly. A failed `continue` must be retried as the same `continue`; never replace it with a fresh `dispatch` or a direct provider call. |
 | `task_record: not_created` and `failure.next_action: correct_request` | Correct that request and retry it. |
+| `task_record: not_created`, `failure.code: workspace_provision_pending` or `workspace_busy`, and `failure.next_action: watch_workspace` | Follow [managed workspace recovery](references/result-handling.md#managed-workspace-results) using the same root and workspace. Once ready, retry the exact admission command and inputs. A failed `continue` remains that same `continue`, never a new dispatch. |
 | `task_record: not_created` with any other next action | Report that attempt's failure and stop it. Do not diagnose provider setup or substitute an integration. |
 | `task_record: created` | Use `status` before taking any other action. Do not dispatch again. |
 | `task_record: unknown` or an ambiguous response | Stop and report; do not retry an uncertain task creation. |
@@ -352,10 +367,14 @@ recruit more agents unless that is explicitly part of the task.
   admission, publication, authentication, errors, or exit codes.
 - Read [continuation](references/continuation.md) for timeout recovery or an
   exact-session follow-up.
+- Read [managed workspaces](references/workspaces.md) for optional Git
+  worktrees, capture, review scope, release, and forgetting.
 - Use [read-only example](examples/read-only-task.md),
-  [write example](examples/workspace-write-task.md), and
-  [JSON examples](examples/json-results.md) when constructing a task or parsing
-  unfamiliar output. Do not load every reference for a routine dispatch.
+  [write example](examples/workspace-write-task.md),
+  [JSON examples](examples/json-results.md), and
+  [managed workspace example](examples/managed-workspace.md) when constructing
+  a task or parsing unfamiliar output. Do not load every reference for a
+  routine dispatch.
 
 ## Completion report
 

package/plugins/delegation-layer/skills/agent-integration/examples/json-results.md

@@ -5,10 +5,9 @@ delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" status "$TASK_ID" --j
 delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect "$TASK_ID" --watch 5s --json
 ```
 
-Decision order:
-
-1. Save `task_id`.
-2. Check `admission` and `error`.
-3. Wait while publication is pending.
-4. Accept only a committed terminal `outcome`.
-5. If `status` is `timed_out`, follow `continuation.resumable`.
+Apply [result handling](../references/result-handling.md) to each response and
+follow [Observe and collect](../SKILL.md#5-observe-and-collect). Those sections
+own the decision order for task creation, failures, timeout continuation,
+terminal outcomes, pending interaction, and bounded collection. Read them
+before interpreting these commands; pending publication alone is not a reason
+to wait when the task needs an answer or timeout recovery.

package/plugins/delegation-layer/skills/agent-integration/examples/managed-workspace.md

@@ -0,0 +1,68 @@
+# Managed workspace example
+
+Use this example for independent write work that should be isolated in a
+retained Git worktree. The source must be a Git checkout and the state root
+must remain outside provider-writable workspaces.
+
+```sh
+SOURCE="$PWD"
+BRIEF="$(mktemp)"
+RESPONSE="$(mktemp)"
+printf '%s\n' 'Implement the requested change and report the files changed.' >"$BRIEF"
+
+if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --auto \
+  --brief "$BRIEF" --cwd "$SOURCE" \
+  --permission workspace-write --isolation git-worktree \
+  --base HEAD --workspace-budget 5m --budget 30m --json >"$RESPONSE"; then
+  dispatch_exit=0
+else
+  dispatch_exit=$?
+fi
+printf '%s\n' "$dispatch_exit" >"$RESPONSE.exit"
+cat "$RESPONSE"
+```
+
+Read the saved JSON before running another command. When
+`task_record: "created"`, use its `task_id` as `TASK_ID` below. When no task
+was created, follow the [result decisions](../references/result-handling.md#managed-workspace-results);
+do not run task status or collection against that nonexistent record.
+
+```sh
+if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" status TASK_ID --json >"$RESPONSE.status"; then
+  status_exit=0
+else
+  status_exit=$?
+fi
+printf '%s\n' "$status_exit" >"$RESPONSE.status.exit"
+if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect TASK_ID --watch 5s --json >"$RESPONSE.collect"; then
+  collect_exit=0
+else
+  collect_exit=$?
+fi
+printf '%s\n' "$collect_exit" >"$RESPONSE.collect.exit"
+```
+
+Continue observing that created task when collection exits `3`. Wait for the
+workspace to return to `state: retained` and inspect its final capture. Only
+after the Lead explicitly chooses release, run:
+
+```sh
+if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" workspace release WORKSPACE_ID \
+  --budget 5m --json >"$RESPONSE.release"; then
+  release_exit=0
+else
+  release_exit=$?
+fi
+printf '%s\n' "$release_exit" >"$RESPONSE.release.exit"
+```
+
+Read the release acknowledgement. `watch_workspace` means observe this
+accepted release; a `retry_release` acknowledgement means it was not accepted.
+Follow the same result decisions rather than assuming either response is
+completed cleanup.
+
+Save each response and exit code once. A created task is observed with
+`status` first and collected in the foreground. Exit `3` means pending, not
+success; continue observing the same task. The Lead reviews the capture and
+owns landing any changes. `workspace release` is explicit; no automatic
+apply, commit, branch merge, TTL eviction, or provider-CLI fallback occurs.

package/plugins/delegation-layer/skills/agent-integration/references/collaboration.md

@@ -1,5 +1,13 @@
 # Parallel reviews and debates
 
+For independent parallel write work, choose `--isolation git-worktree`
+automatically unless the user explicitly chooses shared coordination. The
+model chooses fan-out and task scope; the supervisor has no fixed task-count
+cap or TTL eviction. A read-only review may attach a retained workspace with
+`--workspace ID`. The single managed-workspace policy, capture boundary, and
+release rules live in [managed workspace guidance](workspaces.md); do not
+restate them in each collaboration brief.
+
 ## Keep each request identifiable
 
 Choose the fan-out needed for the user's task. Each participant needs its own
@@ -19,18 +27,26 @@ RECEIPTS="$(mktemp -d)" || exit 1
 # Set these absolute paths and catalog IDs in this same tool invocation.
 # BRIEF_A and BRIEF_B contain the real independent assignments.
 (
-  delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_A" \
+  if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_A" \
     --brief "$BRIEF_A" --cwd "$WORKSPACE_A" \
     --permission read-only --budget 30m --json \
-    >"$RECEIPTS/review-a.json" 2>"$RECEIPTS/review-a.stderr"
-  printf '%s\n' "$?" >"$RECEIPTS/review-a.exit"
+    >"$RECEIPTS/review-a.json" 2>"$RECEIPTS/review-a.stderr"; then
+    dispatch_exit=0
+  else
+    dispatch_exit=$?
+  fi
+  printf '%s\n' "$dispatch_exit" >"$RECEIPTS/review-a.exit"
 ) &
 (
-  delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_B" \
+  if delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --provider "$PROVIDER_B" \
     --brief "$BRIEF_B" --cwd "$WORKSPACE_B" \
     --permission read-only --budget 30m --json \
-    >"$RECEIPTS/review-b.json" 2>"$RECEIPTS/review-b.stderr"
-  printf '%s\n' "$?" >"$RECEIPTS/review-b.exit"
+    >"$RECEIPTS/review-b.json" 2>"$RECEIPTS/review-b.stderr"; then
+    dispatch_exit=0
+  else
+    dispatch_exit=$?
+  fi
+  printf '%s\n' "$dispatch_exit" >"$RECEIPTS/review-b.exit"
 ) &
 wait
 printf 'Read each response separately in %s\n' "$RECEIPTS"

package/plugins/delegation-layer/skills/agent-integration/references/command-reference.md

@@ -3,25 +3,32 @@
 All paths passed to `--root`, `--cwd`, and `--brief` must be absolute. Add
 `--json` to commands that return an agent-consumable response.
 
+Pass the intended workspace directly. Delegate handles provider launch options;
+do not initialize Git, change trust settings, or call a provider CLI as a
+workspace workaround. Ordinary tasks support non-Git directories. Git is
+required for managed worktree creation/attachment only; native review retains
+its separate explicit review-target contract. See [managed workspace guidance](workspaces.md)
+for the policy owner.
+
 | Command | Purpose | Launches provider work? |
 | --- | --- | --- |
 | `delegate --version` | Confirm the installed control CLI | No |
-| `delegate providers --json` | List compiled provider metadata | No |
-| `delegate capabilities --provider ID --json` | Read the catalog contract | No |
-| `delegate models --provider ID [--cwd ABS] --json` | Discover advisory native model and effort facts | Native inspection only; no admitted task |
-| `delegate preflight --provider ID --cwd ABS --json` | Check static provider admission | No |
-| `delegate dispatch --auto ... --json` | Select and admit one bounded turn | Yes, at most once |
-| `delegate status TASK --json` | Reconcile and observe task state | No provider launch |
-| `delegate collect TASK --watch 5s --json` | Read or wait for publication | No provider launch |
-| `delegate recheck TASK --json` | Reassess eligible rejected evidence offline | No provider launch; original outcome unchanged |
-| `delegate continue --task TASK ... --json` | Create an exact-session successor | Yes, at most once for the successor |
-| `delegate reply TASK --request ID --answers FILE --id MESSAGE_ID --json` | Answer a pending native question | No new launch |
-| `delegate steer TASK --brief FILE --id MESSAGE_ID --json` | Guide a supported active turn | No new launch |
-| `delegate events TASK --after SEQUENCE --watch 5s --json` | Read a bounded interaction event page | No |
-| `delegate logs TASK --json` | Return validated output descriptors | No |
-| `delegate cancel TASK --json` | Record one explicit stop request | Stops, does not relaunch |
-
-`delegate supervisor migrate --json` is the single command-neutral recovery
+| `delegate --root ROOT providers --json` | List compiled provider metadata | No |
+| `delegate --root ROOT capabilities --provider ID --json` | Read the catalog contract | No |
+| `delegate --root ROOT models --provider ID [--cwd ABS] --json` | Discover advisory native model and effort facts | Native inspection only; no admitted task |
+| `delegate --root ROOT preflight --provider ID --cwd ABS --json` | Check static provider admission | No |
+| `delegate --root ROOT dispatch --auto ... --json` | Select and admit one bounded turn | Yes, at most once |
+| `delegate --root ROOT status TASK --json` | Reconcile and observe task state | No provider launch |
+| `delegate --root ROOT collect TASK --watch 5s --json` | Read or wait for publication | No provider launch |
+| `delegate --root ROOT recheck TASK --json` | Reassess eligible rejected evidence offline | No provider launch; original outcome unchanged |
+| `delegate --root ROOT continue --task TASK ... --json` | Create an exact-session successor | Yes, at most once for the successor |
+| `delegate --root ROOT reply TASK --request ID --answers FILE --id MESSAGE_ID --json` | Answer a pending native question | No new launch |
+| `delegate --root ROOT steer TASK --brief FILE --id MESSAGE_ID --json` | Guide a supported active turn | No new launch |
+| `delegate --root ROOT events TASK --after SEQUENCE --watch 5s --json` | Read a bounded interaction event page | No |
+| `delegate --root ROOT logs TASK --json` | Return validated output descriptors | No |
+| `delegate --root ROOT cancel TASK --json` | Record one explicit stop request | Stops, does not relaunch |
+
+`delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" supervisor migrate --json` is the single command-neutral recovery
 step for a `supervisor_upgrade_required` admission response. Run it once with
 the failed command's exact root. A successful response names its next action
 `retry_dispatch`, but the original command and argv remain authoritative:
@@ -50,6 +57,35 @@ Dispatch flags:
 - `--interactive`: enable advertised native clarification and steering; see [interaction](interaction.md);
 - `--native-timeout DURATION`: optional provider-native timeout where advertised.
 
+## Managed workspace commands
+
+Managed workspaces are optional. For independent parallel writes, choose
+`--isolation git-worktree` unless the user explicitly chooses shared
+coordination. The model chooses fan-out and task scope; there is no fixed task
+count cap or TTL eviction. Use the canonical [workspace reference](workspaces.md)
+for retention, capture, release, forgetting, and review-scope rules.
+
+The public forms are:
+
+```sh
+delegate --root ROOT dispatch --isolation git-worktree --cwd ABS \
+  [--base REV] [--workspace-budget DURATION] ... --json
+delegate --root ROOT dispatch --workspace WORKSPACE_ID ... --json
+delegate --root ROOT workspace list [--after ID] [--limit 1..50] --json
+delegate --root ROOT workspace status ID [--operation OP] [--watch DURATION] --json
+delegate --root ROOT workspace exec ID --budget DURATION -- ARGV...
+delegate --root ROOT workspace release ID [--discard] [--budget DURATION] --json
+delegate --root ROOT workspace forget ID [--budget DURATION] --json
+```
+
+`--workspace` cannot be combined with public `--cwd`, `--base`, or
+`--isolation`. `workspace exec` passes literal argv after `--` and initially
+returns asynchronously; exit `3` means the operation is pending. The helper
+budget defaults to 5m, is persisted/overridable, and does not renew the task
+budget. `continue --task TASK` inherits the predecessor workspace, cwd, and
+session while creating a new task ID. A read-only review may attach a retained
+workspace with `--workspace ID`.
+
 Model discovery uses the same `--provider ID` profiles and accepts an optional
 absolute `--cwd` (default: current directory). Its JSON has `status` values
 `available`, `partial`, `blocked`, `unavailable`, or `failed`; exits are `0`,
@@ -72,7 +108,8 @@ is incomplete or does not list them. To resolve a natural-language model name
 or choose an option the caller left open, use native discovery:
 
 ```sh
-delegate models --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" models \
+  --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
 ```
 
 Omit `--cwd` to use the current directory. Run discovery only when the caller
@@ -106,7 +143,8 @@ Use `preflight` when the caller asks about static readiness, rather than as a
 required step before every dispatch:
 
 ```sh
-delegate preflight --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE \
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" preflight \
+  --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE \
   --permission REQUESTED_MODE --json
 ```
 

package/plugins/delegation-layer/skills/agent-integration/references/continuation.md

@@ -40,6 +40,19 @@ but it does not authorize a fresh dispatch. Apply the remaining `task_record`
 error rules in [result handling](result-handling.md) before retrying or
 observing.
 
+When the predecessor is bound to a managed workspace, `continue --task` carries
+the recorded workspace, working directory, provider session, and environment
+to the new task ID. It does not mutate the predecessor's immutable request or
+reservation. A changed provider request is a new turn and must pass the normal
+workspace-use reservation. Read [managed workspace guidance](workspaces.md)
+before attaching another provider, review, or verification operation.
+
+If `continue` returns `workspace_busy` with `task_record: "not_created"` and
+`next_action: "watch_workspace"`, observe that workspace with the same root.
+Then retry the exact `continue --task PREDECESSOR_ID` after it becomes retained.
+Keep the original predecessor, brief, and budget; do not replace continuation
+with a fresh dispatch. A created successor is only observed.
+
 `mode` describes the provider contract:
 
 - `native` uses the provider’s exact persisted conversation/session ID;
@@ -53,3 +66,26 @@ terminal outcome or a durable Pueue-ended observation backed by a guardian
 lifetime-termination record with independently proven empty scope for the
 session handoff; without one of those proofs it refuses continuation. Inspect
 the predecessor again rather than bypassing that boundary.
+
+For a managed workspace timeout, capture is a new finite auxiliary operation
+after canonical closure. The normal path proves the provider scope empty and
+records the managed worker's exact `Wait`; recovery can instead use a validated
+absence disposition or previous-boot termination without inventing a native
+`Wait`. Capture never renews the expired provider deadline or reuses its scope. Closure with an
+unavailable capture can still preserve continuation evidence; it does not
+change the provider outcome.
+
+
+## Follow up after normal completion
+
+A validated terminal outcome, committed or rejected, can also support a new
+turn when the provider supports continuation, its exact session was recorded,
+and the runner/session reservation has been released. Not every rejection has
+a usable session. A normal completion without a budget stop need not expose
+`continuation.resumable` in `status` or `collect`. Use `continue` with the exact
+predecessor and a finite budget, then apply its task-creation and failure
+response as described in [result handling](result-handling.md).
+
+If the response says `stop_and_report`, stop that attempt; do not automatically
+retry it. A caller may make a later request after observing the predecessor.
+Native `codex:review` tasks cannot be continued.

package/plugins/delegation-layer/skills/agent-integration/references/result-handling.md

@@ -13,8 +13,11 @@ the same as a successful provider result.
    `supervisor_control.next_action: "retry_dispatch"`, retry the exact original
    admission argv once. The retry is command-neutral: `dispatch` remains
    `dispatch`, and `continue` remains `continue`; never create a fresh dispatch
-   or call a provider directly to replace a failed continuation. For every
-   other `not_created` response, do not poll; correct the request only if
+   or call a provider directly to replace a failed continuation. Also handle
+   `workspace_provision_pending` or `workspace_busy` with `watch_workspace`
+   using [managed workspace recovery](#managed-workspace-results) before the
+   generic stop rule. For every other `not_created` response, do not poll;
+   correct the request only if
    `failure.next_action` is `correct_request`, otherwise report and stop. When
    `task_record` is `unknown`, stop and report without polling or retrying.
    Status and collect can report `admission: "unknown"` alongside valid terminal
@@ -68,6 +71,47 @@ Versions and help are observations, not semantic-version allowlists.
 Authentication is a separate live gate (`not_run`, `passed`, or `blocked`).
 Report a blocked prerequisite without inventing a login command or retrying.
 
+## Managed workspace results
+
+Treat `response.workspace` as a separate resource and Git-content evidence
+projection. It does not replace `outcome`, `publication`, or `continuation`.
+The provider outcome is immutable and the workspace `CaptureReceipt` is a
+separate immutable fact; a failed or unavailable capture must not be reported
+as a provider failure when native closure is already proven.
+
+Before a task record exists, a pending workspace provision returns
+`task_record: "not_created"` with
+`failure.code: "workspace_provision_pending"` and
+`failure.next_action: "watch_workspace"`. Run the returned workspace-status
+command with the same root and workspace ID. Once ready, retry the same
+admission with the returned task ID in `--id` and unchanged provider, brief,
+permission, model, effort, and source options. A proven never-launched attempt
+gets a fresh helper deadline; a created task is only observed.
+
+An occupied managed workspace can return `workspace_busy` with
+`task_record: "not_created"` and `watch_workspace` before authorizing a task.
+Observe the owning workspace, then retry the exact original admission command.
+For `continue`, keep `continue --task PREDECESSOR_ID`; never replace it with a
+dispatch. These two workspace responses are narrow exceptions to the generic
+stop rule. Do not invent another recovery code or provider retry.
+
+Read the acknowledgement before observing or repeating a workspace mutation:
+
+| Response | Required action |
+| --- | --- |
+| Exit `3`, reason `requested_action_not_authorized`, next action `retry_exec`, `retry_release`, or `retry_forget` | The requested mutation was not accepted. Observe the workspace without `--operation` until the prior use ends, then retry that exact mutation. `exec` and `release` need `state: retained`; `forget` needs `state: released`. |
+| Exit `3`, next action `watch_workspace` | The action is accepted. Observe the same workspace; add `--operation OP` only when its response supplies `operation_id`. Do not repeat the mutation or invent an operation ID. |
+| A concrete failure or `stop_and_report` | Preserve the response and report it; do not turn it into a pending watch or provider fallback. |
+
+Use `workspace status ID [--operation OP] --watch DURATION --json` for these
+observations. An accepted action may not have a helper ID yet. An `exec`
+result of `succeeded` proves the command finished; wait for `state: retained`
+before another use, because recapture must finish too. Verification evidence
+does not replace the provider outcome. Keep the checkout retained until the
+Lead has terminal task/capture evidence and explicitly releases it. Read
+[managed workspace guidance](workspaces.md) for the exact command surface and
+review/capture/forgetting boundaries.
+
 ## Offline recovery
 
 When Delegate returns `failure.next_action: "recheck"`, use the same root and