@introspection-ai/recipes 0.13.0 → 0.14.0

package/docs/index.md

@@ -10,16 +10,13 @@ task lifecycle, protocols, and deployment.
 
 | Goal | Document |
 | --- | --- |
+| Create, validate, and run a Recipe | [Recipe workflow](recipe-flow.md) |
 | Understand the portable artifact contract | [Recipe Format](recipe-format.md) |
-| Embed a Recipe in a host | [Runtime library](runtime-library.md) |
+| Run a Recipe in your host | [Host API](host-api.md) |
 | Run a Recipe in Pi | [Pi extension](pi-extension.md) |
 | Compose agents and subagents | [Agent composition](agent-composition.md) |
 | Ask for user input across hosts | [Interactions](interactions.md) |
 | Declare capability policy and bindings | [MCP configuration](mcp-configuration.md) |
-| Declare portable resource intent | [Deployment configuration](deployment-configuration.md) |
-| Package quality definitions | [Recipe judges](recipe-judges.md) |
-| Declare offline evaluation suites | [Recipe evals](recipe-evals.md) |
-| Move from the previous package | [Migration](migration.md) |
 
 ## Boundary
 
@@ -30,20 +27,17 @@ Recipe source
 resolveRecipe()          format interpretation
     │
     ▼
-createRecipeSession()    complete live Pi agent
+createAgentSession()     complete live Pi agent
     │
