effect-assistant 0.2.0 → 0.4.0

package/src/internal/history.ts

@@ -110,16 +110,53 @@ const answerText = (answer: AssistantEvent.BlockAnswer) =>
 const resultText = (result: AssistantEvent.ToolResult) =>
   `<result tool="${result.tool}" call="${result.callId}" outcome="${result.outcome}">\nThe result of a call from earlier in this chat.\n${toJsonText(result.result)}\n</result>`
 
-// In the order the model saw the entries, not the order they were stored.
+/** @internal */
+export const awaitingApprovalOutput =
+  "Waiting for the user's approval: they see this call and approve or reject it. Its outcome arrives later in this chat; don't call it again meanwhile."
+
+const awaitingText = (request: AssistantEvent.ApprovalRequested) =>
+  `<approval tool="${request.tool}" call="${request.callId}" status="pending">\nYour call to ${request.tool} from earlier in this chat waits for the user's approval.\n${toJsonText(request.params)}\n</approval>`
+
+const approvedText = (result: AssistantEvent.ToolResult) =>
+  `<result tool="${result.tool}" call="${result.callId}" outcome="${result.outcome}">\nThe user approved your call to ${result.tool} from earlier in this chat, and it ran.\n${toJsonText(result.result)}\n</result>`
+
+const rejectedText = (decision: AssistantEvent.ApprovalDecision, tool: string) =>
+  `<approval tool="${tool}" call="${decision.callId}" decision="rejected">\nThe user rejected your call to ${tool}; it didn't run.${decision.reason === undefined ? "" : `\nTheir reason: ${decision.reason}`}\n</approval>`
+
+const expiredText = (callId: string, tool: string) =>
+  `<approval tool="${tool}" call="${callId}" status="expired">\nThe user moved on without approving your call to ${tool}; it didn't run.\n</approval>`
+
+const awaitingMessage = (request: AssistantEvent.ApprovalRequested): Prompt.ToolMessage =>
+  Prompt.toolMessage({
+    content: [
+      Prompt.toolResultPart({
+        id: request.callId,
+        name: request.tool,
+        isFailure: false,
+        result: awaitingApprovalOutput,
+        providerExecuted: false
+      })
+    ]
+  })
+
+const isEntry = (item: AssistantEvent.AnyEntry | Prompt.Message): item is AssistantEvent.AnyEntry =>
+  Predicate.hasProperty(item, "seq")
+
+// In the order the model saw the entries, not the order they were stored. A message a history view put in stands
+// where it is, right after the entry before it, and waits like an input for a call's result or for the model's next
+// read; the app's own events reach the model only as such messages.
 /** @internal */
 export const fromEntries = (
-  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
-  readApp: (event: { readonly _tag: string }) => string | undefined
+  items: ReadonlyArray<AssistantEvent.AnyEntry | Prompt.Message>
 ): ReadonlyArray<Prompt.Message> => {
+  const entries = items.filter(isEntry)
   const history: Array<Prompt.Message> = []
   const held: Array<Prompt.Message> = []
   const open = new Set<string>()
   const called = new Set<string>()
+  // Calls that waited for approval: the placeholder answered them, so what came of them later is an input.
+  const requests = new Map<string, AssistantEvent.ApprovalRequested>()
+  const toolOf = (callId: string) => requests.get(callId)?.tool ?? "a tool"
 
   const flushIfClosed = () => {
     if (open.size === 0) history.push(...held.splice(0))
@@ -133,27 +170,35 @@ export const fromEntries = (
       : undefined
   }
 
-  const input = (index: number, item: Prompt.Message) => {
+  // `index` is the last entry at or before the item, and `seq` where the item stands.
+  const input = (index: number, seq: number, item: Prompt.Message) => {
     const seen = nextSeen(index)
 
-    if (open.size > 0 || (seen !== undefined && seen < entries[index]!.seq)) held.push(item)
+    if (open.size > 0 || (seen !== undefined && seen < seq)) held.push(item)
     else history.push(item)
   }
 
-  entries.forEach(({ event }, index) => {
-    if (!AssistantEvent.isLibraryEvent(event)) {
-      const text = readApp(event)
+  let index = -1
 
-      if (text !== undefined) input(index, userText(text))
+  for (const item of items) {
+    if (!isEntry(item)) {
+      input(index, (entries[index]?.seq ?? 0) + 0.5, item)
 
-      return
+      continue
     }
 
+    index += 1
+
+    const { event, seq } = item
+    const at = index
+
+    if (!AssistantEvent.isLibraryEvent(event)) continue
+
     Match.value(event).pipe(
       Match.tagsExhaustive({
         UserMessage: (message) =>
-          input(index, userText(AssistantEvent.textWithAttachments(message.text, message.attachments))),
-        BlockAnswer: (answer) => input(index, userText(answerText(answer))),
+          input(at, seq, userText(AssistantEvent.textWithAttachments(message.text, message.attachments))),
+        BlockAnswer: (answer) => input(at, seq, userText(answerText(answer))),
         ModelOutput: (output) => {
           history.push(...Prompt.fromResponseParts(output.parts).content)
 
@@ -167,9 +212,11 @@ export const fromEntries = (
           flushIfClosed()
         },
         ToolResult: (result) => {
+          if (requests.has(result.callId)) return input(at, seq, userText(approvedText(result)))
+
           // A view that starts after the call (since a summary, say) keeps its result as text: a tool result needs its
           // call right before it.
-          if (!called.has(result.callId)) return input(index, userText(resultText(result)))
+          if (!called.has(result.callId)) return input(at, seq, userText(resultText(result)))
 
           history.push(toolMessage(result))
           open.delete(result.callId)
@@ -180,21 +227,38 @@ export const fromEntries = (
         TurnStarted: () => undefined,
         TurnCompleted: () => undefined,
         TurnFailed: () => undefined,
-        SpecialistFinished: (finished) => input(index, userText(finishedText(entries, index, finished))),
+        SpecialistFinished: (finished) => input(at, seq, userText(finishedText(entries, at, finished))),
         // Every run starts in a call of the model's own (a spawn or a follow-up), whose result says so.
         SpecialistStarted: () => undefined,
         BlocksClosed: () => undefined,
+        // The call's result, for the provider's pairing; what the user decides comes later.
+        ApprovalRequested: (request) => {
+          requests.set(request.callId, request)
+
+          if (!called.has(request.callId)) return input(at, seq, userText(awaitingText(request)))
+
+          history.push(awaitingMessage(request))
+          open.delete(request.callId)
+          flushIfClosed()
+        },
+        // An approved call's result says so.
+        ApprovalDecision: (decision) =>
+          decision.decision === "rejected"
+            ? input(at, seq, userText(rejectedText(decision, toolOf(decision.callId))))
+            : undefined,
+        ApprovalsExpired: (expired) =>
+          expired.callIds.forEach((callId) => input(at, seq, userText(expiredText(callId, toolOf(callId))))),
         ChatDeleted: () => undefined
       })
     )
-  })
+  }
 
   return [...history, ...held]
 }
 
 /** @internal */
-export const isInput = (event: { readonly _tag: string }, wakes: ReadonlySet<string>): boolean =>
-  AssistantEvent.isInput(event) || (!AssistantEvent.isLibraryEvent(event) && wakes.has(event._tag))
+export const isInput = (event: { readonly _tag: string }): boolean =>
+  AssistantEvent.isInput(event) || AssistantEvent.isAppInput(event)
 
 /** @internal */
 export const handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): number => {
@@ -206,23 +270,20 @@ export const handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>):
 // A run the assistant stopped isn't an input here: it wakes nothing.
 /** @internal */
 export const unhandledInputs = (
-  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
-  wakes: ReadonlySet<string>
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>
 ): ReadonlyArray<{ readonly _tag: string }> => {
   const seen = handledThrough(entries)
 
   return entries.flatMap(({ event, seq }) =>
-    seq > seen && isInput(event, wakes) && !(AssistantEvent.isInput(event) && !AssistantEvent.isWaking(event))
-      ? [event]
-      : []
+    seq > seen && isInput(event) && !(AssistantEvent.isInput(event) && !AssistantEvent.isWaking(event)) ? [event] : []
   )
 }
 
 /** @internal */
-export const needsTurn = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, wakes: ReadonlySet<string>): boolean =>
-  unhandledInputs(entries, wakes).length > 0
+export const needsTurn = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): boolean =>
+  unhandledInputs(entries).length > 0
 
-// A failure the user was shown counts as a reply.
+// A failure the user was shown counts as a reply, and so does a call they're asked to approve.
 /** @internal */
 export const owesReply = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSeq: number): boolean => {
   const latest = entries.findLast(
@@ -233,7 +294,10 @@ export const owesReply = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throu
     latest !== undefined &&
     !entries.some(
       ({ event, seq }) =>
-        seq > latest.seq && (Predicate.isTagged(event, "AssistantMessage") || Predicate.isTagged(event, "TurnFailed"))
+        seq > latest.seq &&
+        (Predicate.isTagged(event, "AssistantMessage") ||
+          Predicate.isTagged(event, "TurnFailed") ||
+          Predicate.isTagged(event, "ApprovalRequested"))
     )
   )
 }
@@ -278,17 +342,15 @@ export const owesDelivery = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, th
     )
   )
 
