feat(run): image attachment passthrough with provenance

Adds the operator-facing --attach surface and the spawn-time
provenance contract: each attached image is anchored to the run via
an HMAC-chained audit event, the content-addressed blob store, and
the worker's lineage v1 receipt parents.

Changes:
- Add Task.attachments list field and plumb it through Task.from_dict.
- New module src/bernstein/core/agents/multimodal_attestation.py:
  build_attachment_context() reads paths, stores bytes in CAS,
  records the audit event, and returns a MultiModalContext.
- New module src/bernstein/core/security/audit_chain.py: AuditChainStore
  facade over AuditLog plus the additive multimodal.attach event type
  and the record_multimodal_attach() helper.
- Additive helpers in core/persistence/lineage_signer.py for the
  attachment-as-parent URI scheme.
- CLI: --attach option on bernstein run, repeatable, validated path,
  with capability gating before any process is launched.
- Adapters: Claude and Gemini accept multimodal_context= and inline
  base64-encoded attachments with the documented wire format.
- YAML plan loader honours an attachments: list on each step.
- Worktree pinning enforced at resolve time; cross-worktree attempts
  raise WorktreeAccessDenied.
- Documentation in docs/operations/run.md.
- Tests:
  - tests/unit/test_multimodal_attestation.py: 23 cases covering
    Task model field, capability gating, sha256 stability, audit
    record shape, lineage parents, worktree isolation, replay,
    tamper detection, chain continuity, and YAML plan loader.
  - tests/integration/test_run_attach.py: end-to-end stub-adapter
    round-trip plus CLI option validation.

Closes #1797

Author: auto-heal-fixup

docs/operations/run.md

@@ -0,0 +1,100 @@
+# `bernstein run` operator notes
+
+This document covers the `bernstein run` surface and operator-facing
+flags. Other run-related docs:
+
+* [`run_names.md`](run_names.md) -- the memorable deterministic run-name
+  generator.
+* [`runbooks.md`](runbooks.md) -- recovery playbooks for stuck or
+  failed runs.
+
+## Image attachments (`--attach`)
+
+`bernstein run` accepts one or more `--attach <path>` arguments to
+hand operator-supplied images (screenshots, diagrams) to the spawned
+agent. Repeat the flag for multiple files:
+
+```
+bernstein run --goal "Reproduce the failure shown" \
+  --attach ./screenshot.png \
+  --attach ./architecture.svg \
+  --cli claude
+```
+
+### Capable adapters
+
+Only `claude` and `gemini` accept attachments. Selecting any other
+adapter (`codex`, `aider`, `qwen`, ...) with `--attach` aborts the
+run BEFORE any process is launched with a `UsageError` that names
+the capable adapters.
+
+### Wire format
+
+Attached files are read at spawn time and inlined into the prompt
+body as base64-encoded `<attachment>` blocks at the head of the
+prompt:
+
+```
+<attachment mime="image/png" sha256="<64 hex chars>">
+<base64 payload>
+</attachment>
+
+<original prompt body>
+```
+
+Both adapters use the same wire format so a replay path can
+verify exact bytes regardless of provider.
+
+### Provenance
+
+For each `--attach` invocation the orchestrator:
+
+1. Hashes the raw bytes (SHA-256) and stores them once in the
+   content-addressed blob store at `.sdd/cas/`.
+2. Appends a `multimodal.attach` event to the HMAC-chained audit log
+   carrying `(sha256, mime, operator_install_id_sig, worker_id,
+   turn_seq, worktree_id, prev_chain_digest)`. Tampering with the
+   on-disk log fails verification.
+3. Adds the digest to the worker's lineage v1 receipt as a
+   `multimodal-attachment://<sha256>` parent so any artefact produced
+   this turn carries the input image's hash in its lineage.
+
+Replay over the exported chain reproduces the exact bytes the model
+API saw on the original turn. Substituting bytes breaks the chain.
+
+### Worktree pinning
+
+The audit-chain event embeds the worktree id of the attaching
+worker. A worker in a different worktree cannot resolve the
+attachment back to bytes; the resolver raises
+`WorktreeAccessDenied` on cross-worktree attempts. This protects
+session-shared state where multiple worktrees coexist.
+
+### Task YAML
+
+Plan-file steps accept an `attachments:` list mirroring the CLI
+flag:
+
+```yaml
+name: Reproduce failure
+stages:
+  - name: investigate
+    steps:
+      - title: Describe the screenshot
+        role: backend
+        attachments:
+          - ./screenshot.png
+          - ./architecture.svg
+```
+
+The orchestrator builds the same `MultiModalContext` from the
+listed paths and applies the same capability gate.
+
+## References
+
+* `src/bernstein/core/agents/multimodal_attestation.py` -- spawn-time
+  resolver, capability gate, and worktree pinning.
+* `src/bernstein/core/security/audit_chain.py` -- the
+  `multimodal.attach` event type and the `AuditChainStore` facade.
+* `src/bernstein/core/persistence/lineage_signer.py` --
+  `register_attachment_parents` for lineage receipt augmentation.

src/bernstein/adapters/base.py

