claude-runner

Claude Runner

Use shared/references/model-preview.md to choose the branch first. Deterministic checks need no model selection. Actual dispatch uses one concrete approved snapshot; nested calls consume it without re-resolution or extra workers.

Execute the caller's scoped prompt through the local CLI. Shared roles, envelope keys, and result handling live in shared/references/runner-common.md. Preserve seat fidelity: name the provider that actually answered, and report unavailable or unverified seats honestly.

Native routing

Read shared/references/host-model-execution.md before choosing an external route. If the current host can dispatch the exact selected Claude model with the required effort, isolation, and receipt policy in a native subagent or task thread, use that route. agents/openai.yaml is host UI metadata; it does not dispatch a native model.

Invocation

Set SKILL_DIR to this loaded skill directory in the same shell call:

SKILL_DIR="<absolute path of this skill directory>";
python3 "$SKILL_DIR/scripts/run_claude.py" "<scoped prompt>" \
  --model <approved-model-id> --effort <approved-effort> --disable-fallback --json

Copy the exact model and effort from the selected snapshot. Add its role, tool mode, receipt policy, and limits. Omit an effort flag only for a selected runtime controlled route. Nested calls use these saved options without resolving defaults again. The example does not grant source sharing or tool authority.

Runtime boundaries

• Use the local authenticated claude CLI in print mode. Permission checks remain enabled.
• Analysis roles default to repo_read_only: only Read, Glob, and Grep, with customizations disabled and an empty MCP configuration. --restrict-tools forces this profile; --tool-profile no_tools removes all tools. --allow-write or --tool-profile write keeps normal write permissions within the caller's authority.
• Prompt and file context may be sent to the configured provider. Bare mode changes authentication behavior; read the runtime reference before using it.
• The wrapper forwards model and effort. Primary assistant events can prove the serving model. Requested labels, initialization labels, synthetic events, and usage labels cannot. Missing evidence stays unverified; conflicting primary IDs or an exact model mismatch fail the result.
• Direct calls can fall back once when the CLI is missing and the fallback can preserve the constraints. Tool profiles and native budget limits block fallback. Approved routes disable fallback; native session continuation must preserve the selected runner.

Use --max-turns, --max-budget-usd, and --timeout for native turn, reported cost, and elapsed time limits. All must be positive and finite. A requested response length is advisory.

Load by need

• references/command-reference.md: flags, examples, native mappings, and return codes when composing a non-basic invocation.
• references/runtime-reference.md: authentication, fallback conditions, configuration, and extended envelope fields when configuring a route or interpreting its result.
• references/continuation.md: only when resuming a session or managing a background job.

Result

Read agent_message and the wrapper envelope. Check success, serving-model receipt, effective runner/provider, and any fallback or malformed-output status. A completed process alone does not prove the requested task or model was used. Report touched files when the caller authorized edits.