+  // A call waiting for the user's approval is what comes next, like a specialist's report.
   return (
     messages.length > 0 &&
     messages.every((message) => message.block === undefined && progress.has(message.id)) &&
-    !after.some((event) => Predicate.isTagged(event, "TurnFailed")) &&
+    !after.some((event) => Predicate.isTagged(event, "TurnFailed") || Predicate.isTagged(event, "ApprovalRequested")) &&
     started.every((runId) => finished.has(runId))
   )
 }
 
 /** @internal */
-export const unreadAfter = (
-  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
-  throughSeq: number,
-  wakes: ReadonlySet<string>
-): boolean => entries.some(({ event, seq }) => seq > throughSeq && isInput(event, wakes))
+export const unreadAfter = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSeq: number): boolean =>
+  entries.some(({ event, seq }) => seq > throughSeq && isInput(event))

package/src/internal/input.ts

@@ -0,0 +1,3 @@
+// Marks a stored app event that came in through the assistant's `submit`: an input, which wakes a turn.
+/** @internal */
+export const inputKey = "~effect-assistant/input"

package/src/internal/loop.ts

@@ -21,7 +21,18 @@ import * as Toolkits from "./toolkit.ts"
 import { isTurnEnding } from "./tools.ts"
 
 /** @internal */
-export type Event = AssistantEvent.ModelOutput | AssistantEvent.ToolStarted | AssistantEvent.ToolResult
+export type Event =
+  | AssistantEvent.ModelOutput
+  | AssistantEvent.ToolStarted
+  | AssistantEvent.ToolResult
+  | AssistantEvent.ApprovalRequested
+
+// Only a turn's loop can wait for the user's approval, and runs the calls they approved. A turn's specialists inherit
+// its context, so their runs set it back to none.
+/** @internal */
+export const TurnApprovals = Context.Reference<
+  Option.Option<{ readonly approved: Effect.Effect<ReadonlyArray<AssistantEvent.ToolCallPart>> }>
+>("effect-assistant/TurnApprovals", { defaultValue: Option.none })
 
 // The assistant's own tools with the turn's services, so an app's own loop in a turn can message the user. A
 // specialist's run has none.
