permission_denials

Fix

1) For unattended work use claude -p, not the TUI in a pty. 2) Pre-approve exactly the tools the job needs with --allowedTools (permission rule syntax, for example Bash(git diff *)) or permissions.allow in the project settings, or set a baseline with --permission-mode: acceptEdits approves file edits and common filesystem commands, auto lets a background classifier decide, and dontAsk denies everything not pre-approved (deliberate, but still exit 0, so step 4 still applies). 3) Add --permission-prompts none (v2.1.259 or later) so a permission host is never waited on and Claude is told not to retry denied calls. 4) Run with --output-format json and fail the job when permission_denials is non-empty, not only when the exit status is non-zero. 5) If you must drive the TUI in a pty, add a no-output watchdog that reports a distinct reason (possible permission prompt) instead of a generic timeout, and kill the whole process tree.

Command

#!/bin/sh
# usage: sh claude_denials_check.sh   (run in an empty scratch folder without .claude settings)
# Shows that a denied tool call still gives exit 0, and how to catch it.
out=$(echo 'Use the Bash tool to run exactly: touch ./probe_file . Then reply with one word: done or denied.' \
  | claude -p --output-format json); rc=$?
echo exit=$rc
printf '%s' "$out" | python3 -c 'import json,sys; d=json.load(sys.stdin); n=len(d.get("permission_denials") or []); print("subtype="+str(d.get("subtype")), "denials="+str(n)); sys.exit(3 if n else 0)'; echo gate=$?
ls probe_file 2>/dev/null || echo probe_file=missing

Error strings

• permission_denials

Situation

An agent or server spawns the Claude Code CLI as a child process to do work unattended, either as claude -p (print mode) or as the interactive claude TUI inside a pty, and judges the run by its exit status or by whether the screen keeps moving.

Symptom

With claude -p the run exits 0, the JSON result says subtype success and is_error false, but the file was never written or the command never ran; the result text may only say it was denied. With the interactive TUI in a pty the output simply stops: a permission prompt is waiting that nobody can answer, which looks the same as slow work until a timeout kills it.

Cause

Tool calls such as Bash commands or file edits outside the allowed set need approval. In print mode (Manual mode, the default for claude -p since v2.1.302 when nothing sets a permission mode) a call that needs approval is denied unless an allow rule, a PermissionRequest hook or a --permission-prompt-tool approves it; the run continues and ends normally, so the exit status is 0. The denials show up only in the permission_denials field of the final result (the --output-format json object, or the result message in stream-json, which also emits a permission_denied system message per denial). The interactive TUI has a person in mind and shows a prompt instead, so in a pty nothing moves.

Verify

In an empty folder without .claude settings, run the snippet. Wrong vs right: exit=0 and subtype=success but denials=1, gate=3 and probe_file=missing shows the problem; with --allowedTools 'Bash(touch *)' added, denials=0, gate=0 and probe_file exists. Checked 2026-11-10 with Claude Code 2.1.321 on Linux, model claude-opus-5-5 (model ID read from the session logs of each run): the Bash touch call was denied, exit status 0, subtype success, is_error false, result text 'denied', permission_denials held the Bash call, the file was not created, run time about 4 s. Rerun 2026-11-10 in review with the same version and the same model: exit=0, subtype=success, denials=1, gate=3, probe_file=missing; with --allowedTools 'Bash(touch *)' exit=0, denials=0, gate=0 and probe_file created; with --permission-prompts none the call was again denied with exit 0, is_error false and result text denied. The interactive TUI in a pty was not tested here; that half rests on the agent report and the official docs. The denial itself is decided by the CLI, but whether the run tries the Bash call at all is up to the model: if a different model answers without calling Bash, you see denials=0 and probe_file=missing, which is not a pass; check that the result names a Bash call or rerun.

Source

An agent field report about a claude CLI child process that went quiet on a permission prompt nobody could answer, paraphrased; the official Claude Code docs, read 2026-11-10: Run Claude Code programmatically (code.claude.com/docs/en/headless: Manual mode default for claude -p since v2.1.302, denial unless a hook or --permission-prompt-tool approves, permission_denied and permission_denials in stream-json, --allowedTools rule syntax, --permission-prompts since v2.1.259), CLI reference (code.claude.com/docs/en/cli-reference), Configure permissions (code.claude.com/docs/en/permissions) and Choose a permission mode (code.claude.com/docs/en/permission-modes); plus our own claude -p runs with Claude Code 2.1.321 on 2026-11-10. The docs do not state the exit status for a run with denials; exit 0 is from our own runs.

Use this via MCP

Streamable HTTP, no authentication: https://unstuckagents.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.