Summoning the User

Overview

Help Claude and subagents identify when to block and request user input rather than proceeding with assumptions or guesses.

Core principle: When uncertain, assess the risk. High-risk decisions require summoning the user. Low-risk decisions can proceed with reasonable defaults.

Announce at start: "I'm using the summoning-the-user skill to determine if I need your input before proceeding."

When to Use This Skill

Use this skill when:

• You encounter a blocking decision mid-execution
• Proceeding without user input could lead to wasted work or incorrect implementation

Special note for subagents: If you're running in the background, default to summoning for anything uncertain. The user isn't watching, so making wrong assumptions wastes their time.

Decision Framework: Should I Summon?

SUMMON (High Risk - Block and Wait)

You MUST summon the user when:

• Multiple valid implementation paths exist, no clear "right" answer
• Decision affects security, data integrity, or user privacy
• Requirements are ambiguous or contradictory
• You're about to make an assumption that could waste significant work if wrong
• The choice has architectural implications (hard to change later)
• You don't have enough context about user's actual needs

PROCEED (Low Risk - Make Reasonable Choice)

You can proceed without summoning when:

• One clear best practice or standard approach exists
• It's a minor implementation detail (variable name, code style)
• Decision is easily reversible
• You're following established patterns in the codebase
• User has already provided sufficient context

How to Summon Effectively

When you've determined summoning is needed, follow this process:

1. Send External Notification

First time: Ask user which notification method they prefer.

Check user preference, then use one of:

Option A: terminal-notifier (macOS - requires installation)

# Check if installed
which terminal-notifier

# If not installed, install via Homebrew
brew install terminal-notifier

# Get terminal bundle ID
case "$TERM_PROGRAM" in
  "iTerm.app") BUNDLE_ID="com.googlecode.iterm2" ;;
  "Apple_Terminal") BUNDLE_ID="com.apple.Terminal" ;;
  "WezTerm") BUNDLE_ID="com.github.wez.wezterm" ;;
  "Ghostty") BUNDLE_ID="com.mitchellh.ghostty" ;;
  "Warp") BUNDLE_ID="dev.warp.Warp-Stable" ;;
  *) BUNDLE_ID="com.apple.Terminal" ;;
esac

# Send notification that activates terminal on click
terminal-notifier -message "🤖 Claude needs your input" -title "Claude Code" -activate "$BUNDLE_ID"

Notes:

• Requires terminal-notifier (install via brew install terminal-notifier)
• Clicking notification focuses the terminal application
• Auto-detects terminal type via $TERM_PROGRAM
• Works with iTerm2, Terminal.app, Ghostty, WezTerm, Warp

Option B: OSA Script (macOS - no installation, basic)

TERMINAL_APP="${TERM_PROGRAM:-Terminal}"
osascript -e 'display notification "🤖 Claude needs your input" with title "Claude Code"' && \
osascript -e "tell application \"$TERMINAL_APP\" to activate"

Notes:

• No installation required but less reliable
• Activates terminal immediately (not on click)
• May open Script Editor on notification click
• Consider using terminal-notifier or Slack CLI instead

Option C: Slack CLI

• Check if installed: slack version
• If not installed: Follow https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux
• Send notification: slack chat send --channel @username --text "Claude needs your input"

2. Use AskUserQuestion Tool

• Creates UI prompt that demands attention
• Provides structured options (prevents vague responses)
• Forces explicit choice before proceeding

3. Be Explicit About Blocking

• State clearly: "I need your input before proceeding"
• Explain WHY you're blocked (what decision/ambiguity you're facing)
• Don't hide the question in lots of other text

4. Provide Context

• Briefly explain what you were doing when you got blocked
• State what information you need
• Explain the consequences of different choices if relevant

Example

I'm blocked and need your input.

I was implementing the user authentication system and encountered
an ambiguity: should failed login attempts be logged with the
username included (better for security auditing but potential
privacy concern) or without (more private but harder to trace
attack patterns)?

[Sends OSA notification or Slack message]
[Uses AskUserQuestion with structured options]

Key Principles

| Principle | Application | |-----------|-------------| | Assess risk first | Use the decision framework before acting | | Default to summoning when uncertain | Especially for background agents | | Always send external notification | User may not be watching terminal | | Use AskUserQuestion tool | Structured choices get better responses | | Be explicit about blocking | Don't hide that you're waiting | | Provide context | Help user understand why you need input |

Anti-Patterns

DON'T:

• Summon for trivial decisions you can make yourself
• Proceed with high-risk assumptions to "save time"
• Ask questions without sending external notification
• Hide questions in verbose output
• Make the user guess what you need

DO:

• Assess risk using the framework
• Send notification before asking
• Be clear and concise about what you need
• Use structured questions (AskUserQuestion)
• Explain the stakes of the decision