Claude Code 2.1.319 ships with a setting that developers running automated agents have needed since day one: permissions.denyInsteadOfPrompting. When enabled, any tool call that would wait on a human at a permission prompt gets denied instead — and the agent keeps moving. No more headless runs that freeze silently at 2 AM with nothing to show for it.
The Freeze Problem
If you have ever run Claude Code with -p (non-interactive mode) in a CI pipeline, cron job, or multi-agent workflow, you may have hit this: the agent reaches a tool call outside its allowlist, and nothing happens. The process does not error. It does not time out. It just waits — indefinitely — for a human to click “Allow” that never comes.
This is not a bug. It is the designed behavior of the permission system. But in unattended contexts, it means your 2 AM refactoring agent is probably frozen at step three, looking completely “running” in your process list while doing absolutely nothing.
The Fix: One Setting
Add this to ~/.claude/settings.json (user-wide) or .claude/settings.json (project-level):
{
"permissions": {
"denyInsteadOfPrompting": true
}
}Any tool call that reaches the permission prompt stage now gets an immediate denial, and the agent continues with the rest of its plan. The run that used to freeze now finishes — in a defined direction. You can also pass it at invocation time with --settings. The setting applies across terminal sessions, subagents, and teammates.
This Is Not –dangerously-skip-permissions
It is worth being precise here, because confusing these two has real security implications. --dangerously-skip-permissions bypasses all checks — the agent can do anything it wants, no prompts, no blocks. It exists for isolated environments (containers, sandboxes) where you have already constrained the agent at the infrastructure level. denyInsteadOfPrompting works differently: it sits on top of your existing rules, fires only for calls that would otherwise pause for human input, and leaves your allow and deny lists fully intact.
denyInsteadOfPrompting | --dangerously-skip-permissions | |
|---|---|---|
| Respects allow/deny rules | Yes | No |
| Behavior at prompt | Deny and continue | Allow everything |
| Safe for production | Yes | No |
| Use case | Unattended pipelines, cron jobs | Isolated containers only |
Where It Falls in the Decision Chain
Claude Code resolves permissions in a fixed order. Understanding this order is key to using denyInsteadOfPrompting correctly:
- Explicit deny rules — block outright; classifier never consulted
- Explicit ask rules — force a prompt even in auto mode
- Read-only / working-directory edits — auto-approved (except protected paths like
.git/,.claude/, rc files) - Auto mode classifier — shell commands and network ops evaluated by Claude Sonnet 4.6
denyInsteadOfPrompting— catches whatever reaches the prompt stage
If your allow list is well-configured, this setting rarely fires. Add it alongside a thoughtful allow list and you get predictable behavior without opening up attack surface. The official permissions docs cover the full rule syntax for building that list.
Also in 2.1.319: MCP Task Backgrounding
The same release ships MCP task backgrounding: when an MCP server runs a tool call as a task, Claude Code now moves it to the background immediately and reports the result when it finishes. Previously, a slow database query or long build check would block the entire conversation turn. See the full release notes for the env vars to control this behavior (CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND to revert).
The Gotcha to Watch For
If denyInsteadOfPrompting fires frequently in your automation, that is a signal — your allow list has gaps. The agent is silently skipping operations rather than completing them. The setting prevents hangs; it does not make missing permissions invisible. Monitor your logs for denial events and use them to close the gaps in your allow rules over time.
A solid reference for building the right permission config is the Dev Classmethod breakdown of v2.1.318–2.1.319, which covers the interaction between denyInsteadOfPrompting and the auto mode changes in the same release. For a broader comparison of headless permission strategies, this MorphLLM guide is worth reading alongside.
Bottom Line
If you are running any kind of automated, unattended, or background Claude Code session and you have not set denyInsteadOfPrompting: true, there is a good chance some of those sessions have been silently hanging. Update to 2.1.319, add the setting, and pair it with an explicit allow list. This is what production agent automation looks like.
