coilyco-flight-deck/ward

Fork 0

Evolve harness integrations from argv launchers into capability-aware runtime drivers #960

New issue

Open

opened 2026-07-10 06:35:57 +00:00 by coilysiren · 0 comments

coilysiren commented

2026-07-10 06:35:57 +00:00

Owner

The problem

Proposed change

Body

Summary

Ward currently models an agent harness primarily as a binary plus several argv shapes. That abstraction was sufficient when harnesses behaved like one-shot CLI tools, but Codex, Claude Code, Goose, and OpenCode now expose substantial runtime control planes:

Persistent sessions and resume
Structured event streams
Schema-constrained output
Native long-horizon goals
Lifecycle and tool hooks
Native review modes
Subagents and background execution
Remote-control surfaces
Programmatic protocols and servers

The recent discovery of native /goal support is one instance of a broader architectural gap: Ward is reimplementing several inner-loop capabilities that modern harnesses can now provide directly.

Ward should evolve into a capability-aware control plane over agent runtimes. Harnesses should own their model loop and session semantics; Ward should retain authority over isolation, forge policy, credentials, scheduling, audit, review quorum, and lifecycle enforcement.

Native capabilities should be enabled by default when supported, with Ward-managed behavior retained as the fallback.

Current state

The primary Agent contract in internal/agentsapi/agentsapi.go describes:

Harness identity
Binary resolution
Preflight argv
Headless argv
Interactive argv
Credential and configuration composition
Installation and onboarding
Launch gating

These are predominantly setup-time capabilities. Ward has no common runtime vocabulary for:

Sessions
Events
Goals
Structured output
Resume or interruption
Native review
Remote control
Harness hooks
Subagents

This causes several concrete problems.

Harness output is treated as unstructured

Codex and OpenCode are currently declared with no structured stream support, despite providing JSON event modes:

Codex: codex exec --json
OpenCode: opencode run --format json
Claude: --output-format stream-json is already partially used
Goose: ACP provides a richer session protocol than goose run -t

Ward consequently has to infer state from processes, stdout, ledgers, and polling instead of consuming explicit runtime events.

Review and QA reimplement structured output

cmd/ward/agent_review.go, internal/reviewpanel, and the QA flow ask agents to return fenced JSON and then recover it heuristically.

Modern harnesses support schema-constrained output:

Codex output schemas
Claude --json-schema
OpenCode structured output

Ward should use native schemas where available and preserve the existing parser only as a compatibility fallback.

Ward owns continuation loops that harnesses can now own

The director heartbeat implements polling, reconciliation, dispatch, completion evaluation, and livelock protection.

Some of this remains Ward-specific, particularly forge reconciliation and scheduling. However, long-horizon task continuation can now be delegated to native goal mechanisms:

Codex first-class goal RPCs through app-server
Claude /goal, including headless invocation

Ward should set the native goal at session start and allow the harness to own its inner continuation loop. Ward remains responsible for the outer run lifecycle and policy.

Harness-specific flags can silently become stale

internal/agents/claude/claude.go currently documents Claude effort as echo-only because no native effort flag existed when the adapter was written.

Claude now supports --effort, along with capabilities such as:

--max-turns
--max-budget-usd
--advisor
--bg
--permission-mode
--json-schema

The static argv abstraction makes capability drift easy to miss.

Skills are flattened into context

The container bootstrap composes a large AGENTS.md and exposes substrate skills primarily as documentation.

This provides compatibility, but bypasses native skill systems that support:

Progressive disclosure
Explicit invocation
Harness-specific discovery
Reduced base prompt size

Ward should eventually install or expose skills through each harness’s native mechanism while retaining the composed context as fallback.

Harness capabilities worth integrating

Codex

Codex provides:

codex exec --json
JSON-schema output
codex app-server with threads, turns, items, approvals, and events
First-class goal set/get/clear operations
Persistent sessions
Native codex review
Lifecycle hooks
Native subagents
Experimental remote-control surfaces

Codex should ultimately use an app-server-backed runtime driver rather than only codex exec.

Claude Code

Claude provides:

