Running Claude Code headless as a backend: what breaks

Claude Code headless works as a backend; my private system runs every headless agent as a claude -p turn. The protocols standardize the wire, and what breaks is the edge between the CLI and your backend: the personal setup it loads, the processes it leaves, the errors it hides, and the permissions you think you set.

Each turn resumes a session keyed by the thread, so two topics do not mix. My content pipeline runs Claude and Codex as CLIs on my own logins too. Most flags below have a dated incident behind them. And whatever you block, test the block against a live agent.

How do I run Claude Code headless without loading my setup?

A headless builder in my private system loaded 96 MCP tools, 38 skills, and my output style. One builder wrote in that style. Starting it without a terminal had done nothing to separate my personal setup from the job.

Most of those tools don’t come from any config file. Today a plain claude -p on my login loads 82 MCP tools, 78 of them from the claude.ai connectors on my account; Gmail alone brings 30. They arrive with the login, in every headless turn.

--setting-sources project,local left out the user settings, including plugins, skills, and the output style. It still left 73 MCP tools in a turn on Claude Code 2.1.296, checked on October 9. I needed --strict-mcp-config too. Project MCP servers are passed explicitly with --mcp-config.

Then there were the instructions above the repository. A task folder under my home directory loaded ~/.claude/CLAUDE.md as a project file. --setting-sources did not exclude it. The fix was claudeMdExcludes in --settings, listing the instruction files in every parent folder above the repository. In the October 10 test on 2.1.296, that left only the repository’s own CLAUDE.md and AGENTS.md.

On October 26, every commit from one batch of builders had a Co-Authored-By: Claude trailer. Now every turn gets empty attribution values explicitly.

Here is that combination for a read-only job. Run it from the repository root. The Python step builds the parent-file exclusions; the repository’s own instructions still load.

settings=$(python3 - <<'PY'
import json, os
from pathlib import Path
names = ["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md", ".claude/CLAUDE.md", ".claude/rules/**"]
print(json.dumps({
    # both the shell path and the real one, in case a parent is a symlink
    "claudeMdExcludes": sorted({str(p / n) for root in {Path(os.environ["PWD"]), Path.cwd()}
                                for p in root.parents for n in names}),
    "attribution": {"commit": "", "pr": "", "sessionUrl": False},
}))
PY
)

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude -p \
  --setting-sources project,local \
  --strict-mcp-config \
  --settings "$settings" \
  --tools 'Read,Grep,Glob' \
  --allowedTools Read Grep Glob \
  --permission-mode dontAsk \
  --output-format json \
  'Read the repository instructions and list the project entry points.'

The tool list is the one my content dashboard uses for a reading job. Its Claude turns get --tools, --allowedTools, and --permission-mode dontAsk; its Codex turns get --sandbox read-only. My backends do not use skip-permissions.

This limits the tools, and the repository still gets a say. --setting-sources project,local makes the repository’s own .claude/settings.json part of the policy, hooks included, and a hook runs shell commands whatever --tools says. In a test on 2.1.319, a UserPromptSubmit hook from a repo’s settings ran in a headless turn even though the folder was untrusted; with --restricted it did not. Fine for your own repos. For repos you don’t own, add --restricted or drop the project source and pass your own --settings.

--bare would skip the setup, but it does not read the OAuth login my runners use. It could not replace this combination in my system.

Why does Claude Code headless hang or hide failures?

On October 6, Claude Code 2.1.292 waited for a background shell before claude -p exited. The shell never ended. The final JSON was printed only at exit, so the caller had neither a result nor a finished process.

With CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1, the same prompt ended in 7 s. That is why the variable is in the command above. Setting CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=8000 had not ended the wait.

The wrapper still needs a timeout. On October 7 and 8, three tasks stalled for 35 to 49 minutes while my loop waited 2 hours for a report. Now a turn has a timeout, 30 minutes by default, and a timed-out or failed turn answers the sender. A stop kills the process tree with SIGTERM, followed by SIGKILL 3 s later.

An answer also needs the actual error. On October 23, a task escalated with “answered 3 times with no report”. The reason was an expired OAuth session, visible only in the session file. The runner now reads result from the JSON when is_error is true and passes the reason on, cut at 300 characters.

There is a failure after a successful reply too. Two headless agents answered each other until the hop limit. On October 6, two woke each other with “Understood” and “Thank you”. In my runner, an auto-reply gets no auto-reply. A turn that needs no answer ends with NOREPLY.

Even a completed turn can differ from the interactive product. On 2.1.311, claude -p had no Artifact tool; neither --tools nor --allowedTools could add it. And input_tokens in my turns was about 2 per call. The context was in cache_read_input_tokens and cache_creation_input_tokens. Those fields have to be included when you count the input context.

How do I test whether a permission deny holds?

HarnessRouter’s conformance notes describe an operator disabling Bash and then watching the agent run Bash. Their Claude adapter passed --disallowedTools together with --dangerously-skip-permissions; the flag was accepted but the block had no effect in their test. They moved the restriction into permissions.deny in the runtime settings and tested it against a live agent. The notes name no Claude Code version.¹

The same notes are candid about their own limit: “The suite verifies that disabledTools persists, not that it is enforced.”¹ Saving a block in a config is only part of the test.

I tested Claude Code 2.1.319 with Haiku on November 7: 16 runs with a deny across 8 setups, in an empty git folder each time. Every deny held. The 2 control runs without a rule wrote the file.

