Gestire approvazioni e input dell'utente

Presenta le richieste di approvazione e le domande di chiarimento di Claude agli utenti, quindi restituisci le loro decisioni all'SDK.

Durante il lavoro su un'attività, Claude a volte ha bisogno di verificare con gli utenti. Potrebbe aver bisogno di autorizzazione prima di eliminare file, oppure potrebbe aver bisogno di chiedere quale database utilizzare per un nuovo progetto. La tua applicazione deve presentare queste richieste agli utenti in modo che Claude possa continuare con il loro input.

Claude richiede input dell'utente in due situazioni: quando ha bisogno di autorizzazione per utilizzare uno strumento (come eliminare file o eseguire comandi), e quando ha domande di chiarimento (tramite lo strumento AskUserQuestion). Entrambi attivano il tuo callback canUseTool, che mette in pausa l'esecuzione fino a quando non restituisci una risposta. Questo è diverso dai normali turni di conversazione in cui Claude finisce e attende il tuo prossimo messaggio.

Per le domande di chiarimento, Claude genera le domande e le opzioni. Il tuo ruolo è presentarle agli utenti e restituire le loro selezioni. Non puoi aggiungere le tue domande a questo flusso; se hai bisogno di chiedere qualcosa agli utenti tu stesso, fallo separatamente nella logica dell'applicazione.

Il callback può rimanere in sospeso indefinitamente. L'esecuzione rimane in pausa fino a quando il callback non restituisce, e l'SDK annulla l'attesa solo quando la query stessa viene annullata. Se un utente potrebbe impiegare più tempo per rispondere di quanto il tuo processo possa ragionevolmente rimanere in esecuzione, restituisci la decisione defer hook, che consente al processo di uscire e riprendere in seguito dalla sessione persistente.

Questa guida ti mostra come rilevare ogni tipo di richiesta e rispondere in modo appropriato.

Rilevare quando Claude ha bisogno di input

Passa un callback canUseTool nelle opzioni della query. Il callback si attiva ogni volta che Claude ha bisogno di input dell'utente, ricevendo il nome dello strumento e l'input come argomenti:

async def handle_tool_request(tool_name, input_data, context):
# Chiedi all'utente e restituisci allow o deny
...


options = ClaudeAgentOptions(can_use_tool=handle_tool_request)

async function handleToolRequest(toolName, input, options) {
// options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }
// Chiedi all'utente e restituisci allow o deny
}

const options = { canUseTool: handleToolRequest };

Il callback si attiva in due casi:

1. Lo strumento ha bisogno di approvazione: Claude vuole utilizzare uno strumento che non è approvato automaticamente dalle regole di autorizzazione o dalle modalità. Controlla tool_name per lo strumento (ad es. "Bash", "Write").
2. Claude pone una domanda: Claude chiama lo strumento AskUserQuestion. Controlla se tool_name == "AskUserQuestion" per gestirlo diversamente. Se specifichi un array tools, includi AskUserQuestion affinché funzioni. Vedi Gestire domande di chiarimento per i dettagli.

Gestire le richieste di approvazione dello strumento

Una volta passato un callback canUseTool nelle opzioni della query, si attiva quando Claude vuole utilizzare uno strumento che non è approvato automaticamente. Il tuo callback riceve tre argomenti:

L'oggetto input contiene parametri specifici dello strumento. Esempi comuni:

Vedi il riferimento SDK per gli schemi di input completi: Python | TypeScript.

Puoi visualizzare queste informazioni all'utente in modo che possa decidere se consentire o rifiutare l'azione, quindi restituire la risposta appropriata.

L'esempio seguente chiede a Claude di creare ed eliminare un file di test. Quando Claude tenta ogni operazione, il callback stampa la richiesta dello strumento nel terminale e chiede l'approvazione s/n.

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from claude_agent_sdk.types import (
HookMatcher,
PermissionResultAllow,
PermissionResultDeny,
ToolPermissionContext,
)


