[joshrotenberg]

Adds two documents.

• docs/agent-session-spec.md, draft 0.5.1. The spec now continues in a new repository, voga, which will be published once it has an implementation. This copy is the snapshot at 0.5.1. A spec for one interface that creates, resumes and drives headless Claude Code and Codex sessions for any caller and any task. It is independent of language and runtime. It covers:
  • six operations;
  • their semantics, with a state table;
  • MCP and CLI surfaces over one layer endpoint;
  • an optional host-integration profile for Claude Code and Codex (plugin, skill, hooks);
  • the capabilities the layer needs from a provider wrapper;
  • 21 conformance scenarios;
  • an evaluation of the working hypothesis that a wrapper plus a thin layer is enough, with no agent framework in between.
• docs/agent-interface.md. The history and evidence behind the spec: the native subagent tool shapes, the trace of what each GenAgent and Ensemble layer did on the turn path, the wrapper gaps the spike found, and the evidence from runs 1 to 6.

How the spec was produced

The spec started from the behaviour of the #140 spike and the evidence from procedure runs 1 to 6. The plugins and hooks cookbook supplied the host-integration facts.

Each draft was reviewed through the spike's own agent operation, by one Claude and one Codex session, both read-only. The same two sessions were continued across rounds. Each round's findings went into the next draft, and Appendix D of the spec lists the changes per draft.

Round	Draft reviewed	Result
1	0.1	Lifecycle races, identity, retention, the transport model, and hook-driven defaults
2	0.2	No wire protocol between surfaces and the layer; a state machine was needed
3	0.3	Small blocking items: ownership, process groups, the MCP error boundary, version checks, usage meanings
4	0.4	Last contradictions and the recovery edge cases; applied in 0.4.1
Owner	0.4.1	Open questions settled (0.5); the CLI startup bound removed (0.5.1)

Findings recorded in the spec

• Environment leak. A layer started from inside a Claude Code session passes that session's markers to every child. In run 6 this included CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_SESSION_ATTENDED, and the desktop app's messaging socket and token. Section 5.17 makes a normative strip list.
• Codex usage. Codex reports usage as a running total for the thread. codex_wrapper's Session.total_usage/1 sums those totals, so it overcounts from the second turn. See section 5.15 and Appendix A.