What you will be able to do
- Configure a headless run so that every action it needs is pre-approved and everything else is denied instead of left waiting
- Design a progress record outside the agent run so that a killed or repeated run resumes without duplicating work
- Make an event-triggered responder idempotent against webhook redelivery
- Design notification and escalation paths that do not rely on a run's success status
1.Pre-approving what a headless run may do
An unattended run is one that a goal, a schedule or an event starts with no human at the keyboard. The most common way such a run fails is not a wrong answer. It is a permission prompt that nobody will ever answer. A headless claude -p review job that needs to run the test suite stops at the approval prompt and sits there until the CI job times out. Raising the timeout only means it waits longer for an approval that will never come.
The fix is to decide in advance what the run may do. --allowedTools entries or permissions.allow rules pre-approve exactly the commands the job needs. Patterns such as Bash(git diff *) limit a tool to specific command shapes:
claude -p "Look at my staged changes and create an appropriate commit" \
--allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"The permission mode decides what happens to everything you did not allow:
dontAskdenies every call that would otherwise prompt. Allowed tools, file reads and the read-only command set still run. A locked-down CI run fails fast on a denial instead of hanging.acceptEditswrites files and runs common filesystem commands such asmkdirandmvwithout prompting. Other shell commands still need an allow entry.autohas a classifier review most actions instead of a person.
An instruction in the system prompt telling the agent to "proceed without sign-off" changes nothing, because the model does not enforce permissions. The allow rules and the mode do. Cloud scheduled tasks default to auto mode, but even there a human can end up as the bottleneck. Once blocks reach auto mode's repeated-block thresholds, a prompt appears in the run's session and waits. For machine consumers, --output-format json returns the result, session ID and metadata, and you can parse them with jq -r '.result'.
Checkpoint 1 of 8· Fill the gap
A headless commit job must run only these git commands without stopping at a permission prompt. Which flag completes the command?
claude -p "Look at my staged changes and create an appropriate commit" \
? "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"--allowedTools pre-approves exactly the listed command patterns, so the run doesn't stop at a prompt that nobody will answer. A system-prompt instruction can't do this, because the model doesn't enforce permissions.
Source: code.claude.comCheckpoint 2 of 8· Check yourself
A locked-down CI review job runs claude -p with a short allow list. When Claude tries a command outside that list, the job should fail fast on a denial and not hang until the CI timeout. What should you add?
dontAsk denies every call that would otherwise prompt, so the run fails fast instead of waiting. acceptEdits still requires allow entries for other shell commands, and permissions are enforced by Claude Code, not by the model's instructions.
“dontAsk: Claude Code denies every call that would otherwise prompt, which is useful for locked-down CI runs”Source: code.claude.com
Checkpoint 3 of 8· Exam question
Alder Analytics runs its customer-billing platform in production, and a CI job invokes a headless agent on every pull request to review the diff and run the project's test command. The job runs on an ephemeral runner with no maintainer attached, and the security team requires that what the agent can execute stays limited to what a review needs, enforced by the tooling rather than by instructions to the agent. Last night's review sat silent until the 30-minute job timeout. The logs show the agent paused waiting for approval to run the project's test command, which nobody could grant. A manual re-run of the same job ended the same way. The team wants reviews to finish unattended. What is the best fix?
Correct answer: D — Add allow rules in the job's permission settings for the test runner and read-only commands, with a deny rule covering the remaining tools.
- A. Bypassing prompts ends the stall but leaves the unattended agent with no limit on what it may run. A throwaway container only discards file changes; it does not restrict network access or the credentials available to the job.
- B. A system prompt is guidance, not a grant of permission. The harness still blocks the test command and waits for approval, so the run stalls as before. Even if the agent complied, a prompt line is not an enforced control.
- C. The log shows the request was never going to be answered, because the job runs headless and no maintainer is attached to it. A longer timeout and a retry reach the same unanswered prompt again, only later and at greater cost.
- D. Rules declared up front let the job run the test command and read operations without any prompt, and the deny rule blocks other tools. The run completes unattended while its scope stays limited to what the review needs.
2.Checkpoint progress outside the run
Anything kept only in the session's memory is lost when the process dies. Claude Code's own recovery is partial. On resume it does not restart background Bash commands or monitors, it does not restore a self-paced /loop, and a restored cron task skips the runs it missed. Built-in checkpoints for /rewind are saved with the conversation, so they track edits inside one session, not progress across many nights. (Durable state for long runs covers the general pattern.)
The progress record therefore has to live outside the run, somewhere every new run reads first. For the 60-service upgrade, that means a status manifest with an entry per service, written as soon as each service finishes, including its PR link. Each new run reads the manifest, skips finished services and resumes at the first unfinished one. Duplicate PRs stop, because "already done" is now recorded somewhere the next run checks. A longer timeout plus compaction still leaves one long session as the single point of failure, and a context overflow that auto-compaction can't clear ends a goal anyway. Rereading last night's transcript does not work either: the run that was killed is exactly the run whose record is incomplete.
The same idea drives the Claude Tag on-call agent. Its lessons.md file is a running log, kept in the repository, of every resolved incident. Claude appends to it automatically, and every new investigation begins by reading it.
Checkpoint 4 of 8· Check yourself
Before relying on claude --resume to recover an interrupted unattended session, you check what it brings back. The session had a recurring CronCreate task, a self-paced /loop and a background Bash monitor running when it died. Which of these is restored on resume?
Resume restores CronCreate tasks, but those tasks skip the runs they missed. It does not restore a self-paced /loop or restart background Bash commands and monitors. Because recovery is only partial, progress has to be recorded outside the run, where the next run reads it first.
“A self-paced /loop isn’t restored, so run /loop again to restart it.”Source: code.claude.com
Checkpoint 5 of 8· Exam question
Yarrow Housing runs a nightly agent on a managed CI runner. It upgrades dependencies across the 60 services of its rental-management platform and opens one PR per service. Each service takes roughly 14 minutes, and the runner's six-hour limit kills the job after about 25 services. Every night the agent restarts at service one, so reviewers find duplicate PRs for the same services. Each run starts on a fresh ephemeral runner, and no disk contents or earlier conversation survive between runs. The platform team expects the fleet to keep growing. It also wants failed or retried runs to be harmless, because a retry last week reopened PRs for services that were already finished. What is the best fix?
Correct answer: C — Write a per-service status manifest with PR links outside the run after each service, and have every run skip finished services and resume.
- A. A longer timeout only moves the cliff, and the fleet will grow. Compaction manages context size but does not give the next run any record of what was already done.
- B. Parallel shards avoid the timeout, but with no shared record a rerun or retry still opens duplicate PRs. Nothing makes the work idempotent.
- C. Durable external progress state written after each unit makes runs resumable and idempotent. A timeout then costs only the unfinished services, and duplicates are avoided because finished work is skipped.
- D. A fresh ephemeral runner has no previous conversation to reread, so this depends on state that does not exist. Checkpoints must live in storage the next run can read.
3.Idempotent responders for redelivered events
Every fire of an event trigger starts a new agent session, so the trigger itself does not deduplicate anything. The API trigger's response shows this: each POST returns a fresh session ID.
curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_01ABCDEFGHJKLMNOPQRSTUVW/fire \
-H "Authorization: Bearer sk-ant-oat01-xxxxx" \
-H "anthropic-beta: experimental-cc-routine-2026-04-01" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}'
{
"type": "routine_fire",
"claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ",
"claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ"
}Here is where duplicates come from. A CI provider redelivers a failure webhook whenever the receiver is slow to acknowledge. If the receiver fires an agent for each delivery, one red build gets two agents and two PRs. The fix belongs in your receiver, in front of the agent. Acknowledge immediately and put the event on a queue. Then, before starting any agent, atomically claim a key built from the CI run ID plus the attempt number. A redelivery of the same attempt finds the key already claimed and does nothing. A real re-run of the job is a new attempt, so it correctly gets its own responder.
Three tempting fixes fall short. Making startup faster so acknowledgement beats the timeout makes duplicates rarer but does not stop them. A random startup delay works the same way. Letting both agents run and having the loser close its own PR at the end wastes a full run and still leaves a window where two PRs exist.
Checkpoint 6 of 8· Fill the gap
Your webhook receiver fires a cloud scheduled task's API trigger once for every CI delivery it gets. Which response field shows that each POST starts its own run, so the trigger does nothing to deduplicate a redelivered webhook?
curl -X POST https://api.anthropic.com/v1/claude_code/routines/trig_01ABCDEFGHJKLMNOPQRSTUVW/fire \
-H "Authorization: Bearer sk-ant-oat01-xxxxx" \
-H "anthropic-beta: experimental-cc-routine-2026-04-01" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}'
{
"type": "routine_fire",
" ? ": "session_01HJKLMNOPQRSTUVWXYZ",
"claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ"
}Each fire returns a new claude_code_session_id. The trigger has no idempotency or dedup key, so two deliveries of the same failure start two agents. To stop that, your receiver has to claim a key made from the CI run ID and attempt number before it fires the trigger.
Source: code.claude.comCheckpoint 7 of 8· Exam question
Zephyr Analytics runs an autonomous build-repair agent for its production CI. When a build fails, the CI provider sends a failure webhook to the agent's endpoint, which starts a run that diagnoses the failure and opens a fix PR. The provider redelivers the same webhook if no acknowledgement arrives within ten seconds, and the agent's startup (repository checkout, dependency install) usually takes longer than that. Last week, for a single failing build, two agents launched and opened two PRs. Logs show both runs carried the same run ID and attempt number. Reviewers had to close one PR by hand. The team wants a guarantee that duplicate deliveries never produce duplicate work, whatever the cause of redelivery. What is the best fix?
Correct answer: A — Acknowledge at once and enqueue; claim a key built from run ID and attempt atomically before any agent starts.
- A. Decoupling acknowledgement from work removes the cause of redelivery. An atomic claim on a stable key makes duplicates harmless even if the provider redelivers for other reasons.
- B. Faster acknowledgement lowers the odds of redelivery but cannot rule it out, since networks and providers retry for other reasons. Dedupe must not depend on timing.
- C. Both agents would still spend a full run, and the end-of-run check races. Two agents that finish together can each see no other PR.
- D. Jitter only narrows the race window. Two runs can still pass the check together, so it gives no guarantee.
Sources2
4.Notification and escalation design
A run's status shows how its session ended, not whether the work got done. A cloud scheduled task shows Succeeded when the session ended without Claude Code reporting a failure. Blocked network requests, missing connector tools and work Claude couldn't complete appear only in the transcript. Failed means the session did not finish normally. Alerting only on Failed therefore misses runs that ended cleanly but did nothing useful. The task's own output should state the result explicitly, the way a deploy-verification task posts a go or no-go to the release channel.
Escalation needs both a deterministic path and an agentic one. In the Claude Tag setup, alerting is deterministic. Escalation applies written criteria from oncall.md, for example: page on-call if the error rate stays above 2% for more than 5 minutes outside a known deploy window, and otherwise log it to lessons.md. Because the thresholds are written down, the paging decision can be reviewed and tuned. The agent's judgement goes into the investigation.
Notification also covers the people who were not paged:
- Fixes arrive as PRs that on-call reviews, merges and deploys.
- After a fix, Claude checks it with the same tools it used to investigate, then writes a post-mortem to
lessons.mdand a handoff situation report. - Daily and weekly summaries let the next person on rotation pick up where the last one left off.
Checkpoint 8 of 8· Match them up
Your monitoring for unattended runs has to tell these end states apart, because only some of them mean the work was done. Match each state to what it actually tells you.
Tap a term, then the definition that fits it.
Succeeded describes how the session ended, not whether the work got done. If you alert only on Failed, you miss runs that ended cleanly with work left undone, and you also miss goals that are paused. To catch those, the task's output should state the result explicitly, and monitoring should look for paused and blocked states.
“Succeeded: the session ended without Claude Code reporting a failure. Blocked network requests, missing connector tools, and work Claude couldn’t complete appear in the transcript”Source: code.claude.com
Practise it for real
Run Claude Code headless with a narrow, pre-approved tool set and machine-readable output, the way a CI job would.
1.In a repository, run: claude -p "Summarize this project" --output-format json | jq -r '.result'
Why: A CI step consumes structured output, not terminal text.
You should see: A plain-text summary printed by jq. Without the jq filter you see a JSON object that includes the result and a session ID.
2.Run: claude -p "Run the test suite and fix any failures" --allowedTools "Bash,Read,Edit"
Why: Pre-approving the tools the job needs means it never stops at a prompt nobody can answer.
You should see: The run executes tests and edits files without asking for approval, then exits.
3.Run the same prompt again with --permission-mode dontAsk and only --allowedTools "Read"
Why: Shows what a locked-down run does with an action it was not granted.
You should see: Calls that would have prompted are denied instead of hanging, and the run reports that it could not run the tests.
Stuck? Get a nudge
If a run hangs, check which tool it was waiting on and add an allow entry for that exact command shape rather than switching off permissions.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/headlessOfficial docs
“dontAsk: Claude Code denies every call that would otherwise prompt, which is useful for locked-down CI runs”
↩︎ Pre-approving what a headless run may do“Actions covered by your --allowedTools entries or permissions.allow rules also run.”
↩︎ Pre-approving what a headless run may do“json: structured JSON with result, session ID, and metadata”
↩︎ Pre-approving what a headless run may do“Actions covered by your --allowedTools entries or permissions.allow rules also run.”
↩︎ Exam trap 1 - 2.https://code.claude.com/docs/en/routinesOfficial docs
“Once blocks reach auto mode’s repeated-block thresholds, a permission prompt appears in the run’s session and waits until someone answers it”
↩︎ Pre-approving what a headless run may do“"claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ",”
↩︎ Idempotent responders for redelivered events“Blocked network requests, missing connector tools, and work Claude couldn’t complete appear in the transcript rather than on the row”
↩︎ Notification and escalation design“Blocked network requests, missing connector tools, and work Claude couldn’t complete appear in the transcript rather than on the row”
↩︎ Exam trap 2“Succeeded: the session ended without Claude Code reporting a failure. Blocked network requests, missing connector tools, and work Claude couldn’t complete appear in the transcript”
↩︎ Checkpoint - 3.https://code.claude.com/docs/en/scheduled-tasksOfficial docs
“Claude Code doesn’t restart the background Bash commands and monitors that were running when the session ended.”
↩︎ Checkpoint progress outside the run“A restored recurring task doesn’t fire for the runs it missed while the session wasn’t running.”
↩︎ Checkpoint progress outside the run“A self-paced /loop isn’t restored, so run /loop again to restart it.”
↩︎ Checkpoint - 4.https://code.claude.com/docs/en/checkpointingOfficial docs
“Claude Code saves checkpoints with the conversation, so you can still run /rewind after you resume a session”
↩︎ Checkpoint progress outside the run - 5.https://code.claude.com/docs/en/goalOfficial docs
“A context overflow that auto-compaction couldn’t clear”
↩︎ Checkpoint progress outside the run - 6.https://claude.com/blog/ai-ci-cd-on-callSecondary source
“Every new investigation starts by reading it, so Claude's first hypothesis starts with what has happened recently.”
↩︎ Checkpoint progress outside the run“The key takeaway here is that the alerting process is deterministic, while on-call escalation has both deterministic and agentic paths.”
↩︎ Notification and escalation design“to determine if it can wait until the morning or if the on-call needs a page”
↩︎ Notification and escalation design“Claude produces daily and weekly summaries so one member of the team can pick up where the other left off.”
↩︎ Notification and escalation design