CLI Runtime Controls

Chronos CLI runs can configure streaming, tool approvals, model reasoning, debug logs, and persisted traces from YAML or process-wide flags. Run chronos -c agents.yaml config validate to catch unknown YAML fields and invalid runtime policy before execution.

Tool permission modes

Every tool keeps its declared permission (allow, require_approval, or deny). The registry permission mode controls what happens when an approval-gated tool is reached:

Mode	Behavior
prompt	Ask before each approval-gated tool (default)
auto_approve	Skip approval and confirmation prompts; explicit deny still wins
deny	Reject approval-gated tools without prompting

Configure an agent in YAML:

agents:
  - id: local-dev
    name: Local Developer
    permission_mode: auto_approve
    tools:
      - name: file_read
        permission: allow
      - name: file_write
        permission: require_approval
      - name: shell
        permission: deny

Override YAML for one CLI process:

chronos --permission-mode prompt repl
chronos --permission-mode auto_approve run "update the changelog"
chronos --permission-mode deny run "inspect this repository"
chronos --debug --trace run "diagnose this run"
chronos --no-debug --no-trace run "run quietly"

# Explicit shortcut for a trusted local environment:
chronos --dangerously-skip-permissions repl

--dangerously-skip-permissions is an alias for --permission-mode auto_approve. It does not override a tool declared with permission: deny.

Approve the rest of an interactive session

At a CLI approval prompt, enter:

Approve? [y/N/a=all for session]: a

The current call is approved and all later approval-gated tools are auto-approved for the rest of that CLI session. Enter y to approve only the current call, or anything else to deny it.

chronos pipe cannot safely prompt on the same stdin that supplies batch messages. It therefore changes the default prompt mode to deny. Select auto_approve explicitly in YAML, with CHRONOS_PERMISSION_MODE, or with a CLI flag when trusted tools must run in pipe mode.

Streaming

The REPL streams by default unless the active agent has an explicit stream setting:

agents:
  - id: assistant
    name: Assistant
    stream: true

Headless runs honor the same setting. A team run streams by default when every participating agent (including a separate coordinator) explicitly resolves to stream: true; mixed or unspecified team preferences default to a completed response. CLI flags take precedence:

chronos run --stream "explain this code"     # force token streaming
chronos run --no-stream "explain this code"  # force one completed response
chronos team run --stream pipeline "run it"  # force team token streaming
chronos team run --no-stream pipeline "run it"

Inside the REPL, /stream on and /stream off change the current session. Switching agents applies that agent's explicit stream preference.

Streaming emits model answer tokens as the provider produces them. Tool-only rounds may produce no answer text, so a tool-heavy agent can appear quiet while it reads or writes files. Enable debug: true or --debug to see live model-round and tool-call progress on stderr. A streaming transport failure is reported directly; it is never silently retried as a blocking call.

--stream/--no-stream/-s are process-wide flags, like --debug/--trace: they work anywhere on the command line, not just immediately after run/team run — chronos --stream run "..." and chronos run "..." --stream are equivalent. CHRONOS_STREAM=true|false is the environment equivalent.

Structured (JSON) output

--output-schema <file> points at a JSON Schema file and requests JSON conforming to it, overriding any output_schema: already set in the agent's YAML config. Like --stream, it is a process-wide flag and works anywhere on the command line:

chronos --output-schema schema.json run --agent extractor "Extract: Alice is 30"

schema.json must be plain JSON (a JSON Schema document), not YAML. See Structured (JSON) Output in the Agents guide for how the schema is enforced (request-side for OpenAI/Azure/OpenAI-compatible/Gemini/the Responses API, response-side validation on every provider) and CHRONOS_OUTPUT_SCHEMA=<file> for the environment equivalent.

--output-schema is about what the model returns. It's a separate concern from --json below, which is about what the CLI itself prints to your terminal — you can use either independently, or both together.

Machine-readable CLI output

By default chronos run/chronos team run print human-readable text ("Agent: ...", "Message: ...", the response, a token-count footer). --json (or CHRONOS_JSON=true) replaces all of that with exactly one JSON object on stdout, so scripts don't have to scrape text:

