Define sandbox driver capabilities and execution requirements

[eshulman2]

Problem

PR #243 / #30 introduces multiple sandbox drivers. Forge needs to know whether a selected driver can satisfy the execution requirements requested by ContainerRunner, but a driver should not become the owner of workflow authorization, Git publication policy, artifact semantics, or external integrations.

Without a small capability contract, runtime selection can silently weaken isolation—for example, a driver might ignore a requested network mode or be unable to run with a read-only root filesystem.

Forge architecture boundary

• Workflow nodes decide what work may run and which outputs are agent-derived.
• ContainerRunner prepares tasks and owns the execution lifecycle.
• SandboxDriver translates runtime requirements and executes the workload.
• GitOperations and workflow publication paths validate output before external writes.
• Jira/GitHub clients remain trusted integration components outside the sandbox.

This issue covers only the ContainerRunner ↔ SandboxDriver boundary.

Proposed solution

Add a deliberately small, driver-neutral execution-requirements and capability model:

• requirements such as non-root execution, read-only root, writable workspace, resource limits, network isolation, and service-account-token isolation
• driver capabilities describing which requirements are supported
• preflight validation before execution
• fail-closed behavior for required unsupported controls
• an effective-runtime summary suitable for later observability

Do not put protected Git paths, Jira/GitHub permissions, workflow approvals, secret scanning, or artifact publication policy in this contract.

Acceptance criteria

• ContainerRunner can express required runtime isolation properties without runtime-specific flags.
• Each driver declares supported capabilities.
• Required unsupported capabilities fail before agent execution.
• Podman and Kubernetes translate the common requirements into native settings.
• Workflow-node call sites remain unchanged.
• Effective runtime capabilities are available for audit recording without secrets.
• Tests prove a driver cannot silently ignore a required capability.
• Documentation explicitly describes what remains outside the driver boundary.

Dependencies

• Make sandbox runner pluggable with different execution drivers #30 / PR Make sandbox runner pluggable with Kubernetes driver support #243

Estimate

AI-assisted: 2–4 engineering days.