delegation-layer 0.1.4 → 0.1.6

package/README.md

@@ -20,6 +20,8 @@ already use instead of replacing them.
   and time budget.
 - **Recoverable results** — a later `collect` call can read a finished task
   without launching the provider again.
+- **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.
 - **Native authentication** — provider login stays with the provider CLI; task
@@ -65,7 +67,7 @@ npx --yes delegation-layer install \
 ```
 
 The skill installer only installs guidance for your agent. It does not install
-the CLI, change provider logins, or configure a supervisor.
+the CLI, change provider logins, or run a task.
 
 ### Install the CLI
 
@@ -85,8 +87,9 @@ pnpm dlx delegation-layer install-cli
 bunx --bun delegation-layer install-cli
 ```
 
-The release installer verifies checksums and installs `delegate` and
-`delegate-run` into `$HOME/.local/bin` by default. Set
+The release installer verifies checksums and installs `delegate`,
+`delegate-run`, `pueue`, and `pueued` into `$HOME/.local/bin` by default. The
+CLI uses the bundled supervisor automatically. Set
 `DELEGATION_LAYER_INSTALL_DIR` to use another directory.
 
 Check the installation:
@@ -102,14 +105,17 @@ Normal users do not need Go or Node after choosing an installation method.
 Dispatching a task requires:
 
 - a released Delegation Layer CLI;
-- Pueue 4.0.4 with a private, running `pueued` daemon;
-- a signed-in supported provider CLI such as `agy`, `codex`, `claude`, `pi`,
-  or `opencode`;
+- a compatible provider CLI with an available native login;
+- a supported provider CLI such as `agy`, `codex`, `claude`, `pi`, or `opencode`;
 - Darwin or Linux on amd64 or arm64 for the supplied release builds.
 
-Go is only needed for source builds and contributor work. Node.js 18 or newer
-is needed for the npm-based installers; it is not a runtime requirement for the
-released Go CLI. Provider authentication remains native to each provider.
+The release contains the supervisor client and daemon and starts a private
+instance under the state root, recovering it when a control command finds it
+stopped. An explicit `--pueue-config` or
+`DELEGATE_PUEUE_CONFIG` can still select an existing compatible supervisor for
+advanced integrations. Node.js 18 or newer is needed only for the npm-based
+installers; it is not a runtime requirement for the released Go CLI. Provider
+authentication remains native to each provider.
 
 ## Try one bounded task
 
@@ -119,8 +125,8 @@ Create a brief and a workspace outside the private state root:
 mkdir -p "$HOME/delegation-workspace"
 printf '%s\n' 'Inspect the repository and summarize the current build status.' > brief.txt
 
-delegate --pueue-config /absolute/path/to/pueue.yml dispatch \
-  --provider codex:exec \
+delegate --root "$HOME/delegation-state" dispatch \
+  --auto \
   --brief "$PWD/brief.txt" \
   --cwd "$HOME/delegation-workspace" \
   --permission read-only \
@@ -138,8 +144,21 @@ delegate 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. Dispatch still performs the host-specific runtime probe;
-catalog discovery alone does not prove authentication or supervisor readiness.
+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.
+
+If a task reports `status: "timed_out"` and
+`continuation.resumable: true`, continue the exact session:
+
+```sh
+delegate --root "$HOME/delegation-state" continue \
+  --task TASK_ID --brief "$HOME/follow-up.txt" --budget 30m --json
+```
+
+The successor receives a new task ID and is observed with the same `status` and
+`collect` commands.
 
 ## Documentation
 

package/install.sh

@@ -65,12 +65,12 @@ fi
 
 tar -xzf "$ARCHIVE" -C "$TEMP_DIR" || fail "could not extract $ARCHIVE"
 mkdir -p "$INSTALL_DIR"
-for binary in delegate delegate-run; do
+for binary in delegate delegate-run pueue pueued; do
   [ -f "$TEMP_DIR/$binary" ] || fail "release archive does not contain $binary"
   install -m 0755 "$TEMP_DIR/$binary" "$INSTALL_DIR/$binary"
 done
 
