zidane 3.1.1 → 3.1.2

package/README.md

@@ -15,10 +15,10 @@ Built to be embedded.
 A small, hookable core with sensible defaults so most consumers don't write a single hook. Built around three principles: **token discipline by default** (cache, dedup, compaction, byte-accounting), **self-healing on the fault paths** (auto-coerce args, hallucinated-tool fallback, error rewriting), and **provider parity** (server-side features on Anthropic, client-side equivalents everywhere else).
 
 - 🧠 **Multi-provider, multi-auth** — Anthropic, OpenAI Codex, OpenRouter, Cerebras, plus a generic `openaiCompat` factory (Baseten, Fireworks, Groq, local servers). OAuth + API key, auto-refreshing tokens. Anthropic accepts opt-in `extraBetas` and `contextManagement` for first-party features.
-- 🪝 **Streaming, hookable turn loop** — text/thinking deltas, tool calls, MCP, sessions, skills, spawn, OAuth, validation, budgets — all observable (and most mutatable) via typed hook events.
-- 🛠 **Tools first-class** — `shell`, `read_file`, `write_file`, `edit`, `multi_edit`, `glob`, `grep`, `spawn`, human-in-the-loop, plus any [MCP](https://modelcontextprotocol.io) server. Sequential or parallel, per-call gates (`tool:gate`), validation auto-coerce (`"true"` → `true`), hallucinated-tool fallback (`tool:unknown`), error rewriting (`tool:error` → `result`).
-- ✂️ **Token-aware ergonomics** — paginated reads with a "how to page" footer, 8 KB tail-truncated `shell`, idempotent `write_file`; `outputBytes` surfaced on every tool/MCP hook. `behavior.toolOutputBudget` injects a "summarize" nudge when a turn's outputs exceed the cap.
-- 🗜 **Context discipline** — auto-injected `cache_control` breakpoints (Anthropic + OpenRouter); server-side compaction via `context-management-2025-06-27` on Anthropic, `behavior.compactStrategy: 'tail'` on everyone else. Per-session `read_file` dedup + opt-in `requireReadBeforeEdit` guard kill stale-content edits.
+- 🪝 **Streaming, hookable turn loop** — text/thinking deltas, tool calls, MCP, sessions, skills, spawn, OAuth, validation, budgets — all observable (and most mutatable) via typed hook events. Per-request `system:transform` hook for runtime-derived prompt sections.
+- 🛠 **Tools first-class** — `shell`, `read_file`, `write_file`, `edit`, `multi_edit`, `glob`, `grep`, `spawn`, human-in-the-loop, plus any [MCP](https://modelcontextprotocol.io) server. Sequential or parallel, per-call gates (`tool:gate` with writable `block` / `result` / `runToolCounts`), validation auto-coerce (`"true"` → `true`), hallucinated-tool fallback (`tool:unknown`), error rewriting (`tool:error` → `result`).
+- ✂️ **Token-aware ergonomics** — paginated reads with a "how to page" footer, 8 KB tail-truncated `shell`, idempotent `write_file`; `outputBytes` surfaced on every tool/MCP hook. `behavior.toolOutputBudget` injects a "summarize" nudge when a turn's outputs exceed the cap; `behavior.toolBudgets` caps per-tool call counts (`'steer'` or `'block'`); `behavior.thinkingDecay` tapers reasoning budget per turn.
+- 🗜 **Context discipline** — auto-injected `cache_control` breakpoints (Anthropic + OpenRouter); server-side compaction via `context-management-2025-06-27` on Anthropic, `behavior.compactStrategy: 'tail'` on everyone else. Per-session `read_file` dedup + opt-in `requireReadBeforeEdit` guard kill stale-content edits; `behavior.dedupTools` generalizes the same pattern to arbitrary tools (`todowrite`, `execute_sql`, …).
 - 🎯 **Reasoning + structured output** — thinking levels (`off` / `minimal` / `low` / `medium` / `high` / `adaptive`) with optional exact budgets; force the final answer to a JSON Schema (Zod v4 interop), no brittle parsing.
 - 💾 **Sessions, skills, multimodal** — pluggable session stores (memory / SQLite / remote / file-map), incremental persistence; [Agent Skills](https://agentskills.io/specification) spec-aligned with `allowed-tools` enforcement + resume rehydration; images + documents via `PromptPart[]`, tools can return image blocks routed natively on vision providers or via companion messages elsewhere.
 - 🧵 **Sub-agents + execution contexts** — delegate to child agents with inherited or overridden preset (child events bubble to the parent); run tools in-process, Docker, or any `SandboxProvider` (E2B / Rivet / custom). Parallel MCP bootstrap with `agent.warmup()` + `eager: true` to hide cold starts.
@@ -67,10 +67,13 @@ createAgent({
     maxTurns: 50,                    // max loop iterations
     maxTokens: 16384,                // max tokens per LLM response
     thinkingBudget: 10240,           // exact thinking token budget
+    thinkingDecay: { afterTurn: 5, factor: 0.5, floor: 1024 }, // taper budget per run-relative turn
     cache: true,                     // prompt-cache breakpoints on supported providers (default: true)
     toolOutputBudget: 32768,         // soft per-turn cap on tool-output bytes (off by default)
     dedupReads: true,                // dedup identical re-reads of the same file in `read_file` (default: true)
+    dedupTools: { todowrite: i => JSON.stringify(i.todos) }, // generic per-tool argument dedup
     requireReadBeforeEdit: false,    // refuse `edit` / `multi_edit` against unread or stale files (default: false)
+    toolBudgets: { todowrite: { max: 6, onExceed: 'steer' } }, // per-tool soft call caps
     compactStrategy: 'off',          // client-side tail compaction for non-Anthropic providers — 'off' | 'tail' (default: 'off')
     compactThreshold: 131_072,       // bytes threshold that triggers tail compaction (default: 128 KiB)
     compactKeepTurns: 4,             // trailing turns left intact during compaction (default: 4)
@@ -162,6 +165,18 @@ Fallback: `params.apiKey` > `params.access` > `ANTHROPIC_API_KEY` env > `.creden
 
 `extraBetas` are merged with the OAuth defaults (`claude-code-20250219`, `oauth-2025-04-20`) and de-duped. `contextManagement` is sent on the request body as `context_management`; pair it with the `context-management-2025-06-27` beta. For non-Anthropic providers, see `behavior.compactStrategy: 'tail'` for the client-side fallback.
 
+`extraBodyParams` is a generic forward-compat pass-through for un-typed Messages API fields. Spread into the request before the typed core, so explicit factory options always win on collision. Use it when Anthropic ships a new beta before zidane has a dedicated knob:
+
+```ts
+anthropic({
+  apiKey: '...',
+  extraBetas: ['some-future-beta'],
+  extraBodyParams: { future_field: { /* ... */ } },
+})
+```
+
+`openaiCompat` accepts the same `extraBodyParams` for OpenAI-style endpoints (e.g. `reasoning_effort`, `metadata`, OpenRouter `provider` routing).
+
 ### OpenRouter
 
 ```ts
@@ -367,15 +382,19 @@ All tool hooks include `turnId` and `callId` for correlation. Typed via `ToolHoo
 
 ```ts
 agent.hooks.hook('tool:gate', (ctx) => {
-  // ctx.turnId, ctx.callId, ctx.name, ctx.input
+  // ctx.turnId, ctx.callId, ctx.name, ctx.input, ctx.runToolCounts
   if (ctx.name === 'shell' && String(ctx.input.command).includes('rm -rf')) {
     ctx.block = true
     ctx.reason = 'dangerous command'
   }
+  // Substitute a successful result without running the tool — mirrors
+  // tool:unknown / tool:error. When both are set, `block` wins.
+  if (ctx.name === 'todowrite' && (ctx.runToolCounts.todowrite ?? 0) > 0)
+    ctx.result = 'Already recorded; no-op.'
 })
 
-agent.hooks.hook('tool:before', (ctx) => { /* ctx.turnId, ctx.callId, ctx.name, ctx.input, ctx.coercions? */ })
-agent.hooks.hook('tool:after', (ctx) => { /* + ctx.result, ctx.outputBytes, ctx.coercions? */ })
+agent.hooks.hook('tool:before', (ctx) => { /* ctx.turnId, ctx.callId, ctx.name, ctx.input, ctx.runToolCounts, ctx.coercions? */ })
+agent.hooks.hook('tool:after', (ctx) => { /* + ctx.result, ctx.outputBytes, ctx.runToolCounts, ctx.coercions? */ })
 agent.hooks.hook('tool:error', (ctx) => {
   // + ctx.error. Mutate ctx.result to substitute the payload sent back to the
   // model in place of the default `Tool error: <msg>` — useful for OSS-model
@@ -434,6 +453,20 @@ agent.hooks.hook('context:transform', (ctx) => {
 })
 ```
 
+### System transform
+
+Mutate the system prompt per request — useful for runtime-derived sections (files already read in the session, live tool budgets, skill activation reminders). Fires after `context:transform`, before the request goes out. `messages` is read-only here.
+
+```ts
+agent.hooks.hook('system:transform', (ctx) => {
+  // ctx.system, ctx.messages (readonly), ctx.turn, ctx.turnId, ctx.session?
+  if (ctx.session && ctx.turn > 1)
+    ctx.system += `\n\n## Reminder: keep responses concise after turn ${ctx.turn}.`
+})
+```
+
+Cache breakpoints land naturally inside the provider after this hook, so repeated turns with the same derived system text still hit the cache.
+
 ### Hook recipes
 
 Three patterns that don't have a built-in default. Copy-paste and tune.
@@ -484,6 +517,12 @@ const agent = createAgent({
 agent.hooks.hook('budget:exceeded', (ctx) => {
   console.warn(`turn ${ctx.turn}: ${ctx.bytes} > ${ctx.budget} bytes`)
 })
+
+agent.hooks.hook('tool-budget:exceeded', (ctx) => {
+  // Per-tool counterpart, fires when `behavior.toolBudgets[ctx.tool]` trips.
+  // ctx.tool, ctx.count, ctx.max, ctx.turnId, ctx.mode ('steer' | 'block')
+  console.warn(`tool ${ctx.tool} hit cap (${ctx.count}/${ctx.max}, mode=${ctx.mode})`)
+})
 ```
 
 ### Client-side context compaction (non-Anthropic)
@@ -510,6 +549,70 @@ Anthropic users should prefer the server-side `context-management-2025-06-27` be
 
 `behavior.requireReadBeforeEdit` (off by default) — `edit` and `multi_edit` reject when the file hasn't been read in the session, or when its on-disk content has drifted since the last read. Eliminates the silent-corruption case where a model edits against bytes it "remembers" but no longer reflect reality. Recommended on for stricter eval-grade runs.
 
+### Generic per-tool dedup
+
+`behavior.dedupTools` extends the read-file pattern to arbitrary tools. Provide a hasher per tool keyed by canonical name; identical inputs replay the prior result without re-running the tool. Requires a session.
+
+The hasher contract has **three return values, three meanings** — pick deliberately:
+
+| Return | Meaning |
+|---|---|
+| non-empty string | Cache key for this call. Equal keys replay the prior result. |
+| `undefined` | **Skip dedup for this call.** Tool runs normally; nothing recorded. |
+| `''` or non-string | Treated as `undefined` (defensive). |
+
+```ts
+behavior: {
+  dedupTools: {
+    // Always cache by full input — every identical re-call dedups.
+    todowrite: input => JSON.stringify(input),
+
+    // Cache by a normalized subset; non-cacheable shapes opt out via `undefined`.
+    execute_sql: (input) => {
+      const q = typeof input.query === 'string' ? input.query.trim().toLowerCase() : undefined
+      if (!q || q.includes('now()') || q.includes('random()')) return undefined
+      return q
+    },
+  },
+}
+```
+
+The `undefined` opt-out is **not** the same as `JSON.stringify(input)` — that would dedup against the verbatim input. Use `undefined` to mean "this specific call is not cacheable" (timestamps baked in, randomness, debug flags).
+
+Tools with side effects or non-deterministic outputs (network, time, randomness) **must not** be listed — there is no safety net beyond the consumer's hasher. For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).
+
+### Per-tool call budgets
+
+`behavior.toolBudgets` caps per-tool calls per run. Two reactions:
+
+- `'steer'` — let the call run, but emit a synthetic user message after the turn nudging the model to commit and finish. Fires once per tool per run.
+- `'block'` — refuse subsequent calls with `Blocked: <reason>`.
+
+```ts
+behavior: {
+  toolBudgets: {
+    todowrite: { max: 6, onExceed: 'steer' },
+    execute_sql: { max: 3, onExceed: 'block' },
+  },
+}
+```
+
+Pass a function for custom messages: `onExceed: ctx => ({ mode: 'steer', message: '...' })`. Subscribe to `tool-budget:exceeded` for telemetry. Counts include dedup hits — by design, since both eat against agent-loop sanity.
+
+### Adaptive thinking budget
+
+`behavior.thinkingDecay` tapers the thinking budget across turns. Late turns are usually checkpoint / cleanup work where reasoning rarely pays for itself.
+
+```ts
+behavior: {
+  thinkingBudget: 8192,
+  thinkingDecay: { afterTurn: 5, factor: 0.5, floor: 1024 },
+  // turn 1-5 → 8192, turn 6 → 4096, turn 7 → 2048, turn 8+ → 1024
+}
+```
+
+Pass a function for arbitrary curves: `thinkingDecay: (turn, base) => base / Math.sqrt(turn)`. No-op when `thinkingBudget` is unset. Honored by every provider that respects `thinkingBudget`.
+
 ## Steering and Follow-up
 
 ### Steering

package/dist/{agent-Cq009tbG.d.ts → agent-C9q5VMGa.d.ts}

@@ -229,6 +229,126 @@ interface AgentBehavior {
      * Default: `true`.
      */
     dedupReads?: boolean;
+    /**
+     * Taper the thinking budget over the course of a run. Late turns are
+     * usually checkpoint / cleanup work where reasoning rarely pays for
+     * itself; early turns benefit most. Two forms:
+     *
+     * - **Struct** — geometric decay starting after `afterTurn`, multiplying by
+     *   `factor` each subsequent turn, clamped to `floor`. Example
+     *   `{ afterTurn: 5, factor: 0.5, floor: 1024 }` with a base budget of 8192:
+     *   turns 1-5 = 8192, turn 6 = 4096, turn 7 = 2048, turn 8+ = 1024.
+     * - **Function** — `(runTurn, baseBudget) => number`. Arbitrary curves;
+     *   `runTurn` is 1-indexed, run-relative (resumed sessions reset).
+     *
+     * No-op when `thinkingBudget` is unset. Honored by every provider that
+     * respects `thinkingBudget` (anthropic legacy enabled+budget path,
+     * adaptive `maxTokensCap`, openai-compat `max_tokens` padding).
+     *
+     * Default: `undefined` (no decay).
+     */
+    thinkingDecay?: {
+        afterTurn: number;
+        factor: number;
+        floor: number;
+    } | ((runTurn: number, baseBudget: number) => number);
+    /**
+     * Per-tool soft call budget for this run. Keyed by **canonical** tool name.
+     * On the first call after the run-cumulative dispatched count for that tool
+     * reaches `max`, the framework fires `onExceed`:
+     *
+     * - `'steer'` (default) — let the call execute, but emit a synthetic user
+     *   message after the turn that nudges the model away from re-calling the
+     *   tool. Reuses the existing post-turn steer pathway used by
+     *   `toolOutputBudget`. Fires `tool-budget:exceeded` with `mode: 'steer'`.
+     * - `'block'` — refuse the call via `tool:gate` `block`. The model sees a
+     *   `Blocked: <reason>` tool result. Fires `tool-budget:exceeded` with
+     *   `mode: 'block'`.
+     * - **Function** — `(ctx) => { mode, message }`. The consumer supplies the
+     *   steering / refusal text and chooses the mode dynamically.
+     *
+     * Counts include both real dispatches and dedup substitutes (Z19 hits).
+     * Excludes calls already blocked by an earlier gate (skill allow-list,
+     * consumer hook). Tool dispatched by spawned subagents has its own per-run
+     * counter — child counts never charge the parent.
+     *
+     * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).
+     *
+     * Atomic in parallel mode: the middleware tracks its own per-tool
+     * approval counter, incremented synchronously at gate-time. A
+     * 4-call parallel batch against `max: 2` will let the first 2 through
+     * and refuse the rest, even though the loop's `runToolCounts` only
+     * propagates between calls (not within a single batch's gate fan-out).
+     *
+     * Default: `undefined` (no budget enforcement).
+     */
+    toolBudgets?: Record<string, {
+        max: number;
+        onExceed?: 'steer' | 'block' | ((ctx: {
+            tool: string;
+            count: number;
+            max: number;
+        }) => {
+            mode: 'steer' | 'block';
+            message: string;
+        });
+    }>;
+    /**
+     * Generic per-tool argument deduplication. Keyed by the tool's **canonical**
+     * name (alias-stable). Each entry is a hasher: `(input) => string | undefined`.
+     *
+     * **Hasher contract** — three return values, three meanings:
+     *
+     * | Return                  | Meaning                                                                |
+     * |-------------------------|------------------------------------------------------------------------|
+     * | a non-empty string      | Cache key for this call. Equal keys (most-recent-only, this session)   |
+     * |                         | replay the prior recorded result without re-dispatching the tool.      |
+     * | `undefined`             | **Skip dedup for this call.** The tool runs normally; nothing recorded.|
+     * | `''` / non-string       | Treated identically to `undefined` (defensive: no dedup, no error).    |
+     *
+     * The `undefined` opt-out is the way to say *"this specific call is not
+     * cacheable"* (timestamps in input, randomness baked in, debug flags). It
+     * is **not** the same as `JSON.stringify(input)` — that would dedup against
+     * the verbatim input. Pick one explicitly:
+     *
+     * ```ts
+     * // Always cache by full input — every identical re-call dedups.
+     * dedupTools: { todowrite: input => JSON.stringify(input) }
+     *
+     * // Cache by a normalized subset; non-cacheable shapes opt out.
+     * dedupTools: {
+     *   execute_sql: (input) => {
+     *     const q = typeof input.query === 'string' ? input.query.trim().toLowerCase() : undefined
+     *     if (!q || q.includes('now()') || q.includes('random()')) return undefined
+     *     return q
+     *   },
+     * }
+     * ```
+     *
+     * On a hit, the previously-recorded result is replayed as the tool_result
+     * without dispatching the tool. The substitution flows through `tool:gate`
+     * `result` (Z20), so `tool:after` and `tool:transform` still fire.
+     *
+     * Requires a session (`createSession()`); without one, the map is a silent
+     * no-op since per-session state has nowhere to live. Tools with side
+     * effects or non-deterministic outputs (network, time, randomness) MUST
+     * NOT be listed — there is no safety net beyond the consumer's hasher.
+     *
+     * For MCP tools, key by the namespaced wire name (`mcp_<server>_<tool>`).
+     * Parallel mode (`toolExecution: 'parallel'`, the default) sees calls in
+     * the SAME assistant turn race against each other — none can dedup against
+     * a sibling that started in the same batch. Sequential mode honors order
+     * within a turn.
+     *
+     * **Cache policy**: only the most recent `(hash, result)` per tool is
+     * retained. Interleaved patterns (input A, input B, input A) miss on the
+     * second A because B overwrote it. Sufficient for the common spam-the-
+     * same-call loop; consumers needing a richer cache should hook
+     * `tool:gate` directly.
+     *
+     * Default: `undefined` (no per-tool dedup).
+     */
+    dedupTools?: Record<string, (input: Record<string, unknown>) => string | undefined>;
     /**
      * Require `read_file` before `edit` / `multi_edit` on the same path, and
      * reject edits when the file has changed on disk since the last read in
@@ -674,6 +794,18 @@ interface AnthropicParams {
      * ```
      */
     contextManagement?: AnthropicContextManagement;
+    /**
+     * Generic pass-through for fields on the Messages API request body that the
+     * SDK does not yet type. Spread into the request before the typed fields,
+     * so explicit options ({@link AnthropicParams.contextManagement} and the
+     * built-in fields like `model` / `tools` / `messages`) win on collision.
+     *
+     * Forward-compat escape hatch for new Anthropic betas — when a future flag
+     * ships before zidane has a dedicated typed knob, set it here without
+     * waiting on a release. Most fields will still need the matching beta in
+     * {@link AnthropicParams.extraBetas}.
+     */
+    extraBodyParams?: Record<string, unknown>;
 }
 declare function anthropic(anthropicParams?: AnthropicParams): Provider;
 
@@ -796,6 +928,17 @@ interface OpenAICompatParams {
      * Default: `false`. The `openrouter` wrapper sets this to `true`.
      */
     cacheBreakpoints?: boolean;
+    /**
+     * Generic pass-through for fields on the Chat Completions request body that
+     * zidane does not yet type. Spread into the request before the typed core
+     * (model / messages / tools / max_tokens / stream / tool_choice), so
+     * explicit options always win on collision.
+     *
+     * Forward-compat escape hatch for endpoints that ship one-off fields ahead
+     * of zidane (e.g. OpenAI `reasoning_effort`, OpenRouter `provider` routing,
+     * vendor-specific `safety_level` knobs).
+     */
+    extraBodyParams?: Record<string, unknown>;
 }
 /**
  * Factory for any OpenAI-compatible HTTP endpoint.
@@ -1557,11 +1700,34 @@ interface AgentHooks {
         turnId: string;
         options: StreamOptions;
     }) => void;
+    /**
+     * Fires after each assistant turn (before its tool-result follow-up
+     * dispatches; the loop iterates back to a fresh `turn:before` once the
+     * tool results are produced).
+     *
+     * `toolCounts.turn` — calls **emitted** by the model in this assistant
+     * turn, keyed by canonical tool name. Reflects what the model asked for,
+     * regardless of downstream gate outcome. Most useful for spotting per-turn
+     * spikes ("the model called todowrite 4 times in one turn").
+     *
+     * `toolCounts.run` — cumulative running counter of **dispatched** calls
+     * scoped to this `runId`, captured at fire time. Excludes calls that were
+     * `block`ed by `tool:gate` handlers. Includes calls short-circuited via
+     * `tool:gate` `result` substitution (the model still asked, the framework
+     * just answered without the tool running). Resumed sessions start a fresh
+     * run with empty counts.
+     *
+     * Both fields are frozen snapshots; mutate-safe.
+     */
     'turn:after': (ctx: {
         turn: number;
         turnId: string;
         usage: TurnUsage;
         message: SessionTurn;
+        toolCounts: {
+            turn: Readonly<Record<string, number>>;
+            run: Readonly<Record<string, number>>;
+        };
     }) => void;
     'stream:text': (ctx: StreamHookContext & {
         delta: string;
@@ -1575,17 +1741,53 @@ interface AgentHooks {
         thinking: string;
     }) => void;
     'oauth:refresh': (ctx: OAuthRefreshHookContext) => void;
+    /**
+     * Fires before validation, `tool:before`, and `execute`. Two ways to
+     * intercept:
+     *
+     * - Set `block = true` (with a `reason`) to refuse the call. The model
+     *   sees a `Blocked: <reason>` tool result; `tool:before` / `tool:after`
+     *   do **not** fire.
+     * - Set `result` to substitute a successful tool_result and skip
+     *   execution. The model sees the substitute as a normal tool_result;
+     *   `tool:before` does not fire, but `tool:after` and `tool:transform`
+     *   do — so byte budgets, telemetry, and post-mutation hooks see the
+     *   substitute. Useful for cache hits, dedup, idempotency guards,
+     *   plan-mode synthetic acks.
+     *
+     * If multiple handlers along the chain set both `block` and `result`,
+     * `block` wins — refusal beats substitution, so a policy gate
+     * (skills allow-list, custom security) can always override an upstream
+     * consumer's cache substitute. Mirrors the writable-`result` shape on
+     * `tool:unknown` and `tool:error` so consumers learn one pattern.
+     *
+     * `runToolCounts` — frozen pre-call snapshot of per-tool dispatched
+     * counts in this run. Use it to self-throttle, drive observability, or
+     * implement budget guards. Counts every call that passed gate, including
+     * dedup substitutes (Z19); excludes `block`ed calls.
+     *
+     * **Parallel mode** (`toolExecution: 'parallel'`, the default): the
+     * snapshot is taken before any dispatches in the batch, so consumer
+     * hooks reading `runToolCounts` see the pre-batch view. Built-in
+     * budget / dedup middleware uses internal per-call reservation, so
+     * `behavior.toolBudgets` enforces atomically even within a parallel
+     * batch.
+     */
     'tool:gate': (ctx: ToolHookContext & {
         block: boolean;
         reason: string;
+        result?: string | ToolResultContent[];
+        runToolCounts: Readonly<Record<string, number>>;
     }) => void;
     'tool:before': (ctx: ToolHookContext & {
         coercions?: readonly string[];
+        runToolCounts: Readonly<Record<string, number>>;
     }) => void;
     'tool:after': (ctx: ToolHookContext & {
         result: string | ToolResultContent[];
         outputBytes: number;
         coercions?: readonly string[];
+        runToolCounts: Readonly<Record<string, number>>;
     }) => void;
     /**
      * Fires when a tool throws during execution. Mutate `result` to substitute a
@@ -1646,6 +1848,27 @@ interface AgentHooks {
     'context:transform': (ctx: {
         messages: SessionMessage[];
     }) => void;
+    /**
+     * Fires per request, after `context:transform` and before the request goes
+     * out. Mutating `ctx.system` updates the system prompt the provider sends
+     * for this turn — useful for runtime-derived sections (e.g. listing files
+     * already read in the session, surfacing live tool budgets, injecting
+     * skill activation reminders).
+     *
+     * Cache breakpoints are applied inside the provider after this hook, so
+     * mutations land in the cache key naturally — repeated turns with the
+     * same derived system text still hit the cache.
+     *
+     * `messages` is read-only here; use `context:transform` for message
+     * surgery. `session` is `undefined` when the run is sessionless.
+     */
+    'system:transform': (ctx: {
+        system: string;
+        messages: readonly SessionMessage[];
+        turn: number;
+        turnId: string;
+        session?: Session;
+    }) => void;
     'steer:inject': (ctx: {
         message: string;
     }) => void;
@@ -1673,6 +1896,7 @@ interface AgentHooks {
     }) => void;
     'child:tool:before': (ctx: ToolHookContext & {
         coercions?: readonly string[];
+        runToolCounts: Readonly<Record<string, number>>;
         childId: string;
         depth: number;
     }) => void;
@@ -1680,6 +1904,7 @@ interface AgentHooks {
         result: string | ToolResultContent[];
         outputBytes: number;
         coercions?: readonly string[];
+        runToolCounts: Readonly<Record<string, number>>;
         childId: string;
         depth: number;
     }) => void;
@@ -1693,6 +1918,10 @@ interface AgentHooks {
         turnId: string;
         usage: TurnUsage;
         message: SessionTurn;
+        toolCounts: {
+            turn: Readonly<Record<string, number>>;
+            run: Readonly<Record<string, number>>;
+        };
         childId: string;
         depth: number;
     }) => void;
@@ -1732,9 +1961,22 @@ interface AgentHooks {
         ok: false;
         error: Error;
     })) => void;
+    /**
+     * MCP-side counterpart of `tool:gate`. Same shape: set `block` to refuse,
+     * set `result` to substitute a successful payload and skip the upstream
+     * MCP `callTool`. When both are set across the handler chain, `block` wins.
+     *
+     * Fires INSIDE the MCP wrapper's `execute`, after the loop's `tool:gate`
+     * already ran. Does **not** carry `runToolCounts` — those are loop-level
+     * and already exposed on `tool:gate` for MCP tools (which are registered
+     * as agent tools under their namespaced name `mcp_<server>_<tool>`). Use
+     * `tool:gate` for budget / dedup logic; reserve `mcp:tool:gate` for
+     * MCP-specific concerns (per-server routing, transport-aware refusals).
+     */
     'mcp:tool:gate': (ctx: McpToolHookContext & {
         block: boolean;
         reason: string;
+        result?: string | ToolResultContent[];
     }) => void;
     'mcp:tool:before': (ctx: McpToolHookContext) => void;
     'mcp:tool:after': (ctx: McpToolHookContext & {
@@ -1785,6 +2027,24 @@ interface AgentHooks {
         bytes: number;
         budget: number;
     }) => void;
+    /**
+     * Fires when a per-tool budget configured via `behavior.toolBudgets` is
+     * exceeded for a specific tool. `mode` reflects how the framework reacted:
+     * `'steer'` lets the call run and queues a post-turn nudge; `'block'`
+     * refuses the call outright with `Blocked: <message>`.
+     *
+     * `count` is the run-cumulative dispatched count just before this call.
+     * Use `turnId` to correlate with `turn:after` if you need the integer turn
+     * index. Distinct from `budget:exceeded` (byte-level) so consumers can
+     * subscribe specifically; both can fire in the same turn.
+     */
+    'tool-budget:exceeded': (ctx: {
+        tool: string;
+        count: number;
+        max: number;
+        turnId: string;
+        mode: 'steer' | 'block';
+    }) => void;
     'agent:abort': (ctx: object) => void;
     'agent:done': (ctx: AgentStats) => void;
     'session:start': (ctx: SessionHookContext & {

package/dist/{chunk-EBSFBIP3.js → chunk-2AE3VM5O.js}

@@ -11,7 +11,7 @@ import {
 } from "./chunk-IUBBVF53.js";
 import {
   connectMcpServers
-} from "./chunk-R74LQKAM.js";
+} from "./chunk-7H34OFDA.js";
 import {
   toolOutputByteLength
 } from "./chunk-JH6IAAFA.js";
@@ -197,6 +197,17 @@ function getReadState(session) {
   }
   return map;
 }
+var TOOL_DEDUP_STATE = /* @__PURE__ */ new WeakMap();
+function getToolDedupState(session) {
+  if (!session)
+    return void 0;
+  let map = TOOL_DEDUP_STATE.get(session);
+  if (!map) {
+    map = /* @__PURE__ */ new Map();
+    TOOL_DEDUP_STATE.set(session, map);
+  }
+  return map;
+}
 function hashContent(text) {
   let h = 2166136261;
   for (let i = 0; i < text.length; i++) {
@@ -1279,6 +1290,59 @@ function rewriteMessagesToWire(messages, maps) {
   return messages.map((msg) => ({ ...msg, content: rewriteContentToWire(msg.content, maps) }));
 }
 
+// src/dedup-tools.ts
+function installDedupToolsGate(hooks, getDedupTools, getSession) {
+  const pending = /* @__PURE__ */ new Map();
+  function pendingKey(callId, name) {
+    return `${callId}::${name}`;
+  }
+  function gateHandler(ctx) {
+    if (ctx.block || ctx.result !== void 0)
+      return;
+    const dedupTools = getDedupTools();
+    const hasher = dedupTools?.[ctx.name];
+    if (!hasher)
+      return;
+    const session = getSession();
+    const state = getToolDedupState(session);
+    if (!state)
+      return;
+    let hash;
+    try {
+      hash = hasher(ctx.input);
+    } catch {
+      return;
+    }
+    if (typeof hash !== "string" || hash.length === 0)
+      return;
+    const prior = state.get(ctx.name);
+    if (prior && prior.hash === hash) {
+      ctx.result = prior.result;
+      return;
+    }
+    pending.set(pendingKey(ctx.callId, ctx.name), hash);
+  }
+  function afterHandler(ctx) {
+    const key = pendingKey(ctx.callId, ctx.name);
+    const hash = pending.get(key);
+    if (hash === void 0)
+      return;
+    pending.delete(key);
+    const session = getSession();
+    const state = getToolDedupState(session);
+    if (!state)
+      return;
+    state.set(ctx.name, { hash, result: ctx.result });
+  }
+  const unregisterGate = hooks.hook("tool:gate", gateHandler);
+  const unregisterAfter = hooks.hook("tool:after", afterHandler);
+  return function uninstall() {
+    unregisterGate();
+    unregisterAfter();
+    pending.clear();
+  };
+}
+
 // src/tools/validation.ts
 var TRUE_STRINGS = /* @__PURE__ */ new Set(["true", "True", "TRUE", "1", "yes", "Yes", "YES"]);
 var FALSE_STRINGS = /* @__PURE__ */ new Set(["false", "False", "FALSE", "0", "no", "No", "NO"]);
@@ -1434,6 +1498,24 @@ function formatValue(value) {
 
 // src/loop.ts
 var IMAGE_OMITTED_MARKER = "[image omitted \u2014 model does not support vision]";
+function applyThinkingDecay(baseBudget, decay, turn) {
+  if (typeof baseBudget !== "number" || baseBudget <= 0)
+    return baseBudget;
+  if (!decay)
+    return baseBudget;
+  let raw;
+  if (typeof decay === "function") {
+    raw = decay(turn, baseBudget);
+  } else {
+    if (turn <= decay.afterTurn)
+      return baseBudget;
+    const k = turn - decay.afterTurn;
+    raw = Math.max(decay.floor, baseBudget * decay.factor ** k);
+  }
+  if (Number.isNaN(raw) || raw <= 0)
+    return 0;
+  return Math.round(Math.min(baseBudget, raw));
+}
 function turnsToMessages(turns) {
   return turns.filter((t) => t.role !== "system").map((t) => ({ role: t.role, content: t.content }));
 }
@@ -1589,6 +1671,7 @@ async function executeTurn(ctx, turn) {
     const keep = typeof ctx.compactKeepTurns === "number" && ctx.compactKeepTurns >= 0 ? ctx.compactKeepTurns : 4;
     sanitizedMessages = applyTailCompaction(sanitizedMessages, threshold, keep);
   }
+  const effectiveThinkingBudget = applyThinkingDecay(ctx.thinkingBudget, ctx.thinkingDecay, turn);
   const streamOptions = {
     model: ctx.model,
     system: ctx.system,
@@ -1596,13 +1679,22 @@ async function executeTurn(ctx, turn) {
     messages: sanitizedMessages,
     maxTokens: ctx.maxTokens ?? 16384,
     thinking: ctx.thinking,
-    thinkingBudget: ctx.thinkingBudget,
+    thinkingBudget: effectiveThinkingBudget,
     cache: ctx.cache ?? true,
     signal: ctx.signal
   };
   const transformCtx = { messages: streamOptions.messages };
   await ctx.hooks.callHook("context:transform", transformCtx);
   streamOptions.messages = transformCtx.messages;
+  const systemCtx = {
+    system: streamOptions.system,
+    messages: streamOptions.messages,
+    turn,
+    turnId,
+    ...ctx.session ? { session: ctx.session } : {}
+  };
+  await ctx.hooks.callHook("system:transform", systemCtx);
+  streamOptions.system = systemCtx.system;
   await ctx.hooks.callHook("turn:before", { turn, turnId, options: streamOptions });
   let currentText = "";
   let currentThinking = "";
@@ -1635,7 +1727,13 @@ async function executeTurn(ctx, turn) {
       createdAt: Date.now()
     };
     ctx.turns.push(errorTurn);
-    await ctx.hooks.callHook("turn:after", { turn, turnId, usage: errorUsage, message: errorTurn });
+    await ctx.hooks.callHook("turn:after", {
+      turn,
+      turnId,
+      usage: errorUsage,
+      message: errorTurn,
+      toolCounts: { turn: Object.freeze({}), run: Object.freeze({ ...ctx.runToolCounts }) }
+    });
     throw wrapProviderError(err, ctx);
   }
   if (currentText) {
@@ -1658,7 +1756,16 @@ async function executeTurn(ctx, turn) {
     createdAt: Date.now()
   };
   ctx.turns.push(assistantTurn);
-  await ctx.hooks.callHook("turn:after", { turn, turnId, usage: result.usage, message: assistantTurn });
+  const turnCounts = {};
+  for (const tc of canonicalToolCalls)
+    turnCounts[tc.name] = (turnCounts[tc.name] ?? 0) + 1;
+  await ctx.hooks.callHook("turn:after", {
+    turn,
+    turnId,
+    usage: result.usage,
+    message: assistantTurn,
+    toolCounts: { turn: Object.freeze(turnCounts), run: Object.freeze({ ...ctx.runToolCounts }) }
+  });
   if (result.done) {
     if (ctx.schema && !ctx.signal.aborted) {
       const outputSpec = {
@@ -1771,6 +1878,7 @@ async function executeSingleTool(ctx, call, turnId) {
   const toolDef = ctx.tools[call.name];
   const callId = call.id;
   const displayName = toWireName(call.name, ctx.aliasMaps);
+  const runToolCounts = Object.freeze({ ...ctx.runToolCounts });
   const gateCtx = {
     turnId,
     callId,
@@ -1778,12 +1886,27 @@ async function executeSingleTool(ctx, call, turnId) {
     displayName,
     input: call.input,
     block: false,
-    reason: "Tool execution was blocked"
+    reason: "Tool execution was blocked",
+    runToolCounts
   };
   await ctx.hooks.callHook("tool:gate", gateCtx);
   if (gateCtx.block) {
     return { result: { id: callId, content: `Blocked: ${gateCtx.reason}` } };
   }
+  ctx.runToolCounts[call.name] = (ctx.runToolCounts[call.name] ?? 0) + 1;
+  if (gateCtx.result !== void 0) {
+    const substitute = await emitToolResult(ctx, {
+      turnId,
+      callId,
+      name: call.name,
+      displayName,
+      input: gateCtx.input,
+      output: gateCtx.result,
+      isError: false,
+      runToolCounts
+    });
+    return { result: { id: callId, content: substitute } };
+  }
   let effectiveInput = gateCtx.input;
   if (!toolDef) {
     const unknownCtx = {
@@ -1841,6 +1964,7 @@ async function executeSingleTool(ctx, call, turnId) {
     name: call.name,
     displayName,
     input: effectiveInput,
+    runToolCounts,
     ...coercions ? { coercions } : {}
   });
   let output;
@@ -1880,12 +2004,29 @@ async function executeSingleTool(ctx, call, turnId) {
     output = errorCtx.result ?? `Tool error: ${error.message}`;
     isError = true;
   }
-  const transformCtx = {
+  const finalOutput = await emitToolResult(ctx, {
     turnId,
     callId,
     name: call.name,
     displayName,
     input: effectiveInput,
+    output,
+    isError,
+    runToolCounts,
+    ...coercions ? { coercions } : {}
+  });
+  return { result: { id: callId, content: finalOutput } };
+}
+async function emitToolResult(ctx, params) {
+  const { turnId, callId, name, displayName, input, runToolCounts, coercions } = params;
+  let output = params.output;
+  let isError = params.isError;
+  const transformCtx = {
+    turnId,
+    callId,
+    name,
+    displayName,
+    input,
     result: output,
     isError,
     outputBytes: toolOutputByteLength(output),
@@ -1898,14 +2039,15 @@ async function executeSingleTool(ctx, call, turnId) {
   await ctx.hooks.callHook("tool:after", {
     turnId,
     callId,
-    name: call.name,
+    name,
     displayName,
-    input: effectiveInput,
+    input,
     result: output,
     outputBytes: toolOutputByteLength(output),
+    runToolCounts,
     ...coercions ? { coercions } : {}
   });
-  return { result: { id: callId, content: output } };
+  return output;
 }
 async function executeToolsSequential(ctx, toolCalls, turnId) {
   const results = [];
@@ -2014,6 +2156,81 @@ function buildPromptMessage(provider, parts) {
   return defaultPromptMessage(parts);
 }
 
+// src/tool-budgets.ts
+function installToolBudgetsGate(hooks, getToolBudgets, enqueueSteer) {
+  const steeredOnce = /* @__PURE__ */ new Set();
+  const approvedCounts = {};
+  async function gateHandler(ctx) {
+    if (ctx.block || ctx.result !== void 0)
+      return;
+    const toolBudgets = getToolBudgets();
+    const budget = toolBudgets?.[ctx.name];
+    if (!budget)
+      return;
+    const max = budget.max;
+    if (typeof max !== "number" || max <= 0)
+      return;
+    const count = approvedCounts[ctx.name] ?? 0;
+    if (count < max) {
+      approvedCounts[ctx.name] = count + 1;
+      return;
+    }
+    const onExceed = budget.onExceed ?? "steer";
+    let mode;
+    let message;
+    if (typeof onExceed === "function") {
+      try {
+        const out = onExceed({ tool: ctx.name, count, max });
+        mode = out.mode;
+        message = out.message;
+      } catch {
+        mode = "steer";
+        message = defaultSteerMessage(ctx.name, count, max);
+      }
+    } else if (onExceed === "block") {
+      mode = "block";
+      message = defaultBlockMessage(ctx.name, max);
+    } else {
+      mode = "steer";
+      message = defaultSteerMessage(ctx.name, count, max);
+    }
+    if (mode === "block") {
+      ctx.block = true;
+      ctx.reason = message;
+      await hooks.callHook("tool-budget:exceeded", {
+        tool: ctx.name,
+        count,
+        max,
+        turnId: ctx.turnId,
+        mode: "block"
+      });
+      return;
+    }
+    if (!steeredOnce.has(ctx.name)) {
+      steeredOnce.add(ctx.name);
+      enqueueSteer(message);
+      await hooks.callHook("tool-budget:exceeded", {
+        tool: ctx.name,
+        count,
+        max,
+        turnId: ctx.turnId,
+        mode: "steer"
+      });
+    }
+  }
+  const unregister = hooks.hook("tool:gate", gateHandler);
+  return function uninstall() {
+    unregister();
+    steeredOnce.clear();
+  };
+}
+function defaultSteerMessage(tool, count, max) {
+  return `[Tool budget reached: '${tool}' has been called ${count} times this run (cap: ${max}). Avoid calling it again unless strictly necessary; commit to a result and move on.]`;
+}
+function defaultBlockMessage(tool, max) {
+  return `Tool '${tool}' has reached its per-run budget of ${max} calls; further invocations are refused.`;
+}
+
 // src/agent.ts
 var HOOK_EVENT_NAMES = [
   "system:before",
@@ -2032,6 +2249,7 @@ var HOOK_EVENT_NAMES = [
   "validation:reject",
   "validation:coerce",
   "context:transform",
+  "system:transform",
   "steer:inject",
   "spawn:before",
   "spawn:complete",
@@ -2060,6 +2278,7 @@ var HOOK_EVENT_NAMES = [
   "usage",
   "output",
   "budget:exceeded",
+  "tool-budget:exceeded",
   "agent:abort",
   "agent:done",
   "session:start",
@@ -2083,7 +2302,12 @@ function resolveBehavior(agentBehavior, runBehavior) {
     toolOutputBudget: runBehavior?.toolOutputBudget ?? agentBehavior?.toolOutputBudget,
     compactStrategy: runBehavior?.compactStrategy ?? agentBehavior?.compactStrategy ?? "off",
     compactThreshold: runBehavior?.compactThreshold ?? agentBehavior?.compactThreshold,
-    compactKeepTurns: runBehavior?.compactKeepTurns ?? agentBehavior?.compactKeepTurns
+    compactKeepTurns: runBehavior?.compactKeepTurns ?? agentBehavior?.compactKeepTurns,
+    thinkingDecay: runBehavior?.thinkingDecay ?? agentBehavior?.thinkingDecay,
+    dedupReads: runBehavior?.dedupReads ?? agentBehavior?.dedupReads,
+    dedupTools: runBehavior?.dedupTools ?? agentBehavior?.dedupTools,
+    requireReadBeforeEdit: runBehavior?.requireReadBeforeEdit ?? agentBehavior?.requireReadBeforeEdit,
+    toolBudgets: runBehavior?.toolBudgets ?? agentBehavior?.toolBudgets
   };
 }
 function createAgent({ provider, name: agentName, system: agentSystem, tools: agentTools, toolAliases, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, mcpConnector, eager }) {
@@ -2206,7 +2430,8 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
     }
     const thinking = options.thinking ?? "off";
     const model = options.model ?? provider.meta.defaultModel;
-    const { toolExecution, maxTurns, maxTokens, thinkingBudget, schema, cache, toolOutputBudget, compactStrategy, compactThreshold, compactKeepTurns } = resolveBehavior(agentBehavior, options.behavior);
+    const resolvedBehavior = resolveBehavior(agentBehavior, options.behavior);
+    const { toolExecution, maxTurns, maxTokens, thinkingBudget, schema, cache, toolOutputBudget, compactStrategy, compactThreshold, compactKeepTurns, thinkingDecay, dedupTools, toolBudgets } = resolvedBehavior;
     let system = options.system || agentSystem || "You are a helpful assistant.";
     if (skillsCatalog) {
       system = `${system}
@@ -2306,6 +2531,16 @@ ${skillsCatalog}`;
       await hooks.callHook("session:end", { sessionId: session.id, runId, status, turnRange: [runTurnStart, turns.length - 1] });
     }
     const uninstallAllowedToolsGate = installAllowedToolsGate(hooks, skillActivationState);
+    const uninstallToolBudgets = installToolBudgetsGate(
+      hooks,
+      () => toolBudgets,
+      (msg) => steeringQueue.push(msg)
+    );
+    const uninstallDedupTools = installDedupToolsGate(
+      hooks,
+      () => dedupTools,
+      () => session ?? void 0
+    );
     const runStartMs = Date.now();
     const runDepth = typeof options.depth === "number" ? options.depth : 0;
     try {
@@ -2318,7 +2553,10 @@ ${skillsCatalog}`;
         agentToolAliases: toolAliases,
         agentMcpServers: mcpServers,
         agentSkills,
-        agentBehavior,
+        // Forward the resolved view (agent + run merged) so per-run overrides
+        // of `dedupReads` / `requireReadBeforeEdit` / etc. are visible to
+        // tools via `ToolContext.behavior`.
+        agentBehavior: resolvedBehavior,
         tools,
         formattedTools,
         aliasMaps,
@@ -2345,7 +2583,9 @@ ${skillsCatalog}`;
         compactStrategy,
         compactThreshold,
         compactKeepTurns,
-        runStartMs
+        ...thinkingDecay !== void 0 ? { thinkingDecay } : {},
+        runStartMs,
+        runToolCounts: {}
       });
       const finalStats = {
         ...stats,
@@ -2387,6 +2627,8 @@ ${skillsCatalog}`;
     } finally {
       await deactivateAllSkills();
       uninstallAllowedToolsGate();
+      uninstallDedupTools();
+      uninstallToolBudgets();
       unregisterSpawnHook();
       unregisterSessionSync?.();
       for (const unregister of perRunUnregisters)

package/dist/{chunk-R74LQKAM.js → chunk-7H34OFDA.js}

@@ -259,6 +259,32 @@ function buildMcpToolDef(config, client, tool, namespacedName, hooks) {
       if (gateCtx.block)
         return `Blocked: ${gateCtx.reason}`;
       const effectiveInput = gateCtx.input;
+      if (gateCtx.result !== void 0) {
+        let substitute = gateCtx.result;
+        const transformCtx = {
+          turnId,
+          callId,
+          server: config.name,
+          tool: tool.name,
+          displayName,
+          input: effectiveInput,
+          result: substitute,
+          outputBytes: toolOutputByteLength(substitute)
+        };
+        await hooks?.callHook("mcp:tool:transform", transformCtx);
+        substitute = transformCtx.result;
+        await hooks?.callHook("mcp:tool:after", {
+          turnId,
+          callId,
+          server: config.name,
+          tool: tool.name,
+          displayName,
+          input: effectiveInput,
+          result: substitute,
+          outputBytes: toolOutputByteLength(substitute)
+        });
+        return substitute;
+      }
       await hooks?.callHook("mcp:tool:before", {
         turnId,
         callId,

package/dist/{chunk-3DUWP7YU.js → chunk-BRMURQA2.js}

@@ -5,7 +5,7 @@ import {
   toAnthropic,
   toolResultsMessage,
   userMessage
-} from "./chunk-VF4A7HAC.js";
+} from "./chunk-YQ7LY6CL.js";
 import {
   matchesContextExceeded
 } from "./chunk-LNN5UTS2.js";
@@ -437,6 +437,11 @@ function anthropic(anthropicParams) {
       const thinking = options.thinking ?? "off";
       const modelId = options.model;
       const params = {
+        // Forward-compat escape hatch for un-typed beta fields. Spread first so
+        // the typed core (model / max_tokens / system / tools / messages /
+        // stream) and the explicit `context_management` below override on
+        // collision — explicit always wins.
+        ...anthropicParams?.extraBodyParams ?? {},
         model: modelId,
         max_tokens: options.maxTokens,
         system,

package/dist/{chunk-ATMVSCGJ.js → chunk-BXO7CZHJ.js}

@@ -6,7 +6,7 @@ import {
   shell,
   spawn,
   writeFile
-} from "./chunk-EBSFBIP3.js";
+} from "./chunk-2AE3VM5O.js";
 
 // src/presets/basic.ts
 var basicTools = { shell, readFile, writeFile, listFiles, edit, multiEdit };

package/dist/{chunk-VF4A7HAC.js → chunk-YQ7LY6CL.js}

@@ -393,6 +393,9 @@ function openaiCompat(params) {
       }
       const maxTokens = options.thinkingBudget ? options.thinkingBudget + options.maxTokens : options.maxTokens;
       const body = {
+        // Spread first so the typed core below wins on collision — explicit
+        // always overrides generic.
+        ...params.extraBodyParams ?? {},
         model: modelId,
         messages,
         max_tokens: maxTokens,

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { d as AgentHooks } from './agent-Cq009tbG.js';
-export { ac as ActivationVia, ad as ActiveSkill, A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, ae as DeactivationReason, af as FileMapAdapter, ag as FileMapStoreOptions, I as ImageContent, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, ah as OpenAICompatAuthHeader, ai as OpenAICompatHttpError, aj as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, J as SessionTurn, ak as SkillActivationState, al as SkillActivationStateOptions, K as SkillConfig, am as SkillDiagnostic, L as SkillResource, an as SkillSource, N as SkillsConfig, Q as SpawnHookContext, T as StreamCallbacks, U as StreamHookContext, V as StreamOptions, W as ThinkingLevel, X as ToolCall, Y as ToolContext, Z as ToolDef, _ as ToolExecutionMode, $ as ToolHookContext, a0 as ToolMap, a1 as ToolResult, a2 as ToolResultContent, a3 as ToolResultImageContent, a4 as ToolResultTextContent, a5 as ToolSpec, a6 as TurnFinishReason, a7 as TurnResult, a8 as TurnUsage, ao as anthropic, ap as autoDetectAndConvert, aq as cerebras, ar as classifyOpenAICompatError, as as connectMcpServers, at as createAgent, au as createFileMapStore, av as createMemoryStore, aw as createRemoteStore, ax as createSession, ay as createSkillActivationState, az as fromAnthropic, aA as fromOpenAI, aB as loadSession, aC as mapOAIFinishReason, a9 as matchesContextExceeded, aD as normalizeMcpBlocks, aE as normalizeMcpServers, aF as openai, aG as openaiCompat, aH as openrouter, aI as resultToString, aJ as toAnthropic, aK as toOpenAI, aL as toTypedError, aa as toolOutputByteLength, ab as toolResultToText } from './agent-Cq009tbG.js';
+import { d as AgentHooks } from './agent-C9q5VMGa.js';
+export { ac as ActivationVia, ad as ActiveSkill, A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, ae as DeactivationReason, af as FileMapAdapter, ag as FileMapStoreOptions, I as ImageContent, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, ah as OpenAICompatAuthHeader, ai as OpenAICompatHttpError, aj as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, J as SessionTurn, ak as SkillActivationState, al as SkillActivationStateOptions, K as SkillConfig, am as SkillDiagnostic, L as SkillResource, an as SkillSource, N as SkillsConfig, Q as SpawnHookContext, T as StreamCallbacks, U as StreamHookContext, V as StreamOptions, W as ThinkingLevel, X as ToolCall, Y as ToolContext, Z as ToolDef, _ as ToolExecutionMode, $ as ToolHookContext, a0 as ToolMap, a1 as ToolResult, a2 as ToolResultContent, a3 as ToolResultImageContent, a4 as ToolResultTextContent, a5 as ToolSpec, a6 as TurnFinishReason, a7 as TurnResult, a8 as TurnUsage, ao as anthropic, ap as autoDetectAndConvert, aq as cerebras, ar as classifyOpenAICompatError, as as connectMcpServers, at as createAgent, au as createFileMapStore, av as createMemoryStore, aw as createRemoteStore, ax as createSession, ay as createSkillActivationState, az as fromAnthropic, aA as fromOpenAI, aB as loadSession, aC as mapOAIFinishReason, a9 as matchesContextExceeded, aD as normalizeMcpBlocks, aE as normalizeMcpServers, aF as openai, aG as openaiCompat, aH as openrouter, aI as resultToString, aJ as toAnthropic, aK as toOpenAI, aL as toTypedError, aa as toolOutputByteLength, ab as toolResultToText } from './agent-C9q5VMGa.js';
 export { createDockerContext, createProcessContext } from './contexts.js';
 export { S as SandboxProvider, c as createSandboxContext } from './sandbox-CLghrTLi.js';
 export { C as ContextCapabilities, a as ContextType, E as ExecResult, b as ExecutionContext, c as ExecutionHandle, S as SpawnConfig } from './types-vA1a_ZX7.js';
 export { Preset, basic, basicTools, definePreset } from './presets.js';
 export { IMPLICITLY_ALLOWED_SKILL_TOOLS, SkillValidationIssue, SkillValidationResult, SourcedScanPath, buildCatalog, defineSkill, discoverSkills, installAllowedToolsGate, interpolateShellCommands, isToolAllowedByUnion, matchesAllowedTool, parseAllowedToolPattern, parseSkillFile, resolveSkills, validateResourcePath, validateSkillForWrite, validateSkillName, writeSkillToDisk, writeSkillsToDisk } from './skills.js';
-export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-Bi6Dklye.js';
-export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, s as spawn, v as validateToolArgs } from './validation-BeQD94ft.js';
+export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-DU0unNP4.js';
+export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, s as spawn, v as validateToolArgs } from './validation-BKA33eqb.js';
 import { Hookable } from 'hookable';
 import '@modelcontextprotocol/sdk/client/index.js';
 

package/dist/index.js

@@ -6,12 +6,12 @@ import {
   cerebras,
   openai,
   openrouter
-} from "./chunk-3DUWP7YU.js";
+} from "./chunk-BRMURQA2.js";
 import {
   basicTools,
   basic_default,
   definePreset
-} from "./chunk-ATMVSCGJ.js";
+} from "./chunk-BXO7CZHJ.js";
 import {
   createAgent,
   createInteractionTool,
@@ -25,7 +25,7 @@ import {
   multiEdit,
   spawn,
   validateToolArgs
-} from "./chunk-EBSFBIP3.js";
+} from "./chunk-2AE3VM5O.js";
 import {
   IMPLICITLY_ALLOWED_SKILL_TOOLS,
   buildCatalog,
@@ -54,7 +54,7 @@ import {
   normalizeMcpBlocks,
   normalizeMcpServers,
   resultToString
-} from "./chunk-R74LQKAM.js";
+} from "./chunk-7H34OFDA.js";
 import {
   toolOutputByteLength,
   toolResultToText
@@ -76,7 +76,7 @@ import {
   openaiCompat,
   toAnthropic,
   toOpenAI
-} from "./chunk-VF4A7HAC.js";
+} from "./chunk-YQ7LY6CL.js";
 import {
   AgentAbortedError,
   AgentContextExceededError,

package/dist/mcp.d.ts

@@ -1,4 +1,4 @@
 import 'hookable';
-export { M as McpConnection, p as McpServerConfig, as as connectMcpServers, aD as normalizeMcpBlocks, aE as normalizeMcpServers, aI as resultToString } from './agent-Cq009tbG.js';
+export { M as McpConnection, p as McpServerConfig, as as connectMcpServers, aD as normalizeMcpBlocks, aE as normalizeMcpServers, aI as resultToString } from './agent-C9q5VMGa.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 import './types-vA1a_ZX7.js';

package/dist/mcp.js

@@ -3,7 +3,7 @@ import {
   normalizeMcpBlocks,
   normalizeMcpServers,
   resultToString
-} from "./chunk-R74LQKAM.js";
+} from "./chunk-7H34OFDA.js";
 import "./chunk-JH6IAAFA.js";
 export {
   connectMcpServers,

package/dist/presets.d.ts

@@ -1,4 +1,4 @@
-import { Z as ToolDef, e as AgentOptions } from './agent-Cq009tbG.js';
+import { Z as ToolDef, e as AgentOptions } from './agent-C9q5VMGa.js';
 import 'hookable';
 import './types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/presets.js

@@ -2,11 +2,11 @@ import {
   basicTools,
   basic_default,
   definePreset
-} from "./chunk-ATMVSCGJ.js";
-import "./chunk-EBSFBIP3.js";
+} from "./chunk-BXO7CZHJ.js";
+import "./chunk-2AE3VM5O.js";
 import "./chunk-TPXPVEH6.js";
 import "./chunk-IUBBVF53.js";
-import "./chunk-R74LQKAM.js";
+import "./chunk-7H34OFDA.js";
 import "./chunk-JH6IAAFA.js";
 import "./chunk-LNN5UTS2.js";
 export {

package/dist/providers.d.ts

@@ -1,4 +1,4 @@
-export { j as AnthropicParams, k as CerebrasParams, ah as OpenAICompatAuthHeader, ai as OpenAICompatHttpError, aj as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, w as Provider, x as ProviderCapabilities, T as StreamCallbacks, V as StreamOptions, X as ToolCall, a1 as ToolResult, a5 as ToolSpec, a7 as TurnResult, ao as anthropic, aq as cerebras, ar as classifyOpenAICompatError, aC as mapOAIFinishReason, aF as openai, aG as openaiCompat, aH as openrouter } from './agent-Cq009tbG.js';
+export { j as AnthropicParams, k as CerebrasParams, ah as OpenAICompatAuthHeader, ai as OpenAICompatHttpError, aj as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, w as Provider, x as ProviderCapabilities, T as StreamCallbacks, V as StreamOptions, X as ToolCall, a1 as ToolResult, a5 as ToolSpec, a7 as TurnResult, ao as anthropic, aq as cerebras, ar as classifyOpenAICompatError, aC as mapOAIFinishReason, aF as openai, aG as openaiCompat, aH as openrouter } from './agent-C9q5VMGa.js';
 import 'hookable';
 import './types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/providers.js

@@ -3,13 +3,13 @@ import {
   cerebras,
   openai,
   openrouter
-} from "./chunk-3DUWP7YU.js";
+} from "./chunk-BRMURQA2.js";
 import {
   OpenAICompatHttpError,
   classifyOpenAICompatError,
   mapOAIFinishReason,
   openaiCompat
-} from "./chunk-VF4A7HAC.js";
+} from "./chunk-YQ7LY6CL.js";
 import "./chunk-LNN5UTS2.js";
 export {
   OpenAICompatHttpError,

package/dist/session/sqlite.d.ts

@@ -1,4 +1,4 @@
-import { H as SessionStore } from '../agent-Cq009tbG.js';
+import { H as SessionStore } from '../agent-C9q5VMGa.js';
 import 'hookable';
 import '../types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-export { o as CreateSessionOptions, af as FileMapAdapter, ag as FileMapStoreOptions, R as RemoteStoreOptions, S as Session, z as SessionContentBlock, B as SessionData, F as SessionMessage, G as SessionRun, H as SessionStore, J as SessionTurn, ap as autoDetectAndConvert, au as createFileMapStore, av as createMemoryStore, aw as createRemoteStore, ax as createSession, az as fromAnthropic, aA as fromOpenAI, aB as loadSession, aJ as toAnthropic, aK as toOpenAI } from './agent-Cq009tbG.js';
+export { o as CreateSessionOptions, af as FileMapAdapter, ag as FileMapStoreOptions, R as RemoteStoreOptions, S as Session, z as SessionContentBlock, B as SessionData, F as SessionMessage, G as SessionRun, H as SessionStore, J as SessionTurn, ap as autoDetectAndConvert, au as createFileMapStore, av as createMemoryStore, aw as createRemoteStore, ax as createSession, az as fromAnthropic, aA as fromOpenAI, aB as loadSession, aJ as toAnthropic, aK as toOpenAI } from './agent-C9q5VMGa.js';
 import 'hookable';
 import './types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/session.js

@@ -11,7 +11,7 @@ import {
   fromOpenAI,
   toAnthropic,
   toOpenAI
-} from "./chunk-VF4A7HAC.js";
+} from "./chunk-YQ7LY6CL.js";
 import "./chunk-LNN5UTS2.js";
 export {
   autoDetectAndConvert,

package/dist/{skills-use-Bi6Dklye.d.ts → skills-use-DU0unNP4.d.ts}

@@ -1,4 +1,4 @@
-import { Z as ToolDef, K as SkillConfig, ak as SkillActivationState, d as AgentHooks } from './agent-Cq009tbG.js';
+import { Z as ToolDef, K as SkillConfig, ak as SkillActivationState, d as AgentHooks } from './agent-C9q5VMGa.js';
 import { Hookable } from 'hookable';
 
 /**

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
-import { d as AgentHooks, ak as SkillActivationState, K as SkillConfig, an as SkillSource, am as SkillDiagnostic, N as SkillsConfig } from './agent-Cq009tbG.js';
-export { ac as ActivationVia, ad as ActiveSkill, ae as DeactivationReason, al as SkillActivationStateOptions, L as SkillResource, ay as createSkillActivationState } from './agent-Cq009tbG.js';
+import { d as AgentHooks, ak as SkillActivationState, K as SkillConfig, an as SkillSource, am as SkillDiagnostic, N as SkillsConfig } from './agent-C9q5VMGa.js';
+export { ac as ActivationVia, ad as ActiveSkill, ae as DeactivationReason, al as SkillActivationStateOptions, L as SkillResource, ay as createSkillActivationState } from './agent-C9q5VMGa.js';
 import { Hookable } from 'hookable';
 import { b as ExecutionContext, c as ExecutionHandle } from './types-vA1a_ZX7.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/tools.d.ts

@@ -1,7 +1,7 @@
-export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-Bi6Dklye.js';
-export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, s as spawn, v as validateToolArgs } from './validation-BeQD94ft.js';
-import { Z as ToolDef } from './agent-Cq009tbG.js';
-export { Y as ToolContext, a0 as ToolMap } from './agent-Cq009tbG.js';
+export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-DU0unNP4.js';
+export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, s as spawn, v as validateToolArgs } from './validation-BKA33eqb.js';
+import { Z as ToolDef } from './agent-C9q5VMGa.js';
+export { Y as ToolContext, a0 as ToolMap } from './agent-C9q5VMGa.js';
 import 'hookable';
 import './presets.js';
 import './types-vA1a_ZX7.js';

package/dist/tools.js

@@ -14,10 +14,10 @@ import {
   spawn,
   validateToolArgs,
   writeFile
-} from "./chunk-EBSFBIP3.js";
+} from "./chunk-2AE3VM5O.js";
 import "./chunk-TPXPVEH6.js";
 import "./chunk-IUBBVF53.js";
-import "./chunk-R74LQKAM.js";
+import "./chunk-7H34OFDA.js";
 import "./chunk-JH6IAAFA.js";
 import "./chunk-LNN5UTS2.js";
 export {

package/dist/types.d.ts

@@ -1,7 +1,7 @@
-export { A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, d as AgentHooks, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, l as ChildRunStats, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, I as ImageContent, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, J as SessionTurn, K as SkillConfig, L as SkillResource, N as SkillsConfig, Q as SpawnHookContext, T as StreamCallbacks, U as StreamHookContext, V as StreamOptions, W as ThinkingLevel, X as ToolCall, Y as ToolContext, Z as ToolDef, _ as ToolExecutionMode, $ as ToolHookContext, a0 as ToolMap, a1 as ToolResult, a2 as ToolResultContent, a3 as ToolResultImageContent, a4 as ToolResultTextContent, a5 as ToolSpec, a6 as TurnFinishReason, a7 as TurnResult, a8 as TurnUsage, a9 as matchesContextExceeded, aa as toolOutputByteLength, ab as toolResultToText } from './agent-Cq009tbG.js';
+export { A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, d as AgentHooks, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, l as ChildRunStats, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, I as ImageContent, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, J as SessionTurn, K as SkillConfig, L as SkillResource, N as SkillsConfig, Q as SpawnHookContext, T as StreamCallbacks, U as StreamHookContext, V as StreamOptions, W as ThinkingLevel, X as ToolCall, Y as ToolContext, Z as ToolDef, _ as ToolExecutionMode, $ as ToolHookContext, a0 as ToolMap, a1 as ToolResult, a2 as ToolResultContent, a3 as ToolResultImageContent, a4 as ToolResultTextContent, a5 as ToolSpec, a6 as TurnFinishReason, a7 as TurnResult, a8 as TurnUsage, a9 as matchesContextExceeded, aa as toolOutputByteLength, ab as toolResultToText } from './agent-C9q5VMGa.js';
 export { C as ContextCapabilities, a as ContextType, E as ExecResult, b as ExecutionContext, c as ExecutionHandle, S as SpawnConfig } from './types-vA1a_ZX7.js';
 export { S as SandboxProvider } from './sandbox-CLghrTLi.js';
 export { Preset } from './presets.js';
-export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult } from './validation-BeQD94ft.js';
+export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult } from './validation-BKA33eqb.js';
 import 'hookable';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/{validation-BeQD94ft.d.ts → validation-BKA33eqb.d.ts}

@@ -1,4 +1,4 @@
-import { Y as ToolContext, Z as ToolDef, h as AgentStats, l as ChildRunStats } from './agent-Cq009tbG.js';
+import { Y as ToolContext, Z as ToolDef, h as AgentStats, l as ChildRunStats } from './agent-C9q5VMGa.js';
 import { Preset } from './presets.js';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,