docs(sdk): add ask-human tool example

packages/sdk-next/README.md

@@ -13,6 +13,21 @@ const session = yield * opencode.sessions.get({ sessionID })
 
 It also exports `Tool` and exposes local-only `tools.register(...)`, replacing the former `@opencode-ai/core/public` facade. Registration uses Core's host-level `ApplicationTools` service shared by the host's Locations; each Location retains its own `ToolRegistry` for overlay, lookup, and settlement. Closing the owning Effect Scope releases router resources, location services, fibers, and scoped tool registrations.
 
+Host applications can register a callback as an agent tool. For example, an app can pause for a person instead of teaching each agent how its UI works:
+
+```ts
+import { OpenCode } from "@opencode-ai/sdk-next"
+import { makeAskHuman } from "./ask-human"
+
+const opencode = yield * OpenCode.create()
+yield *
+  opencode.tools.register({
+    ask_human: makeAskHuman((question) => showQuestionModal(question)),
+  })
+```
+
+A complete `makeAskHuman` implementation is in [`examples/ask-human.ts`](examples/ask-human.ts).
+
 `sessions.events({ sessionID, after })` replays durable events after the optional aggregate sequence, then emits newly committed durable events. `sessions.interrupt(...)` targets execution owned by this host, and `sessions.message(...)` retrieves one projected Session message.
 
 The same constructor is available as a service Layer:

packages/sdk-next/examples/ask-human.ts

@@ -0,0 +1,15 @@
+import { Tool } from "@opencode-ai/sdk-next"
+import { Effect, Schema } from "effect"
+
+export function makeAskHuman(ask: (question: string) => Promise<string>) {
+  return Tool.make({
+    description: "Ask the person using this agent for a decision or missing information",
+    input: Schema.Struct({ question: Schema.String }),
+    output: Schema.Struct({ answer: Schema.String }),
+    execute: ({ question }) =>
+      Effect.tryPromise({
+        try: () => ask(question),
+        catch: () => new Tool.Failure({ message: "The person did not answer" }),
+      }).pipe(Effect.map((answer) => ({ answer }))),
+  })
+}

packages/sdk-next/test/ask-human-example.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from "bun:test"
+import { Agent, Session, SessionMessage } from "@opencode-ai/sdk-next"
+import { Tool } from "@opencode-ai/core/tool/tool"
+import { Effect } from "effect"
+import { makeAskHuman } from "../examples/ask-human"
+
+test("ask_human returns the host application's answer", async () => {
+  const asked: string[] = []
+  const tool = makeAskHuman(async (question) => {
+    asked.push(question)
+    return "Use the existing account"
+  })
+
+  const result = await Effect.runPromise(
+    Tool.settle(
+      tool,
+      {
+        type: "tool-call",
+        id: "call-ask-human",
+        name: "ask_human",
+        input: { question: "Which account should I use?" },
+      },
+      {
+        sessionID: Session.ID.make("ses_ask_human"),
+        agent: Agent.ID.make("build"),
+        assistantMessageID: SessionMessage.ID.make("msg_ask_human"),
+        toolCallID: "call-ask-human",
+      },
+    ),
+  )
+
+  expect(asked).toEqual(["Which account should I use?"])
+  expect(result.structured).toEqual({ answer: "Use the existing account" })
+})