-printf 'Installed delegate and delegate-run %s in %s\n' "$VERSION" "$INSTALL_DIR"
+printf 'Installed delegation-layer CLI and bundled supervisor %s in %s\n' "$VERSION" "$INSTALL_DIR"
 case ":${PATH:-}:" in
   *:"$INSTALL_DIR":*) ;;
   *) printf 'Add %s to PATH if it is not already there.\n' "$INSTALL_DIR" ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delegation-layer",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Multi-provider AI agent delegation CLI and Agent Skill for running bounded coding tasks across provider CLIs.",
   "keywords": [
     "ai-agents",
@@ -24,7 +24,7 @@
     "LICENSE",
     "docs/assets/delegation-layer-hero.jpg",
     "install.sh",
-    "skills/agent-integration/SKILL.md",
+    "skills/agent-integration/",
     "scripts/install-agent-integration.mjs",
     "scripts/install-cli.mjs"
   ],

package/scripts/install-agent-integration.mjs

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
 import { accessSync, constants } from "node:fs";
-import { copyFile, lstat, mkdir, readFile } from "node:fs/promises";
+import { copyFile, lstat, mkdir, readdir, readFile } from "node:fs/promises";
 import { emitKeypressEvents } from "node:readline";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const sourcePath = join(packageRoot, "skills", "agent-integration", "SKILL.md");
