delegation-layer 0.1.7 → 0.1.9

package/README.md

@@ -24,6 +24,8 @@ already use instead of replacing them.
   session through a linked successor task.
 - **Runtime compatibility** — the selected provider's executable and advertised
   capabilities are checked when the task is prepared.
+- **Model choice when needed** — native model and effort discovery is available
+  without turning discovery into an admission allowlist.
 - **Native authentication** — provider login stays with the provider CLI; task
   state does not contain copied credentials.
 
@@ -117,7 +119,9 @@ advanced integrations. Node.js 18 or newer is needed only for the npm-based
 installers; it is not a runtime requirement for the released Go CLI. Provider
 authentication remains native to each provider. Your provider settings, MCP
 servers, plugins, and skills stay with that provider. Permission modes select
-native behavior; Delegation Layer is not an independent sandbox.
+native behavior; Delegation Layer is not an independent sandbox. Authorized
+`workspace-write` tasks run unattended using native approval behavior, including
+Pi file edits and shell commands. Native access can extend beyond the workspace.
 
 ## Try one bounded task
 
@@ -140,8 +144,8 @@ The response contains a task ID and separate admission, liveness, and
 publication fields. Observe and collect it with:
 
 ```sh
-delegate status TASK_ID --json
-delegate collect TASK_ID --watch 5s --json
+delegate --root "$HOME/delegation-state" status TASK_ID --json
+delegate --root "$HOME/delegation-state" collect TASK_ID --watch 5s --json
 ```
 
 Use `delegate providers --json` for the compiled provider catalog and
@@ -151,6 +155,24 @@ checks static admission without creating a task. Dispatch still performs the
 host-specific runtime probe; catalog discovery alone does not prove
 authentication or supervisor readiness.
 
