fix(chat): never leave a client tool call unanswered on the server (#807)

* docs(specs): client-tool continuation correctness fixes

Design for five defects found reviewing the shipped client-tool
continuation stack (#782-#805). Four violate one unstated invariant:
the server thread must never hold a client tool call without a result.

Adds flush() to ClientToolsCapability so a settled result can be made
durable without continuing the run, and maps all five fixes onto it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(plans): client-tool continuation fixes implementation plan

Ten tasks covering all five defects, TDD per task, with a live
browser verification gate whose decisive step is reload-then-continue.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(chat): add flush() to ClientToolsCapability

* feat(langgraph): batched flush() with submit-drain fallback

* fix(langgraph): take flush() batch ownership at snapshot and clear staging on thread switch

* fix(chat): flush settled client-tool groups and stop discarding limited results

* fix(chat): settle aborted client tools and wrap agent.stop once

* fix(chat): flush blocked client-tool groups once on completion

Flushing per blocked call stranded every batch after the first: adapter
flush() implementations coalesce concurrent calls by returning the
in-flight promise, so only the first batch was ever snapshotted. Gate the
blocked-group flush on group completion, mirroring the terminal path.

Drop the blockedIds guard: both shipped adapters mark a call resolved
inside settle() so pending() drops it immediately, meaning a settled call
can never be re-presented to the executor effect. The hazard it guarded
was an artifact of a test double whose settle() left calls pending
forever; the fakes now mirror adapter behavior instead.

Warn rather than silently discard when a blocked call cannot be recorded
because the capability implements no settle().

* fix(middleware): enforce tenant isolation in the client tool execution store

* fix(chat): never continue the run when settling a cancelled client tool

* feat(examples): add terminal client tool to the chat demo

* docs: regenerate API docs for client-tool flush surface

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(langgraph): chain concurrent flushes and drop stale-thread client tool results

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: blove

apps/website/content/docs/chat/api/api-docs.json

@@ -6952,6 +6952,12 @@
         "description": "",
         "optional": true
       },
+      {
+        "name": "settleWithoutContinuing",
+        "type": "(toolCall: ToolCall, result: ClientToolResult) => void",
+        "description": "Settlement for calls that must NOT continue the run (user abort, teardown).",
+        "optional": true
+      },
       {
         "name": "shouldExecuteToolCall",
         "type": "(toolCall: ToolCall) => boolean",
@@ -7024,6 +7030,12 @@
       }
     ],
     "methods": [
+      {
+        "name": "flush",
+        "signature": "flush(): void | Promise<void>",
+        "description": "Make every result recorded via settle durable on the server\nWITHOUT continuing the run. No-op for adapters whose settle() is already\ndurable. Adapters that buffer locally MUST clear their buffer only on a\nsuccessful write, so a failure degrades to a later flush or submit.",
+        "params": []
+      },
       {
         "name": "resolve",
         "signature": "resolve(toolCallId: string, result: ClientToolResult): void",
@@ -8698,6 +8710,25 @@
     },
     "examples": []
   },
+  {
+    "name": "cancelledClientToolResult",
+    "kind": "function",
+    "description": "Result recorded when the user stops a run while a client tool is running.",
+    "signature": "cancelledClientToolResult(toolCallId: string): ClientToolResult",
+    "params": [
+      {
+        "name": "toolCallId",
+        "type": "string",
+        "description": "",
+        "optional": false
+      }
+    ],
+    "returns": {
+      "type": "ClientToolResult",
+      "description": ""
+    },
+    "examples": []
+  },
   {
     "name": "citationSourceVisual",
     "kind": "function",

apps/website/content/docs/middleware/api/api-docs.json

@@ -381,7 +381,7 @@
       {
         "name": "tenantId",
         "type": "string | null",
-        "description": "",
+        "description": "Tenant scope for every read and write. Defaults to `''` (the single-tenant scope).",
         "optional": true
       }
     ],
@@ -472,7 +472,7 @@
     "name": "THREADPLANE_CLIENT_TOOL_EXECUTIONS_SCHEMA",
     "kind": "const",
     "description": "",
-    "signature": "\"\\nCREATE TABLE IF NOT EXISTS threadplane_client_tool_executions (\\n  tenant_id     text,\\n  thread_id     text        NOT NULL,\\n  tool_call_id  text        NOT NULL,\\n  status        text        NOT NULL,\\n  result        jsonb,\\n  created_at    timestamptz NOT NULL DEFAULT now(),\\n  updated_at    timestamptz NOT NULL DEFAULT now(),\\n  PRIMARY KEY (thread_id, tool_call_id)\\n);\\n\"",
+    "signature": "\"\\nCREATE TABLE IF NOT EXISTS threadplane_client_tool_executions (\\n  tenant_id     text        NOT NULL DEFAULT '',\\n  thread_id     text        NOT NULL,\\n  tool_call_id  text        NOT NULL,\\n  status        text        NOT NULL,\\n  result        jsonb,\\n  created_at    timestamptz NOT NULL DEFAULT now(),\\n  updated_at    timestamptz NOT NULL DEFAULT now(),\\n  PRIMARY KEY (tenant_id, thread_id, tool_call_id)\\n);\\n\"",
     "examples": []
   },
   {