Delegate runs self-contained work in a fresh, ephemeral child Pi and restricts every child launch to an operator-approved model.

Requires Piclaw >=1.8.0.

Version 0.2.20 makes explicit built-in tool lists MCP-none (no adapter load or MCP hint), disables default extensions during model discovery, recognises additional credential/refresh failures before fallback, and fences the total deadline immediately before each launch. Named profiles keep the existing wrapper default. See issue #160 offline qualification for Pi 1.1.0 evidence and unproved real-provider/auth limits. Version 0.2.19 supplied the parent-owned POSIX group anchor; descendants escaping its group remain outside that cleanup guarantee.

Version 0.2.18 passes the parent's current thinking level to each plain child subprocess, including fallback attempts. Pi applies the selected model's supported levels. Model approval, tools, timeouts and process cleanup are unchanged.

Version 0.2.17 resolves the child Pi CLI from the running Piclaw release before add-on-local dependencies, including portable releases and symlinked launchers. PI_DELEGATE_CLI remains the highest-priority explicit override. A recognised Piclaw release with a missing/invalid Pi manifest fails rather than silently launching another version; standalone fallback remains available outside Piclaw. Discovery and execution share one selected CLI, and cache entries cannot cross CLI path/package-version/file-identity changes. Settings reports the selected path and manifest version. Authentication and MCP qualification remain separate.

Version 0.2.15 follows the installed Pi package's public bin.pi entry instead of guessing dist/cli.js. Pi 1.0.0 publishes dist/bundle/cli.js; valid older manifests still work. This resolver change does not qualify child authentication, selected-engine MCP or the full Pi 1.0.0 migration. See historical CLI resolver evidence and current Pi 1.0.3 synthetic qualification. The current CLI/auth receipts do not qualify production credential/environment inheritance, raw cleanup settlement or account-generation authority.

Version 0.2.14 prepares exact gpt-6.1-sol recognition at tier 3, with the same selection preference as GPT-6 Sol. Provider approval, exact child-CLI discovery, exclusions and confirmed image support remain required. Coverage uses synthetic catalogue/child fixtures; GPT-6.1 Sol is not yet in this instance's runtime registry and has not been live-qualified. No preview, pro, mini, routed or batch variants are inferred.

Version 0.2.13 labels progress with each call's start-order ordinal and the number of calls started in its group (Delegate (2 of 3)). The total grows as calls start; completed calls do not reduce it or renumber survivors. Child retries and model fallback keep the same ordinal. Numbering resets after the last call exits, independently for each session. The parent add-on supplies these labels; no child prompt, host UI or settings changes are required.

Version 0.2.11 adds exact Earendil 0.87.1 catalogue coverage for GPT-6 Sol/Luna and Grok 4.7 at tier 3; Claude Opus 5.5 remains tier 5. Unknown suffixes remain unclassified, and no provider becomes approved automatically. The catalogue and JSON-mode fixtures are qualified offline in Earendil 0.87.1 evidence.

Approved-model boundary

Delegate can launch a model only when all four conditions hold:

1. An operator marked its provider Approved in Settings → Delegate. No provider is approved by default.
2. Its model ID matches one ordered, code-reviewed classification rule.
3. The child pi --list-models catalog contains the exact provider/model ID.
4. No provider or model exclusion denies it.

The Settings pane lists the resulting Approved delegate models. That list is the execution allowlist for automatic selection, an agent-supplied model, and fallback attempts. Agents cannot expand it through the delegate tool arguments, prompts, custom system prompts, or fallback errors. If a provider discloses a different message or response model, Delegate accepts the result only when that exact model is also approved.

Behaviour

• Verified model catalogs — Piclaw's runtime registry supplies capability metadata; exact child pi --list-models entries establish executability.
• Deterministic policy — every recognized model has one family, one tier, one ordered rule, and a classification reason. Unknown models fail closed.
• Approved providers — an unset or empty provider list approves nothing. Newly discovered providers remain denied until an operator approves them.
• Tier-safe automatic selection — automatic delegation never selects above the verified current-model tier.
• Exact explicit selection — model can choose an exact member of the approved list and bypass automatic tier selection. It cannot bypass provider approval, classification, exclusions, executability, or image-capability checks.
• Pre-spawn enforcement — Delegate checks the approved list immediately before every child process launch, including fallback attempts.
• Capability filtering — image input requires catalog-confirmed image support. Reasoning, context-window, and output-limit metadata are retained for diagnostics.
• Ephemeral structured execution — the child runs with --mode json --no-session --no-extensions; Delegate parses structured messages, tool progress, usage, model, stop reason, and errors.
• Bounded lifecycle — one total deadline covers all fallback attempts; cancellation terminates the process tree, output buffers are bounded, and no child session is persisted.
• Restricted fallback — automatic retry occurs only for classified provider setup or model-unavailable failures. Authentication, expiry and logout stop without account/provider fallback. A non-zero exit never succeeds merely because partial text was emitted.
• Narrow tool loading — Delegate loads Pi's requested core tool profile plus the explicitly discovered MCP adapter; it does not inherit or scan arbitrary workspace/add-on extensions.
• Catalog diagnostics — Settings shows runtime/CLI counts, eligible and runtime-only models, unclassified/rejected models and reasons, cache age, refresh failures, capabilities, and effective exclusions.

Installation

Open Settings → Add-Ons, install Delegate, then reload Piclaw when convenient. Installing or updating the package does not activate new code until Piclaw reloads.

Delegate self-activates after reload. It may also be listed explicitly in .piclaw/config.json:

{
  "tools": {
    "additionalDefaultTools": ["delegate"]
  }
}

Usage

delegate({
  prompt: "Summarize the public API and list compatibility risks.",
  files: ["src/client.ts"],
  task_category: "summarize"
})

Task categories

The requested tier is capped at the current model's verified tier. If that tier has no eligible model, Delegate searches lower tiers. Judge mode crosses families only when an eligible alternative exists.

Tool profiles

Named profiles append the discovered MCP adapter when available. A custom comma-separated list of child Pi built-ins is also accepted and loads no MCP bridge unless it explicitly includes mcp. A named tool must exist in the child; installed Piclaw add-on tools are not inherited automatically.

Explicit model selection

delegate({
  prompt: "Review this implementation.",
  task_category: "analyze",
  model: "github-copilot/gpt-5.4-mini"
})

The ID must appear in Settings → Delegate → Approved delegate models. Explicit selection can bypass the automatic tier choice, but it cannot use an unapproved provider, an unclassified or excluded model, a runtime-only model, or a model without the required image capability.

Files

• Text files are UTF-8-inlined up to 100 KiB each.
• Native raster attachments are accepted only after content sniffing: JPEG, PNG, GIF, WebP, and BMP.
• Extensions do not determine attachment type; spoofed files are rejected.
• PDF, SVG, TIFF/ICO, archives, audio, video, and unknown binary data are rejected with conversion or tool-reading guidance.
• Canonical paths must remain under /workspace; symlinks cannot escape it, and non-regular files are rejected before sniffing.

For a PDF or Office document, extract it with the appropriate Piclaw tool and delegate the resulting text. Convert unsupported images to PNG, JPEG, GIF, WebP, or BMP first.

Settings API

The browser pane reads configuration from /agent/addons/api/delegate/config and model diagnostics from /agent/addons/api/delegate/models. Both are authenticated local Piclaw endpoints; Delegate stores no secrets.

Each discovered provider has one mutually exclusive mode: Approved or Exclude. Changing modes writes a complete partition to the persisted searchable_providers and excluded_providers fields. The legacy field name searchable_providers now stores the operator-approved provider list. A missing or empty list approves no providers.

The pane opts into the shared settings-addon-* controls from Piclaw #1318. It keeps pane-owned catalogue cards, wrapping provider rows and bounded scroll lists. A pane-scoped fallback CSS layer keeps older supported hosts readable; host styles take precedence when available. Save payloads, failed-save rollback, refresh behaviour and approval rules are unchanged.

settings-browser.test.ts checks these interactions through mocked APIs in Classic, Visual and a standalone older-host fixture. From the repository root, set PICLAW_E2E_DISPOSABLE=1, PICLAW_SETTINGS_CORE_SOURCE=/absolute/path/to/piclaw and an installed PLAYWRIGHT_BROWSERS_PATH, then run bun test addons/delegate/settings-browser.test.ts. No child delegate or provider is invoked by these browser tests.

Model catalogs and caching

Delegate keeps these roles separate:

1. Runtime catalog — ctx.modelRegistry; capability metadata and the current model.
2. Executable catalog — child pi --list-models; the only source of subprocess candidates.
3. Current model — classified independently to establish the automatic tier ceiling.

Executable discovery is cached for 60 seconds. A manual Settings refresh invalidates it. Failed refreshes preserve the last known-good snapshot only for the same CLI identity, expose the error, and remain stale so the next request retries automatically. A different CLI starts with an empty catalogue; it cannot inherit another runtime's executable models.

Failure and timeout behavior

• Default timeout: 120 seconds; allowed range: 10–300 seconds.
• The timeout is one total deadline across the initial attempt and every fallback.
• Cancellation and timeout terminate the child process group, escalating from SIGTERM to SIGKILL if necessary.
• Automatic fallback is limited to provider setup and unavailable-model errors. Authentication failures stop the chain without switching account/provider.
• Protocol failures, malformed JSON, timeouts, aborts, rate limits, tool failures, and ordinary execution errors are not retried.
• Final response text is capped at 50,000 characters; structured output and stderr buffers are bounded separately.

Limitations

• Every call is stateless and has no conversation history.
• The final result is returned when the child exits; structured tool/message progress is emitted through onUpdate while it runs.
• Runtime-only Piclaw models cannot be used until the child CLI also lists them.
• Unclassified current models disable automatic delegation until policy is updated. Explicit selection still requires an approved, classified candidate.
• Model policy is intentionally explicit and must be updated for genuinely new model families or variants.
• Children inherit the parent's process environment and Pi profile/config resolution. Delegate does not supply scoped credentials or prevent unrelated secret inheritance; offline fixtures are not evidence of real-provider credential safety.
• Core tool profiles are child allowlists, not an operating-system sandbox. A child granted bash or external MCP services can execute capabilities outside Delegate's child-model launcher; use read_only and a restricted environment when that distinction matters.

See REFERENCE.md for the full selection, execution, and diagnostics contract.

OpenCode Go region restrictions

Some OpenCode Go models require the workspace Privacy region setting to be Global. Delegate recognises the provider's specific rejection, stops the attempt chain and points to the OpenCode console and Go privacy information.

Choosing Global broadens permitted processing regions and may relax data-residency restrictions. Delegate does not change that policy, add a region header, retry the blocked request or switch billing routes. Choose another approved compatible model if you need to preserve the restriction.

The installed Go provider accepts an API key; no documented client-side Global parameter was found. OpenCode's workspace update is an administrator operation. The public documentation does not establish an exact Privacy navigation path or a supported API for third-party management, so this integration links to the console without inventing one.

Skills

• delegate