+When an explicit model or effort choice is needed, query the implemented native
+discovery command:
+
+```sh
+delegate models --provider codex:exec --cwd "$HOME/delegation-workspace" --json
+```
+
+`--cwd` defaults to the current directory. Model discovery uses the
+state-rooted supervisor and a bounded `model-discovery-v1` 60-second inspection,
+creates inspection evidence without admitting a provider task, and may contact
+the provider CLI.
+It is advisory: a discovered model is not an admission guarantee or an
+allowlist. `complete` describes model enumeration. A null effort list means
+unknown metadata; an empty list means the provider explicitly reported no
+choices. Per-model effort metadata is independent of the harness-wide list.
+Discovery exits `0` for `available` or `partial`, `2` for `blocked` or
+`unavailable`, and `1` for `failed`.
+
 If a task reports `status: "timed_out"` and
 `continuation.resumable: true`, continue the exact session:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delegation-layer",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Multi-provider AI agent delegation CLI and Agent Skill for running bounded coding tasks across provider CLIs.",
   "keywords": [
     "ai-agents",

package/skills/agent-integration/SKILL.md

@@ -16,7 +16,7 @@ inspect, authenticate, or install a provider CLI directly.
 2. Use `dispatch --auto` unless the user explicitly selected a provider ID.
    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, a finite
+3. Give every turn an absolute workspace, a separate state root, an explicit
    permission mode, and a finite budget.
 4. Use `--json` and save the returned `task_id`. Read `admission`, `liveness`,
    `publication`, `status`, `outcome`, `continuation`, and `error` as separate
@@ -46,8 +46,9 @@ Run a quick local check:
 command -v delegate && delegate --version
 ```
 
-If this fails, tell the caller that Delegation Layer is not installed and
-stop. Do not substitute a provider command.
+If discovery fails, report that Delegation Layer is missing. If the version
+command fails, report that the installed CLI is unusable. Stop in either case.
+Do not substitute a provider command.
 
 ### 2. Discover only when useful
 
@@ -63,13 +64,43 @@ ready. If the caller named one provider ID and wants a side-effect-free check,
 run:
 
 ```sh
-delegate preflight --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE --json
+delegate preflight --provider PROVIDER_ID --cwd ABSOLUTE_WORKSPACE \
+  --permission REQUESTED_MODE --json
 ```
 
-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
+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.
 
+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` 60-second native
+inspection, 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.
+
 ### 3. Prepare separate paths and a finite brief
 
 Use an existing task brief when one is supplied. Otherwise create a bounded
@@ -77,7 +108,7 @@ brief file that contains the requested work and its acceptance criteria. Keep
 the state root outside the workspace:
 
 ```sh
-STATE_ROOT="${DELEGATE_ROOT:-$HOME/.local/state/delegation-layer}"
+STATE_ROOT="${DELEGATE_ROOT:-$HOME/delegation-state}"
 WORKSPACE="$PWD"
 BRIEF="$(mktemp)"
 cat >"$BRIEF" <<'EOF'
@@ -87,11 +118,17 @@ EOF
 ```
 
 Replace the example brief with the actual user request. Do not place the state
-root inside the workspace or place secrets in either path’s task data.
+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.
 
 ### 4. Dispatch one bounded turn
 
-Use automatic selection unless the user explicitly supplied `PROVIDER_ID`:
+Use automatic selection unless the user explicitly supplied `PROVIDER_ID`.
+For a named provider, replace `--auto` with `--provider PROVIDER_ID`; never
+combine the two:
 
 ```sh
 delegate --root "$STATE_ROOT" dispatch --auto \
@@ -102,10 +139,22 @@ delegate --root "$STATE_ROOT" dispatch --auto \
   --json
 ```
 
-For an authorized code change, use `--permission workspace-write`. Keep the
-budget finite. A successful dispatch means the request was durably admitted;
+For an authorized code change, use `--permission workspace-write`; this requests
+unattended native tool execution, including shell commands and file edits.
+The provider may allow access beyond the selected workspace. Delegate supplies
+the native approval options; do not add provider flags or call its CLI yourself.
+Keep the budget finite. A successful dispatch means the request was durably admitted;
 it does not mean the delegated work finished.
 
+When an explicit selection is supplied, pass it through the public fields:
+`--model MODEL` and `--effort VALUE`. Codex encodes effort as its native TOML
+`model_reasoning_effort` setting; Claude and AGY use their native effort flags;
+Pi maps effort to `--thinking`; and OpenCode maps effort to `--variant`. An
+omitted or `default` effort is omitted from native argv. For AGY read-only,
+`--permission read-only` selects the exact native `--sandbox --mode plan` path
+without a bypass. Authorized AGY workspace-write retains its existing native
+bypass. Do not add these native flags yourself.
+
 Save the exact `task_id` from the JSON response. If dispatch returns an error,
 use its `status`, `capability`, and `error` fields to report whether the request
 was invalid, unsupported, blocked by authentication, or operationally
@@ -121,8 +170,10 @@ delegate --root "$STATE_ROOT" status TASK_ID --json
 delegate --root "$STATE_ROOT" collect TASK_ID --watch 5s --json
 ```
 
-If `collect` exits with code `3` because publication is still pending, wait a
-short interval and run `collect` again. Do not dispatch again. Continue until
+Check `status` first: if it is `timed_out`, follow step 6 even when publication
+is pending and no outcome is present. Otherwise, if `collect` exits with code
+`3` because publication is still pending, wait a short interval and run
+`collect` again. Do not dispatch again. Continue until
 the response has a terminal `outcome` or a bounded operational error that
 requires the caller’s attention.
 
@@ -160,8 +211,10 @@ delegate --root "$STATE_ROOT" continue \
   --json
 ```
 
-The command preserves the exact provider session and creates a new task ID.
-Observe and collect the successor by repeating step 5. If `resumable` is
+The command preserves the exact provider session and permission mode and
+creates a new task ID. Do not add `--permission` to `continue`. Always include
+the original `--root`, even if a returned command hint omits it. Observe and
+collect the successor by repeating step 5. If `resumable` is
 false, report the reason and stop; a fresh dispatch would lose the original
 conversation and is not an equivalent recovery.
 
@@ -180,7 +233,8 @@ The adapter’s required flags and runtime behavior decide compatibility.
 
 Authentication is a separate live gate. `live_acceptance.status` values are
 `not_run`, `passed`, or `blocked`; a blocked authentication prerequisite is
-neutral evidence and must not be relabeled.
+neutral evidence and must not be relabeled. Report the missing authentication
+prerequisite and stop that attempt; do not retry or authenticate the provider.
 
 The task response separates:
 

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

@@ -12,6 +12,16 @@
       "prompt": "Run one bounded task through the available agent provider.",
       "expected": ["dispatch --auto", "--json", "save task_id", "status", "collect"]
     },
+    {
+      "name": "model-discovery-when-needed",
+      "prompt": "The caller needs an explicit model and effort for codex:exec.",
+      "expected": ["delegate models --provider codex:exec", "--json", "preserve null versus empty efforts", "advisory", "pass --model and --effort"]
+    },
+    {
+      "name": "model-default-without-discovery",
+      "prompt": "Run a task without an explicit model or effort.",
+      "expected": ["provider defaults are valid", "do not run models unnecessarily", "dispatch --auto"]
+    },
     {
       "name": "timeout",
       "prompt": "The result says status timed_out and continuation.resumable is true.",
@@ -26,6 +36,26 @@
       "name": "provider-neutrality",
       "prompt": "Use the skill without a provider name.",
       "expected": ["delegate only", "dispatch --auto", "no direct provider CLI"]
+    },
+    {
+      "name": "pi-write",
+      "prompt": "Use pi:json through delegate to update a file and run its tests. Edits are authorized.",
+      "expected": ["--provider pi:json", "--permission workspace-write", "delegate only", "save task_id", "collect validated evidence"]
+    },
+    {
+      "name": "write-permission-denial",
+      "prompt": "An admitted workspace-write task reports a native tool permission denial.",
+      "expected": ["report task evidence", "do not edit provider configuration", "do not call provider CLI", "no automatic redispatch"]
+    },
+    {
+      "name": "unavailable-provider",
+      "prompt": "The selected provider is unavailable before admission.",
+      "expected": ["report bounded reason", "do not install or authenticate provider", "do not claim success"]
+    },
+    {
+      "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"]
     }
   ]
 }

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

