feat(oss): hitl config expansion (#3818)

updating based on langchain-ai/langchain#37095

Author: sydney-runkle

src/oss/deepagents/human-in-the-loop.mdx

@@ -17,6 +17,7 @@ graph LR
     Human --> |approve| Execute
     Human --> |edit| Execute
     Human --> |reject| ToolMessage[ToolMessage]
+    Human --> |respond| ToolMessage
 
     Execute --> Agent
     ToolMessage --> Agent
@@ -36,7 +37,7 @@ graph LR
 
 The `interrupt_on` parameter accepts a dictionary mapping tool names to interrupt configurations. Each tool can be configured with:
 
-- **`True`**: Enable interrupts with default behavior (approve, edit, reject allowed)
+- **`True`**: Enable interrupts with default behavior (approve, edit, reject, respond allowed)
 - **`False`**: Disable interrupts for this tool
 - **`{"allowed_decisions": [...]}`**: Custom configuration with specific allowed decisions
 
@@ -55,6 +56,7 @@ The `allowed_decisions` list controls what actions a human can take when reviewi
 - **`"approve"`**: Execute the tool with the original arguments as proposed by the agent
 - **`"edit"`**: Modify the tool arguments before execution
 - **`"reject"`**: Skip executing this tool call entirely
+- **`"respond"`**: Return the human's message directly as the tool result, skipping execution — for "ask user" style tools
 
 You can customize which decisions are available for each tool:
 

src/oss/langchain/frontend/human-in-the-loop.mdx

@@ -194,7 +194,7 @@ interface ActionRequest {
 }
 
 interface ReviewConfig {
-  allowedDecisions: ("approve" | "reject" | "edit")[];
+  allowedDecisions: ("approve" | "reject" | "edit" | "respond")[];
 }
 ```
 
@@ -205,11 +205,11 @@ interface ReviewConfig {
 | `actionRequests[].args` | Structured arguments for the action |
 | `actionRequests[].description` | Optional human-readable description of what the action does |
 | `reviewConfigs` | Per-action configuration controlling which decisions are allowed |
-| `reviewConfigs[].allowedDecisions` | Which buttons to show: `"approve"`, `"reject"`, `"edit"` |
+| `reviewConfigs[].allowedDecisions` | Which buttons to show: `"approve"`, `"reject"`, `"edit"`, `"respond"` |
 
 ## Decision types
 
-The HITL pattern supports three decision types:
+The HITL pattern supports four decision types:
 
 ### Approve
 
@@ -259,9 +259,26 @@ const response: HITLResponse = {
 stream.submit(null, { command: { resume: response } });
 ```
 
+### Respond
+
+The user provides a direct reply for "ask user" style tools. The `message` becomes the tool result and the tool itself is not executed:
+
+```ts
+const response: HITLResponse = {
+  decision: "respond",
+  message: "Blue.",
+};
+
+stream.submit(null, { command: { resume: response } });
+```
+
+<Note>
+Use `respond` when the tool is intentionally a placeholder for human input — for example, an `ask_user` tool that prompts the agent to collect information from the user.
+</Note>
+
 ## Building the ApprovalCard
 
-Here is a full approval card component that handles all three decision types:
+Here is a full approval card component that handles all four decision types:
 
 ```tsx
 function ApprovalCard({
@@ -276,7 +293,8 @@ function ApprovalCard({
     request.actionRequests[0]?.args ?? {}
   );
   const [rejectReason, setRejectReason] = useState("");
-  const [mode, setMode] = useState<"review" | "edit" | "reject">("review");
+  const [respondMessage, setRespondMessage] = useState("");
+  const [mode, setMode] = useState<"review" | "edit" | "reject" | "respond">("review");
 
   const action = request.actionRequests[0];
   const config = request.reviewConfigs[0];
@@ -320,6 +338,14 @@ function ApprovalCard({
               Edit
             </button>
           )}
+          {config.allowedDecisions.includes("respond") && (
+            <button
+              className="rounded bg-purple-600 px-4 py-2 text-white"
+              onClick={() => setMode("respond")}
+            >
+              Respond
+            </button>
+          )}
         </div>
       )}
 
@@ -365,6 +391,25 @@ function ApprovalCard({
           </button>
         </div>
       )}
+
+      {mode === "respond" && (
+        <div className="mt-4 space-y-2">
+          <textarea
+            className="w-full rounded border p-2"
+            placeholder="Your response..."
+            value={respondMessage}
+            onChange={(e) => setRespondMessage(e.target.value)}
+          />
+          <button
+            className="rounded bg-purple-600 px-4 py-2 text-white"
+            onClick={() =>
+              onRespond({ decision: "respond", message: respondMessage })
+            }
+          >
+            Send Response
+          </button>
+        </div>
+      )}
     </div>
   );
 }
@@ -376,10 +421,12 @@ After the user makes a decision, the full cycle looks like this:
 
 1. Call `stream.submit(null, { command: { resume: hitlResponse } })`
 2. The `useStream` hook sends the resume command to the LangGraph backend
-3. The agent receives the `HITLResponse` and continues execution
-4. If approved, the tool runs with the original (or edited) arguments
-5. If rejected, the agent receives the reason and decides its next step
-6. The `interrupt` property resets to `null` as the agent resumes streaming
+3. The agent receives the `HITLResponse` and continues execution. The HITL response may be one of:
+    - `"approve"`: The agent continues executing the next action
+    - `"reject"`: The agent receives the rejection reasoning and decides its next step
+    - `"edit"`: The agent runs the tool with the edited arguments
+    - `"respond"`: The human's message is returned directly as the tool result without executing the tool
+4. The `interrupt` property resets to `null` as the agent resumes streaming
 
 <Tip>
 You can chain multiple HITL checkpoints in a single agent run. For example, an
@@ -396,6 +443,7 @@ with the results. Each interrupt is handled independently.
 | Financial transactions | `transfer_funds` | `["approve", "reject"]` |
 | File deletion | `delete_files` | `["approve", "reject"]` |
 | API calls to external services | `call_api` | `["approve", "reject", "edit"]` |
+| Collecting user input | `ask_user` | `["respond"]` |
 
 ## Handling multiple pending actions
 

src/oss/langchain/human-in-the-loop.mdx

@@ -7,17 +7,18 @@ When a model proposes an action that might require review—for example, writing
 
 It does this by checking each tool call against a configurable policy. If intervention is needed, the middleware issues an @[interrupt] that halts execution. The graph state is saved using LangGraph's [persistence layer](/oss/langgraph/persistence), so execution can pause safely and resume later.
 
-A human decision then determines what happens next: the action can be approved as-is (`approve`), modified before running (`edit`), or rejected with feedback (`reject`).
+A human decision then determines what happens next: the action can be approved as-is (`approve`), modified before running (`edit`), rejected with feedback (`reject`), or responded to directly (`respond`) for "ask user" style tools.
 
 ## Interrupt decision types
 
-The [middleware](/oss/langchain/middleware/built-in#human-in-the-loop) defines three built-in ways a human can respond to an interrupt:
+The [middleware](/oss/langchain/middleware/built-in#human-in-the-loop) defines four built-in ways a human can respond to an interrupt:
 
 | Decision Type | Description                                                               | Example Use Case                                    |
 |---------------|---------------------------------------------------------------------------|-----------------------------------------------------|
 | ✅ `approve`   | The action is approved as-is and executed without changes.                | Send an email draft exactly as written              |
 | ✏️ `edit`     | The tool call is executed with modifications.                             | Change the recipient before sending an email        |
 | ❌ `reject`    | The tool call is rejected, with an explanation added to the conversation. | Reject an email draft and explain how to rewrite it |
+| 💬 `respond`  | Tool execution is skipped; the human's message becomes the tool result.   | Answer an "ask_user" prompt with a direct reply     |
 
 The available decision types for each tool depend on the policy you configure in `interrupt_on`.
 When multiple tool calls are paused at the same time, each action requires a separate decision.
@@ -47,7 +48,7 @@ agent = create_agent(
     middleware=[
         HumanInTheLoopMiddleware( # [!code highlight]
             interrupt_on={
-                "write_file": True,  # All decisions (approve, edit, reject) allowed
+                "write_file": True,  # All decisions (approve, edit, reject, respond) allowed
                 "execute_sql": {"allowed_decisions": ["approve", "reject"]},  # No editing allowed
                 "read_data": False, # Safe operation, no approval needed
             },
@@ -75,7 +76,7 @@ const agent = createAgent({
     middleware: [
         humanInTheLoopMiddleware({
             interruptOn: {
-                write_file: true, // All decisions (approve, edit, reject) allowed
+                write_file: true, // All decisions (approve, edit, reject, respond) allowed
                 execute_sql: {
                     allowedDecisions: ["approve", "reject"],
                     // No editing allowed
@@ -120,7 +121,7 @@ const agent = createAgent({
 **`InterruptOnConfig` options:**
 
 <ParamField body="allowed_decisions" type="list[string]">
-    List of allowed decisions: `'approve'`, `'edit'`, or `'reject'`
+    List of allowed decisions: `'approve'`, `'edit'`, `'reject'`, or `'respond'`
 </ParamField>
 
 <ParamField body="description" type="string | callable">
@@ -473,6 +474,58 @@ When multiple actions are under review, provide a decision for each action in th
 ```
 :::
 
+</Tab>
+
+<Tab title="💬 respond">
+    Use `respond` for "ask user" style tools where the tool's real implementation is the human's reply. The `message` content is returned directly as the tool result; the tool itself is not executed.
+
+    :::python
+    ```python
+    agent.invoke(
+        Command(
+            # Decisions are provided as a list, one per action under review.
+            # The order of decisions must match the order of actions
+            # in the interrupt request.
+            resume={
+                "decisions": [
+                    {
+                        "type": "respond",
+                        # The human's reply, returned directly as the tool result
+                        "message": "Blue.",
+                    }
+                ]
+            }
+        ),
+        config=config,  # Same thread ID to resume the paused conversation
+        version="v2",
+    )
+    ```
+    :::
+
+    :::js
+    ```typescript
+    await agent.invoke(
+        new Command({
+            // Decisions are provided as a list, one per action under review.
+            // The order of decisions must match the order of actions
+            // in the interrupt request.
+            resume: {
+                decisions: [
+                    {
+                        type: "respond",
+                        // The human's reply, returned directly as the tool result
+                        message: "Blue.",
+                    }
+                ]
+            }
+        }),
+        config  // Same thread ID to resume the paused conversation
+    );
+    ```
+    :::
+
+The `message` is returned to the agent as a successful `ToolMessage`. Use `respond` when the tool is intentionally a placeholder for human input—for example, an `ask_user` tool that prompts for clarification.
+
 </Tab>
 </Tabs>
 
@@ -567,7 +620,7 @@ The middleware defines an `after_model` hook that runs after the model generates
 2. The middleware inspects the response for tool calls.
 3. If any calls require human input, the middleware builds a `HITLRequest` with `action_requests` and `review_configs` and calls @[interrupt].
 4. The agent waits for human decisions.
-5. Based on the `HITLResponse` decisions, the middleware executes approved or edited calls, synthesizes @[ToolMessage]'s for rejected calls, and resumes execution.
+5. Based on the `HITLResponse` decisions, the middleware executes approved or edited calls, synthesizes @[ToolMessage]'s for rejected calls, returns human replies directly as @[ToolMessage]'s for `respond` decisions, and resumes execution.
 
 
 

src/snippets/hitl-basic-config-js.mdx

@@ -52,7 +52,7 @@ const agent = createDeepAgent({
   model: "google_genai:gemini-3.1-pro-preview",
   tools: [deleteFile, readFile, sendEmail],
   interruptOn: {
-    delete_file: true,  // Default: approve, edit, reject
+    delete_file: true,  // Default: approve, edit, reject, respond
     read_file: false,   // No interrupts needed
     send_email: { allowedDecisions: ["approve", "reject"] },  // No editing
   },

src/snippets/hitl-basic-config-py.mdx

@@ -25,7 +25,7 @@ agent = create_deep_agent(
     model="google_genai:gemini-3.1-pro-preview",
     tools=[delete_file, read_file, send_email],
     interrupt_on={
-        "delete_file": True,  # Default: approve, edit, reject
+        "delete_file": True,  # Default: approve, edit, reject, respond
         "read_file": False,   # No interrupts needed
         "send_email": {"allowed_decisions": ["approve", "reject"]},  # No editing
     },