delegation-layer 0.1.18 → 0.1.20

package/scripts/install-agent-integration.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { accessSync, constants } from "node:fs";
-import { copyFile, lstat, mkdir, readdir, readFile } from "node:fs/promises";
+import { copyFile, lstat, mkdir, open, readdir, readFile, rename, unlink } from "node:fs/promises";
 import { emitKeypressEvents } from "node:readline";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { homedir } from "node:os";
@@ -90,14 +90,14 @@ function usage(message, exitCode = 2) {
     console.error(`Error: ${message}`);
   }
   console.error(
-    "Usage:\n  delegation-layer install [--scope project|global] [--harness NAME[,NAME...]] [--yes] [--force]\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]",
+    "Usage:\n  delegation-layer install [--scope project|global] [--harness NAME[,NAME...]] [--yes] [--force] [--routing default|skill-only]\n  delegation-layer routing status|disable [--scope project|global] [--harness NAME[,NAME...]]\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]",
   );
   process.exitCode = exitCode;
 }
 
 function help() {
   console.log(
-    "Usage:\n  delegation-layer install [--scope project|global] [--harness NAME[,NAME...]] [--yes] [--force]\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]\n\nThe install command detects supported agent harnesses and installs the skill for a project or user.\nGlobal scope is the default; use --scope project for a project-local install.\nUse --harness universal when no specific harness is detected.",
+    "Usage:\n  delegation-layer install [--scope project|global] [--harness NAME[,NAME...]] [--yes] [--force] [--routing default|skill-only]\n  delegation-layer routing status|disable [--scope project|global] [--harness NAME[,NAME...]]\n  delegation-layer --target ABSOLUTE_SKILL_DIR [--force]\n  delegation-layer install-cli [--version VERSION] [--install-dir ABSOLUTE_DIR]\n\nThe install command detects supported agent harnesses and installs the skill for a project or user.\nGlobal scope is the default; use --scope project for a project-local install.\nUse --harness universal when no specific harness is detected.",
   );
 }
 
