TL;DR Before you leave Claude Code working on its own, launch it with
claude --settings '{"permissions":{"denyInsteadOfPrompting":true}}'and put what it does need inpermissions.allow. Anything that would prompt is denied, Claude tells you what was left out, and it carries on with the rest.
A background subagent that reaches a tool call needing permission doesn't settle it on its own: the prompt surfaces in your main session and the subagent waits for your answer. Agent team teammates do the same, with the prompt landing in the lead session. If you've walked away, the whole task sits there. Since v2.1.319, permissions.denyInsteadOfPrompting turns each of those prompts into a denial, and the turn keeps going.
What you see without the setting
A session in Manual mode, a background subagent, and a command that isn't in your rules. v2.1.325 shows this in the main session:
● Agent(Run touch and date command)
⎿ Backgrounded agent (↓ to manage · ctrl+o to expand)
● The subagent is running in the background and is creating made-by-subagent.txt.
✻ Waiting for 1 background agent to finish
Bash command · from the general-purpose agent
touch made-by-subagent.txt && date > made-by-subagent.txt
Do you want to proceed?
❯ 1. Yes
2. Yes, and don't ask again for touch made-by-subagent.txt and date commands in …
3. Yes, and switch to auto mode · auto mode handles these prompts for you
4. No
The prompt names the subagent asking, as the tip on the tools subagents lose in the background covers. What it doesn't do is resolve itself: twenty minutes later it was still on screen, with the subagent stopped and the file never created.
What you see with the setting
The same request, in a session launched with the setting:
● Agent "Run touch and date command" finished · 3s
● The subagent's run failed. The permission system denied its Bash call, so
made-by-subagent.txt was never created. The command needed approval, the
subagent's session couldn't answer a permission prompt, and it didn't retry.
Three seconds. The subagent gets this denial, which forbids a retry and tells it to carry on with whatever needs no approval:
Permission for this tool use was denied. It requires approval, and this session has no approval surface — nobody can answer a permission prompt here — so it was denied automatically. The action was NOT performed; do not claim it succeeded, and do not retry it: this action, and anything else that requires approval, will be denied the same way for the rest of this session. Tell the user what was blocked and why you needed it, then continue with the parts of the task that do not require approval. What required approval: This Bash command contains multiple operations. The following parts require approval: touch made-by-subagent.txt, date
How to turn it on
1. Only for the session you'll leave alone
claude --settings '{"permissions":{"denyInsteadOfPrompting":true}}'
The setting doesn't care who's asking: with it on, your main session stops asking you too. A touch requested directly in that session ended in Not run · permission denied. That's why it pays to launch it this way, for the long task, rather than keep it on all the time.
2. Or for good, in your user settings
In ~/.claude/settings.json:
{
"permissions": {
"denyInsteadOfPrompting": true
}
}
Mind that it only goes one way: a false in --settings won't turn it off for one session, because a single source saying true is enough. Put it here and your main session won't ask you anything again until you edit the file.
It only counts there, in managed settings, or through --settings. A repository can't turn it on for you: with the same block in the project's .claude/settings.json, the touch brought back the usual prompt.
3. Pre-approve what it does need
An allow rule beats the denial. With "allow": ["Bash(touch *)"] next to the setting and a bare touch made-by-subagent.txt as the command, the subagent created the file without asking and permission_denials came back empty. In a chained command every part has to be allowed: with the && date > from above, that rule alone isn't enough. List what the task needs and let the setting absorb the rest. In auto mode, the classifier still approves what it judges safe, and only what would fall back to a prompt is denied.
4. Check what was denied
In an interactive session, Claude sums it up at the end, because the denial itself tells it to. In claude -p with --output-format stream-json --verbose, each one arrives as an event and the final result lists them in permission_denials:
"subtype": "permission_denied", "tool_name": "Bash", "agent_id": "a15becbcafa4ea09e",
"decision_reason": "no approval surface in this session; permission request denied automatically"
The agent_id tells you which subagent it was. It's the same array that lets a claude -p job exit green without doing anything: read it in your script.
What else stops asking
AskUserQuestion,EnterPlanModeandExitPlanModego away, so a session in plan mode can't leave it on its own. A teammate keeps the two plan mode tools.- An MCP elicitation request is cancelled, unless an
Elicitationhook answers it. - Your
--permission-prompt-tooland the Agent SDK'scanUseToolaren't consulted. To approve from code, use aPermissionRequesthook, though some calls are denied before they reach it, such as removing a critical path in auto mode. - Where auto mode's classifier billing notice would open a dialog, it doesn't show, and the actions that need it are denied.
- In auto mode, 20 refused calls in a row end the turn:
20 actions were refused and no work went ahead in between, so Claude stopped.In a subagent, the v2.1.325 binary words it differently:so this agent was stopped before it finished. Nobody interrupted it; whatever it returned is partial.
Two things still wait: the folder trust dialog and the approval of the project's MCP servers. Answer both before you leave.
Against the other options
| Option | What it does with a call that would prompt | Where it falls short |
|---|---|---|
denyInsteadOfPrompting |
Denies it in any mode, for the session, subagents and teammates | Your own session doesn't ask you either |
dontAsk mode |
Denies it, but replaces your mode | A subagent with permissionMode: default prompts again, and a teammate of a dontAsk lead starts in Manual |
--permission-prompts none |
Denies it in one claude -p run |
That run only, headless only |
allow rules |
Approve it | Anything you didn't list still prompts |
That's the difference from the permission modes: the setting adds to whatever mode you're in, auto, acceptEdits or Manual, instead of replacing it. And where it shows most is in an agent team, where every teammate prompt climbs to the lead.
Official docs: Settings reference: permissions.denyInsteadOfPrompting
Requirements
Claude Code v2.1.319 or later. Tested on v2.1.325 on Linux: the background subagent's prompt, the denial with the setting in the session and in the subagent, the allow rule that lets a call through, the setting ignored in project settings, and the stream-json events. Agent teams, plan mode, elicitation and the auto mode cap come from the docs.