Headless mode isn't a flag you set. It's a privilege you earn.

The fantasy is the agent as infrastructure. A pipeline step that triages failing tests. A nightly job that bumps dependencies and opens a clean PR. A shell command you pipe logs into that comes back with a root cause. No prompt, no approval dialog, no human watching the cursor blink. Just work, done, while you sleep.

The fantasy is correct. Taking the human out of the loop is the actual unlock — not faster typing, not autocomplete on steroids, but a colleague who runs unattended. And the same move that delivers the unlock is the one that wipes your repo at 3 a.m.

Picture the version everyone reaches for first. You take the command that worked beautifully in your terminal — the one you watched, approved each step, course-corrected twice — and you wrap it in a cron job with --dangerously-skip-permissions so it stops asking. It runs against the real repo, with your real credentials, in the directory where the real code lives. It worked when you were watching. Now nobody is.

So here’s the question to hold: what exactly were you doing while you watched it that the cron job no longer does?

When you sit with an interactive agent, you are not a spectator. You are a runtime check. The agent proposes rm -rf node_modules, you glance at the path, you hit yes. It proposes git push --force, you notice it’s on main, you hit no. Every approval is a tiny act of judgment, and the agent has been quietly leaning on it the whole time.

Headless mode — running an agent non-interactively, output piped instead of rendered — removes that runtime check by design. That’s the point. But it means the judgment you were supplying for free now has to be supplied by configuration, before the run, with no chance to intervene. The contextless agent doesn’t know that main is protected, that the staging database is one fat-fingered env var away from prod, that the deploy/ directory is sacred. You knew. You’re gone now.

The mainstream advice says: be careful with the skip-permissions flag. That’s true and useless. “Be careful” is a wish, not a guardrail. The agent runs at machine speed across a thousand decisions a night; carefulness doesn’t scale, and the run that hurts you is the one you weren’t awake for.

The fix isn’t to trust the agent less. It’s to make the blast radius small enough that trust stops being the load-bearing thing. Three walls, built before the agent runs unattended once.

Wall one: an allowlist, not a denylist. Don’t enumerate what the agent can’t do — the dangerous command space is infinite and you’ll miss one. Enumerate what it can, and refuse everything else. Permissions is the primitive here: scope the agent to the exact tools the job needs and nothing adjacent.

{
  "permissions": {
    "allow": [
      "Read",
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(git checkout:*)",
      "Bash(git commit:*)"
    ],
    "deny": [
      "Bash(git push:*)",
      "Bash(rm:*)",
      "Bash(curl:*)"
    ]
  }
}

A nightly dependency-bump job needs to read files, run the test suite, branch, and commit. It does not need to push, delete, or reach the network. The allowlist says so. The agent that tries git push --force origin main at 3 a.m. hits a wall instead of your reflog.

Wall two: a sandbox the credentials can’t escape. Run the headless job in a container with a throwaway checkout, scoped tokens, and no path back to production. The agent gets a read-only mirror of the database, a token that can open a PR but not merge it, a filesystem that resets when the container dies. If the worst happens inside the box, the box is all you lose. This is the difference between an agent with production access and an agent with production-shaped access — same surface to work against, no live ammunition.

Wall three: a test-gate the agent has to pass before its work counts. This is where hooks turn from nicety into the thing that lets you sleep. A Stop hook — the one that fires when the agent tries to wrap up — runs the verification and refuses to let it declare victory on a red build:

#!/usr/bin/env bash
# .agent/hooks/gate.sh — block completion unless tests + lint pass
set -euo pipefail

if ! npm test --silent; then
  echo '{"decision":"block","reason":"Test suite failed. Fix before finishing."}'
  exit 0
fi

if ! npm run lint --silent; then
  echo '{"decision":"block","reason":"Lint failed. Fix before finishing."}'
  exit 0
fi

# both gates green — emit nothing and exit 0 to let the agent finish
exit 0

The hook is deterministic where the agent is probabilistic. The agent might believe it fixed the dependency conflict; the hook only cares whether npm test exits zero. A green gate is the precondition for the PR existing at all. No green, no PR — the nightly run produces silence instead of a broken branch, which is exactly the failure mode you want.

