cyberine
UsageRun recipes

CLI flag-compat diagnosis + structured-output knobs (T656)

The claude and codex build workers pass version-gated CLI flags (e.g. codex's --dangerously-bypass-hook-trust, claude's --exclude-dynamic-system-prompt-sections). On an older installed CLI, the CLI rejects the unknown flag and the worker exits immediately. Cyberine now detects that failure shape (commander/clap/yargs unknown-option stderr) and surfaces a named, diagnosable error instead of the bare exit-code line — the message carries the rejected flag, the Cyberine task that relies on it, a known-good CLI version to upgrade to, and the env knob that disables the feature when one exists. The raw stderr stays appended, so no evidence is lost.

Run recipe — nothing to enable; the diagnosis is always on. To see it in action against your installed CLIs without dispatching a real task:

npm run selftest:cli-flag-compat

The registry of version-gated flags lives in CLI_FLAG_COMPAT (src/adapters/CliAgentAdapter.ts); add a row there when a new version-gated flag ships.

Structured output + subagent capture (T626/T628/T631, made reachable by T656) — three previously library-only opt-ins are now wired to env knobs, so the standard dispatch paths (CLI/TUI/MCP/web -> buildAdapters.ts) can reach them:

# claude worker: forward subagent text/thinking into Result.raw.subagentText
CYBERINE_CLAUDE_CAPTURE_SUBAGENT_TEXT=1 cyberine run "..."

# claude worker: schema-validated structured output into Result.raw.structuredOutput
# (inline JSON, or a path to a schema file — either works)
CYBERINE_CLAUDE_OUTPUT_SCHEMA='{"type":"object","properties":{"verdict":{"type":"string"}}}' cyberine run "..."
CYBERINE_CLAUDE_OUTPUT_SCHEMA=./schema.json cyberine run "..."

# codex worker: constrain the final message to a JSON Schema (file path only — codex's own
# --output-schema flag takes a FILE, unlike claude's --json-schema which takes schema text)
CYBERINE_CODEX_OUTPUT_SCHEMA=./schema.json cyberine run "..."

Known limitations and deferred work:

  • There is no upfront --version probe: an unsupported flag is diagnosed at first dispatch (from the CLI's own rejection), not at adapter-build time. The known-good versions in the message are verification floors ("upgrade to at least this"), not exact introduction points.
  • The diagnosis only recognizes commander (claude), clap (codex), and yargs (gemini) stderr shapes; other CLI workers (aider, crush, goose, ...) keep the generic exit-code message.
  • The codex structured-output knob feeds the headless build worker. makeCodexAdapter (the --json read-only variant) remains library-only — no production call site; embedders pass its outputSchema factory option explicitly.
  • An invalid schema value (unparseable JSON, missing file) is treated as unset — the worker runs without the flag rather than failing every dispatch; check cyberine doctor/the run output if structured output silently does not appear.