backends: expose reference and worktree tools through Claude and Pi #2432

Out of scope

No new policy, custom-skill rewriting, unmanaged checkout bypass, changing prior provider history, accounting reimplementation in adapters, new tool/provider registry, or reimplementation of A-D host logic. A backend adapter must never grant itself storage or credentials.

Context

Part of #2390. The complete consolidated specification and its maintainer rulings are binding. The durable record is in draft PR #2427 at 6fc6183fe36125db1f465c9abb72eed0838d32ef (tree 212a1ec86ce0cb92bfbe254b4697c303de4ff3b1). That documentation is not product implementation or native qualification.

Code citations below were checked against 90a95123cfceb169bd2ecf7c213544db742eaed7. Recheck them when refreshing the implementation base. Preserve ROADMAP's concrete owners, deterministic CLI/host execution, unchanged brain-history accounting and append-only provider history. No policy ruling is requested by this issue.

Blocked by #2431

Sources:

• BackendBridge, packages/ui-sdk/src/server/backend.ts:167-174, is the existing parent-side bridge owner; brainApplicationInput, packages/ui-sdk/src/server/brain-application.ts:8-23, and fixed descriptions at same file:47-59 demonstrate shared runtime schemas/static descriptions.
• makeBridge, packages/ui-server/src/ws/bridge.ts:33-50, with authoritative application binding at same file:599-620; connect current request authority here rather than trusting model fields.
• registerBrainApplicationTools, packages/ui-backend-claude/src/brain-application-tools.ts:7-40, shows full strict schemas and stable registration. Audit its caller and permission/worker forwarding paths.
• createPiBridgeTools, packages/ui-backend-pi/src/bridge-tools.ts:99-120; createBrainTools, packages/ui-backend-pi/src/tools.ts:303-310, routes application tools at same file:856-880. Include worker-entry/worker-session protocol forwarding and classification; registration alone is insufficient.
• workerSandboxNote, packages/ui-sdk/src/server/worker-sandbox.ts:471-533; binding provider-history guards under both backend test trees.

Scope

Publish one concrete shared tool/CLI contract for authorized read-only reference access and managed worktree access/resume/renew/release, then wire both existing backend adapters to the already-governed host owner. Exact names and strict schemas are implementation design; choose them once in the SDK and use them identically across adapters.

Acceptance criteria

1. Stable strict input schemas, names, static descriptions and bounded results report usable path/identity, starting/current commit as appropriate, authority refusal, source freshness/stale status/time/error, moving versus fixed-starting semantics, limits and release/renewal instructions. No result claims a host path is worker-usable without actual namespace evidence.
2. Host derives principal/profile/brain/session and live worker identity from authenticated turn context; model-supplied IDs/paths do not widen grants. Unsupported/expired/revoked access refuses honestly. Tools are stable across session turns; permissions enforce posture/capabilities without changing cached roster bytes.
3. Claude and Pi dispatch through actual installed adapter worker/parent pipes, per-tool policy/allowlist/risk classification and cancellation paths into A-D. Scope tool-call accounting and principal/private isolation remain intact. All operations behave equivalently through both backends.
4. Actionable static guidance explains shared moving source, when edits or stable reads require a managed worktree, request/resume/renew/release, returned path and expiry/refusal. Do not mutate user custom skills. Dynamic facts appear once in current result/new tail, never rewritten system/tools/history.
5. Actual offline >1,000-file acquisition/inspection runs through each backend supported tool and worker path without consuming content changed-path allowance; intentional worktree edits remain journaled, governed and scope-counted, while ordinary workspace edits retain their existing behavior. Include source refresh/live reads, stable worktree base and supported release lifecycle.
6. Both installed-backend provider-history guards prove stable tool/system/earlier messages across lifecycle/freshness changes. Contract envelopes, package/type/build/packed-consumer and selected runtime categories pass on actual current candidate identities.
7. Reconcile every Epic: shared reference source and governed worktrees #2390 acceptance criterion against delivered A-E commits and native/backend proof. Only the delivery whose integrated tree satisfies all criteria and required proof may close Epic: shared reference source and governed worktrees #2390. Documentation PR docs: record shared reference and managed worktree rulings #2427 alone never supplies that completion evidence.

Parent acceptance mapping

Completes criteria 2 and 3 through supported tools/backends and integrated proof of 4-8. Criterion 1's durable record remains #2418/#2427; verify its actual merge rather than assuming draft delivery.

Failing-first/mutation targets

Bypass host principal binding, omit a backend worker forwarding/risk route, expose shared source writable, change tool roster on renewal, mutate resumed provider system/history, or disable worktree journal integration: require a specific actual runtime/contract/provider-history assertion to fail and the restored implementation to pass.

Verification

Use only offline Odysseus repositories and keyless native worker/storage fixtures. Record named failing-first assertions and restored mutations, actual head/base/checkout tree, toolchain and fixture identities, commands, exit codes and retained output. Source inspection, parser/unit fixtures and documentation proof do not establish actual allocation, worker, mount or backend behavior. Complete affected package/type/contract checks and required current-candidate PR proof before readiness/merge. Do not launch native or container resources without the coordinator's explicit resource slot; installation/local feedback is separately owned. A missing slot leaves runtime proof pending, not passed.

Contract impact

Additive only. Any supported configuration, CLI JSON, HTTP, SDK or tool surface added by this slice owns the relevant integration-contract component and index link in the same CONTRACT: commit, plus a minor changeset naming actual affected package manifests. Load the release skill before those edits; do not version or publish here. Keep internal host-only protocol definitions concrete and private; adding one does not authorize a generic extension interface. Update changed code citations in the same slice.