Streamed JSON output
JSON-schema output
Session IDs, resume, and fork
Headless slash-command invocation
Native /goal
Native effort, turn, and budget controls
Lifecycle and tool hooks
Subagents, background agents, and experimental agent teams
Native code, security, and ultrareview modes
Experimental --advisor
Remote Control for browser and mobile access
Channels for pushing external events into a running session

Remote Control is particularly relevant to Ward’s attached-only director experience. It may provide mobile access to a Ward-managed session without Ward first implementing its own remote UI.

Claude’s native advisor should not replace Ward’s independent advisor role. It is an inner-loop consultation using the engineer’s session context and trust boundary, while Ward’s advisor remains separately brokered and read-only.

Goose

Goose provides:

Agent Client Protocol support
Multiple isolated ACP sessions
Recipes and subrecipes
Remote serving
Session persistence
Scheduled execution
Claude and Codex subscription-backed ACP providers
Adversary mode and prompt-injection defenses

Goose ACP may be useful as a common transport for local or otherwise weakly integrated harnesses.

It should not immediately become the universal wrapper. Wrapping Codex or Claude through Goose can obscure native goal, session, resume, fork, approval, and review semantics.

Goose adversary mode is also not a replacement for Ward’s security boundary: its reviewer failure behavior is fail-open.

OpenCode

OpenCode provides:

opencode run --format json
Session continuation, selection, and forking
A persistent headless server
An OpenAPI specification and SDK
Structured output
Native agents and child sessions
Plugins and event hooks
Native skills

The immediate improvement is to consume --format json. A server-backed driver can follow later.

Proposed ownership boundary

Ward continues to own

Container and repository isolation
Forge authority
Issue reservation and scheduling
Credential delivery
Agent eligibility and launch policy
Audit records
Deterministic reaping
Landing and merge policy
Cross-harness orchestration
Heterogeneous review quorum
Managed fallback implementations

Harnesses should own

Model execution and context compaction
Inner-loop goal continuation
Native session persistence
Resume and interruption semantics
Tool and approval event production
Inner-loop subagents
Harness-native review
Model consultation and advisor features
Interactive and remote session presentation

Harness-native worktrees, sandboxes, teams, and background agents must not replace Ward’s container boundary or forge policy.

Proposed architecture

Extend the existing optional-interface pattern with runtime capabilities rather than adding more harness-specific conditionals to launch construction.

The exact interfaces can evolve during implementation, but the capability vocabulary should cover concepts such as:

type SessionDriver interface {
    Start(context.Context, SessionRequest) (Session, error)
    Resume(context.Context, SessionID) (Session, error)
    Interrupt(context.Context, SessionID) error
    Events(context.Context, SessionID) (<-chan Event, error)
}

type GoalDriver interface {
    SetGoal(context.Context, SessionID, Goal) error
    GetGoal(context.Context, SessionID) (Goal, error)
    ClearGoal(context.Context, SessionID) error
}

type StructuredOutputDriver interface {
    RunSchema(context.Context, SessionRequest, json.RawMessage) (json.RawMessage, error)
}

type ReviewDriver interface {
    Review(context.Context, ReviewRequest) (ReviewResult, error)
}

type RemoteControlDriver interface {
    Expose(context.Context, SessionID) (RemoteEndpoint, error)
}

Capabilities should be discovered explicitly. Example capability names might include:

structured-events
structured-output
persistent-session
resume
interrupt
native-goal
native-review
hooks
subagents
remote-control
push-events
native-skills

Ward should prefer the native implementation when advertised and use the existing managed implementation otherwise.

Persistence changes

The Ward run ledger should record native harness identity alongside process identity:

Harness name and version
Native session or thread ID
Native goal state, when applicable
Runtime protocol
Capability snapshot
Remote-control metadata, if enabled
Last observed structured event
Resume eligibility

This allows Ward to distinguish:

A running process
A resumable harness session
A completed goal
An interrupted but recoverable run
A run whose underlying harness state has been lost

Review integration

Native review commands should become available as review-panel voters:

Codex native review
Claude code review
Claude security review
Claude ultrareview where configured

They should not replace Ward’s heterogeneous review quorum.

Ward remains responsible for:

Selecting voters
Maintaining independence between voters
Normalizing results
Applying quorum policy
Recording provenance
Failing closed where required

