0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code -pを無人実行|権限プロンプト対策4つの使い分け

0
Posted at

Claude Code -pを無人実行|権限プロンプト対策4つの使い分け

この記事でわかること

  • claude -p を cron などで無人実行したとき、権限の確認が必要な操作がどう扱われるか
  • dontAsk / --permission-prompts none / permissions.denyInsteadOfPrompting(v2.1.319 で追加)の違いと使い分け
  • 「終了したのに仕事ができていない」を検知する、結果 JSON の判定スクリプト(コピペ可)

対象読者: Claude Code を -p(非対話)で定期実行している、またはこれから組む人。

要点(TL;DR)

  • claude -p は権限モードを指定しないと Manual モード(設定値は default) で始まり、承認が必要な操作は止まらずに拒否される(公式ドキュメント、v2.1.302 以降)。無人ジョブの失敗は「固まる」より 「拒否されたまま正常終了する」 形で起きる。
  • 無人ジョブの基本形は --permission-mode dontAsk + --allowedTools で必要な操作だけ許可。許可していない操作はすべて自動で拒否される。
  • --permission-prompts none は「この 1 回の実行では誰も答えない」と宣言するフラグ(v2.1.259 以降)。権限モードはそのまま働き、プロンプトに落ちる分だけが拒否される。
  • permissions.denyInsteadOfPrompting: true はその設定版(v2.1.319 以降)。-p だけでなく対話セッションやサブエージェントにも効くので、~/.claude/settings.json に書くと普段の作業でも確認が出なくなる点に注意。ジョブだけに効かせたいなら --settings で渡す。
  • 結果 JSON は subtype ではなく is_error・終了コード・permission_denials を見る。実機で subtype: "success" のまま is_error: true(未ログイン)になる例を確認した。

動作環境 / 前提

項目 値
機種 Mac mini(Apple Silicon / メモリ32GB)
OS macOS 27.2(ビルド 26B123)
Claude Code 2.1.323
Python 3 系(判定スクリプトは標準ライブラリのみ)

この記事の根拠は 3 種類あり、本文でも区別して書く。

種類 内容
公式ドキュメント Permission modes / Headless / Settings reference / CHANGELOG
手元で確認 claude --help(2.1.323)の記載、未ログイン時の結果 JSON、判定スクリプトの動作
未検証 各設定でツール呼び出しが実際に拒否・許可される様子の実測(理由は「つまずきポイント」に書く)

Claude Code は更新が速い。フラグや設定キーは、お使いのバージョンの claude --help と公式ドキュメントで確認してほしい。

無人実行で「確認プロンプト」はどうなるか

対話セッションなら、許可していない Bash コマンドやファイル編集の前に確認が出る。では誰も画面を見ていない -p 実行ではどうなるか。

公式ドキュメント(Permission modes)の説明を要約するとこうなる。

  • v2.1.302 以降、権限モードを指定しない claude -p と Agent SDK の実行は Manual モードで始まる(設定値・SDK 上の名前は default。CLI では manual という別名も使える)。
  • 承認が必要な呼び出しは、allow ルール・フック・canUseTool コールバック・--permission-prompt-tool のいずれかで承認しない限り拒否される。

つまり素の claude -p は、確認待ちで固まるのではなく、拒否して先へ進む。流れを図にするとこうなる。

無人ジョブで問題になるのは 2 か所。

  1. Y に落ちる:必要な操作が拒否されたまま、Claude が「できませんでした」と報告して正常終了する。ログを見ないと気づかない。
  2. W に落ちる:Agent SDK の canUseTool や --permission-prompt-tool のような「権限ホスト」を付けている構成で、ホストが答えないと待ち続ける。

以下の 4 つは、この 2 か所をどう制御するかの違いである。

4つの手段の比較(早見表)

公式ドキュメントと claude --help の記載をもとに整理した。

# 手段 指定方法 効く範囲 プロンプトに落ちる呼び出し 向いている場面
1 何も指定しない claude -p "..." その実行 拒否(Manual モード) 読み取りだけのジョブ
2 dontAsk モード --permission-mode dontAsk + --allowedTools その実行 拒否。ask ルールに一致する呼び出しも拒否 許可リストを固定した CI・定期ジョブ
3 --permission-prompts none -p と併用するフラグ その実行 拒否。Claude に「再試行するな」と伝える 権限ホストあり、または auto モードの無人実行
4 permissions.denyInsteadOfPrompting ユーザー設定 / managed 設定 / --settings -p・対話・サブエージェント・エージェントチームなど 拒否してターン続行 無人で動くマシン全体の既定にしたいとき

補足を 3 点。

  • 2 の dontAsk は権限モードそのもの。3 と 4 はいまの権限モードの上に重ねる指定で、モードの判断(allow ルール、auto モードの分類器など)はそのまま働く。公式も「dontAsk はそれ自体が権限モードで、このキーはいまのモードと一緒に働く」と区別している。
  • 3 について公式は「ホストのない -p 実行では、これらの要求はどちらにせよ拒否される。フラグは加えて Claude に再試行しないよう伝える」と説明している。つまり cron から素の claude -p を呼ぶだけなら、3 の効果は**「拒否される」ことではなく「無駄な再試行をさせない」「AskUserQuestion のような人に聞くツールを外す」**ところにある。
  • --dangerously-skip-permissions(bypassPermissions)は確認をすべて飛ばす手段で、claude --help 自身が「インターネットに出られないサンドボックスでのみ推奨」と書いている。普段使いの Mac で動かす定期ジョブの選択肢からは外した。

手段2: dontAsk + allowedTools(基本形)

公式の説明では、dontAsk モードは本来プロンプトが出る呼び出しをすべて自動で拒否する。一方で次のものは動く。

  • Manual モードでも承認不要なもの(作業ディレクトリ内のファイル読み取り、読み取り専用の Bash コマンド)
  • permissions.allow ルールに一致するもの
  • PreToolUse フックが承認したもの

公式ドキュメントの例はこの形。

claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"

「このジョブがやってよいこと」を --allowedTools に書き切り、それ以外は一律で拒否させる。許可リスト方式なので、プロンプトの書き方や入力データに引きずられて想定外のコマンドが走る余地が小さい。

手段3: --permission-prompts none

手元の claude --help(2.1.323)にはこう出る(文言はそのまま、改行位置だけ整えた)。

--permission-prompts <target>  Who answers permission prompts with --print:
                               "host" (the SDK host or --permission-prompt-tool)
                               or "none" (nobody: anything that would prompt is
                               denied automatically; the permission mode still
                               decides everything else)
                               (choices: "host", "none", default: "host")

公式ドキュメントの例は auto モードとの組み合わせ。

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

公式の説明では、分類器はいつもどおり 1 件ずつ操作を審査し、そのうえで確認プロンプトに落ちるはずだった分を Claude Code が拒否する。v2.1.259 以降が必要で、それより古いと unknown option エラーになる(公式記載)。

手段4: permissions.denyInsteadOfPrompting(v2.1.319〜)

CHANGELOG の 2.1.319 に「権限プロンプトを待つはずのツール呼び出しを拒否してターンを続ける設定」として追加された。公式のサンプルは次のとおり。

{
  "permissions": {
    "defaultMode": "auto",
    "denyInsteadOfPrompting": true
  }
}

Settings reference から、押さえておく性質を拾う。

性質 内容
置ける場所 ユーザー設定(~/.claude/settings.json)・managed 設定・--settings。リポジトリ側の設定からは有効にできない
効く範囲 -p 実行、対話ターミナル、VS Code 拡張、Desktop アプリのローカルセッション、サブエージェント、エージェントチーム
一緒に止まるもの AskUserQuestion・EnterPlanMode・ExitPlanMode が外れる。MCP の elicitation は Elicitation フックが答えない限りキャンセル。canUseTool や --permission-prompt-tool にも問い合わせない
false の意味 未設定と同じ。別の設定元が true なら拒否のまま

ここで注意したいのが効く範囲の広さ。~/.claude/settings.json に書くと、自分が普段使う対話セッションでも確認が出なくなり、黙って拒否される。定期ジョブのためだけなら、ジョブ側で渡すほうが影響が閉じる。

claude -p "$(cat prompt.md)" \
  --permission-mode dontAsk \
  --allowedTools "Read" "Bash(git log *)" \
  --settings '{"permissions":{"denyInsteadOfPrompting":true}}'

この 1 回きりなら、同じ目的は --permission-prompts none でも足りる(公式も「フラグは 1 回の実行だけ、以後の実行にも効かせるなら設定」と使い分けを書いている)。

結果JSONで「拒否されたまま成功」を検知する

無人ジョブで一番困るのは、拒否された操作があってもプロセスが普通に終わること。--output-format json の結果には permission_denials という配列があり、拒否された呼び出しが入る(Agent SDK の型定義では各要素が tool_name / tool_use_id / tool_input を持つ)。これをジョブの後段で機械的に見る。

#!/usr/bin/env python3
"""jobcheck.py : claude -p --output-format json の結果を判定する(無人ジョブの後段に置く)

使い方:
    claude -p "..." --output-format json > result.json; echo $? > result.exit
    python3 jobcheck.py result.json "$(cat result.exit)"

終了コード: 0=OK / 1=WARN(権限で拒否された操作あり) / 2=FAIL(実行自体が失敗)
"""
import json
import sys


def judge(data: dict, exit_code: int) -> tuple[str, list[str]]:
    reasons = []
    # FAIL: subtype は見ない。"success" のまま is_error が true になる例がある
    if exit_code != 0:
        reasons.append(f"exit={exit_code}")
    if data.get("is_error"):
        reasons.append(f"is_error=true terminal_reason={data.get('terminal_reason')}")
    if not data:
        reasons.append("結果JSONが空または壊れている")
    if reasons:
        return "FAIL", reasons

    # WARN: 走り切ったが、権限で拒否された操作がある(=頼んだ仕事が一部できていない可能性)
    denials = data.get("permission_denials") or []
    if denials:
        tools = sorted({d.get("tool_name", "?") for d in denials})
        return "WARN", [f"permission_denials={len(denials)}件 tools={','.join(tools)}"]
    return "OK", []


def main() -> int:
    if len(sys.argv) < 2:
        print(__doc__)
        return 2
    try:
        with open(sys.argv[1], encoding="utf-8") as f:
            data = json.load(f)
    except (OSError, json.JSONDecodeError):
        data = {}
    exit_code = int(sys.argv[2]) if len(sys.argv) > 2 else 0
    verdict, reasons = judge(data, exit_code)
    summary = (data.get("result") or "").strip().replace("\n", " ")[:60]
    print(f"{verdict}: {'; '.join(reasons) or '問題なし'} | result={summary!r}")
    return {"OK": 0, "WARN": 1, "FAIL": 2}[verdict]


if __name__ == "__main__":
    sys.exit(main())

手元で 4 種類の入力に通した結果がこれ。1 行目だけが実機の結果 JSON、残りは判定ロジック確認用の合成データである。

入力 中身 出力 終了コード
実機の JSON(未ログイン) is_error: true、permission_denials: [] FAIL: exit=1; is_error=true terminal_reason=api_error 2
合成: 正常 is_error: false、拒否なし OK: 問題なし 0
合成: 拒否あり permission_denials に Bash が 1 件 WARN: permission_denials=1件 tools=Bash 1
合成: 空ファイル 0 バイト FAIL: 結果JSONが空または壊れている 2

合成データの「拒否あり」はこの 1 行で再現できる。

cat > synth_denied.json <<'EOF'
{"type":"result","subtype":"success","is_error":false,"num_turns":2,"result":"DENIED","permission_denials":[{"tool_name":"Bash","tool_use_id":"toolu_synthetic_0001","tool_input":{"command":"touch marker.txt"}}]}
EOF
python3 jobcheck.py synth_denied.json 0; echo "終了コード=$?"

つまずきポイント

subtype: "success" なのに失敗している(Not logged in · Please run /login)

今回いちばんの収穫。各設定の挙動を実測しようと、定期ジョブとして動いている Claude Code のセッションの中から、さらに claude -p を起動したところ、返ってきた結果 JSON はこうだった(抜粋。ID 類は省略)。

{
  "type": "result",
  "subtype": "success",
  "is_error": true,
  "terminal_reason": "api_error",
  "result": "Not logged in · Please run /login",
  "num_turns": 1,
  "total_cost_usd": 0,
  "duration_ms": 110,
  "permission_denials": []
}

プロセスの終了コードは 1 だった。subtype だけを見て成否を判定していると、これを成功として扱ってしまう。is_error と終了コードを見るのが安全で、上の jobcheck.py が subtype を見ていないのはこのため。

なお、入れ子で起動したセッションだけが未ログイン扱いになった原因は特定していない(未検証)。認証を回避するような細工はせず、そこで実測を打ち切った。

各設定の実測は未検証

上の理由で、「同じ依頼を 4 通りの設定で投げて、ファイルができたか・permission_denials が何件か」を並べる実測表は作れていない。比較表は公式ドキュメントと --help の記載に基づくもので、手元の実測ではない。検証用に書いたスクリプトの骨子は次のとおりで、ログイン済みの端末で使い捨てフォルダを作って回せば表になる想定(1 ケース目が認証エラーで終わるところまでしか動かしていない)。

import json, pathlib, subprocess

PROMPT = ("Run exactly this one Bash command and nothing else: touch {m} . "
          "Then reply DONE or DENIED. Do not try alternatives.")
DENY = json.dumps({"permissions": {"denyInsteadOfPrompting": True}})
CASES = [
    ("default", []),
    ("dontask", ["--permission-mode", "dontAsk"]),
    ("dontask_allow", ["--permission-mode", "dontAsk", "--allowedTools", "Bash(touch *)"]),
    ("prompts_none", ["--permission-prompts", "none"]),
    ("deny_setting", ["--settings", DENY]),
]
for name, extra in CASES:
    m = f"marker_{name}.txt"
    p = subprocess.run(
        ["claude", "-p", PROMPT.format(m=m), "--model", "haiku",
         "--setting-sources", "project",      # 自分のユーザー設定の許可ルールを混ぜない
         "--output-format", "json", "--no-session-persistence", *extra],
        capture_output=True, text=True, timeout=300)
    d = json.loads(p.stdout or "{}")
    print(name, "exit=", p.returncode, "created=", pathlib.Path(m).exists(),
          "denials=", len(d.get("permission_denials") or []), "is_error=", d.get("is_error"))

--setting-sources project を付けているのは、~/.claude/settings.json に既に書いてある allow ルールが混ざると、どの設定の効果か分からなくなるため。

denyInsteadOfPrompting を書いたら対話セッションでも確認が出ない

仕様どおりの挙動(対話ターミナルにも効く)。「最近 Claude が確認せずに諦める」と感じたら、~/.claude/settings.json にこのキーが残っていないかを見る。ジョブ専用なら --settings か --permission-prompts none に寄せる。

リポジトリの .claude/settings.json に書いても効かない

denyInsteadOfPrompting のスコープは「ユーザーまたは managed、および --settings」で、公式に「リポジトリからは設定できない」と明記されている。プロジェクト設定に書いて効かないのは不具合ではない。

rm -rf 系は allow ルールでも通らないものがある

dontAsk モードでは、rm -rf / や rm -rf ~ のような「重要パスの削除」と、ネットワークパスからの読み取りは、allow ルールや PreToolUse フックでも承認できないと公式にある。無人ジョブに削除をさせる設計は、そもそも避けたほうがよい。

まとめ

  • claude -p の無人実行では、承認が必要な操作は待たずに拒否される(v2.1.302 以降は既定で Manual モード)。怖いのは「固まる」より「できていないのに終わる」こと。
  • 基本形は --permission-mode dontAsk + --allowedTools の許可リスト方式。
  • --permission-prompts none は 1 回の実行用、permissions.denyInsteadOfPrompting(v2.1.319〜)は以後ずっと効く設定版。後者は対話セッションにも効くので、置き場所に注意する。
  • 成否は 終了コード・is_error・permission_denials で判定する。subtype: "success" は当てにならない場面があった(実機で確認)。
  • 未検証:4 つの設定それぞれでの拒否・許可の実測、入れ子起動で未ログインになった原因、auto モードと none を組み合わせたときの実際の拒否件数。比較表は公式ドキュメントに基づく整理である。

早見表:無人ジョブを登録する前の 5 項目

# 確認 具体策
1 やってよい操作を書き切ったか --permission-mode dontAsk + --allowedTools
2 誰も答えないことを伝えたか --permission-prompts none(v2.1.259〜)
3 設定の影響範囲は閉じているか denyInsteadOfPrompting は --settings で渡す
4 結果を機械的に判定しているか --output-format json → jobcheck.py
5 バージョンは足りているか claude --version(denyInsteadOfPrompting は 2.1.319〜)

次に読む / 続編(CTA)

同じ Mac mini で Claude Code を定期実行する話の関連記事です。

次は、今回未検証として残した「4 つの設定の実測表」をログイン済みの端末で取り直して書く予定です。早見表と jobcheck.py は定期ジョブを組むときにそのまま使えると思うので、ストックしておくと役立つはずです。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?