async def can_use_tool(
tool_name: str, input_data: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
# Visualizza la richiesta dello strumento
print(f"\nTool: {tool_name}")
if tool_name == "Bash":
print(f"Command: {input_data.get('command')}")
if input_data.get("description"):
print(f"Description: {input_data.get('description')}")
else:
print(f"Input: {input_data}")

# Ottieni l'approvazione dell'utente
response = input("Allow this action? (y/n): ")

# Restituisci allow o deny in base alla risposta dell'utente
if response.lower() == "y":
# Allow: lo strumento viene eseguito con l'input originale (o modificato)
return PermissionResultAllow(updated_input=input_data)
else:
# Deny: lo strumento non viene eseguito, Claude vede il messaggio
return PermissionResultDeny(message="User denied this action")


# Workaround richiesto: dummy hook mantiene il flusso aperto per can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
return {"continue_": True}


async def prompt_stream():
yield {
"type": "user",
"message": {
"role": "user",
"content": "Create a test file in /tmp and then delete it",
},
}


async def main():
async for message in query(
prompt=prompt_stream(),
options=ClaudeAgentOptions(
can_use_tool=can_use_tool,
hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";
import * as readline from "readline";

// Helper per chiedere all'utente l'input nel terminale
function prompt(question: string): Promise<string> {
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});
return new Promise((resolve) =>
rl.question(question, (answer) => {
rl.close();
resolve(answer);
})
);
}

for await (const message of query({
prompt: "Create a test file in /tmp and then delete it",
options: {
canUseTool: async (toolName, input) => {
// Visualizza la richiesta dello strumento
console.log(`\nTool: ${toolName}`);
if (toolName === "Bash") {
console.log(`Command: ${input.command}`);
if (input.description) console.log(`Description: ${input.description}`);
} else {
console.log(`Input: ${JSON.stringify(input, null, 2)}`);
}

// Ottieni l'approvazione dell'utente
const response = await prompt("Allow this action? (y/n): ");

// Restituisci allow o deny in base alla risposta dell'utente
if (response.toLowerCase() === "y") {
// Allow: lo strumento viene eseguito con l'input originale (o modificato)
return { behavior: "allow", updatedInput: input };
} else {
// Deny: lo strumento non viene eseguito, Claude vede il messaggio
return { behavior: "deny", message: "User denied this action" };
}
}
}
})) {
if ("result" in message) console.log(message.result);
}

Questo esempio utilizza un flusso s/n in cui qualsiasi input diverso da y viene trattato come un rifiuto. In pratica, potresti creare un'interfaccia utente più ricca che consenta agli utenti di modificare la richiesta, fornire feedback o reindirizzare completamente Claude. Vedi Rispondere alle richieste dello strumento per tutti i modi in cui puoi rispondere.

Rispondere alle richieste dello strumento

Il tuo callback restituisce uno di due tipi di risposta:

Quando consenti, passa l'input dello strumento (originale o modificato). Quando neghi, fornisci un messaggio che spiega il motivo. Claude vede questo messaggio e potrebbe adattare il suo approccio.

from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

# Consenti l'esecuzione dello strumento
return PermissionResultAllow(updated_input=input_data)

# Blocca lo strumento
return PermissionResultDeny(message="User rejected this action")

// Consenti l'esecuzione dello strumento
return { behavior: "allow", updatedInput: input };

// Blocca lo strumento
return { behavior: "deny", message: "User rejected this action" };

Oltre a consentire o negare, puoi modificare l'input dello strumento o fornire contesto che aiuta Claude ad adattare il suo approccio:

• Approva: consenti l'esecuzione dello strumento come richiesto da Claude
• Approva con modifiche: modifica l'input prima dell'esecuzione (ad es. sanitizza i percorsi, aggiungi vincoli)
• Approva e ricorda: ripeti una regola di autorizzazione suggerita in modo che le chiamate corrispondenti saltino il prompt la prossima volta
• Rifiuta: blocca lo strumento e spiega a Claude il motivo
• Suggerisci alternativa: blocca ma guida Claude verso ciò che l'utente vuole invece
• Reindirizza completamente: utilizza input streaming per inviare a Claude un'istruzione completamente nuova

async def can_use_tool(tool_name, input_data, context):
print(f"Claude wants to use {tool_name}")
approved = await ask_user("Allow this action?")

if approved:
return PermissionResultAllow(updated_input=input_data)
return PermissionResultDeny(message="User declined")

canUseTool: async (toolName, input) => {
console.log(`Claude wants to use ${toolName}`);
const approved = await askUser("Allow this action?");

if (approved) {
return { behavior: "allow", updatedInput: input };
}
return { behavior: "deny", message: "User declined" };
};

async def can_use_tool(tool_name, input_data, context):
if tool_name == "Bash":
# L'utente ha approvato, ma limita tutti i comandi alla sandbox
sandboxed_input = {**input_data}
sandboxed_input["command"] = input_data["command"].replace(
"/tmp", "/tmp/sandbox"
)
return PermissionResultAllow(updated_input=sandboxed_input)
return PermissionResultAllow(updated_input=input_data)

canUseTool: async (toolName, input) => {
if (toolName === "Bash") {
// L'utente ha approvato, ma limita tutti i comandi alla sandbox
const sandboxedInput = {
...input,
command: input.command.replace("/tmp", "/tmp/sandbox")
};
return { behavior: "allow", updatedInput: sandboxedInput };
}
return { behavior: "allow", updatedInput: input };
};

async def can_use_tool(tool_name, input_data, context):
choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"])

if choice == "always":
persist = [
s for s in context.suggestions if s.destination == "localSettings"
]
return PermissionResultAllow(
updated_input=input_data, updated_permissions=persist
)
if choice == "once":
return PermissionResultAllow(updated_input=input_data)
return PermissionResultDeny(message="User declined")

canUseTool: async (toolName, input, { suggestions = [] }) => {
const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]);

