delegation-layer 0.1.16 → 0.1.18

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

@@ -0,0 +1,251 @@
+---
+name: agent-integration
+description: Consult external AI agents and harnesses through Delegate for reviews, research, implementation, testing, second opinions, comparisons, and debates. Use when asked to ask Codex, consult Claude, get Antigravity’s opinion, or assign work to another harness or model, including external collaboration you choose during a task. Not for ordinary native subagents, provider setup, or questions merely about a tool.
+---
+
+# Delegation Layer
+
+## When to use
+
+Use this skill before selecting a provider-specific plugin or launching an
+external harness to do work. Requests such as “ask Codex to review this”,
+“get Antigravity’s opinion”, and “have Claude investigate” are external
+collaboration even when the user never mentions Delegate. The same applies
+when you decide external expertise is useful to fulfill the user's task.
+These names are examples; discover supported destinations through the CLI.
+
+Ordinary subagents within the current harness remain available. Naming the
+current harness (for example, “have Claude investigate” while using Claude)
+also permits native delegation unless the user requests a separate session.
+A separate CLI session uses Delegate even when its brand matches yours. A subagent
+or plugin that calls an external harness is still external collaboration and
+uses Delegate. Merely discussing a provider, editing documentation about it,
+or troubleshooting its installation does not trigger delegation. Respect an
+explicit user choice of another integration; this skill does not override it.
+
+The local `delegate` CLI is the integration surface for external work. Do not
+replace it with a provider command, a provider-specific plugin, or an API call.
+Do not inspect, authenticate, install, or repair provider CLIs to bypass a
+Delegate blocker.
+
+## Rules
+
+1. Check whether `delegate` is already installed. A plugin SessionStart hook
+   normally bootstraps the self-contained CLI when it is missing. This skill
+   never installs or repairs the CLI itself. If `delegate` is still missing or
+   unusable, report the bootstrap failure and stop; never fall back to a native
+   provider command.
+2. Preserve a named harness or provider, even when the user supplied a natural
+   name rather than a provider ID. Use `dispatch --auto` when none was chosen.
+   Provider selection, executable checks, compatibility checks, authentication
+   gates, and supervisor admission belong inside Delegation Layer.
+3. Give every turn an absolute workspace, a separate state root, an explicit
+   permission mode, and a finite budget. Preserve a caller-supplied
+   `DELEGATE_ROOT`; do not replace it with a temporary directory.
+4. Use `--json` and save the returned `task_id`. Read `admission`, `liveness`,
+   `publication`, `status`, `outcome`, `continuation`, `task_record`, `failure`,
+   and `error` as separate fields.
+   Delegate owns the supervisor lifecycle. Never install, configure, start,
+   inspect, or repair Pueue, and never poll a task unless the response says its
+   `task_record` is `created`.
+5. Observe with `status` and collect with `collect`. Collection may recover the
+   saved supervisor only to observe an already-requested budget stop; it never
+   launches a provider or retries a task.
+6. If a task is timed out and its JSON says `continuation.resumable: true`, use
+   `continue --task TASK_ID`, optionally with a new `--brief`. Do not create a
+   fresh unrelated dispatch to replace a resumable task.
+7. Treat `blocked` authentication as unresolved. Do not call it compatible,
+   successful, or failed provider behavior, and do not invent login commands.
+8. Never put credentials, tokens, or unrestricted provider output in a brief,
+   option, receipt, or agent message.
+9. Permission modes select provider-native behavior, not an independent sandbox.
+   Providers load their own configuration and extensions. If a task is rejected,
+   report delegate's evidence; do not assume the user's configuration is faulty
+   or remove MCP servers, plugins, settings, or credentials to make it pass.
+10. 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.
+
+## Operating procedure
+
+### 1. Verify the control CLI
+
+Run a quick local check:
+
+```sh
+command -v delegate && delegate --version
+```
+
+If discovery fails, report that Delegation Layer is missing. If the version
+command fails, report that the installed CLI is unusable. Stop in either case.
+Do not substitute a provider command.
+
+### 2. Discover only when useful
+
+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
+```
+
+Use the matching catalog ID with `--provider`; do not silently substitute
+`--auto` or another provider. If the name is ambiguous, clarify the intended
+destination. If it is absent, report that this build does not support it.
+The catalog is not proof that a provider is installed, authenticated, or ready.
+If a side-effect-free readiness check is useful,
+run:
+
+```sh
+delegate preflight --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE \
+  --permission REQUESTED_MODE --json
+```
+
+Replace `REQUESTED_MODE` with `read-only` for investigation or
+`workspace-write` for authorized edits. Preflight reports static admission only.
+It does not create a task, start the supervisor, or launch a provider. Do not keep
+retrying preflight when it says
+`blocked` or `unsupported`; report the bounded reason.
+
+The catalog and `capabilities` response expose supported permission modes,
+request options, continuation, and the read-only mechanism. A read-only
+capability with `containment: "provider-owned"` selects the provider's native
+behavior but is not an independent delegate-owned sandbox. Static discovery
+does not prove authentication or live acceptance; use the dispatch or live
+acceptance result for that evidence.
+
+Keep provider defaults when no model or effort was requested. When an explicit
+choice is needed, read [model and effort guidance](references/command-reference.md#choosing-models-and-effort).
+Pass requested choices through Delegate's public `--model` and `--effort`
+fields; discovery is advisory, never an allowlist.
+
+### 3. Prepare separate paths and a finite brief
+
+Use an existing task brief when one is supplied. Otherwise create a bounded
+brief file that contains the requested work and its acceptance criteria. Keep
+the state root outside the workspace and provider-writable trees (which can
+include the system temporary directory). Use `DELEGATE_ROOT` when supplied:
+
+```sh
+STATE_ROOT="${DELEGATE_ROOT:-$HOME/delegation-state}"
+WORKSPACE="$PWD"
+BRIEF="$(mktemp)"
+cat >"$BRIEF" <<'EOF'
+Describe the delegated task, the files or behavior to change, and the checks
+that must pass. Keep the response concise and report validation evidence.
+EOF
+```
+
+Replace the example brief with the actual user request. Do not place the state
+root inside the workspace or place secrets in either path’s task data. Keep it
+outside provider configuration and runtime directories as well. If delegate
+rejects placement before admission, choose a separate state directory; do not
+change provider settings. Once admitted, retain that state root for every
+observation and continuation.
+
+### 4. Dispatch one bounded turn
+
+Use automatic selection unless the user named a destination.
+For a named harness or provider resolved in step 2, replace `--auto` with `--provider PROVIDER_ID`; never
+combine the two:
+
+```sh
+delegate --root "$STATE_ROOT" dispatch --auto \
+  --brief "$BRIEF" \
+  --cwd "$WORKSPACE" \
+  --permission read-only \
+  --budget 30m \
+  --json
+```
+
+For an authorized code change, use `--permission workspace-write`; this requests
+unattended native tool execution, including shell commands and file edits.
+The provider may allow access beyond the selected workspace. Delegate supplies
+the native approval options; do not add provider flags or call its CLI yourself.
+Keep the budget finite. A successful dispatch means the request was durably admitted;
+it does not mean the delegated work finished.
+
+For independent work, the model may run several complete `dispatch` commands
+concurrently. Keep each task's brief, workspace, permission, and task ID
+independent. Do not configure Pueue or wait for one task before dispatching the
+next solely to serialize ordinary work. Inspect each returned task separately
+with `status` and `collect`.
+
+Save the exact `task_id` from the JSON response. The recovery steps below apply
+to parsed dispatch responses. If the CLI rejects the command syntax before
+dispatch (nonzero exit with a usage error and no JSON response), correct the
+reported syntax and invoke it again; argument parsing fails before admission and
+does not create a task record. For a parsed dispatch error, read its `failure`
+and `task_record` fields. If `task_record` is
+`not_created`, do not run `status`, `collect`, or `continue`; correct the request
+only when `failure.next_action` is `correct_request`, otherwise report the
+delegate failure and stop. If it is `created`, use `status` before taking any
+other action. If it is `unknown`, stop and report the failure: with an
+explicit task ID, absence can race another dispatch that is creating the same
+ID. Never retry that ID, run Pueue commands, or silently try another provider
+after a task may have been admitted.
+
+### 5. Observe and collect
+
+Use the same state root and task ID:
+
+```sh
+delegate --root "$STATE_ROOT" status TASK_ID --json
+delegate --root "$STATE_ROOT" collect TASK_ID --watch 5s --json
+```
+
+Check `status` first: if it is `timed_out`, follow step 6 even when publication
+is pending and no outcome is present. Otherwise, if `collect` exits with code
+`3` because publication is still pending, wait a short interval and run
+`collect` again. Do not dispatch again. Continue until
+the response has a terminal `outcome` or a bounded operational error that
+requires the caller’s attention.
+
+Accept a result only when the terminal outcome is present and its publication
+is committed. A rejected outcome is terminal evidence and must be reported as
+rejected. Payload and raw output are returned as validated descriptors; do not
+copy unrestricted provider output into the control response.
+
+### 6. Continue a timed out turn
+
+When `status` or `collect` reports `timed_out`, read
+[continuation and timeout recovery](references/continuation.md). If
+`continuation.resumable` is true, use `continue --task TASK_ID` with the original
+state root and a finite budget, then observe the returned successor ID. Do not
+wait indefinitely for pending publication or restart the task as an unrelated
+dispatch. If continuation is unavailable, report its reason. Apply the same
+`failure` and `task_record` decisions as for dispatch; never repeat an uncertain
+successor creation.
+
+## Comparisons, debate, and follow-up
+
+Choose a finite scope and number of rounds appropriate to the user's request.
+For independent opinions, dispatch separate briefs to the chosen destinations
+and collect each result. Summarize the relevant findings as task data in the
+next brief; do not forward credentials or unrestricted output. Use a supported
+`continue` for an exact-session follow-up, or a new bounded task for an
+independent question. Preserve which agent supplied each finding, explain
+agreements and disagreements, and stop at the agreed scope or a blocker.
+An external worker should perform its assigned work; do not ask it to recursively
+recruit more agents unless that is explicitly part of the task.
+
+## Details when needed
+
+- Read [command reference](references/command-reference.md) when choosing
+  model/effort options or another public command.
+- Read [result handling](references/result-handling.md) when interpreting
+  admission, publication, authentication, errors, or exit codes.
+- Read [continuation](references/continuation.md) for timeout recovery or an
+  exact-session follow-up.
+- 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.
+
+## Completion report
+
+Report the original task ID, selected provider ID when the CLI returns one,
+the final admission/liveness/publication fields, the terminal outcome and
+evidence descriptors, and any continuation or blocked-authentication state.

package/plugins/delegation-layer/skills/agent-integration/evals/evals.json

@@ -0,0 +1,61 @@
+{
+  "skill": "agent-integration",
+  "version": 1,
+  "cases": [
+    {
+      "name": "missing-cli",
+      "prompt": "Delegate this read-only task.",
+      "expected": ["check delegate", "report missing prerequisite", "do not install a provider"]
+    },
+    {
+      "name": "normal-dispatch",
+      "prompt": "Run one bounded task through the available agent provider.",
+      "expected": ["dispatch --auto", "--json", "save task_id", "status", "collect"]
+    },
+    {
+      "name": "model-discovery-when-needed",
+      "prompt": "The caller needs an explicit model and effort for codex:exec.",
+      "expected": ["delegate models --provider codex:exec", "--json", "preserve null versus empty efforts", "advisory", "pass --model and --effort"]
+    },
+    {
+      "name": "model-default-without-discovery",
+      "prompt": "Run a task without an explicit model or effort.",
+      "expected": ["provider defaults are valid", "do not run models unnecessarily", "dispatch --auto"]
+    },
+    {
+      "name": "timeout",
+      "prompt": "The result says status timed_out and continuation.resumable is true.",
+      "expected": ["delegate continue --task", "new task id", "collect successor", "no fresh unrelated dispatch"]
+    },
+    {
+      "name": "blocked-auth",
+      "prompt": "Capability output says live_acceptance.status is blocked.",
+      "expected": ["preserve blocked", "do not call a provider login command", "do not claim success"]
+    },
+    {
+      "name": "provider-neutrality",
+      "prompt": "Use the skill without a provider name.",
+      "expected": ["delegate only", "dispatch --auto", "no direct provider CLI"]
+    },
+    {
+      "name": "pi-write",
+      "prompt": "Use pi:json through delegate to update a file and run its tests. Edits are authorized.",
+      "expected": ["--provider pi:json", "--permission workspace-write", "delegate only", "save task_id", "collect validated evidence"]
+    },
+    {
+      "name": "write-permission-denial",
+      "prompt": "An admitted workspace-write task reports a native tool permission denial.",
+      "expected": ["report task evidence", "do not edit provider configuration", "do not call provider CLI", "no automatic redispatch"]
+    },
+    {
+      "name": "unavailable-provider",
+      "prompt": "The selected provider is unavailable before admission.",
+      "expected": ["report bounded reason", "do not install or authenticate provider", "do not claim success"]
+    },
+    {
+      "name": "write-timeout",
+      "prompt": "An authorized write task has status timed_out, publication unknown, no outcome, and continuation.resumable true.",
+      "expected": ["delegate continue --task", "same state root", "new task id", "do not wait indefinitely for an outcome", "no fresh unrelated dispatch"]
+    }
+  ]
+}

package/plugins/delegation-layer/skills/agent-integration/evals/routing.json

@@ -0,0 +1,155 @@
+{
+  "version": 1,
+  "cases": [
+    {
+      "name": "codex-review",
+      "prompt": "Ask Codex to review pricing.py for correctness. Return the finding without editing files.",
+      "external": true,
+      "provider": "codex:exec",
+      "split": "development",
+      "native_alternative_for": "codex"
+    },
+    {
+      "name": "agy-opinion",
+      "prompt": "Get Antigravity\u2019s opinion on the discount calculation in pricing.py. Do not edit files.",
+      "external": true,
+      "provider": "antigravity:print",
+      "split": "development"
+    },
+    {
+      "name": "claude-investigate",
+      "prompt": "Have Claude investigate why discounted_price(200, 10) returns the wrong value. Do not change files.",
+      "external": true,
+      "provider": "claude:print",
+      "split": "development",
+      "native_alternative_for": "claude"
+    },
+    {
+      "name": "external-write",
+      "prompt": "Ask Codex to fix pricing.py so discounts are percentages. Authorize edits only in this workspace and verify 200 with 10 percent gives 180.",
+      "external": true,
+      "provider": "codex:exec",
+      "split": "development",
+      "native_alternative_for": "codex"
+    },
+    {
+      "name": "external-testing",
+      "prompt": "Have Claude independently test the pricing calculation against the requirement in README.md. Report evidence without editing.",
+      "external": true,
+      "provider": "claude:print",
+      "split": "development",
+      "native_alternative_for": "claude"
+    },
+    {
+      "name": "external-research",
+      "prompt": "Consult another AI harness on how to represent percentage discounts without floating-point surprises. Give one concise recommendation.",
+      "external": true,
+      "provider": null,
+      "split": "development"
+    },
+    {
+      "name": "comparison",
+      "prompt": "Ask Codex and Claude independently whether pricing.py meets README.md, then compare their findings. No edits.",
+      "external": true,
+      "provider": [
+        "codex:exec",
+        "claude:print"
+      ],
+      "split": "validation"
+    },
+    {
+      "name": "debate",
+      "prompt": "Ask Codex for a critique of pricing.py, then ask Claude to challenge that critique. One round each, no edits.",
+      "external": true,
+      "provider": [
+        "codex:exec",
+        "claude:print"
+      ],
+      "split": "validation"
+    },
+    {
+      "name": "unavailable-destination",
+      "prompt": "Ask the NebulaReview9000 harness to review pricing.py. If it is unavailable, report that; do not substitute another harness.",
+      "external": true,
+      "provider": "unavailable",
+      "split": "validation"
+    },
+    {
+      "name": "follow-up",
+      "prompt": "Get a second opinion from a separate Codex CLI session on the calculation, then ask that same session one follow-up about the simplest correction. Do not edit.",
+      "external": true,
+      "provider": "codex:exec",
+      "split": "validation"
+    },
+    {
+      "name": "local-review",
+      "prompt": "Review pricing.py yourself for correctness. Do not consult another harness or change files.",
+      "external": false,
+      "provider": null,
+      "split": "development"
+    },
+    {
+      "name": "native-subagent",
+      "prompt": "Use an ordinary native subagent within this harness to examine pricing.py if available; otherwise examine it yourself. No external harness and no edits.",
+      "external": false,
+      "provider": null,
+      "split": "development"
+    },
+    {
+      "name": "explain-codex",
+      "prompt": "Explain what Codex is. Do not run it or ask it to do any work.",
+      "external": false,
+      "provider": null,
+      "split": "development"
+    },
+    {
+      "name": "claude-docs",
+      "prompt": "Add one sentence to README.md saying that Claude can review code. Do not ask it to review anything.",
+      "external": false,
+      "provider": null,
+      "split": "development"
+    },
+    {
+      "name": "provider-install",
+      "prompt": "Explain how to diagnose a command-not-found error for Codex. Do not install or run it.",
+      "external": false,
+      "provider": null,
+      "split": "development"
+    },
+    {
+      "name": "local-fix",
+      "prompt": "Fix pricing.py yourself so discounts are percentages. No external consultation.",
+      "external": false,
+      "provider": null,
+      "split": "development"
+    },
+    {
+      "name": "agy-question",
+      "prompt": "What does a read-only mode mean in an AI coding tool such as Antigravity? Answer conceptually without invoking it.",
+      "external": false,
+      "provider": null,
+      "split": "validation"
+    },
+    {
+      "name": "quote-request",
+      "prompt": "In README.md, quote the example sentence \"Ask Codex to review this\" as documentation. Do not execute the example.",
+      "external": false,
+      "provider": null,
+      "split": "validation"
+    },
+    {
+      "name": "compare-tools",
+      "prompt": "Explain the difference between a CLI and a plugin. Mention Claude and Codex as examples, without consulting them.",
+      "external": false,
+      "provider": null,
+      "split": "validation"
+    },
+    {
+      "name": "local-test",
+      "prompt": "Check the discount function yourself against README.md and report the result. No other agents.",
+      "external": false,
+      "provider": null,
+      "split": "validation"
+    }
+  ]
+}

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

@@ -0,0 +1,14 @@
+# JSON decision sketch
+
+```sh
+delegate --root "$STATE_ROOT" status "$TASK_ID" --json
+delegate --root "$STATE_ROOT" 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`.

package/plugins/delegation-layer/skills/agent-integration/examples/read-only-task.md

@@ -0,0 +1,12 @@
+# Read-only task
+
+```sh
+STATE_ROOT="${DELEGATE_ROOT:-$HOME/delegation-state}"
+BRIEF="$(mktemp)"
+printf '%s\n' 'Inspect the workspace and summarize the current test failures. Do not edit files.' >"$BRIEF"
+delegate --root "$STATE_ROOT" dispatch --auto \
+  --brief "$BRIEF" --cwd "$PWD" --permission read-only --budget 15m --json
+```
+
+Save the returned `task_id`, then use `status` and `collect` with the same
+state root.

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

@@ -0,0 +1,14 @@
+# Authorized workspace write task
+
+```sh
+STATE_ROOT="${DELEGATE_ROOT:-$HOME/delegation-state}"
+delegate --root "$STATE_ROOT" dispatch --auto \
+  --brief "$PWD/delegated-task.md" --cwd "$PWD" \
+  --permission workspace-write --budget 30m --json
+```
+
+Use `workspace-write` only when the caller authorized edits in the selected
+workspace. Delegate requests unattended native approval for commands and edits.
+The provider owns its tools and access restrictions; the workspace is not an
+independent sandbox. Save the returned task ID, then use the same state root
+with `status` and `collect`; do not run the provider directly after a denial.

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

@@ -0,0 +1,80 @@
+# Command reference
+
+All paths passed to `--root`, `--cwd`, and `--brief` must be absolute. Add
+`--json` to commands that return an agent-consumable response.
+
+| 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 continue --task TASK ... --json` | Create an exact-session successor | Yes, at most once for the successor |
+| `delegate logs TASK --json` | Return validated output descriptors | No |
+| `delegate cancel TASK --json` | Record one explicit stop request | Stops, does not relaunch |
+
+The bundled supervisor is managed by the released CLI under the state root.
+Collection remains observational. Provider authentication remains the
+provider’s own responsibility and is never performed by this skill.
+
+Dispatch flags:
+
+- `--brief FILE`: bounded task instructions;
+- `--cwd ABS`: workspace for the delegated turn;
+- `--permission read-only|workspace-write`: read-only investigation or authorized unattended write execution, including commands (not independent containment);
+- `--budget DURATION`: finite turn budget;
+- `--auto`: let the CLI select a ready provider;
+- `--provider ID`: preserve the caller’s named harness or provider, resolved through the catalog;
+- `--model MODEL` and `--effort VALUE`: optional provider-advertised choices;
+  Codex maps effort to TOML `model_reasoning_effort`, while Claude and AGY
+  pass native effort flags; Pi maps effort to `--thinking`; OpenCode maps it to
+  `--variant`; `default` is omitted;
+- `--native-timeout DURATION`: optional provider-native timeout where advertised.
+
+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`,
+`0`, `2`, `2`, and `1` respectively. `complete` describes model enumeration.
+Top-level or per-model `efforts: null` means unknown, while `[]` means no
+choices were explicitly reported. Discovery is advisory and never an admission
+allowlist; defaults remain valid when it is not run.
+
+Continuation flags:
+
+- `--task TASK`: predecessor task ID;
+- `--brief FILE`: optional new follow-up instruction;
+- `--budget DURATION`, `--model MODEL`, and `--effort VALUE`: optional overrides.
+
+## Choosing models and effort
+
+If the caller needs an explicit model or effort, use the implemented native
+discovery command for that provider:
+
+```sh
+delegate models --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
+```
+
+Omit `--cwd` to use the current directory. Run discovery only when the caller
+needs a non-default choice; provider defaults are valid. The command uses the
+state-rooted supervisor and a bounded `model-discovery-v1` five-minute native
+inspection to allow first-run provider model/cache initialization. It creates
+inspection evidence without admitting a provider task, and may contact the
+provider CLI. It is advisory and never an admission allowlist. Do not reject a
+requested value merely because discovery did not list it, and do not infer
+per-model effort support from the harness-wide list. If a selected model has
+`efforts: null` or `efforts: []`, omit `--effort` unless the caller explicitly
+requested it; do not invent model aliases or combine options by guessing.
+
+The response includes `schema_version`, `command: "models"`, `provider`,
+`observed_at`, `status`, `reason_code`, `complete`, `source`, nullable
+`efforts`, and model rows with exact `id` values plus optional `name`, nullable
+`efforts`, and optional `default_effort`. `complete` describes model
+enumeration, not effort metadata. `null` means effort metadata is unknown;
+`[]` means the provider explicitly reported no choices. Discovery exits `0`
+for `available` or `partial`, `2` for `blocked` or `unavailable`, and `1` for
+`failed`. Preserve a blocked or unavailable discovery result as unresolved;
+defaults remain allowed.

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

@@ -0,0 +1,49 @@
+# Continuation and timeout recovery
+
+Each task is one provider turn. A time limit ends that turn; it does not grant
+permission to launch the same task again. The durable task record keeps the
+exact provider session identity and the stop evidence.
+
+When `status` or `collect` reports a timed-out turn with:
+
+```json
+"continuation": {
+  "resumable": true,
+  "mode": "native",
+  "predecessor_task_id": "..."
+}
+```
+
+run:
+
+```sh
+delegate --root "$STATE_ROOT" continue \
+  --task PREDECESSOR_TASK_ID \
+  --brief FOLLOW_UP_BRIEF \
+  --budget 30m \
+  --json
+```
+
+A timed-out turn can have `publication: "unknown"` and no `outcome` while
+`continuation.resumable` is true. Use that continuation decision; do not wait
+indefinitely for a publication that the interrupted turn cannot complete.
+
+The follow-up brief is optional. If it is omitted, Delegation Layer reuses the
+validated predecessor brief. A successful continuation returns a new task ID
+and links it to the predecessor. Observe and collect the new ID separately. Always retain the original state
+root, even if a returned command hint omits it. Permission is inherited; do not
+add `--permission` to `continue`. Apply the dispatch `task_record` error rules
+in [result handling](result-handling.md) before retrying or observing.
+
+`mode` describes the provider contract:
+
+- `native` uses the provider’s exact persisted conversation/session ID;
+- `checkpoint` requires a provider checkpoint and is resumable only when the
+  response explicitly says so;
+- `unsupported` cannot be continued safely.
+
+Do not use a guessed session ID, a provider-specific resume command, or a new
+independent dispatch to recover a timeout. The CLI accepts either a validated
+terminal outcome or durable supervisor-ended budget-stop evidence for the
+session handoff; without one of those proofs it refuses continuation. Inspect
+the predecessor again rather than bypassing that boundary.