Lesson 19 — First real adapter

Outcome

Run one real coding agent inside the prepared Task worktree through a structured protocol while retaining raw evidence and normalized state.

Why this comes now

The fake has proven our architecture. Now we integrate one real source of messy external behavior without letting it define the whole system.

Understand

The adapter owns provider protocol and Run semantics. The execution environment owns cwd/location. Raw frames are persisted before decode. External session identity may arrive after startup. Provider result semantics—not only exit code—classify Run stop. Capabilities are explicit and no feature silently degrades.

Build the real project

1. Implement strategy startup through ProcessRunner or provider service protocol as appropriate.
2. Apply per-run configuration/isolation rules without writing user/repo config.
3. Feed raw protocol frames through RawLog before parse.
4. Normalize only the event types Forge currently understands.
5. Capture external session ID when assigned.
6. Implement interrupt/cancel semantics.
7. Implement correct provider completion/stopped-reason classification.
8. Add captured protocol fixtures and adapter contract tests.
9. Run a disposable live acceptance repository and inspect raw + normalized output.

Completion gate

A real agent edits the Task worktree, Forge displays structured progress, cancellation works, and completion is classified from provider semantics. Unknown protocol message remains diagnosable. No provider name branches appear in domain/UI.

Pitfalls to avoid

Do not scrape terminal text when a machine protocol exists. Do not modify global/repo provider config as a hidden setup step. Do not swallow parser errors. Do not treat exit 0 as definitive semantic success.

References

Sculptor integrated harness: https://github.com/imbue-ai/sculptor/blob/main/docs/help/integrated_harnesses.md ; T3 provider constraints: https://github.com/pingdotgg/t3code/blob/main/docs/internals/providers.md ; use the selected provider's official protocol/CLI docs too.

Checkpoint

M7 is complete only after one live task and the deterministic contract suite both pass.