@llblab/pi-actors 0.49.2 → 0.50.0

package/docs/template-recipes.md

@@ -1,27 +1,45 @@
-# Template Recipes
+# Template Recipe Standard
 
-A Recipe stores a reusable command-template definition as JSON or Markdown.
+A Template Recipe is a file-backed, reusable command-template graph. It adds stable identity, typed inputs, composition, optional detached execution, artifacts, Control, and provenance around the portable [Command Template Standard](./command-templates.md).
 
-## JSON
+## Mental Model
+
+A Recipe has three layers:
+
+1. **Recipe contract**: identity, description, arguments, defaults, imports, lifecycle, artifacts, and Control.
+2. **Command-template graph**: the executable string, sequence, parallel fanout, conditions, retry, and output behavior stored in `template`.
+3. **Run projection**: detached process state, Trace, Control delivery, artifacts, and inspection when `async: true`.
+
+Use a Recipe when a command graph should be named, validated, reused, imported, registered as a tool, or launched as a Run. Use an inline command template when file identity and Recipe metadata add no value.
+
+## File Formats
+
+Recipes may be authored as JSON or Markdown. Both formats compile to the same Recipe contract.
+
+### JSON
+
+JSON is the most direct form for structured composition:
 
 ```json
 {
-  "async": true,
-  "description": "Create a repository health artifact",
+  "description": "Create a repository health report",
   "args": ["repo:path", "artifact_path:path", "model:string"],
-  "defaults": { "artifact_path": "{state_dir}/health.md" },
-  "imports": { "review": "swarm/quorum-review" },
-  "artifacts": { "report": "{artifact_path}" },
+  "defaults": {
+    "artifact_path": "{state_dir}/health.md"
+  },
+  "async": true,
+  "artifacts": {
+    "report": "{artifact_path}"
+  },
   "template": {
-    "name": "review",
-    "values": { "input": "Inspect {repo}", "model": "{model}" }
+    "template": "pi -p {repo} --model {model}"
   }
 }
 ```
 
-## Markdown
+### Markdown
 
-Markdown Recipes use YAML frontmatter and one executable fence:
+Markdown uses YAML frontmatter for the Recipe contract and one executable fence for `template`:
 
 ````markdown
 ---
@@ -30,142 +48,283 @@ args:
   - file:path
 ---
 
-Human notes remain advisory.
+Human-facing notes may explain intent and usage.
 
 ```template
 summarize {file}
 ```
 ````
 
-Fences marked `template`, `command-template`, `json`, or `recipe` can define execution. Frontmatter supports Recipe metadata and command-template flags.
+Executable fences may be marked `template`, `command-template`, `json`, or `recipe`. Narrative Markdown outside the executable fence is advisory and is not executed.
+
+Choose JSON for dense machine-oriented graphs. Choose Markdown when a short executable definition benefits from nearby human guidance.
+
+## Identity and Placement
+
+Recipe identity comes from its location and filename, never from a top-level `name` field.
+
+| Placement | Identity | Typical use |
+| --- | --- | --- |
+| Direct file under an active Skill's `recipes/` directory | `<skill>/<filename-stem>` | Maintained Skill capability |
+| Explicit `.json` or `.md` path | Resolved file path with filename-stem evidence | Local or project-specific composition |
+| File under `~/.pi/agent/recipes` | Registered user tool identity | User-maintained reusable tool |
 
-Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`. Recipe files have no top-level `name`; both JSON and Markdown fail with migration guidance when that removed field is present. `SKILL.md` `name` remains Pi host metadata and matches the Skill directory; pi-actors introduces no additional Skill identity field. The `name` field on a command-template node still selects an imported alias and is not Recipe self-identity.
+A Skill Recipe is one direct file under `<skill>/recipes/`. Nested files are not Skill components. The Skill name comes from its active `SKILL.md`; the Recipe stem comes from the direct filename.
 
-## Fields
+A Recipe file must not declare top-level `name`. Within a command-template graph, a node-level `name` has a different purpose: it invokes an alias declared in `imports`.
 
-Common Recipe fields:
+## Recipe Field Reference
 
-- `description`, `disabled`;
-- `args`, typed arg declarations, inline defaults, `defaults`, and composition `values`;
-- `imports` with optional binding defaults/values;
-- `template`;
-- `async`;
-- `singleton: true` for one explicit Skill-owned async service slot;
-- `artifacts`;
-- `control` for actual controlled services;
-- command-template flags such as `parallel`, `concurrency`, `min_successful`, `when`, `timeout`, `delay`, `retry`, `failure`, `recover`, `repeat`, `accept_output`, and `output`;
-- `retire_when: "children_terminal"` for opt-in supervisor retirement.
+The following fields belong to the file-level Recipe contract. Unless noted otherwise, each field is optional.
 
-## Imports
+| Field | Type | Default | Contract |
+| --- | --- | --- | --- |
+| `description` | string | none | Human-facing purpose used by discovery and tool surfaces. Describe the outcome, not implementation history. |
+| `disabled` | boolean | `false` | Prevents launch and import when `true`. Use it to make an authored Recipe intentionally unavailable without deleting the file. |
+| `args` | string[] | inferred/untyped placeholders | Declares public inputs. Entries may be untyped (`input`), typed (`file:path`), enum-constrained (`mode:enum(check,fix)`), or include an inline default (`limit:int=10`). Names must be unique and agree with placeholder types. |
+| `defaults` | object | `{}` | Supplies fallback values for declared inputs. A default may reference another placeholder and is resolved recursively with a depth bound. Every authored default must correspond to a declared argument. |
+| `values` | object | `{}` | Binds composition values before executing the Recipe graph. Use for authored wiring between wrapper/import context and template nodes, not for caller-owned configuration. |
+| `imports` | object | `{}` | Maps local aliases to other Recipes. Each value is a canonical Skill reference, explicit file path, or binding object with `from`, `defaults`, and/or `values`. Imports are resolved and validated before launch. |
+| `template` | string, array, or command-template object | required | Defines the executable command-template graph. It may directly execute commands, compose nodes, invoke import aliases, or delegate to another Recipe. |
+| `async` | boolean | `false` | Launches the Recipe as a detached Run when `true`. Detached execution owns durable state, Trace, terminal reconciliation, and optional Control/artifacts. |
+| `singleton` | boolean | `false` | Gives one async Skill Recipe a stable `run:<skill>` service slot. Valid only with `async: true`; at most one singleton Recipe may belong to a Skill. |
+| `artifacts` | object of string paths | `{}` | Declares named files produced by the Run. Paths support placeholders, resolve under containment policy, and appear in Run inspection. |
+| `control` | string[] | `[]` | Declares actions consumed by an actual controlled service. Actions must be unique lowercase ASCII names, non-reserved, and at most 64 characters. |
+| `retire_when` | `"children_terminal"` | none | Opts an async supervisor into retirement after all owned child Runs become terminal. Omit it for ordinary Run lifecycle. |
+| `actor_context` | boolean or `"off"` | enabled | Controls injection of Recipe composition context into compatible child-agent prompts. Use `false` or `"off"` only when a deliberately minimal child prompt is required. |
+
+### Value Resolution
+
+For a declared name, effective values resolve in this order:
+
+```text
+caller values
+→ node/import/Recipe values
+→ defaults
+→ inline argument default
+→ missing-value error
+```
+
+The selected value is then validated against its declared type or enum. Runtime-provided origin values such as `{recipe_dir}` and `{skill_dir}` are immutable and cannot be declared or overridden through `args`, `defaults`, or `values`.
+
+## Command-Template Fields
+
+A Recipe may place command-template execution fields beside `template`, and any object node inside the graph may use the same fields. Their execution semantics are defined by the [Command Template Standard](./command-templates.md).
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `label` | string | none | Human-readable node label for diagnostics and branch reports. |
+| `parallel` | boolean | `false` | Runs an array node concurrently instead of sequentially. |
+| `concurrency` | positive integer or placeholder | unlimited | Caps simultaneous children of a parallel node. |
+| `min_successful` | non-negative integer or placeholder | none | Requires a minimum count of successful branches with non-empty stdout. |
+| `when` | boolean or expression | `true` | Skips the node when its guard resolves false. |
+| `timeout` | milliseconds or placeholder | `0` / unbounded | Terminates an execution attempt after a positive duration. |
+| `delay` | milliseconds or placeholder | `0` | Waits before starting the node. |
+| `retry` | positive integer or placeholder | `1` | Sets total attempts, including the first attempt. |
+| `failure` | `continue`, `branch`, or `root` | `continue` | Selects how a node failure propagates through composition. |
+| `recover` | command template | none | Runs cleanup between failed attempts; a recovery failure ends retry. |
+| `repeat` | non-negative integer or expression | none | Repeats a node, exposing the current index to placeholders. |
+| `accept_output` | supported semantic contract | none | Applies fail-closed semantic validation to otherwise successful stdout. |
+| `output` | string selector | `stdout` | Selects the result channel returned by the graph. |
+
+Keep Recipe metadata at the file level and execution behavior near the node it controls. For object form, place `template` last so readers encounter contract and execution flags before executable content.
+
+## Imports and Composition
+
+Imports are local aliases within one resolved execution graph:
 
 ```json
 {
+  "description": "Review and format one report",
+  "args": ["input:string", "thinking:string=medium"],
   "imports": {
     "review": "swarm/quorum-review",
-    "report": {
+    "format": {
       "from": "../shared/report.md",
-      "defaults": { "thinking": "medium" }
+      "defaults": {
+        "thinking": "{thinking}"
+      }
     }
   },
   "template": [
-    { "name": "review", "values": { "input": "{input}" } },
-    { "name": "report", "values": { "input": "Use prior output" } }
+    {
+      "name": "review",
+      "values": {
+        "input": "{input}"
+      }
+    },
+    {
+      "name": "format",
+      "values": {
+        "input": "Use prior output"
+      }
+    }
   ]
 }
 ```
 
-Imports are local definitions. Named nodes call imported templates inside the same execution graph and Run. Effective values follow `caller > node/import/Recipe values > defaults > inline arg default > missing-value error`, then the selected value is checked against its declared type or enum.
+### Accepted References
 
-Imports accept exactly `<skill>/<recipe>` or an explicit `.json` / `.md` file path. A Skill reference selects one direct filename stem under the exact Skill currently active through Pi resource discovery; duplicate active Skill identities and JSON/Markdown stem collisions fail closed. Explicit paths may be relative (`./local-review.json`, `../shared/report.md`) or absolute (`/absolute/path/to/recipe.json`). An entry file path resolves from invocation `cwd`; a relative import resolves from the importing Recipe's directory. No bare or ambient lookup remains.
+An import `from` value accepts exactly one of these forms:
 
-Direct delegation can use another Recipe as the entire template. The delegated Recipe remains the source of truth while the wrapper may narrow args/defaults or override selected lifecycle metadata.
+| Form | Resolution |
+| --- | --- |
+| `<skill>/<recipe>` | One direct filename stem under the exact active Skill |
+| `./file.json` or `../file.md` | Relative to the importing Recipe's directory |
+| `/absolute/path/to/file.json` | Exact absolute file |
 
-A launched Run captures each entry/import role, filename-derived stem, logical reference, Skill identity when owned, and import alias ancestry. Private physical source paths remain execution provenance; Inspector and child-agent context expose logical identities rather than machine-local Skill locations.
+An entry Recipe path resolves from invocation `cwd`. A relative import resolves from the importing Recipe, not from invocation `cwd`. Bare ambient names and implicit fallback search are not part of the contract.
 
-## Migration from pre-0.46 references
+Duplicate active Skill names, duplicate JSON/Markdown stems, missing references, disabled targets, import cycles, and excessive import depth fail closed. A launched Run captures the resolved graph; later catalog changes affect future launches only.
 
-```text
-std:foo              -> owning-skill/foo
-skill:foo/bar        -> foo/bar
-root packaged foo    -> owning-skill/new-file-stem
-Recipe name field    -> delete; filename is identity
-nested skill path    -> flatten filename or use explicit file path
+### Import Bindings
+
+A string import uses the target as authored:
+
+```json
+{ "review": "swarm/quorum-review" }
 ```
 
-Removed `std:` and `skill:` forms fail with migration guidance; they are not aliases. Root packaged Recipes no longer exist. Flatten a maintained Skill component to a direct filename, or reference a nested/local file explicitly when it is intentionally outside the Skill component namespace.
+An object binding can supply alias-local defaults or values:
 
-## Singleton Services
+```json
+{
+  "review": {
+    "from": "swarm/quorum-review",
+    "defaults": { "thinking": "medium" },
+    "values": { "mode": "strict" }
+  }
+}
+```
+
+Use `defaults` when callers may override the value. Use `values` for authored composition wiring subject to the normal resolution order.
+
+### Direct Delegation
+
+A Recipe may use another Recipe as its entire template. The delegated Recipe remains authoritative while the wrapper may narrow public arguments, defaults, or selected lifecycle metadata. Singleton Run and Recipe identities remain owned by the delegated singleton; wrappers cannot create alternate service identities.
+
+## Async Runs and Singleton Services
 
-`singleton: true` is valid only for an async Skill Recipe, and one Skill may declare at most one singleton Recipe. The runtime derives `run:<skill>` and the canonical `<skill>/<recipe>` identity, then rejects a conflicting caller-supplied Run id. A compatible repeated launch returns the healthy active generation; contradictory Recipe identity, ownership, startup values, or Control fails closed. A terminal result is never reused even during runner exit; retry after that process exits starts a fresh `run_instance_id` under the same logical Run id. Actor-owned workload continuity requires a validated state artifact that restart cleanup deliberately preserves; singleton identity alone never proves restored state.
+`async: true` changes execution from an inline result to a detached Run. The Run receives durable state, stdout/stderr evidence, Trace, generation identity, and terminal reconciliation.
 
-Direct Recipe delegation inherits the original singleton Run and Recipe identities, so registered tools and explicit wrappers cannot retarget the service or create parallel aliases.
+A singleton Recipe additionally follows these rules:
+
+- it must be a direct Recipe owned by one active Skill;
+- it must declare `async: true`;
+- one Skill may declare at most one singleton Recipe;
+- its logical address is `run:<skill>`;
+- a compatible repeated launch reuses the healthy active generation;
+- conflicting Recipe identity, owner, startup values, or Control contract fails closed;
+- terminal generations are never reused;
+- singleton identity alone does not restore workload state after restart.
+
+Use singleton only for a genuine long-lived Skill service. Ordinary jobs should remain non-singleton Runs.
 
 ## Control
 
-Only a process that consumes actor-local input declares actions:
+Declare Control only when the launched process consumes actor-local input:
 
 ```json
 {
+  "description": "Run a controllable service",
   "async": true,
   "control": ["pause", "resume", "stop"],
   "template": "{skill_dir}/scripts/service.mjs --state-dir {state_dir}"
 }
 ```
 
-Actions must be lowercase ASCII, unique, non-reserved, and at most 64 characters. Serialized Control input is at most 380 bytes so every admitted wire record remains within 512 bytes on FIFO and named pipe. One-shot Recipes omit Control. Larger data belongs in a declared artifact/path; outputs belong in Trace, artifacts, execution evidence, or the command result.
+Control action names are lowercase ASCII, unique, non-reserved, and at most 64 characters. Serialized Control input is limited to 380 bytes so admitted wire records remain within 512 bytes on FIFO and named pipe transports.
+
+Do not use Control as a general data channel. Large inputs belong in declared files or artifacts; outputs belong in Trace, artifacts, execution evidence, or the command result.
 
 ## Artifacts
 
+Declare deterministic outputs by stable name:
+
 ```json
 {
   "artifacts": {
     "report": "{state_dir}/report.md",
     "manifest": "{state_dir}/manifest.json"
-  }
+  },
+  "template": "generate-report --output {state_dir}/report.md"
 }
 ```
 
-Artifact paths resolve under containment policy and appear in Run inspection. Recipes should write declared artifacts deterministically and fail when the requested write policy cannot be honored.
-
-## File Origins
-
-Every file-backed Recipe receives immutable `{recipe_dir}`. A Recipe under an active Skill also receives `{skill_dir}`, resolved to the directory containing that Skill's `SKILL.md`; using `{skill_dir}` elsewhere fails clearly. These runtime values cannot be declared in `args`, `defaults`, or `values`, and caller input cannot override them. They expand in templates, recursive defaults/values, imports, and artifacts while existing `./` executable behavior remains relative to invocation `cwd`.
+Artifact declarations do not create files. The Recipe must write them and fail when its write policy cannot be honored. Inspection reports declaration, availability, size, and digest evidence without treating undeclared arbitrary paths as public artifacts.
 
-## Context and Provenance
+## Runtime Origins
 
-File-backed Runs capture Recipe context records for the entry and imports. File identity is the filename stem; a direct Recipe under an active Skill has the logical identity `<skill>/<stem>`. The captured bundle explains composition identity and remains generation-local evidence. Runtime origin paths remain in local Run provenance but are omitted from model-facing launch values. It does not override the authored task prompt.
+Every file-backed Recipe receives immutable `{recipe_dir}`, the directory containing the Recipe file. A Recipe directly owned by an active Skill also receives `{skill_dir}`, the directory containing that Skill's `SKILL.md`.
 
-Recipes that need a minimal child prompt may opt out of injected Recipe context through the documented `actor_context` launch option.
+| Placeholder | Availability | Meaning |
+| --- | --- | --- |
+| `{recipe_dir}` | every file-backed Recipe | Stable origin for Recipe-relative helpers and assets |
+| `{skill_dir}` | active Skill-owned Recipe only | Stable origin for Skill-owned helpers and assets |
+| `{state_dir}` | async Run context | Generation-local durable Run state directory |
+| `{current_model}` | when current Pi policy is available | Current model inherited as an explicit resolved value |
+| `{current_thinking}` | when current Pi policy is available | Current thinking policy inherited as an explicit resolved value |
 
-## Current Policy
+Origin and policy placeholders expand through templates, recursive defaults/values, imports, and artifacts where applicable. Resolution fails before launch when a required runtime value is unavailable.
 
-Defaults can inherit current Pi policy:
+Example policy inheritance:
 
 ```json
 {
+  "args": ["model:string", "thinking:string"],
   "defaults": {
     "model": "{current_model}",
     "thinking": "{current_thinking}"
-  }
+  },
+  "template": "pi -p inspect --model {model} --thinking {thinking}"
 }
 ```
 
-Resolution fails before launch when required current policy is unavailable. The Run persists whether values were inherited or explicit.
+## Context and Provenance
+
+A file-backed launch captures generation-local records for the entry Recipe and every resolved import. Records include role, filename stem, logical reference, Skill identity when applicable, and import alias ancestry.
 
-## Resolution Context
+Logical identities are exposed to Inspector and child-agent context. Machine-local physical paths remain local execution provenance and are not promoted into model-facing launch values.
 
-User Recipes under `~/.pi/agent/recipes` remain intentionally registered tools, not an ambient import namespace. Each session receives one immutable resolution context from Pi's loaded Skill metadata; spawn, user-Recipe admission, registration, schema derivation, live inspection, and watcher reconciliation consume that same context rather than scanning ambient Skill roots or keeping a process-global mutable namespace. A launch captures its resolved graph, so later Skill changes affect only future launches. An invalid or missing exact target fails without fallback. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+`actor_context` controls only compatible child-prompt injection:
 
-Active-Skill catalog inventory is fail-soft diagnostic state, not exact-resolution authority. Invalid components are reported individually and make the catalog partial while unrelated valid `<skill>/<recipe>` references remain exactly resolvable.
+```json
+{
+  "actor_context": false,
+  "template": "pi -p minimal-task"
+}
+```
+
+Disabling injected context does not remove Run provenance or change the authored task prompt.
+
+## Authoring Checklist
+
+1. Choose a direct Skill identity or explicit file location.
+2. When useful, add one outcome-oriented `description`; descriptions are optional.
+3. Declare every public input in `args`, including types where useful.
+4. Put overridable fallback configuration in `defaults`.
+5. Add imports only when composition earns a stable local alias.
+6. Keep execution flags on the node they govern.
+7. Use `async` only when detached lifecycle or durable evidence is required.
+8. Declare `control` only for actions the process actually consumes.
+9. Declare deterministic artifact paths before writing them.
+10. Validate exact references, portable paths, and platform assumptions.
 
 ## Validation
 
+Validate one Recipe:
+
 ```bash
 node skills/actors/scripts/validate-recipe.mjs path/to/recipe.json --qa
+```
+
+Validate all maintained Skill Recipes:
+
+```bash
 node skills/actors/scripts/validate-recipe.mjs skills --skills --qa --summary
 ```
 
-Skill validation recursively inventories every direct `<skill>/recipes/*.json|*.md` component, rejects nested files and duplicate stems, and checks filename identity, JSON/Markdown compilation, origins, imports, Control, artifacts, portable paths, helper targets, and platform notes. Files exceeding 1 MiB or import depth 32 fail closed.
+Validation checks file size, filename identity, JSON/Markdown compilation, argument contracts, imports, cycles and depth, runtime origins, Control, artifacts, portable paths, helper targets, and platform notes. Recipe files larger than 1 MiB and import graphs deeper than 32 levels fail closed.
 
 ## Related
 

package/docs/tool-registry.md

@@ -22,9 +22,21 @@ Specialize a maintained Recipe without copying its contract:
 register_tool name=music_player from=music-player/playback defaults={"source":"~/Music/1MIX"}
 ```
 
-`from`, `template`, and `draft` are distinct source modes. `from` accepts exact `<skill>/<recipe>` identity or an explicit `.json` / `.md` path and inherits async behavior, args/types, source defaults, artifacts, Control, and runtime-owned origins. `defaults` may set only effective caller-owned args and must satisfy their types. `template` is only for trusted command definitions; public `values` authoring has been removed in favor of caller defaults or an authored Recipe file.
+`from`, `template`, and `draft` are distinct source modes. `from` accepts exact `<skill>/<recipe>` identity or an explicit `.json` / `.md` path and inherits async behavior, args/types, source defaults, artifacts, Control, and runtime-owned origins. `defaults` may set only effective caller-owned args and must satisfy their types. `template` is only for trusted command definitions; specialization accepts caller `defaults`, while authored composition values belong in a Recipe file.
 
-Promote an immutable captured draft only with its draft path and explicit target name. Name collisions require `update=true`. Invalid content fails before active mutation.
+Promote an immutable captured draft only with its draft path and explicit target name:
+
+```text
+register_tool name=repo_check draft=~/.pi/agent/recipes/drafts/<captured-recipe>.json
+```
+
+Delete a persisted definition through the same fenced mutation path:
+
+```text
+register_tool name=repo_check template=null
+```
+
+An empty `template` string is the equivalent deletion form. Do not delete registry files manually. Host-visible dynamic definitions may remain visible until reload because Pi cannot unregister them, but extension-local lookup rejects the deleted definition immediately. Name collisions for creation or replacement require `update=true`. Invalid content fails before active mutation.
 
 Registration resolves the effective delegated contract before persistence, then reports logical `source`, effective `required_args` / `optional_args`, and distinct `persisted`, `registry_active`, `host_registered`, `active_tool`, and `callable_now` states. A callable result points to the actual generated tool as the next action. An uncallable result names its `activation_boundary` and status/doctor action without suggesting spawn as a substitute. Diagnose one maintained source with `inspect target=recipes view=doctor identity=<skill>/<recipe>`; diagnose final activation, source, schema summary, and separate spawn/tool usage with `inspect target=tool:<name> view=status`. Treat the tool as callable in the current session only when `callable_now` is true; persistence alone is not activation proof. Registration results omit raw persisted paths and executable template/config payloads.
 
@@ -41,10 +53,19 @@ inspect target=recipes view=status
 inspect target=tool:<name> view=status
 ```
 
-Recipe inspection reports generation, scan/watch state, active, shadowed, invalid, disabled, component rejection, diagnostic, risk, usage, and review evidence. Tool status reports current activation plus separate `tool_calls` and `spawn_calls`; tool schema reports the caller-owned capability contract. A registered tool is not a running actor.
+Recipe inspection reports generation, scan/watch state, active, shadowed, invalid, disabled, component rejection, diagnostic, risk, usage, and review evidence. Tool status reports current activation plus separate `tool_calls` and `spawn_calls`; tool schema reports the caller-owned capability contract. Inspect the complete target/view contract in [Management Inspection](./inspection.md). A registered tool is not a running actor.
 
 `spawn recipe=<name>` executes a Recipe and reports `launch_kind: "spawn"`; it does not prove that a registered tool was exposed or invoked. Registered-tool execution reports `launch_kind: "tool"`.
 
+Async registered tools add runtime-owned optional invocation parameters after resolving the Recipe contract:
+
+| Parameter | Availability | Purpose |
+| --- | --- | --- |
+| `run_id` | non-singleton async tools | Overrides the generated logical Run id for this invocation |
+| `transport_context` | all async tools | Preserves an originating transport route for detached terminal follow-up |
+
+These parameters are not Recipe-authored args. Singleton tools do not expose `run_id` because their canonical Run identity is owned by the Skill Recipe.
+
 ## Automatic Review
 
 Automatic draft/tool review remains silent and mechanically fenced: