@fastagent-sh/fastagent 0.13.0 → 0.14.0

package/dist/engines/pi/auth.js

@@ -12,22 +12,24 @@
  * token and persisting the new one elsewhere leaves global stale for every other consumer.
  *
  * Sharing is still SAFE the right way: point everything at ONE file (`FASTAGENT_AUTH_PATH` → the
- * global path). One file means one refresh lifecycle under `FileAuthStorageBackend`'s cross-process
- * lock (refresh re-reads the latest token under the lock) — the documented same-machine pattern.
+ * global path). One file means one refresh lifecycle under the store's cross-process write lock
+ * (refresh re-reads the latest token under the lock), the documented same-machine pattern.
  * fastagent's store stays SEPARATE from the pi CLI's `~/.pi/agent/auth.json` for the same single-
  * lifecycle reason: two uncoordinated files over one grant would each rotate and break the other.
  *
- * Persistence + locking reuse pi's `FileAuthStorageBackend` (a cross-process file lock) on the WRITE
- * path only. `read` is pi-ai's per-request hot path, so it stays UNLOCKED; the backend's in-place
- * write opens only a sub-millisecond torn-read window, which `read` absorbs by re-reading. The write
- * path refuses to overwrite a corrupt file (never clobbering other providers' credentials).
+ * Locking is vendored here on `proper-lockfile`, with the same parameters pi's file backend used
+ * before pi 0.80.8 stopped exporting it (upstream's stated migration path for SDK consumers is a
+ * custom pi-ai `CredentialStore`, which this file is). The lock guards the WRITE path only. `read`
+ * is pi-ai's per-request hot path, so it stays UNLOCKED; the in-place locked write opens only a
+ * sub-millisecond torn-read window, which `read` absorbs by re-reading. The write path refuses to
+ * overwrite a corrupt file (never clobbering other providers' credentials).
  */
-import { existsSync, readFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { log } from "../../log.js";
 import { setTimeout as sleep } from "node:timers/promises";
-import { FileAuthStorageBackend } from "@earendil-works/pi-coding-agent";
+import lockfile from "proper-lockfile";
 /**
  * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`). The project-level default is
  * `<dir>/.fastagent/auth.json` (computed by the opener and by `fastagent login`); this is only the
@@ -42,57 +44,169 @@ function pick(creds, providerId) {
     const cred = creds[providerId];
     return cred && (cred.type === "oauth" || cred.type === "api_key") ? cred : undefined;
 }
+const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: 0o600 };
 /**
- * Parse the credentials JSON for a WRITE: a corrupt file must THROW — serializing `{}` over it would
- * wipe every other provider's credentials. The throw aborts the locked write, leaving the file intact.
+ * Serialized cross-process read-modify-write of the credentials file: exponential-backoff retries,
+ * 30s staleness, and compromise detection (the parameters pi's `FileAuthStorageBackend` used).
+ * Ensures the file exists first (0700 dir, 0600 file, EXCLUSIVE create: a concurrent first write
+ * must never be clobbered by the init) because `proper-lockfile` locks an existing path. A
+ * compromised lock aborts before the write rather than clobbering a concurrent writer, and a
+ * failed unlock after a successful operation rejects instead of leaving a stale lock silently.
  */
-function parseForWrite(raw, where) {
-    if (!raw)
-        return {};
+async function withLockedAuthFile(authPath, fn) {
+    const dir = dirname(authPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (!existsSync(authPath)) {
+        try {
+            writeFileSync(authPath, "{}", { ...AUTH_FILE_WRITE_OPTIONS, flag: "wx" });
+            chmodSync(authPath, 0o600);
+        }
+        catch (error) {
+            // EEXIST: another process created the file between the existence check and this exclusive
+            // create; its content (possibly already-written credentials) must not be clobbered.
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    let compromised;
+    const throwIfCompromised = () => {
+        if (compromised)
+            throw compromised;
+    };
+    const release = await lockfile.lock(authPath, {
+        retries: { retries: 10, factor: 2, minTimeout: 100, maxTimeout: 10_000, randomize: true },
+        stale: 30_000,
+        onCompromised: (error) => {
+            compromised = error;
+        },
+    });
+    let result;
+    try {
+        throwIfCompromised();
+        const current = existsSync(authPath) ? readFileSync(authPath, "utf8") : undefined;
+        const out = await fn(current);
+        throwIfCompromised();
+        if (out.next !== undefined) {
+            writeFileSync(authPath, out.next, AUTH_FILE_WRITE_OPTIONS);
+            chmodSync(authPath, 0o600);
+        }
+        throwIfCompromised();
+        result = out.result;
+    }
+    catch (error) {
+        // The primary failure stays the signal; unlock noise must not mask it.
+        try {
+            await release();
+        }
+        catch {
+            // Secondary: a compromised or stale-reclaimed lock often cannot release cleanly.
+        }
+        throw error;
+    }
+    // Success path: a failed release is a real cleanup failure (the leftover auth.json.lock stalls
+    // the next writer for the staleness window with zero diagnostics), so it surfaces instead of
+    // resolving a silently degraded operation. A compromise detected after the last in-band check
+    // surfaces here too.
+    try {
+        await release();
+    }
+    catch (releaseError) {
+        if (compromised === undefined)
+            throw releaseError;
+    }
+    throwIfCompromised();
+    return result;
+}
+/**
+ * Decode the credentials JSON, shared by the read and write paths. The root must be a plain
+ * non-null, non-array object: `[]`, `null`, and scalar roots pass JSON.parse but break the record
+ * semantics (an array root even swallows writes, since JSON.stringify drops string keys on arrays).
+ * Structurally invalid = corrupt, exactly like unparsable text.
+ */
+function decodeCreds(raw) {
+    let parsed;
     try {
-        return JSON.parse(raw);
+        parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error(`refusing to overwrite corrupt auth file ${where} — fix or remove it`);
+        return undefined;
     }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    return parsed;
+}
+/**
+ * Tolerant UNLOCKED read of the whole credentials file, shared by `read` and `list`. The only race
+ * is a sub-millisecond in-place write during an OAuth rotation, which can yield an empty/partial
+ * file; re-read a few times before concluding it is corrupt. A missing file reads as undefined
+ * silently (normal not-configured); a valid file returns immediately, so the common case costs one
+ * read.
+ */
+async function readCreds(authPath, warn) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        let raw;
+        try {
+            raw = readFileSync(authPath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined; // missing/deleted
+            warn(`[fastagent] cannot read ${authPath}: ${error.message}`);
+            return undefined;
+        }
+        if (raw !== "") {
+            const creds = decodeCreds(raw);
+            if (creds !== undefined)
+                return creds;
+            // A partial read mid-write parses as garbage; fall through and retry. A structurally invalid
+            // root lands here too and is reported as corrupt below.
+        }
+        if (attempt < 2)
+            await sleep(2);
+    }
+    warn(`[fastagent] corrupt auth file ${authPath}: fix or remove it`);
+    return undefined;
+}
+/**
+ * Parse the credentials JSON for a WRITE: a corrupt file must THROW, because serializing `{}` over
+ * it would wipe every other provider's credentials. The throw aborts the locked write, leaving the
+ * file intact.
+ */
+function parseForWrite(raw, where) {
+    if (!raw)
+        return {};
+    const creds = decodeCreds(raw);
+    if (creds === undefined) {
+        throw new Error(`refusing to overwrite corrupt auth file ${where}: fix or remove it`);
+    }
+    return creds;
 }
 /** A read-write `CredentialStore` backed by the given credentials file (default {@link GLOBAL_AUTH_PATH};
  *  the directory opener passes the project-level `<dir>/.fastagent/auth.json`). */
 export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options = {}) {
     const warn = options.warn ?? ((message) => log.warn(message));
-    const backend = new FileAuthStorageBackend(authPath);
     return {
         async read(providerId) {
-            // UNLOCKED hot path: the only race is a sub-millisecond in-place write during an OAuth rotation,
-            // which can yield an empty/partial file. Re-read a few times before concluding it is corrupt;
-            // a valid `{}` (provider absent) returns immediately, so a not-configured read costs nothing.
-            for (let attempt = 0; attempt < 3; attempt++) {
-                let raw;
-                try {
-                    raw = readFileSync(authPath, "utf8");
-                }
-                catch (error) {
-                    if (error.code === "ENOENT")
-                        return undefined; // missing/deleted
-                    warn(`[fastagent] cannot read ${authPath}: ${error.message}`);
-                    return undefined;
-                }
-                if (raw !== "") {
-                    try {
-                        return pick(JSON.parse(raw), providerId);
-                    }
-                    catch {
-                        // A partial read mid-write parses as garbage — fall through and retry.
-                    }
+            const creds = await readCreds(authPath, warn);
+            return creds ? pick(creds, providerId) : undefined;
+        },
+        async list() {
+            // Metadata only, never secrets (the pi-ai `list` contract). Foreign/old entries are filtered
+            // with the same validation as `read`, so both surfaces agree on what "configured" means.
+            const creds = await readCreds(authPath, warn);
+            if (!creds)
+                return [];
+            const infos = [];
+            for (const [providerId, cred] of Object.entries(creds)) {
+                if (cred && (cred.type === "oauth" || cred.type === "api_key")) {
+                    infos.push({ providerId, type: cred.type });
                 }
-                if (attempt < 2)
-                    await sleep(2);
             }
-            warn(`[fastagent] corrupt auth file ${authPath} — fix or remove it`);
-            return undefined;
+            return infos;
         },
         modify(providerId, fn) {
-            return backend.withLockAsync(async (current) => {
+            return withLockedAuthFile(authPath, async (current) => {
                 const creds = parseForWrite(current, authPath); // corrupt → throw → no clobber
                 const next = await fn(pick(creds, providerId));
                 if (next === undefined)
@@ -102,11 +216,11 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
             });
         },
         async delete(providerId) {
-            // No-op when nothing is stored: do NOT take the lock (which would create the file via the
-            // backend's ensureFileExists) on a machine that never stored this provider.
+            // No-op when nothing is stored: do NOT take the lock (which would create the file) on a
+            // machine that never stored this provider.
             if (!existsSync(authPath))
                 return;
-            await backend.withLockAsync(async (current) => {
+            await withLockedAuthFile(authPath, async (current) => {
                 const creds = parseForWrite(current, authPath);
                 if (!(providerId in creds))
                     return { result: undefined }; // absent: no write

package/dist/engines/pi/chat.js

@@ -28,7 +28,9 @@ import { loadConfig, resolveAgentDir, resolveModel, resolveModelSpec } from "./c
 import { assembleSystemPrompt, piBasePrompt, piDefaultTools, resolveTools } from "./create.js";
 import { createPiModels } from "./models.js";
 import { canonicalPath, loadAgentDefinition } from "./definition.js";
-import { loadTools, mergeDiscoveredTools } from "./tool.js";
+import { isDeferredTool, loadTools, mergeDiscoveredTools } from "./tool.js";
+import { withSearchTool } from "./search-tools.js";
+import { additiveActivation, turnContext } from "./tool-context.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
 /**
  * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools,
@@ -38,6 +40,34 @@ import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollision
 export async function buildChatRuntime(dir, options = {}, 
 /** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
 sessionManager) {
+    /** The turn's {@link ToolActivation} over pi's AgentSession — the chat counterpart of invoke.ts's
+     *  harness bridge, so the SAME builtin search_tools serves both paths. Additive; unknown names
+     *  filtered (`setActiveToolsByName` is authoritative on the session and rebuilds its prompt — our
+     *  static override keeps the prompt identical to serving). */
+    function chatToolActivation(session) {
+        // Same serialization as invoke.ts's bridge (there per turn; here per session — chat turns are
+        // interactive, so per-session is equivalent): the read-modify-write below is only race-free while
+        // nothing awaits between read and write, and pi's session setters happening to be synchronous today
+        // is not a contract worth betting parallel tool batches on. Built ONCE per session (createRuntime),
+        // so parallel calls actually share the chain.
+        let chain = Promise.resolve([]);
+        return {
+            active: () => session.getActiveToolNames(),
+            registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
+            activate(names) {
+                const run = async () => {
+                    const current = session.getActiveToolNames();
+                    const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
+                    if (added.length > 0)
+                        session.setActiveToolsByName([...current, ...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;
+            },
+        };
+    }
     async function resolveAssembly(cwd) {
         const { config } = await loadConfig(cwd);
         const modelSpec = resolveModelSpec(options.model, config);
@@ -55,18 +85,39 @@ sessionManager) {
         // Same tool resolution as the dev opener, then split: defaults go to pi by NAME (rebuilt cwd-bound
         // for rich rendering); customs go through pi's `customTools` path so they survive /new, /resume, fork.
         const discovered = await loadTools(agentDir);
-        const { tools, collisions: crossCollisions } = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
+        const merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
+        // Chat EMULATES deferral, like serving (what you iterate is what you serve): the builtin loader
+        // mounts when a deferred tool exists, the initial active set excludes deferred tools (applied on
+        // the session in createRuntime below — pi's TUI session starts all-active), and the activation
+        // bridge below rides the same turn context the serving path uses, so the SAME search_tools works
+        // against pi's AgentSession instead of fastagent's harness.
+        const tools = withSearchTool(merged.tools);
+        const crossCollisions = merged.collisions;
         reportToolCollisions([...discovered.collisions, ...crossCollisions]);
         reportModuleLoadFailures(discovered.failures);
         const defaultNames = piDefaultTools(cwd).map((t) => t.name);
         const customTools = tools.filter((t) => !defaultNames.includes(t.name));
-        // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts it).
+        // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts
+        // it). Each execute runs inside the turn context with the CURRENT session's activation bridge — the
+        // assembly is memoized across /new//resume/fork rebuilds while the session changes, so the bridge
+        // resolves through sessionRef at call time, exactly like the serving path resolves its harness.
         const customToolDefs = customTools.map((t) => ({
             name: t.name,
             label: t.name,
             description: t.description ?? "",
             parameters: t.parameters,
-            execute: (id, params, signal) => t.execute(id, params, signal),
+            // Propagate the execution mode — an activating tool (the builtin loader) declares "sequential"
+            // so pi serializes its batch; without this, pi's outer active-set diff double-stamps parallels.
+            executionMode: t.executionMode,
+            execute: (id, params, signal) => {
+                const bound = sessionRef.current;
+                // Unreachable by construction (createRuntime sets sessionRef before any turn can run a tool).
+                // Throw rather than silently run outside the turn context — that would disguise a broken
+                // session-lifecycle invariant as a normal out-of-turn call (fail visibly).
+                if (!bound)
+                    throw new Error("chat tool executed before its session was built (lifecycle invariant broken)");
+                return turnContext.run({ session: bound.session.sessionId, tools: bound.activation }, () => t.execute(id, params, signal));
+            },
         }));
         // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including
         // them here would duplicate them).
@@ -82,6 +133,13 @@ sessionManager) {
     // edits. And keep it workspace-scoped — `.env` is process-global, so a switch to another cwd would
     // leak env or require mutating global env at runtime.
     const rootCwd = canonicalPath(dir);
+    // The CURRENT pi session + its activation bridge, BOUND TOGETHER — rebuilt on /new//resume/fork
+    // while the memoized assembly (and its tool execute closures) stays. The bridge must share the
+    // session's lifetime, NOT be rebuilt per tool call (a per-call chain serializes nothing). Note on
+    // parallel batches: pi wraps SDK customTools in its own before/after active-set diff, so an
+    // activating tool must carry `executionMode: "sequential"` (the builtin loader does) — pi then runs
+    // the whole batch serially and the outer diff sees correct snapshots.
+    const sessionRef = {};
     let assembly;
     const assemblyFor = (cwd) => {
         // Canonical paths: pi's process.cwd() fallback is a realpath, so a symlinked workspace would
@@ -135,6 +193,21 @@ sessionManager) {
             tools: [...defaultNames, ...customTools.map((t) => t.name)],
             customTools: customToolDefs,
         });
+        sessionRef.current = { session: result.session, activation: chatToolActivation(result.session) };
+        // Deferral emulation: pi's TUI session starts with everything active — narrow it by SUBTRACTING
+        // the deferred names from whatever is active (robust to pi mounting tools of its own; an
+        // exact-set-equality gate would silently stop narrowing the day pi adds one). Applied on EVERY
+        // build including /resume: pi's chat session does not record activations (its SessionContext has
+        // no activeToolNames), so "restore prior activations" is not implementable here — deferral stays
+        // consistently ON and a resumed conversation re-discovers via search_tools (documented divergence
+        // from serving, where activations persist in the session).
+        const deferredNames = customTools.filter(isDeferredTool).map((t) => t.name);
+        if (deferredNames.length > 0) {
+            const active = result.session.getActiveToolNames();
+            if (deferredNames.some((n) => active.includes(n))) {
+                result.session.setActiveToolsByName(active.filter((n) => !deferredNames.includes(n)));
+            }
+        }
         return { ...result, services, diagnostics: services.diagnostics };
     };
     const runtime = await createAgentSessionRuntime(createRuntime, {

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[];
 }>;
@@ -53,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 /
@@ -90,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,11 +45,30 @@ 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 ───────────────────────────
 //
@@ -69,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.
 
@@ -119,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,
@@ -145,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,
@@ -177,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).