# Reliable tool handoffs

Use these interfaces to avoid reconstructing receipts, re-running unchanged selection work, or inspecting plugin source after a validation error.

## Match and select by need ID

`talking_head_broll_match` and `talking_head_broll_select` accept `needId` together with the unchanged `continuityPlanReceipt`. The tool retrieves and verifies the selected need, including any `mask-cut` artifact hash. Do not copy or modify its fields. The existing complete `need` object is still accepted; supply exactly one of `needId` and `need`.

```js
talking_head_broll_match {
  projectId,
  revision,
  assetDirectory: "Broll",
  needId: "keyboard-demo",
  continuityPlanReceipt
}

talking_head_broll_select {
  projectId,
  revision,
  needId: "keyboard-demo",
  continuityPlanReceipt,
  matchReceipt,
  assetPath,
  manifestPath,
  selectedStartMs,
  evidenceTimestampsMs,
  fit: "cover",
  visualIdentity
}
```

Only selected IDs are accepted. A missing/omitted ID, changed receipt hash, foreign project or wrong preparation revision still fails. Never add `necessity` or `visualCueText` to a mask-cut need to satisfy errors from the semantic-need schema branch. The plan input omits the artifact hash; the verified plan output contains it.

## Add BGM without reselecting B-roll

After B-roll is applied, read the current project and prepare BGM against that revision. If the ordered A-roll ranges are unchanged, apply the selected BGM with:

```js
talking_head_apply {
  projectId,
  expectedRevision,
  aroll,
  inheritBroll: true,
  bgm: selectedBgm.bgm
}
```

Omit `broll` and `continuityPlanReceipt` in this mode. The plugin reads them from the current snapshot and verifies their original preparation revision, continuity policy, selection/match receipts, sources, manifests and visual-review artifacts. It does not rewrite hashes or manufacture fresh receipts. A-roll changes require new B-roll planning and selection. Concurrent revisions still fail the expectedRevision check.

Legacy callers may keep submitting the exact unchanged full placements and stored continuity receipt: the same inheritance path is detected automatically. Pass `broll: []` without `inheritBroll` to remove the track. Omission alone is an error, not an implicit deletion or inheritance. Other fields retain their existing replacement behavior: for example, omitting `bgm` removes music. For subtitle-only changes, reuse `talking_head_get`'s `mediaOperation` instead of applying the talking-head project again.

For unchanged A-roll, omit `editorialPlanReceipt` to retain the stored review. Do not submit an old editorial receipt as if it had been newly prepared.

## Recover from source-window errors

`talking_head_broll_select` returns `isError: true` and a structured error for unavailable starts, incomplete evidence, insufficient tail coverage and windows outside the analyzed range:

- `code`, `requestedStartMs`, `requiredDurationMs`, `analyzedRangeMs` identify the failure.
- `availableStartTimestampsMs` contains up to 20 nearby manifest-backed candidate starts with enough analyzed duration.
- `availableEvidenceTimestampsMs` contains up to 100 existing timestamps inside the requested window, prioritizing its tail.
- `requiredTailAtOrAfterMs` gives the tail coverage threshold; evidence must also be at/before the selected end.
- `nextStep` describes selection or higher-precision contact-sheet recovery.

These candidates are not visual approval or proof of continuous usable footage. Inspect the actual frames; if necessary use `media_contact_sheet` on the selected source range, inspect its new evidence, and retry. Do not round timestamps, infer timestamps from thumbnails, bypass validation, or generate an ad hoc extraction script.

## BGM objects

The `bgm.mix` object's property order does not affect comparison with its receipt. Changing a mix value still fails. Preserve the original nested receipts and hashes: this release deliberately retains the legacy hash algorithm and stored project formats.

This release extends the public 0.3.0 interfaces and keeps its fixed relative-loudness mode and pi-media requirements. It does not migrate the separate Speclip private quality build or change its renderer's capabilities.