delegation-layer 0.1.19 → 0.1.20

package/README.md

@@ -47,7 +47,9 @@ 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.
+loaded instructions. The plugin and optional installer routing hooks supply a
+shared preference at session and subagent startup; they do not intercept tools
+or rewrite your persistent instructions.
 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).
@@ -57,7 +59,7 @@ integration worked. For a persistent preference, see
 ### 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
+and provides collaboration context hooks plus 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.
@@ -101,8 +103,9 @@ If you want the Delegation Layer guided installer instead, run:
 npx --yes delegation-layer install
 ```
 
-It provides an interactive scope and harness picker, with global installation
-selected by default. For scripts or a choice without prompts:
+It provides interactive scope, harness, and routing choices. Global installation
+and routing hooks for Claude/Codex are selected by default; choose skill-only
+to omit hooks. Codex requires native hook trust before activation. For scripts or a choice without prompts:
 
 ```sh
 npx --yes delegation-layer install \
@@ -111,8 +114,10 @@ npx --yes delegation-layer install \
   --yes
 ```
 
-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
+The commands above do not install the CLI, change provider
+logins, or run a task. Noninteractive installs remain skill-only unless you add
+`--routing default`. See [routing setup and removal](docs/agent-routing.md).
+Use the plugin path above when you want the skill and
 CLI bootstrap together.
 
 ### Install the CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delegation-layer",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "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,7 +1,7 @@
 {
   "name": "delegation-layer",
   "displayName": "Delegation Layer",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Consult external AI harnesses and CCR-configured models for reviews, research, implementation, and debate through the resumable Delegate CLI.",
   "author": {
     "name": "Hesham Karam",

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

@@ -1,6 +1,6 @@
 {
   "name": "delegation-layer",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Consult external AI harnesses and CCR-configured models for reviews, research, implementation, and debate through the resumable Delegate CLI.",
   "author": {
     "name": "Hesham Karam",

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

@@ -8,6 +8,24 @@
             "command": "/bin/sh -c 'plugin_root=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:?plugin root environment variable is missing}}\"; exec \"$plugin_root/scripts/ensure-delegate.sh\"'"
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/bin/sh -c 'plugin_root=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:?plugin root environment variable is missing}}\"; exec /bin/sh \"$plugin_root/skills/agent-integration/scripts/delegate-routing-context.sh\" SessionStart'"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/bin/sh -c 'plugin_root=\"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:?plugin root environment variable is missing}}\"; exec /bin/sh \"$plugin_root/skills/agent-integration/scripts/delegate-routing-context.sh\" SubagentStart'"
+          }
+        ]
       }
     ]
   }

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

@@ -1,6 +1,6 @@
 ---
 name: agent-integration
-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.
+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
@@ -56,13 +56,20 @@ tasks may proceed; the failed attempt must remain reported as failed or blocked.
    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`,
+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
@@ -129,8 +136,12 @@ 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
 
