feat(agent-spec): add direct argv launches

[schickling-assistant]

Why

Agent Specs currently require shell source even when the declaration already knows the exact
program and argument boundaries. Authors therefore need shell quoting and a leading exec solely
to avoid retaining an intermediate shell process.

Closes #67.

What

• add mutually exclusive argv launch declarations alongside the existing command shell form;
• support compact agents and explicit PTY/exec tasks in KDL, TOML, and JSON;
• launch structured argv directly in both execution backends, with no sh -c;
• migrate maintained examples and compile-agent output to the direct form.

How

The declaration model preserves command and adds argv, rejecting empty vectors, empty programs,
and declarations that provide both. Reconciliation lowers either representation into a typed task
launch. PTY tasks place direct values verbatim after pty run ... --; terminal-free tasks pass the
program and arguments through the existing isolation wrapper. $VAR expansion follows the existing
non-shell field behavior, including Codex hook-gate classification, while shell commands retain
their exact historical semantics.

Rationale

Keeping command unchanged preserves pipelines, redirects, variable expansion, and compound shell
programs. A separate structured form avoids guessing shell syntax, preserves exact argument
boundaries, and lets bare programs resolve through the controlled task PATH.

Verification

• nix flake check --print-build-logs
• cargo clippy --all-targets --all-features -- -D warnings
• parser/lowering tests for compact and explicit KDL plus TOML/JSON
• negative tests for empty argv and command/argv ambiguity
• PTY argv-shape test proving no shell is inserted
• exec-backend behavior test proving literal argument boundaries and catalog expansion
• compiler/example materialization tests

Canonical Agent Spec follow-up

compoundingtech/evals#44 tracks updating the
pinned canonical authoring contract and executable semantic coverage after this implementation
lands.

Posted on behalf of @schickling

field	value
agent_name	co2-bear
agent_session_id	a078daee-6f98-4916-91a8-d21291407789
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	st2/schickling-assistant/2026-07-29-direct-argv
machine	dev3
tooling_profile	dotfiles@0fb7e03

[myobie]

I like this direction. A structured direct-argv launch is a clearer default whenever a declaration does not need shell syntax, while preserving command as the explicit shell escape hatch.

One validation edge should be closed before this is marked ready: argv "" is a non-empty vector, so validate_launch accepts it even though element 0 is the program and spawning it can only fail later. Please reject an empty program (and add the compact/explicit regression cases) alongside the existing empty-vector and command+argv checks.

Interested in reviewing the finished PR; this comment is not yet merge approval.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7e1f4ec1e3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[schickling-assistant]

Addressed the remaining launch-validation edge in 1968343: both compact and explicit argv "" declarations are now rejected, with regression cases alongside the existing empty-vector and mixed command + argv coverage. The authoritative nix flake check --print-build-logs gate passes. Canonical downstream Agent Spec evaluation coverage is tracked in compoundingtech/evals#44.

Posted on behalf of @schickling

field	value
agent_name	co2-bear
agent_session_id	a078daee-6f98-4916-91a8-d21291407789
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	st2/schickling-assistant/2026-07-29-direct-argv
machine	dev3
tooling_profile	dotfiles@0fb7e03