@fastagent-sh/fastagent 0.12.1 → 0.14.0

package/dist/engines/pi/config.d.ts

@@ -1,9 +1,17 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
 import type { AnyModel } from "./harness.ts";
+/** pi's thinking levels (types.d.ts `ThinkingLevel`), as a runtime list for config validation — pi
+ *  exports only the type. A level the selected model does not support is clamped by pi per model. */
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;
+    /** Reasoning effort for the model, pi's scale ("off" | "minimal" | "low" | "medium" | "high" |
+     *  "xhigh" | "max"). Unset = pi's default. Authors tune thinking in the pi TUI while vibing — this
+     *  is the serving-side counterpart (fidelity). Levels a model doesn't support are clamped by pi. */
+    thinkingLevel?: ThinkingLevel;
     /**
      * The agent-definition subdirectory (persona.md, skills/, tools/, channels/), relative to the config
      * file's directory. Default: the config directory itself (flat — today's behaviour). Point it at a
@@ -12,8 +20,9 @@ export interface FastagentConfig {
      * subdir and does not collide with the host's `tools/`/`src/` (core.md scenario grid).
      */
     agentDir?: string;
-    /** Extra custom tools, appended after pi defaults — never replaces them. */
-    tools?: AgentTool[];
+    /** Extra custom tools, appended after pi defaults — never replaces them. `FastagentTool` = AgentTool
+     *  plus the optional `deferred` marker (see defineTool). */
+    tools?: FastagentTool[];
     http?: {
         port?: number;
     };

package/dist/engines/pi/config.js

@@ -19,6 +19,17 @@ import { homedir } from "node:os";
 import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { moduleLoadHint } from "../../loader.js";