-    ├── runRecipe()      one-turn convenience
-    │
-    └── host             tasks, persistence, auth, protocols, deployment
+    └── host              tasks, persistence, auth, protocols, deployment
 ```
 
 Recipes stops at the live session boundary. It does not ship a generic server,
-task store, scheduler, sandbox, or provider-specific deployment adapter.
+task store, scheduler, sandbox, or provider-specific hosting integration.
 
-The first-party hosts are:
+The same contracts power:
 
 - the Pi terminal harness through the Recipes extension;
-- Introspection's managed `runtime-agent`.
+- Node.js hosts through `createAgentSession()`.
 
-Other hosts implement the same session contract and can run the host
-conformance suite.
+Every host can run the exported conformance suite against its integration.

package/docs/interactions.md

@@ -1,7 +1,7 @@
 # Recipe Interactions
 
-`@introspection-ai/recipes/interactions` gives recipe tools one contract for
-asking the user a question or requesting approval that works on every pi host:
+`@introspection-ai/recipes/interactions` gives Recipe tools one contract for
+asking the user a question or requesting approval that works on every Pi host:
 the local TUI, RPC-driven UIs, headless runs, and hosts that stream tool
 results to a remote frontend and can pause/resume a run.
 
@@ -77,7 +77,7 @@ Pi's native tool-result shape is `content` plus arbitrary structured
 `details`. Recipes stores its interaction state at `details.interrupt`.
 A host that supports pause/resume treats
 `details.interrupt.outcome.type === "awaiting_user"` as a pause request.
-Runtime adapters generate their own pause state from this record.
+Hosts generate their own pause state from this record.
 
 | Field | Meaning |
 | --- | --- |
@@ -90,26 +90,26 @@ Runtime adapters generate their own pause state from this record.
 | `outcome` | Local result, or `{ type: "awaiting_user" }` when the host must pause |
 
 Question options are suggestions, not a closed enum. Local Pi shows them in a
-selector plus an `Other` input path, and runtime adapters should preserve that
+selector plus an `Other` input path, and hosts should preserve that
 same custom-answer path unless a specific tool explicitly does something else.
 
 Resume payloads are single-question: `{ answer }` for questions,
 `{ approved, feedback? }` for confirmations. A decline is a resume with
 status `cancelled` and **no payload**. Any host-specific pause/resume state
-should be generated by the host adapter from this request, not authored inside
-recipes.
+should be generated by the host from this request, not authored inside a
+Recipe.
 
 ## AG-UI compatibility
 
 `details.interrupt` is intentionally close to the shape needed by AG-UI-style
-frontends, while remaining Pi-native recipe metadata. A host that deploys
-recipes behind the Agent User Interaction Protocol can map an awaiting
+frontends, while remaining Pi-native Recipe metadata. A host that deploys a
+Recipe behind the Agent User Interaction Protocol can map an awaiting
 `details.interrupt` request into `RUN_FINISHED` with
 `outcome: { type: "interrupt", interrupts: [...] }`, then resume with the
 same `{ answer }`, `{ approved, feedback? }`, or cancelled payloads described
 above.
 
-Recipes should still emit only `details.interrupt`. The host adapter owns ids,
+Recipes should still emit only `details.interrupt`. The host owns ids,
 tool-call binding, response schemas, transport events, persistence, and any
 frontend-specific rendering.
 
@@ -157,7 +157,7 @@ options.
 The envelope is the tool-result text the model sees after the user responds.
 It is a byte-exact wire contract: the local dialog walk and every pause/resume
 host must synthesize identical text for the same outcome,
-so recipes cannot tell where the answer came from. Do not reword these
+so Recipe tools cannot tell where the answer came from. Do not reword these
 without a coordinated protocol change across all hosts.
 
 | Outcome | Envelope |
@@ -178,7 +178,8 @@ best judgment.
 - **`executionMode: "sequential"` is mandatory.** A host pause must never
   race concurrently executing tools.
 - **Prefer the wrappers.** Use `askUserQuestion()` and `askUserApproval()` so
-  recipes do not hand-author interrupt details, reasons, or display metadata.
+  Recipe tools do not hand-author interrupt details, reasons, or display
+  metadata.
 - **Never format envelopes yourself.** Return the helper result as-is; envelope
   authorship must not split across layers.
 - **Thread the tool's `signal`** into the helper and check for aborts after any

package/docs/mcp-auth.md

@@ -7,7 +7,7 @@ endpoint model.
 Recipe MCP authentication follows the endpoint source that made an
 already-approved server reachable: a configured package manifest or a local/host
 binding. Authentication never selects a server or grants tools; the package and
-active/visible-agent selections still determine the final server/tool inventory.
+selected-agent policies still determine the final server/tool inventory.
 
 ## Local OAuth
 
@@ -49,13 +49,13 @@ cannot initiate authentication.
 
 ## Hosted bindings
 
-Hosted runtimes adapt their endpoint and credential systems into the same
+Hosts adapt their endpoint and credential systems into the same
 `.pi/mcp.local.json` shape before starting Recipes. Header values remain
 environment references, so credentials are resolved at runtime rather than
 written into the recipe workspace. Deployment-specific bootstrap, token, and
-egress behavior belongs to the hosting adapter, not this package.
+egress behavior belongs to the host, not this package.
 
-Regardless of where a recipe runs, the agent sees one rule: MCP operations are
+Regardless of where a Recipe runs, the agent sees one rule: MCP operations are
 headless. When authentication is missing, it receives a deployment-neutral
 recovery telling it to ask the user to authenticate the connection outside the
 agent session and then retry; `mcp run --json-errors` reports this as
@@ -75,6 +75,6 @@ reads an absolute local path supplied by an MCP result; server output must not
 choose files for an agent session to read.
 
 This command policy prevents accidental escape from the materialized MCP
-surface. It is not an OS or network sandbox: the enclosing local shell or
-managed runtime remains responsible for filesystem, process, and egress
+surface. It is not an OS or network sandbox: the enclosing local shell or host
+remains responsible for filesystem, process, and egress
 isolation.

package/docs/mcp-configuration.md

@@ -1,31 +1,30 @@
 # MCP configuration
 
 MCP authorization is the intersection of two fail-closed policy gates: the
-package boundary and the subsets selected by the active agent and its visible
-subagents. The authorized server must
+package boundary and the subset selected by an agent. The authorized server must
 also have a reachable endpoint, supplied either by a package-declared MCP
 manifest or by a local/host binding. A binding supplies connectivity; it never
 expands authorization.
 
 ```text
