jeo-code 0.5.10 → 0.5.13

package/src/agent/loop.ts

@@ -21,6 +21,8 @@ export interface ChatOptions {
   onToken?: (delta: string) => void;
   /** Streaming sink for native reasoning/thinking deltas (drives the dimmed live view). */
   onReasoning?: (delta: string) => void;
+  /** NATIVE tool-calling function declarations (forwarded to capable adapters). */
+  tools?: import("../ai/types").NativeToolSchema[];
 }
 
 const manager = createModelManager();

package/src/agent/tool-schemas.ts

@@ -0,0 +1,132 @@
+import type { NativeToolSchema } from "../ai/types";
+
+/**
+ * Native function-calling schemas for jeo's tools, keyed by canonical tool name.
+ *
+ * The `properties` keys MUST match the argument names the DEFAULT_TOOLS handlers read
+ * (engine.ts) EXACTLY — a renamed parameter would land in a key the handler ignores and
+ * silently no-op the call. The model fills an API-validated schema, so this registry is
+ * the single source of truth for argument names on the native path.
+ */
+const STRING = { type: "string" } as const;
+
+const SCHEMAS: Record<string, NativeToolSchema> = {
+  read: {
+    name: "read",
+    description: "Read a file. Optional lineRange ('a-b','a-','a','a+n','a-b,c-d'); raw=true skips line-number prefixes.",
+    parameters: {
+      type: "object",
+      properties: { filePath: STRING, lineRange: STRING, raw: { type: "boolean" } },
+      required: ["filePath"],
+    },
+  },
+  write: {
+    name: "write",
+    description: "Create or overwrite a file with the given content.",
+    parameters: { type: "object", properties: { filePath: STRING, content: STRING }, required: ["filePath", "content"] },
+  },
+  edit: {
+    name: "edit",
+    description: "Apply a line-anchored edit block to a file (≔A..B replace, ≔A+ insert after, ≔$ append).",
+    parameters: { type: "object", properties: { filePath: STRING, editBlock: STRING }, required: ["filePath", "editBlock"] },
+  },
+  bash: {
+    name: "bash",
+    description: "Run a shell command. Optional timeoutMs, cwd (subdir), env (extra vars).",
+    parameters: {
+      type: "object",
+      properties: { command: STRING, timeoutMs: { type: "number" }, cwd: STRING, env: { type: "object" } },
+      required: ["command"],
+    },
+  },
+  find: {
+    name: "find",
+    description: "Find files by glob pattern.",
+    parameters: { type: "object", properties: { globPattern: STRING }, required: ["globPattern"] },
+  },
+  search: {
+    name: "search",
+    description: "Search file contents by regex (grep). Optional globPattern, ignoreCase, context, maxMatches.",
+    parameters: {
+      type: "object",
+      properties: {
+        pattern: STRING,
+        globPattern: STRING,
+        ignoreCase: { type: "boolean" },
+        context: { type: "number" },
+        maxMatches: { type: "number" },
+      },
+      required: ["pattern"],
+    },
+  },
+  ls: {
+    name: "ls",
+    description: "List a directory's entries (directories first).",
+    parameters: { type: "object", properties: { dirPath: STRING }, required: ["dirPath"] },
+  },
+  mkdir: {
+    name: "mkdir",
+    description: "Create a directory (parents included; idempotent).",
+    parameters: { type: "object", properties: { dirPath: STRING }, required: ["dirPath"] },
+  },
+  delete: {
+    name: "delete",
+    description: "Remove a file, or a directory when recursive=true.",
+    parameters: { type: "object", properties: { path: STRING, recursive: { type: "boolean" } }, required: ["path"] },
+  },
+  web_search: {
+    name: "web_search",
+    description: "Search the web (synthesized answer + sources + citations). Optional recency, limit.",
+    parameters: { type: "object", properties: { query: STRING, recency: STRING, limit: { type: "number" } }, required: ["query"] },
+  },
+  done: {
+    name: "done",
+    description: "Call when the task is fully implemented AND verified. The reason is shown to the user as your message.",
+    parameters: { type: "object", properties: { reason: STRING }, required: [] },
+  },
+};
+
+/**
+ * Build the native tool-schema list for the ACTIVE toolset. Pass the real tool names the
+ * turn is allowed to use (Object.keys of the engine's toolset); `done` is always appended
+ * so the model can signal completion natively. Read-only subagents therefore expose only
+ * their non-mutating tools — never write/edit/bash — on the native channel.
+ */
+export function nativeToolSchemasFor(toolNames: Iterable<string>): NativeToolSchema[] {
+  const out: NativeToolSchema[] = [];
+  const seen = new Set<string>();
+  for (const name of toolNames) {
+    const schema = SCHEMAS[name];
+    if (schema && !seen.has(name)) {
+      out.push(schema);
+      seen.add(name);
+    }
+  }
+  if (!seen.has("done")) out.push(SCHEMAS.done!);
+  return out;
+}
+
+/**
+ * Re-serialize parsed native tool calls into the engine's canonical JSON string. Coalesces
+ * a batched `done` to a single envelope (the engine rejects done-in-batch). Returns null
+ * when there are no calls. Shared by capable provider adapters (antigravity/openai/…).
+ */
+export function serializeToolCalls(calls: { tool: string; arguments: Record<string, unknown> }[]): string | null {
+  // Gemini (antigravity) intermittently namespaces native functions under `default_api`
+  // (e.g. functionCall.name = "default_api.done" / "default_api:done") when handed raw
+  // functionDeclarations, which the engine then rejects as an unknown tool. Strip that
+  // namespace back to the bare tool name so the call dispatches normally.
+  const valid = calls
+    .map(c => ({ ...c, tool: normalizeNativeToolName(c.tool) }))
+    .filter(c => c.tool);
+  if (valid.length === 0) return null;
+  const done = valid.find(c => c.tool === "done");
+  if (done) return JSON.stringify(done);
+  if (valid.length === 1) return JSON.stringify(valid[0]);
+  return JSON.stringify({ tools: valid });
+}
+
+/** Strip the Gemini `default_api.` / `default_api:` namespace prefix from a tool name. */
+export function normalizeNativeToolName(name: string): string {
+  return (name ?? "").replace(/^default_api\s*[.:]\s*/, "").trim();
+}

