HITL Integration ✅

State machine for tool confirmations. Approve/reject high-risk ops (bash/delete). Parse yes/no flows.

TL;DR: Detect risky tools -> Request confirm (yes/no). State machine: idle -> awaiting -> executing -> done. 5min expiry.

Risk Detection
State Machine
Confirmation Flows
Code Snippets
Error Handling
Try It

Risk Detection

Auto-classify tools: low/medium/high. High-risk (bash/delete) -> confirm.

From confirmation.ts

export function determineRiskLevel(toolName: string, args?: Record<string, unknown>): RiskLevel {
  // bash, delete, drop -> 'high'
  // read, get -> 'low'
}

Risk	Examples	Confirm?
high 🔴	bash, delete, push	✅ Always
medium 🟡	write, update	Threshold
low 🟢	list, search	❌ Never

State Machine

START
  |
  v
+--------------------+
|     idle           |---REQUEST_CONFIRMATION---+
+--------------------+                         |
  ^                                            v
  |            +------------------------------+
  |            | awaiting_confirmation        |
  |            +------------------------------+
  |              |                         |
  |    USER_APPROVED            USER_REJECTED/
  |        |                         EXPIRED
  |        v                            |
  |    +-----------+                    |
  |    | executing |                    |
  |    +-----------+                    |
  |       |       |                     |
  |       |       |                     |
  |EXEC_COMPLETED EXEC_FAILED           |
  |       |       |                     |
  |       v       v                     |
  |   +-------+ +-------+               |
  |   |complete|  error |               |
  |   +-------+ +-------+               |
  |       |       |                     |
  |       |    RESET                    |
  |       |       |                     |
  |       v       v                     |
  +---END---------+---------------------+

From state-machine.ts

export type HITLStatus = 'idle' | 'awaiting_confirmation' | 'executing' | 'completed' | 'error';

Confirmation Flows

Parse user reply:

// yes/ok/✅ -> approve
// no/cancel/❌ -> reject
parseConfirmationResponse("yes") // { action: 'approve' }

Format request confirmation.ts

🔴 **Confirmation Required**
**Tool:** `bash`
**Risk:** high
**Args:** {"command": "rm file.txt"}
Reply **yes** or **no**.

Code Snippets

HITL Agent integration hitl-agent.ts

if (requiresConfirmation(toolName)) {
  return requestConfirmations(toolCalls);
}

Execute approved executions.ts

const result = await executeApprovedTools(approved, executor);

Error Handling

Code	Status	Desc
HITL_001	400	Invalid confirmation
EXEC_TIMEOUT	408	Tool timeout (30s)
CONF_EXPIRED	410	5min expiry

Quiz: "no because risky" -> ? A: reject + reason ✅

Try It

bun run deploy:telegram
Ask: "Delete all files" -> See confirm!
Reply "yes" -> Executes (safely).

Related: Agents | Tools