Claude Code 2.1.319: Fix Headless Agent Freezes With denyInsteadOfPrompting

Anthropic's Claude Code 2.1.319 adds a `permissions.denyInsteadOfPrompting` setting that denies any tool call reaching a permission prompt instead of waiting indefinitely for human input, so unattended agents in CI pipelines, cron jobs and multi-agent workflows continue rather than freezing. The setting respects existing allow and deny rules, unlike `--dangerously-skip-permissions`, and sits last in the permission decision chain after deny rules, ask rules, read-only edits and the auto mode classifier run by Claude Sonnet 4.6. The same release adds MCP task backgrounding, moving MCP server tool calls to the background and reporting results on completion, with `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` to revert.

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: 1. Explicit deny rules — block outright; classifier never consulted 2. Explicit ask rules — force a prompt even in auto mode 3. Read-only / working-directory edits — auto-approved except protected paths like .git/ , .claude/ , rc files 4. Auto mode classifier — shell commands and network ops evaluated by Claude Sonnet 4.6 5. 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 https://code.claude.com/docs/en/permissions 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 https://github.com/anthropics/claude-code/releases/tag/v2.1.319 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 https://dev.classmethod.jp/en/articles/20261108-cc-updates-v2-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 https://www.morphllm.com/claude-code-dangerously-skip-permissions 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.