-package policy  ∩  active/visible-agent selections  =  authorized tools
+package policy  ∩  selected-agent policy  =  authorized tools
        package.json#pi.mcp             agents/*.yaml#mcp
                               +
  endpoint from package manifest or local/host binding
                               ↓
-                     session-local mcp CLI
+                 CLI or Pi-registered tools
 ```
 
 ## 1. Declare the package boundary
 
-`package.json#pi.mcp` declares the servers a recipe may use and the maximum
+`package.json#pi.mcp` declares the servers a Recipe may use and the maximum
 tool set available from each one. It can also reference portable MCP manifests.
 
 ```json
 {
   "pi": {
     "mcp": {
-      "manifest": "mcp.json",
+      "manifests": ["mcp.json"],
       "servers": [
         {
           "id": "contacts",
@@ -44,13 +43,12 @@ tool set available from each one. It can also reference portable MCP manifests.
 Prefer exact tool names. `"*"` explicitly permits the package-visible tool set,
 including tools a server may add later; patterns such as `search_*` are invalid.
 
-`manifest` accepts a single path; `manifests` accepts an array, and either the
-`mcp` value or a manifest reference may be given as a string shorthand for a
-single path. A server marked `"required": true` must resolve to a bound endpoint
-at session materialization or the session fails closed rather than starting
-without the capability.
+`manifests` is always an array of Recipe-relative paths or globs. Singular
+`manifest` and string shorthand are invalid. A server marked
+`"required": true` must resolve to a bound endpoint at session materialization
+or the session fails closed rather than starting without the capability.
 
-## 2. Narrow access for each agent
+## 2. Choose an agent mode and narrow access
 
 An agent selects a subset of the package-permitted servers and tools. It cannot
 add capability that the package did not declare.
@@ -59,15 +57,51 @@ add capability that the package did not declare.
 tools:
   - bash
 mcp:
-  contacts:
-    include:
-      - search_contacts
+  mode: cli
+  servers:
+    contacts:
+      include:
+        - search_contacts
 ```
 
 Omitting a server—or the entire agent `mcp` block—means no access. `exclude`
 removes exact names after inclusion and always wins. MCP tools are selected here,
 not in the agent's ordinary `tools` list.
 
+`mode: cli` creates the session-local `mcp` command.
+
+`mode: tools` registers every authorized MCP tool with Pi. Server-local
+`defer` selectors control which authorized tools start hidden from the model;
+`eager` subtracts exceptions from that deferred set:
+
+```yaml
+mcp:
+  mode: tools
+  servers:
+    contacts:
+      include: ["*"]
+      defer: ["*"]
+      eager:
+        - search_contacts
+```
+
+Omit `defer` to expose every authorized tool immediately. Use `defer: ["*"]`
+to hide all authorized tools for a server, then optionally list exact tools in
+`eager` to expose those tools at startup. Both fields accept exact tool names
+or a sole `"*"` selector. `eager` wins when a tool matches both fields, but
+neither field can authorize a tool excluded by `include`/`exclude`.
+
+Deferred tools remain authorized and discoverable. When at least one exists,
+Recipes registers `mcp_search`; calling it searches only the authorized
+deferred catalog and adds matches to Pi's current active tool set for the next
+model request. It never grants access beyond `servers`.
+
+`defer` and `eager` are invalid in CLI mode. An omitted agent `mcp` block
+inherits its base policy. Once a child declares `mcp`, the complete block
+replaces the inherited policy; restate its mode, servers, authorization, and
+activation selectors. This makes external capability changes reviewable at the
+derived agent. Every resolved agent owns its mode independently.
+
 ## 3. Supply endpoint configuration
 
 A referenced MCP manifest can carry a portable configured endpoint and catalog.
@@ -99,10 +133,10 @@ pi --recipe . --agent agent
 
 Do not commit or distribute `.pi/mcp.local.json`; publish validation rejects
 local configuration. Commit `.pi/mcp.local.example.json` when a binding template
