docs: agent invocation parity audit 2026-07 + enclave workspace-ops and BYOA SDK designs

[kristofferremback]

Problem

docs/plans/agent-runtimes-unification-redesign.md declared Phases 0–2 of the Turn Contract complete as of 2026-06-12. Three weeks and ~50 commits later there was no verified answer to: are the three agent surfaces (in-process companion, E2EE enclave, external bot-runtimes) still at parity, what new drift landed, and what do the two known open fronts — workspace tools inside the enclave, and the bring-your-own-agent kit — actually look like against the current tree?

Solution

One new doc, docs/plans/agent-invocation-parity-audit-2026-07.md, in three parts. Produced by a fan-out audit (five per-surface inventory agents, two adversarial verification passes that re-opened every cited file) with the load-bearing claims re-verified by hand before writing.

Part 1 — verified state. The unification held: companion and enclave share the loop, TraceProjector, negotiateCapabilities/stream_policies gating, turn digests, rolling summary, /fail, and cost recording (each suspected-regression row re-verified with file:line evidence). What remains is enumerated and classified (by-design / drift / new-drift / policy-off):

• NEW-DRIFT: schedule_follow_up (feat(agents): schedule_follow_up tool + follow-up infra (roadmap 1.1) #1138) is companion-only — the first durable-write tool and the template for every roadmap tool after it; the roadmap's per-tool parity policy makes this compound unless PRs must declare an enclave/external story.
• LIVE BUG: rebindPiRemoteSessionInstance hardcodes runtimeKind: "pi-local" (bot-runtimes/service.ts:359,368) while rebindInstance filters AND runtime_kind = $kind (repository.ts:540) — a claude-code-channel session link 404s on every rebind. Verified by hand.
• DRIFT: external turns record zero cost/usage/telemetry (grep-confirmed: no costService/recordUsage/otel on the bot path; complete schemas carry no token field).
• POLICY-OFF: the sealed external wire is code-complete and tested behind EXTERNAL_SEALED_DELIVERY = false (negotiate-capabilities.ts:35).
• Zero commits touched apps/enclave/ or features/enclave-runtimes/ in the window.

Also corrects a stale row in the baseline doc (digest injection now ships on both first-party surfaces) and ends with a ranked fix list.

Part 2 — design: opt-in workspace tools for the E2EE enclave. Consent-first per the product ruling (Threa never decides sensitivity; opting in is informed acceptance that queries/results transit the backend in the clear while traces stay sealed). Mechanism: an explicit E2E policy floor at the claim seam (policy ?? ["web"] — today policy absence means allow-everything, which would silently grant the leak once enclave workspace tools exist), consent via the existing ToolPolicyPicker with an honest-disclosure row, one generic session-token-bound execute callback dispatching to the existing server-side tool registry with an independent server-side re-gate, reads-only (writes 403'd and structurally excluded at assembly), an enumerated leak surface including the log-scrubbing requirement, and a unified resolveE2eAgentPolicy resolver so the future BIK-bot sealed flip is the same gate, not a second one. Five-PR shipping plan, safety floor first.

Part 3 — design: the @threa/bot SDK. Verdict: extensions/bot-runtime-client is the hard 25% (socket, hello/cursor, reconnect, lease-safe renew); each harness hand-rolls the rest — three HTTP clients, two disagreeing ClaimedInvocation types, duplicated claim loops/presence/shutdown. Design: createThreaBot({ token, runtimeKind, capabilities, onTurn }) factory + callbacks, renew/presence/error-normalization invisible by default, 9-line echo bot, wire types promoted to packages/types, sealed-ready TurnContext union, ~1,000–1,300 LOC of duplicated protocol code deleted across pi-remote / claude-code-remote / harness-daemon, npm publish as the trigger for the deferred taipVersion.

Files changed

File	Change
docs/plans/agent-invocation-parity-audit-2026-07.md	New — audit + two designs (434 lines)

Out of scope (deliberate)

No code changes. The ranked fixes (rebind bug, external usage field, enclave follow-up parity, workspace-ops PR1) are follow-up PRs; this doc is the shared baseline for them.

Test plan

• Docs-only change — full pre-commit hook passed on commit: monorepo eslint, tsc --noEmit across all packages/apps, dockerfile-workspace check, migration check (181 clean), OpenAPI spec --check
• Claim verification: two adversarial Opus verify passes re-opened every cited file; rebind bug, EXTERNAL_SEALED_DELIVERY=false, absent bot-path cost recording, and policy-absence semantics additionally re-verified by hand in-session
• No unit tests apply (no runtime surface)

---

🤖 PR by Claude Code

https://claude.ai/code/session_01MJU9G8akiwCi4g8KQZeQ2Q

---

Generated by Claude Code

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f57cd268-ca96-46c1-a052-f4697d863d8d

📥 Commits

Reviewing files that changed from the base of the PR and between 6eda910 and c44e18c.

📒 Files selected for processing (1)

• docs/plans/agent-invocation-parity-audit-2026-07.md

---

_{Comment @coderabbitai help to get the list of available commands.}

[kristofferremback]

@coderabbitai review

---

Generated by Claude Code

[coderabbitai]

@kristofferremback I'll review the PR now.

Action performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Caution

Failed to replace (edit) comment. This is likely due to insufficient permissions or the comment being deleted.

Error details

{}