+/** pi's thinking levels (types.d.ts `ThinkingLevel`), as a runtime list for config validation — pi
+ *  exports only the type. A level the selected model does not support is clamped by pi per model. */
+export const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
 /** Identity function for typing and IDE completion (vite/next-style). */
 export function defineConfig(config) {
     return config;
@@ -70,17 +81,21 @@ export async function loadConfig(dir) {
     // (`modle:`) must not silently degrade to zero-config.
     for (const key of Object.keys(c)) {
         if (key !== "model" &&
+            key !== "thinkingLevel" &&
             key !== "agentDir" &&
             key !== "tools" &&
             key !== "http" &&
             key !== "deploy" &&
             key !== "selfSchedule") {
-            throw new Error(`${path}: unknown key "${key}" (valid keys: model, agentDir, tools, http, deploy, selfSchedule)`);
+            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, agentDir, tools, http, deploy, selfSchedule)`);
         }
     }
     if (c.model !== undefined && typeof c.model !== "string") {
         throw new Error(`${path}: "model" must be a "provider/modelId" string`);
     }
+    if (c.thinkingLevel !== undefined && !THINKING_LEVELS.includes(c.thinkingLevel)) {
+        throw new Error(`${path}: "thinkingLevel" must be one of ${THINKING_LEVELS.join(", ")}`);
+    }
     if (c.agentDir !== undefined && typeof c.agentDir !== "string") {
         throw new Error(`${path}: "agentDir" must be a string (a subdirectory relative to the config file)`);
     }

package/dist/engines/pi/create.d.ts

@@ -1,11 +1,11 @@
-import type { AgentTool, ExecutionEnv, Skill } from "@earendil-works/pi-agent-core";
+import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
 import { type LoadedDefinition } from "./definition.ts";
 import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
-import { type ToolCollision } from "./tool.ts";
+import { type FastagentTool, type ToolCollision } from "./tool.ts";
 import { type Lease } from "./invoke.ts";
 /** pi's core default toolset (read/bash/edit/write), rooted at cwd. */
 export declare function piDefaultTools(cwd: string): AgentTool[];
@@ -19,6 +19,9 @@ export declare function resolveTools(config: FastagentConfig, cwd: string): Agen
 export declare function resolveWorkspaceTools(config: FastagentConfig, agentDir: string, cwd?: string): Promise<{
     tools: AgentTool[];
     toolNames: string[];
+    /** Tools registered but not initially active (defineTool `deferred: true`) — discovered/activated
+     *  via the built-in `search_tools` loader. Surfaced so the operator can see deferral took effect. */
+    deferredToolNames: string[];
     toolCollisions: ToolCollision[];
     toolFailures: ModuleLoadFailure[];
 }>;
@@ -46,7 +49,6 @@ export interface AssembleSystemPromptOptions {
     /** ③ Skills for the <available_skills> listing. */
     skills?: Skill[];
     /** ④ Env context, caller-provided (keeps this function pure). Omitted = segment omitted. */
-    date?: string;
     cwd?: string;
 }
 export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;
@@ -54,13 +56,16 @@ export declare function assembleSystemPrompt(options: AssembleSystemPromptOption
 export interface CreatePiAgentOptions {
     /** Model spec "provider/modelId" (e.g. "openai-codex/gpt-5.5"), resolved against {@link models}. */
     model: string;
+    /** Reasoning effort (pi's scale). Unset = pi's default; unsupported levels are clamped per model. */
+    thinkingLevel?: ThinkingLevel;
     /**
      * The system prompt itself — verbatim, no engine base and no wrapping (unlike the directory path,
      * which assembles the engine base + AGENTS.md as segment ② + persona.md as segment ①). A plain string
      * or a factory re-evaluated per invoke. When {@link skills} are mounted their listing is appended.
      */
     instructions?: string | (() => string);
-    tools?: AgentTool[];
+    /** `FastagentTool` = AgentTool plus the optional `deferred` marker (see {@link DefineToolOptions}). */
+    tools?: FastagentTool[];
     skills?: Skill[];
     /**
      * Extra providers registered on top of the built-ins — your own gateway / self-hosted endpoint /
@@ -91,11 +96,14 @@ export declare function createPiAgent(options: CreatePiAgentOptions): Agent;
 export interface CreatePiAgentFromDefinitionOptions {
     /** Model spec "provider/modelId", resolved against {@link models}. */
     model: string;
+    /** Reasoning effort (pi's scale). Unset = pi's default; unsupported levels are clamped per model. */
+    thinkingLevel?: ThinkingLevel;
     /** Override the engine base prompt (segment ①). Defaults to piBasePrompt({ tools, persona }) using the
      *  live-read persona.md; pass base to fully opt out of persona.md. */
     base?: string;
-    /** Override tools. Defaults to piDefaultTools (lock down with a custom list). */
-    tools?: AgentTool[];
+    /** Override tools. Defaults to piDefaultTools (lock down with a custom list). `FastagentTool` =
+     *  AgentTool plus the optional `deferred` marker. */
+    tools?: FastagentTool[];
     /**
      * The agent's working directory: where the default tools operate AND whose ancestors are walked for
      * ② project context (AGENTS.md). Defaults to `dir` (flat: the definition dir is also the run root).

package/dist/engines/pi/create.js

@@ -19,7 +19,8 @@ import { piHarnessFactory } from "./harness.js";
 import { createPiModels } from "./models.js";
 import { reportDefinitionWarnings } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
-import { loadTools, mergeDiscoveredTools } from "./tool.js";
+import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
+import { withSearchTool } from "./search-tools.js";
 import { createPiAgentFromHarness } from "./invoke.js";
 // ── §1 tools ─────────────────────────────────────────────────────────────────
 //
@@ -44,20 +45,43 @@ export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
     // Default coding tools (read/bash/edit/write) are rooted at `cwd` (the run root the agent operates on);
     // discovered `tools/` come from `agentDir` (the agent's own surface). They coincide in the flat case.
     const discovered = await loadTools(agentDir);
-    const { tools, collisions } = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
-    const toolCollisions = [...discovered.collisions, ...collisions];
+    const merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
+    // The built-in `search_tools` loader mounts here — the one place the workspace's full tool set is
+    // computed — so `dev`/`start`/`info`/`fastagent tool` all see the same surface (idempotent; a
+    // workspace-defined search_tools wins).
+    const tools = withSearchTool(merged.tools);
+    // Builtin = a search_tools that was ABSENT before withSearchTool (a reference compare would misfire
+    // on the deferred-authored-loader case, where withSearchTool returns a new array without adding one).
+    const builtinLoaderMounted = !merged.tools.some((t) => t.name === "search_tools") && tools.some((t) => t.name === "search_tools");
+    const toolCollisions = [...discovered.collisions, ...merged.collisions];
+    // `toolNames` is the AUTHOR's active-by-default surface (config.tools + tools/): exclude pi
+    // defaults, the builtin loader (like wake, a builtin gets its own report line, not an anonymous
+    // slot in the author's list — an author-DEFINED search_tools still shows), and deferred tools —
+    // each name lives in exactly ONE report slot, and deferred names live in `deferredToolNames`.
     const defaultNames = new Set(piDefaultTools(cwd).map((t) => t.name));
-    const toolNames = tools.map((t) => t.name).filter((n) => !defaultNames.has(n));
-    return { tools, toolNames, toolCollisions, toolFailures: discovered.failures };
+    const toolNames = tools
+        .filter((t) => !defaultNames.has(t.name) && !isDeferredTool(t) && !(builtinLoaderMounted && t.name === "search_tools"))
+        .map((t) => t.name);
+    return {
+        tools,
+        toolNames,
+        deferredToolNames: tools.filter(isDeferredTool).map((t) => t.name),
+        toolCollisions,
+        toolFailures: discovered.failures,
+    };
 }
 // ── §2 prompt: four-segment systemPrompt assembly ───────────────────────────
 //
 //   systemPrompt = ① base (engine asset; a persona.md persona overrides its identity line)
 //                + ② project context (AGENTS.md files via pi's loadProjectContextFiles, <project_context>-wrapped)
-//                + ③ skills listing + ④ env context (date/cwd)
+//                + ③ skills listing + ④ env context (cwd)
 //
-// AGENTS.md ≠ system prompt. Pure functions: segment ④ inputs (date/cwd) are caller-provided, so the
-// same inputs always produce the same prompt (testable, reproducible).
+// AGENTS.md ≠ system prompt. Pure functions: segment ④ input (cwd) is caller-provided, so the
+// same inputs always produce the same prompt (testable, reproducible). No date: a date line would
+// invalidate the provider prompt cache (a prefix cache) for every session at each day boundary —
+// channel sessions routinely live for weeks (pi ≥0.80.7 dropped it from its default prompt for the
+// same reason). The model gets the date when it needs it: `bash date`, and the wake tool takes
+// relative delays ("30m") / cron — never an absolute now-derived instant.
 /**
  * The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two
  * deviations: the pi-TUI docs section is dropped (those paths don't exist in deployments), and the
@@ -65,16 +89,25 @@ export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
  * `persona` (from persona.md) replaces the default identity line, keeping the tools list + guidelines.
  */
 export function piBasePrompt(options = {}) {
-    const tools = options.tools ?? [];
+    const mounted = options.tools ?? [];
+    // Deferred tools stay OUT of the list: their schemas are not in the request until activated, so
+    // naming them here would invite calls to tools that don't exist yet; discovery is search_tools' job
+    // (which IS listed — it's active). Computed from the static mounted set, so the prompt — the cached
+    // context prefix — does not change when a tool is activated mid-session.
+    const tools = mounted.filter((t) => !isDeferredTool(t));
+    const deferredCount = mounted.length - tools.length;
     const toolsList = tools.length > 0 ? tools.map((t) => `- ${t.name}: ${(t.description ?? "").split("\n")[0]}`).join("\n") : "(none)";
     // Segment ① identity: an authored persona (persona.md) replaces the default engine identity line
     // (the standalone×code-repo cell's persona; core.md §11), keeping the tools list + guidelines below.
     const identity = options.persona?.trim() ||
         "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.";
+    const deferredNote = deferredCount > 0
+        ? `\n\n${deferredCount} additional tool(s) are registered but inactive — use search_tools to discover and activate them before concluding a capability is missing.`
+        : "";
     return `${identity}
 
 Available tools:
-${toolsList}
+${toolsList}${deferredNote}
 
 In addition to the tools above, you may have access to other custom tools depending on the project.
 
@@ -96,8 +129,6 @@ export function assembleSystemPrompt(options) {
     if (options.skills && options.skills.length > 0) {
         prompt += `\n${formatSkillsForSystemPrompt(options.skills)}\n`;
     }
-    if (options.date)
-        prompt += `\nCurrent date: ${options.date}`;
     if (options.cwd)
         prompt += `\nCurrent working directory: ${options.cwd}`;
     return prompt;
@@ -117,6 +148,7 @@ function buildPiAgent(opts) {
             env: opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() }),
             models,
             model: resolveModel(models, opts.model),
+            thinkingLevel: opts.thinkingLevel,
             systemPrompt: opts.systemPrompt,
             tools: opts.tools,
             skills: opts.skills,
@@ -143,10 +175,12 @@ function instructionsPrompt(instructions, skills) {
 export function createPiAgent(options) {
     return buildPiAgent({
         model: options.model,
+        thinkingLevel: options.thinkingLevel,
         providers: options.providers,
         authPath: options.authPath,
         systemPrompt: instructionsPrompt(options.instructions, options.skills),
-        tools: options.tools,
+        // Deferred tools need their loader on every rung (idempotent; the caller's own search_tools wins).
+        tools: options.tools ? withSearchTool(options.tools) : options.tools,
         skills: options.skills,
         sessions: options.sessions,
         env: options.env,
@@ -175,9 +209,12 @@ export async function createPiAgentFromDefinition(dir, options) {
     // runtime-written bad skill surfaces the moment it appears, while a static finding does not spam
     // every turn's log. A log-dedup memo, not session state (stateless invoke holds).
     let reportedFindings = findingsSignature(definition);
-    const tools = options.tools ?? piDefaultTools(env.cwd);
+    // Deferred tools need their loader on every rung (idempotent — the workspace opener already applied
+    // it; a caller's own search_tools wins).
+    const tools = withSearchTool(options.tools ?? piDefaultTools(env.cwd));
     const agent = buildPiAgent({
         model: options.model,
+        thinkingLevel: options.thinkingLevel,
         providers: options.providers,
         // Dir-aware default: the same state-root-derived file the opener uses for this dir (the opener
         // passes an explicit authPath, so this only affects direct L2 callers).
@@ -185,7 +222,7 @@ export async function createPiAgentFromDefinition(dir, options) {
         // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills
         // edits (the author's, or the agent's own self-modification) take effect on the next turn with
         // no process restart — restarts are reserved for code (tools/channels/config, module cache).
-        // One read yields prompt AND skills (they can never diverge), `date` is the turn's date, and the
+        // One read yields prompt AND skills (they can never diverge), and the
         // fs cost is a few reads against a model call. Broken edits stay visible: a throw-class problem
         // (unreadable AGENTS.md) fails that turn's invoke, and the loader's NON-fatal findings (bad
         // SKILL.md frontmatter, name collisions — returned as data, not thrown) are warned the moment
@@ -207,7 +244,6 @@ export async function createPiAgentFromDefinition(dir, options) {
                     // ② project context: AGENTS.md files (agentDir + cwd-ancestor walk) via loadProjectContextFiles.
                     contextFiles: def.contextFiles,
                     skills: def.skills,
-                    date: new Date().toISOString().slice(0, 10),
                     cwd: env.cwd,
                 }),
                 skills: def.skills,

package/dist/engines/pi/harness.d.ts

@@ -7,9 +7,20 @@
  * historical entries back into context via buildContext().
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
-import type { AgentTool, ExecutionEnv, Skill } from "@earendil-works/pi-agent-core";
+import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Model, Models } from "@earendil-works/pi-ai";
 import type { PiSessionStore } from "./sessions.ts";
+/**
+ * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
+ * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
+ * `active_tools_change` entries are full active-set SNAPSHOTS (setActiveTools persists everything
+ * active at that moment), and reinterpreting a snapshot as activations would keep a tool active in
+ * old sessions after the author flips it to `deferred` — the session never discovered it. Deltas
+ * carry only what was actually discovered.
+ */
+export declare const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
+export type PiSession = Awaited<ReturnType<PiSessionStore["openOrCreate"]>>;
+export declare function harnessSession(harness: AgentHarness): PiSession | undefined;
 /**
  * pi's Model with the API-shape generic erased — fastagent only passes models through to the
  * harness, so the generic carries no information. One alias keeps the `any` auditable.
@@ -24,6 +35,9 @@ export interface PiHarnessFactoryOptions {
     /** Provider collection for all model requests; {@link model} must belong to it (same provider id). */
     models: Models;
     model: AnyModel;
+    /** Reasoning effort for the model (pi's scale). Unset = fastagent's pinned default ("medium", pi
+     *  TUI parity — see {@link DEFAULT_THINKING_LEVEL}); unsupported levels are clamped by pi per model. */
+    thinkingLevel?: ThinkingLevel;
     tools?: AgentTool[];
     /**
      * Final assembled prompt, or a SYNC factory re-evaluated per invoke (how L1 serves dynamic
@@ -46,5 +60,6 @@ export interface PiHarnessFactoryOptions {
         skills?: Skill[];
     }>;
 }
+export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: AgentTool[], sessionId: string): string[] | undefined;
 /** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
 export declare function piHarnessFactory(options: PiHarnessFactoryOptions): PiHarnessFactory;

package/dist/engines/pi/harness.js

@@ -7,6 +7,25 @@
  * historical entries back into context via buildContext().
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
+import { log } from "../../log.js";
+import { isDeferredTool } from "./tool.js";
+/**
+ * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
+ * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
+ * `active_tools_change` entries are full active-set SNAPSHOTS (setActiveTools persists everything
+ * active at that moment), and reinterpreting a snapshot as activations would keep a tool active in
+ * old sessions after the author flips it to `deferred` — the session never discovered it. Deltas
+ * carry only what was actually discovered.
+ */
+export const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
+/** The session a factory-built harness is bound to — the seam the activation bridge (invoke.ts) uses
+ *  to write {@link TOOL_ACTIVATION_ENTRY} deltas (pi's harness keeps its session private). Absent for
+ *  a harness built outside {@link piHarnessFactory}: activation still works in-turn there, but is not
+ *  recorded — the factory owns persistence. */
+const harnessSessions = new WeakMap();
+export function harnessSession(harness) {
+    return harnessSessions.get(harness);
+}
 /**
  * Provider request retries. The OpenAI-family / Anthropic / Azure / Codex pi-ai adapters
  * implement client-side retries (429/5xx/request-phase network failures with backoff, honoring
@@ -19,23 +38,80 @@ import { AgentHarness } from "@earendil-works/pi-agent-core";
  * so a mid-stream failure surfaces as a `failed` event.
  */
 const PROVIDER_MAX_RETRIES = 2;
+/**
+ * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
+ * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own fallback is "off": an
+ * author vibes at "medium" in pi and must get "medium" when served (fidelity), and pinning the value
+ * here means an upstream default change in either place cannot silently alter deployments. Models
+ * that don't support a level are clamped by pi per model.
+ */
+const DEFAULT_THINKING_LEVEL = "medium";
+/**
+ * Resolve the active-tool set for a fresh harness — the ONE place both fallbacks live. pi's harness
+ * WRITES active-tool changes to the session (`setActiveTools` → `active_tools_change`) but its
+ * constructor never reads them back — pi's long-lived TUI harness keeps the set in memory, while
+ * fastagent builds a FRESH harness per invoke, which would silently reset the session's active set
+ * every turn.
+ *
+ * No record (`null`) → the INITIAL set: every non-deferred tool; undefined when nothing is deferred
+ * (pi's default — all active — applies, and no session entry is ever written; tool-sets without
+ * deferral behave exactly as before deferral existed).
+ *
+ * A record is NOT replayed as a frozen snapshot — the active set is rebuilt as the UNION of the
+ * initial set and the recorded names (filtered to the mounted tools: the constructor THROWS on
+ * unknown names, so a recorded-but-removed tool would otherwise brick every future invoke of that
+ * session). On the serving path only the additive activation bridge writes records, so a record's
+ * real semantic is "which deferred tools this session activated" — layered on top of whatever the
+ * workspace mounts TODAY. A snapshot replay would silently freeze a later-added non-deferred tool
+ * out of every session the loader ever touched. Missing recorded names are logged (fail visibly) —
+ * ONCE per session+missing set: a fresh harness is built per invoke and channel sessions live for
+ * weeks, so an un-deduped warn would repeat every turn and dilute its own signal. A log-dedup memo
+ * (like L2's findings memo), not session state — the resolve stays derived from the session.
+ */
+const warnedRestores = new Set();
+export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
+    const anyDeferred = tools.some(isDeferredTool);
+    const initial = tools.filter((t) => !isDeferredTool(t)).map((t) => t.name);
+    if (recorded === null)
+        return anyDeferred ? initial : undefined;
+    const mounted = new Set(tools.map((t) => t.name));
+    const known = recorded.filter((name) => mounted.has(name));
+    const missing = recorded.filter((name) => !mounted.has(name));
+    if (missing.length > 0) {
+        const emit = warnedRestores.has(`${sessionId}\u0000${missing.join(",")}`) ? log.debug : log.warn;
+        warnedRestores.add(`${sessionId}\u0000${missing.join(",")}`);
+        emit(`[fastagent] session ${sessionId}: dropping recorded activation(s) no longer mounted: ${missing.join(", ")}`);
+    }
+    return [...new Set([...initial, ...known])];
+}
 /** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
 export function piHarnessFactory(options) {
     return async (sessionId) => {
         const session = await options.sessions.openOrCreate(sessionId);
+        // One extra entry walk per invoke to collect the activation deltas — negligible against the model
+        // call, same trade as L2's per-invoke definition re-read. Serving sessions never branch, so a flat
+        // getEntries() read (no leaf-path walk) is correct.
+        const entries = await session.getEntries();
+        const activated = entries.flatMap((e) => e.type === "custom" && e.customType === TOOL_ACTIVATION_ENTRY
+            ? (e.data?.names ?? [])
+            : []);
         const fresh = options.live ? await options.live() : undefined;
         const { systemPrompt } = options;
         const prompt = fresh ? fresh.systemPrompt : typeof systemPrompt === "function" ? systemPrompt() : systemPrompt;
         const skills = fresh ? fresh.skills : options.skills;
-        return new AgentHarness({
+        const harness = new AgentHarness({
             env: options.env,
             session,
             models: options.models,
             model: options.model,
+            thinkingLevel: options.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
             tools: options.tools,
+            activeToolNames: resolveHarnessActiveToolNames(activated.length > 0 ? activated : null, options.tools ?? [], sessionId),
             systemPrompt: prompt,
             resources: skills ? { skills } : undefined,
             streamOptions: { maxRetries: PROVIDER_MAX_RETRIES },
         });
+        harnessSessions.set(harness, session);
+        return harness;
     };
 }

package/dist/engines/pi/invoke.d.ts

@@ -1,6 +1,6 @@
 import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { type Agent, type AgentEvent } from "../../agent.ts";
-import type { PiHarnessFactory } from "./harness.ts";
+import { type PiHarnessFactory } from "./harness.ts";
 export type Release = () => void;
 export interface Lease {
     /** Try to acquire exclusive write access for the session (fail-fast). Returns null if held. */

package/dist/engines/pi/invoke.js

@@ -1,7 +1,8 @@
 import { DEFAULT_COMPACTION_SETTINGS, calculateContextTokens, shouldCompact } from "@earendil-works/pi-agent-core";
 import { SESSION_BUSY_CODE } from "../../agent.js";
 import { log } from "../../log.js";
-import { turnContext } from "./tool-context.js";
+import { TOOL_ACTIVATION_ENTRY, harnessSession } from "./harness.js";
+import { additiveActivation, turnContext } from "./tool-context.js";
 export function inProcessLease() {
     const busy = new Set();
     return {
@@ -129,6 +130,40 @@ export function errorToTerminal(error) {
     const details = error instanceof Error ? error.message : String(error);
     return { type: "failed", details, retryable: classifyRetryable(details, errorSignal(error)) };
 }
+/**
+ * The turn's {@link ToolActivation} over the live harness. `activate` is additive and filters to the
+ * registered names first — pi's `setActiveTools` THROWS on unknown names, and a loader must get a
+ * usable "nothing new" answer, not an exception. pi persists the change in the session, so the
+ * per-invoke restore (harness.ts) carries it into later turns.
+ */
+function toolActivation(harness) {
+    // Serialize activations per turn: "who activated first" must be decided HERE, not by whether pi's
+    // setActiveTools happens to mutate before its first await — parallel tool calls in one batch race
+    // their activate() calls, and the addedToolNames load points must not double-stamp.
+    let chain = Promise.resolve([]);
+    return {
+        active: () => harness.getActiveTools().map((t) => t.name),
+        registered: () => harness.getTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
+        activate(names) {
+            const run = async () => {
+                const current = harness.getActiveTools().map((t) => t.name);
+                const added = additiveActivation(harness.getTools().map((t) => t.name), current, names);
+                if (added.length > 0) {
+                    await harness.setActiveTools([...current, ...added]);
+                    // Persist the DELTA in a dedicated entry — what the per-invoke resolve (harness.ts) reads.
+                    // pi's own active_tools_change record is a full snapshot and is deliberately ignored there.
+                    // Absent session (a harness built outside piHarnessFactory): in-turn activation still works,
+                    // it just isn't durable — the factory owns persistence.
+                    await harnessSession(harness)?.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added });
+                }
+                return added;
+            };
+            const result = chain.then(run, run); // run after the predecessor settles, success or failure
+            chain = result.catch(() => []); // the caller sees a rejection on `result`; the chain stays usable
+            return result;
+        },
+    };
+}
 /**
  * After a successful turn, compact the session if its context has grown past pi's threshold — a long
  * shared (group) or 1:1 conversation otherwise overflows the model's window. pi owns the mechanism
@@ -242,7 +277,7 @@ export function createPiAgentFromHarness(options) {
                 // (turnContext / ToolContext.session). prompt() starts the async work synchronously here, so the
                 // store propagates to the tool calls awaited within it.
                 const opts = await toPiPromptOptions(prompt);
-                const run = turnContext.run({ session: scope.session }, () => harness.prompt(prompt.text, opts));
+                const run = turnContext.run({ session: scope.session, tools: toolActivation(harness) }, () => harness.prompt(prompt.text, opts));
                 yield* queue.drainUntil(run);
                 let terminal;
                 try {

package/dist/engines/pi/login.js

@@ -6,7 +6,7 @@ function anySignal(...signals) {
     return present.length === 0 ? undefined : present.length === 1 ? present[0] : AbortSignal.any(present);
 }
 /**
- * Map pi-ai's `AuthLoginCallbacks` onto the injected {@link LoginIO}. `doneSignal` fires when the flow
+ * Map pi-ai's `AuthInteraction` onto the injected {@link LoginIO}. `doneSignal` fires when the flow
  * resolves, cancelling a prompt the provider left pending (a manual-code paste racing a callback
  * server it just won) so the one-shot CLI exits instead of hanging on stdin.
  */

package/dist/engines/pi/search-tools.d.ts

@@ -0,0 +1,10 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
+export declare function withSearchTool(tools: AgentTool[]): AgentTool[];
+/** Build the `search_tools` loader. Keyword search over the inactive tools' name+description.
+ *
+ * `executionMode: "sequential"` — pi turns any batch containing a sequential tool serial. Required for
+ * correct load-point attribution everywhere an OUTER active-set diff exists: pi wraps SDK customTools
+ * (the chat path) in a before/after diff, and two parallel loader calls would both snapshot the
+ * pre-activation set and get stamped with the same activation. Custom loader authors must set it too. */
+export declare function makeSearchToolsTool(): AgentTool;