delegation-layer 0.1.16 → 0.1.17

package/README.md

@@ -31,14 +31,41 @@ already use instead of replacing them.
 
 ## How it works
 
-1. Install the Agent Skill so your harness knows how to use Delegation Layer.
+1. Install the plugin so the skill and self-contained CLI are available together.
 2. The lead agent discovers the available provider capabilities.
 3. Delegation Layer admits one bounded provider turn through the supervisor.
 4. The lead agent collects the sealed result and evidence.
 
 ## Install
 
-### Install the Agent Skill
+### Recommended for Codex and Claude Code
+
+Install the plugin from this repository. It installs the provider-neutral skill
+and runs a trusted session-start bootstrap that reuses the checksum-verified
+Delegation Layer release installer when `delegate` is missing. The bootstrap
+installs the CLI and its bundled supervisor; it does not install provider CLIs,
+change provider authentication, or change provider configuration.
+
+For Codex:
+
+```sh
+codex plugin marketplace add hishamkaram/delegation-layer
+codex plugin add delegation-layer@delegation-layer
+```
+
+For Claude Code:
+
+```sh
+claude plugin marketplace add hishamkaram/delegation-layer
+claude plugin install delegation-layer@delegation-layer
+```
+
+Start a new harness session after installation. Plugin hooks require the
+harness trust review before they run. If the bootstrap reports that the
+install directory is not on `PATH`, add the reported directory to `PATH` and
+start a new session; the skill never falls back to a provider-native CLI.
+
+### Install the Agent Skill only
 
 The standard Agent Skills installer works across popular coding agents. From
 the project where you want the skill available, run:
