agent-lattice 0.9.23 → 0.9.24

package/README.md

@@ -283,6 +283,47 @@ const result = await agent.prompt("What is 2+2?");
 console.log(result.result);
 ```
 
+## Tool Batch Policy
+
+Use `toolBatchPolicy` when some tools must not run in the same model response.
+The policy sees the complete batch before any tool executes. If it rejects the
+batch, no tool runs and every tool call receives a structured `is_error: true`
+result.
+
+```ts
+const lead = createAgent({
+  model: "claude-sonnet-4-6",
+  tools: [incrementRevision],
+  toolBatchPolicy: {
+    validate({ toolCalls }) {
+      const incrementsRevision = toolCalls.find(
+        call => call.name === "incrementRevision",
+      );
+      const handoff = toolCalls.find(
+        call => call.kind === "agent_tool" &&
+          (call.input as { mode?: string }).mode === "handoff",
+      );
+      if (incrementsRevision && handoff) {
+        return {
+          allowed: false,
+          code: "invalid_tool_batch",
+          message: "Update the revision before delegating dependent work.",
+          conflictingToolCallIds: [incrementsRevision.id, handoff.id],
+          suggestedNextStep: "Run incrementRevision first, then hand off the new revision.",
+        };
+      }
+      return { allowed: true };
+    },
+  },
+});
+```
+
+The policy may be synchronous or asynchronous. If it throws, the SDK rejects
+the whole batch with `tool_batch_policy_error`; no tool has executed. Without a
+policy, tool execution is unchanged. A policy prevents known bad combinations
+inside one model response, but it does not replace database transactions or
+revision checks against concurrent external updates.
+
 ## Business Context For Tools
 
 Pass host application data through `context`. The SDK gives that context to

package/dist/index.d.ts

@@ -177,6 +177,32 @@ export interface ModelClient {
 export type ToolResult = {
     content: string | ContentBlock[];
 };
+export type ToolKind = "tool" | "agent_tool";
+export type ToolBatchCall = {
+    id: string;
+    name: string;
+    input: unknown;
+    kind: ToolKind;
+};
+export type ToolBatchPolicyContext<TContext = unknown> = {
+    source?: AgentRuntimeSource;
+    toolCalls: ToolBatchCall[];
+    context?: TContext;
+    signal?: AbortSignal;
+};
+export type ToolBatchPolicyRejection = {
+    allowed: false;
+    code: string;
+    message: string;
+    conflictingToolCallIds?: string[];
+    suggestedNextStep?: string;
+};
+export type ToolBatchPolicyResult = {
+    allowed: true;
+} | ToolBatchPolicyRejection;
+export type ToolBatchPolicy<TContext = unknown> = {
+    validate(context: ToolBatchPolicyContext<TContext>): ToolBatchPolicyResult | Promise<ToolBatchPolicyResult>;
+};
 export type ToolExecutionContext<TContext = unknown> = {
     signal?: AbortSignal;
     toolUseId: string;
@@ -188,6 +214,7 @@ export type ToolHandler<TInput = unknown, TContext = unknown> = (input: TInput,
 export type ToolDefinition<TInput = unknown, TContext = unknown> = {
     name: string;
     description: string;
+    kind?: ToolKind;
     inputSchema: unknown;
     jsonSchema: Record<string, unknown>;
     parse(input: unknown): TInput;
@@ -386,6 +413,7 @@ export type AgentOptions<TContext = unknown> = {
     maxTurns?: number;
     thinkingConfig?: ThinkingConfig;
     tools?: Array<ToolDefinition<any, TContext>>;
+    toolBatchPolicy?: ToolBatchPolicy<TContext>;
     skills?: SkillDefinition[];
     workspace?: AgentWorkspaceOptions;
     permission?: (request: PermissionRequest) => Promise<PermissionDecision> | PermissionDecision;
@@ -490,6 +518,10 @@ export declare class MaxTurnsError extends AgentSDKError {
 }
 export declare class AbortError extends AgentSDKError {
 }
+export declare class ToolBatchRejectedError extends AgentSDKError {
+    readonly rejection: ToolBatchPolicyRejection;
+    constructor(rejection: ToolBatchPolicyRejection);
+}
 export declare class ToolPermissionDeniedError extends AgentSDKError {
     readonly denial: PermissionDenial;
     constructor(denial: PermissionDenial);