if (choice === "always") {
const persist = suggestions.filter(
(s) => s.destination === "localSettings"
);
return {
behavior: "allow",
updatedInput: input,
updatedPermissions: persist
};
}
if (choice === "once") {
return { behavior: "allow", updatedInput: input };
}
return { behavior: "deny", message: "User declined" };
};

async def can_use_tool(tool_name, input_data, context):
approved = await ask_user(f"Allow {tool_name}?")

if not approved:
return PermissionResultDeny(message="User rejected this action")
return PermissionResultAllow(updated_input=input_data)

canUseTool: async (toolName, input) => {
const approved = await askUser(`Allow ${toolName}?`);

if (!approved) {
return {
behavior: "deny",
message: "User rejected this action"
};
}
return { behavior: "allow", updatedInput: input };
};

async def can_use_tool(tool_name, input_data, context):
if tool_name == "Bash" and "rm" in input_data.get("command", ""):
# L'utente non vuole eliminare, suggerisci di comprimere invece
return PermissionResultDeny(
message="User doesn't want to delete files. They asked if you could compress them into an archive instead."
)
return PermissionResultAllow(updated_input=input_data)

canUseTool: async (toolName, input) => {
if (toolName === "Bash" && input.command.includes("rm")) {
// L'utente non vuole eliminare, suggerisci di comprimere invece
return {
behavior: "deny",
message:
"User doesn't want to delete files. They asked if you could compress them into an archive instead."
};
}
return { behavior: "allow", updatedInput: input };
};

Gestire domande di chiarimento

Quando Claude ha bisogno di più direzione su un'attività con più approcci validi, chiama lo strumento AskUserQuestion. Questo attiva il tuo callback canUseTool con toolName impostato su AskUserQuestion. L'input contiene le domande di Claude come opzioni a scelta multipla, che visualizzi all'utente e restituisci le sue selezioni.

I seguenti passaggi mostrano come gestire le domande di chiarimento:

