delegation-layer 0.1.18 → 0.1.20

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

@@ -29,10 +29,10 @@ Dispatch flags:
 - `--budget DURATION`: finite turn budget;
 - `--auto`: let the CLI select a ready provider;
 - `--provider ID`: preserve the caller’s named harness or provider, resolved through the catalog;
-- `--model MODEL` and `--effort VALUE`: optional provider-advertised choices;
+- `--model MODEL` and `--effort VALUE`: provider-advertised choices (CCR requires a model alias);
   Codex maps effort to TOML `model_reasoning_effort`, while Claude and AGY
   pass native effort flags; Pi maps effort to `--thinking`; OpenCode maps it to
-  `--variant`; `default` is omitted;
+  `--variant`; CCR forwards effort to Claude and uses `--model` as a CCR alias; `default` is omitted;
 - `--native-timeout DURATION`: optional provider-native timeout where advertised.
 
 Model discovery uses the same `--provider ID` profiles and accepts an optional
@@ -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
@@ -78,3 +83,21 @@ enumeration, not effort metadata. `null` means effort metadata is unknown;
 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.
+
+## Checking readiness
+
+Use `preflight` when the caller asks about static readiness, rather than as a
+required step before every dispatch:
+
+```sh
+delegate preflight --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE \
+  --permission REQUESTED_MODE --json
+```
+
+Use `read-only` for investigation or `workspace-write` for authorized edits.
+Supply any required provider options, including `--model ALIAS` for `ccr:print`.
+Preflight does not create a task, start the supervisor, or launch a provider.
+Its result is not proof of live authentication or successful execution. Report
+`blocked` or `unsupported` results; a readiness request does not authorize
+provider configuration changes. Honor `failure.next_action` without probing
+provider CLIs yourself.

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"