chronos --json run --agent extractor "Extract: Alice is 30"
# {"agent":"extractor","model":"gpt-4o","message":"Extract: Alice is 30","content":"...","usage":{"prompt_tokens":12,"completion_tokens":8}}

chronos --json team run pipeline "run it"
# {"team":"pipeline","message":"run it","response":"..."}

Like every other global flag, --json works anywhere on the command line. It also forces token streaming off (regardless of --stream/CHRONOS_STREAM/YAML stream:) — partial tokens on stdout would corrupt the single JSON object a script is expecting. On failure, the JSON object carries an "error" key and the process still exits non-zero; diagnostics beyond that stay on stderr, so stdout is always either one clean JSON object or nothing.

This is a different, more general mechanism than chronos pipe's own per-line {"agent":..., "content":...} protocol (which predates --json and is unaffected by it) — pipe reads one message per stdin line and always emits JSON, with no flag needed.

Native reasoning and thinking

Reasoning has two independent controls:

• strategy adds Chronos prompt scaffolding: none, cot, or reflection.
• native asks a supported provider to use its native reasoning/thinking feature. When false, effort, budget, and summary settings are not sent to the provider.

agents:
  - id: reasoner
    name: Reasoning Agent
    model:
      provider: anthropic
      model: claude-sonnet-4-6
      api_key: ${ANTHROPIC_API_KEY}
    reasoning:
      strategy: none
      native: true
      effort: high
      budget_tokens: 4096
      summary: true

Provider mapping:

Provider	Native mapping
OpenAI / compatible	reasoning_effort when effort is set
Azure OpenAI	Native reasoning uses /openai/v1/responses; encrypted reasoning items are preserved across tool rounds
Anthropic	extended thinking with budget_tokens
Gemini	thinkingConfig with budget and includeThoughts

Reasoning is carried separately from final answer text in ChatResponse.Reasoning. The CLI displays provider-approved reasoning summaries on stderr only when both native: true and summary: true; normal answer text remains on stdout. Providers can legitimately return no summary for simple or tool-only rounds. Setting native: false disables effort, budget_tokens, and native summary output. Prompt strategies (cot and reflection) modify answer content and are not native reasoning summaries.

Anthropic native reasoning with tools preserves signed thinking blocks on ProviderState and sends them back on later tool rounds. Gemini native reasoning is currently rejected when the request also contains tools because signed thought blocks cannot yet be preserved. Azure OpenAI native reasoning with tools is sent through the Responses API and preserves encrypted reasoning state between rounds.

Debug logs and traces

Enable runtime diagnostics in YAML:

agents:
  - id: observed
    name: Observed Agent
    debug: true
    tracing: true
    storage:
      backend: sqlite
      dsn: chronos.db

Or override for one CLI process:

chronos --debug --trace run --stream "diagnose this failure"

• --debug writes detailed agent execution logs to stderr.
• --trace attaches the storage-backed tracer and persists model, tool, and graph spans in the configured storage; it does not print spans to the terminal.
• Tracing requires storage.backend: sqlite or storage.backend: postgres. Configuration fails clearly when tracing is combined with none/memory storage instead of silently dropping spans.
• A relative SQLite DSN such as chronos.db is resolved from the process working directory, not from the YAML file's directory. chronos agent show <id> prints the resolved absolute path.
• Streaming and blocking model calls emit the same model-call hooks and tracing spans. Span completion updates the original row with ended_at, output, and error data.

Environment equivalents:

CHRONOS_PERMISSION_MODE=auto_approve
CHRONOS_DEBUG=true             # false explicitly disables YAML debug
CHRONOS_TRACE=true             # false explicitly disables YAML tracing
CHRONOS_STREAM=true            # false explicitly disables YAML/default streaming
CHRONOS_OUTPUT_SCHEMA=schema.json
CHRONOS_JSON=true              # print "run"/"team run" output as JSON

Precedence

For process-wide runtime controls, explicit CLI flags/environment overrides take precedence over YAML. Per-tool permission: deny is always enforced, including in auto-approve mode.