@@ -152,6 +152,7 @@ function parseInstallArguments(argumentsList) {
   let harnessNames;
   let scope;
   let yes = false;
+  let routing;
 
   for (let index = 0; index < argumentsList.length; index += 1) {
     const argument = argumentsList[index];
@@ -163,6 +164,12 @@ function parseInstallArguments(argumentsList) {
       yes = true;
       continue;
     }
+    if (argument === "--routing") {
+      routing = requiredValue(argumentsList, index, "--routing");
+      if (!routing) return null;
+      index += 1;
+      continue;
+    }
     if (argument === "--scope") {
       scope = requiredValue(argumentsList, index, "--scope");
       if (!scope) {
@@ -201,7 +208,11 @@ function parseInstallArguments(argumentsList) {
     usage(`unknown harness ${unknown}; choose from ${harnesses.map((harness) => harness.name).join(", ")}`);
     return null;
   }
-  return { force, harnessNames, scope, yes };
+  if (routing && !["default", "skill-only"].includes(routing)) {
+    usage("--routing must be default or skill-only");
+    return null;
+  }
+  return { force, harnessNames, scope, yes, routing };
 }
 
 async function existingPath(path) {
@@ -486,7 +497,7 @@ function pickOptions({ initialValues = [], multiple = false, options, title }) {
   });
 }
 
-async function chooseInstallOptions({ force, harnessNames, scope, yes }) {
+async function chooseInstallOptions({ force, harnessNames, scope, yes, routing }) {
   const cwd = process.cwd();
   const home = resolve(process.env.DELEGATION_LAYER_HOME ?? homedir());
   const detections = await detectHarnesses({ cwd, home });
@@ -536,7 +547,20 @@ async function chooseInstallOptions({ force, harnessNames, scope, yes }) {
     }
   }
 
+  if (needsPrompt && !routing) {
+    routing = await pickOptions({
+      initialValues: ["default"],
+      options: [
+        { value: "default", label: "Prefer Delegate", description: "Install collaboration context hooks for Claude and Codex; native hook trust still applies" },
+        { value: "skill-only", label: "Skill only", description: "Install guidance without adding hooks; keep existing routing settings" },
+      ],
+      title: "How should external collaboration be routed?",
+    });
+    if (!routing) return null;
+  }
+
   return {
+    routing: routing ?? "skill-only",
     cwd,
     force,
     harnessNames: harnessNames ?? defaults,
@@ -546,6 +570,9 @@ async function chooseInstallOptions({ force, harnessNames, scope, yes }) {
 }
 
 function targetFor(harness, scope, cwd, home) {
+  if (scope === "global" && harness.name === "claude" && process.env.CLAUDE_CONFIG_DIR) {
+    return join(resolve(process.env.CLAUDE_CONFIG_DIR), "skills", "agent-integration");
+  }
   const root = scope === "global" ? home : cwd;
   const relativePath = scope === "global" ? harness.globalPath : harness.projectPath;
   return join(resolve(root, relativePath), "agent-integration");
@@ -576,6 +603,165 @@ async function install({ force, target }) {
   console.log(`Installed agent integration skill: ${join(target, "SKILL.md")}`);
 }
 
+function shellQuote(value) {
+  return "'" + value.replaceAll("'", "'\\''") + "'";
+}
+
+function routingPath(name, { scope, cwd, home }) {
+  if (name === "claude") {
+    return scope === "global"
+      ? join(resolve(process.env.CLAUDE_CONFIG_DIR || join(home, ".claude")), "settings.json")
+      : join(cwd, ".claude", "settings.local.json");
+  }
+  if (name === "codex") {
+    return join(scope === "global" ? resolve(process.env.CODEX_HOME || join(home, ".codex")) : join(cwd, ".codex"), "hooks.json");
+  }
+  return null;
+}
+
+function jsonObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateHookConfig(config, path) {
+  if (!jsonObject(config) || (config.hooks !== undefined && !jsonObject(config.hooks))) {
+    throw new Error(`expected a JSON object with an optional hooks object: ${path}`);
+  }
+  for (const groups of Object.values(config.hooks ?? {})) {
+    if (!Array.isArray(groups) || groups.some((group) => !jsonObject(group)
+      || !Array.isArray(group.hooks) || group.hooks.some((hook) => !jsonObject(hook) || typeof hook.type !== "string"))) {
+      throw new Error(`invalid hook configuration; no routing changes written: ${path}`);
+    }
+  }
+}
+
+async function prepareRouting(selected, action) {
+  const plans = [];
+  for (const name of new Set(selected.harnessNames)) {
+    const path = routingPath(name, selected);
+    if (!path || process.platform === "win32") {
+      plans.push({ name, status: "unsupported-host" });
+      continue;
+    }
+    await assertNoSymlinkComponents(path);
+    const stat = await existingPath(path);
+    if (stat && !stat.isFile()) throw new Error(`routing configuration must be a regular file: ${path}`);
+    const before = stat ? await readFile(path, "utf8") : null;
+    let config;
+    try {
+      config = before === null ? {} : JSON.parse(before);
+    } catch {
+      throw new Error(`invalid JSON; routing configuration left unchanged: ${path}`);
+    }
+    validateHookConfig(config, path);
+    const target = targetFor(harnessByName.get(name), selected.scope, selected.cwd, selected.home);
+    const script = join(target, "scripts", "delegate-routing-context.sh");
+    const hooks = config.hooks ?? {};
+    let present = 0;
+    let changed = false;
+    for (const event of ["SessionStart", "SubagentStart"]) {
+      const command = `/bin/sh ${shellQuote(script)} ${event}`;
+      const groups = hooks[event] ?? [];
+      const matches = groups.flatMap((group) => group.hooks).filter((hook) => hook.type === "command" && hook.command === command);
+      if (matches.length) present += 1;
+      if (action === "disable") {
+        if (!matches.length) continue;
+        hooks[event] = groups.flatMap((group) => {
+          const remaining = group.hooks.filter((hook) => hook.type !== "command" || hook.command !== command);
+          if (remaining.length === group.hooks.length) return [group];
+          return remaining.length ? [{ ...group, hooks: remaining }] : [];
+        });
+        if (!hooks[event].length) delete hooks[event];
+        changed = true;
+      } else if (action === "enable" && !matches.length) {
+        hooks[event] = [...groups, { hooks: [{ type: "command", command }] }];
+        changed = true;
+      }
+    }
+    if (changed) config.hooks = hooks;
+    let assetsPresent = true;
+    if (action === "status" && present) {
+      for (const relative of ["SKILL.md", "scripts/delegate-routing-context.sh", "references/routing-rule.json"]) {
+        const asset = await existingPath(join(target, relative));
+        if (!asset?.isFile() || asset.isSymbolicLink()) assetsPresent = false;
+      }
+    }
+    plans.push({ name, path, target, before, after: changed ? JSON.stringify(config, null, 2) + "\n" : before,
+      mode: stat ? stat.mode & 0o777 : 0o600,
+      status: action === "disable" ? "disabled" : action === "enable" || (present === 2 && assetsPresent) ? "configured" : present ? "incomplete" : "not-configured" });
+  }
+  return plans;
+}
+
+async function replaceRoutingConfig(plan, before, after) {
+  await assertNoSymlinkComponents(plan.path);
+  await mkdir(dirname(plan.path), { recursive: true });
+  const lockPath = plan.path + ".delegation-layer.lock";
+  let lock;
+  try {
+    lock = await open(lockPath, "wx", 0o600);
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Error(`routing configuration is locked: ${lockPath}; verify no other installer is running before removing a stale lock`);
+    throw error;
+  }
+  const suffix = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const temporary = plan.path + `.delegation-layer-stage-${suffix}`;
+  try {
+    const stat = await existingPath(plan.path);
+    if (stat && (!stat.isFile() || stat.isSymbolicLink())) throw new Error(`routing configuration changed during installation: ${plan.path}`);
+    const current = stat ? await readFile(plan.path, "utf8") : null;
+    if (current !== before) throw new Error(`routing configuration changed during installation; retry: ${plan.path}`);
+    if (before !== null) {
+      const backup = await open(plan.path + `.delegation-layer-backup-${suffix}`, "wx", 0o600);
+      try { await backup.writeFile(before); await backup.sync(); } finally { await backup.close(); }
+    }
+    if (after === null) {
+      await unlink(plan.path);
+      return;
+    }
+    const staged = await open(temporary, "wx", plan.mode);
+    try { await staged.writeFile(after); await staged.sync(); } finally { await staged.close(); }
+    await rename(temporary, plan.path);
+  } finally {
+    try {
+      try { await unlink(temporary); } catch (error) { if (error.code !== "ENOENT") throw error; }
+    } finally {
+      try { await lock.close(); } finally { await unlink(lockPath); }
+    }
+  }
+}
+
+async function applyRouting(plans) {
+  const applied = [];
+  try {
+    for (const plan of plans) {
+      if (!plan.path || plan.before === plan.after) continue;
+      await replaceRoutingConfig(plan, plan.before, plan.after);
+      applied.push(plan);
+    }
+  } catch (error) {
+    const failures = [];
+    for (const plan of applied.reverse()) {
+      try { await replaceRoutingConfig(plan, plan.after, plan.before); }
+      catch (rollbackError) { failures.push(rollbackError.message); }
+    }
+    throw new Error(`${error.message}${failures.length ? `; rollback needs attention: ${failures.join("; ")}` : "; earlier routing changes rolled back"}`);
+  }
+}
+
+function printRouting(plan, action) {
+  if (!plan.path) {
+    console.log(`${plan.name}: unsupported-host for automatic routing; skill-only guidance remains available.`);
+    return;
+  }
+  console.log(`${plan.name}: ${plan.status} (${plan.path}).`);
+  if (plan.status === "configured") {
+    console.log("Activation not verified: start or resume a session and check the native hook output. Installation is not proof of model compliance.");
+    if (plan.name === "codex") console.log("Codex: review and trust the hooks using /hooks. New or changed definitions are skipped until trusted.");
+  }
+  if (action === "disable") console.log("Only this installer's matching hooks were removed; plugin hooks are managed by the host plugin manager.");
+}
+
 async function validateSourceTree() {
   const files = await skillFiles(sourceDirectory);
   if (!files.includes("SKILL.md")) {
@@ -595,6 +781,23 @@ if (argumentsList[0] === "install-cli") {
     console.error(`Error: ${error.message}`);
     process.exitCode = 1;
   }
+} else if (argumentsList[0] === "routing") {
+  const action = argumentsList[1];
+  const options = parseInstallArguments(argumentsList.slice(2));
+  if (!["status", "disable"].includes(action)) {
+    usage("routing requires status or disable");
+  } else if (options) {
+    try {
+      if (options.routing || options.force) throw new Error("routing status/disable do not accept --routing or --force");
+      const selected = await chooseInstallOptions({ ...options, yes: true, harnessNames: options.harnessNames ?? ["claude", "codex"] });
+      const plans = await prepareRouting(selected, action);
+      if (action === "disable") await applyRouting(plans);
+      for (const plan of plans) printRouting(plan, action);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exitCode = 1;
+    }
+  }
 } else if (argumentsList[0] === "install") {
   const options = parseInstallArguments(argumentsList.slice(1));
   if (options) {
@@ -603,12 +806,16 @@ if (argumentsList[0] === "install-cli") {
       if (!selected) {
         console.log("Installation cancelled.");
       } else {
+        const routingPlans = selected.routing === "default" ? await prepareRouting(selected, "enable") : [];
         const targets = selected.harnessNames.map((name) => targetFor(harnessByName.get(name), selected.scope, selected.cwd, selected.home));
         const uniqueTargets = [...new Set(targets)];
         console.log(`Installing for ${selected.scope}: ${uniqueTargets.join(", ")}`);
         for (const target of uniqueTargets) {
           await install({ force: selected.force, target });
         }
+        await applyRouting(routingPlans);
+        for (const plan of routingPlans) printRouting(plan, "enable");
+        if (selected.routing === "skill-only") console.log("Skill-only installation; existing routing settings were not changed.");
       }
     } catch (error) {
       console.error(`Error: ${error.message}`);

package/skills/agent-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-integration
-description: Consult external AI agents and harnesses through Delegate for reviews, research, implementation, testing, second opinions, comparisons, and debates. Use when asked to ask Codex, consult Claude, get Antigravity’s opinion, or assign work to another harness or model, including external collaboration you choose during a task. Not for ordinary native subagents, provider setup, or questions merely about a tool.
+description: Coordinate external agent, model, and separate harness tasks through Delegate, including research, implementation, tests, reviews, consultations, comparisons, and debates. Use before choosing an external integration; ordinary native subagents and questions about tools remain local.
 ---
 
 # Delegation Layer
@@ -13,6 +13,9 @@ external harness to do work. Requests such as “ask Codex to review this”,
 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)
@@ -28,6 +31,16 @@ 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
 
 1. Check whether `delegate` is already installed. A plugin SessionStart hook
@@ -39,16 +52,24 @@ Delegate blocker.
    name rather than a provider ID. Use `dispatch --auto` when none was chosen.
    Provider selection, executable checks, compatibility checks, authentication
    gates, and supervisor admission belong inside Delegation Layer.
-3. Give every turn an absolute workspace, a separate state root, an explicit
-   permission mode, and a finite budget. Preserve a caller-supplied
-   `DELEGATE_ROOT`; do not replace it with a temporary directory.
-4. Use `--json` and save the returned `task_id`. Read `admission`, `liveness`,
+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 each response separately with its requested destination,
+   model, effort, workspace, and returned `task_id`. Never merge concurrent
+   responses into an unlabeled output stream. Read `admission`, `liveness`,
    `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
+5. Observe with `status` and collect with `collect`. Keep collection in the
+   foreground until all requested tasks reach a terminal result or an explicit
+   blocker. Do not end a headless turn promising a background notification.
+   Pending publication (exit 3) means keep waiting, not success. Only detach
+   when the user explicitly requests it, retaining the exact task IDs.
+   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
@@ -95,19 +116,9 @@ Use the matching catalog ID with `--provider`; do not silently substitute
 `--auto` or another provider. If the name is ambiguous, clarify the intended
 destination. If it is absent, report that this build does not support it.
 The catalog is not proof that a provider is installed, authenticated, or ready.
-If a side-effect-free readiness check is useful,
-run:
-
-```sh
-delegate preflight --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE \
-  --permission REQUESTED_MODE --json
-```
-
-Replace `REQUESTED_MODE` with `read-only` for investigation or
-`workspace-write` for authorized edits. Preflight reports static admission only.
-It does not create a task, start the supervisor, or launch a provider. Do not keep
-retrying preflight when it says
-`blocked` or `unsupported`; report the bounded reason.
+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
@@ -116,10 +127,21 @@ behavior but is not an independent delegate-owned sandbox. Static discovery
 does not prove authentication or live acceptance; use the dispatch or live
 acceptance result for that evidence.
 
-Keep provider defaults when no model or effort was requested. When an explicit
+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.
+
+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.
+Pass exact requested model IDs and effort values unchanged through Delegate's
+public `--model` and `--effort` fields; discovery is advisory, never an allowlist.
+For a natural-language model name, resolve one exact ID through discovery. If
+it remains ambiguous or discovery is unavailable, ask for the exact model ID;
+do not turn a display name into a guessed alias. An explicit ID needs no such
+clarification just because it is absent from discovery.
 
 ### 3. Prepare separate paths and a finite brief
 
@@ -128,22 +150,18 @@ brief file that contains the requested work and its acceptance criteria. Keep
 the state root outside the workspace and provider-writable trees (which can
 include the system temporary directory). Use `DELEGATE_ROOT` when supplied:
 
-```sh
-STATE_ROOT="${DELEGATE_ROOT:-$HOME/delegation-state}"
-WORKSPACE="$PWD"
-BRIEF="$(mktemp)"
-cat >"$BRIEF" <<'EOF'
-Describe the delegated task, the files or behavior to change, and the checks
-that must pass. Keep the response concise and report validation evidence.
-EOF
-```
+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
 
@@ -152,6 +170,13 @@ For a named harness or provider resolved in step 2, replace `--auto` with `--pro
 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" \
@@ -171,21 +196,26 @@ For independent work, the model may run several complete `dispatch` commands
 concurrently. Keep each task's brief, workspace, permission, and task ID
 independent. Do not configure Pueue or wait for one task before dispatching the
 next solely to serialize ordinary work. Inspect each returned task separately
-with `status` and `collect`.
-
-Save the exact `task_id` from the JSON response. The recovery steps below apply
-to parsed dispatch responses. If the CLI rejects the command syntax before
-dispatch (nonzero exit with a usage error and no JSON response), correct the
-reported syntax and invoke it again; argument parsing fails before admission and
-does not create a task record. For a parsed dispatch error, read its `failure`
-and `task_record` fields. If `task_record` is
-`not_created`, do not run `status`, `collect`, or `continue`; correct the request
-only when `failure.next_action` is `correct_request`, otherwise report the
-delegate failure and stop. If it is `created`, use `status` before taking any
-other action. If it is `unknown`, stop and report the failure: with an
-explicit task ID, absence can race another dispatch that is creating the same
-ID. Never retry that ID, run Pueue commands, or silently try another provider
-after a task may have been admitted.
+with `status` and `collect`. Use independent tool calls or separate response
+files, never background commands writing to the same stdout. Read
+[parallel reviews and debates](references/collaboration.md) when coordinating
+multiple participants or challenge rounds.
+
+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
 
@@ -246,6 +276,10 @@ recruit more agents unless that is explicitly part of the task.
 
 ## 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.

package/skills/agent-integration/evals/routing.json

@@ -150,6 +150,101 @@
       "external": false,
       "provider": null,
       "split": "validation"
+    },
+    {
+      "name": "ccr-review",
+      "prompt": "Ask Claude Code Router to review pricing.py for correctness without editing. Choose an appropriate configured model and report which one you used.",
+      "external": true,
+      "provider": "ccr:print",
+      "split": "development"
+    },
+    {
+      "name": "ccr-explicit-alias",
+      "prompt": "Ask CCR using the alias local-review to investigate pricing.py. Do not edit files.",
+      "external": true,
+      "provider": "ccr:print",
+      "model": "local-review",
+      "split": "validation"
+    },
+    {
+      "name": "ccr-write",
+      "prompt": "Have CCR with the alias local-review fix pricing.py so discounts are percentages, and test the correction. Authorize edits in this workspace.",
+      "external": true,
+      "provider": "ccr:print",
+      "model": "local-review",
+      "split": "validation"
+    },
+    {
+      "name": "ccr-follow-up",
+      "prompt": "Ask CCR using local-review to critique pricing.py, then ask that same session one follow-up about its recommendation. No edits.",
+      "external": true,
+      "provider": "ccr:print",
+      "model": "local-review",
+      "split": "validation"
+    },
+    {
+      "name": "ccr-explain",
+      "prompt": "Explain what Claude Code Router does. Do not ask it to perform work.",
+      "external": false,
+      "provider": null,
+      "split": "validation"
+    },
+    {
+      "name": "ccr-compare",
+      "prompt": "Ask CCR using local-review and a separate Codex session for independent reviews of pricing.py, then compare their findings. No edits.",
+      "external": true,
+      "provider": [
+        "ccr:print",
+        "codex:exec"
+      ],
+      "split": "validation"
+    },
+    {
+      "name": "requested-model-effort",
+      "prompt": "Ask a separate Codex CLI session to review pricing.py without edits. Use model gpt-5.6-luna and effort max, preserving both choices.",
+      "external": true,
+      "provider": "codex:exec",
+      "model": "gpt-5.6-luna",
+      "effort": "max",
+      "split": "validation",
+      "regression": true
+    },
+    {
+      "name": "ambiguous-model",
+      "prompt": "Ask a separate Antigravity CLI session to review pricing.py using the fastest Flash model. I do not know the exact model ID. Do not edit files.",
+      "external": true,
+      "provider": "antigravity:print",
+      "expectation": "Resolve an exact model ID through discovery; clarify if unavailable or ambiguous. Never guess an identifier.",
+      "split": "validation",
+      "regression": true
+    },
+    {
+      "name": "parallel-receipts",
+      "prompt": "Ask separate Codex and Claude CLI sessions to independently review pricing.py against README.md concurrently. Keep the exact provider-to-task-ID mapping for both, including any failed dispatch. No edits.",
+      "external": true,
+      "provider": [
+        "codex:exec",
+        "claude:print"
+      ],
+      "split": "validation",
+      "regression": true
+    },
+    {
+      "name": "subagent-external",
+      "prompt": "Use an ordinary native subagent to coordinate a read-only second opinion from a separate Codex CLI session about pricing.py. Let the subagent choose its tools. Report the external finding or blocker.",
+      "external": true,
+      "provider": "codex:exec",
+      "split": "validation",
+      "regression": true
+    },
+    {
+      "name": "explicit-bypass",
+      "prompt": "For this request explicitly bypass Delegate and its skill. Run only codex --version directly; do not start a model session or review.",
+      "external": false,
+      "provider": null,
+      "expectation": "Respect the explicit direct integration choice; this bounded test proves bypass permission, not task completion.",
+      "split": "validation",
+      "regression": true
     }
   ]
 }

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

@@ -0,0 +1,33 @@
+# CCR model selection
+
+Use this reference when asked to consult Claude Code Router (CCR), use one of
+its configured model aliases, or compare its models with other harnesses.
+CCR runs Claude Code against a configured third-party or local provider.
+
+1. Resolve CCR through `delegate providers --json`; its profile is `ccr:print`.
+2. Preserve an explicitly requested CCR alias as `--model ALIAS`. Do not replace
+   it with an upstream model ID or reject it solely because discovery omitted it.
+3. If no alias was chosen, run
+   `delegate models --provider ccr:print --cwd ABSOLUTE_WORKSPACE --json`.
+   Choose a suitable configured alias from the available metadata and report
+   the choice. Clarify when the intended model remains ambiguous. If discovery
+   is unavailable and no alias is known, report the blocker; do not guess.
+4. Dispatch through Delegate with `--provider ccr:print --model ALIAS`, the brief,
+   workspace, permission, finite budget, and `--json`. Use the normal status,
+   collect, and continuation procedure from the main skill.
+
+CCR requires an explicit alias. Unspecified external collaboration still uses
+`dispatch --auto`; do not prefer CCR unless the request calls for it. Multiple
+aliases can be assigned independent tasks for comparison or debate.
+
+Read-only selects native Claude plan behavior; workspace-write selects native
+unattended tool execution. Neither is an independent Delegate sandbox. Preserve
+requested effort through `--effort`; unknown effort metadata is not an allowlist
+or a reason to invent a level. Leave effort unspecified unless requested.
+
+Delegate uses CCR's foreground provider-only route. Model/provider setup and
+credentials belong to CCR. Never run `ccr launch`, configure CCR, inspect its
+SQLite database, call Claude directly, or select another integration to bypass a
+Delegate error. Ordinary questions about CCR or installation do not trigger
+external collaboration. An explicit request to use another integration remains
+an explicit user choice.