@@ -68,8 +95,9 @@ npx --yes delegation-layer install \
   --yes
 ```
 
-The skill installer only installs guidance for your agent. It does not install
-the CLI, change provider logins, or run a task.
+This path installs guidance only. It does not install the CLI, change provider
+logins, or run a task. Use the plugin path above when you want the skill and
+CLI bootstrap together.
 
 ### Install the CLI
 

package/install.sh

@@ -10,13 +10,18 @@ fail() {
   exit 1
 }
 
-for command_name in awk curl grep install mktemp tar uname; do
+for command_name in awk curl grep install mkdir mktemp mv rm tar uname; do
   command -v "$command_name" >/dev/null 2>&1 || fail "required command not found: $command_name"
 done
 
+case "$INSTALL_DIR" in
+  /*) ;;
+  *) fail "install directory must be an absolute path: $INSTALL_DIR" ;;
+esac
+
 if [ "$REQUESTED_VERSION" = "latest" ]; then
   latest_url="https://github.com/${REPOSITORY}/releases/latest"
-  resolved_url="$(curl -fsSL -o /dev/null -w '%{url_effective}' "$latest_url")" || fail "could not resolve the latest release"
+  resolved_url="$(curl -fsSL --connect-timeout 5 --max-time 20 --retry 2 --retry-delay 1 --retry-max-time 30 -o /dev/null -w '%{url_effective}' "$latest_url")" || fail "could not resolve the latest release"
   VERSION="${resolved_url##*/}"
 else
   VERSION="$REQUESTED_VERSION"
@@ -44,11 +49,21 @@ esac
 ARCHIVE="delegation-layer_${VERSION#v}_${OS}_${ARCH}.tar.gz"
 RELEASE_URL="https://github.com/${REPOSITORY}/releases/download/${VERSION}"
 TEMP_DIR="$(mktemp -d)"
-trap 'rm -rf "$TEMP_DIR"' EXIT
+STAGE_DIR=""
 
-curl -fsSL --retry 3 -o "$TEMP_DIR/$ARCHIVE" "$RELEASE_URL/$ARCHIVE" || \
+cleanup() {
+  status=$?
+  trap - EXIT HUP INT TERM
+  set +e
+  [ -z "$STAGE_DIR" ] || rm -rf "$STAGE_DIR"
+  rm -rf "$TEMP_DIR"
+  exit "$status"
+}
+trap cleanup EXIT HUP INT TERM
+
+curl -fsSL --connect-timeout 5 --max-time 20 --retry 2 --retry-delay 1 --retry-max-time 30 -o "$TEMP_DIR/$ARCHIVE" "$RELEASE_URL/$ARCHIVE" || \
   fail "could not download $ARCHIVE"
-curl -fsSL --retry 3 -o "$TEMP_DIR/checksums.txt" "$RELEASE_URL/checksums.txt" || \
+curl -fsSL --connect-timeout 5 --max-time 20 --retry 2 --retry-delay 1 --retry-max-time 30 -o "$TEMP_DIR/checksums.txt" "$RELEASE_URL/checksums.txt" || \
   fail "could not download checksums.txt"
 
 CHECKSUM_LINE="$(awk -v archive="$ARCHIVE" '$2 == archive { print; exit }' "$TEMP_DIR/checksums.txt")"
@@ -65,10 +80,26 @@ fi
 
 tar -xzf "$ARCHIVE" -C "$TEMP_DIR" || fail "could not extract $ARCHIVE"
 mkdir -p "$INSTALL_DIR"
+STAGE_DIR="$(mktemp -d "$INSTALL_DIR/.delegation-layer-stage.XXXXXX")" || \
+  fail "could not create an installation staging directory"
 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"
+  install -m 0755 "$TEMP_DIR/$binary" "$STAGE_DIR/$binary" || \
+    fail "could not stage $binary"
+done
+
+for binary in delegate delegate-run pueue pueued; do
+  [ -x "$STAGE_DIR/$binary" ] || fail "staged release bundle does not contain executable $binary"
+done
+
+# Rename staged files only after the complete bundle has been downloaded,
+# verified, extracted, and checked. Keep delegate last so a fresh install never
+# exposes the control command before its runner and supervisor are ready.
+for binary in delegate-run pueue pueued delegate; do
+  mv "$STAGE_DIR/$binary" "$INSTALL_DIR/$binary" || fail "could not publish $binary"
 done
+rm -rf "$STAGE_DIR"
+STAGE_DIR=""
 
 printf 'Installed delegation-layer CLI and bundled supervisor %s in %s\n' "$VERSION" "$INSTALL_DIR"
 case ":${PATH:-}:" in

package/package.json

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

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

@@ -0,0 +1,22 @@
+{
+  "name": "delegation-layer",
+  "displayName": "Delegation Layer",
+  "version": "0.1.17",
+  "description": "Route every delegated agent task through a bounded, resumable Delegation Layer CLI.",
+  "author": {
+    "name": "Hesham Karam",
+    "url": "https://github.com/hishamkaram"
+  },
+  "homepage": "https://github.com/hishamkaram/delegation-layer",
+  "repository": "https://github.com/hishamkaram/delegation-layer",
+  "license": "MIT",
+  "keywords": [
+    "agent-delegation",
+    "agent-skills",
+    "coding-agents",
+    "orchestration",
+    "task-lifecycle"
+  ],
+  "defaultEnabled": true,
+  "skills": "./skills/"
+}

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

@@ -0,0 +1,33 @@
+{
+  "name": "delegation-layer",
+  "version": "0.1.17",
+  "description": "Route every delegated agent task through a bounded, resumable Delegation Layer CLI.",
+  "author": {
+    "name": "Hesham Karam",
+    "url": "https://github.com/hishamkaram"
+  },
+  "homepage": "https://github.com/hishamkaram/delegation-layer",
+  "repository": "https://github.com/hishamkaram/delegation-layer",
+  "license": "MIT",
+  "keywords": [
+    "agent-delegation",
+    "agent-skills",
+    "coding-agents",
+    "orchestration",
+    "task-lifecycle"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Delegation Layer",
+    "shortDescription": "Delegate agent work reliably",
+    "longDescription": "Routes external agent work through a bounded, resumable CLI with durable evidence and provider-neutral capability handling.",
+    "developerName": "Hesham Karam",
+    "category": "Productivity",
+    "capabilities": [
+      "Agent delegation",
+      "Bounded execution",
+      "Resumable tasks"
+    ],
+    "defaultPrompt": "Use $agent-integration whenever another agent, harness, model, or provider should perform work."
+  }
+}

package/plugins/delegation-layer/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/bin/sh -c 'plugin_root=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:?plugin root environment variable is missing}}\"; exec \"$plugin_root/scripts/ensure-delegate.sh\"'"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/delegation-layer/scripts/ensure-delegate.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env sh
+set -eu
+
+fail() {
+  printf 'delegation-layer plugin: %s\n' "$1" >&2
+  exit 1
+}
+
+plugin_root="${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
+[ -n "$plugin_root" ] || fail 'the plugin root environment variable is missing'
+
+installer="$plugin_root/scripts/install-cli.sh"
+[ -x "$installer" ] || fail "the bundled CLI installer is missing: $installer"
+
+resolve_command_path() {
+  path="$1"
+  case "$path" in
+    /*) ;;
+    *) path="$(cd -P "$(dirname "$path")" 2>/dev/null && pwd)/$(basename "$path")" || return 1 ;;
+  esac
+  while [ -L "$path" ]; do
+    link="$(readlink "$path")" || return 1
+    case "$link" in
+      /*) path="$link" ;;
+      *) path="$(dirname "$path")/$link" ;;
+    esac
+  done
+  path="$(cd -P "$(dirname "$path")" 2>/dev/null && pwd)/$(basename "$path")" || return 1
+  printf '%s\n' "$path"
+}
+
+valid_delegate() {
+  candidate="$1"
+  [ -f "$candidate" ] && [ -x "$candidate" ] || return 1
+  resolved_candidate="$(resolve_command_path "$candidate")" || return 1
+  resolved_bin_dir="$(dirname "$resolved_candidate")"
+  supervisor_dir="$resolved_bin_dir"
+  if [ ! -x "$supervisor_dir/pueue" ] || [ ! -x "$supervisor_dir/pueued" ]; then
+    supervisor_dir="$resolved_bin_dir/../libexec"
+  fi
+  delegate_run="$resolved_bin_dir/delegate-run"
+  pueue="$supervisor_dir/pueue"
+  pueued="$supervisor_dir/pueued"
+  [ -f "$delegate_run" ] && [ -x "$delegate_run" ] || return 1
+  [ -f "$pueue" ] && [ -x "$pueue" ] || return 1
+  [ -f "$pueued" ] && [ -x "$pueued" ] || return 1
+
+  delegate_version="$("$candidate" --version 2>/dev/null)" || return 1
+  case "$delegate_version" in
+    delegate\ *) ;;
+    *) return 1 ;;
+  esac
+  pueue_version="$("$pueue" --version 2>/dev/null)" || return 1
+  pueued_version="$("$pueued" --version 2>/dev/null)" || return 1
+  case "$pueue_version" in
+    pueue\ *) ;;
+    *) return 1 ;;
+  esac
+  case "$pueued_version" in
+    pueued\ *) ;;
+    *) return 1 ;;
+  esac
+  pueue_release="$(printf '%s\n' "$pueue_version" | awk 'NF { print $NF; exit }')"
+  pueued_release="$(printf '%s\n' "$pueued_version" | awk 'NF { print $NF; exit }')"
+  [ -n "$pueue_release" ] && [ "$pueue_release" = "$pueued_release" ]
+}
+
+path_points_to() {
+  expected="$1"
+  actual="$(command -v delegate 2>/dev/null || true)"
+  [ -n "$actual" ] || return 1
+  actual="$(resolve_command_path "$actual")" || return 1
+  expected="$(resolve_command_path "$expected")" || return 1
+  [ "$actual" = "$expected" ]
+}
+
+path_delegate="$(command -v delegate 2>/dev/null || true)"
+if [ -n "$path_delegate" ] && valid_delegate "$path_delegate"; then
+  exit 0
+fi
+
+existing_install_dir="${DELEGATION_LAYER_INSTALL_DIR:-$HOME/.local/bin}"
+existing_delegate="$existing_install_dir/delegate"
+if valid_delegate "$existing_delegate"; then
+  case ":${PATH:-}:" in
+    *:"$existing_install_dir":*)
+      path_points_to "$existing_delegate" && exit 0
+      shadowed_delegate="$(command -v delegate 2>/dev/null || true)"
+      fail "delegate is installed at $existing_install_dir but PATH resolves delegate to ${shadowed_delegate:-an unavailable command}; put $existing_install_dir before the shadowing entry and start a new harness session"
+      ;;
+    *)
+      fail "delegate is installed at $existing_install_dir but that directory is not on PATH; add it to PATH and start a new harness session"
+      ;;
+  esac
+fi
+
+install_dir="$existing_install_dir"
+case "$install_dir" in
+  /*) ;;
+  *) fail "the CLI install directory must be an absolute path: $install_dir" ;;
+esac
+
+if [ -e "$install_dir/delegate" ] || [ -L "$install_dir/delegate" ]; then
+  fail "refusing to overwrite an existing delegate at $install_dir/delegate; put a clean directory first in PATH or set DELEGATION_LAYER_INSTALL_DIR to a dedicated directory"
+fi
+
+DELEGATION_LAYER_INSTALL_DIR="$install_dir" sh "$installer" ||
+  fail 'the checksum-verified CLI installation failed'
+
+installed_delegate="$install_dir/delegate"
+valid_delegate "$installed_delegate" ||
+  fail "the installer completed but delegate is not usable at $installed_delegate"
+
+if path_points_to "$installed_delegate"; then
+  printf 'Delegation Layer CLI is ready at %s\n' "$installed_delegate"
+  exit 0
+fi
+
+path_delegate="$(command -v delegate 2>/dev/null || true)"
+if [ -n "$path_delegate" ]; then
+  fail "delegate was installed at $install_dir but PATH resolves delegate to $path_delegate; put $install_dir before the shadowing entry and start a new harness session"
+fi
+fail "delegate was installed at $install_dir but that directory is not on PATH; add it to PATH and start a new harness session"

package/plugins/delegation-layer/scripts/install-cli.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env sh
+set -eu
+
+REPOSITORY="hishamkaram/delegation-layer"
+REQUESTED_VERSION="${DELEGATION_LAYER_VERSION:-latest}"
+INSTALL_DIR="${DELEGATION_LAYER_INSTALL_DIR:-$HOME/.local/bin}"
+
+fail() {
+  printf 'delegation-layer: %s\n' "$1" >&2
+  exit 1
+}
+
+for command_name in awk curl grep install mkdir mktemp mv rm tar uname; do
+  command -v "$command_name" >/dev/null 2>&1 || fail "required command not found: $command_name"
+done
+
+case "$INSTALL_DIR" in
+  /*) ;;
+  *) fail "install directory must be an absolute path: $INSTALL_DIR" ;;
+esac
+
+if [ "$REQUESTED_VERSION" = "latest" ]; then
+  latest_url="https://github.com/${REPOSITORY}/releases/latest"
+  resolved_url="$(curl -fsSL --connect-timeout 5 --max-time 20 --retry 2 --retry-delay 1 --retry-max-time 30 -o /dev/null -w '%{url_effective}' "$latest_url")" || fail "could not resolve the latest release"
+  VERSION="${resolved_url##*/}"
+else
+  VERSION="$REQUESTED_VERSION"
+  case "$VERSION" in
+    v*) ;;
+    *) VERSION="v${VERSION}" ;;
+  esac
+fi
+
+printf '%s\n' "$VERSION" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$' || \
+  fail "invalid version: $VERSION"
+
+case "$(uname -s)" in
+  Linux) OS=Linux ;;
+  Darwin) OS=Darwin ;;
+  *) fail "unsupported operating system: $(uname -s)" ;;
+esac
+
+case "$(uname -m)" in
+  x86_64|amd64) ARCH=amd64 ;;
+  arm64|aarch64) ARCH=arm64 ;;
+  *) fail "unsupported architecture: $(uname -m)" ;;
+esac
+
+ARCHIVE="delegation-layer_${VERSION#v}_${OS}_${ARCH}.tar.gz"
+RELEASE_URL="https://github.com/${REPOSITORY}/releases/download/${VERSION}"
+TEMP_DIR="$(mktemp -d)"
+STAGE_DIR=""
+
+cleanup() {
+  status=$?
+  trap - EXIT HUP INT TERM
+  set +e
+  [ -z "$STAGE_DIR" ] || rm -rf "$STAGE_DIR"
+  rm -rf "$TEMP_DIR"
+  exit "$status"
+}
+trap cleanup EXIT HUP INT TERM
+
+curl -fsSL --connect-timeout 5 --max-time 20 --retry 2 --retry-delay 1 --retry-max-time 30 -o "$TEMP_DIR/$ARCHIVE" "$RELEASE_URL/$ARCHIVE" || \
+  fail "could not download $ARCHIVE"
+curl -fsSL --connect-timeout 5 --max-time 20 --retry 2 --retry-delay 1 --retry-max-time 30 -o "$TEMP_DIR/checksums.txt" "$RELEASE_URL/checksums.txt" || \
+  fail "could not download checksums.txt"
+
+CHECKSUM_LINE="$(awk -v archive="$ARCHIVE" '$2 == archive { print; exit }' "$TEMP_DIR/checksums.txt")"
+[ -n "$CHECKSUM_LINE" ] || fail "checksums.txt does not contain $ARCHIVE"
+
+cd "$TEMP_DIR"
+if command -v sha256sum >/dev/null 2>&1; then
+  printf '%s\n' "$CHECKSUM_LINE" | sha256sum -c - || fail "checksum verification failed"
+elif command -v shasum >/dev/null 2>&1; then
+  printf '%s\n' "$CHECKSUM_LINE" | shasum -a 256 -c - || fail "checksum verification failed"
+else
+  fail "sha256sum or shasum is required for checksum verification"
+fi
+
+tar -xzf "$ARCHIVE" -C "$TEMP_DIR" || fail "could not extract $ARCHIVE"
+mkdir -p "$INSTALL_DIR"
+STAGE_DIR="$(mktemp -d "$INSTALL_DIR/.delegation-layer-stage.XXXXXX")" || \
+  fail "could not create an installation staging directory"
+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" "$STAGE_DIR/$binary" || \
+    fail "could not stage $binary"
+done
+
+for binary in delegate delegate-run pueue pueued; do
+  [ -x "$STAGE_DIR/$binary" ] || fail "staged release bundle does not contain executable $binary"
+done
+
+# Rename staged files only after the complete bundle has been downloaded,
+# verified, extracted, and checked. Keep delegate last so a fresh install never
+# exposes the control command before its runner and supervisor are ready.
+for binary in delegate-run pueue pueued delegate; do
+  mv "$STAGE_DIR/$binary" "$INSTALL_DIR/$binary" || fail "could not publish $binary"
+done
+rm -rf "$STAGE_DIR"
+STAGE_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" ;;
+esac

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

@@ -0,0 +1,301 @@
+---
+name: agent-integration
+description: Use the Delegation Layer CLI whenever another agent, harness, model, or provider should perform work, then collect durable evidence and continue timed out sessions safely.
+---
+
+# Delegation Layer
+
+Use this skill whenever the user asks another agent, harness, model, or provider
+to perform any part of the work. This includes implementation, research,
+review, testing, debate, comparison, summarization, and follow-up work. Route
+that work through the local `delegate` CLI. The CLI is the only integration
+surface. Do not call, inspect, authenticate, or install a provider CLI directly,
+and do not replace delegation with a provider's native subagent or team feature.
+
+## 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. 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, an explicit
+   permission mode, and a finite budget.
+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
+
+For the normal path, use automatic selection directly. If you need to explain
+what the installed build knows, run:
+
+```sh
+delegate providers --json
+```
+
+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
+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.
+
+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.
+
+### 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:
+
+```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 explicitly supplied `PROVIDER_ID`.
+For a named provider, 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`.
+
+When an explicit selection is supplied, pass it through the public fields:
+`--model MODEL` and `--effort VALUE`. Codex encodes effort as its native TOML
+`model_reasoning_effort` setting; Claude and AGY use their native effort flags;
+Pi maps effort to `--thinking`; and OpenCode maps effort to `--variant`. An
+omitted or `default` effort is omitted from native argv. For AGY read-only,
+`--permission read-only` selects the exact native `--sandbox --mode plan` path
+without a bypass. Authorized AGY workspace-write retains its existing native
+bypass. Do not add these native flags yourself.
+
+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` returns `status: "timed_out"`, inspect the nested
+continuation object:
+
+```json
+{
+  "status": "timed_out",
+  "continuation": {
+    "resumable": true,
+    "mode": "native",
+    "predecessor_task_id": "TASK_ID",
+    "continue_command": "delegate continue --task TASK_ID --json"
+  }
+}
+```
+
+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 permission mode and
+creates a new task ID. Do not add `--permission` to `continue`. Always include
+the original `--root`, even if a returned command hint omits it. 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.
+
+If `continue` returns an error, use its `failure` and `task_record` fields just
+as for dispatch: when the record is `created`, check the returned successor
+`task_id` with `status`; when it is `not_created`, correct the request only if
+`failure.next_action` is `correct_request`; and when it is `unknown`, stop and
+report the failure. Do not repeat `continue` while successor creation is
+unknown.
+
+## 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. Report the missing authentication
+prerequisite and stop that attempt; do not retry or authenticate the provider.
+
+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/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/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,50 @@
+# 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`: use only when the caller explicitly selected an ID;
+- `--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.

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

@@ -0,0 +1,46 @@
+# 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.
+
+`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/plugins/delegation-layer/skills/agent-integration/references/result-handling.md