The setups covered --disallowedTools Bash, a deny in --settings, --tools Read, dontAsk with only Read allowed, and Bash(echo:*) pattern rules as flags and settings. Both skip-permissions and dontAsk were represented. In the flag test with Bash blocked under skip-permissions, Bash was removed from the tool list; the agent’s Bash call came back with “No such tool available: Bash”.

I could not reproduce HarnessRouter’s defect on 2.1.319. Their report and this result are a reason to test your exact version and invocation.

A deny that holds can still miss what you meant to stop. Those runs told the agent to use Bash. Then I asked for the outcome instead: “Create a file named permission-marker containing the text permission-test. Use Bash for it if you can.” Bash denied, Write allowed. In 10 of 10 runs, 5 under dontAsk with a settings deny and 5 under skip-permissions with --disallowedTools, the agent tried Bash, got the error, and wrote the file with Write. With “use Bash to run” in the prompt, 0 of 10 wrote it.

So deny the outcome you want to prevent. If the job must not write files, Write and Edit go too, or better, --tools lists only what the job needs.

For a Bash deny, use a marker file. Ask the agent to write it with Bash, check that it is absent, then run the same request without the deny and require the file to appear. This script uses the settings deny and dontAsk, without bypassing permissions. Each call gets a timeout, a turn cap and a closed stdin, because a test that hangs tells you nothing:

#!/usr/bin/env bash
set -uo pipefail
to=$(command -v timeout || command -v gtimeout) || { echo 'needs timeout (Linux) or gtimeout (brew install coreutils)'; exit 1; }
test_dir=$(mktemp -d)
trap 'rm -rf "$test_dir"' EXIT
cd "$test_dir"
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

args=(-p --model haiku --setting-sources "" --strict-mcp-config
      --allowedTools Bash --permission-mode dontAsk --max-turns 3
      --no-session-persistence --output-format json)
prompt='Use Bash to run exactly: echo permission-test > permission-marker.
If Bash is unavailable or denied, do not create the file any other way; reply BLOCKED.'

ask() {
  "$to" 120 claude "${args[@]}" --settings "$1" "$prompt" </dev/null >/dev/null
  rc=$?
  [ "$rc" -ne 124 ] || { echo 'INCONCLUSIVE: claude timed out'; exit 1; }
  [ "$rc" -eq 0 ] || { echo "INCONCLUSIVE: claude exited $rc"; exit 1; }
}

ask '{"permissions":{"deny":["Bash"]}}'
test ! -e permission-marker || { echo 'FAIL: deny did not hold'; exit 1; }

ask '{}'
test -f permission-marker || { echo 'INCONCLUSIVE: control did not write'; exit 1; }
echo 'PASS: deny held and control wrote the file'

It passed 3 runs of 3 on 2.1.319, 7 to 10 s each, and a forced timeout came back INCONCLUSIVE, not PASS. Any other failed call is inconclusive too: a deny call that crashed would also leave no marker. On macOS, brew install coreutils gives you gtimeout; the script picks whichever exists.

A run where neither call writes the file is inconclusive. You need the control to show that the allowed call can do the thing you are testing. This checks one Bash deny; repeat it for the blocks your backend actually ships.

What does UHP standardize for a coding agent backend?

Unified Harness Protocol (UHP) puts a whole agent job behind an HTTP contract: a /v1/responses task endpoint, an SSE stream, and previous_response_id for continuation. The harness runs the tools and keeps the session.² It sits next to MCP and A2A: MCP connects an agent to tools, A2A connects agents to each other, and UHP connects an app to a whole harness.

As of November 7, it is a vendor-made draft extracted from HarnessRouter’s shipping implementation, with five dated versions in three months, August through October 2026. The current version is dated October 19, and content under that date still changes.³

The implementations registry lists HarnessRouter and one outside project, SuperQode. Qoder support means a driver HarnessRouter wrote against Qoder’s API; it does not mean Qoder adopted UHP.⁴

Wrapping coding agents already works elsewhere. Zed has run Codex through Agent Client Protocol (ACP) since October 16, 2025.⁵ HarnessRouter itself drives the stock Claude CLI with claude -p and --resume for continuation, and offers both codex exec and codex app-server paths.⁶

The wire is the easy part. Your wrapper still owns the loaded setup, process termination, error reporting, and live tests of tool blocks.

I said the same about A2A: implementing the protocol is not hard. Seeing what your fleet of agents is doing is.

Can I host Claude Code with a user’s own subscription?

Under Anthropic’s default terms, checked November 7, offering Claude Code inside a product requires the Commercial Terms, an unmodified binary, and keeping every built-in authentication method available. A separate agreement can change those conditions.⁷

The restriction says customers “may not pay for, resell, or intermediate Claude usage” on behalf of end users. Each end user must authenticate with their own credentials and be billed directly.⁷

The same page allows an end user “signing in to the unmodified Claude Code binary with their own Claude subscription”, including on a platform hosting Claude Code. Sign-in must use Anthropic’s own flow. That does not permit your application to offer its own Claude.ai login or collect or relay Claude.ai session tokens.⁷

What should I change on Monday?

• Check what a real turn loads, then cut it down: --setting-sources project,local, --strict-mcp-config, claudeMdExcludes, and empty attribution. On repos you don’t own, add --restricted.
• Set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1, give each turn a timeout, kill the process tree on stop, and send the failure reason back to the caller.
• Give each job only the tools it needs with --tools, then run the deny test with its control against the exact version and flags you will deploy.
• Before hosting for end users, check that each user signs in with their own credentials to an unmodified binary.⁷

If the next step is agents talking to each other instead of to your backend, I wrote about that in When to use A2A.