fix: #168 — exec-command / exec-tool / route / bootstrap now accept --output-format; CLI family JSON parity COMPLETE
Extends the #167 inspect-surface parity fix to the four remaining CLI
outliers: the commands claws actually invoke to DO work, not just
inspect state. After this commit, the entire claw-code CLI family speaks
a unified JSON envelope contract.
Concrete additions:
- exec-command: --output-format {text,json}
- exec-tool: --output-format {text,json}
- route: --output-format {text,json}
- bootstrap: --output-format {text,json}
JSON envelope shapes:
exec-command (handled):
{name, prompt, source_hint, handled: true, message}
exec-command (not-found):
{name, prompt, handled: false,
error: {kind:'command_not_found', message, retryable: false}}
exec-tool (handled):
{name, payload, source_hint, handled: true, message}
exec-tool (not-found):
{name, payload, handled: false,
error: {kind:'tool_not_found', message, retryable: false}}
route:
{prompt, limit, match_count, matches: [{kind, name, score, source_hint}]}
bootstrap:
{prompt, limit,
setup: {python_version, implementation, platform_name, test_command},
routed_matches: [{kind, name, score, source_hint}],
command_execution_messages: [str],
tool_execution_messages: [str],
turn: {prompt, output, stop_reason},
persisted_session_path}
Exit codes (unchanged from pre-#168):
0 = success
1 = exec not-found (exec-command, exec-tool only)
Backward compatibility:
- Default (no --output-format) is 'text'
- exec-command/exec-tool text output byte-identical
- route text output: unchanged tab-separated kind/name/score/source_hint
- bootstrap text output: unchanged Markdown runtime session report
Tests (13 new, test_exec_route_bootstrap_output_format.py):
- TestExecCommandOutputFormat (3): handled + not-found JSON; text compat
- TestExecToolOutputFormat (3): handled + not-found JSON; text compat
- TestRouteOutputFormat (3): JSON envelope; zero-matches case; text compat
- TestBootstrapOutputFormat (2): JSON envelope; text-mode Markdown compat
- TestFamilyWideJsonParity (2): parametrised over ALL 6 family commands
(show-command, show-tool, exec-command, exec-tool, route, bootstrap) —
every one accepts --output-format json and emits parseable JSON; every
one defaults to text mode without a leading {. One future regression on
any family member breaks this test.
Full suite: 124 → 137 passing, zero regression.
Closes ROADMAP #168.
This completes the CLI-wide JSON parity sweep:
- Session-lifecycle family: #160 (list/delete), #165 (load), #166 (flush)
- Inspect family: #167 (show-command, show-tool)
- Work-verb family: #168 (exec-command, exec-tool, route, bootstrap)
ENTIRE CLI SURFACE is now machine-readable via --output-format json with
typed errors, deterministic exit codes, and consistent envelope shape.
Claws no longer need to regex-parse any CLI output.
Related clusters:
- Clawability principle: 'machine-readable in state and failure modes'
(ROADMAP top-level). 9 pinpoints in this cluster; all now landed.
- Typed-error envelope consistency: command_not_found / tool_not_found /
session_not_found / session_load_failed all share {kind, message,
retryable} shape.
- Work-verb semantics: exec-* surfaces expose 'handled' boolean (not
'found') because 'not handled' is the operational signal — claws
dispatch on whether the work was performed, not whether the entry
exists in the inventory.
60925fa9f7