async for message in query(
prompt="Analyze this codebase",
options=ClaudeAgentOptions(
# Includi AskUserQuestion nella tua lista di strumenti
tools=["Read", "Glob", "Grep", "AskUserQuestion"],
can_use_tool=can_use_tool,
),
):
print(message)

for await (const message of query({
prompt: "Analyze this codebase",
options: {
// Includi AskUserQuestion nella tua lista di strumenti
tools: ["Read", "Glob", "Grep", "AskUserQuestion"],
canUseTool: async (toolName, input) => {
// Gestisci le domande di chiarimento qui
}
}
})) {
console.log(message);
}

async def can_use_tool(tool_name: str, input_data: dict, context):
if tool_name == "AskUserQuestion":
# La tua implementazione per raccogliere risposte dall'utente
return await handle_clarifying_questions(input_data)
# Gestisci altri strumenti normalmente
return await prompt_for_approval(tool_name, input_data)

canUseTool: async (toolName, input) => {
if (toolName === "AskUserQuestion") {
// La tua implementazione per raccogliere risposte dall'utente
return handleClarifyingQuestions(input);
}
// Gestisci altri strumenti normalmente
return promptForApproval(toolName, input);
};

{
"questions": [
{
"question": "How should I format the output?",
"header": "Format",
"options": [
{ "label": "Summary", "description": "Brief overview" },
{ "label": "Detailed", "description": "Full explanation" }
],
"multiSelect": false
},
{
"question": "Which sections should I include?",
"header": "Sections",
"options": [
{ "label": "Introduction", "description": "Opening context" },
{ "label": "Conclusion", "description": "Final summary" }
],
"multiSelect": true
}
]
}

return PermissionResultAllow(
updated_input={
"questions": input_data.get("questions", []),
"answers": {
"How should I format the output?": "Summary",
"Which sections should I include?": ["Introduction", "Conclusion"],
},
}
)

return {
behavior: "allow",
updatedInput: {
questions: input.questions,
answers: {
"How should I format the output?": "Summary",
"Which sections should I include?": "Introduction, Conclusion"
}
}
};

Formato della domanda

L'input contiene le domande generate da Claude in un array questions. Ogni domanda ha questi campi:

La struttura che il tuo callback riceve:

{
  "questions": [
    {
      "question": "How should I format the output?",
      "header": "Format",
      "options": [
        { "label": "Summary", "description": "Brief overview of key points" },
        { "label": "Detailed", "description": "Full explanation with examples" }
      ],
      "multiSelect": false
    }
  ]
}

Anteprime delle opzioni (TypeScript)

toolConfig.askUserQuestion.previewFormat aggiunge un campo preview a ogni opzione in modo che la tua app possa mostrare un mockup visivo insieme all'etichetta. Senza questa impostazione, Claude non genera anteprime e il campo è assente.

Il formato si applica a tutte le domande nella sessione. Claude include preview sulle opzioni in cui un confronto visivo aiuta (scelte di layout, schemi di colori) e lo omette dove non lo farebbe (conferme sì/no, scelte solo testo). Controlla undefined prima di eseguire il rendering.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Help me choose a card layout",
  options: {
    toolConfig: {
      askUserQuestion: { previewFormat: "html" }
    },
    canUseTool: async (toolName, input) => {
      // input.questions[].options[].preview è una stringa HTML o undefined
      return { behavior: "allow", updatedInput: input };
    }
  }
})) {
  // ...
}

Un'opzione con un'anteprima HTML:

{
  "label": "Compact",
  "description": "Title and metric value only",
  "preview": "<div style=\"padding:12px;border:1px solid #ddd;border-radius:8px\"><div style=\"font-size:12px;color:#666\">Active users</div><div style=\"font-size:28px;font-weight:600\">1,284</div></div>"
}

Formato della risposta

Restituisci un oggetto answers che mappa il campo question di ogni domanda all'label dell'opzione selezionata:

Per le domande a selezione multipla, passa un array di etichette o uniscile con ", ". Per l'input di testo libero, utilizza il testo personalizzato dell'utente direttamente.

{
  "questions": [
    // ...
  ],
  "answers": {
    "How should I format the output?": "Summary",
    "Which sections should I include?": ["Introduction", "Conclusion"]
  }
}

Supporta input di testo libero

Le opzioni predefinite di Claude non copriranno sempre ciò che gli utenti vogliono. Per consentire agli utenti di digitare la propria risposta:

• Visualizza una scelta "Other" aggiuntiva dopo le opzioni di Claude che accetta input di testo
• Utilizza il testo personalizzato dell'utente come valore della risposta (non la parola "Other")

Vedi l'esempio completo di seguito per un'implementazione completa.

Esempio completo

Claude pone domande di chiarimento quando ha bisogno di input dell'utente per procedere. Ad esempio, quando gli viene chiesto di aiutare a decidere su uno stack tecnologico per un'app mobile, Claude potrebbe chiedere informazioni su cross-platform vs nativo, preferenze di backend o piattaforme di destinazione. Queste domande aiutano Claude a prendere decisioni che corrispondono alle preferenze dell'utente piuttosto che indovinare.

Questo esempio gestisce quelle domande in un'applicazione terminale. Ecco cosa accade ad ogni passaggio:

1. Instrada la richiesta: Il callback canUseTool controlla se il nome dello strumento è "AskUserQuestion" e instrada a un gestore dedicato
2. Visualizza le domande: Il gestore scorre l'array questions e stampa ogni domanda con opzioni numerate
3. Raccogli input: L'utente può inserire un numero per selezionare un'opzione, o digitare testo libero direttamente (ad es. "jquery", "i don't know")
4. Mappa le risposte: Il codice controlla se l'input è numerico (utilizza l'etichetta dell'opzione) o testo libero (utilizza il testo direttamente)
5. Restituisci a Claude: La risposta include sia l'array questions originale che la mappatura answers

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from claude_agent_sdk.types import HookMatcher, PermissionResultAllow


def parse_response(response: str, options: list) -> str:
"""Analizza l'input dell'utente come numero(i) di opzione o testo libero."""
try:
indices = [int(s.strip()) - 1 for s in response.split(",")]
labels = [options[i]["label"] for i in indices if 0 <= i < len(options)]
return ", ".join(labels) if labels else response
except ValueError:
return response


async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow:
"""Visualizza le domande di Claude e raccogli le risposte dell'utente."""
answers = {}

for q in input_data.get("questions", []):
print(f"\n{q['header']}: {q['question']}")

options = q["options"]
for i, opt in enumerate(options):
print(f"  {i + 1}. {opt['label']} - {opt['description']}")
if q.get("multiSelect"):
print("  (Enter numbers separated by commas, or type your own answer)")
else:
print("  (Enter a number, or type your own answer)")

response = input("Your choice: ").strip()
answers[q["question"]] = parse_response(response, options)

return PermissionResultAllow(
updated_input={
"questions": input_data.get("questions", []),
"answers": answers,
}
)


async def can_use_tool(
tool_name: str, input_data: dict, context
) -> PermissionResultAllow:
# Instrada AskUserQuestion al nostro gestore di domande
if tool_name == "AskUserQuestion":
return await handle_ask_user_question(input_data)
# Auto-approva altri strumenti per questo esempio
return PermissionResultAllow(updated_input=input_data)


async def prompt_stream():
yield {
"type": "user",
"message": {
"role": "user",
"content": "Help me decide on the tech stack for a new mobile app",
},
}


# Workaround richiesto: dummy hook mantiene il flusso aperto per can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
return {"continue_": True}