@@ -61,8 +72,9 @@ export interface StepResult {
   /** The model's output; unset when the step only ran calls a crash cut off. */
   readonly output: AssistantEvent.ModelOutput | undefined
   /**
-   * Whether the model is done: it made no tool calls, or ended its turn (`wait`, or a message
-   * with `wait: true`) and none of the step's calls failed.
+   * Whether the model is done: it made no tool calls, one of its calls waits for the user's
+   * approval, or it ended its turn (`wait`, or a message with `wait: true`) and none of the step's
+   * calls failed.
    */
   readonly done: boolean
   /**
@@ -71,9 +83,15 @@ export interface StepResult {
   readonly historyLength: number
 }
 
-// The loop runs the calls itself, after storing each as started, so the model call runs none.
+// The loop runs the calls itself, after storing each as started, so the model call runs none. It also decides which
+// calls wait for approval: the model call would ask for approvals of its own.
 const requestToolkit = (definitions: ReadonlyArray<Tool.Any>): Toolkit.WithHandler<Record<string, Tool.Any>> => ({
-  tools: Object.fromEntries(definitions.map((tool) => [tool.name, tool])),
+  tools: Object.fromEntries(
+    definitions.map((tool) => [
+      tool.name,
+      tool.needsApproval === undefined || tool.needsApproval === false ? tool : tool.setNeedsApproval(false)
+    ])
+  ),
   handle: () => Effect.succeed(Stream.empty)
 })
 
@@ -111,28 +129,79 @@ const runCall = Effect.fnUntraced(function* <R>(tools: Toolkits.Tools<R>, call:
   return AssistantEvent.ToolResult.make({ callId: call.id, tool: call.name, ...result })
 })
 
-// Every `ToolStarted` is stored before any call runs. `then` is told whether one of the calls failed, so the model
-// has to read the results.
+// A call that needs approval waits for the user in a turn. A specialist's run can't ask them, so its call fails.
+const awaitApproval = Effect.fnUntraced(function* (call: AssistantEvent.ToolCallPart) {
+  if (Option.isNone(yield* TurnApprovals)) {
+    return AssistantEvent.ToolResult.make({
+      callId: call.id,
+      tool: call.name,
+      ...Toolkits.failed(
+        `${call.name} needs the user's approval, and only the assistant can ask for it. Don't run it: say in your answer what needs approving, with the details.`,
+        "NeedsApproval"
+      )
+    })
+  }
+
+  return AssistantEvent.ApprovalRequested.make({ callId: call.id, tool: call.name, params: call.params })
+})
+
+interface Pending {
+  readonly call: AssistantEvent.ToolCallPart
+  /** The user approved it: it runs without asking again. */
+  readonly approved: boolean
+}
+
+interface Ran {
+  /** One of the calls failed, so the model has to read the results. */
+  readonly failed: boolean
+  /** One of the calls waits for the user's approval, so the turn ends. */
+  readonly waiting: boolean
+}
+
+// Every `ToolStarted` is stored before any call runs; a call that waits for approval doesn't start.
 const runCalls = <R, S, E, R2>(
   tools: Toolkits.Tools<R>,
-  calls: ReadonlyArray<AssistantEvent.ToolCallPart>,
-  then: (failed: boolean) => Stream.Stream<Step<never, S>, E, R2>
+  pending: ReadonlyArray<Pending>,
+  history: ReadonlyArray<Prompt.Message>,
+  then: (ran: Ran) => Stream.Stream<Step<never, S>, E, R2>
 ): Stream.Stream<Step<Event, S>, E, R | R2> =>
