delegation-layer 0.1.19 → 0.1.21

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

@@ -56,6 +56,46 @@
       "name": "write-timeout",
       "prompt": "An authorized write task has status timed_out, publication unknown, no outcome, and continuation.resumable true.",
       "expected": ["delegate continue --task", "same state root", "new task id", "do not wait indefinitely for an outcome", "no fresh unrelated dispatch"]
+    },
+    {
+      "name": "admitted-without-explicit-exit-marker",
+      "prompt": "Dispatch returned task_record created, admission admitted, and a task_id. The shell output did not include a separate EXIT marker. Confirm the task and collect its result.",
+      "expected": ["use status with returned task_id", "read saved dispatch response if needed", "do not dispatch again to print an exit code", "exactly one admitted task for the assignment"]
+    },
+    {
+      "name": "supplied-root-across-shell-calls",
+      "prompt": "DELEGATE_ROOT is already set. Consult a separate external agent and answer its questions; each shell tool call starts a new shell.",
+      "expected": ["use supplied DELEGATE_ROOT on dispatch, status, collect, reply, steer, and continue", "resolve the same root in each shell call", "no invented task-specific root"]
+    },
+    {
+      "name": "pending-without-questions",
+      "prompt": "The admitted task is running. Collect exits 3 with pending publication, empty pending_requests, and no operational error.",
+      "expected": ["keep collecting the same task", "no ps or pgrep or process-tree inspection", "no supervisor commands", "no duplicate dispatch", "answer through delegate reply when a question appears"]
+    },
+    {
+      "name": "interactive-worker-assignment",
+      "prompt": "Consult a separate external agent about a pricing plan and answer its questions from README.md.",
+      "expected": ["brief assigns the pricing investigation directly", "worker does not recruit another external agent", "lead answers through delegate reply", "do not copy the orchestration request verbatim"]
+    },
+    {
+      "name": "interactive-clarification",
+      "prompt": "An external planning task returned pending.kind interaction with question IDs, choices, and free_text false. The requested preference is not in the user brief.",
+      "expected": ["read references/interaction.md", "ask user for missing preference", "reply through delegate with exact request and question IDs", "stable message ID", "continue collecting"]
+    },
+    {
+      "name": "interactive-steering",
+      "prompt": "The user adds guidance while an interactive external task is running and its capabilities advertise steering.",
+      "expected": ["delegate steer", "preserve task model permission and budget", "do not cancel and redispatch", "receipt is not completion"]
+    },
+    {
+      "name": "interactive-unknown-delivery",
+      "prompt": "A reply submission lost its CLI response. Its recorded delivery is unknown.",
+      "expected": ["same message ID and exact content to retrieve receipt", "no new message ID retry", "no native CLI bypass", "observe task"]
+    },
+    {
+      "name": "interactive-unsupported-destination",
+      "prompt": "A named external provider supports continuation but neither native clarification nor steering. The user wants a discussion with it.",
+      "expected": ["preserve named provider", "ordinary bounded turns and continuation", "explain no active-turn questions", "do not pass unsupported interactive flag"]
     }
   ]
 }

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/examples/json-results.md

@@ -1,8 +1,8 @@
 # JSON decision sketch
 
 ```sh
-delegate --root "$STATE_ROOT" status "$TASK_ID" --json
-delegate --root "$STATE_ROOT" collect "$TASK_ID" --watch 5s --json
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" status "$TASK_ID" --json
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" collect "$TASK_ID" --watch 5s --json
 ```
 
 Decision order:

package/skills/agent-integration/examples/read-only-task.md

@@ -1,10 +1,9 @@
 # Read-only task
 
 ```sh
-STATE_ROOT="${DELEGATE_ROOT:-$HOME/delegation-state}"
 BRIEF="$(mktemp)"
 printf '%s\n' 'Inspect the workspace and summarize the current test failures. Do not edit files.' >"$BRIEF"
-delegate --root "$STATE_ROOT" dispatch --auto \
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --auto \
   --brief "$BRIEF" --cwd "$PWD" --permission read-only --budget 15m --json
 ```
 

package/skills/agent-integration/examples/workspace-write-task.md

@@ -1,8 +1,7 @@
 # Authorized workspace write task
 
 ```sh
-STATE_ROOT="${DELEGATE_ROOT:-$HOME/delegation-state}"
-delegate --root "$STATE_ROOT" dispatch --auto \
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" dispatch --auto \
   --brief "$PWD/delegated-task.md" --cwd "$PWD" \
   --permission workspace-write --budget 30m --json
 ```

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 "${DELEGATE_ROOT:-$HOME/delegation-state}" 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 "${DELEGATE_ROOT:-$HOME/delegation-state}" 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

@@ -14,6 +14,9 @@ All paths passed to `--root`, `--cwd`, and `--brief` must be absolute. Add
 | `delegate status TASK --json` | Reconcile and observe task state | No provider launch |
 | `delegate collect TASK --watch 5s --json` | Read or wait for publication | No provider launch |
 | `delegate continue --task TASK ... --json` | Create an exact-session successor | Yes, at most once for the successor |