async def main():
async for message in query(
prompt=prompt_stream(),
options=ClaudeAgentOptions(
can_use_tool=can_use_tool,
hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";
import * as readline from "readline/promises";

// Helper per chiedere all'utente l'input nel terminale
async function prompt(question: string): Promise<string> {
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
const answer = await rl.question(question);
rl.close();
return answer;
}

// Analizza l'input dell'utente come numero(i) di opzione o testo libero
function parseResponse(response: string, options: any[]): string {
const indices = response.split(",").map((s) => parseInt(s.trim()) - 1);
const labels = indices
.filter((i) => !isNaN(i) && i >= 0 && i < options.length)
.map((i) => options[i].label);
return labels.length > 0 ? labels.join(", ") : response;
}

// Visualizza le domande di Claude e raccogli le risposte dell'utente
async function handleAskUserQuestion(input: any) {
const answers: Record<string, string> = {};

for (const q of input.questions) {
console.log(`\n${q.header}: ${q.question}`);

const options = q.options;
options.forEach((opt: any, i: number) => {
console.log(`  ${i + 1}. ${opt.label} - ${opt.description}`);
});
if (q.multiSelect) {
console.log("  (Enter numbers separated by commas, or type your own answer)");
} else {
console.log("  (Enter a number, or type your own answer)");
}

const response = (await prompt("Your choice: ")).trim();
answers[q.question] = parseResponse(response, options);
}

// Restituisci le risposte a Claude (deve includere le domande originali)
return {
behavior: "allow",
updatedInput: { questions: input.questions, answers }
};
}

async function main() {
for await (const message of query({
prompt: "Help me decide on the tech stack for a new mobile app",
options: {
canUseTool: async (toolName, input) => {
// Instrada AskUserQuestion al nostro gestore di domande
if (toolName === "AskUserQuestion") {
return handleAskUserQuestion(input);
}
// Auto-approva altri strumenti per questo esempio
return { behavior: "allow", updatedInput: input };
}
}
})) {
if ("result" in message) console.log(message.result);
}
}

main();

Limitazioni

• Subagenti: AskUserQuestion non è attualmente disponibile nei subagenti generati tramite lo strumento Agent
• Limiti delle domande: ogni chiamata AskUserQuestion supporta 1-4 domande con 2-4 opzioni ciascuna

Altri modi per ottenere input dall'utente

Il callback canUseTool e lo strumento AskUserQuestion coprono la maggior parte degli scenari di approvazione e chiarimento, ma l'SDK offre altri modi per ottenere input dagli utenti:

Input streaming

Utilizza input streaming quando hai bisogno di:

• Interrompere l'agente a metà attività: invia un segnale di annullamento o cambia direzione mentre Claude sta lavorando
• Fornire contesto aggiuntivo: aggiungi informazioni di cui Claude ha bisogno senza aspettare che le chieda
• Costruire interfacce di chat: consenti agli utenti di inviare messaggi di follow-up durante operazioni di lunga durata

L'input streaming è ideale per interfacce conversazionali in cui gli utenti interagiscono con l'agente durante l'esecuzione, non solo nei checkpoint di approvazione.

Strumenti personalizzati

Utilizza strumenti personalizzati quando hai bisogno di:

• Raccogliere input strutturato: costruisci moduli, procedure guidate o flussi di lavoro multi-step che vanno oltre il formato a scelta multipla di AskUserQuestion
• Integrare sistemi di approvazione esterni: connettiti a piattaforme di ticketing, flusso di lavoro o approvazione esistenti
• Implementare interazioni specifiche del dominio: crea strumenti personalizzati per le esigenze della tua applicazione, come interfacce di revisione del codice o elenchi di controllo di distribuzione

Gli strumenti personalizzati ti danno il controllo completo sull'interazione, ma richiedono più lavoro di implementazione rispetto all'utilizzo del callback canUseTool integrato.

Risorse correlate

• Configura autorizzazioni: configura modalità e regole di autorizzazione
• Controlla l'esecuzione con hook: esegui codice personalizzato nei punti chiave del ciclo di vita dell'agente
• Riferimento SDK TypeScript: documentazione API completa di canUseTool