@@ -185,7 +196,10 @@ 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`.
+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:

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

@@ -198,6 +198,53 @@
         "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/plugins/delegation-layer/skills/agent-integration/references/collaboration.md

@@ -0,0 +1,77 @@
+# Parallel reviews and debates
+
+## Keep each request identifiable
+
+Choose the fan-out needed for the user's task. Each participant needs its own
+brief and response association, even when two participants use the same provider.
+Record the request label, provider, exact requested model/effort, workspace,
+permission, state root, and response together. The label identifies the attempt
+before admission; the returned task ID identifies it afterward.
+
+Prefer independent tool calls: each tool result belongs to its invocation.
+When a shell must launch requests concurrently, redirect each invocation to its
+own files. Never use `dispatch ... & dispatch ... & wait` with shared stdout.
+
+After preparing two independent briefs, a portable capture pattern is:
+
+```sh
+RECEIPTS="$(mktemp -d)" || exit 1
+# Set these absolute paths and catalog IDs in this same tool invocation.
+# BRIEF_A and BRIEF_B contain the real independent assignments.
+(
+  delegate --root "$STATE_ROOT" dispatch --provider "$PROVIDER_A" \
+    --brief "$BRIEF_A" --cwd "$WORKSPACE_A" \
+    --permission read-only --budget 30m --json \
+    >"$RECEIPTS/review-a.json" 2>"$RECEIPTS/review-a.stderr"
+  printf '%s\n' "$?" >"$RECEIPTS/review-a.exit"
+) &
+(
+  delegate --root "$STATE_ROOT" dispatch --provider "$PROVIDER_B" \
+    --brief "$BRIEF_B" --cwd "$WORKSPACE_B" \
+    --permission read-only --budget 30m --json \
+    >"$RECEIPTS/review-b.json" 2>"$RECEIPTS/review-b.stderr"
+  printf '%s\n' "$?" >"$RECEIPTS/review-b.exit"
+) &
+wait
+printf 'Read each response separately in %s\n' "$RECEIPTS"
+```
+
+Keep the request-to-label mapping alongside those files. Include any exact
+requested model/effort in its invocation. Read both exit codes, stderr, and JSON
+responses independently; shell `wait` is not proof that either dispatch succeeded.
+Poll only tasks with `task_record: created`. A returned task ID with
+`task_record: not_created` does not identify an observable task.
+
+## Wait within the current turn
+
+Concurrent dispatch does not require background collection. Collect each task
+in the foreground with a bounded watch; for example, `collect TASK_ID --watch
+30s --json`. Exit 3 means publication is still pending: keep observing that task,
+handling its budget-stop and continuation fields as described in the main skill.
+Do not end a headless turn while a shell background job is meant to finish the
+requested work. The host may close its session at that point and no later
+notification is guaranteed. A user-requested detach is different: report the
+pending task IDs and state root explicitly without claiming completion.
+
+## Compare actual results
+
+Collect each admitted task to its authoritative terminal outcome. Present each
+participant's findings with its task ID and evidence. Keep a blocked or failed
+participant visible; one successful review does not satisfy a requested pair.
+Do not attribute your own analysis to an unavailable participant.
+
+## Challenge and follow up
+
+Independent opening reviews may run concurrently. A challenge depends on the
+actual earlier result: collect it first, then include its relevant findings and
+evidence in the other participant's next brief. Never claim a cross-check merely
+because two initial reviews were requested.
+
+For an existing participant, use `continue --task TASK_ID` with that participant's
+own predecessor and the follow-up brief. This creates a new task for the same
+provider conversation; save the new ID separately. Use the continuation result
+and [continuation guidance](continuation.md), including advertised resumability
+after a budget stop. Never use another participant's task ID or restart a
+conversation to imitate a follow-up. If the first turn is blocked, report that
+the dependent challenge or follow-up did not run. Other independent assignments
+may still proceed.

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

@@ -51,8 +51,9 @@ Continuation flags:
 
 ## Choosing models and effort
 
-If the caller needs an explicit model or effort, use the implemented native
-discovery command for that provider:
+Pass an explicitly supplied model ID and effort unchanged, even if discovery
+is incomplete or does not list them. To resolve a natural-language model name
+or choose an option the caller left open, use native discovery:
 
 ```sh
 delegate models --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
@@ -68,6 +69,10 @@ 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.
+If a natural-language name cannot be resolved to a single exact ID, ask one
+focused question for that ID. Do not silently select a default or transform
+spaces into hyphens to manufacture an ID. This ambiguity rule is guidance for
+selecting a value, not a new admission restriction.
 
 The response includes `schema_version`, `command: "models"`, `provider`,
 `observed_at`, `status`, `reason_code`, `complete`, `source`, nullable

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