@@ -0,0 +1,37 @@
+# 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 a dispatch or continue response does not confirm admission, preserve any
+   task ID and report its bounded error. An uncertain admission must be
+   inspected, never automatically dispatched again. Status and collect can
+   report `admission: "unknown"` alongside valid terminal evidence.
+3. If `status` is `timed_out`, follow the continuation procedure before treating
+   pending publication as a reason to wait. `continuation.resumable: true`
+   permits a linked successor even when no outcome has been published.
+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. Otherwise, if `liveness` is queued or running or publication is pending,
+   observe the same task again with a finite watch interval.
+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.
+
+For `delegate models`, validate the complete JSON envelope before using any
+fact. Treat `available` and `partial` with exit `0` as observations, preserve
+`blocked` and `unavailable` with exit `2` as unresolved prerequisites, and
+preserve `failed` with exit `1` as a discovery failure. `complete` refers to
+model enumeration. Keep `efforts: null` distinct from `efforts: []`, and do not
+apply harness-wide effort choices to every model. Discovery is advisory and
+never an admission allowlist; a provider default remains valid and a listed
+model is not an execution guarantee.
+
+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.

package/skills/agent-integration/SKILL.md

@@ -1,18 +1,24 @@
 ---
 name: agent-integration
-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.
+description: Use the Delegation Layer CLI whenever another agent, harness, model, or provider should perform work, then collect durable evidence and continue timed out sessions safely.
 ---
 
 # 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.
+Use this skill whenever the user asks another agent, harness, model, or provider
+to perform any part of the work. This includes implementation, research,
+review, testing, debate, comparison, summarization, and follow-up work. Route
+that work through the local `delegate` CLI. The CLI is the only integration
+surface. Do not call, inspect, authenticate, or install a provider CLI directly,
+and do not replace delegation with a provider's native subagent or team feature.
 
 ## 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.
+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. 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.