@@ -503,6 +503,7 @@ def spawn(
         task_scope: str = "medium",
         budget_multiplier: float = 1.0,
         system_addendum: str = "",
+        multimodal_context: Any | None = None,
     ) -> SpawnResult:
         """Launch an agent process with the given prompt.
 
@@ -523,6 +524,14 @@ def spawn(
                 Adapters that support a separate system prompt (e.g. Claude
                 Code's ``--append-system-prompt``) should use it; others
                 may append to the user prompt as a fallback.
+            multimodal_context: Optional
+                :class:`bernstein.core.agents.multimodal.MultiModalContext`
+                carrying base64-encoded attachments to be passed to the
+                model API. Multimodal-capable adapters (Claude, Gemini)
+                encode the attached bytes inline in the request body;
+                other adapters MUST raise :class:`CapabilityRefusal`
+                before any process is launched (see
+                :func:`bernstein.core.agents.multimodal_attestation.refuse_when_incapable`).
         """
         ...
 

src/bernstein/adapters/claude.py

@@ -63,6 +63,55 @@ def _task_budgets_opt_in() -> bool:
     return raw.strip().lower() in {"1", "true", "yes", "on"}
 
 
+# ---------------------------------------------------------------------------
+# Multimodal attachment encoding (issue #1797)
+# ---------------------------------------------------------------------------
+
+
+def _inject_multimodal_attachments(prompt: str, multimodal_context: Any) -> str:
+    """Inline encoded attachments at the head of *prompt*.
+
+    The Claude Code CLI does not accept image attachments as separate
+    arguments; we wrap each base64-encoded blob in a structured
+    ``<attachment mime="..." sha256="...">`` block before the user
+    prompt so the model API receives the bytes inline. Tests assert the
+    exact format so downstream replay can reconstruct what was sent.
+
+    Args:
+        prompt: The agent prompt that will be passed to the CLI.
+        multimodal_context: A
+            :class:`bernstein.core.agents.multimodal.MultiModalContext`.
+
+    Returns:
+        Prompt with the encoded blocks prepended, or *prompt* unchanged
+        when the context contains no inputs.
+    """
+    inputs = getattr(multimodal_context, "inputs", ())
+    if not inputs:
+        return prompt
+
+    import hashlib as _hashlib
+
+    blocks: list[str] = []
+    for inp in inputs:
+        b64 = getattr(inp, "content_base64", None) or ""
+        mime = getattr(inp, "mime_type", "application/octet-stream")
+        path = getattr(inp, "content_path", None)
+        if path is not None:
+            try:
+                raw = Path(path).read_bytes()
+                digest = _hashlib.sha256(raw).hexdigest()
+            except OSError:
+                digest = ""
+        else:
+            digest = ""
+        # Format documented in docs/operations/run.md so adapters and
+        # tests share the same wire format.
+        blocks.append(f'<attachment mime="{mime}" sha256="{digest}">\n{b64}\n</attachment>')
+    header = "\n".join(blocks)
+    return f"{header}\n\n{prompt}"
+
+
 # Map short model names to Claude Code CLI model IDs.
 # Last verified against upstream @anthropic-ai/claude-code 2.1.x on 2026-05-05.
 # Opus 4.7 is GA at the same price as 4.6 (Anthropic news, 2026-04-16); Sonnet
@@ -509,8 +558,16 @@ def spawn(
         task_scope: str = "medium",
         budget_multiplier: float = 1.0,
         system_addendum: str = "",
+        multimodal_context: Any | None = None,
     ) -> SpawnResult:
         self.enforce_network_policy()
+        # Issue #1797: encode any attached images into the prompt body
+        # as base64 with the correct MIME type so the upstream model API
+        # sees them. The Claude Code CLI does not accept attachments
+        # directly; we inline them in a structured ``<attachment>`` block
+        # at the head of the prompt so the model picks them up.
+        if multimodal_context is not None:
+            prompt = _inject_multimodal_attachments(prompt, multimodal_context)
         log_path = workdir / ".sdd" / "runtime" / f"{session_id}.log"
         log_path.parent.mkdir(parents=True, exist_ok=True)
 

src/bernstein/adapters/gemini.py