+| `delegate reply TASK --request ID --answers FILE --id MESSAGE_ID --json` | Answer a pending native question | No new launch |
+| `delegate steer TASK --brief FILE --id MESSAGE_ID --json` | Guide a supported active turn | No new launch |
+| `delegate events TASK --after SEQUENCE --watch 5s --json` | Read a bounded interaction event page | No |
 | `delegate logs TASK --json` | Return validated output descriptors | No |
 | `delegate cancel TASK --json` | Record one explicit stop request | Stops, does not relaunch |
 
@@ -30,9 +33,11 @@ Dispatch flags:
 - `--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`: provider-advertised choices (CCR requires a model alias);
-  Codex maps effort to TOML `model_reasoning_effort`, while Claude and AGY
+  Codex maps effort to TOML `model_reasoning_effort` for ordinary turns or a native
+  turn parameter for interactive turns, while Claude and AGY
   pass native effort flags; Pi maps effort to `--thinking`; OpenCode maps it to
   `--variant`; CCR forwards effort to Claude and uses `--model` as a CCR alias; `default` is omitted;
+- `--interactive`: enable advertised native clarification and steering; see [interaction](interaction.md);
 - `--native-timeout DURATION`: optional provider-native timeout where advertised.
 
 Model discovery uses the same `--provider ID` profiles and accepts an optional
@@ -47,12 +52,14 @@ Continuation flags:
 
 - `--task TASK`: predecessor task ID;
 - `--brief FILE`: optional new follow-up instruction;
-- `--budget DURATION`, `--model MODEL`, and `--effort VALUE`: optional overrides.
+- `--budget DURATION`, `--model MODEL`, and `--effort VALUE`: optional overrides;
+- `--interactive`: enable interaction when supported; already-interactive predecessors keep it.
 
 ## 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 +75,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/continuation.md

