delegation-layer 0.1.17 → 0.1.19

package/README.md

@@ -36,6 +36,22 @@ already use instead of replacing them.
 3. Delegation Layer admits one bounded provider turn through the supervisor.
 4. The lead agent collects the sealed result and evidence.
 
+## Ask naturally
+
+Try “Ask Codex to review this change”, “Get Antigravity’s opinion”, or
+“Have Claude investigate this failure”. The skill routes external collaboration
+through `delegate`, preserves a named destination, and collects task evidence.
+Ordinary native subagents remain available for work inside the current harness,
+even when you name that harness. Ask for a separate session when you want
+Delegate to launch another instance of the same CLI.
+
+Skill installation makes this workflow discoverable; it does not force a model
+to choose it over another plugin. Selection depends on the harness, model, and
+loaded instructions. No user rules, settings, or competing plugins are rewritten.
+If an agent bypasses Delegate, that is a selection failure, not proof the
+integration worked. For a persistent preference, see
+[configure agent routing](docs/agent-routing.md).
+
 ## Install
 
 ### Recommended for Codex and Claude Code
@@ -234,3 +250,10 @@ The successor receives a new task ID and is observed with the same `status` and
 ## License
 
 This project is licensed under the [MIT License](LICENSE).
+
+### Consult models through Claude Code Router
+
+Delegate also supports CCR-configured third-party and local models through
+`ccr:print`. Ask your agent to “have CCR review this” and it can discover and
+choose a configured model alias. CCR and Claude Code must already be installed
+and the provider configured. See [provider guidance](docs/providers.md#claude-code-router).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delegation-layer",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Multi-provider AI agent delegation CLI and Agent Skill for running bounded coding tasks across provider CLIs.",
   "keywords": [
     "ai-agents",

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

@@ -1,8 +1,8 @@
 {
   "name": "delegation-layer",
   "displayName": "Delegation Layer",
-  "version": "0.1.17",
-  "description": "Route every delegated agent task through a bounded, resumable Delegation Layer CLI.",
+  "version": "0.1.19",
+  "description": "Consult external AI harnesses and CCR-configured models for reviews, research, implementation, and debate through the resumable Delegate CLI.",
   "author": {
     "name": "Hesham Karam",
     "url": "https://github.com/hishamkaram"

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

@@ -1,7 +1,7 @@
 {
   "name": "delegation-layer",
-  "version": "0.1.17",
-  "description": "Route every delegated agent task through a bounded, resumable Delegation Layer CLI.",
+  "version": "0.1.19",
+  "description": "Consult external AI harnesses and CCR-configured models for reviews, research, implementation, and debate through the resumable Delegate CLI.",
   "author": {
     "name": "Hesham Karam",
     "url": "https://github.com/hishamkaram"
@@ -19,7 +19,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Delegation Layer",
-    "shortDescription": "Delegate agent work reliably",
+    "shortDescription": "Consult external AI harnesses",
     "longDescription": "Routes external agent work through a bounded, resumable CLI with durable evidence and provider-neutral capability handling.",
     "developerName": "Hesham Karam",
     "category": "Productivity",
@@ -28,6 +28,6 @@
       "Bounded execution",
       "Resumable tasks"
     ],
-    "defaultPrompt": "Use $agent-integration whenever another agent, harness, model, or provider should perform work."
+    "defaultPrompt": "Use $agent-integration to consult another harness or model for review, research, implementation, testing, or debate."
   }
 }

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

@@ -1,16 +1,45 @@
 ---
 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.
+description: Delegate external tasks to CCR (Claude Code Router) and other agents. Use for Codex, Claude, AGY, and other external agent or model collaboration for reviews, research, implementation, testing, second opinions, comparisons, and debates, including collaboration you choose during a task. Discover other supported harnesses such as Pi and OpenCode through Delegate. Not for ordinary native subagents, provider setup, or questions merely about a tool.
 ---
 
 # 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.
+## 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.
+“Claude Code Router” and “CCR” mean `ccr:print`, not ordinary Claude Code.
+For that request, use Delegate with a CCR model alias; a Claude-specific skill
+or subscription model does not fulfill the requested route.
+
+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.
+
+A reported blocker is a valid final response to a delegation request. It does
+not turn that request into an environment-repair task. When a response says
+`failure.next_action: "stop_and_report"`, that attempt is finished. Include its
+failure in your final response without opening a clarification dialog to choose
+a fallback. For `task_record: not_created`, identify the requested destination
+and quote the returned `task_id` (if present), `task_record`, `failure`, and
+`error`. Do not append inferred state paths or provider-setup diagnoses. Do not run diagnostic commands, retry it, or use another integration.
+Troubleshooting requires a separate user request. Other independently requested
+tasks may proceed; the failed attempt must remain reported as failed or blocked.
 
 ## Rules
 
@@ -19,11 +48,14 @@ and do not replace delegation with a provider's native subagent or team feature.
    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.
+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.
+3. Give every turn an absolute workspace, an explicit permission mode, and a
+   finite budget. Keep the state root outside the workspace. Reuse a supplied
+   `DELEGATE_ROOT` for all providers and tasks; do not invent per-provider or
+   per-task state roots. Task IDs separate work within that root.
 4. Use `--json` and save the returned `task_id`. Read `admission`, `liveness`,
    `publication`, `status`, `outcome`, `continuation`, `task_record`, `failure`,
    and `error` as separate fields.
@@ -66,27 +98,20 @@ 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:
+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
 ```
 
-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.
+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.
+Dispatch performs admission checks; a separate preflight is not needed for a
+normal task. For an explicitly requested readiness check, see
+[preflight guidance](references/command-reference.md#checking-readiness).
 
 The catalog and `capabilities` response expose supported permission modes,
 request options, continuation, and the read-only mechanism. A read-only
@@ -95,64 +120,52 @@ 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:
+Read `required_options` in provider discovery before dispatch. Supply every
+required option; a provider's optional defaults do not replace required inputs.
+For CCR / Claude Code Router or a CCR model request, read
+[CCR model selection](references/ccr.md). A CCR route is external collaboration
+even when you are already using Claude. Do not assume every open-source model
+name belongs to CCR; clarify only if discovery leaves the destination ambiguous.
 
-```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.
+Keep provider defaults when no model or effort was requested and neither is required. 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:
+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
-```
+Run path preparation and dispatch in **one shell/tool invocation**, as shown
+below. Shell variables may disappear between tool calls. For later commands,
+use the actual saved absolute paths or assign them again in that invocation;
+never pass an empty `--root`, `--brief`, or `--cwd`.
 
-Replace the example brief with the actual user request. Do not place the state
+Replace the example brief below 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.
+rejects a caller-supplied state root, report the placement error rather than
+silently replacing that root. If no root was supplied, choose one outside the
+workspace and reuse it. Do not change provider settings. Retain the selected
+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
+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
+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
 delegate --root "$STATE_ROOT" dispatch --auto \
   --brief "$BRIEF" \
   --cwd "$WORKSPACE" \
@@ -174,28 +187,21 @@ 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.
+Save the exact `task_id` from the JSON response. Apply this decision separately
+for **each attempt**, including requests issued together:
+
+| Response | Next action |
+|---|---|
+| Usage error, no JSON response | Correct the reported syntax using Delegate help or `providers --json`, then invoke that request again. Parsing failed before admission. |
+| `task_record: not_created` and `failure.next_action: correct_request` | Correct that request and retry it. |
+| `task_record: not_created` with any other next action | Report that attempt's failure and stop it. Do not diagnose provider setup or substitute an integration. |
+| `task_record: created` | Use `status` before taking any other action. Do not dispatch again. |
+| `task_record: unknown` or an ambiguous response | Stop and report; do not retry an uncertain task creation. |
+
+One attempt's `stop_and_report` does not prevent correcting another independent
+request's usage error. Keep the failed attempt reported as failed. With an
+explicit task ID, absence can race another dispatch creating the same ID;
+never retry that uncertain ID or run Pueue commands.
 
 ### 5. Observe and collect
 
@@ -220,82 +226,46 @@ 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.
+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
 
+Build the report from observed CLI responses and collected evidence. Copy
+returned values; do not reconstruct paths from example commands or shell
+defaults. Omit unobserved configuration details.
+
 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.