Extension-owned roles

Overview

Core forwards unknown JSON agent options unchanged. Without the roles extension, role is opaque data and has no effect. With it enabled in the parent Pi session, its generic preparation hook owns validation, discovery, precedence, model defaults, resource selectors, and role prompt append.

const report = await agent("Review the change", { role: "reviewer" });

For built-in behavior without plugins, use model, tools, skills, extensions, and contextFiles directly. Thinking is expressed by the model suffix, for example provider/model:high.

Independent launcher

pi-role is supplied only by @piewf/pi-ext-roles. Core and @piewf/cli do not depend on it or export a role launcher.

Integration API

Role contributors register with the independent package. Workflow plugins use agentPreparationHooks. There is no pi-extensible-workflows/roles export and no core role catalog.

Role files

The independent roles package owns file locations, parsing, discovery, and trust-aware precedence. Consult its shipped guide rather than adding workflow-specific role directories.

Frontmatter

Frontmatter validation and role settings are extension-owned. Core validates only the resulting concrete model, tools, resource policy, settings, context scopes, and prompt configuration.

Call options

Workflow agent(), named agent handles, nested child agents, standalone subagents_run, and generic CLI inspection share preparation. Every loaded plugin schema is checked against the original call before any preparation hook runs.

Context and capabilities

Preparation receives the effective cwd, agent directory, project trust, defaults, original options, cancellation signal, model catalogs, and authorized tool/skill/extension inventories. Root and parent ceilings remain authoritative. Excluded factories are filtered before loading; setup hooks cannot widen prepared tools or restore untrusted project resources.

Inspect generic options

Use piewf doctor --agent-options '{"role":"reviewer"}' --prompt "Review this". Doctor loads the same preparation and setup hooks, then inspects the local native prompt and resources without contacting a model. No role-specific doctor command remains.

Migration and replay

Install roles explicitly if your workflows need them. Core no longer reads shared role settings, imports role APIs, or ships role files. Prepared configurations are persisted by operation or handle identity and reused after restart and retry without rerunning role resolution. Removed capabilities or lost trust fail with RESUME_INCOMPATIBLE. Historical role snapshots are intentionally rejected; launch a new run.