@@ -0,0 +1 @@
+"For work assigned to an external agent, model, or separate harness session, load the installed agent-integration skill before choosing tools and use Delegate. This includes research, implementation, testing, review, consultation, comparison, and debate, including external collaboration you choose. Discover destinations through Delegate. Preserve requested model IDs, effort, and permissions; do not guess ambiguous model identifiers. For task commands, set STATE_ROOT=\"${DELEGATE_ROOT:-$HOME/delegation-state}\" and pass --root \"$STATE_ROOT\" in the same shell invocation; reuse that root for dispatch, observation, and continuation, never an invented /tmp root. Keep each concurrent request and its response associated separately. Naming a CLI identifies the destination, not a request to bypass Delegate. Earlier assistant-generated direct-launch workflows do not override this preference. Native same-harness subagents remain available unless a separate session is requested. Respect an explicit user choice of another integration; otherwise do not substitute provider CLIs, plugins, or APIs after a Delegate blocker. A stop_and_report failure ends that attempt: report it without retrying, diagnosing setup, or offering a fallback. Continue other independent requests. Keep collection in the foreground until completion or a reported blocker unless the user requested detachment. Merely discussing or configuring a tool is not delegation."

package/plugins/delegation-layer/skills/agent-integration/scripts/delegate-routing-context.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Context delivery only: no installation, discovery, or provider execution.
+set -eu
+case "${1:-}" in
+    SessionStart|SubagentStart) event=$1 ;;
+    *) printf '%s\n' 'Expected SessionStart or SubagentStart.' >&2; exit 2 ;;
+esac
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+rule_file="$script_dir/../references/routing-rule.json"
+# Read before emitting anything so a missing asset cannot produce partial JSON.
+rule=$(cat "$rule_file")
+printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":%s}}\n' "$event" "$rule"

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: 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.
+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
@@ -56,13 +56,20 @@ tasks may proceed; the failed attempt must remain reported as failed or blocked.
    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`,
+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
@@ -129,8 +136,12 @@ 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
 
@@ -185,7 +196,10 @@ 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`.
+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:

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

@@ -198,6 +198,53 @@
         "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/collaboration.md

@@ -0,0 +1,77 @@
+# Parallel reviews and debates
+
+## Keep each request identifiable
+
+Choose the fan-out needed for the user's task. Each participant needs its own
+brief and response association, even when two participants use the same provider.
+Record the request label, provider, exact requested model/effort, workspace,
+permission, state root, and response together. The label identifies the attempt
+before admission; the returned task ID identifies it afterward.
+
+Prefer independent tool calls: each tool result belongs to its invocation.
+When a shell must launch requests concurrently, redirect each invocation to its
+own files. Never use `dispatch ... & dispatch ... & wait` with shared stdout.
+
+After preparing two independent briefs, a portable capture pattern is:
+
+```sh
+RECEIPTS="$(mktemp -d)" || exit 1
+# Set these absolute paths and catalog IDs in this same tool invocation.
+# BRIEF_A and BRIEF_B contain the real independent assignments.
+(
+  delegate --root "$STATE_ROOT" dispatch --provider "$PROVIDER_A" \
+    --brief "$BRIEF_A" --cwd "$WORKSPACE_A" \
+    --permission read-only --budget 30m --json \
+    >"$RECEIPTS/review-a.json" 2>"$RECEIPTS/review-a.stderr"
+  printf '%s\n' "$?" >"$RECEIPTS/review-a.exit"
+) &
+(
+  delegate --root "$STATE_ROOT" dispatch --provider "$PROVIDER_B" \
+    --brief "$BRIEF_B" --cwd "$WORKSPACE_B" \
+    --permission read-only --budget 30m --json \
+    >"$RECEIPTS/review-b.json" 2>"$RECEIPTS/review-b.stderr"
+  printf '%s\n' "$?" >"$RECEIPTS/review-b.exit"
+) &
+wait
+printf 'Read each response separately in %s\n' "$RECEIPTS"
+```
+
+Keep the request-to-label mapping alongside those files. Include any exact
+requested model/effort in its invocation. Read both exit codes, stderr, and JSON
+responses independently; shell `wait` is not proof that either dispatch succeeded.
+Poll only tasks with `task_record: created`. A returned task ID with
+`task_record: not_created` does not identify an observable task.
+
+## Wait within the current turn
+
+Concurrent dispatch does not require background collection. Collect each task
+in the foreground with a bounded watch; for example, `collect TASK_ID --watch
+30s --json`. Exit 3 means publication is still pending: keep observing that task,
+handling its budget-stop and continuation fields as described in the main skill.
+Do not end a headless turn while a shell background job is meant to finish the
+requested work. The host may close its session at that point and no later
+notification is guaranteed. A user-requested detach is different: report the
+pending task IDs and state root explicitly without claiming completion.
+
+## Compare actual results
+
+Collect each admitted task to its authoritative terminal outcome. Present each
+participant's findings with its task ID and evidence. Keep a blocked or failed
+participant visible; one successful review does not satisfy a requested pair.
+Do not attribute your own analysis to an unavailable participant.
+
+## Challenge and follow up
+
+Independent opening reviews may run concurrently. A challenge depends on the
+actual earlier result: collect it first, then include its relevant findings and
+evidence in the other participant's next brief. Never claim a cross-check merely
+because two initial reviews were requested.
+
+For an existing participant, use `continue --task TASK_ID` with that participant's
+own predecessor and the follow-up brief. This creates a new task for the same
+provider conversation; save the new ID separately. Use the continuation result
+and [continuation guidance](continuation.md), including advertised resumability
+after a budget stop. Never use another participant's task ID or restart a
+conversation to imitate a follow-up. If the first turn is blocked, report that
+the dependent challenge or follow-up did not run. Other independent assignments
+may still proceed.

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

