delegation-layer 0.1.17 → 0.1.19

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

@@ -28,11 +28,11 @@ Dispatch flags:
 - `--permission read-only|workspace-write`: read-only investigation or authorized unattended write execution, including commands (not independent containment);
 - `--budget DURATION`: finite turn budget;
 - `--auto`: let the CLI select a ready provider;
-- `--provider ID`: use only when the caller explicitly selected an ID;
-- `--model MODEL` and `--effort VALUE`: optional provider-advertised choices;
+- `--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
   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
@@ -48,3 +48,51 @@ Continuation flags:
 - `--task TASK`: predecessor task ID;
 - `--brief FILE`: optional new follow-up instruction;
 - `--budget DURATION`, `--model MODEL`, and `--effort VALUE`: optional overrides.
+
+## Choosing models and effort
+
+If the caller needs an explicit model or effort, use the implemented native
+discovery command for that provider:
+
+```sh
+delegate models --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
+```
+
+Omit `--cwd` to use the current directory. Run discovery only when the caller
+needs a non-default choice; provider defaults are valid. The command uses the
+state-rooted supervisor and a bounded `model-discovery-v1` five-minute native
+inspection to allow first-run provider model/cache initialization. It creates
+inspection evidence without admitting a provider task, and may contact the
+provider CLI. It is advisory and never an admission allowlist. Do not reject a
+requested value merely because discovery did not list it, and do not infer
+per-model effort support from the harness-wide list. If a selected model has
+`efforts: null` or `efforts: []`, omit `--effort` unless the caller explicitly
+requested it; do not invent model aliases or combine options by guessing.
+
+The response includes `schema_version`, `command: "models"`, `provider`,
+`observed_at`, `status`, `reason_code`, `complete`, `source`, nullable
+`efforts`, and model rows with exact `id` values plus optional `name`, nullable
+`efforts`, and optional `default_effort`. `complete` describes model
+enumeration, not effort metadata. `null` means effort metadata is unknown;
+`[]` means the provider explicitly reported no choices. Discovery exits `0`
+for `available` or `partial`, `2` for `blocked` or `unavailable`, and `1` for
+`failed`. Preserve a blocked or unavailable discovery result as unresolved;
+defaults remain allowed.
+
+## 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/continuation.md

@@ -30,7 +30,10 @@ indefinitely for a publication that the interrupted turn cannot complete.
 
 The follow-up brief is optional. If it is omitted, Delegation Layer reuses the
 validated predecessor brief. A successful continuation returns a new task ID
-and links it to the predecessor. Observe and collect the new ID separately.
+and links it to the predecessor. Observe and collect the new ID separately. Always retain the original state
+root, even if a returned command hint omits it. Permission is inherited; do not
+add `--permission` to `continue`. Apply the dispatch `task_record` error rules
+in [result handling](result-handling.md) before retrying or observing.
 
 `mode` describes the provider contract:
 

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

@@ -4,10 +4,12 @@ Use the response fields independently. A successful control command is not
 the same as a successful provider result.
 
 1. Save `task_id` immediately after dispatch or continue.
-2. If a dispatch or continue response does not confirm admission, preserve any
-   task ID and report its bounded error. An uncertain admission must be
-   inspected, never automatically dispatched again. Status and collect can
-   report `admission: "unknown"` alongside valid terminal evidence.
+2. For a dispatch or continue error, inspect `task_record` first. When it is
+   `created`, observe the returned ID with `status`. When it is `not_created`,
+   do not poll; correct the request only if `failure.next_action` is
+   `correct_request`, otherwise report and stop. When it is `unknown`, stop and
+   report without polling or retrying. Status and collect can report
+   `admission: "unknown"` alongside valid terminal evidence for an existing task.
 3. If `status` is `timed_out`, follow the continuation procedure before treating
    pending publication as a reason to wait. `continuation.resumable: true`
    permits a linked successor even when no outcome has been published.
@@ -19,9 +21,8 @@ the same as a successful provider result.
    observe the same task again 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. If a command reports an operational uncertainty, inspect the original task
-   with `status` and `collect` before considering any action. Never relaunch an
-   uncertain task by guessing.
+8. Never relaunch an uncertain task by guessing. Observe only a task whose
+   record is known to exist; the `task_record` decision above takes precedence.
 
 For `delegate models`, validate the complete JSON envelope before using any
 fact. Treat `available` and `partial` with exit `0` as observations, preserve
@@ -35,3 +36,9 @@ model is not an execution guarantee.
 Exit codes are bounded control signals: `0` is a completed command, `1` is an
 operational error, `2` is an invalid or unsupported request, `3` is a pending
 collection watch, and `4` is a validated rejected outcome.
+
+Catalog facts (`verification: "catalog"`) are not runtime proof. Preflight
+checks static readiness; runtime verification requires the supervised probe.
+Versions and help are observations, not semantic-version allowlists.
+Authentication is a separate live gate (`not_run`, `passed`, or `blocked`).
+Report a blocked prerequisite without inventing a login command or retrying.