@oh-my-pi/pi-agent-core 17.1.5 → 17.1.7

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [17.1.7] - 2026-07-27
+
+### Changed
+
+- `beforeToolCall` now runs during arg-prep in a pre-dispatch prepare phase — on the streamed path before the assistant message's `message_start`/`message_end` are emitted, and always ahead of concurrency resolution, `tool_execution_start`, telemetry span start, and `tool.execute` — instead of inside the already-scheduled execution slot. It receives the resolved `tool` in its context and may return `args` to replace the call's arguments; a replacement is revalidated against the tool schema, written back to the assistant message's tool-call block, and re-resolves argument-dependent interruptibility, making it the single source of truth for history, persistence, provider replay, scheduling, execution events, and `tool.execute`. Argument validation moved into the same prepare phase, so functional `concurrency` resolvers now see validated (and possibly revised) arguments rather than raw pre-validation ones. The hook now receives the run's request abort signal rather than the per-tool signal.
+
+## [17.1.6] - 2026-07-27
+
+### Added
+
+- Added a pre-model-call gate: `AgentLoopConfig.beforeModelCall` receives the finalized provider context and run abort signal, and may return `{ stop: true, reason? }` to end the run before the provider is called, so a host can refuse a request it has decided not to pay for (prompt no longer fits, budget boundary crossed, session should hand off). `Agent.setBeforeModelCall` installs the host callback; `Agent.addBeforeModelCall` registers an additional one without displacing it and returns a disposer. A gate-stopped run retains pending soft tool reminders/escalations and an unserved hard tool choice for the next admitted request; deferred choices are revalidated against active tools and cleared with queued session state ([#6543](https://github.com/can1357/oh-my-pi/pull/6543) by [@paralin](https://github.com/paralin)).
+
+### Changed
+
+- Input message events (prompt, steering, soft reminders) are now emitted once provider-context preparation succeeds, so a pre-model gate can veto the request before any turn opens; gate-stopped and failed runs still commit their accepted inputs ([#6543](https://github.com/can1357/oh-my-pi/pull/6543) by [@paralin](https://github.com/paralin)).
+
 ## [17.1.5] - 2026-07-27
 
 ### Fixed

package/dist/types/agent.d.ts

@@ -2,7 +2,7 @@ import { type ApiKey, type AssistantMessage, type AssistantMessageEvent, type Co
 import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context.js";
-import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideMessage, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
+import type { AgentBeforeModelCall, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideMessage, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
 export declare class AgentBusyError extends Error {
     constructor(message?: string);
 }
@@ -159,6 +159,8 @@ export interface AgentOptions {
     abortOnFabricatedToolResult?: boolean;
     /** Dynamic tool-choice directive (hard {@link ToolChoice} or {@link SoftToolRequirement}), resolved once per turn. */
     getToolChoice?: () => ToolChoiceDirective | undefined;
+    /** Reject a deferred hard choice when its named tool is no longer active. */
+    onToolChoiceUnavailable?: () => void;
     /**
      * Cursor exec handlers for local tool execution.
      */
@@ -374,6 +376,19 @@ export declare class Agent {
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
     setOnTurnEnd(fn: ((messages: AgentMessage[], signal?: AbortSignal, context?: AgentTurnEndContext) => Promise<void> | void) | undefined): void;
+    /**
+     * Install or replace the host pre-model-call gate; pass `undefined` to
+     * remove it. Gates are sampled when a run starts: installing the first
+     * gate while a run is in flight takes effect on the next run.
+     */
+    setBeforeModelCall(fn: AgentBeforeModelCall | undefined): void;
+    /**
+     * Add a pre-model callback without replacing callbacks owned by the host.
+     * Returns a disposer that removes only this callback. Like
+     * {@link setBeforeModelCall}, the first gate installed while a run is in
+     * flight takes effect on the next run.
+     */
+    addBeforeModelCall(fn: AgentBeforeModelCall): () => void;
     /**
      * Provide a source of non-interrupting "aside" messages (e.g. background-job
      * completions, late LSP diagnostics) drained at each step boundary. Never
@@ -408,6 +423,11 @@ export declare class Agent {
     followUp(m: AgentMessage): void;
     clearSteeringQueue(): void;
     clearFollowUpQueue(): void;
+    /**
+     * Drop tool-directive state retained across a gate-stopped run: the
+     * deferred hard choice and the soft-requirement lifecycle.
+     */
+    clearDeferredToolDirectives(): void;
     clearAllQueues(): void;
     hasQueuedMessages(): boolean;
     /** Non-consuming view of the pending steering queue (insertion order, newest

package/dist/types/types.d.ts

@@ -21,6 +21,18 @@ export interface AgentTurnEndContext {
     /** True when the current tool-loop batch is continuing without yielding to post-turn steering. */
     willContinue: boolean;
 }
+export interface AgentPreModelCallStop {
+    /** Stop the agent loop before sending the next provider request. */
+    stop: true;
+    /** Optional owner-facing reason, logged by the loop when it stops. */
+    reason?: string;
+}
+export type AgentPreModelCallResult = AgentPreModelCallStop | undefined;
+/**
+ * A pre-model-call gate. Return {@link AgentPreModelCallStop} to refuse the
+ * request, or nothing to proceed; the signal aborts with the run.
+ */
+export type AgentBeforeModelCall = (context: Context, signal?: AbortSignal) => AgentPreModelCallResult | void | Promise<AgentPreModelCallResult | void>;
 /**
  * A soft tool requirement: the host wants `toolName` called before the loop
  * runs other tools or yields, but WITHOUT paying the forced-`toolChoice` cost
@@ -61,6 +73,12 @@ export interface SoftToolRequirement {
  * (applied verbatim) or a {@link SoftToolRequirement} (remind-then-escalate).
  */
 export type ToolChoiceDirective = ToolChoice | SoftToolRequirement;
+/** Mutable soft-requirement lifecycle retained across stopped agent runs. */
+export interface SoftToolRequirementState {
+    id?: string;
+    forcedToolChoice?: ToolChoice;
+    escalations: number;
+}
 /** True when a {@link ToolChoiceDirective} is a soft requirement, not a hard choice. */
 export declare function isSoftToolRequirement(directive: ToolChoiceDirective | undefined): directive is SoftToolRequirement;
 /** Source category for a queued steering interrupt observed without consuming the queue. */
@@ -230,8 +248,21 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     /**
      * Refreshes prompt/tool context from live session state before each model call.
      * Use this when tool availability or the system prompt can change mid-turn.
+     *
+     * Runs after pending messages are folded in and before provider conversion.
+     * Mutate the agent context here; use `beforeModelCall` to inspect the
+     * provider-bound context.
      */
     syncContextBeforeModelCall?: (context: AgentContext) => void | Promise<void>;
+    /**
+     * Asked after the complete provider context has been built, including
+     * message conversion, provider transforms, normalized tools, and owned
+     * dialect prompt injection. Returning {@link AgentPreModelCallStop} ends
+     * the stream without emitting `turn_start`, so no turn is left open and no
+     * request is billed. Return nothing to proceed. The signal aborts when
+     * the run is canceled or its deadline expires.
+     */
+    beforeModelCall?: AgentBeforeModelCall;
     /**
      * Optional transform applied to tool call arguments before execution.
      * Use for deobfuscating secrets or rewriting arguments.
@@ -304,6 +335,17 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * to the static `toolChoice`.
      */
     getToolChoice?: () => ToolChoiceDirective | undefined;
+    /**
+     * Soft-requirement lifecycle retained by the host when a pre-model-call
+     * gate stops a run before its pending reminder or escalation is served.
+     */
+    softToolRequirementState?: SoftToolRequirementState;
+    /**
+     * Notifies the host that the pre-model-call gate stopped the run after a
+     * hard tool choice was obtained from {@link getToolChoice} but before it
+     * was served, so the host can retain it for the next admitted request.
+     */
+    onToolChoiceRejected?: () => void;
     /**
      * Dynamic reasoning effort override, resolved per LLM call.
      * When set and returns a value, overrides the static `reasoning` captured
@@ -348,15 +390,22 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      */
     getCwd?: () => string | undefined;
     /**
-     * Called after a tool call has been validated and is about to execute.
+     * Called once per tool call after argument validation, in call order, before
+     * the call is scheduled — ahead of concurrency resolution,
+     * `tool_execution_start`, and `tool.execute`. On the streamed path it runs
+     * before the assistant message's `message_start`/`message_end` are emitted.
      *
      * Return `{ block: true }` to prevent execution. The loop emits an error tool
      * result instead (using `reason` as the error text, or a default if omitted).
      *
-     * Mutating `context.args` in place changes the arguments passed to `tool.execute`
-     * — the loop does **not** re-validate after this hook runs.
+     * Return `{ args }` to replace the arguments the call runs with. The
+     * replacement is revalidated against the tool schema and written back to the
+     * tool-call block, making it the single source of truth: history, execution
+     * events, persistence, provider replay, concurrency scheduling, and
+     * `tool.execute` all see the revised arguments. Mutating `context.args` in
+     * place also survives into execution, but a returned `args` object wins.
      *
-     * The hook receives the tool abort signal (`signal`) and is responsible for
+     * The hook receives the run's request abort signal and is responsible for
      * honoring it. Throwing surfaces as a tool-error result and does not abort the
      * rest of the batch.
      */
@@ -435,12 +484,16 @@ export type AgentToolCall = Extract<AssistantMessage["content"][number], {
  * Set `block: true` to prevent the tool from executing. The loop emits an error tool
  * result instead, using `reason` as the error text (or a default if omitted).
  *
- * Mutating the `args` reference passed in `BeforeToolCallContext` is supported and
- * survives into execution — the loop does **not** re-validate after this hook runs.
+ * Set `args` to replace the tool-call arguments. The replacement is revalidated
+ * against the tool schema (a failure surfaces as a validation-error tool result),
+ * written back to the tool-call block on the assistant message, and seen by
+ * history, scheduling, execution events, and `tool.execute` alike. It is
+ * ignored when `block` is true.
  */
 export interface BeforeToolCallResult {
     block?: boolean;
     reason?: string;
+    args?: Record<string, unknown>;
 }
 /**
  * Partial override returned from `afterToolCall`.
@@ -466,9 +519,12 @@ export interface BeforeToolCallContext {
     assistantMessage: AssistantMessage;
     /** The raw tool call block from `assistantMessage.content`. */
     toolCall: AgentToolCall;
+    /** The resolved tool the call dispatches to. */
+    tool: AgentTool<any>;
     /**
      * Validated tool arguments. The same reference is forwarded to `tool.execute`
-     * (after any `transformToolCallArguments` pass), so in-place mutations stick.
+     * (after any `transformToolCallArguments` pass), so in-place mutations stick;
+     * a returned `BeforeToolCallResult.args` replaces them entirely.
      */
     args: Record<string, unknown>;
     /** Current agent context at the time the tool call is prepared. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "17.1.5",
+	"version": "17.1.7",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,12 +35,12 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "17.1.5",
-		"@oh-my-pi/pi-catalog": "17.1.5",
-		"@oh-my-pi/pi-natives": "17.1.5",
-		"@oh-my-pi/pi-utils": "17.1.5",
-		"@oh-my-pi/pi-wire": "17.1.5",
-		"@oh-my-pi/snapcompact": "17.1.5",
+		"@oh-my-pi/pi-ai": "17.1.7",
+		"@oh-my-pi/pi-catalog": "17.1.7",
+		"@oh-my-pi/pi-natives": "17.1.7",
+		"@oh-my-pi/pi-utils": "17.1.7",
+		"@oh-my-pi/pi-wire": "17.1.7",
+		"@oh-my-pi/snapcompact": "17.1.7",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {