Agent System

Forge must support agents without spreading provider-specific branches throughout the application.

Identity layers

Agent Driver
   │
   └── Agent Instance
          │
          └── Adapter Strategy
                 │
                 └── Capabilities

Example:

Driver: Claude Code
Instance: Personal Claude
Strategy: streaming/control protocol
Capabilities: structured events, decision backchannel, resume, ...

For Codex, separate strategies may expose materially different capabilities. Forge must never assume “Codex” alone tells us what the selected execution surface can do.

Adapter responsibility

An adapter knows:

• provider startup protocol;
• structured event decoding;
• external session identity;
• provider completion semantics;
• interruption/cancellation semantics;
• resume semantics;
• provider-specific question/permission protocol;
• how Forge-injected tools are registered per invocation;
• how to keep ambient user configuration from silently violating the intended run boundary where required.

An adapter does not own Task state, SQLite transactions, Git worktree policy, or React UI.

Run is not process

A provider can implement work as:

• one process per Run;
• one process per Turn;
• one long-lived service with many sessions;
• a remote service.

Therefore process supervision lives inside adapter/execution infrastructure. The domain tracks Run lifecycle, not PIDs as identity.

Capability design

Capabilities must express real semantics. Examples:

• interactive decision backchannel;
• can resume conversation;
• can interrupt;
• can capture provider-native plan events;
• structured tool-call lifecycle;
• usage information;
• can capture workspace checkpoint;
• can restore conversation to matching checkpoint;
• can switch model between turns.

Do not use one broad flag such as supportsCheckpoints if workspace rollback and conversation rollback differ.

No silent fallback

If a rich strategy is selected and initialization fails, Forge reports that strategy as unavailable. It must not silently switch to a weaker strategy when doing so removes guarantees shown by the UI.

A user may explicitly choose a weaker strategy after seeing the consequences.

Probe versus Start

Probe answers availability/version/capability questions with minimal side effects. Start opens real provider work and may start hooks, MCP servers, auth sessions, or other machinery.

Settings screens must not use full session setup as a periodic health check.

Raw before parse

The core writes each raw line/message frame to durable raw storage before the adapter interprets it. The adapter then emits normalized events referencing the raw record.

Parser bugs are therefore recoverable from retained evidence.

Unknown events

• Preserve unknown complete protocol messages in raw storage and surface diagnostic information.
• Unknown streaming deltas may be droppable only when the provider guarantees equivalent complete content later.
• If Forge is asked to act on an unknown control/event type, fail closed rather than guessing.

Escalation integration

For capable strategies, Forge injects/controls the escalation tool per run. The adapter must verify the tool is actually invocable; “we registered it” is not proof that permissions allow it.

Native provider question tools may need suppression/replacement when necessary to make the Decision path reliable. Forge configures a run, not the user's global or repository configuration.

Adapter contract suite

Every adapter strategy must pass the same behavioral contract where capabilities apply. The deterministic fake adapter proves the contract independently of live model APIs.

Scenarios include:

• normal start/work/complete;
• cancellation;
• malformed/unknown provider message;
• duplicate message;
• late event;
• decision request/resume;
• external session ID assigned after startup;
• provider completion distinct from process exit;
• restart/reconciliation where supported.