Non-shippable proof-of-concept (Feature #2 of Epic #1): a standalone VS Code extension that drives @cline/sdk — validating Approach A (own coauthoring extension on the Cline SDK, no fork).

What it does

Registers one command, Cowriting: Show Cline SDK Info, which loads @cline/sdk and shows the SDK build version plus the agent's builtin tool catalog (a pure, key-free SDK call) in a notification and the "Cowriting (Cline SDK)" output channel.

Features shipped so far: F2 region-anchored threads (Feature #4), F3 live human/Claude attribution (Feature #6), F4 propose/accept diff flow (Feature #12), F5 cross-rung sidecar contract (Feature #14), F6 diff-view toggle (Feature #17).

Architecture

CommonJS extension bundled with esbuild (src/extension.ts → out/extension.cjs).
@cline/sdk is ESM-only (Node ≥22) and uses createRequire(import.meta.url), so it is not bundled — it is shipped in node_modules and loaded at runtime via dynamic import() from the vscode-free src/cline.ts.

Run it (F5)

npm install
npm run build
Press F5 (or Run → "Run Extension") to launch the Extension Development Host. It opens the committed sandbox/ playground as its workspace (not the repo itself — VS Code won't open one folder in two windows, #8); start with sandbox/playground.md.
In the new window: Cmd/Ctrl+Shift+P → "Cowriting: Show Cline SDK Info".

F2 — Region-anchored threads (Feature #4)

Attach durable, region-anchored discussion threads to any document. Threads render in the native VS Code Comments gutter and persist as git-native sidecars under .threads/<doc-path>.json (plain, diffable JSON — no server).

Create: select text → run "Cowriting: Add Coauthoring Thread on Selection" (or the Comments gutter "+").
Reply / Resolve: use the native Comments reply box and the thread's Resolve/Reopen actions.
Survives edits, reload, and external change (git pull): a hybrid anchor (durable content fingerprint + live offset tracking) re-resolves the thread. If the anchored text can't be confidently re-found, the thread is shown as orphaned at its last-known line — never silently moved.

Design: vscode-cowriting-plugin-content/specs/coauthoring-inner-loop.md. No live @cline/sdk turn and no credentials are involved in F2.

F3 — Live human/Claude attribution (Feature #6)

As you and Claude coauthor, every span in the buffer carries an author: human edits render with a subtle left border, Claude-authored spans with a background tint. Text that predates tracking stays plain — the honest record. Edits that touch a boundary (split, merge, partial overwrite) are handled char-precisely.

Attribution is persisted git-natively in the same .threads/ sidecars (attributions[], sharing the same anchors fingerprints as F2 threads). On reload, fingerprints re-resolve spans against the current document; spans that can't be confidently re-found are orphaned (status-bar count + "Cowriting Attribution" output channel) rather than silently moved or discarded.

Commands

Cowriting: Ask Claude to Edit Selection — select text → enter an instruction → a live @cline/sdk turn runs on the built-in claude-code provider (rides your local Claude Code Pro/Max login; the extension stores no credentials). As of F4 the turn ends in a proposal (see below); accepted text lands as a Claude-attributed span.
Cowriting: Toggle Attribution — show/hide attribution decorations.
cowriting.applyAgentEdit (palette-hidden) — the single machine-edit ingress seam. Tests drive this directly so CI requires no LLM.

Design: vscode-cowriting-plugin-content/specs/coauthoring-attribution.md.

F4 — Propose/accept diff flow (Feature #12)

Claude's edits arrive as pending proposals — propose-by-default, the document never changes without your say-so. A proposal renders two ways at once: an amber tint on the target range, and a "Claude proposes" comment thread showing a fenced diff of current → proposed text with two actions:

✓ Accept Proposal — applies the replacement through the applyAgentEdit seam, so it lands Claude-attributed (F3) — and the proposal disappears.
✗ Reject Proposal — the document is untouched; the proposal disappears.

Pending proposals persist git-natively in the same sidecar (proposals[], sharing the F2/F3 anchors fingerprints), survive reload, and re-anchor as surrounding text changes. If the target text itself changes, the proposal goes stale (status-bar count, accept disabled — never applied by guess); undo the change and it becomes decidable again. cowriting.proposeAgentEdit (palette-hidden) is the programmatic propose ingress E2E drives — no LLM in CI.

Design: vscode-cowriting-plugin-content/specs/coauthoring-propose-accept.md. Live smoke: docs/MANUAL-SMOKE-F4.md.

F5 — Cross-rung format + round-trip (Feature #14)

The .threads/ sidecar is the published cross-rung contract: any rung of the ladder (this editor → Gitea substrate → rfc-app) reads and writes the same record per the contract; git push/pull is the transport, no re-homing ever.

Normative contract (INV-14): vscode-cowriting-plugin-content/specs/coauthoring-sidecar-contract.md — format changes land there first, then schema, then code.
Machine-checkable half: schemas/coauthoring-sidecar.schema.json; validate any sidecar from any rung with node scripts/validate-sidecar.mjs <file>. The unit suite validates every serialized artifact — contract drift fails CI.
Identity crosses rungs: Provenance.email (git's own join key — populated from the workspace git config when available) and agent.onBehalfOf (who the machine acted for).
Writers preserve unknown fields (INV-15): rewriting a sidecar never destroys another rung's data — unknown keys survive, after known keys, sorted.
Newer-major sidecars are read-only (INV-16): the editor renders what it understands, warns once, and writes nothing (the store refuses as a backstop).
Deterministic merge (INV-17): src/mergeArtifacts.ts — union-by-id, documented tie-breaks, every resolved divergence surfaced in conflicts.
The round-trip is proven, not asserted: scripts/crossrung-reply.mjs is a self-contained conforming foreign writer (the Gitea-rung stand-in); host E2E drives editor-thread → stand-in reply → external-change → the reply renders in the thread.

Design: vscode-cowriting-plugin-content/specs/coauthoring-cross-rung-format.md.

F6 — Diff-view toggle (Feature #17, #19)

Ctrl+Alt+D (the same chord on macOS — not Cmd; or Cowriting: Toggle Diff View) flips the focused document into a native vscode.diff against a coauthoring baseline — the readonly baseline on the left, your live, editable document on the right (so you keep writing inside the diff; toggling again closes it). The diff answers "what did I change?" in one keystroke instead of git archaeology.

Works on any file (#19): any document you can edit — a file inside or outside the workspace folder, or an untitled scratch buffer. Only a non-text-editor focus warns. (Untitled buffers diff in-memory; saving makes the baseline persist.)
Machine-factored baseline (INV-18): the baseline initializes when a doc is first seen and advances automatically at every machine landing (every successful applyAgentEdit seam apply — INV-9). So text Claude landed never shows as a change; everything the diff shows is operator-authored by construction — no attribution filtering.
Pin on demand: Cowriting: Pin Diff Baseline to Now resets the baseline to the current buffer for a deliberate "review my next pass" epoch; the diff tab title names the epoch (opened / Claude landed / pinned).
Pure view, repo-free (INV-19): the baseline snapshot lives in VS Code global extension storage, keyed by a hash of the document URI, never the repo — .threads/, the cross-rung contract (INV-14..17), and SCHEMA_VERSION are untouched. Storage-unavailable degrades to in-memory baselines + one warning.
No LLM in CI: host E2E (test/e2e/suite/diffView.test.ts) drives the same programmatic seam ingress (propose + accept) the F4 suite uses.

Design: vscode-cowriting-plugin-content/specs/coauthoring-diff-view.md. Live smoke: docs/MANUAL-SMOKE-F6.md.

F7 — Rendered track-changes preview (Feature #21)

Ctrl+Alt+R (or Cowriting: Open Track-Changes Preview) opens a read-only webview beside a Markdown editor that renders the document and marks what changed since the F6 baseline — the "track changes" / "suggesting mode" altitude rather than a raw-text split-diff:

Prose additions are highlighted (<ins>), deletions struck (<del>), refined to the word.
Code and mermaid fences are diffed whole (atomic, INV-23): a changed or added one renders fully with a small "changed" badge; a removed one renders struck. Mermaid fences render as diagrams (mermaid runs in the webview). Intra-diagram node/edge diffing is deferred (#22).
It updates live as you and Claude edit (debounced), and re-bases when Claude lands an edit (baseline advances, INV-18) or you pin — so accepted text drops its marks. It reuses the F6 baseline and adds no persistence (pure read-only, INV-20).
The webview is sealed (INV-21): local bundled assets only, strict CSP with a per-load nonce, no network/CDN, no LLM. Mermaid is bundled into the webview asset only, never the extension-host bundle.
The render engine (src/trackChangesModel.ts) is a pure, vscode-free function (INV-22), unit-tested with no editor and no webview; host E2E (test/e2e/suite/trackChangesPreview.test.ts) drives the same programmatic propose/accept seam with no LLM.

F7 is markdown-only; for any other file (incl. code), use F6's diff toggle (Ctrl+Alt+D). The webview's visual rendering (mermaid, theming) is verified by the manual smoke, not the sealed-sandbox E2E.

Design: vscode-cowriting-plugin-content/specs/coauthoring-rendered-preview.md. Live smoke: docs/MANUAL-SMOKE-F7.md.

Develop

npm run watch — rebuild on change.
npx vitest run — unit suite (SDK driver, schema, store, anchorer, thread mutations, attribution split/merge).
npm run test:e2e — @vscode/test-electron host E2E (create → reply → resolve → persist → reload → re-anchor → orphan; drives cowriting.applyAgentEdit directly — no LLM required).
npm run smoke:live — scripted live-turn smoke test for F3; requires Claude Code installed and signed in. See docs/MANUAL-SMOKE-F3.md.
npm run typecheck — type-check without emit.