-is helpful. A hosted runtime binds its own endpoint and credential system to the
-same shape. A binding overrides a package-manifest endpoint with the same id,
-but a server that the package does not permit, or that none of the active/visible
-agents permit, remains unavailable.
+is helpful. A host binds its own endpoint and credential system to the same
+shape. A binding overrides a package-manifest endpoint with the same id,
+but a server that the package or selected agent does not permit remains
+unavailable.
 
 When the local file is absent, manifest-supplied endpoints remain usable.
 Required servers that need environment-specific bindings fail closed until the
@@ -110,9 +144,10 @@ local Pi environment or embedding host supplies them.
 
 ## Use capabilities from an agent
 
-When the active agent or one of its visible subagents has MCP access, the
-extension creates a session-local `mcp` command from their combined selections.
-Discover narrowly, inspect one schema, then call or compose:
+In CLI mode, Recipes creates a session-local `mcp` command containing only the
+selected agent's authorized tools. Delegating to another agent does not grant
+the parent direct access to that child's MCP capabilities. Discover narrowly,
+inspect one schema, then call or compose:
 
 ```bash
 mcp search "contact lookup"
@@ -122,5 +157,18 @@ mcp call contacts.search_contacts query="Ada Lovelace"
 
 The command is headless and cannot add servers, mutate configuration, or start
 browser authentication. See [MCP authentication](mcp-auth.md) for OAuth and
-hosted binding details, and [Recipes extension](pi-extension.md#mcp) for the
-full runtime contract.
+hosted binding details, and [Recipes extension](pi-extension.md) for the
+full session contract.
+
+In tools mode, each Pi session—including each delegated child session—gets its
+own registered tool catalog and active set. The MCP daemon and mcporter config
+remain private to those wrappers; shell tools do not receive an `mcp` command,
+`MCPORTER_CONFIG`, or MCP session path.
+
+Pi receives each tool's MCP input schema. If the server declares
+`outputSchema`, Recipes retains and validates it locally against successful
+`structuredContent`; providers do not currently receive it as a tool
+declaration field. Text, image, resource, resource-link, audio, and structured
+results are normalized to Pi tool results. Duplicate structured JSON text is
+removed, errors become ordinary failed tool calls, and model-visible text is
+bounded to 50 KiB or 2,000 lines by default.

package/docs/pi-extension.md

@@ -9,7 +9,8 @@ pi --recipe ./path/to/recipe --agent agent
 
 Pi is the harness. The extension resolves the selected Recipe, configures its
 model and tools, loads its skills and extensions, materializes its declared
-capabilities, and registers its subagents.
+capabilities, and registers its subagents. Every launch with `--recipe`
+validates the authored package first.
 
 ## Installation
 
@@ -52,7 +53,7 @@ For the selected agent, the extension:
 1. reads the root `package.json#pi` resource declarations;
 2. resolves the agent YAML, including `from:` inheritance;
 3. selects the model, thinking level, and tool allowlist;
-4. loads selected skills, prompts, and Recipe-owned extensions;
+4. loads selected skills, package prompts, and the complete Recipe extension closure;
 5. materializes declared MCP bindings from host or local configuration;
 6. exposes only the declared subagents through the shared `agent` tool.
 
@@ -71,24 +72,51 @@ remain unavailable. See [MCP configuration](mcp-configuration.md).
 ## Recipe-owned extensions
 
 TypeScript extension sources declared by `package.json#pi.extensions` are
-loaded relative to the Recipe. Agent-level `extensions.include` and
-`extensions.exclude` select which declared extensions participate.
+resolved deterministically and loaded for every Recipe session. This complete
+set is one executable closure; agent YAML only controls which registered tools
+the model may call.
+
+Recipe extensions can import `forAgent`, `forRecipeSession`, and
+`getRecipeSessionContext` from `@introspection-ai/recipes/extensions` for
+session-local conditional behavior:
+
+```ts
+import { forAgent } from "@introspection-ai/recipes/extensions";
+
+export default function reviewerHooks(pi) {
+  forAgent(pi, "reviewer", () => {
+    pi.on("tool_call", reviewPolicy);
+  });
+}
+```
+
+The context distinguishes `root` and `subagent` roles. Conditional behavior is
+not code isolation: the extension module still executes with the Pi process's
+authority. `forAgent` matches the final resolved `agent.name` exactly; `from`
+is configuration inheritance and does not make a derived agent match its
+ancestor's hooks.
 
