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: 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: 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.

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.