@@ -51,8 +51,9 @@ Continuation flags:
 
 ## Choosing models and effort
 
-If the caller needs an explicit model or effort, use the implemented native
-discovery command for that provider:
+Pass an explicitly supplied model ID and effort unchanged, even if discovery
+is incomplete or does not list them. To resolve a natural-language model name
+or choose an option the caller left open, use native discovery:
 
 ```sh
 delegate models --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
@@ -68,6 +69,10 @@ 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.
+If a natural-language name cannot be resolved to a single exact ID, ask one
+focused question for that ID. Do not silently select a default or transform
+spaces into hyphens to manufacture an ID. This ambiguity rule is guidance for
+selecting a value, not a new admission restriction.
 
 The response includes `schema_version`, `command: "models"`, `provider`,
 `observed_at`, `status`, `reason_code`, `complete`, `source`, nullable

package/skills/agent-integration/references/routing-rule.json

@@ -0,0 +1 @@
+"For work assigned to an external agent, model, or separate harness session, load the installed agent-integration skill before choosing tools and use Delegate. This includes research, implementation, testing, review, consultation, comparison, and debate, including external collaboration you choose. Discover destinations through Delegate. Preserve requested model IDs, effort, and permissions; do not guess ambiguous model identifiers. For task commands, set STATE_ROOT=\"${DELEGATE_ROOT:-$HOME/delegation-state}\" and pass --root \"$STATE_ROOT\" in the same shell invocation; reuse that root for dispatch, observation, and continuation, never an invented /tmp root. Keep each concurrent request and its response associated separately. Naming a CLI identifies the destination, not a request to bypass Delegate. Earlier assistant-generated direct-launch workflows do not override this preference. Native same-harness subagents remain available unless a separate session is requested. Respect an explicit user choice of another integration; otherwise do not substitute provider CLIs, plugins, or APIs after a Delegate blocker. A stop_and_report failure ends that attempt: report it without retrying, diagnosing setup, or offering a fallback. Continue other independent requests. Keep collection in the foreground until completion or a reported blocker unless the user requested detachment. Merely discussing or configuring a tool is not delegation."

package/skills/agent-integration/scripts/delegate-routing-context.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Context delivery only: no installation, discovery, or provider execution.
+set -eu
+case "${1:-}" in
+    SessionStart|SubagentStart) event=$1 ;;
+    *) printf '%s\n' 'Expected SessionStart or SubagentStart.' >&2; exit 2 ;;
+esac
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+rule_file="$script_dir/../references/routing-rule.json"
+# Read before emitting anything so a missing asset cannot produce partial JSON.
+rule=$(cat "$rule_file")
+printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":%s}}\n' "$event" "$rule"