-Recipe extensions can import runtime helpers from `@introspection-ai/recipes`.
-The loader also aliases the previous `@introspection-ai/pi-recipes` name during
-the migration period so existing Recipe source shares the same runtime state.
+The closure contains every extension declared by the Recipe. It does not claim
+exclusive ownership of the surrounding Pi process: trusted global or project
+extensions already loaded by interactive Pi may still run hooks, providers,
+commands, and other non-tool behavior. Recipe `tools` remains the exact
+model-callable allowlist. Embedded Recipe sessions disable ambient extensions,
+skills, prompt templates, and context files by default.
 
 ## Validation
 
-Run:
+Every `pi --recipe` launch automatically runs the shared Recipe Format
+validator. Invalid Recipes are rendered in Pi and stop the session before any
+model call.
+
+For an explicit manual or CI check, run:
 
 ```bash
 introspection check
 ```
 
-The runtime also performs the minimum validation required to fail safely before
-constructing a session. Static authoring diagnostics remain the CLI validator's
-job.
+Both paths use the same Rust validation core. The binary embedded in the npm
+package is an internal bridge for Pi startup, not a second user-facing CLI.
 
 ## Host parity
 

package/docs/recipe-flow.md

@@ -1,7 +1,7 @@
 # Recipe workflow
 
 The `introspection` CLI owns the developer workflow. The Recipes npm package is
-the format implementation and Pi runtime extension; it does not install a
+the format implementation, Host API, and Pi extension; it does not install a
 second CLI.
 
 ## Create and run locally
@@ -15,10 +15,11 @@ introspection local
 
 `introspection init` scaffolds a Recipe and ensures compatible versions of Pi
 and the Recipes extension are present. `introspection check` runs the Recipe
-Format validator. `introspection local` resolves the repository's local runtime
-manifest and launches Pi with the Recipe path.
+Format validator. `introspection local` resolves the repository's project
+manifest and launches Pi with the Recipe path. Pi automatically runs the same
+validator whenever `--recipe` is present.
 
-The local path requires no login and no Introspection cloud runtime.
+The local path requires no login or Introspection cloud service.
 
 ## Run Pi directly
 
@@ -33,9 +34,8 @@ publish command.
 
 ## Deploy
 
-The Recipe remains unchanged across hosts. A host calls
-`createRecipeSession()` and supplies its own credentials, task lifecycle,
-persistence, isolation, and protocol surface.
+The Recipe remains unchanged across hosts. A long-lived host resolves the Recipe
+once, calls `createAgentSession()`, and supplies its own credentials, task
+lifecycle, persistence, isolation, and protocol surface.
 
-Use Introspection when you want the managed host. Use a host adapter when you
-want to operate the same Recipe on another platform.
+Integrate the Host API with the platform that will operate the Recipe.

package/docs/recipe-format.md

@@ -2,7 +2,7 @@
 
 **Status:** Open format, version 1  
 **Reference implementation:** `@introspection-ai/recipes`  
-**Validator:** `pi-recipe-check`
+**Validator:** `introspection check`
 
 The Recipe Format is a Git-native package contract for complete Pi agents. It
 defines the agent-owned inputs that a compatible host must interpret the same
@@ -23,7 +23,18 @@ This format does not claim interoperability with non-Pi agent harnesses.
 
 ## Package root
 