@@ -17,7 +17,7 @@ When `status` or `collect` reports a timed-out turn with:
 run:
 
 ```sh
-delegate --root "$STATE_ROOT" continue \
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" continue \
   --task PREDECESSOR_TASK_ID \
   --brief FOLLOW_UP_BRIEF \
   --budget 30m \

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

@@ -0,0 +1,110 @@
+# Questions and guidance during an active task
+
+Use this reference when an external task may need clarification or guidance
+before it finishes, including planning, consultation, and debate. Use only
+Delegate commands; do not open a terminal session with the provider.
+
+## Choose the transport
+
+Read the selected provider's `interaction` capability and
+`interaction.supported_modes`. `clarification` and `steering` are independent.
+Add `--interactive` to dispatch when the chosen provider and permission mode
+support the interaction you need. Keep the user's exact provider, model,
+effort, workspace, permission, and budget.
+
+Without a named provider, `dispatch --auto --interactive` selects among
+providers that support interaction. If a named provider does not support it,
+use ordinary bounded turns and `continue` for discussion when native
+continuation is available. Explain that questions cannot be answered during
+that provider's active turn. Never replace the requested provider silently.
+
+In the worker brief, explicitly request **native structured clarification**:
+"Use your native question tool to request clarification and await its answer.
+Do not ask only in final text or a progress message and then sleep: the lead
+can answer structured requests, not an unstructured prompt. If the question
+tool is unavailable, report that blocker and finish instead of waiting."
+Assign the actual work directly; the worker should not start another delegate.
+
+No change is needed for self-contained tasks that do not need mid-turn input.
+Continuation inherits interaction from its predecessor. `continue --task ID
+--interactive` can enable it for a previously ordinary task.
+
+## Respond to questions
+
+1. Save the admitted task ID and state root. Run `collect TASK_ID --watch 30s
+   --json` with that same root. Exit 3 is pending, not completion. Collection
+   returns early when there is an outstanding native question.
+2. Read `interaction.pending_requests`. Use the returned request ID, question
+   IDs, options, `multiple`, and `free_text`; do not invent or guess IDs.
+3. Answer facts already supplied by the user or verified during the task.
+   Ask the user for missing preferences, business decisions, new scope, or
+   authorization. Do not guess an answer to keep the worker moving. A question
+   reply does not approve tool access or change the task's permission mode.
+4. Write one JSON object mapping **every question ID in that request** to an
+   array of answer strings. A single-choice question takes one value. Use exact
+   option labels unless `free_text` permits another answer. Example:
+
+   ```json
+   {"color": ["Blue"], "sections": ["Summary", "Evidence"]}
+   ```
+
+5. Allocate a new 32-character lowercase hexadecimal message ID and save it
+   together with the exact answers. Submit once:
+
+   ```sh
+   delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" reply "$task_id" \
+     --request "$request_id" --answers "$answers_file" \
+     --id "$message_id" --json
+   ```
+
+6. Keep collecting. A receipt is not task completion. Only the task's
+   authoritative `outcome` establishes the final result.
+
+Use the same root expression for dispatch, collection, reply, and steering.
+If the user explicitly chose another root, use that exact path for all of
+them. The other variables stand for actual values saved from this task;
+reassign them in each shell invocation if your tool does not preserve variables.
+A pending response without questions means keep collecting, not inspect OS
+processes or dispatch a replacement task.
+
+## Guide active work
+
+When `interaction.capabilities.steering` is true and the task is active, put
+additional guidance in a brief file and submit:
+
+```sh
+delegate --root "${DELEGATE_ROOT:-$HOME/delegation-state}" steer "$task_id" \
+  --brief "$guidance_file" --id "$message_id" --json
+```
+
+Steering is guidance to the existing turn. It does not change provider, model,
+effort, workspace, permission, or budget. Once the turn ends, use `continue`
+for another authorized turn instead. Do not cancel and redispatch simply to
+send guidance.
+
+## Interpret delivery precisely
+
+| State | What it establishes |
+| --- | --- |
+| `queued` | Delegate durably accepted the message; native delivery is pending. |
+| `unknown` | Delivery was reserved or attempted, but its result is uncertain. |
+| `sent` | The native input write completed; no native acknowledgement is established. |
+| `acknowledged` | A correlated native response acknowledged the message. This does not prove the model followed guidance. |
+| `rejected` | The message could not be delivered or the native protocol rejected it. Read the reason. |
+
+If a submission response was lost, repeat the **same message ID and exact
+content** to recover its receipt. Never allocate a fresh ID to retry an
+`unknown` delivery. Delegate will not replay an ambiguous native write.
+Changed content with an existing ID is a conflict. Observe the task instead
+of guessing whether it consumed the message.
+
+`events TASK_ID --after SEQUENCE --watch 30s --json` returns a bounded event
+page. Save the returned `cursor` for the next page. Events and interaction
+state are progress evidence, not a replacement for `collect` and `outcome`.
+
+Waiting for an answer consumes the original execution budget; it does not
+pause or extend it. `interaction.deadline` shows the recorded wall-clock
+boundary when execution has started. If the task ends while waiting, do not
+reply to the old request. Follow the ordinary continuation guidance only when
+Delegate reports the task resumable. Preserve any verified answers in the new
+brief; uncertain delivery must not become an automatic replay.

package/skills/agent-integration/references/result-handling.md

@@ -17,8 +17,10 @@ the same as a successful provider result.
    the result and its payload/evidence descriptors.
 5. If `outcome.verdict` is rejected, report a terminal rejected result with its
    refusal and evidence. Do not retry automatically.
-6. Otherwise, if `liveness` is queued or running or publication is pending,
-   observe the same task again with a finite watch interval.
+6. If `pending.kind` is `interaction`, handle the returned questions using
+   [interaction guidance](interaction.md) before waiting again. Otherwise, if
+   `liveness` is queued or running or publication is pending, observe the same
+   task with a finite watch interval.
 7. If authentication is `blocked`, preserve that neutral state and tell the
    caller what prerequisite is unavailable without inventing a login command.
 8. Never relaunch an uncertain task by guessing. Observe only a task whose

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, pass --root \"${DELEGATE_ROOT:-$HOME/delegation-state}\" directly in each shell invocation; reuse that root for dispatch, observation, and continuation, never an invented /tmp root. If the user explicitly requests another root, use that exact path consistently. Keep each concurrent request and its response associated separately. Capture each dispatch response and exit status once; after task_record created, observe that task ID. Never dispatch again merely to recover output or inspect its exit status. 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. Pending work is observed through Delegate status, collect, or events, not OS process searches or supervisor commands. Merely discussing or configuring a tool is not delegation."

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

@@ -0,0 +1,26 @@
+#!/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")
+skill_file="$(CDPATH= cd -- "$script_dir/.." && pwd)/SKILL.md"
+DELEGATE_ROUTING_EVENT="$event" DELEGATE_ROUTING_RULE="$rule" DELEGATE_ROUTING_SKILL="$skill_file" awk '
+BEGIN {
+    # Paths are task data, not shell code. Escape every JSON control character.
+    for (i = 1; i < 32; i++) escapes[sprintf("%c", i)] = sprintf("\\u%04x", i)
+    escapes["\\"] = "\\\\"
+    escapes["\""] = "\\\""
+    path = ENVIRON["DELEGATE_ROUTING_SKILL"]
+    for (i = 1; i <= length(path); i++) {
+        character = substr(path, i, 1)
+        escaped = escaped ((character in escapes) ? escapes[character] : character)
+    }
+    # The maintained rule is a JSON string. Keep its escaping when prefixing it.
+    printf "{\"hookSpecificOutput\":{\"hookEventName\":\"%s\",\"additionalContext\":\"Read the complete agent-integration skill at %s. %s}}\n", ENVIRON["DELEGATE_ROUTING_EVENT"], escaped, substr(ENVIRON["DELEGATE_ROUTING_RULE"], 2)
+}'