+const sourceDirectory = join(packageRoot, "skills", "agent-integration");
 const harnesses = [
   {
     name: "universal",
@@ -215,6 +215,93 @@ async function existingPath(path) {
   }
 }
 
+async function assertNoSymlinkComponents(path) {
+  let current = resolve(path);
+  while (true) {
+    const stat = await existingPath(current);
+    if (stat?.isSymbolicLink()) {
+      throw new Error(`skill destination must not contain symlink components: ${current}`);
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return;
+    }
+    current = parent;
+  }
+}
+
+async function skillFiles(directory, relative = "") {
+  const entries = await readdir(join(directory, relative), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const child = join(relative, entry.name);
+    const path = join(directory, child);
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`skill source or destination must not contain symlinks: ${path}`);
+    }
+    if (stat.isDirectory()) {
+      files.push(...(await skillFiles(directory, child)));
+      continue;
+    }
+    if (!stat.isFile()) {
+      throw new Error(`skill entry must be a regular file: ${path}`);
+    }
+    files.push(child);
+  }
+  return files.sort();
+}
+
+async function skillTreeMatches(target, files) {
+  for (const relative of files) {
+    const destination = join(target, relative);
+    await assertNoSymlinkComponents(destination);
+    const stat = await existingPath(destination);
+    if (!stat || !stat.isFile() || stat.isSymbolicLink()) {
+      return false;
+    }
+    const [source, existing] = await Promise.all([
+      readFile(join(sourceDirectory, relative)),
+      readFile(destination),
+    ]);
+    if (!source.equals(existing)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function skillTreeHasExistingFiles(target, files) {
+  for (const relative of files) {
+    const destination = join(target, relative);
+    await assertNoSymlinkComponents(destination);
+    if (await existingPath(destination)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function copySkillTree(target, files, force) {
+  for (const relative of files) {
+    const destination = join(target, relative);
+    const parent = dirname(destination);
+    await assertNoSymlinkComponents(destination);
+    await mkdir(parent, { recursive: true });
+    const stat = await existingPath(destination);
+    if (stat?.isSymbolicLink()) {
+      throw new Error(`existing skill file must not be a symlink: ${destination}`);
+    }
+    if (stat && !stat.isFile()) {
+      throw new Error(`existing skill entry is not a regular file: ${destination}`);
+    }
+    if (stat && !force) {
+      throw new Error(`skill files already exist; use --force to replace them: ${target}`);
+    }
+    await copyFile(join(sourceDirectory, relative), destination);
+  }
+}
+
 function executableOnPath(command) {
   const pathEntries = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
   const candidates = process.platform === "win32" ? [command, `${command}.exe`, `${command}.cmd`] : [command];
@@ -465,6 +552,7 @@ function targetFor(harness, scope, cwd, home) {
 }
 
 async function install({ force, target }) {
+  await assertNoSymlinkComponents(target);
   const targetStat = await existingPath(target);
   if (targetStat?.isSymbolicLink()) {
     throw new Error(`target directory must not be a symlink: ${target}`);
@@ -473,33 +561,31 @@ async function install({ force, target }) {
     throw new Error(`target must be a directory: ${target}`);
   }
 
+  const files = await skillFiles(sourceDirectory);
   await mkdir(target, { recursive: true });
 
-  const destination = join(target, "SKILL.md");
-  const destinationStat = await existingPath(destination);
-  if (destinationStat?.isSymbolicLink()) {
-    throw new Error(`existing SKILL.md must not be a symlink: ${destination}`);
+  if (!force && (await skillTreeMatches(target, files))) {
+    console.log(`Skill already installed: ${join(target, "SKILL.md")}`);
+    return;
   }
-  if (destinationStat && !destinationStat.isFile()) {
-    throw new Error(`existing SKILL.md is not a regular file: ${destination}`);
+  if (!force && (await skillTreeHasExistingFiles(target, files))) {
+    throw new Error(`skill files already exist; use --force to replace them: ${target}`);
   }
 
-  if (destinationStat && !force) {
-    const [source, existing] = await Promise.all([
-      readFile(sourcePath),
-      readFile(destination),
-    ]);
-    if (source.equals(existing)) {
-      console.log(`Skill already installed: ${destination}`);
-      return;
-    }
-    throw new Error(`SKILL.md already exists; use --force to replace it: ${destination}`);
-  }
+  await copySkillTree(target, files, force);
+  console.log(`Installed agent integration skill: ${join(target, "SKILL.md")}`);
+}
 
-  await copyFile(sourcePath, destination);
-  console.log(`Installed agent integration skill: ${destination}`);
+async function validateSourceTree() {
+  const files = await skillFiles(sourceDirectory);
+  if (!files.includes("SKILL.md")) {
+    throw new Error(`skill package is missing SKILL.md: ${sourceDirectory}`);
+  }
+  return files;
 }
 
+await validateSourceTree();
+
 const argumentsList = process.argv.slice(2);
 if (argumentsList[0] === "install-cli") {
   try {

package/skills/agent-integration/SKILL.md

@@ -1,182 +1,200 @@
 ---
 name: agent-integration
-description: Use Delegation Layer from a provider-agnostic agent workflow, including capability discovery, bounded dispatch, terminal collection, and live authentication handling.
+description: Use the installed Delegation Layer CLI to select a ready provider, run one bounded agent turn, collect durable JSON evidence, and continue a timed out session safely.
 ---
 
-# Agent integration
+# Delegation Layer
+
+Use this skill when a task should be performed by another coding agent through
+the local `delegate` CLI. The CLI is the only integration surface. Do not call,
+inspect, authenticate, or install a provider CLI directly.
+
+## Rules
+
+1. Check whether `delegate` is already installed. If it is missing, report the
+   missing prerequisite and stop. This skill never installs or repairs the CLI.
+2. Use `dispatch --auto` unless the user explicitly selected a provider ID.
+   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, a finite
+   permission mode, and a finite budget.
+4. Use `--json` and save the returned `task_id`. Read `admission`, `liveness`,
+   `publication`, `status`, `outcome`, `continuation`, and `error` as separate
+   fields.
+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.
+
+## Operating procedure
+
+### 1. Verify the control CLI
+
+Run a quick local check:
 
-This skill is self-contained as an operating guide. It gives an agent enough
-information to prepare a safe run, choose a provider from observed
-capabilities, and collect a terminal result when the host exposes the
-Delegation Layer CLI. It applies to every provider profile and does not encode
-provider names, release versions, or native CLI syntax.
+```sh
+command -v delegate && delegate --version
+```
 
-## Preconditions
+If this fails, tell the caller that Delegation Layer is not installed and
+stop. Do not substitute a provider command.
 
-The host is responsible for installing and configuring the CLI and supervisor.
-This skill must not install, build, upgrade, or repair either one. It may check
-whether `delegate` is available, use a configured private supervisor
-configuration and socket, and create separate task and state directories that
-it is authorized to use.
-Authentication is a separate live gate; do not invent a provider-specific
-login check or classify a missing login as static incompatibility.
+### 2. Discover only when useful
 
-Keep the supervisor configuration, Delegation Layer state root, and task
-workspace as separate canonical paths. Do not put credentials in a brief, task
-option, environment value recorded by the task, or agent-visible output.
+For the normal path, use automatic selection directly. If you need to explain
+what the installed build knows, run:
 
-## Start safely
+```sh
+delegate providers --json
+```
 
-First check that the already-installed CLI is available, then discover compiled
-profiles:
+This is a catalog, not proof that a provider is installed, authenticated, or
+ready. If the caller named one provider ID and wants a side-effect-free check,
+run:
 
 ```sh
-command -v delegate
-delegate help
-delegate providers --json
+delegate preflight --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
 ```
 
-If `command -v delegate` fails, stop and report that the host prerequisite is
-missing. Do not install or build the CLI from this skill.
+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.
 
-`providers --json` is static discovery. It lists provider IDs, supported
-permission modes and options, and the help arguments and flags required by the
-compiled adapters. It does not inspect the host, authenticate a provider, or
-prove that a provider is launchable.
+### 3. Prepare separate paths and a finite brief
 
-Choose a listed `PROFILE`, then inspect its provider-neutral contract:
+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:
 
 ```sh
-delegate capabilities --provider PROFILE --json
+STATE_ROOT="${DELEGATE_ROOT:-$HOME/.local/state/delegation-layer}"
+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
 ```
 
-This command is side-effect-free. It does not create state, contact Pueue, or
-launch a provider. A successful catalog response has
-`status: "unknown"`, `verification: "catalog"`, and
-`live_acceptance.status: "not_run"`. Unknown here means that dispatch has not
-run the host probe yet; it is neither a compatibility failure nor live proof.
+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.
+
+### 4. Dispatch one bounded turn
 
-Choose a listed `PROFILE`, ensure its provider executable is available to the
-dispatch environment, and prepare a finite brief and two separate absolute
-directories. Then dispatch one bounded task:
+Use automatic selection unless the user explicitly supplied `PROVIDER_ID`:
 
 ```sh
-mkdir -p "${HOME}/delegation-workspace" "${HOME}/delegation-state"
-printf '%s\n' 'Inspect the workspace and return a short summary.' > "${HOME}/delegation-brief.txt"
-
-delegate --root "${HOME}/delegation-state" \
-  --pueue-config /absolute/path/to/private-pueue.yml \
-  dispatch \
-  --provider PROFILE \
-  --brief "${HOME}/delegation-brief.txt" \
-  --cwd "${HOME}/delegation-workspace" \
+delegate --root "$STATE_ROOT" dispatch --auto \
+  --brief "$BRIEF" \
+  --cwd "$WORKSPACE" \
   --permission read-only \
   --budget 30m \
   --json
 ```
 
-Use the host's configured private supervisor path (or its
-`DELEGATE_PUEUE_CONFIG` equivalent); the placeholder above is not a path to
-create. If the supervisor or provider executable is unavailable, stop on the
-CLI's structured error. For live acceptance, an unavailable authentication
-prerequisite is `blocked`; preserve that evidence and never relabel it as
-incompatible or passed.
+For an authorized code change, use `--permission workspace-write`. Keep the
+budget finite. A successful dispatch means the request was durably admitted;
+it does not mean the delegated work finished.
 
-Save the returned `task_id`. Admission records one immutable request and at
-most one provider launch attempt; the command does not wait for completion.
-Observe and collect with that exact ID:
+Save the exact `task_id` from the JSON response. If dispatch returns an error,
+use its `status`, `capability`, and `error` fields to report whether the request
+was invalid, unsupported, blocked by authentication, or operationally
+uncertain. Do not silently try another provider after a task has been
+admitted.
+
+### 5. Observe and collect
+
+Use the same state root and task ID:
 
 ```sh
-delegate --root "${HOME}/delegation-state" status TASK_ID --json
-delegate --root "${HOME}/delegation-state" collect TASK_ID --watch 5s --json
+delegate --root "$STATE_ROOT" status TASK_ID --json
+delegate --root "$STATE_ROOT" collect TASK_ID --watch 5s --json
 ```
 
-Repeat `collect` while the task is pending. Collection is observational: it
-may wait for the bounded watch interval and clean up a validated reservation,
-but it never launches, retries, or resumes provider work. A continuation is a
-new task with an exact predecessor ID when the selected profile advertises
-continuation support.
+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.
 
-## Read the JSON contract
+### 6. Continue a timed out turn
 
-The capability response has this stable shape. The two arrays are
-profile-specific and can be non-empty; empty arrays below only keep the example
-provider-agnostic:
+When `status` or `collect` returns `status: "timed_out"`, inspect the nested
+continuation object:
 
 ```json
 {
-  "schema_version": 1,
-  "command": "capabilities",
-  "capability": {
-    "contract": "runtime-capability-v1",
-    "provider": "PROFILE",
-    "status": "unknown",
-    "verification": "catalog",
-    "help_args": [],
-    "required_flags": [],
-    "reason_code": "runtime_probe_not_run",
-    "live_acceptance": {
-      "status": "not_run",
-      "authentication": "unknown",
-      "reason_code": "runtime_probe_not_run"
-    }
+  "status": "timed_out",
+  "continuation": {
+    "resumable": true,
+    "mode": "native",
+    "predecessor_task_id": "TASK_ID",
+    "continue_command": "delegate continue --task TASK_ID --json"
   }
 }
 ```
 
-Interpret the fields as follows:
-
-- `status=unknown` with `verification=catalog` is a declaration from the
-  compiled catalog.
-- `status=ready` with `verification=runtime` appears in a dispatch response
-  only after the supervised probe observed the required behavior and exact
-  executable identity for that admission boundary.
-- `status=unsupported` is a machine-readable refusal. Use `reason_code` and
-  the bounded error to explain it; do not try another profile without a new
-  explicit selection.
-- `version` is diagnostic observation. Accept any valid nonempty trimmed UTF-8
-  version text. Never use a release allowlist, semantic-version comparison, or
-  web lookup as a compatibility decision. Required flags, executable identity,
-  and provider behavior decide compatibility. An unusually large version may
-  be omitted from the bounded projection.
-- `live_acceptance` is separate from compatibility. `not_run` does not claim a
-  live test; `passed` requires authenticated provider evidence; `blocked` means
-  authentication or another prerequisite was unavailable and is neutral. A
-  blocked result must never be reported as a pass or as incompatible behavior.
-
-Dispatch JSON contains the same `capability` projection plus separate task
-`admission`, `liveness`, and `publication` fields. Read those fields
-independently. Trust a terminal `outcome` only after it has been returned by
-the validated collection path and its payload and sealed evidence descriptors
-match the task records.
-
-## Integration acceptance contract
-
-Apply these criteria to every provider and every agent integration:
-
-- required behavior is verified at the runtime boundary;
-- arbitrary valid provider version text remains acceptable;
-- missing flags, executable identity drift, malformed facts, and timeouts fail
-  closed;
-- authentication is represented separately from compatibility;
-- missing authentication is `blocked`, never a passing skip;
-- admission is at most once and collection is observational;
-- terminal results come from durable validated evidence; and
-- JSON output is bounded, deterministic for observational commands, versioned,
-  and free of credentials.
-
-Do not expose credentials, tokens, private raw provider output, or unrestricted
-diagnostics in prompts, tool results, receipts, or task metadata. After an
-uncertain admission or lost response, inspect the original task with
-`status`/`collect`; do not relaunch it. Stop and report the durable state when
-the task cannot be resolved from validated evidence.
-
-## Completion record
-
-An integration is complete when it can provide:
-
-- the selected profile and original task ID;
-- the bounded capability and dispatch JSON responses;
-- the terminal committed or rejected outcome and validated evidence
-  descriptors; and
-- a sanitized live-acceptance receipt marked `passed`, `failed`, or `blocked`.
+If `resumable` is true, create the linked successor through the public
+continuation command. Supply a new follow-up brief when the next turn needs a
+new instruction:
+
+```sh
+delegate --root "$STATE_ROOT" continue \
+  --task TASK_ID \
+  --brief "$FOLLOW_UP_BRIEF" \
+  --budget 30m \
+  --json
+```
+
+The command preserves the exact provider session and creates a new task ID.
+Observe and collect the successor by repeating step 5. If `resumable` is
+false, report the reason and stop; a fresh dispatch would lose the original
+conversation and is not an equivalent recovery.
+
+## JSON decisions
+
+The capability projection uses the stable `runtime-capability-v1` contract.
+Catalog responses have `verification: "catalog"` and `status: "unknown"`.
+Preflight responses have `verification: "preflight"` and describe static
+readiness. A dispatch response can report `verification: "runtime"` only after
+the supervised runtime probe has observed the required behavior and executable
+identity.
+
+Versions and help text are observations. Accept any valid nonempty version
+reported by the CLI; never apply a semantic-version allowlist or web lookup.
+The adapter’s required flags and runtime behavior decide compatibility.
+
+Authentication is a separate live gate. `live_acceptance.status` values are
+`not_run`, `passed`, or `blocked`; a blocked authentication prerequisite is
+neutral evidence and must not be relabeled.
+
+The task response separates:
+
+- `admission`: whether the request was accepted by the durable boundary;
+- `liveness`: the observed supervisor state;
+- `publication`: whether validated evidence was committed or rejected;
+- `outcome`: the terminal authority, when available;
+- `continuation`: whether the exact session can make a linked successor; and
+- `error`: bounded operational diagnostics.
+
+See [references/command-reference.md](references/command-reference.md) for
+the command matrix, [references/result-handling.md](references/result-handling.md)
+for decision rules, and [references/continuation.md](references/continuation.md)
+for timeout recovery. The examples and machine-readable checks in `examples/`
+and `evals/` are part of this skill package.
+
+## 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/skills/agent-integration/evals/evals.json

@@ -0,0 +1,31 @@
+{
+  "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": "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"]
+    }
+  ]
+}

package/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/skills/agent-integration/examples/read-only-task.md

@@ -0,0 +1,12 @@
+# Read-only task
+
+```sh
+STATE_ROOT="${DELEGATE_ROOT:-$HOME/.local/state/delegation-layer}"
+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/skills/agent-integration/examples/workspace-write-task.md

@@ -0,0 +1,12 @@
+# Authorized workspace write task
+
+```sh
+STATE_ROOT="${DELEGATE_ROOT:-$HOME/.local/state/delegation-layer}"
+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. The CLI still owns provider selection, policy, admission, and
+publication.

package/skills/agent-integration/references/command-reference.md

@@ -0,0 +1,38 @@
+# 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 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`: requested containment;
+- `--budget DURATION`: finite turn budget;
+- `--auto`: let the CLI select a ready provider;
+- `--provider ID`: use only when the caller explicitly selected an ID;
+- `--model MODEL` and `--effort VALUE`: optional provider-advertised choices;
+- `--native-timeout DURATION`: optional provider-native timeout where advertised.
+
+Continuation flags:
+
+- `--task TASK`: predecessor task ID;
+- `--brief FILE`: optional new follow-up instruction;
+- `--budget DURATION`, `--model MODEL`, and `--effort VALUE`: optional overrides.

package/skills/agent-integration/references/continuation.md

@@ -0,0 +1,42 @@
+# 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
+```
+
+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.
+
+`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.

package/skills/agent-integration/references/result-handling.md

@@ -0,0 +1,25 @@
+# Result handling
+
+Use the response fields independently. A successful control command is not
+the same as a successful provider result.
+
+1. Save `task_id` immediately after dispatch or continue.
+2. If `admission` is not admitted, report the bounded `error` and do not claim
+   that provider work ran.
+3. If `liveness` is queued or running, call `status` or `collect` again with a
+   finite watch interval.
+4. If `publication` is committed and `outcome.verdict` is committed, return
+   the result and its payload/evidence descriptors.
+5. If `outcome.verdict` is rejected, report a terminal rejected result with its
+   refusal and evidence. Do not retry automatically.
+6. If `status` is `timed_out`, follow the continuation procedure. A timeout is
+   recoverable only when `continuation.resumable` is true.
+7. If authentication is `blocked`, preserve that neutral state and tell the
+   caller what prerequisite is unavailable without inventing a login command.
+8. If a command reports an operational uncertainty, inspect the original task
+   with `status` and `collect` before considering any action. Never relaunch an
+   uncertain task by guessing.
+
+Exit codes are bounded control signals: `0` is a completed command, `1` is an
+operational error, `2` is an invalid or unsupported request, `3` is a pending
+collection watch, and `4` is a validated rejected outcome.