@@ -151,6 +151,46 @@ def resolve_google_cli_binary(
     return _DISCOVERY_CASCADE[0]
 
 
+# ---------------------------------------------------------------------------
+# Multimodal attachment encoding (issue #1797)
+# ---------------------------------------------------------------------------
+
+
+def _inject_multimodal_attachments(prompt: str, multimodal_context: Any) -> str:
+    """Inline encoded attachments at the head of the Gemini prompt.
+
+    Gemini accepts inline image bytes via ``inline_data`` blocks in the
+    Generative Language API request. The CLI surface here forwards the
+    prompt as a single argument so we serialise attachments as
+    ``<attachment>`` XML-ish blocks that the CLI's prompt processor
+    inlines verbatim. This matches the Claude adapter wire format so
+    downstream replay can verify exact bytes for both providers.
+    """
+    inputs = getattr(multimodal_context, "inputs", ())
+    if not inputs:
+        return prompt
+
+    import hashlib as _hashlib
+    from pathlib import Path as _Path
+
+    blocks: list[str] = []
+    for inp in inputs:
+        b64 = getattr(inp, "content_base64", None) or ""
+        mime = getattr(inp, "mime_type", "application/octet-stream")
+        path = getattr(inp, "content_path", None)
+        if path is not None:
+            try:
+                raw = _Path(path).read_bytes()
+                digest = _hashlib.sha256(raw).hexdigest()
+            except OSError:
+                digest = ""
+        else:
+            digest = ""
+        blocks.append(f'<attachment mime="{mime}" sha256="{digest}">\n{b64}\n</attachment>')
+    header = "\n".join(blocks)
+    return f"{header}\n\n{prompt}"
+
+
 class GeminiAdapter(CLIAdapter):
     """Spawn and monitor Google Gemini / Antigravity CLI sessions."""
 
@@ -171,8 +211,15 @@ def spawn(
         task_scope: str = "medium",
         budget_multiplier: float = 1.0,
         system_addendum: str = "",
+        multimodal_context: Any | None = None,
     ) -> SpawnResult:
         self.enforce_network_policy()
+        # Issue #1797: inline encoded attachments at the head of the
+        # prompt body so the Gemini API receives the bytes alongside
+        # the text. The Antigravity / legacy Gemini CLIs do not accept
+        # attachments as separate arguments.
+        if multimodal_context is not None:
+            prompt = _inject_multimodal_attachments(prompt, multimodal_context)
         log_path = workdir / ".sdd" / "runtime" / f"{session_id}.log"
         log_path.parent.mkdir(parents=True, exist_ok=True)
 

src/bernstein/cli/run_bootstrap.py

@@ -1124,6 +1124,20 @@ def exec_restart() -> None:
         "score 1.0. Off by default; existing runs are unaffected."
     ),
 )
+@click.option(
+    "--attach",
+    "attach",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    multiple=True,
+    default=(),
+    help=(
+        "Attach an image / diagram to the run (issue #1797). May be repeated "
+        "for multiple files. The orchestrator builds a MultiModalContext at "
+        "spawn time, records a multimodal.attach event in the audit chain, "
+        "and refuses adapters that do not advertise multimodal capability. "
+        "Capable adapters: claude, gemini."
+    ),
+)
 def run(
     plan_file: Path | None,
     goal: str | None,
@@ -1165,6 +1179,7 @@ def run(
     retry_budget_spec: str | None = None,
     criterion_profile: str | None = None,
     max_blast_radius: float | None = None,
+    attach: tuple[Path, ...] = (),
 ) -> None:
     """Parse seed, init workspace, start server, launch agents.
 
@@ -1214,6 +1229,7 @@ def run(
             retry_budget_spec=retry_budget_spec,
             criterion_profile=criterion_profile,
             max_blast_radius=max_blast_radius,
+            attach=attach,
         )
     except (click.UsageError, SystemExit):
         raise
@@ -1263,6 +1279,7 @@ def _run_impl(
     retry_budget_spec: str | None,
     criterion_profile: str | None,
     max_blast_radius: float | None,
+    attach: tuple[Path, ...] = (),
 ) -> None:
     """Concrete ``run`` implementation; wrapped by :func:`run` for hinting.
 
@@ -1324,6 +1341,35 @@ def _run_impl(
             raise click.UsageError(f"--criterion-profile {criterion_profile!r}: {exc}") from None
         os.environ["BERNSTEIN_RUN_CRITERION_PROFILE"] = criterion_profile
 
+    # Issue #1797: capability-gate ``--attach`` BEFORE any process is
+    # launched. When the operator selected an adapter that does not
+    # advertise multimodal capability, surface a structured error that
+    # names capable adapters instead of spawning the run and failing
+    # mid-flight.
+    if attach:
+        from bernstein.core.agents.multimodal_attestation import (
+            CapabilityRefusal,
+            refuse_when_incapable,
+        )
+
+        # ``cli`` may be ``None`` (auto-detect) or "auto". When the
+        # operator has not pinned an adapter, only refuse if every
+        # candidate is incapable; with "claude" / "gemini" auto-detect
+        # is allowed.
+        explicit_adapter = (cli or "").strip().lower()
+        if explicit_adapter and explicit_adapter not in {"", "auto"}:
+            try:
+                refuse_when_incapable(
+                    adapter_name=explicit_adapter,
+                    attachments=[str(p) for p in attach],
+                )
+            except CapabilityRefusal as exc:
+                raise click.UsageError(f"--attach requires a multimodal-capable adapter. {exc!s}") from None
+        # Stash the attachments for downstream consumers via env var so
+        # the orchestrator subprocess can pick them up without
+        # additional argument threading.
+        os.environ["BERNSTEIN_RUN_ATTACHMENTS"] = os.pathsep.join(str(p) for p in attach)
+
     # Issue #1320: ``--budget`` is the friendlier alias of ``--max-cost-usd``
     # and shares the same env var. When both are set, the operator's
     # explicit ``--max-cost-usd`` wins for backward compat.