-  Stream.fromIterable(
-    calls.map((call) => value(AssistantEvent.ToolStarted.make({ callId: call.id, tool: call.name })))
-  ).pipe(
-    Stream.concat(
-      Stream.unwrap(
-        Effect.gen(function* () {
-          const done = yield* Effect.forEach(calls, (call) => runCall(tools, call), { concurrency: "unbounded" })
-
-          return Stream.fromIterable(done.map(value)).pipe(Stream.concat(then(done.some(isFailure))))
-        })
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const waits = yield* Effect.forEach(pending, ({ call, approved }) =>
+        approved ? Effect.succeed(false) : tools.needsApproval(call, history)
       )
-    )
+
+      const started = pending.flatMap(({ call }, i) =>
+        waits[i] === true ? [] : [value(AssistantEvent.ToolStarted.make({ callId: call.id, tool: call.name }))]
+      )
+
+      return Stream.fromIterable(started).pipe(
+        Stream.concat(
+          Stream.unwrap(
+            Effect.gen(function* () {
+              const done = yield* Effect.forEach(
+                pending,
+                ({ call }, i): Effect.Effect<Event, never, R> =>
+                  waits[i] === true ? awaitApproval(call) : runCall(tools, call),
+                { concurrency: "unbounded" }
+              )
+
+              return Stream.fromIterable(done.map(value)).pipe(
+                Stream.concat(
+                  then({
+                    failed: done.some(isFailure),
+                    waiting: done.some((event) => Predicate.isTagged(event, "ApprovalRequested"))
+                  })
+                )
+              )
+            })
+          )
+        )
+      )
+    })
   )
 