Native JSON schemas should be used to normalize each voter’s response.

Hooks and policy

Harness hooks should be used as defense-in-depth and event instrumentation.

Potential uses include:

Recording tool calls and outcomes
Emitting deterministic activity events
Enforcing harness-level tool restrictions
Detecting session start, stop, and compaction
Relaying approval requests
Reporting subagent creation and completion
Triggering Ward reconciliation after meaningful activity

Harness hooks are not the primary security boundary. Containers, repository permissions, credentials, and forge authority remain enforced by Ward.

Remote control and event delivery

Evaluate Claude Remote Control as an optional presentation layer for Ward-managed interactive sessions.

The intended model is:

Ward creates and governs the container.
Claude continues running inside that environment.
Remote Control exposes the existing session to an authenticated browser or phone.
Ward records the exposure in the run ledger.
Ward retains termination and cleanup authority.

Also evaluate Claude Channels for pushing CI, webhook, or issue events into a running session.

This should complement, not replace, Ward’s outer backlog and forge reconciliation.

Implementation plan

Phase 1: Low-risk correctness and observability

Pass native Claude --effort.
Add Codex JSON event mode.
Add OpenCode JSON event mode.
Normalize structured events into a small Ward event type.
Use native output schemas for review and QA where supported.
Retain existing text and fenced-JSON behavior as fallback.
Record harness versions and advertised capabilities.

Phase 2: Native session identity

Add a session-driver abstraction.
Persist native session and thread IDs in the run ledger.
Support resume and interrupt where available.
Distinguish process termination from session termination.
Add recovery behavior after Ward restart.

Phase 3: Native goals and review

Enable native goals by default for Codex and Claude.
Retain the managed director loop for unsupported harnesses.
Allow native review commands to participate as panel voters.
Record whether a result came from native or managed execution.

Phase 4: Protocol-backed drivers

Implement a Codex app-server driver.
Evaluate Claude Agent SDK integration versus the headless CLI.
Implement or adopt Goose ACP support.
Evaluate an OpenCode server driver.
Preserve argv drivers as compatibility mode.

Phase 5: Presentation and context

Evaluate Claude Remote Control for Ward sessions.
Evaluate push-based event channels.
Install skills through harness-native mechanisms.
Retain composed AGENTS.md as compatibility and policy context.
Experiment with native advisors and subagents inside engineer runs.

Non-goals

This work does not:

Replace Ward’s container isolation with harness-native sandboxing.
Replace forge reservations or Ward scheduling with background agents.
Replace Ward’s heterogeneous review panel with one harness’s reviewer.
Make Goose a mandatory wrapper around every harness.
Treat harness hooks as the security boundary.
Require every harness to implement every capability.
Remove managed fallbacks.
Replace Ward’s external advisor with Claude’s native advisor.
Delegate merge, landing, or repository authority to the harness.

Acceptance criteria

Harnesses advertise runtime capabilities independently of argv construction.
Claude effort is passed through natively.
Codex and OpenCode runs can emit normalized structured events.
Review and QA use schema-constrained output when supported.
Native session IDs are persisted for at least one harness.
Codex and Claude goals are enabled by default when available.
Unsupported harnesses continue using the managed director flow.
At least one native review implementation can participate as a Ward review voter.
Native failures fall back cleanly or fail closed according to the existing role policy.
Ward’s container, forge, credential, audit, reaper, and review-quorum boundaries remain intact.
Documentation clearly distinguishes Ward-owned outer orchestration from harness-owned inner execution.

References

Alternatives considered

Before filing

I searched existing issues and this is not a duplicate.
This stays within ward's scope (the dev-verb gate / agent driver), not a personal-infra or downstream-repo verb.

