Claude harness reference
ClaudeOpts configures the claude() harness factory for Claude Code CLI-backed turns. Pass it as claude(opts); every field is optional.
ClaudeOpts
| Option | Type | Default | When to set |
|---|---|---|---|
binary | string | 'claude' (resolved via PATH) | Worker environments (systemd, containers) with a minimal PATH; pass an absolute path. |
model | ClaudeModel | Claude Code CLI default | Pin a default model for all turns from this harness instance; per-turn run.model/opts.model overrides it. |
apiKey | string | inherits environment/auth from process | Headless auth with ANTHROPIC_API_KEY. Orchard forwards it to the child process environment, never as an argv flag. |
defaultTimeoutMs | number | 1_800_000 (30 min) | Change the default per-turn timeout for this harness instance; per-call run.timeoutMs still overrides it. |
Per-run options
These are set per runUnstructuredTurn/runStructuredTurn call via HarnessTurnOptions (the harness-agnostic options harnessCall accepts), not on ClaudeOpts:
| Option | Type | Notes |
|---|---|---|
cwd | string | Required; working directory for the CLI process. |
access | 'read' | 'edit' | Defaults to 'read'; maps to Claude Code dontAsk or acceptEdits. |
resume | string | Resumes a prior Claude Code session by ID, used for same-session structured-output repair. |
model | HarnessModel | Per-turn override of ClaudeOpts.model. |
timeoutMs | number | Per-turn override of defaultTimeoutMs. |
onEvent | (event: unknown) => void | Receives parsed raw claude -p --output-format stream-json --verbose events for unstructured turns. |
Example
import { claude } from '@snevins/orchard-core/harness'
const harness = claude({
model: 'sonnet',
defaultTimeoutMs: 900_000,
})Supported model catalog
SUPPORTED_CLAUDE_MODELS covers Claude Code's advertised model aliases (fable, opus, sonnet, haiku) and the model-shaped full names observed in the installed Claude Code CLI surface. Claude Code 2.1.205 does not expose a clean models subcommand, so Orchard keeps this as a checked-in known catalog and keeps runtime pass-through open.
The ClaudeModel type includes those known values while still accepting custom strings so newly released or account-specific Claude Code models continue to pass through to the CLI.
Access and permission mode
harnessCall passes the selected access level into the harness. For Claude:
| Orchard access | Claude Code permission mode |
|---|---|
'read' | dontAsk |
'edit' | acceptEdits |
The built-in Claude harness intentionally does not expose Claude Code bypassPermissions or other dangerous bypass modes. Orchard keeps the public contract to read/edit intent plus readiness options (binary, model, apiKey, defaultTimeoutMs).
Structured output
claude() implements runStructuredTurn. Orchard calls Claude Code in print mode with --output-format json and --json-schema, then passes the returned structured_output through harnessCall validation. If a repair turn is needed, harnessCall resumes the same Claude Code session and falls back to extracted JSON.
Failure classification
Claude Code auth, usage, invalid-model, and missing-binary failures are rethrown as NonRetryableHarnessError with a claude: prefix so the runtime does not retry unrecoverable configuration failures. Agent-reported errors, timeouts, and unclassified process failures remain retryable.