-A Recipe MUST be a directory containing `package.json`. The manifest MUST have:
+A Recipe MUST be a directory containing `package.json`. At minimum, its
+manifest contains a package name and a `pi` object:
+
+```json
+{
+  "name": "acme-research",
+  "pi": {}
+}
+```
+
+A fuller package may declare distribution metadata and explicit resource
+paths:
 
 ```json
 {
@@ -39,15 +50,27 @@ A Recipe MUST be a directory containing `package.json`. The manifest MUST have:
 }
 ```
 
-`name` is the package identity. `version` is distribution metadata and defaults
-to `0.0.0` when omitted for compatibility. `description` is human-facing.
+`name` is the package identity. `version` is optional distribution metadata and
+defaults to `0.0.0` when omitted. `description` is optional human-facing
+metadata. When resource arrays are omitted, conventional `agents/`, `skills/`,
+and `prompts/` directories are discovered when present. Executable extensions
+and MCP servers are never discovered by convention and MUST be declared
+explicitly.
+
+Omission and an explicit empty array are different:
+
+- an omitted `agents`, `skills`, or `prompts` key opts into its documented
+  conventional directory;
+- an explicit `[]` resolves no resources of that kind;
+- every explicitly authored path or glob MUST match.
 
 Resource paths:
 
 - MUST be relative to the package root;
-- MUST NOT traverse outside the package;
+- MUST NOT resolve outside the package, including through symlinks;
 - MAY be files, directories, or supported glob patterns;
-- are resolved deterministically in lexical order.
+- preserve declaration order, with matches inside each glob ordered
+  lexically.
 
 Unknown top-level `package.json` fields retain normal npm semantics. Unknown
 Recipe fields inside supported `pi` structures are validation errors unless a
@@ -55,8 +78,9 @@ later format version explicitly defines them.
 
 ## Agents
 
