@sublang/playbook 17.2.0 → 17.4.0

package/README.md

@@ -29,7 +29,7 @@ Run `playbook` for an interactive tmux UI powered by [cligent](https://github.co
 
 ## Quick start
 
-Out of the box, Playbook includes **CODE** for implementation, **REVIEW** for commit-based review and fixes, **DECIDE** for independently proposed and reviewed specification decisions, **DEV** for repository-aware planning of a development request, **BRANCH** for checking out a new branch for a GitHub issue, and **PR** for publishing, checking, and merging that branch through a pull request.
+Out of the box, Playbook includes **CODE** for implementation, **REVIEW** for commit-based review and fixes, **DECIDE** for independently proposed and reviewed specification decisions, **DEV** for repository-aware planning of a development request, **BRANCH** for checking out a new branch for a GitHub issue, **PR** for publishing, checking, and merging that branch through a pull request, and **INSPECT** for explaining supplied material or a running interface without changing the repository.
 CODE and DECIDE call REVIEW as a nested playbook; DEV calls CODE, or DECIDE and then CODE, and wraps them in BRANCH and PR when the request names a GitHub issue or asks for a pull request.
 
 The shared starter config selects one adapter for the Captain and all players
@@ -37,7 +37,8 @@ from locally visible credentials: Claude first, then Codex. If neither is
 configured, it seeds Claude and prints a notice. CODE, REVIEW, DECIDE, BRANCH, and PR bind
 their local roles explicitly to `dev.coder` and `dev.reviewer`, so nested and later
 engagements share a conversation only where their bindings name the same
-player ID; DEV's Analyst binds a distinct `dev.analyst` player.
+player ID; DEV's Analyst binds a distinct `dev.analyst` player and INSPECT's
+Inspector binds `inspect.inspector`.
 
 ```sh
 npm install -g @sublang/playbook
@@ -85,6 +86,8 @@ playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 "continue"
 
 If a step fails or needs preparation before your answer, ask Captain to fix the prerequisite and resume; see [Preparing a stopped step](docs/cli.md#preparing-a-stopped-step).
 
+Use `/inspect` to analyze existing material or explain a running interface. Browser access requires explicitly enabling the Inspector’s [browser capability](docs/configuration.md#browser-capability). Embedded hosts can submit portable attachments and display saved native figures through the [asset and session APIs](docs/embedding.md#attachments-and-captured-evidence).
+
 See [Using the CLI](docs/cli.md) for flags and durable continuation, [Configuring agents](docs/configuration.md) for the shared lineup, [Embedding](docs/embedding.md) for custom hosts, and the [changelog](https://github.com/sublang-ai/playbook/blob/main/CHANGELOG.md) for releases.
 
 ## Create your own playbook

package/docs/cli.md

@@ -202,8 +202,8 @@ The former positional `<from>`, `resume`, `--player`, `--captain`,
 `--option`, `--cwd`, `--last`, run-only `--config`, and top-level `run:`
 config are removed from `playbook run`. Enable a registry under `playbooks`,
 declare provider agents once under top-level `players`, bind every local role
-under `playbooks.<id>.roles`, tune compatible model, effort, fast mode, and
-subagent model in a `--with` overlay, invoke the effective `/command`, and run from the working directory
+under `playbooks.<id>.roles`, tune compatible model, effort, fast mode,
+subagent model, and subagent effort in a `--with` overlay, invoke the effective `/command`, and run from the working directory
 you want agents to use. Legacy `playbooks.<id>.players` blocks are rejected and
 are not auto-migrated because choosing equal or distinct new player IDs chooses
 conversation sharing or isolation; see [Migrating per-playbook
@@ -280,9 +280,10 @@ competing front end fails closed instead of forking the history.
 An ordinary reopen reads current config and any opening `--with` fragments,
 projects them to the stored catalog and player roster, and requires the stored
 role bindings plus every structural setting to remain exact. Compatible
-current `model`, `effort`, and optional `fastMode` and `subagentModel` settings
-apply to the next call. Boolean `false` explicitly resets model, effort, or
-subagent model to the provider default, but `fastMode: false` is a literal
+current `model`, `effort`, and optional `fastMode`, `subagentModel`, and
+`subagentEffort` settings apply to the next call. Boolean `false` explicitly
+resets model, effort, subagent model, or subagent effort to the provider
+default, but `fastMode: false` is a literal
 disabled request; omission selects the provider default or inherits the player
 value at a role binding.
 Provider conversations are local hints. Missing hints start fresh from stored

package/docs/configuration.md

@@ -48,8 +48,8 @@ names, nesting, and ancestry never infer a binding.
 
 Each `captain` or `players.<player-id>` value is either an adapter shorthand
 (`claude`, `codex`) or a block carrying that agent's own `adapter`, `model`,
-`effort`, `fastMode`, `subagentModel`, `instruction`, and `permissions`.
-Settings are inline per stable agent
+`effort`, `fastMode`, `subagentModel`, `subagentEffort`, `instruction`, and
+`permissions`. Settings are inline per stable agent
 ([DR-021](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/021-inline-agent-settings.md)).
 Dots in a player ID are literal characters, not YAML hierarchy. Other adapter
 IDs pass through to `tmux-play` with a warning because `playbook` cannot
@@ -102,6 +102,13 @@ players:
     permissions:
       mode: auto # protected auto mode for the Claude Analyst
 
+  inspect.inspector:
+    adapter: claude
+    model: claude-opus-5-5
+    effort: high
+    permissions:
+      mode: auto
+
 playbooks:
   code:
     from: '@sublang/playbook/code/registry'
@@ -138,6 +145,11 @@ playbooks:
     from: '@sublang/playbook/pr/registry'
     roles:
       coder: dev.coder
+
+  inspect:
+    from: '@sublang/playbook/inspect/registry'
+    roles:
+      inspector: inspect.inspector
 ```
 
 The current bundled workflows accept no workflow-specific options.
@@ -157,7 +169,7 @@ roles:
 ```
 
 Use a block to override only that role invocation's model, effort, fast mode,
-or subagent model:
+subagent model, or subagent effort:
 
 ```yaml
 roles:
@@ -168,25 +180,41 @@ roles:
     fastMode: false # literal disabled request, not a default sentinel
   reviewer:
     player: dev.reviewer
-    subagentModel: claude-sonnet-5-5 # every subagent of this role runs on it
+    subagentModel: inherit # inherit | <model> | false
+    subagentEffort: medium # <effort> | false
 ```
 
 Omitting any override inherits that player's top-level default. For `model`,
-`effort`, and `subagentModel`, boolean `false` selects the provider default
-explicitly, so a resumed conversation cannot accidentally retain an earlier
-selection. For `fastMode`, `false` is a literal request to disable fast mode;
-omitting the top-level setting selects the provider default. A present
-fast-mode boolean or subagent model is accepted only for adapters Cligent
-reports as supporting it. A role binding cannot override adapter, instruction,
+`effort`, `subagentModel`, and `subagentEffort`, boolean `false` selects the
+provider default explicitly, so a resumed conversation cannot accidentally
+retain an earlier selection. For `fastMode`, `false` is a literal request to
+disable fast mode; omitting the top-level setting selects the provider default.
+A present fast-mode boolean, subagent model, or subagent effort is accepted
+only for adapters Cligent reports as supporting it. A role binding cannot override adapter, instruction,
 permissions, workspace, or tool posture; those define the stable player
 envelope, so an overriding model must be one that player's adapter serves.
 
-A subagent model makes every subagent the agent starts run on that model, and
-tells the agent to hand well-defined, fine-grained tasks to its subagents while
+`subagentModel` makes every subagent the agent starts run on one model —
+`inherit` names the agent's own, a model name pins another, and `false` on a
+`captain` or `players.<player-id>` block switches delegation off — and tells
+the agent to hand well-defined, fine-grained tasks to its subagents while
 keeping the deep thinking, reasoning, and design work itself, without lowering
 the quality of what it delivers
 ([DR-075](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/075-subagent-model-is-tuning.md)).
-Nothing sets one by default.
+`subagentEffort`, any effort the adapter accepts other than `ultracode`, pins
+the effort the agent's delegated work runs at; left unset, the agent chooses an
+effort per task. On Claude, a pinned effort governs Cligent's `delegate`
+subagent and the `general-purpose` one it replaces, while an unpinned agent's
+choice runs through `delegate-<effort>` subagents and a call naming no type
+runs `general-purpose` at `medium`; `Explore` and `Plan` are never replaced and
+keep the agent's own effort
+([Cligent DR-029](https://github.com/sublang-ai/cligent/blob/main/specs/decisions/029-subagent-effort.md)).
+An agent whose adapter serves a subagent model (Claude today) and whose block
+leaves `subagentModel` unset resolves to `inherit`: it delegates by default.
+The launcher resolves this on its own copy and never rewrites your config, and
+the starter config names neither field
+([DR-076](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/076-subagents-delegate-by-default.md)).
+
 
 ## Sharing, isolation, and concurrency
 
@@ -246,6 +274,30 @@ Claude Code auth or `ANTHROPIC_API_KEY`; `codex` with local Codex CLI
 auth or `OPENAI_API_KEY`. A known adapter that is not ready blocks the
 launch and prints the help text.
 
+## Browser capability
+
+A Captain or player agent block may set `browser: true` to make Cligent's managed
+browser tools available to working calls. Existing configurations default to
+false. This is an execution capability: reopening the same settled session with a
+changed value applies it to the next accepted turn. Recovery of an uncertain turn
+uses that attempt's recorded value. Agent permissions remain fixed and retain
+their native precedence.
+
+Ordinary Captain decisions, replies, question checks and judges always receive
+`browser: false` and an empty MCP configuration. Enabling Browser does not turn
+them into working actors. A working player, or bounded recovery preparation when
+needed, can use the capability explicitly configured for its agent. An embedding
+application should use Cligent's capability and browser-preparation APIs before
+enabling its Browser control and report setup failures; Playbook does not invent a
+successful setup or change permissions to make it succeed.
+
+For browser inspection, enable `browser: true` on `players.inspect.inspector`
+and ask `/inspect Open http://localhost:3000, capture a screenshot, and explain
+the navigation.` Keep the application running and give its exact address. The
+Inspector uses actual tool results and native images, asks about missing targets,
+and reports unavailable evidence explicitly. Browser capture supports web pages;
+it does not grant arbitrary operating-system desktop control.
+
 ## Per-launch overlays
 
 To retune one launch without editing the file, overlay a fragment in
@@ -279,6 +331,7 @@ playbooks:
       coder:
         player: dev.coder
         effort: low
+        subagentEffort: high # its delegates still run at high effort
 ```
 
 The global file is never modified, and `--with` is not forwarded to
@@ -286,9 +339,10 @@ The global file is never modified, and `--with` is not forwarded to
 Overlays apply when creating a fresh session and as current-config input for a
 compatible ordinary reopen. A selected session keeps its stored catalog,
 player roster, role bindings, adapter, instruction, permissions, and working
-directory; only model, effort, fast mode, and subagent model may change. The
-next call reapplies both complete model and effort selections, the optional
-effective fast-mode boolean, and the optional effective subagent model. An uncertain retry accepts no tuning overlay and only restores and reports the recorded attempt. Later turns use the current compatible settings.
+directory; only model, effort, fast mode, subagent model, and subagent effort
+may change. The next call reapplies both complete model and effort selections,
+the optional effective fast-mode boolean, and the optional effective subagent
+model and subagent effort. An uncertain retry accepts no tuning overlay and only restores and reports the recorded attempt. Later turns use the current compatible settings.
 
 ## Session storage
 
@@ -329,8 +383,8 @@ public UUID. Presentation-only fields are inert headlessly.
 An ordinary reopen reads current config and opening overlays, but first
 projects them to the stored playbooks and referenced players. An unrelated new
 entry cannot enter or invalidate the session. Structural drift fails closed;
-compatible model, effort, fast-mode, or subagent-model changes apply on the
-next provider call. Legacy record, shell, runtime-snapshot, and trace schemas are rejected
+compatible model, effort, fast-mode, subagent-model, or subagent-effort
+changes apply on the next provider call. Legacy record, shell, runtime-snapshot, and trace schemas are rejected
 rather than having role or player identity guessed.
 
 ## External playbooks

package/docs/embedding.md

@@ -492,3 +492,97 @@ contracts. Their JavaScript module exports are internal implementation details
 and carry no SemVer compatibility guarantee.
 The initializer requires further semantic compilation and verification
 before its output is runnable.
+
+## Attachments and captured evidence
+
+The shared host accepts `handleBossTurn({ text, attachments })` as well as a plain
+string. Keep the user's text exact. Import uploads through the controller's
+existing lease before submitting the turn; portable references contain a content
+hash, MIME type, byte count and optional display name, never a machine path.
+
+```ts
+const reference = await controller.lease.importAsset({
+  path: stagedUploadPath,
+  mimeType: 'image/png',
+  name: 'Reference screen.png',
+});
+await controller.handleBossTurn({
+  text: 'Compare the running interface with this reference.',
+  attachments: [reference],
+});
+```
+
+An empty text with attachments is accepted, recorded and answered with a host-owned
+clarification. It makes no model call and fabricates no instruction. Captain can
+then explicitly select the pending attachment IDs for the clarified request.
+Omitted selection means only uploads from the current turn. Working engagements
+retain selected references, and nested calls inherit their parent's snapshot;
+finishing, dismissing or starting unrelated work does not implicitly reuse them.
+Captain decisions, judges and closing replies see metadata only. A capable worker
+receives the actual selected files; unavailable required evidence fails that call
+explicitly, without requiring the controller's provider to support the same media.
+
+Observe the `SessionRecord` union from `@sublang/playbook/session-assets` or
+`@sublang/playbook/session-host`. `turn_started.turn.attachments` preserves input
+references. A `playbook_evidence` record carries a saved output asset with its turn,
+call and player or preparation origin; present it in the main conversation.
+Duplicate content is promoted once per call. Native worker `media` events remain
+in the worker lane, using `playbook-asset:<assetId>` URIs after persistence. Hidden
+controller traffic is never promoted as visible evidence. URI-only native media
+is preserved without fetching remote URLs or reading arbitrary local files.
+
+Tool-result output JSON larger than 4096 UTF-8 bytes becomes
+`{ type: 'asset_reference', asset }`; retrieve and decode the original JSON when a
+user opens its details. Base64 media is stored outside replay lines. An unavailable
+or oversized output is reported explicitly instead of being replayed inline.
+These host projections do not alter the native agent's own tool-result reasoning.
+
+Use `shared.openAsset(sessionId, reference)` for verified bounded reads and close
+the returned reader in `finally`. `shared.readAsset()` reads a whole asset, and
+`describeAsset()` looks up a descriptor by ID. The default per-asset maximum is
+100 MiB; hosts may impose smaller upload or turn limits. `exportBundle()` returns
+exact manifest bytes, the checkpoint's exact replay prefix and verified relative
+asset entries. Copy all of them together. Session deletion removes only that
+session's asset owner; copies in other owners remain independent. All hosts sharing
+the store must support the optional asset inventory before writing it.
+
+For uploads awaiting a session, draft work or direct authoring calls, use
+`createAssetStore({ directory })` from `@sublang/playbook/session-assets` under your
+own owner lifetime and writer coordination. Its `prepare()` validates ownership
+and tightens Git-restored permissions without changing bytes. `copyAsset()` imports
+verified content into another owner. `externalizeAgentEvent(store, event)` shares
+the same native-media and large-tool-result ingestion boundary with authoring;
+it returns the projected event and, for native media, its asset reference. Handle
+persistence failures explicitly, and never save the original large payload as a
+fallback.
+
+Captured native media also becomes evidence for still-active parent workflows in the same engagement, so a parent can continue reasoning about a child's figure. Newly submitted Boss attachments stay scoped to the addressed worker; neither kind is implicitly inherited by unrelated later work.
+
+Before adopting asset-bearing sessions, upgrade every Playbook CLI and embedded SDK that shares the store and stop all older writers. Older readers tolerating unknown replay records does not make older writers compatible: they may discard additive asset metadata on save.
+
+Accepted visible worker prose also reaches Captain as attributed, quoted observations, separately from effect and completion facts. Reports keep up to 8192 rendered characters each and 24576 across the latest accepted observations, labeling truncated or omitted content; full text stays in the durable ledger. Interrupted reporting uses an exact producing-boundary reference saved with the player result. Older progress without that reference contributes no inferred report, and recovery never reruns a worker merely to recreate its prose.
+
+## Live tool approvals
+
+`openSessionHost` and `createCaptainSessionHost` accept an ephemeral
+`approvalHandler(envelope, { signal })` callback. Its exported
+`TmuxPlayApprovalRequest` envelope contains the original native `request`, the
+persisted `turnId`, the concrete `actorId`, and a fresh `invocationId` for that
+working call. Return `allow_once` or `deny`; an application should bind its own
+session or draft identity in the callback closure and stop showing a request
+when its signal aborts. Hidden control and tool-free calls receive no callback.
+
+The callback is never configuration or model input. Native request/response
+events remain historical actor records, and reopening does not make an old
+request actionable. Native provider limits and OS dialogs still apply; a tool
+approval cannot grant an operating-system permission. Controller disposal denies
+pending requests before draining work and releasing the session lease. Without a
+handler, adapters retain their native fail-closed behavior.
+
+This callback handles tool consent independently of tool or application names.
+Native questions, forms, and URL authentication require separate typed response
+transports; a later Boss reply cannot answer a native callback still waiting
+inside the current call. A workflow can instead return its declared Boss-question
+outcome and resume after a reply, including a request to perform an external
+prerequisite. The reply is an acknowledgement; the working agent must check the
+prerequisite before claiming that it is satisfied.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.2.0",
+  "version": "17.4.0",
   "type": "module",
-  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
+  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/sublang-ai/playbook#readme",
   "repository": {
@@ -146,7 +146,24 @@
     "reference/sdlc/code.playbook/session-host.js",
     "reference/sdlc/code.playbook/session-host.d.ts",
     "reference/sdlc/code.playbook/bin/portable-codec.js",
-    "reference/sdlc/code.playbook/bin/session-host.js"
+    "reference/sdlc/code.playbook/bin/session-host.js",
+    "reference/sdlc/code.playbook/session-assets.js",
+    "reference/sdlc/code.playbook/session-assets.d.ts",
+    "reference/sdlc/code.playbook/bin/session-media.js",
+    "reference/sdlc/code.playbook/asset-types.d.ts",
+    "reference/sdlc/code.playbook/worker-evidence.js",
+    "reference/sdlc/code.playbook/worker-evidence.d.ts",
+    "reference/sdlc/inspect.md",
+    "reference/sdlc/inspect.playbook/inspect.gears.md",
+    "reference/sdlc/inspect.playbook/inspect.fsm.ts",
+    "reference/sdlc/inspect.playbook/inspect.fsm.js",
+    "reference/sdlc/inspect.playbook/inspect.fsm.d.ts",
+    "reference/sdlc/inspect.playbook/inspect.playbook.ts",
+    "reference/sdlc/inspect.playbook/inspect.playbook.js",
+    "reference/sdlc/inspect.playbook/inspect.playbook.d.ts",
+    "reference/sdlc/inspect.playbook/inspect.registry.ts",
+    "reference/sdlc/inspect.playbook/inspect.registry.js",
+    "reference/sdlc/inspect.playbook/inspect.registry.d.ts"
   ],
   "bin": {
     "playbook": "reference/sdlc/code.playbook/bin/playbook.js"
@@ -228,12 +245,24 @@
     "./session-host": {
       "types": "./reference/sdlc/code.playbook/session-host.d.ts",
       "default": "./reference/sdlc/code.playbook/session-host.js"
+    },
+    "./session-assets": {
+      "types": "./reference/sdlc/code.playbook/session-assets.d.ts",
+      "default": "./reference/sdlc/code.playbook/session-assets.js"
+    },
+    "./inspect/playbook": {
+      "types": "./reference/sdlc/inspect.playbook/inspect.playbook.d.ts",
+      "default": "./reference/sdlc/inspect.playbook/inspect.playbook.js"
+    },
+    "./inspect/registry": {
+      "types": "./reference/sdlc/inspect.playbook/inspect.registry.d.ts",
+      "default": "./reference/sdlc/inspect.playbook/inspect.registry.js"
     }
   },
   "scripts": {
     "build": "tsc",
     "test": "spex lint && vitest run --exclude src/cligent-release-capabilities.test.ts && vitest run src/cligent-release-capabilities.test.ts",
-    "test:acceptance": "vitest run --config vitest.acceptance.config.ts",
+    "test:acceptance": "node scripts/run-live-acceptance.mjs",
     "smoke:release": "node scripts/release-smoke.mjs",
     "check:links": "node scripts/check-links.mjs",
     "playbook": "node reference/sdlc/code.playbook/bin/playbook.js"
@@ -243,7 +272,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.29.0",
+    "@sublang/cligent": "^0.33.1",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/captain.md

@@ -8,7 +8,7 @@ It has no players beyond Boss and Captain.
 It declares the session-scoped controller policy: a session Captain that runs for the whole host session, receives every Boss turn, and operates the working playbooks from outside the engagement stack.
 Captain is the controller, not the specialist that performs the requested work.
 A `recover` action authorizes a separate host-owned Captain preparation call to repair prerequisites within Boss's instructions before the runtime continues the interrupted leaf; this controller's own calls remain tool-free.
-Captain shall decide each turn only from the exact Boss text, the supplied ControlView and catalog digests, and its remembered session conversation, without investigating the task, inspecting the workspace, using tools, or relying on ambient project evidence.
+Captain shall decide each turn only from the exact Boss text, the supplied ControlView and catalog digests, supplied attachment and evidence metadata, and its remembered session conversation, without investigating the task, inspecting the workspace, using tools, or relying on ambient project evidence.
 
 At runtime the host supplies an immutable catalog of enabled callable playbooks; each entry contains only a stable playbook id, its command, and its intent.
 The catalog is immutable host input for the session; Boss events and Captain decisions cannot replace it.
@@ -57,6 +57,7 @@ When Boss submits a turn that the host's command parse did not resolve, Captain
 > `{ "action": "runtime", "actionId": … }` — apply the runtime action `actionId` names, only when the ControlView digest currently advertises it and only on Boss's explicit recovery or resume request.
 > `{ "action": "recover" }` — prepare the interrupted leaf and continue it when recovery preparation is advertised and the task should continue. Task authorization includes necessary cleanup and preparation. Ask Boss only for missing decisions, authority, or an incomplete or contradictory playbook. Ordinary answers use `deliver`; a retry requiring no preparation uses `runtime`.
 > Honor explicit Boss intent first. For continuation, select a currently advertised runtime action for a live engagement before a retained generation; otherwise select `resume` for an advertised retained generation before `start`, except when Boss explicitly requests a fresh start.
+> For `start`, `switch`, or `deliver`, optionally include `attachmentIds: [...]` selecting only supplied opaque asset identifiers relevant to the agreed request. Omission selects only attachments submitted in the current Boss turn. Select earlier pending attachments explicitly when Boss clarifies or says to proceed; never include unrelated prior material. Attachment metadata is not evidence that you viewed its bytes.
 > Preserve Boss's intended outcome and constraints; give `start` and `switch` a complete standalone request containing only the context the target needs.
 > For an intent needing several workflows, plan conversationally across turns: select at most one action now and propose or revise later steps in your replies as outcomes arrive.
 > Keep the reply to 60 words unless extra words are essential to preserve choices, constraints, or result evidence.
@@ -66,13 +67,14 @@ When Boss submits a turn that the host's command parse did not resolve, Captain
 Results:
 - `respond`: Captain settled the turn in this decision call; the validated text is the turn's captain speech. Output shall include `text: <the complete captain reply>`.
 - `resume`: Captain selected resuming an advertised retained generation. Output shall include `playbookId: <stable catalog id>`.
-- `start`: Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.
-- `switch`: Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.
+- `start`: Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`, and may include `attachmentIds: <unique array of supplied opaque asset identifiers>`.
+- `switch`: Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`, and may include `attachmentIds: <unique array of supplied opaque asset identifiers>`.
 - `dismiss`: Captain selected stopping the active engagement; the selection carries no payload field.
-- `deliver`: Captain selected handing the turn to the working playbook; the host is authoritative for the delivered text, so the selection carries no payload field.
+- `deliver`: Captain selected handing the turn to the working playbook; the host is authoritative for the delivered text, so the selection carries no text field and may include only `attachmentIds: <unique array of supplied opaque asset identifiers>`.
 - `runtime`: Captain selected one advertised runtime action. Output shall include `actionId: <advertised action id>`.
 - `recover`: Captain selected preparing the interrupted leaf and continuing it; the selection carries no payload field.
 
+An `attachmentIds` value must be an array of unique strings, each exactly `sha256:` followed by 64 lowercase hexadecimal digits; the host independently validates availability and scope.
 The compiled decision result guards are exactly `respond`, `resume`, `start`, `switch`, `dismiss`, `deliver`, `runtime`, and `recover`, respectively, with those payload fields; these names are part of this default playbook's stable machine contract.
 As decision and reply evidence the machine retains only a settlement's status, its canonical outcome-report facts, its exact bounded `unresolvedEffects` list, its optional rejection reason, the receipt disposition with its reason or a compact `{ name, message }` error, and the leaf-state summary; it never retains a playbook session id, call id, child state, stack ledger, resume token, repository path or projection, internal effect-envelope data, aggregate conversation or recovery transcript, or opaque runtime result.
 

package/reference/sdlc/captain.playbook/captain.fsm.d.ts

@@ -22,8 +22,10 @@ export type ParsedActingDecision = {
     readonly action: 'start' | 'switch';
     readonly playbookId: string;
     readonly input: string;
+    readonly attachmentIds?: readonly string[];
 } | {
     readonly action: 'deliver';
+    readonly attachmentIds?: readonly string[];
 };
 /** Compact `{ name, message }` error evidence (never a raw Error). */
 export type CompactError = {
@@ -96,17 +98,20 @@ export type CaptainOutput = {
     readonly guard: 'start';
     readonly playbookId: string;
     readonly input: string;
+    readonly attachmentIds?: readonly string[];
     readonly settlement: SettlementEvidence;
 } | {
     readonly guard: 'switch';
     readonly playbookId: string;
     readonly input: string;
+    readonly attachmentIds?: readonly string[];
     readonly settlement: SettlementEvidence;
 } | {
     readonly guard: 'dismiss' | 'recover';
     readonly settlement: SettlementEvidence;
 } | {
     readonly guard: 'deliver';
+    readonly attachmentIds?: readonly string[];
     readonly settlement: SettlementEvidence;
 } | {
     readonly guard: 'runtime';

package/reference/sdlc/captain.playbook/captain.fsm.js

@@ -30,6 +30,7 @@ const DECISION_PROMPT = [
     "`{ \"action\": \"runtime\", \"actionId\": … }` — apply the runtime action `actionId` names, only when the ControlView digest currently advertises it and only on Boss's explicit recovery or resume request.",
     '`{ "action": "recover" }` — prepare the interrupted leaf and continue it when recovery preparation is advertised and the task should continue. Task authorization includes necessary cleanup and preparation. Ask Boss only for missing decisions, authority, or an incomplete or contradictory playbook. Ordinary answers use `deliver`; a retry requiring no preparation uses `runtime`.',
     'Honor explicit Boss intent first. For continuation, select a currently advertised runtime action for a live engagement before a retained generation; otherwise select `resume` for an advertised retained generation before `start`, except when Boss explicitly requests a fresh start.',
+    "For `start`, `switch`, or `deliver`, optionally include `attachmentIds: [...]` selecting only supplied opaque asset identifiers relevant to the agreed request. Omission selects only attachments submitted in the current Boss turn. Select earlier pending attachments explicitly when Boss clarifies or says to proceed; never include unrelated prior material. Attachment metadata is not evidence that you viewed its bytes.",
     "Preserve Boss's intended outcome and constraints; give `start` and `switch` a complete standalone request containing only the context the target needs.",
     'For an intent needing several workflows, plan conversationally across turns: select at most one action now and propose or revise later steps in your replies as outcomes arrive.',
     'Keep the reply to 60 words unless extra words are essential to preserve choices, constraints, or result evidence.',
@@ -65,10 +66,10 @@ const CLOSING_REPLY_PROMPT = [
 const DECISION_RESULTS = {
     respond: "Captain settled the turn in this decision call; the validated text is the turn's captain speech. Output shall include `text: <the complete captain reply>`.",
     resume: 'Captain selected resuming an advertised retained generation. Output shall include `playbookId: <stable catalog id>`.',
-    start: 'Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.',
-    switch: 'Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.',
+    start: "Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`, and may include `attachmentIds: <unique array of supplied opaque asset identifiers>`.",
+    switch: "Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`, and may include `attachmentIds: <unique array of supplied opaque asset identifiers>`.",
     dismiss: 'Captain selected stopping the active engagement; the selection carries no payload field.',
-    deliver: 'Captain selected handing the turn to the working playbook; the host is authoritative for the delivered text, so the selection carries no payload field.',
+    deliver: "Captain selected handing the turn to the working playbook; the host is authoritative for the delivered text, so the selection carries no text field and may include only `attachmentIds: <unique array of supplied opaque asset identifiers>`.",
     runtime: 'Captain selected one advertised runtime action. Output shall include `actionId: <advertised action id>`.',
     recover: 'Captain selected preparing the interrupted leaf and continuing it; the selection carries no payload field.',
 };

package/reference/sdlc/captain.playbook/captain.fsm.ts

@@ -55,8 +55,9 @@ export type ParsedActingDecision =
       readonly action: 'start' | 'switch';
       readonly playbookId: string;
       readonly input: string;
+      readonly attachmentIds?: readonly string[];
     }
-  | { readonly action: 'deliver' };
+  | { readonly action: 'deliver'; readonly attachmentIds?: readonly string[] };
 
 /** Compact `{ name, message }` error evidence (never a raw Error). */
 export type CompactError = {
@@ -147,12 +148,14 @@ export type CaptainOutput =
       readonly guard: 'start';
       readonly playbookId: string;
       readonly input: string;
+      readonly attachmentIds?: readonly string[];
       readonly settlement: SettlementEvidence;
     }
   | {
       readonly guard: 'switch';
       readonly playbookId: string;
       readonly input: string;
+      readonly attachmentIds?: readonly string[];
       readonly settlement: SettlementEvidence;
     }
   | {
@@ -161,6 +164,7 @@ export type CaptainOutput =
     }
   | {
       readonly guard: 'deliver';
+      readonly attachmentIds?: readonly string[];
       readonly settlement: SettlementEvidence;
     }
   | {
@@ -238,6 +242,7 @@ const DECISION_PROMPT = [
   "`{ \"action\": \"runtime\", \"actionId\": … }` — apply the runtime action `actionId` names, only when the ControlView digest currently advertises it and only on Boss's explicit recovery or resume request.",
   '`{ "action": "recover" }` — prepare the interrupted leaf and continue it when recovery preparation is advertised and the task should continue. Task authorization includes necessary cleanup and preparation. Ask Boss only for missing decisions, authority, or an incomplete or contradictory playbook. Ordinary answers use `deliver`; a retry requiring no preparation uses `runtime`.',
   'Honor explicit Boss intent first. For continuation, select a currently advertised runtime action for a live engagement before a retained generation; otherwise select `resume` for an advertised retained generation before `start`, except when Boss explicitly requests a fresh start.',
+  "For `start`, `switch`, or `deliver`, optionally include `attachmentIds: [...]` selecting only supplied opaque asset identifiers relevant to the agreed request. Omission selects only attachments submitted in the current Boss turn. Select earlier pending attachments explicitly when Boss clarifies or says to proceed; never include unrelated prior material. Attachment metadata is not evidence that you viewed its bytes.",
   "Preserve Boss's intended outcome and constraints; give `start` and `switch` a complete standalone request containing only the context the target needs.",
   'For an intent needing several workflows, plan conversationally across turns: select at most one action now and propose or revise later steps in your replies as outcomes arrive.',
   'Keep the reply to 60 words unless extra words are essential to preserve choices, constraints, or result evidence.',
@@ -279,13 +284,13 @@ const DECISION_RESULTS = {
   resume:
     'Captain selected resuming an advertised retained generation. Output shall include `playbookId: <stable catalog id>`.',
   start:
-    'Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.',
+    "Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`, and may include `attachmentIds: <unique array of supplied opaque asset identifiers>`.",
   switch:
-    'Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.',
+    "Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`, and may include `attachmentIds: <unique array of supplied opaque asset identifiers>`.",
   dismiss:
     'Captain selected stopping the active engagement; the selection carries no payload field.',
   deliver:
-    'Captain selected handing the turn to the working playbook; the host is authoritative for the delivered text, so the selection carries no payload field.',
+    "Captain selected handing the turn to the working playbook; the host is authoritative for the delivered text, so the selection carries no text field and may include only `attachmentIds: <unique array of supplied opaque asset identifiers>`.",
   runtime:
     'Captain selected one advertised runtime action. Output shall include `actionId: <advertised action id>`.',
   recover:

package/reference/sdlc/captain.playbook/captain.gears.md

@@ -3,6 +3,8 @@
 
 # Captain GEARS
 
+An `attachmentIds` value must be an array of unique strings, each exactly `sha256:` followed by 64 lowercase hexadecimal digits; the host independently validates availability and scope.
+
 ### CAPTAIN-1
 
 Where this is the default generic Captain playbook — the session Captain, with no players beyond Boss and Captain — declaring the session-scoped controller policy of a session Captain that runs for the whole host session, receives every Boss turn, and operates the working playbooks from outside the engagement stack without performing the requested work itself, where the host supplies an immutable catalog of enabled callable playbooks whose entries contain only a stable playbook id, its command, and its intent and which Boss events and Captain decisions cannot replace, where a `start`, `resume`, or `switch` selection shall name only an id in that catalog and never this Captain playbook itself, where Captain shall decide each turn only from the exact Boss text, the supplied ControlView and catalog digests, and its remembered session conversation, without investigating the task, inspecting the workspace, using tools, or relying on ambient project evidence, where this call runs hidden on the host's one durable session conversation whose resume token the host pins and rotates, where the host composes and appends the labeled Boss-message, ControlView digest, and catalog digest blocks this prompt references and this playbook composes no digest itself, where Source deliberately places the one `{ action, … }` JSON reply contract in this hidden controller call's acting prompt, where the linked runtime validates the decision reply against the declared result contract — known action, required payload fields, catalog membership, never this Captain playbook itself as a target — and issues exactly one corrective re-ask for a malformed reply, where a second malformed reply settles the turn as a Boss-appropriate failure reply with no action executed and the engagement stack untouched and the machine returns to its hub for the next turn, where per Boss turn the linked runtime submits at most one validated selection through the host-supplied controller port and treats the returned settlement — status, outcome-report facts, optional rejection reason, optional receipt, and leaf-state summary — as the only evidence of effects while the host supplies its separately counted activity only to the result-phase prompt, where the host owns validation and execution of effects and a rejected selection executes no action, where every settlement is final for its turn so an action is never submitted again after the controller returns `ok`, `rejected`, or `failed`, where a turn the host's deterministic command parse resolved enters with its decision already made — the injected parse-resolved decision object is that turn's decision, no decision call occurs, and an acting parse-resolved decision follows the same validation, execution, outcome report, and closing reply as a model-decided acting turn — and where as decision and reply evidence the machine retains only a settlement's status, its outcome-report facts, its optional rejection reason, the receipt disposition with its reason or a compact `{ name, message }` error, and the leaf-state summary and never retains a playbook session id, call id, child state, stack ledger, resume token, or opaque runtime result, when Boss submits a turn that the host's command parse did not resolve, Captain shall decide the turn by selecting exactly one action:
@@ -24,6 +26,7 @@ Where this is the default generic Captain playbook — the session Captain, with
 > `{ "action": "runtime", "actionId": … }` — apply the runtime action `actionId` names, only when the ControlView digest currently advertises it and only on Boss's explicit recovery or resume request.
 > `{ "action": "recover" }` — prepare the interrupted leaf and continue it when recovery preparation is advertised and the task should continue. Task authorization includes necessary cleanup and preparation. Ask Boss only for missing decisions, authority, or an incomplete or contradictory playbook. Ordinary answers use `deliver`; a retry requiring no preparation uses `runtime`.
 > Honor explicit Boss intent first. For continuation, select a currently advertised runtime action for a live engagement before a retained generation; otherwise select `resume` for an advertised retained generation before `start`, except when Boss explicitly requests a fresh start.
+> For `start`, `switch`, or `deliver`, optionally include `attachmentIds: [...]` selecting only supplied opaque asset identifiers relevant to the agreed request. Omission selects only attachments submitted in the current Boss turn. Select earlier pending attachments explicitly when Boss clarifies or says to proceed; never include unrelated prior material. Attachment metadata is not evidence that you viewed its bytes.
 > Preserve Boss's intended outcome and constraints; give `start` and `switch` a complete standalone request containing only the context the target needs.
 > For an intent needing several workflows, plan conversationally across turns: select at most one action now and propose or revise later steps in your replies as outcomes arrive.
 > Keep the reply to 60 words unless extra words are essential to preserve choices, constraints, or result evidence.
@@ -33,10 +36,10 @@ Where this is the default generic Captain playbook — the session Captain, with
 Results:
 - `respond`: Captain settled the turn in this decision call; the validated text is the turn's captain speech. Output shall include `text: <the complete captain reply>`.
 - `resume`: Captain selected resuming an advertised retained generation. Output shall include `playbookId: <stable catalog id>`.
-- `start`: Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.
-- `switch`: Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`.
+- `start`: Captain selected starting an enabled playbook. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`, and may include `attachmentIds: <unique array of supplied opaque asset identifiers>`.
+- `switch`: Captain selected replacing the active engagement. Output shall include `playbookId: <stable catalog id>` and `input: <one nonempty complete standalone request>`, and may include `attachmentIds: <unique array of supplied opaque asset identifiers>`.
 - `dismiss`: Captain selected stopping the active engagement; the selection carries no payload field.
-- `deliver`: Captain selected handing the turn to the working playbook; the host is authoritative for the delivered text, so the selection carries no payload field.
+- `deliver`: Captain selected handing the turn to the working playbook; the host is authoritative for the delivered text, so the selection carries no text field and may include only `attachmentIds: <unique array of supplied opaque asset identifiers>`.
 - `runtime`: Captain selected one advertised runtime action. Output shall include `actionId: <advertised action id>`.
 - `recover`: Captain selected preparing the interrupted leaf and continuing it; the selection carries no payload field.
 

package/reference/sdlc/captain.playbook/captain.playbook.d.ts

@@ -17,10 +17,12 @@ export type CaptainControllerSelection = {
     readonly playbookId: string;
     /** Complete standalone request synthesized from the remembered Boss conversation. */
     readonly input: CaptainControllerInput;
+    readonly attachmentIds?: readonly string[];
 } | {
     readonly action: 'dismiss' | 'recover';
 } | {
     readonly action: 'deliver';
+    readonly attachmentIds?: readonly string[];
 } | {
     readonly action: 'runtime';
     readonly actionId: string;