DEV Community

AgentKoji
AgentKoji

Posted on Originally published at agentkoji.com

UserPromptSubmitの使い方（Claude Code hooks）

#ai #devtools #productivity #claudecode

UserPromptSubmit は、プロンプトを送ったとき Claude が処理する前に動く hook です。プロンプトに文脈を足したり、Claude に届く前に止めたりできます。ここでは「文脈を足す hook」と「API キーらしき文字列を止める hook」の要点をまとめます（Claude Code 2.1.309、2026年10月23日時点。スクリプトにダミー JSON を流して確認）。

いつ動くか

自分で打ったときだけでなく、次のときにも動きます。

  • 予約タスクが動いたとき（/loop を含む）
  • バックグラウンドのサブエージェントが結果を返したとき
  • 別のセッションからメッセージが届いたとき

入力 JSON には prompt が入ります。/deploy staging のようなコマンドは、展開前の1行のまま届きます。

例1：文脈を足す

exit 0 で stdout に出した文（または JSON の additionalContext）が Claude の文脈に足されます。

#!/usr/bin/env bash
# .claude/hooks/prompt-context.sh  (UserPromptSubmit)
cd "${CLAUDE_PROJECT_DIR:?}" || exit 0
branch=$(git branch --show-current 2>/dev/null)
changed=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
echo "Current branch: ${branch:-unknown}. Uncommitted files: ${changed}. Today: $(date +%F)."
exit 0
Enter fullscreen mode Exit fullscreen mode

実行は 0.03〜0.04 秒でした。この1行は毎プロンプト足されるので、たいていのターンで要るものだけにします。

例2：API キーらしき文字列を止める 

#!/usr/bin/env bash
# .claude/hooks/block-secrets-in-prompt.sh  (UserPromptSubmit)
prompt=$(jq -r '.prompt // ""')
if printf '%s' "$prompt" | grep -Eq 'sk-ant-[A-Za-z0-9_-]{10,}|AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}'; then
  jq -n '{decision: "block",
          reason: "プロンプトに API キーらしき文字列があります。消してから、環境変数で渡してください。",
          hookSpecificOutput: {hookEventName: "UserPromptSubmit", suppressOriginalPrompt: true}}'
fi
exit 0
Enter fullscreen mode Exit fullscreen mode

reason は人にだけ見え、Claude には届きません。suppressOriginalPrompt: true で、止めたときのメッセージから元の文を省けます。

ただし、鍵がディスクに残らなくなるわけではありません。 公式によると、送った文はセッションの記録など手元のファイルに残ることがあります。防げるのは鍵がモデルに届くことです。貼ってしまった鍵は作り直します。

settings.json と注意点

UserPromptSubmit は matcher 非対応なので matcher は書きません。

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/prompt-context.sh" },
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-secrets-in-prompt.sh" }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode
  • 既定のタイムアウトは30秒（多くのイベントの600秒より短い）
  • タイムアウトすると出力は捨てられ、プロンプトはそのまま届く。止めたいなら "onFailure": "block"
  • 特定の skill やコマンドだけに反応させるなら UserPromptExpansion
  • exit 2 と stderr でも止められる

出典：https://code.claude.com/docs/en/hooks （2026-10-23確認）

返し方の一覧表や関連する hook の記事は、元記事にあります。

👉 全文：https://agentkoji.com/ja/articles/claude-code-userpromptsubmit/

Top comments (0)