-`pi.agents` declares YAML agent definitions. A resolved Recipe MUST contain at
-least one agent.
+`pi.agents` may declare YAML agent definitions explicitly. When omitted,
+direct `.yaml` and `.yml` children of `agents/` are discovered. A resolved
+Recipe MUST contain at least one agent.
 
 ```yaml
 name: agent
@@ -67,8 +91,6 @@ model:
 tools: [read, bash]
 skills: [research]
 subagents: [reviewer]
-extensions:
-  include: [citations]
 system_instructions:
   mode: append
   content: Verify every material claim.
@@ -79,14 +101,22 @@ acyclic. Child fields override inherited scalar fields; documented collection
 fields use the merge or replacement behavior in
 [Agent composition](agent-composition.md).
 
-Every fully resolved agent MUST define:
+Every agent YAML MUST declare a package-unique lowercase kebab-case `name`.
+This is its
+stable identity for selection, subagent references, artifacts, and telemetry;
+the filename has no semantic meaning.
 
-- `model.name` as `<provider>/<model_id>`;
-- `model.thinking_level`;
-- `tools`;
-- `system_instructions`.
+Every fully resolved agent MUST also define `model.name` as
+`<provider>/<model_id>`. The model may be declared directly or inherited with
+`from`.
 
-Omitted `skills` and `subagents` resolve to empty lists.
+All remaining agent fields are optional. Omitted `tools`, `skills`, and
+`subagents` resolve to empty lists. Omitted `model.thinking_level` preserves the
+provider or session default. Omitted agent instructions preserve `SYSTEM.md`
+when present, or Pi's normal base prompt otherwise.
+
+`tools` MUST NOT contain `agent`. The host materializes that session-generated
+tool for a root session whose effective `subagents` list is non-empty.
 
 The default agent is named `agent`. If no `agent` exists, a host MAY select the
 only declared agent. When multiple agents exist without `agent`, the caller
@@ -99,13 +129,41 @@ MUST select one explicitly.
 replace the current prompt.
 
 Skills follow the [Agent Skills](https://agentskills.io) directory convention
-and are selected from the resources declared by `pi.skills`.
-
-Prompt templates are declared by `pi.prompts`.
-
-Recipe-owned Pi extensions are declared by `pi.extensions`. An agent MAY select
-declared extensions with `extensions.include` and `extensions.exclude`. A host
-MUST NOT load undeclared Recipe extension source.
+and are selected from the resources declared by `pi.skills`. A skill is named
+by its `SKILL.md` frontmatter `name`, then by its containing directory; a
+root-level unnamed `SKILL.md` uses the portable fallback name `skill`.
+
+Prompt templates are declared by `pi.prompts`. They retain Pi's normal SDK and
+TUI behavior: hosts expose them through `AgentSession.promptTemplates`, and a
+caller invokes one by prompting with its slash command and arguments.
+
+Recipe-owned Pi extensions are declared by `pi.extensions`. The deterministically
+resolved set forms the package's executable trust boundary and loads for every
+root and child session. Package membership means execution; agent YAML cannot
+select or remove extensions.
+
+An extension declaration may name a module or directory. A directory index
+(`index.ts`, `index.tsx`, `index.js`, `index.jsx`, `index.mjs`, or `index.cjs`,
+in that precedence order) owns the directory. Without an index, Recipes loads
+its direct extension modules and the indexes of its immediate child
+directories, both in lexical order. Discovery is intentionally shallow;
+declare deeper modules explicitly.
+
+Programmatic root and child sessions invoke the closure's factories for their
+own Pi runtime. Interactive Pi keeps one extension runtime for the selected
+Recipe launch and does not retry a partially failed closure without rebuilding
+that runtime. Extension load failures stop the agent before a model call.
+Recipe extensions MUST NOT override host or Pi built-in tool names; use a
+distinct tool name when behavior differs. Extension code retains its non-tool
+behavior even when none of its tools appear in the selected agent's `tools`
+allowlist.
+
+The package extension closure is complete with respect to Recipe source, not
+the surrounding host process. A host MAY supply extensions, settings, or other
+runtime policy. Interactive Pi may already have trusted global or project
+resources loaded; compatible hosts MUST keep those additions distinguishable
+from Recipe-owned inputs. `tools` limits model-callable tools, not extension
+hook execution.
 
 ## Tools, subagents, and capabilities
 
@@ -124,19 +182,6 @@ MUST reject an unbound required server before the session begins.
 See [MCP configuration](mcp-configuration.md) for the complete authored and
 binding grammar.
 
-## Quality and resource intent
-
-Recipe-owned judge YAML expresses portable quality definitions. Hosts MAY use
-those definitions online or offline, but MUST preserve their authored identity
-and semantics.
-
-`pi.evals` MAY pin external evaluation suites. The format records the pin; an
-evaluation runner remains an external tool.
-
-Portable resource intent is declared under the documented runtime resource
-grammar. A host decides whether it can satisfy that intent and MUST report
-unsupported required resources rather than silently weakening them.
-
 ## Host responsibilities
 
 The Recipe Format owns:
@@ -144,10 +189,9 @@ The Recipe Format owns:
 - package and agent interpretation;
 - instruction composition;
 - model and tool selection;
-- skill, prompt, and extension selection;
+- skill and prompt selection plus the package extension closure;
 - subagent visibility;
 - capability policy;
-- quality definitions and resource intent.
 
 The host owns:
 
@@ -162,16 +206,21 @@ The host owns:
 
 Those host concerns MUST NOT become mandatory Recipe source fields.
 
+Recipe packages are trusted application code. In particular, authored
+TypeScript extensions execute inside the Pi process with its authority. A host
+that accepts third-party Recipes MUST review or isolate them before execution;
+the format and Host API are not a sandbox boundary.
+
 ## Conformance
 
 There are two conformance layers:
 
-1. `pi-recipe-check` validates authored package snapshots without executing
-   them.
+1. A Recipe checker validates authored Recipe source without executing it.
 2. `@introspection-ai/recipes/test-utils` verifies that a host constructs and
    disposes Recipe sessions with the required semantics.
 
-A host SHOULD run both layers in CI.
+Pi also runs the same validator automatically whenever it launches with
+`--recipe`. Other hosts SHOULD run both layers in CI.
 
 ## Evolution