Module engine 

The internal config-and-run seam (#407).

run is roba’s resolve-free, side-effect-free core: a Config in, a claude_wrapper::types::QueryResult out. No clap, no stdout/stderr, no process::exit, no TTY, no interactive prompts. The CLI’s run_ask resolves flags/profiles/prompt and renders the result around this; a programmatic caller (or, later, serve – see #142) builds a Config directly.

Config covers the full run-shaping surface that apply_session consumes – model/fallback/effort/agent, the permission posture + --permission-mode, session continuity, worktree, caps, timeout, the system-prompt overrides + the agent notice, retry/persistence/bare/safe modes, --add-dir, and MCP config. It feeds the proven apply_session mapper directly (apply_session reads &Config), so there is one flag->command mapper and no second copy to drift; a bare Config maps to roba’s safe defaults (read-only, a fresh session, no caps, and the built-in agent notice injected). The CLI’s run_ask builds a Config from its resolved AskArgs (build_config) and routes through this same seam.

Out of scope for v1 (stays in the CLI layer): prompt composition (attach/git/prepend/vars – Config takes the already-composed prompt), profile/env layering, live streaming display, output formatting, and exit-code classification.

Structs

Config

A config-and-run request: everything run needs to send one prompt through claude and hand back the typed result. The prompt is the final, already-composed text (the CLI does attach/git/var composition before building this).

Enums

Permissions

The permission posture for a run. Mirrors roba’s safe-by-default model: the default is read-only (Read/Glob/Grep), and the variants open it up.

Session

What to do about session continuity, mirroring the CLI’s -c / --resume / --session-id / --fresh selectors as one closed choice.

Functions

execute

Build the QueryCommand for config – through the one proven apply_session mapper – and run it non-streaming, returning the typed result. The single build+execute path shared by run and the CLI’s non-streaming branch (run_ask), which both hand this the same Config, so there is no parallel copy to drift.

run

Run one prompt through claude under config and return the typed result.

surface_structured_output

Surface --json-schema structured output cleanly (#317).