### The problem // ### Proposed change **Body** ## Summary Ward currently models an agent harness primarily as a binary plus several argv shapes. That abstraction was sufficient when harnesses behaved like one-shot CLI tools, but Codex, Claude Code, Goose, and OpenCode now expose substantial runtime control planes: * Persistent sessions and resume * Structured event streams * Schema-constrained output * Native long-horizon goals * Lifecycle and tool hooks * Native review modes * Subagents and background execution * Remote-control surfaces * Programmatic protocols and servers The recent discovery of native `/goal` support is one instance of a broader architectural gap: Ward is reimplementing several inner-loop capabilities that modern harnesses can now provide directly. Ward should evolve into a capability-aware control plane over agent runtimes. Harnesses should own their model loop and session semantics; Ward should retain authority over isolation, forge policy, credentials, scheduling, audit, review quorum, and lifecycle enforcement. Native capabilities should be enabled by default when supported, with Ward-managed behavior retained as the fallback. ## Current state The primary `Agent` contract in `internal/agentsapi/agentsapi.go` describes: * Harness identity * Binary resolution * Preflight argv * Headless argv * Interactive argv * Credential and configuration composition * Installation and onboarding * Launch gating These are predominantly setup-time capabilities. Ward has no common runtime vocabulary for: * Sessions * Events * Goals * Structured output * Resume or interruption * Native review * Remote control * Harness hooks * Subagents This causes several concrete problems. ### Harness output is treated as unstructured Codex and OpenCode are currently declared with no structured stream support, despite providing JSON event modes: * Codex: `codex exec --json` * OpenCode: `opencode run --format json` * Claude: `--output-format stream-json` is already partially used * Goose: ACP provides a richer session protocol than `goose run -t` Ward consequently has to infer state from processes, stdout, ledgers, and polling instead of consuming explicit runtime events. ### Review and QA reimplement structured output `cmd/ward/agent_review.go`, `internal/reviewpanel`, and the QA flow ask agents to return fenced JSON and then recover it heuristically. Modern harnesses support schema-constrained output: * Codex output schemas * Claude `--json-schema` * OpenCode structured output Ward should use native schemas where available and preserve the existing parser only as a compatibility fallback. ### Ward owns continuation loops that harnesses can now own The director heartbeat implements polling, reconciliation, dispatch, completion evaluation, and livelock protection. Some of this remains Ward-specific, particularly forge reconciliation and scheduling. However, long-horizon task continuation can now be delegated to native goal mechanisms: * Codex first-class goal RPCs through app-server * Claude `/goal`, including headless invocation Ward should set the native goal at session start and allow the harness to own its inner continuation loop. Ward remains responsible for the outer run lifecycle and policy. ### Harness-specific flags can silently become stale `internal/agents/claude/claude.go` currently documents Claude effort as echo-only because no native effort flag existed when the adapter was written. Claude now supports `--effort`, along with capabilities such as: * `--max-turns` * `--max-budget-usd` * `--advisor` * `--bg` * `--permission-mode` * `--json-schema` The static argv abstraction makes capability drift easy to miss. ### Skills are flattened into context The container bootstrap composes a large `AGENTS.md` and exposes substrate skills primarily as documentation. This provides compatibility, but bypasses native skill systems that support: * Progressive disclosure * Explicit invocation * Harness-specific discovery * Reduced base prompt size Ward should eventually install or expose skills through each harness’s native mechanism while retaining the composed context as fallback. ## Harness capabilities worth integrating ### Codex Codex provides: * `codex exec --json` * JSON-schema output * `codex app-server` with threads, turns, items, approvals, and events * First-class goal set/get/clear operations * Persistent sessions * Native `codex review` * Lifecycle hooks * Native subagents * Experimental remote-control surfaces Codex should ultimately use an app-server-backed runtime driver rather than only `codex exec`. ### Claude Code Claude provides: * Streamed JSON output * JSON-schema output * Session IDs, resume, and fork * Headless slash-command invocation * Native `/goal` * Native effort, turn, and budget controls * Lifecycle and tool hooks * Subagents, background agents, and experimental agent teams * Native code, security, and ultrareview modes * Experimental `--advisor` * Remote Control for browser and mobile access * Channels for pushing external events into a running session Remote Control is particularly relevant to Ward’s attached-only director experience. It may provide mobile access to a Ward-managed session without Ward first implementing its own remote UI. Claude’s native advisor should not replace Ward’s independent advisor role. It is an inner-loop consultation using the engineer’s session context and trust boundary, while Ward’s advisor remains separately brokered and read-only. ### Goose Goose provides: * Agent Client Protocol support * Multiple isolated ACP sessions * Recipes and subrecipes * Remote serving * Session persistence * Scheduled execution * Claude and Codex subscription-backed ACP providers * Adversary mode and prompt-injection defenses Goose ACP may be useful as a common transport for local or otherwise weakly integrated harnesses. It should not immediately become the universal wrapper. Wrapping Codex or Claude through Goose can obscure native goal, session, resume, fork, approval, and review semantics. Goose adversary mode is also not a replacement for Ward’s security boundary: its reviewer failure behavior is fail-open. ### OpenCode OpenCode provides: * `opencode run --format json` * Session continuation, selection, and forking * A persistent headless server * An OpenAPI specification and SDK * Structured output * Native agents and child sessions * Plugins and event hooks * Native skills The immediate improvement is to consume `--format json`. A server-backed driver can follow later. ## Proposed ownership boundary ### Ward continues to own * Container and repository isolation * Forge authority * Issue reservation and scheduling * Credential delivery * Agent eligibility and launch policy * Audit records * Deterministic reaping * Landing and merge policy * Cross-harness orchestration * Heterogeneous review quorum * Managed fallback implementations ### Harnesses should own * Model execution and context compaction * Inner-loop goal continuation * Native session persistence * Resume and interruption semantics * Tool and approval event production * Inner-loop subagents * Harness-native review * Model consultation and advisor features * Interactive and remote session presentation Harness-native worktrees, sandboxes, teams, and background agents must not replace Ward’s container boundary or forge policy. ## Proposed architecture Extend the existing optional-interface pattern with runtime capabilities rather than adding more harness-specific conditionals to launch construction. The exact interfaces can evolve during implementation, but the capability vocabulary should cover concepts such as: ```go type SessionDriver interface { Start(context.Context, SessionRequest) (Session, error) Resume(context.Context, SessionID) (Session, error) Interrupt(context.Context, SessionID) error Events(context.Context, SessionID) (<-chan Event, error) } type GoalDriver interface { SetGoal(context.Context, SessionID, Goal) error GetGoal(context.Context, SessionID) (Goal, error) ClearGoal(context.Context, SessionID) error } type StructuredOutputDriver interface { RunSchema(context.Context, SessionRequest, json.RawMessage) (json.RawMessage, error) } type ReviewDriver interface { Review(context.Context, ReviewRequest) (ReviewResult, error) } type RemoteControlDriver interface { Expose(context.Context, SessionID) (RemoteEndpoint, error) } ``` Capabilities should be discovered explicitly. Example capability names might include: * `structured-events` * `structured-output` * `persistent-session` * `resume` * `interrupt` * `native-goal` * `native-review` * `hooks` * `subagents` * `remote-control` * `push-events` * `native-skills` Ward should prefer the native implementation when advertised and use the existing managed implementation otherwise. ## Persistence changes The Ward run ledger should record native harness identity alongside process identity: * Harness name and version * Native session or thread ID * Native goal state, when applicable * Runtime protocol * Capability snapshot * Remote-control metadata, if enabled * Last observed structured event * Resume eligibility This allows Ward to distinguish: * A running process * A resumable harness session * A completed goal * An interrupted but recoverable run * A run whose underlying harness state has been lost ## Review integration Native review commands should become available as review-panel voters: * Codex native review * Claude code review * Claude security review * Claude ultrareview where configured They should not replace Ward’s heterogeneous review quorum. Ward remains responsible for: * Selecting voters * Maintaining independence between voters * Normalizing results * Applying quorum policy * Recording provenance * Failing closed where required Native JSON schemas should be used to normalize each voter’s response. ## Hooks and policy Harness hooks should be used as defense-in-depth and event instrumentation. Potential uses include: * Recording tool calls and outcomes * Emitting deterministic activity events * Enforcing harness-level tool restrictions * Detecting session start, stop, and compaction * Relaying approval requests * Reporting subagent creation and completion * Triggering Ward reconciliation after meaningful activity Harness hooks are not the primary security boundary. Containers, repository permissions, credentials, and forge authority remain enforced by Ward. ## Remote control and event delivery Evaluate Claude Remote Control as an optional presentation layer for Ward-managed interactive sessions. The intended model is: 1. Ward creates and governs the container. 2. Claude continues running inside that environment. 3. Remote Control exposes the existing session to an authenticated browser or phone. 4. Ward records the exposure in the run ledger. 5. Ward retains termination and cleanup authority. Also evaluate Claude Channels for pushing CI, webhook, or issue events into a running session. This should complement, not replace, Ward’s outer backlog and forge reconciliation. ## Implementation plan ### Phase 1: Low-risk correctness and observability * Pass native Claude `--effort`. * Add Codex JSON event mode. * Add OpenCode JSON event mode. * Normalize structured events into a small Ward event type. * Use native output schemas for review and QA where supported. * Retain existing text and fenced-JSON behavior as fallback. * Record harness versions and advertised capabilities. ### Phase 2: Native session identity * Add a session-driver abstraction. * Persist native session and thread IDs in the run ledger. * Support resume and interrupt where available. * Distinguish process termination from session termination. * Add recovery behavior after Ward restart. ### Phase 3: Native goals and review * Enable native goals by default for Codex and Claude. * Retain the managed director loop for unsupported harnesses. * Allow native review commands to participate as panel voters. * Record whether a result came from native or managed execution. ### Phase 4: Protocol-backed drivers * Implement a Codex app-server driver. * Evaluate Claude Agent SDK integration versus the headless CLI. * Implement or adopt Goose ACP support. * Evaluate an OpenCode server driver. * Preserve argv drivers as compatibility mode. ### Phase 5: Presentation and context * Evaluate Claude Remote Control for Ward sessions. * Evaluate push-based event channels. * Install skills through harness-native mechanisms. * Retain composed `AGENTS.md` as compatibility and policy context. * Experiment with native advisors and subagents inside engineer runs. ## Non-goals This work does not: * Replace Ward’s container isolation with harness-native sandboxing. * Replace forge reservations or Ward scheduling with background agents. * Replace Ward’s heterogeneous review panel with one harness’s reviewer. * Make Goose a mandatory wrapper around every harness. * Treat harness hooks as the security boundary. * Require every harness to implement every capability. * Remove managed fallbacks. * Replace Ward’s external advisor with Claude’s native advisor. * Delegate merge, landing, or repository authority to the harness. ## Acceptance criteria * Harnesses advertise runtime capabilities independently of argv construction. * Claude effort is passed through natively. * Codex and OpenCode runs can emit normalized structured events. * Review and QA use schema-constrained output when supported. * Native session IDs are persisted for at least one harness. * Codex and Claude goals are enabled by default when available. * Unsupported harnesses continue using the managed director flow. * At least one native review implementation can participate as a Ward review voter. * Native failures fall back cleanly or fail closed according to the existing role policy. * Ward’s container, forge, credential, audit, reaper, and review-quorum boundaries remain intact. * Documentation clearly distinguishes Ward-owned outer orchestration from harness-owned inner execution. ## References * [Codex app-server](https://learn.chatgpt.com/docs/app-server) * [Codex non-interactive mode](https://developers.openai.com/codex/noninteractive) * [Codex hooks](https://developers.openai.com/codex/hooks) * [Codex subagents](https://developers.openai.com/codex/subagents) * [Claude CLI reference](https://code.claude.com/docs/en/cli-reference) * [Claude goals](https://code.claude.com/docs/en/goal) * [Claude headless mode](https://code.claude.com/docs/en/headless) * [Claude Remote Control](https://code.claude.com/docs/en/remote-control) * [Claude Channels](https://code.claude.com/docs/en/channels) * [Claude advisor](https://code.claude.com/docs/en/advisor) * [Goose ACP clients](https://goose-docs.ai/docs/guides/acp-clients/) * [Goose ACP providers](https://goose-docs.ai/docs/guides/acp-providers/) * [OpenCode CLI](https://opencode.ai/docs/cli/) * [OpenCode server](https://opencode.ai/docs/server/) ### Alternatives considered // ### Before filing - [x] I searched existing issues and this is not a duplicate. - [x] This stays within ward's scope (the dev-verb gate / agent driver), not a personal-infra or downstream-repo verb.