package/src/agent/tools.ts

@@ -787,9 +787,15 @@ export async function searchTool(
   try {
     const flags = ignoreCase ? "-rnIi" : "-rnI";
     const gi = await readGitignore(cwd);
+    // A gitignore glob like `.*` (or a bare `*`/`**`) is meant to skip dotfiles, but as a
+    // grep --exclude/--exclude-dir it matches the `./`-prefixed traversal paths and silently
+    // excludes EVERY file on BSD grep (the field bug: search returned "No matches found" for
+    // text that existed). Drop these all-matching globs — IGNORED_DIRS still covers the key
+    // dotdirs (.git/.jeo/.next/.cache), and find() is unaffected (it matches via -name).
+    const safeGlob = (g: string) => !/^\.?\*+$/.test(g);
     const excludes = [
-      ...[...IGNORED_DIRS, ...gi.dirs].map(d => `--exclude-dir=${d}`),
-      ...gi.fileGlobs.map(f => `--exclude=${f}`),
+      ...[...IGNORED_DIRS, ...gi.dirs.filter(safeGlob)].map(d => `--exclude-dir=${d}`),
+      ...gi.fileGlobs.filter(safeGlob).map(f => `--exclude=${f}`),
     ];
     const n = (v: unknown): number | undefined =>
       typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;

package/src/ai/model-manager.ts

@@ -306,6 +306,7 @@ async function resolveCall(options: Partial<CallOptions>, kind: "request" | "str
     signal: options.signal,
     reasoningEffort: options.reasoningEffort ?? thinkingToReasoningEffort(config.thinkingLevel),
     onReasoning: options.onReasoning,
+    tools: options.tools,
   };
   // Caller-supplied retry sink rides on the config-derived retry budget so the
   // engine/TUI can surface "rate limited — retrying in Ns" instead of a silent wait.

package/src/ai/providers/anthropic.ts

@@ -115,6 +115,13 @@ export function anthropicPayload(
   };
   if (credential.kind === "oauth") payload.metadata = { user_id: createClaudeCloakingUserId() };
   if (includeTemperature && options.temperature !== undefined) payload.temperature = options.temperature;
+  if (options.tools?.length) {
+    // NATIVE tool-calling: declare jeo's tools as Anthropic functions. tool_choice
+    // "auto" keeps prose-salvage reachable and lets the model call `done` (declared as
+    // a tool) — never "required", which would kill the plain-text final-answer path.
+    payload.tools = options.tools.map(t => ({ name: t.name, description: t.description, input_schema: t.parameters }));
+    payload.tool_choice = { type: "auto" };
+  }
   if (stream) payload.stream = true;
   const system = anthropicSystemBlocks(systemPrompt, model, credential, payload);
   if (system) payload.system = system;
@@ -190,12 +197,36 @@ function emptyCompletionError(stopReason: string | undefined): Error {
     : "";
   return new Error(`Anthropic returned no content${stopReason ? ` (stop_reason=${stopReason})` : ""}${hint}.`);
 }
+
+/**
+ * Re-serialize Anthropic native `tool_use` content block(s) into the engine's canonical
+ * JSON string — the linchpin of the adapter-internal-serialization design: the engine,
+ * anti-spin guards, and done-gate keep consuming the SAME {"tool":...}/{"tools":[...]}
+ * shape they parse from the JSON-in-prose path. A batched `done` is coalesced to a single
+ * done envelope (the engine rejects done-in-batch). Returns null when there is no tool_use.
+ */
+function serializeAnthropicToolUse(
+  content: { type: string; name?: string; input?: unknown }[],
+): string | null {
+  const calls = content
+    .filter(c => c.type === "tool_use" && typeof c.name === "string")
+    .map(c => ({ tool: c.name as string, arguments: (c.input ?? {}) as Record<string, unknown> }));
+  if (calls.length === 0) return null;
+  const done = calls.find(c => c.tool === "done");
+  if (done) return JSON.stringify(done);
+  if (calls.length === 1) return JSON.stringify(calls[0]);
+  return JSON.stringify({ tools: calls });
+}
 export const anthropicAdapter: ProviderAdapter = {
   name: "anthropic",
+  supportsNativeTools: true,
   async call(messages, options, credential) {
     const response = await postAnthropic(messages, options, credential, false);
-    const result = (await response.json()) as { content: { type: string; text: string }[]; stop_reason?: string; usage?: AnthropicUsage };
+    const result = (await response.json()) as { content: { type: string; text?: string; name?: string; input?: unknown }[]; stop_reason?: string; usage?: AnthropicUsage };
     if (result.usage) options.onUsage?.({ inputTokens: totalInputTokens(result.usage), outputTokens: result.usage.output_tokens });
+    // Prefer a native tool call (re-serialized to canonical JSON) over any stray text.
+    const toolCall = serializeAnthropicToolUse(result.content);
+    if (toolCall) return toolCall;
     const text = result.content.find(c => c.type === "text")?.text ?? "";
     if (!text) throw emptyCompletionError(result.stop_reason);
     return text;
@@ -206,10 +237,16 @@ export const anthropicAdapter: ProviderAdapter = {
     let cachedInput: number | undefined;
     let yieldedAny = false;
     let stopReason: string | undefined;
+    // Native tool_use streams as content_block_start (name) + input_json_delta fragments,
+    // never as text_delta — accumulate per block index, then re-serialize to canonical
+    // JSON and yield it once at the end (concatenation still equals call()).
+    const toolBlocks = new Map<number, { name: string; json: string }>();
     for await (const data of readSse(response.body)) {
       let evt: {
         type?: string;
-        delta?: { type?: string; text?: string; stop_reason?: string };
+        index?: number;
+        content_block?: { type?: string; name?: string };
+        delta?: { type?: string; text?: string; partial_json?: string; stop_reason?: string };
         message?: { usage?: AnthropicUsage };
         usage?: { output_tokens?: number };
       };
@@ -218,7 +255,12 @@ export const anthropicAdapter: ProviderAdapter = {
       } catch {
         continue;
       }
-      if (evt.type === "content_block_delta" && evt.delta?.type === "text_delta" && evt.delta.text) {
+      if (evt.type === "content_block_start" && evt.content_block?.type === "tool_use" && typeof evt.index === "number") {
+        toolBlocks.set(evt.index, { name: evt.content_block.name ?? "", json: "" });
+      } else if (evt.type === "content_block_delta" && evt.delta?.type === "input_json_delta" && typeof evt.index === "number") {
+        const b = toolBlocks.get(evt.index);
+        if (b) b.json += evt.delta.partial_json ?? "";
+      } else if (evt.type === "content_block_delta" && evt.delta?.type === "text_delta" && evt.delta.text) {
         yieldedAny = true;
         yield evt.delta.text;
       } else if (evt.type === "message_start" && evt.message?.usage) {
@@ -231,6 +273,21 @@ export const anthropicAdapter: ProviderAdapter = {
         if (evt.usage) options.onUsage?.({ inputTokens: cachedInput, outputTokens: evt.usage.output_tokens });
       }
     }
+    if (toolBlocks.size > 0) {
+      const calls = [...toolBlocks.values()]
+        .map(b => {
+          let args: Record<string, unknown> = {};
+          try { args = b.json ? JSON.parse(b.json) : {}; } catch { args = {}; }
+          return { tool: b.name, arguments: args };
+        })
+        .filter(c => c.tool);
+      if (calls.length > 0) {
+        const done = calls.find(c => c.tool === "done");
+        const envelope = done ? JSON.stringify(done) : calls.length === 1 ? JSON.stringify(calls[0]) : JSON.stringify({ tools: calls });
+        yieldedAny = true;
+        yield envelope;
+      }
+    }
     if (!yieldedAny) throw emptyCompletionError(stopReason);
   },
 };

package/src/ai/providers/antigravity.ts

@@ -3,6 +3,7 @@ import type { Credential } from "../../auth";
 import type { CallOptions, Message, ProviderAdapter } from "../types";
 import { readSse } from "../sse";
 import { providerHttpError } from "./errors";
+import { serializeToolCalls } from "../../agent/tool-schemas";
 
 const ANTIGRAVITY_DAILY_ENDPOINT = "https://daily-cloudcode-pa.googleapis.com";
 const ANTIGRAVITY_SANDBOX_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com";
@@ -136,6 +137,12 @@ export function antigravityRequest(messages: Message[], options: CallOptions, cr
   };
   if (systemPrompt) request.systemInstruction = { role: "user", parts: [{ text: systemPrompt }] };
   if (Object.keys(generationConfig).length > 0) request.generationConfig = generationConfig;
+  if (options.tools?.length) {
+    // NATIVE tool-calling: Gemini functionDeclarations through the CCA proxy. AUTO mode
+    // keeps prose answers + the `done` tool both reachable.
+    request.tools = [{ functionDeclarations: options.tools.map(t => ({ name: t.name, description: t.description, parameters: t.parameters })) }];
+    request.toolConfig = { functionCallingConfig: { mode: "AUTO" } };
+  }
 
   const body = JSON.stringify({
     project,
@@ -160,7 +167,7 @@ export function antigravityRequest(messages: Message[], options: CallOptions, cr
 type CcaUsage = { promptTokenCount?: number; candidatesTokenCount?: number; thoughtsTokenCount?: number };
 interface CcaChunk {
   response?: {
-    candidates?: { content?: { parts?: { text?: string; thought?: boolean }[] }; finishReason?: string }[];
+    candidates?: { content?: { parts?: { text?: string; thought?: boolean; functionCall?: { name?: string; args?: Record<string, unknown> } }[] }; finishReason?: string }[];
     usageMetadata?: CcaUsage;
   };
 }
@@ -174,6 +181,18 @@ function thoughtOf(chunk: CcaChunk): string {
   return chunk.response?.candidates?.[0]?.content?.parts?.filter(p => p.thought).map(p => p.text ?? "").join("") ?? "";
 }
 
+/** Native Gemini functionCall parts (Cloud Code Assist) → {tool, arguments}. */
+function functionCallsOf(chunk: CcaChunk): { tool: string; arguments: Record<string, unknown> }[] {
+  const parts = chunk.response?.candidates?.[0]?.content?.parts ?? [];
+  const out: { tool: string; arguments: Record<string, unknown> }[] = [];
+  for (const p of parts) {
+    if (p.functionCall && typeof p.functionCall.name === "string") {
+      out.push({ tool: p.functionCall.name, arguments: (p.functionCall.args ?? {}) as Record<string, unknown> });
+    }
+  }
+  return out;
+}
+
 async function fetchAntigravity(messages: Message[], options: CallOptions, credential: Credential): Promise<Response> {
   // Resolve the project id up front: stored credential → env → lazy
   // loadCodeAssist/onboardUser discovery (persisted for future sessions).
@@ -191,20 +210,26 @@ async function fetchAntigravity(messages: Message[], options: CallOptions, crede
 
 export const antigravityAdapter: ProviderAdapter = {
   name: "antigravity",
+  supportsNativeTools: true,
   async call(messages, options, credential) {
     const response = await fetchAntigravity(messages, options, credential);
     if (!response.body) return "";
     let out = "";
     let usage: CcaUsage | undefined;
+    const fnCalls: { tool: string; arguments: Record<string, unknown> }[] = [];
     for await (const data of readSse(response.body)) {
       let chunk: CcaChunk;
       try { chunk = JSON.parse(data); } catch { continue; }
       const thought = thoughtOf(chunk);
       if (thought) options.onReasoning?.(thought);
       out += textOf(chunk);
+      fnCalls.push(...functionCallsOf(chunk));
       if (chunk.response?.usageMetadata) usage = chunk.response.usageMetadata;
     }
     if (usage) options.onUsage?.({ inputTokens: usage.promptTokenCount, outputTokens: (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0) });
+    // Prefer a native tool call (re-serialized to canonical JSON) over any stray text.
+    const envelope = serializeToolCalls(fnCalls);
+    if (envelope) return envelope;
     if (!out) throw new Error("Antigravity Cloud Code Assist returned an empty response.");
     return out;
   },
@@ -213,6 +238,7 @@ export const antigravityAdapter: ProviderAdapter = {
     if (!response.body) return;
     let yielded = false;
     let usage: CcaUsage | undefined;
+    const fnCalls: { tool: string; arguments: Record<string, unknown> }[] = [];
     for await (const data of readSse(response.body)) {
       let chunk: CcaChunk;
       try { chunk = JSON.parse(data); } catch { continue; }
@@ -220,9 +246,13 @@ export const antigravityAdapter: ProviderAdapter = {
       if (thought) options.onReasoning?.(thought);
       const delta = textOf(chunk);
       if (delta) { yielded = true; yield delta; }
+      fnCalls.push(...functionCallsOf(chunk));
       if (chunk.response?.usageMetadata) usage = chunk.response.usageMetadata;
     }
     if (usage) options.onUsage?.({ inputTokens: usage.promptTokenCount, outputTokens: (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0) });
+    // Native tool calls have no text deltas — yield the re-serialized envelope once at end.
+    const envelope = serializeToolCalls(fnCalls);
+    if (envelope) { yielded = true; yield envelope; }
     if (!yielded) throw new Error("Antigravity Cloud Code Assist returned an empty response.");
   },
 };

package/src/ai/providers/openai-responses.ts

@@ -14,6 +14,7 @@ import type { Credential } from "../../auth";
 import type { CallOptions, Message } from "../types";
 import { readSse } from "../sse";
 import { providerHttpError } from "./errors";
+import { serializeToolCalls } from "../../agent/tool-schemas";
 
 export const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
 
@@ -63,6 +64,11 @@ export function codexResponsesRequest(
     stream: true, // the Codex backend only streams
     store: false,
   };
+  if (options.tools?.length) {
+    // Responses API function tools (flat shape). tool_choice "auto" keeps prose + `done`.
+    payload.tools = options.tools.map(t => ({ type: "function", name: t.name, description: t.description, parameters: t.parameters, strict: false }));
+    payload.tool_choice = "auto";
+  }
   // Map thinkingLevel → reasoning effort for Codex reasoning models (gjc parity).
   // Drop out-of-enum values instead of forwarding them — the backend 400s on unknown efforts.
   if (options.reasoningEffort && VALID_REASONING_EFFORTS.has(options.reasoningEffort)) {
@@ -87,6 +93,10 @@ export interface ResponsesEvent {
   /** `response.incomplete` cause (e.g. max_output_tokens) — surfaced when the
    *  whole response produced no text (round-5 #1). */
   incompleteReason?: string;
+  /** NATIVE function_call output items (accumulated by the caller across SSE events). */
+  toolCallName?: string;
+  toolCallArgsDelta?: string;
+  toolCallIndex?: number;
 }
 
 /** Parse one Responses SSE `data:` payload into a delta / usage / error. */
@@ -94,6 +104,8 @@ export function parseResponsesEvent(data: string): ResponsesEvent {
   let o: {
     type?: string;
     delta?: unknown;
+    item?: { type?: string; name?: string };
+    output_index?: number;
     response?: {
       usage?: { input_tokens?: number; output_tokens?: number };
       error?: { message?: string };
@@ -106,6 +118,12 @@ export function parseResponsesEvent(data: string): ResponsesEvent {
   } catch {
     return {};
   }
+  if (o.type === "response.output_item.added" && o.item?.type === "function_call") {
+    return { toolCallName: o.item.name, toolCallIndex: o.output_index };
+  }
+  if (o.type === "response.function_call_arguments.delta" && typeof o.delta === "string") {
+    return { toolCallArgsDelta: o.delta, toolCallIndex: o.output_index };
+  }
   if (o.type === "response.output_text.delta" && typeof o.delta === "string") return { delta: o.delta };
   // `response.incomplete` (max_output_tokens / content filter) also carries usage — don't drop it.
   if ((o.type === "response.completed" || o.type === "response.incomplete") && o.response?.usage) {
@@ -120,6 +138,33 @@ export function parseResponsesEvent(data: string): ResponsesEvent {
   return {};
 }
 
+/** Accumulate Responses function_call name + streamed argument fragments by output index. */
+function accumulateResponsesToolCall(acc: Map<number, { name: string; args: string }>, ev: ResponsesEvent): void {
+  if (ev.toolCallName !== undefined) {
+    const i = ev.toolCallIndex ?? 0;
+    const b = acc.get(i) ?? { name: "", args: "" };
+    b.name = ev.toolCallName;
+    acc.set(i, b);
+  }
+  if (ev.toolCallArgsDelta) {
+    const i = ev.toolCallIndex ?? 0;
+    const b = acc.get(i) ?? { name: "", args: "" };
+    b.args += ev.toolCallArgsDelta;
+    acc.set(i, b);
+  }
+}
+
+/** Re-serialize accumulated Responses function calls into the engine's canonical JSON. */
+function serializeResponsesToolCalls(acc: Map<number, { name: string; args: string }>): string | null {
+  if (acc.size === 0) return null;
+  const calls = [...acc.values()].map(b => {
+    let args: Record<string, unknown> = {};
+    try { args = b.args ? JSON.parse(b.args) : {}; } catch { args = {}; }
+    return { tool: b.name, arguments: args };
+  });
+  return serializeToolCalls(calls);
+}
+
 /** Round-5 #1: no-text completions surface their cause instead of returning "". */
 function emptyCompletionError(reason: string | undefined): Error {
   const hint = reason === "max_output_tokens"
@@ -136,13 +181,18 @@ export async function codexResponsesCall(messages: Message[], options: CallOptio
   if (!response.body) return "";
   let out = "";
   let incompleteReason: string | undefined;
+  const toolAcc = new Map<number, { name: string; args: string }>();
   for await (const data of readSse(response.body)) {
     const ev = parseResponsesEvent(data);
     if (ev.delta) out += ev.delta;
+    accumulateResponsesToolCall(toolAcc, ev);
     if (ev.usage) options.onUsage?.(ev.usage);
     if (ev.incompleteReason) incompleteReason = ev.incompleteReason;
     if (ev.error) throw new Error(`OpenAI Codex response failed: ${ev.error}`);
   }
+  // Prefer a native tool call (re-serialized to canonical JSON) over any stray text.
+  const envelope = serializeResponsesToolCalls(toolAcc);
+  if (envelope) return envelope;
   if (!out) throw emptyCompletionError(incompleteReason);
   return out;
 }
@@ -159,15 +209,20 @@ export async function* codexResponsesStream(
   if (!response.body) return;
   let yieldedAny = false;
   let incompleteReason: string | undefined;
+  const toolAcc = new Map<number, { name: string; args: string }>();
   for await (const data of readSse(response.body)) {
     const ev = parseResponsesEvent(data);
     if (ev.delta) {
       yieldedAny = true;
       yield ev.delta;
     }
+    accumulateResponsesToolCall(toolAcc, ev);
     if (ev.usage) options.onUsage?.(ev.usage);
     if (ev.incompleteReason) incompleteReason = ev.incompleteReason;
     if (ev.error) throw new Error(`OpenAI Codex response failed: ${ev.error}`);
   }
+  // Native tool calls have no output_text deltas — yield the re-serialized envelope once.
+  const envelope = serializeResponsesToolCalls(toolAcc);
+  if (envelope) { yieldedAny = true; yield envelope; }
   if (!yieldedAny) throw emptyCompletionError(incompleteReason);
 }

package/src/ai/providers/openai.ts

@@ -3,6 +3,7 @@ import type { CallOptions, Message, ProviderAdapter } from "../types";
 import { readSse } from "../sse";
 import { providerHttpError } from "./errors";
 import { codexResponsesCall, codexResponsesStream } from "./openai-responses";
+import { serializeToolCalls } from "../../agent/tool-schemas";
 
 export function openaiRequest(messages: Message[], options: CallOptions, credential: Credential, stream: boolean): { url: string; headers: Record<string, string>; body: string } {
   const model = options.model.startsWith("openai/") ? options.model.slice(7) : options.model;
@@ -39,7 +40,11 @@ export function openaiRequest(messages: Message[], options: CallOptions, credent
     payload.stream = true;
     payload.stream_options = { include_usage: true };
   }
-  if (options.jsonMode) payload.response_format = { type: "json_object" };
+  if (options.tools?.length) {
+    payload.tools = options.tools.map(t => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.parameters } }));
+    payload.tool_choice = "auto";
+  }
+  if (options.jsonMode && !options.tools?.length) payload.response_format = { type: "json_object" };
   const base = (options.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
   return {
     url: `${base}/chat/completions`,
@@ -59,14 +64,18 @@ function emptyCompletionError(finishReason: string | undefined): Error {
 
 export const openaiAdapter: ProviderAdapter = {
   name: "openai",
+  supportsNativeTools: true,
   async call(messages, options, credential) {
     // ChatGPT/Codex OAuth can't use /chat/completions — route to the Codex Responses backend.
     if (credential.kind === "oauth") return codexResponsesCall(messages, options, credential);
     const { url, headers, body } = openaiRequest(messages, options, credential, false);
     const response = await fetch(url, { method: "POST", headers, body, signal: options.signal });
     if (!response.ok) throw await providerHttpError("OpenAI", response);
-    const result = (await response.json()) as { choices: { message: { content: string }; finish_reason?: string }[]; usage?: { prompt_tokens?: number; completion_tokens?: number } };
+    const result = (await response.json()) as { choices: { message: { content?: string; tool_calls?: { function?: { name?: string; arguments?: string } }[] }; finish_reason?: string }[]; usage?: { prompt_tokens?: number; completion_tokens?: number } };
     if (result.usage) options.onUsage?.({ inputTokens: result.usage.prompt_tokens, outputTokens: result.usage.completion_tokens });
+    // Prefer a native tool call (re-serialized to canonical JSON) over any stray text.
+    const envelope = serializeToolCalls(parseOpenaiToolCalls(result.choices[0]?.message?.tool_calls));
+    if (envelope) return envelope;
     const text = result.choices[0]?.message?.content ?? "";
     if (!text) throw emptyCompletionError(result.choices[0]?.finish_reason);
     return text;
@@ -93,8 +102,9 @@ export const openaiAdapter: ProviderAdapter = {
     if (!response.body) return;
     let yieldedAny = false;
     let finishReason: string | undefined;
+    const toolAcc = new Map<number, { name: string; args: string }>();
     for await (const data of readSse(response.body)) {
-      let chunk: { choices?: { delta?: { content?: string }; finish_reason?: string }[]; usage?: { prompt_tokens?: number; completion_tokens?: number } };
+      let chunk: { choices?: { delta?: { content?: string; tool_calls?: { index?: number; function?: { name?: string; arguments?: string } }[] }; finish_reason?: string }[]; usage?: { prompt_tokens?: number; completion_tokens?: number } };
       try {
         chunk = JSON.parse(data);
       } catch {
@@ -105,13 +115,46 @@ export const openaiAdapter: ProviderAdapter = {
         yieldedAny = true;
         yield delta;
       }
+      const tcs = chunk.choices?.[0]?.delta?.tool_calls;
+      if (tcs) {
+        for (const tc of tcs) {
+          const idx = tc.index ?? 0;
+          const b = toolAcc.get(idx) ?? { name: "", args: "" };
+          if (tc.function?.name) b.name = tc.function.name;
+          if (tc.function?.arguments) b.args += tc.function.arguments;
+          toolAcc.set(idx, b);
+        }
+      }
       if (chunk.choices?.[0]?.finish_reason) finishReason = chunk.choices[0].finish_reason;
       if (chunk.usage) options.onUsage?.({ inputTokens: chunk.usage.prompt_tokens, outputTokens: chunk.usage.completion_tokens });
     }
+    // Native tool calls stream as tool_calls argument fragments — re-serialize once at end.
+    if (toolAcc.size > 0) {
+      const calls = [...toolAcc.values()].map(b => {
+        let args: Record<string, unknown> = {};
+        try { args = b.args ? JSON.parse(b.args) : {}; } catch { args = {}; }
+        return { tool: b.name, arguments: args };
+      });
+      const envelope = serializeToolCalls(calls);
+      if (envelope) { yieldedAny = true; yield envelope; }
+    }
     if (!yieldedAny) throw emptyCompletionError(finishReason);
   },
 };
 
+function parseOpenaiToolCalls(toolCalls: { function?: { name?: string; arguments?: string } }[] | undefined): { tool: string; arguments: Record<string, unknown> }[] {
+  if (!toolCalls?.length) return [];
+  const out: { tool: string; arguments: Record<string, unknown> }[] = [];
+  for (const tc of toolCalls) {
+    const name = tc.function?.name;
+    if (!name) continue;
+    let args: Record<string, unknown> = {};
+    try { args = tc.function?.arguments ? JSON.parse(tc.function.arguments) : {}; } catch { args = {}; }
+    out.push({ tool: name, arguments: args });
+  }
+  return out;
+}
+
 function bearerFor(credential: Credential): string {
   if (credential.kind === "oauth") return credential.token;
   if (credential.kind === "api_key") return credential.token;

package/src/ai/types.ts

@@ -26,6 +26,16 @@ export interface Usage {
   durationMs?: number;
 }
 
+/** Provider-neutral function/tool schema for NATIVE tool-calling. Capable adapters
+ *  (anthropic/openai/gemini) map this onto their wire format (Anthropic input_schema,
+ *  OpenAI function.parameters, Gemini functionDeclarations); fallback adapters
+ *  (antigravity/ollama) ignore it and keep the JSON-in-prose protocol. */
+export interface NativeToolSchema {
+  name: string;
+  description: string;
+  parameters: { type: "object"; properties: Record<string, unknown>; required?: string[] };
+}
+
 export interface CallOptions {
   model: string;
   systemPrompt?: string;
@@ -47,10 +57,19 @@ export interface CallOptions {
    *  answer text). Surfaced as a transient dimmed view; absent for models that emit no
    *  thought text. */
   onReasoning?: (delta: string) => void;
+  /** NATIVE tool-calling: function declarations the model may call. Present only on the
+   *  main agent step (never the prose wrap-up). Adapters with `supportsNativeTools` send
+   *  these on the wire and re-serialize the structured tool call back into the engine's
+   *  canonical {"tool":...}/{"tools":[...]} string; others ignore it. */
+  tools?: NativeToolSchema[];
 }
 
 export interface ProviderAdapter {
   readonly name: ProviderName;
+  /** True when this adapter implements native function-calling (re-serialized to the
+   *  canonical JSON string). When false/absent, `CallOptions.tools` is ignored and the
+   *  model drives tools via the JSON-in-prose protocol. */
+  readonly supportsNativeTools?: boolean;
   /** Local providers ignore the credential argument; cloud adapters require it. */
   call(messages: Message[], options: CallOptions, credential: Credential): Promise<string>;
   /** Optional token streaming. Yields text deltas; concatenation equals the `call()` result. */