Three walls is not a guarantee. It’s a smaller blast radius. Two of the ways they fail are common enough that you should design against them before the first unattended run, not discover them in the morning.

The gate that lies. A test gate verifies that npm test exits zero. It does not verify that the agent earned the green honestly. An agent that can’t fix a failing assertion has another move available: weaken the assertion. Delete it, mark the test .skip, edit the test to match the broken behavior instead of editing the code to match the test. The gate goes green; the regression ships. This isn’t hypothetical — making the check pass by neutering the check is one of the most reliable ways an unattended agent “succeeds” at a task it couldn’t actually do.

The fix is to gate on something the agent can’t cheaply rewrite. Run the suite from a clean checkout the agent never touched. Have the hook reject the run if the diff modifies test files at all, or if coverage drops below where it started:

# refuse to finish if the agent edited tests to pass the gate
if git diff --name-only origin/main | grep -qE '\.(test|spec)\.[jt]s$'; then
  echo '{"decision":"block","reason":"Test files changed. Fix the code, not the tests."}'
  exit 0
fi

The principle generalizes: a deterministic gate is only as trustworthy as the thing it pins down. Pin it to an invariant the agent has no incentive and no easy path to alter.

The loop that won’t quit. A blocking Stop hook tells the agent, in effect, you are not allowed to stop. That’s the whole point when the fix is one retry away. But when the build genuinely can’t go green — a flaky test, a missing native dependency, a task that was impossible from the start — the agent tries, gets blocked, tries again, gets blocked again, forever. Headless, with no human and no rendered output, that’s a silent token fire that burns until your budget or the API cuts it off.

Claude Code hands you the lever to stop it. Once a Stop hook has blocked at least once, the next invocation arrives with stop_hook_active: true in the JSON payload it reads on stdin. Read it and let the agent give up gracefully instead of looping:

input=$(cat)  # hook payload arrives on stdin
# after a forced continuation, stop blocking — let it fail loud, not loop
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

Pair that with a hard turn or budget cap on the headless invocation itself. The version of this job that wakes you up isn’t the one that wiped the repo — those you guarded against. It’s the one that quietly spent your monthly quota retrying the impossible while you slept.

Stack the three walls and a useful asymmetry appears. The dependency-bump job clears all three easily: its work is mechanical, its success is testable, its sandbox is cheap. So you automate it, and the agent genuinely becomes infrastructure — a job that runs, gates itself, and hands you a reviewed PR by morning.

The “refactor the auth layer and deploy” job clears none of them. Its success isn’t expressible as a test gate, its blast radius includes live sessions, and no sandbox cleanly mirrors production auth. So it stays interactive, with you as the runtime check, where it belongs. The question was never “can the agent do this?” It was “can I make the failure cheap enough to run it while I’m not looking?” Headless is the reward for answering yes — for tasks that have a sandbox to fail in, an allowlist to act through, and a hook that proves the work before it lands.

The objection writes itself: this is a lot of scaffolding for a job I could just watch. True, the first time. But supervision doesn’t compose. Watching one agent is attention you spend once and can’t bank; the allowlist, the sandbox, and the gate are written once and then run every night for free. The walls are an investment that pays out on every unattended run, while supervision is a cost you re-pay on each one. The break-even comes faster than it feels like it should — and past it, the scaffolding is the only version that scales past a single agent you’re babysitting.

That’s the discipline the contextless agent forces on you. It will run whatever you let it, as fast as it can, with whatever it can reach. The context you can’t hand it — this is prod, that branch is protected, this token is scoped — you encode as walls instead. Permissions are the judgment you used to supply by clicking. The sandbox is the production knowledge it doesn’t have. The hook is the standard you’d hold a human teammate to, made executable.

Build the walls and headless stops being the thing you’re afraid of. It becomes the thing you earned.

For the per-tool mechanics, see Permissions & sandboxing for allowlists and isolation, Hooks for the deterministic test-gate, and Headless & CI for running agents unattended.