[FEATURE] AskUserQuestion Hook Support

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Feature Request: AskUserQuestion Hook Support

Date: 2025-11-27
Target: Anthropic Claude Code Team

Summary

Request native hook support for intercepting and responding to AskUserQuestion tool calls, enabling custom UI integrations for plan mode questions.

Problem Statement

Claude Code's current hook system allows interception of various events (file operations, session lifecycle, notifications), but does not support intercepting or responding to AskUserQuestion tool calls.

Current Limitations

1. No Pre/Post Hooks for AskUserQuestion: Unlike file operation tools (Edit, Write, NotebookEdit) which have PreToolUse/PostToolUse hooks, the AskUserQuestion tool cannot be intercepted effectively
2. No Response Mechanism: Even when detecting questions via PreToolUse, hooks cannot provide answers back to Claude Code
3. CLI Blocking: When AskUserQuestion is called, Claude Code blocks waiting for CLI input with no programmatic way to provide the answer

Impact

This prevents:

• Rich UI integrations (desktop apps, web dashboards) from handling plan mode questions
• Automated workflows that need to answer questions programmatically
• Centralized logging and tracking of all Q&A interactions
• Remote question answering (e.g., mobile app answering questions on behalf of desktop)

Current Workaround

We've implemented a partial workaround using the PreToolUse hook:

# on-tool-use.sh
if [ "$TOOL_NAME" = "AskUserQuestion" ]; then
  QUESTIONS=$(echo "$PAYLOAD" | jq '.tool_input.questions')

  # Send to backend API
  curl -X POST "$BACKEND_URL/api/hooks/question-detected" \
    -H "Authorization: Bearer $AUTH_TOKEN" \
    -d "{\"session_id\": \"$SESSION_ID\", \"questionData\": {\"questions\": $QUESTIONS}}"
fi

This allows:
✅ Detecting when questions are asked
✅ Displaying questions in custom UI (desktop app, web dashboard)
✅ Collecting answers through custom UI
✅ Storing answers in backend database

But still requires:
❌ User to also answer in CLI to unblock Claude Code
❌ Dual entry (answer in UI, then dismiss CLI prompt)
❌ No automated workflows possible

Proposed Solution

Proposed Solution

Add native hook support for AskUserQuestion with a bidirectional flow:

1. PreAskUserQuestion Hook

Trigger: Before AskUserQuestion displays in CLI
Payload: Full question structure with options

{
  "hook_event_name": "PreAskUserQuestion",
  "session_id": "abc-123",
  "task_id": "task-456",
  "questions": [
    {
      "question": "Which approach should we use?",
      "header": "Implementation",
      "multiSelect": false,
      "options": [
        {"label": "Option A", "description": "Use existing pattern"},
        {"label": "Option B", "description": "Create new pattern"}
      ]
    }
  ],
  "timeout": 1800000  // 30 minutes in ms
}

2. Answer Response Mechanism

Option A: Hook Script Return Value
Allow hook script to write answer to stdout:

#!/bin/bash
# Hook can optionally provide answer
echo '{"answers": {"0": "Option A"}}'
exit 0  # Exit code 0 = answer provided, skip CLI prompt
exit 1  # Exit code 1 = no answer, show CLI prompt

Option B: Answer File
Hook writes answer to temporary file:

#!/bin/bash
ANSWER_FILE="/tmp/claude-answer-${SESSION_ID}.json"
echo '{"answers": {"0": "Option A"}}' > "$ANSWER_FILE"
echo "$ANSWER_FILE"  # Print path to answer file

Option C: Polling Endpoint
Claude Code polls a user-defined endpoint for answers:

# In ~/.claude/settings.json
{
  "hooks": {
    "answer_poll_url": "http://localhost:3001/api/claude/poll-answer?session={session_id}",
    "answer_poll_timeout": 30000  // 30 seconds
  }
}

3. PostAskUserQuestion Hook

Trigger: After user answers (either via hook response or CLI)
Payload: Question + Answer

{
  "hook_event_name": "PostAskUserQuestion",
  "session_id": "abc-123",
  "questions": [...],
  "answers": {
    "0": "Option A"
  },
  "answered_via": "hook" | "cli",
  "timestamp": 1732742400000
}

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

Interactive mode (TUI)

Use Case Example

Use Cases

1. Desktop/Web UI Integration

Benefits:

• Better UX with modal dialogs, checkboxes, radio buttons
• Centralized tracking of all questions/answers
• Remote answering capability
• Answer history and suggestions

2. Automated Workflows

Scenario: CI/CD pipeline runs Claude Code with pre-defined answers

Benefits:

• Fully automated plan mode execution
• Consistent decision-making across runs
• No manual intervention required

3. Team Collaboration

Scenario: Junior developer runs Claude Code, senior developer answers questions remotely

Benefits:

• Real-time collaboration
• Expert input on critical decisions
• Training opportunities

4. Answer Templates

Scenario: Organization maintains answer templates for common questions

Benefits:

• Consistent architectural decisions
• Policy enforcement
• Faster onboarding

Additional Context

Implementation Suggestions

Phase 1: Basic Hook Support

• Add PreAskUserQuestion hook event
• Implement simple return value mechanism (Option A)
• Document in Claude Code hooks guide

Phase 2: Advanced Features

• Add timeout support (fallback to CLI if hook doesn't respond)
• Add PostAskUserQuestion hook for logging
• Support multiple answer sources (hook → CLI fallback)

Phase 3: Ecosystem Integration

• Polling endpoint support for remote answer services
• Answer validation in hooks
• Multi-user approval workflows

Backward Compatibility

Proposed changes are fully backward compatible:

• Existing behavior: If no hook provides answer, show CLI prompt (current behavior)
• New behavior: If hook provides answer, skip CLI prompt
• No breaking changes to existing hooks

Security Considerations

1. Answer Validation: Claude Code should validate hook-provided answers match expected format
2. Timeout Enforcement: If hook doesn't respond within timeout, fall back to CLI
3. Audit Trail: Log whether answers came from hook or CLI for debugging
4. Permission Model: Consider adding permission requirements for answer-providing hooks

Alternative Solutions Considered

1. Use Notification Hook with Pattern Matching ❌

Problem: Notifications don't contain structured question data, only generic "Claude Code needs your attention" message

2. Programmatically Send Input to CLI ❌

Problem: No API to send input to Claude Code process, would require OS-level automation (fragile)

3. Modify Claude Code Binary ❌

Problem: Not maintainable, breaks on updates, violates ToS

4. Accept Dual Entry (Current Workaround) ⚠️

Problem: Poor UX, not suitable for automation, defeats purpose of custom UI

---

We believe this feature would unlock significant value for Claude Code users building custom integrations and automated workflows. Happy to provide more details or collaborate on implementation.

P.S. This was generated using Claude Code!