Use Claude Code in a repeatable pipeline

Claude Code's print mode can turn a well-defined task into a pipeline stage. The surrounding program still owns the input contract, permission boundary, failure handling, and human decisions.

Flags were checked with Claude Code 2.1.263 on 2026-09-08. The reference parser uses synthetic envelopes; a credentialed end-to-end run is not verified here.

Export a bounded request

The reference package includes a plan stage that reads a retry contract and proposes a configuration change. In an import run, approve the scope packet before exporting that stage:

node cli.mjs export ./my-run --stage plan --file plan-request.json

The package returns a prompt, result schema, input digest, and limits. Keep the digest with the result so an old response cannot silently satisfy a new attempt.

For this artifact-only task, the reference invocation uses:

claude -p --restricted --safe-mode --strict-mcp-config --tools "" \
  --output-format json --json-schema SCHEMA_JSON --model YOUR_AVAILABLE_MODEL

Provide the exported prompt through standard input. SCHEMA_JSON is the schema's JSON text, not its filename. Use the package's argument builder to preserve quotes and the empty --tools value correctly on your platform.

Check both layers of JSON

A JSON response envelope is different from the task's structured result. Require process success, a successful result subtype, and a populated structured_output. Validate that object against the task schema and original evidence.

For example, a plan that cites line 2 of docs/retry-contract.md must quote text that exists there. A structurally valid plan that invents the requirement fails validation. Preserve a readable error for the operator; do not convert it into an empty successful result.

Preserve the intended authentication path

Ordinary print mode may load configuration and integrations without an interactive workspace-trust dialog. Use a prepared environment and inspect effective settings before automating a repository task.

The reference uses restricted mode and safe mode for a task that needs only supplied text. Restricted mode removes relevant execution tools and ignores ordinary user/project settings; safe mode disables customizations. Managed policy still matters. --strict-mcp-config prevents accidental discovery of other MCP configurations in this invocation.

Do not add --bare mechanically to an existing subscription workflow. Anthropic documents that bare mode skips OAuth/keychain authentication and requires a supported API/provider authentication path. That changes more than startup overhead.

Tool availability and permission approval are different controls. --allowedTools pre-approves tools; it is not a complete tool inventory. The empty built-in tool set plus explicit MCP handling is suited to this supplied-text example. Validate your installed version's behavior before using a different capability set.

Handle requests for more authority

If the task needs a command, file, or network destination outside the approved scope, stop that stage and return the concrete request to the coordinator. A failure is not permission to bypass the restriction.

For an interactive custom host, the Claude Agent SDK supports permission handling through canUseTool. Connect the applicable requests to a real decision flow. A print-mode answer saying “approved” is task output, not an approval record.

The package now supports supervised CLI execution through an explicit launcher/model profile. Use that walkthrough to automate dispatch and observe process outcomes while retaining human decisions. Its local subprocess tests do not establish credentialed provider behavior.

What goes wrong

Passing a schema filename where JSON text is expected breaks the request. Using bare mode with an assumed subscription login can change the authentication path. Pre-approving tools without controlling their availability can grant more capability than the stage needs.

How to check

Run the package tests. A result with is_error, missing structured output, or a nonzero recorded process exit must fail. Verify that a failed stage cannot open the design gate.

For a live synthetic trial, inspect the tool inventory and configuration behavior before submitting the request. Save the version, requested model, process result, and evidence checks. Account dashboards are the authority for billing; response usage or cost estimates should be labelled as reported measurements or estimates.