-const isFailure = (result: AssistantEvent.ToolResult) => result.outcome === "failure"
+const isFailure = (event: Event) => Predicate.isTagged(event, "ToolResult") && event.outcome === "failure"
 
 /** @internal */
 export type Step<A, S> = Data.TaggedEnum<{
@@ -192,19 +261,31 @@ export const step = <R, S, E2 = never, R2 = never>(
   const instructions = Predicate.isString(options.instructions) ? { text: options.instructions } : options.instructions
 
   const after = (result: StepResult) => Stream.suspend(() => then(result))
-  const needingApproval = Toolkits.needingApproval(toolkit.definitions)
-
-  if (needingApproval.length > 0) return Stream.die(Toolkits.needsApprovalMessage(needingApproval))
 
   return Stream.unwrap(
     Effect.gen(function* () {
       const { messages: history, throughSeq } = readHistory(yield* options.history)
       // Calls a crash cut off, with no result: they run again, with the same ids, before the model goes on.
       const cutOff = History.unansweredCalls(history)
+      const approvals = yield* TurnApprovals
+
+      // Calls the user approved: they run as the model made them, with the same ids, before the model goes on. Not in
+      // a loop without their tools.
+      const approved = Option.isNone(approvals)
+        ? []
+        : (yield* approvals.value.approved).filter(
+            (call) =>
+              toolkit.definitions.some((tool) => tool.name === call.name) && !cutOff.some((cut) => cut.id === call.id)
+          )
+
+      if (cutOff.length > 0 || approved.length > 0) {
+        const pending = [
+          ...cutOff.map((call) => ({ call, approved: false })),
+          ...approved.map((call) => ({ call, approved: true }))
+        ]
 
-      if (cutOff.length > 0) {
-        return runCalls(toolkit, cutOff, () =>
-          after({ output: undefined, done: false, historyLength: history.length + cutOff.length })
+        return runCalls(toolkit, pending, history, ({ waiting }) =>
+          after({ output: undefined, done: waiting, historyLength: history.length + pending.length })
         )
       }
 
@@ -230,15 +311,20 @@ export const step = <R, S, E2 = never, R2 = never>(
       const calls = toolCalls(output.parts)
       const historyLength = history.length + Prompt.fromResponseParts(output.parts).content.length + calls.length
 
-      // A failed call doesn't end the turn: a message that failed never reached the user, so the model reads why.
+      // A failed call doesn't end the turn: a message that failed never reached the user, so the model reads why. A call
+      // that waits for approval does: the turn waits for the user.
       return Stream.make(value(output)).pipe(
         Stream.concat(
-          runCalls(toolkit, calls, (failed) =>
-            after({
-              output,
-              done: calls.length === 0 || (!failed && calls.some(isTurnEnding)),
-              historyLength
-            })
+          runCalls(
+            toolkit,
+            calls.map((call) => ({ call, approved: false })),
+            history,
+            ({ failed, waiting }) =>
+              after({
+                output,
+                done: calls.length === 0 || waiting || (!failed && calls.some(isTurnEnding)),
+                historyLength
+              })
           )
         )
       )

package/src/internal/specialists.ts

@@ -22,12 +22,9 @@ import * as Loop from "./loop.ts"
 import { CurrentChat } from "../CurrentChat.ts"
 import * as InputId from "../InputId.ts"
 import * as RunId from "../RunId.ts"
-import * as Skill from "../Skill.ts"
-import * as Skills from "./skills.ts"
 import * as Specialist from "../Specialist.ts"
 import * as ToolFailure from "../ToolFailure.ts"
 import { toolMessage, userText } from "./history.ts"
-import { mapText } from "./instructions.ts"
 import * as Telemetry from "./telemetry.ts"
 import * as Toolkits from "./toolkit.ts"
 import type { Writer } from "./writer.ts"
@@ -83,21 +80,19 @@ export const runBrief = Effect.fnUntraced(
       chatId: options.chatId,
       brief: options.brief,
       history: current,
-      loop: (loop) => {
-        const skills = loop.skills ?? []
-
-        return Loop.run({
-          instructions: mapText(loop.instructions, (text) => Skill.withCatalog(text, skills)),
-          toolkit: Toolkits.merge(Skills.toTools(skills), Toolkits.fromToolkitOrEmpty(loop.toolkit)),
+      // A run can't wait for the user's approval: a call that needs it fails, and the run reads why.
+      loop: (loop) =>
+        Loop.run({
+          instructions: loop.instructions,
+          toolkit: Toolkits.fromToolkitOrEmpty(loop.toolkit),
           history: current,
           maxSteps: loop.maxSteps ?? 8
-        })
-      }
+        }).pipe(Stream.provideService(Loop.TurnApprovals, Option.none()))
     }
 
     // A run lives in memory, so there's nothing to run again after a crash: `ToolStarted` isn't kept.
     const record = Effect.fnUntraced(function* (event: AssistantLoop.Event) {
-      if (Predicate.isTagged(event, "ToolStarted")) return
+      if (Predicate.isTagged(event, "ToolStarted") || Predicate.isTagged(event, "ApprovalRequested")) return
 
       if (Predicate.isTagged(event, "ToolResult")) return yield* add([toolMessage(event)])
 

package/src/internal/toolkit.ts

@@ -1,9 +1,11 @@
 import * as AiError from "effect/ai/AiError"
+import type * as Prompt from "effect/ai/Prompt"
 import type * as Tool from "effect/ai/Tool"
 import type * as Toolkit from "effect/ai/Toolkit"
 import type * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 import * as Stream from "effect/Stream"
 import type * as AssistantEvent from "../AssistantEvent.ts"
@@ -23,13 +25,18 @@ export interface CallResult {
 export interface Tools<out R = never> {
   readonly definitions: ReadonlyArray<Tool.Any>
   readonly run: (call: AssistantEvent.ToolCallPart) => Effect.Effect<CallResult, never, R>
+  // Whether the call waits for the user's approval instead of running: its tool's `needsApproval`.
+  readonly needsApproval: (
+    call: AssistantEvent.ToolCallPart,
+    history: ReadonlyArray<Prompt.Message>
+  ) => Effect.Effect<boolean, never, R>
 }
 
 /** @internal */
-export type ToolServices<T extends Record<string, Tool.Any>> = Exclude<
-  Tool.HandlerServices<T[keyof T]>,
-  AssistantToolCall
->
+export type ToolServices<T extends Record<string, Tool.Any>> =
+  | Exclude<Tool.HandlerServices<T[keyof T]>, AssistantToolCall>
+  // Already in the handlers' services; stated for the loop, which decodes params to ask `needsApproval`.
+  | T[keyof T]["parametersSchema"]["DecodingServices"]
 
 const encodeFailure = Schema.encodeSync(ToolFailure.ToolFailure)
 
@@ -60,15 +67,32 @@ const hasTool = <T extends Record<string, Tool.Any>>(
   name: PropertyKey
 ): name is keyof T => Object.hasOwn(toolkit.tools, name)
 
-// Approval would park a call until the user decides, which this library doesn't do: the model calls a tool with
-// final values, and a user's own commitment goes through the app's API from a block.
 /** @internal */
 export const needingApproval = (definitions: ReadonlyArray<Tool.Any>): ReadonlyArray<string> =>
   definitions.flatMap((tool) => (tool.needsApproval === undefined || tool.needsApproval === false ? [] : [tool.name]))
 
-/** @internal */
-export const needsApprovalMessage = (names: ReadonlyArray<string>): string =>
-  `${names.join(", ")} ${names.length === 1 ? "sets" : "set"} needsApproval, and effect-assistant doesn't run tools that wait for approval. Remove needsApproval: let the model call the tool with final values, or show a block whose button calls your app's API, which does the work and submits an app event that wakes the chat.`
+// With noUncheckedIndexedAccess, an index doesn't narrow on `hasTool`.
+const toolNamed = (toolkit: { readonly tools: Record<string, Tool.Any> }, name: string): Tool.Any | undefined =>
+  Object.hasOwn(toolkit.tools, name) ? toolkit.tools[name] : undefined
+
+// Params that don't fit the tool don't wait: the call runs, and fails with why.
+const needsApprovalNative = Effect.fnUntraced(function* <T extends Record<string, Tool.Any>>(
+  toolkit: { readonly tools: T },
+  call: AssistantEvent.ToolCallPart,
+  history: ReadonlyArray<Prompt.Message>
+): Effect.fn.Return<boolean, never, ToolServices<T>> {
+  const tool = toolNamed(toolkit, call.name)
+  const needs = tool?.needsApproval
+
+  if (tool === undefined || needs === undefined || Predicate.isBoolean(needs)) return needs === true
+
+  return yield* Effect.gen(function* () {
+    const params = yield* Schema.decodeUnknownEffect(tool.parametersSchema)(call.params)
+    const decided = needs(params, { toolCallId: call.id, messages: history })
+
+    return Effect.isEffect(decided) ? yield* decided : decided
+  }).pipe(Effect.orElseSucceed(() => false))
+})
 
 // The toolkit decodes the params with the tool's schema before its handler sees them, and a call whose params don't
 // fit fails with a validation error the model reads: the model's JSON is what `handle` takes.
@@ -117,7 +141,8 @@ export const fromWithHandler = <T extends Record<string, Tool.Any>>(
   toolkit: Toolkit.WithHandler<T>
 ): Tools<ToolServices<T>> => ({
   definitions: Object.values(toolkit.tools),
-  run: (call) => runNative(toolkit, call)
+  run: (call) => runNative(toolkit, call),
+  needsApproval: (call, history) => needsApprovalNative(toolkit, call, history)
 })
 
 /** @internal */
@@ -127,22 +152,8 @@ export const fromToolkit = <T extends Record<string, Tool.Any>>(
   definitions: Object.values(toolkit.tools),
   run: Effect.fnUntraced(function* (call) {
     return yield* runNative(yield* toolkit, call)
-  })
-})
-
-// The handlers use services of the loop they run in, so they're made for each call, with its context.
-/** @internal */
-export const withContext = <T extends Record<string, Tool.Any>, R>(
-  toolkit: Toolkit.Toolkit<T>,
-  handlers: (context: Context.Context<R>) => Toolkit.HandlersFrom<T>
-): Tools<R | ToolServices<T>> => ({
-  definitions: Object.values(toolkit.tools),
-  run: Effect.fnUntraced(function* (call) {
-    const context = yield* Effect.context<R>()
-    const resolved = yield* Effect.provideContext(toolkit, yield* toolkit.toHandlers(handlers(context)))
-
-    return yield* runNative(resolved, call)
-  })
+  }),
+  needsApproval: (call, history) => needsApprovalNative(toolkit, call, history)
 })
 
 /** @internal */
@@ -153,7 +164,8 @@ export const fromToolkitOrEmpty = <T extends Record<string, Tool.Any>>(
 /** @internal */
 export const empty: Tools = {
   definitions: [],
-  run: (call) => Effect.succeed(failed(`No tool named ${call.name}.`, "ToolNotFoundError"))
+  run: (call) => Effect.succeed(failed(`No tool named ${call.name}.`, "ToolNotFoundError")),
+  needsApproval: () => Effect.succeed(false)
 }
 
 /** @internal */
@@ -162,7 +174,9 @@ export const merge = <A, B>(self: Tools<A>, that: Tools<B>): Tools<A | B> => {
 
   return {
     definitions: [...self.definitions, ...that.definitions],
-    run: (call) => (inSelf(call) ? self.run(call) : that.run(call))
+    run: (call) => (inSelf(call) ? self.run(call) : that.run(call)),
+    needsApproval: (call, history) =>
+      inSelf(call) ? self.needsApproval(call, history) : that.needsApproval(call, history)
   }
 }
 
@@ -170,7 +184,8 @@ export const merge = <A, B>(self: Tools<A>, that: Tools<B>): Tools<A | B> => {
 /** @internal */
 export const provide = <R>(tools: Tools<R>, context: Context.Context<R>): Tools => ({
   definitions: tools.definitions,
-  run: (call) => Effect.provideContext(tools.run(call), context)
+  run: (call) => Effect.provideContext(tools.run(call), context),
+  needsApproval: (call, history) => Effect.provideContext(tools.needsApproval(call, history), context)
 })
 
 /** @internal */
@@ -184,5 +199,7 @@ export const duplicateNames = (tools: Tools<unknown>): ReadonlyArray<string> =>
 /** @internal */
 export const runOnly = <R>(tools: Tools<R>, names: ReadonlyArray<string>, message: string): Tools<R> => ({
   definitions: tools.definitions,
-  run: (call) => (names.includes(call.name) ? tools.run(call) : Effect.succeed(failed(message, "NotNow")))
+  run: (call) => (names.includes(call.name) ? tools.run(call) : Effect.succeed(failed(message, "NotNow"))),
+  // Refused like any other call it doesn't run.
+  needsApproval: () => Effect.succeed(false)
 })