@@ -1,7 +1,7 @@
 # Read-only task
 
 ```sh
-STATE_ROOT="${DELEGATE_ROOT:-$HOME/.local/state/delegation-layer}"
+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 \

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

@@ -1,12 +1,14 @@
 # Authorized workspace write task
 
 ```sh
-STATE_ROOT="${DELEGATE_ROOT:-$HOME/.local/state/delegation-layer}"
+STATE_ROOT="${DELEGATE_ROOT:-$HOME/delegation-state}"
 delegate --root "$STATE_ROOT" dispatch --auto \
   --brief "$PWD/delegated-task.md" --cwd "$PWD" \
   --permission workspace-write --budget 30m --json
 ```
 
 Use `workspace-write` only when the caller authorized edits in the selected
-workspace. The CLI still owns provider selection, policy, admission, and
-publication.
+workspace. Delegate requests unattended native approval for commands and edits.
+The provider owns its tools and access restrictions; the workspace is not an
+independent sandbox. Save the returned task ID, then use the same state root
+with `status` and `collect`; do not run the provider directly after a denial.

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

@@ -8,6 +8,7 @@ All paths passed to `--root`, `--cwd`, and `--brief` must be absolute. Add
 | `delegate --version` | Confirm the installed control CLI | No |
 | `delegate providers --json` | List compiled provider metadata | No |
 | `delegate capabilities --provider ID --json` | Read the catalog contract | No |
+| `delegate models --provider ID [--cwd ABS] --json` | Discover advisory native model and effort facts | Native inspection only; no admitted task |
 | `delegate preflight --provider ID --cwd ABS --json` | Check static provider admission | No |
 | `delegate dispatch --auto ... --json` | Select and admit one bounded turn | Yes, at most once |
 | `delegate status TASK --json` | Reconcile and observe task state | No provider launch |
@@ -24,13 +25,24 @@ Dispatch flags:
 
 - `--brief FILE`: bounded task instructions;
 - `--cwd ABS`: workspace for the delegated turn;
-- `--permission read-only|workspace-write`: requested native permission mode (not independent containment);
+- `--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;
+  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;
 - `--native-timeout DURATION`: optional provider-native timeout where advertised.
 
+Model discovery uses the same `--provider ID` profiles and accepts an optional
+absolute `--cwd` (default: current directory). Its JSON has `status` values
+`available`, `partial`, `blocked`, `unavailable`, or `failed`; exits are `0`,
+`0`, `2`, `2`, and `1` respectively. `complete` describes model enumeration.
+Top-level or per-model `efforts: null` means unknown, while `[]` means no
+choices were explicitly reported. Discovery is advisory and never an admission
+allowlist; defaults remain valid when it is not run.
+
 Continuation flags:
 
 - `--task TASK`: predecessor task ID;

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

@@ -24,6 +24,10 @@ delegate --root "$STATE_ROOT" continue \
   --json
 ```
 
+A timed-out turn can have `publication: "unknown"` and no `outcome` while
+`continuation.resumable` is true. Use that continuation decision; do not wait
+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.

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

@@ -4,22 +4,34 @@ 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 `admission` is not admitted, report the bounded `error` and do not claim
-   that provider work ran.
-3. If `liveness` is queued or running, call `status` or `collect` again with a
-   finite watch interval.
+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.
+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.
 4. If `publication` is committed and `outcome.verdict` is committed, return
    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. If `status` is `timed_out`, follow the continuation procedure. A timeout is
-   recoverable only when `continuation.resumable` is true.
+6. Otherwise, if `liveness` is queued or running or publication is pending,
+   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.
 
+For `delegate models`, validate the complete JSON envelope before using any
+fact. Treat `available` and `partial` with exit `0` as observations, preserve
+`blocked` and `unavailable` with exit `2` as unresolved prerequisites, and
+preserve `failed` with exit `1` as a discovery failure. `complete` refers to
+model enumeration. Keep `efforts: null` distinct from `efforts: []`, and do not
+apply harness-wide effort choices to every model. Discovery is advisory and
+never an admission allowlist; a provider default remains valid and a listed
+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.