# agent/drivercontract evolution guardrails

`drivercontract` is the shared boundary between the agent `Process` and concrete
runtime drivers. Keep this package small: it should describe what the process
needs from every runtime, not every knob a single runtime happens to support.

## When adding to `LaunchConfig`

1. Confirm the field is needed by the process or by more than one runtime.
2. Keep runtime-private config parsing in the concrete driver instead.
3. Place the field in the existing identity/session/prompt/contract/runtime/tools
   grouping or add a new documented group.
4. Update `TestLaunchConfigContractSurfaceIsIntentional` in
   `contract_surface_test.go` so the public surface change is intentional.

## When adding to `ParsedEvent`

1. Confirm the field is part of the normalized driver event contract, not just a
   raw runtime payload detail.
2. Update driver event translation characterization tests for every affected
   runtime.
3. Update the runtimeevents/dispatcher mapping tests when the event reaches those
   layers.
4. Update `TestParsedEventContractSurfaceIsIntentional`.

## Optional driver behavior

Prefer narrow capability interfaces (`BusyStdinMessageDriver`,
`IdleCompactionDriver`, etc.) over growing the base `Driver` interface. A new
capability should have a single focused reason to exist and should be consumed by
one process subsystem.