@thurstonsand/pi-librarian 0.1.1 → 0.2.0

package/AGENTS.md

@@ -15,7 +15,7 @@ And this doesn't even touch on the advantages of giving the agent an efficient t
 ## Core principles
 
 - Build on pi-native concepts, types, and extension APIs where available; read pi source when helpful
-- The librarian is read-only: no write/edit tools, clones live only in the checkout cache
+- The librarian does not include write/edit tools; clones live only in the checkout cache
 - Prioritize ergonomics of the exposed interaction surface over internal implementation
 
 See @DEV.md for code style and development commands.

package/CONTEXT.md

@@ -3,12 +3,15 @@
 ## Language
 
 **Librarian**:
-The research agent spawned by the `librarian` tool; runs in a nested, in-memory agent session with its own toolset and system prompt.
+The research agent spawned by the `librarian` tool; runs in a nested agent session with its own toolset and system prompt.
 
 **Librarian run**:
 One invocation of the librarian: query in, findings out, with a recorded tool-call trace.
 _Avoid_: session (reserved for pi sessions)
 
+**Run id**:
+The pi session uuid of a librarian run, so that it may be continued for follow up questions.
+
 **Findings**:
 The structured output of a librarian run, produced by `provide_results`: summary, locations, optional description.
 
@@ -16,7 +19,10 @@ The structured output of a librarian run, produced by `provide_results`: summary
 The repository research tools this package registers: `search_repos`, `search_code`, `search_github_code`, `checkout_repo`, `read_github_file`, `provide_results`. Exclusive to librarian runs unless attached.
 
 **Inherited tools**:
-Pi built-ins granted to librarian runs (`read`, `grep`, `find`, `ls`, `bash`) plus tools from allowlisted extensions. Never `write`/`edit`.
+Pi built-ins granted to librarian runs (`read`, `grep`, `find`, `ls`, `bash`); `write`/`edit` are not included.
+
+**Extra tools**:
+Tools made available to the librarian as configured in `librarian.tools` settings, in addition to the **Repo tools** and **Inherited tools**.
 
 **Attach / attached tools**:
 Loading the repo tools into the main pi session via `/librarian`, making them directly usable by the main agent alongside the `librarian` tool.
@@ -26,3 +32,5 @@ _Avoid_: load, enable
 
 - A **Librarian run** ends with exactly one **Findings**, containing zero or more **Locations**.
 - **Attached tools** are the same **Repo tools** a **Librarian** uses, minus `provide_results`.
+- **Extra tools** are only relevant inside librarian runs; **Attach** mode is unaffected because the main session manages its own set of tools.
+- a **Librarian run** is persisted in its own session directory, identified by a **Run id**.

package/README.md

@@ -12,11 +12,19 @@ The `librarian` tool spawns a nested research agent with purpose-built tools:
 - **`search_github_code`** — GitHub REST code search over public code and private repositories your configured GitHub auth can access.
 - **`read_github_file`** — single-file API reads for quick peeks without cloning.
 
-Private repos work through your existing `gh` auth for GitHub-backed tools.
+## GitHub auth for private repos
+
+Public GitHub reads work without configuration. To let the librarian search and read private GitHub repositories, provide a token in one of these ways:
+
+1. Set `GITHUB_TOKEN` or `GH_TOKEN` in the environment before starting pi.
+2. Or authenticate the GitHub CLI so `gh auth token` returns a token:
+
+The token is loaded once per pi session and passed to GitHub REST calls used by `search_repos`, `search_github_code`, `checkout_repo`, and `read_github_file`. For private repositories, use a token with read access to the target repos.
 
 ## Usage
 
 - Ask pi a question involving other repos; it delegates to the `librarian` tool.
+- Ask follow-up questions to earlier librarian runs.
 - `/librarian` attaches the research tools directly to your session for manual lookups.
 
 ## Configuration
@@ -26,15 +34,25 @@ In pi's global `settings.json`:
 ```jsonc
 {
   "librarian": {
-    "model": "anthropic/claude-sonnet-5", // default: current session model
-    "thinkingLevel": "high", // default: current session thinking level
-    "extensions": ["~/.pi/agent/extensions/parallel-web-tools"], // extra tools for the librarian
-    "disabledTools": [], // inherited built-ins to drop (write/edit are always excluded)
-    "cacheDir": "/tmp/pi-librarian" // clone cache location
-  }
+    "model": "openai-codex/gpt-5.5",
+    "thinkingLevel": "off",
+    "tools": ["search_web", "fetch_web"],
+    "extensions": ["~/.pi/agent/extensions/parallel-web-tools"],
+    "cacheDir": "/tmp/pi-librarian",
+  },
 }
 ```
 
+| Setting         | Recommended                                   | Default                        |
+| --------------- | --------------------------------------------- | ------------------------------ |
+| `model`         | `openai-codex/gpt-5.5`                        | current session model          |
+| `thinkingLevel` | `off`                                         | current session thinking level |
+| `tools`         | names of extra tools to activate, when needed | `[]`                           |
+| `extensions`    | escape hatch paths for tools not loaded in pi | `[]`                           |
+| `cacheDir`      | `/tmp/pi-librarian`                           | `/tmp/pi-librarian`            |
+
+`librarian.tools` is the activation gate for extra tools. `librarian.extensions` only adds extension paths to the search space when a named tool is not already loaded in the main pi session; listing an extension path does not activate every tool in that bundle. Librarian runs exclude `write` and `edit`.
+
 ## Development
 
 ```bash

package/RELEASE.md

@@ -2,6 +2,26 @@
 
 # Release notes
 
+## 0.2.0
+
+Adds continuable librarian runs and opt-in for extra tools.
+
+### Added
+
+- Added continuation support for prior librarian runs by run id.
+- Added `librarian.tools` for opting extra tools into librarian runs by name.
+- Added startup warnings for unresolved extra tool names and failed escape-hatch extension loads.
+
+### Changed
+
+- Changed `librarian.extensions` into an escape hatch for resolving named tools not loaded by the main pi agent.
+- Stripped extension hooks from extra tools loaded into nested librarian runs.
+- Removed `librarian.disabledTools`; baseline librarian tools are fixed, while extra tools are additive by name.
+
+### Fixed
+
+- Fixed tool error handling so pi marks librarian tool failures as errored executions.
+
 ## 0.1.1
 
 Adds automated release and dependency maintenance infrastructure.

package/docs/designs/02-continuable-runs.md

@@ -0,0 +1,102 @@
+# Continuable librarian runs
+
+## Status
+
+Draft
+
+## Decision Summary
+
+Persist librarian run transcripts as real pi session files in a librarian-owned directory, and add an optional `continue_from: <run uuid>` parameter to the `librarian` tool that reopens a prior run with its full research context. The run id is the durable transcript identifier: a continuation appends to the same run id rather than minting a second per-invocation id. Follow-up questions ("just one more thing about that flow you traced") reuse everything the run already read instead of starting cold. One machinery for both cheap follow-ups and full second research legs.
+
+## Problem Statement / Background
+
+A librarian run often answers 90% of a question, and the main session discovers the missing 10% only after reading the findings — "you traced the D1 prepared-statement flow; does the same apply to batch()?" Today every run is ephemeral (`SessionManager.inMemory`, disposed on completion), so the follow-up pays full price: re-clone context, re-grep, re-read, re-derive. The run's accumulated context — files read, structure understood, dead ends eliminated — is exactly the asset a follow-up needs.
+
+pi already has the machinery: `SessionManager.create(cwd, sessionDir)` persists transcripts to any directory, `SessionManager.listAll(sessionDir)` lists sessions in an arbitrary directory, and `SessionManager.open(path)` reopens a specific file.
+
+## Goals
+
+- A follow-up to a prior run answers from that run's context when sufficient — potentially zero new tool calls — and researches further when not, with no special-casing between the two.
+- The run uuid is discoverable by both the main agent (in the tool result content) and the human (in the rendered output), so continuation survives compaction boundaries: the user can supply the uuid if the agent lost it.
+- Continuations work across pi restarts and from different main sessions.
+
+## Non-Goals
+
+- No integration with pi-sessions indexing/search in v1 (see Alternatives).
+- No transcript eviction policy in v1 (mirrors the checkout-cache decision; `rm -rf /tmp/pi-librarian/sessions` is the manual escape for default settings).
+- No lighter-weight result shape for cheap follow-ups — `provide_results` ceremony applies to every run.
+
+## Exposed Shape
+
+- `librarian` tool gains `continue_from?: string` — the uuid of a prior run. When present, the run resumes that transcript; `query` carries the follow-up question. `repos`/`owners` scope params remain usable.
+- Every librarian tool result with an associated transcript ends with a `run: <uuid>` line (for the agent). On success this is appended after rendered findings; on error or abort it is appended after the error text.
+- The final render shows the same uuid as a muted line above the footer (for the human), whether the run succeeded, errored, or aborted.
+- `LibrarianRunDetails` carries `runId`. Its `trace` remains the live UI trace for the current librarian tool invocation, not the durable transcript history.
+- Tool description documents: pass `continue_from` for follow-ups to earlier research; omit it for new topics.
+
+## Design Decisions
+
+### 1. Transcripts are pi session files in a librarian-owned directory
+
+New runs use `SessionManager.create(cacheDir, <cacheDir>/sessions)` instead of `inMemory`. Continuations list `<cacheDir>/sessions` with `SessionManager.listAll(sessionDir)`, match the requested run id, and reopen via `SessionManager.open(path)`. The directory lives outside pi's default session store, so runs never appear in resume pickers and are invisible to pi-sessions indexing.
+
+**Tradeoff**: research memory stays siloed from the pi-sessions "sessions are memory" thesis. Deliberate for v1 — see Alternatives.
+
+### 2. Continuation rebuilds the runtime, the transcript provides the memory
+
+Tools, system prompt, and model are never read from the transcript; each continuation re-registers the current repo tools, rebuilds the system prompt, and resolves the model fresh (configured → current session model — possibly a different model than the original run; pi handles resumed transcripts under a new model). Only the message history is resumed. This keeps continuation semantics identical to fresh runs — including `provide_results` enforcement and the reminder loop — and means prompt/tool improvements apply retroactively to old runs.
+
+### 3. One machinery for cheap follow-ups and big second legs
+
+No fast path. A follow-up that the prior context already answers naturally produces a zero-tool-call run ending in `provide_results`; a big second leg just runs longer. The system prompt gains a continuation expectation: runs may be resumed later; on resume, answer from prior context when it suffices, research further when it does not, cite evidence from the available transcript context, and always finish with `provide_results`.
+
+### 4. uuid surfaced in two places, by design redundancy
+
+The agent reads `run: <uuid>` from the result content; the human sees it in the render. If the agent loses the uuid across a compaction boundary, the user can paste it back. Inelegant, deliberately so — one fallback beats zero.
+
+## Edge Cases & Failure Modes
+
+- **Unknown/missing `continue_from` uuid**: structured error result telling the agent the run was not found and to start a fresh run (the sessions dir may have been cleaned, or an early-aborted run may never have flushed a session file). Fresh runs surface the session id pi gives us without post-run filesystem verification.
+- **Concurrent continuations of the same run**: not locked; last write wins. Documented, not defended — a single-user tool.
+- **Original run errored or was aborted**: if pi persisted the transcript, it is continuable; the follow-up prompt simply lands after the failure. Often the right move ("try again, but look at X").
+- **Model changed between runs**: allowed; transcript resumes under the newly resolved model.
+- **Aborted continuation**: same abort path as fresh runs; the transcript keeps whatever was persisted, and remains continuable.
+
+## Alternatives
+
+### Persist into the normal pi session store (pi-sessions integration)
+
+- **Status:** Deferred
+- **Open issue:** Landing runs in the regular store would let pi-sessions index them — past research searchable, askable, and linked into lineage. It also pollutes resume pickers with untitled subagent sessions and couples the packages.
+- **Retained discussion:** The cleaner future shape is probably pi-sessions optionally indexing `<cacheDir>/sessions` as an additional source, keeping picker separation while gaining research memory.
+- **Next step:** Revisit once continuations prove their worth in practice.
+
+### In-memory session map for the pi process lifetime
+
+- **Status:** Rejected
+- **Decision or open issue:** Dies on restart and cannot serve a different main session; disk persistence costs nearly nothing given pi's existing machinery.
+
+### Lighter result shape for one-line follow-ups
+
+- **Status:** Rejected
+- **Decision or open issue:** Two result shapes for the main agent to handle; `provide_results` on a zero-tool-call run is cheap enough.
+
+## Implementation Plan
+
+- [ ] Phase 1: Persistent run sessions + `continue_from`
+  - Goal: Runs persist to `<cacheDir>/sessions/`; `continue_from` resumes them end to end.
+  - Files: `extensions/librarian/run.ts`, `extensions/librarian.ts`, `extensions/librarian/prompt.ts`.
+  - Work: swap `SessionManager.inMemory` for `create(cacheDir, sessionsDir)`; capture `session.sessionManager.getSessionId()` into `LibrarianRunDetails.runId` and append `run: <uuid>` to all result content when a run id exists; add `continue_from` param, resolve uuid via `SessionManager.listAll(sessionsDir)`, `SessionManager.open`, structured not-found error; system prompt continuation expectation; tool description guidance.
+  - Validation: `npm run check` green and live smoke covers fresh run plus continuation.
+
+- [ ] Phase 2: Render the run id
+  - Goal: Human-visible uuid in the final rendered state.
+  - Files: `extensions/librarian/view.ts`.
+  - Work: muted `run <uuid>` line above the footer in the final render (fresh and continued runs alike, including error and abort results).
+  - Validation: view unit test; visual check in TUI.
+
+- [ ] Phase 3: Live smoke
+  - Goal: Continuation proven in a real pi session.
+  - Files: `SMOKE.md`.
+  - Work: run a deep dive; ask a follow-up via `continue_from` in the same session (expect few/zero tool calls); restart pi and continue the same run from a fresh session using the rendered uuid; record evidence.
+  - Validation: SMOKE.md entries with captured output.

package/docs/designs/04-librarian-extra-tools.md

@@ -0,0 +1,138 @@
+# Librarian extra tools: name-based opt-in
+
+## Status
+
+Draft
+
+## Decision Summary
+
+Replace extension-path allowlisting as the user-facing control for librarian run composition with `librarian.tools`: a list of tool names, auto-resolved to their providing extensions through the main session's tool registry. Extension loading becomes an internal mechanism (plus a rarely-needed escape hatch), the named tools become the sole activation gate, and loaded bundles contribute tools only — their hooks are stripped. The tradeoff: extension code still loads to make a tool callable (pi has no cross-session tool proxying), so a bundle's other machinery is neutralized rather than never present.
+
+## Problem Statement / Background
+
+Design 01 (decision 3) made `librarian.extensions` — a list of extension paths — the way to grant librarian runs extra tools, with everything a loaded bundle registers activated wholesale. That model misplaces the abstraction: extensions are what users configure, but tools are what the run actually needs. The concrete case is BYO web search: the user has preferred web search/fetch tools provided by a pi extension and wants "use this web search tool in librarian" to be expressible as the tool, not as the path of the bundle it ships in, and without accepting whatever else that bundle registers.
+
+Design 01 rejected name-based composition because `pi.getAllTools()` was believed metadata-only. It still is — `ToolInfo` carries no execute handle — but each `ToolInfo.sourceInfo.path` names the extension path pi loaded the tool from, which is exactly the form `additionalExtensionPaths` accepts. Name → path resolution is therefore a straight lookup against the main session, and the missing piece of design 01's rejected alternative exists.
+
+## Goals
+
+- "Make this tool available in librarian runs" is configured as the tool's name; extension paths are not the primary mental model.
+- Librarian runs stay locked down by default: the baseline toolset (inherited built-ins + repo tools) is fixed and always on; extra tools are additive and explicit.
+- A loaded bundle's unrequested surface (other tools, hooks, commands) does not leak into runs.
+- Misconfiguration is loud at session start, not silently degrading every run.
+
+## Non-Goals
+
+- No skill opt-in. Skills stay hard-off in librarian runs until a concrete use case appears.
+- No cross-session tool proxying; this design works within pi's load-code-to-get-tools constraint.
+- No subtraction knob for the baseline: `librarian.disabledTools` is deleted, not replaced.
+- No change to attach mode; the main session already has the user's tools.
+
+## Exposed Shape
+
+```jsonc
+// pi global settings
+{
+  "librarian": {
+    "tools": ["search_web", "fetch_web"],   // extra tools, by name
+    "extensions": ["~/path/to/ext.ts"]      // escape hatch: extra search space only
+  }
+}
+```
+
+- **`librarian.tools`** — names of tools to activate inside librarian runs, in addition to the implied baseline (`read`, `grep`, `find`, `ls`, `bash`, plus the repo tools). This is the only thing that activates an extension tool, and may also explicitly opt in built-ins such as `write` or `edit`.
+- **`librarian.extensions`** — demoted to an escape hatch: extension paths to load into runs when a named tool's extension is not loaded in the main session. Listing an extension here activates nothing by itself.
+- **`librarian.disabledTools`** — removed.
+- Unresolvable names produce a one-time warning at session start; runs proceed with whatever resolves.
+
+## Design Decisions
+
+### 1. `librarian.tools` is the sole activation gate
+
+An extension tool is active in a librarian run iff its name appears in `librarian.tools`, regardless of how its code arrived (auto-resolution or the escape hatch). One rule, no bundle ever activates wholesale. This breaks the current `librarian.extensions` behavior deliberately: users who load a bundle must now also name the tools they want from it. The old model's "load path, get everything" was the mismatch this design exists to remove.
+
+### 2. Name resolution rides the main session's registry
+
+At `librarian` tool execution, the extension resolves each configured name via `pi.getAllTools()`: the matching `ToolInfo.sourceInfo.path` is the providing extension's path, collected (deduped) into `additionalExtensionPaths` for the nested run's resource loader. After session creation, `setActiveToolsByName` activates the baseline plus exactly the resolved names. Consequence: auto-resolution only sees tools loaded in the main session — which is the stated contract ("opt existing tools from your pi setup into librarian"), with the escape hatch covering the rest.
+
+Names that resolve to pi-librarian's own registrations (the `librarian` tool, repo tools) are skipped with a warning to guard against recursive self-loading. Names that resolve to built-ins are allowed; no extension path is needed for them.
+
+### 3. Loaded bundles contribute tools only — hooks stripped
+
+The nested loader's `extensionsOverride` clears each loaded extension's `handlers` map before the runner sees it, so no bundle event handlers execute inside librarian runs. This is the lockdown design 01 wanted when it rejected full inheritance (UI companions, session machinery misbehaving in headless runs), now enforced structurally instead of by curating the allowlist.
+
+**Tradeoff:** an extension whose tool depends on hook-based initialization (e.g. `session_start` state setup) breaks silently. Accepted for now; typical BYO tools are execute-only. An opt-out setting is added only when a real tool needs its hooks — not preemptively.
+
+### 4. Validation warns once at session start; runs proceed
+
+On `session_start` (after all main-session extensions are registered), configured names are checked: resolvable in the main session, or accounted for by a dry-load of the escape-hatch paths — the dry-load only happens when the escape hatch is configured and names remain unresolved. Misses produce a `ctx.ui.notify` warning naming the entry. Runs themselves do not fail on unresolved names; they proceed with what resolved. A failing run was rejected because a config typo shouldn't take down research entirely, but a silent miss was rejected too — hence loud-at-startup.
+
+### 5. Name collisions follow pi's rule
+
+If two extensions register the same tool name, pi's runner is first-registration-wins. Resolution inherits the main session's winner; the nested run inherits its own load order. No bespoke arbitration.
+
+## Edge Cases & Failure Modes
+
+- **Configured name matches nothing** (typo, extension removed): session-start warning naming the entry; runs proceed without it.
+- **Name resolves to a synthetic path** (`<inline:N>` from in-process `extensionFactories`): deliberately not special-cased — the path flows through like any other, the nested loader fails to load it, and the failure surfaces as a generic loader error. In-process factories are rare enough that this is accepted as undefined behavior.
+- **Name is a built-in** (`read`, `write`): activated by name without adding an extension path. Baseline built-ins are already active, but naming them is harmless.
+- **Name is `librarian` or a repo tool**: skipped with warning; never loads pi-librarian into its own runs.
+- **One extension provides several requested tools**: its path loads once; all requested names activate.
+- **Escape-hatch extension fails to load in the nested run**: surfaced from the loader's error list into the run trace; remaining tools unaffected.
+- **Tool exists but is deactivated in the main session**: still resolvable — `getAllTools()` returns configured tools regardless of active state, and naming it in `librarian.tools` expresses intent.
+- **Hook-dependent tool breaks under stripping**: known accepted risk (decision 3); the fix is a future opt-out, not silent hook execution.
+
+## Alternatives
+
+### Keep extension paths as the loading surface, add a tool filter
+
+- **Status:** Rejected
+- **Decision:** Leaves the user managing paths — the exact problem stated. Auto-resolution makes the path bookkeeping mechanical, so the user-facing surface should be the intent (tool names).
+
+### Escape-hatch extensions retain activate-all behavior
+
+- **Status:** Rejected
+- **Decision:** Two activation semantics for one run. A single gate (`librarian.tools`) is easier to reason about, and backwards compatibility was explicitly waived.
+
+### Skill opt-in (`librarian.skills`)
+
+- **Status:** Deferred
+- **Open issue:** Mechanically straightforward (`skillsOverride` + name filtering against global skill discovery) but no concrete use case yet.
+- **Next step:** Revisit when a specific skill would improve librarian research (e.g. a web-research skill).
+
+### MCP tools via pi-mcp-adapter
+
+- **Status:** Open
+- **Open issue:** Not supported by this design, for two independent reasons. The adapter's tool executors depend on state initialized in its `session_start` handler, which hook stripping removes — and even with hooks kept, nested librarian sessions never emit `session_start` at all: `bindExtensions()` (which fires it) is called only by pi's modes (interactive/print/rpc), never by bare `createAgentSession`. MCP tools opted in by name would load, register, and then return "MCP not initialized" on every call.
+- **Retained discussion:** This is the concrete instance of decision 3's hook-dependent-init risk, discovered by inspection rather than in production. Supporting it would take both a hook-keeping escape for the adapter's bundle and the librarian calling `session.bindExtensions({})` to emit `session_start` in nested runs — which also means MCP server processes spawning per run. The librarian would also have to emit `session_shutdown` before `dispose()` (pi's modes do this; `dispose()` alone does not), or every run leaks whatever the lifecycle hooks spawned.
+- **Next step:** Revisit if an MCP-provided tool becomes genuinely wanted inside librarian runs.
+
+### Fail runs on unresolved names
+
+- **Status:** Rejected
+- **Retained discussion:** Loud but disproportionate — a typo shouldn't block all research. Startup warning chosen; revisit if degraded runs still go unnoticed in practice.
+
+### Keep `librarian.disabledTools` as a baseline subtraction knob
+
+- **Status:** Rejected
+- **Decision:** With extra tools opted in by name, disabling an opted-in tool is just removing it from the list; the only remaining use was dropping a built-in (e.g. `bash`), which nothing currently needs. Deleted for a single-knob model; trivially reintroducible.
+
+## Implementation Plan
+
+- [ ] Phase 1: Settings reshape + resolution + run wiring
+  - Goal: `librarian.tools` works end to end — named tools resolve, load, and activate in runs; old semantics gone.
+  - Files: `extensions/librarian/settings.ts`, new `extensions/librarian/extra-tools.ts` (resolution module), `extensions/librarian/run.ts`, `extensions/librarian.ts`, tests.
+  - Work: settings schema gains `tools`, drops `disabledTools`, keeps `extensions` (escape-hatch semantics); pure resolution function `(toolInfos, settings) → { extensionPaths, toolNames }` implementing the self-guard, built-in handling, and dedupe; `runLibrarian` accepts resolved paths + names, wires them into `additionalExtensionPaths`, strips hooks via `extensionsOverride`, and activates baseline + resolved names via `setActiveToolsByName`; entrypoint passes `pi.getAllTools()` output at execute time.
+  - Validation: unit tests for resolution (hit, miss, built-in, self, dedupe, escape-hatch pass-through) and run activation; `npm run check`.
+
+- [ ] Phase 2: Session-start validation warnings
+  - Goal: Misconfiguration is loud once, at startup.
+  - Files: `extensions/librarian.ts`, `extensions/librarian/extra-tools.ts`, tests.
+  - Work: on `session_start`, collect extra-tool warnings against `pi.getAllTools()`; for names still unresolved with `librarian.extensions` configured, dry-load those paths through the same hook-stripping resource-loader factory used by runs to enumerate tools and surface loader errors; `ctx.ui.notify` per unresolved entry or loader failure with the specific reason.
+  - Validation: unit tests for warning selection (including the dry-load-only-when-needed rule); manual check that a typo'd name warns at pi startup; `npm run check`.
+
+- [ ] Phase 3: Documentation + live smoke
+  - Goal: The new model is documented and proven against the motivating use case.
+  - Files: `README.md`, `AGENTS.md`/`CONTEXT.md` cross-references as needed, `SMOKE.md`.
+  - Work: document `librarian.tools` and the escape-hatch semantics of `librarian.extensions`; remove `disabledTools` references; run a live librarian query that uses a BYO web search tool opted in by name, and one with a deliberate typo showing the startup warning; record both in `SMOKE.md`.
+  - Validation: smoke evidence in `SMOKE.md`; `npm run check`.

package/extensions/librarian/extra-tools.ts

@@ -0,0 +1,130 @@
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import { createLibrarianResourceLoader } from "./resource-loader.ts";
+import type { LibrarianSettings } from "./settings.ts";
+import { LIBRARIAN_RUN_TOOL_NAMES } from "./tools/names.ts";
+
+export const LIBRARIAN_BASELINE_TOOL_NAMES = ["read", "grep", "find", "ls", "bash"] as const;
+
+const LIBRARIAN_SELF_TOOL_NAMES = new Set<string>(["librarian", ...LIBRARIAN_RUN_TOOL_NAMES]);
+
+export type ExtraToolWarningReason = "self" | "unresolved" | "extensionLoad";
+
+export interface ExtraToolWarning {
+  toolName: string;
+  reason: ExtraToolWarningReason;
+  message: string;
+}
+
+export interface ExtraToolsResolution {
+  extensionPaths: string[];
+  toolNames: string[];
+}
+
+interface ExtraToolsValidation {
+  resolution: ExtraToolsResolution;
+  warnings: ExtraToolWarning[];
+  unresolvedToolNames: string[];
+}
+
+function resolveExtraToolsForValidation(
+  toolInfos: ToolInfo[],
+  settings: LibrarianSettings,
+): ExtraToolsValidation {
+  const toolInfosByName = new Map(toolInfos.map((toolInfo) => [toolInfo.name, toolInfo]));
+  const extensionPaths = new Set(settings.extensions);
+  const toolNames = new Set<string>();
+  const warnings: ExtraToolWarning[] = [];
+  const unresolvedToolNames: string[] = [];
+
+  for (const toolName of settings.tools) {
+    if (LIBRARIAN_SELF_TOOL_NAMES.has(toolName)) {
+      warnings.push({
+        toolName,
+        reason: "self",
+        message: `librarian.tools includes ${toolName}, but librarian's own tools cannot be opted into librarian runs. Remove it from librarian.tools.`,
+      });
+      continue;
+    }
+
+    const toolInfo = toolInfosByName.get(toolName);
+    if (!toolInfo) {
+      toolNames.add(toolName);
+      unresolvedToolNames.push(toolName);
+      warnings.push({
+        toolName,
+        reason: "unresolved",
+        message: `librarian.tools includes ${toolName}, but no loaded pi tool has that name.`,
+      });
+      continue;
+    }
+
+    toolNames.add(toolName);
+    if (toolInfo.sourceInfo.source !== "builtin") {
+      extensionPaths.add(toolInfo.sourceInfo.path);
+    }
+  }
+
+  return {
+    resolution: {
+      extensionPaths: [...extensionPaths],
+      toolNames: [...toolNames],
+    },
+    warnings,
+    unresolvedToolNames,
+  };
+}
+
+export function resolveExtraTools(
+  toolInfos: ToolInfo[],
+  settings: LibrarianSettings,
+): ExtraToolsResolution {
+  return resolveExtraToolsForValidation(toolInfos, settings).resolution;
+}
+
+export async function collectExtraToolWarnings(
+  toolInfos: ToolInfo[],
+  settings: LibrarianSettings,
+): Promise<ExtraToolWarning[]> {
+  const validation = resolveExtraToolsForValidation(toolInfos, settings);
+  const nonUnresolvedWarnings = validation.warnings.filter(
+    (warning) => warning.reason !== "unresolved",
+  );
+
+  if (validation.unresolvedToolNames.length === 0 || settings.extensions.length === 0) {
+    return validation.warnings;
+  }
+
+  const resourceLoader = createLibrarianResourceLoader({
+    cacheDir: settings.cacheDir,
+    extensionPaths: settings.extensions,
+    systemPromptOverride: () => undefined,
+  });
+  await resourceLoader.reload();
+
+  const extensionsResult = resourceLoader.getExtensions();
+  const escapeHatchToolNames = new Set<string>();
+  for (const extension of extensionsResult.extensions) {
+    for (const toolName of extension.tools.keys()) {
+      escapeHatchToolNames.add(toolName);
+    }
+  }
+
+  const loaderWarnings = extensionsResult.errors.map((error) => ({
+    toolName: error.path,
+    reason: "extensionLoad" as const,
+    message: `librarian.extensions failed to load ${error.path}: ${error.error}`,
+  }));
+
+  const unresolvedWarnings = validation.unresolvedToolNames
+    .filter((toolName) => !escapeHatchToolNames.has(toolName))
+    .map((toolName) => ({
+      toolName,
+      reason: "unresolved" as const,
+      message:
+        loaderWarnings.length > 0
+          ? `librarian.tools includes ${toolName}, but it was not found in the main session or successfully loaded escape-hatch tools. Fix librarian.extensions load errors or the tool name.`
+          : `librarian.tools includes ${toolName}, but no loaded pi tool or escape-hatch extension tool has that name.`,
+    }));
+
+  return [...nonUnresolvedWarnings, ...loaderWarnings, ...unresolvedWarnings];
+}

package/extensions/librarian/prompt.ts

@@ -21,7 +21,7 @@ Clones live under ${cacheDir}/repos/<owner>/<repo>. They are read-only research
 
 ## Citations
 
-- Only cite files you actually read in this run.
+- Only cite files you actually read within context.
 - Cite as repo + file path + line range when you have one.
 - If evidence is partial, say what is confirmed and what remains uncertain.
 - If access fails (404/403, private repo), report that constraint plainly.

package/extensions/librarian/resource-loader.ts

@@ -0,0 +1,40 @@
+import {
+  DefaultResourceLoader,
+  getAgentDir,
+  type LoadExtensionsResult,
+} from "@earendil-works/pi-coding-agent";
+
+export function stripExtensionHooks(result: LoadExtensionsResult): LoadExtensionsResult {
+  return {
+    ...result,
+    extensions: result.extensions.map((extension) => ({
+      ...extension,
+      handlers: new Map(),
+    })),
+  };
+}
+
+export interface LibrarianResourceLoaderOptions {
+  cacheDir: string;
+  extensionPaths: string[];
+  systemPromptOverride: (base: string | undefined) => string | undefined;
+}
+
+export function createLibrarianResourceLoader(
+  options: LibrarianResourceLoaderOptions,
+): DefaultResourceLoader {
+  return new DefaultResourceLoader({
+    cwd: options.cacheDir,
+    agentDir: getAgentDir(),
+    noExtensions: true,
+    ...(options.extensionPaths.length > 0
+      ? { additionalExtensionPaths: options.extensionPaths }
+      : {}),
+    noSkills: true,
+    noPromptTemplates: true,
+    noThemes: true,
+    extensionsOverride: stripExtensionHooks,
+    skillsOverride: () => ({ skills: [], diagnostics: [] }),
+    systemPromptOverride: options.systemPromptOverride,
+  });
+}

package/extensions/librarian/run.ts

@@ -1,22 +1,21 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import type { AgentToolResult, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import {
-  createAgentSession,
-  DefaultResourceLoader,
-  getAgentDir,
-  SessionManager,
-} from "@earendil-works/pi-coding-agent";
+import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import { type ExtraToolsResolution, LIBRARIAN_BASELINE_TOOL_NAMES } from "./extra-tools.ts";
 import type { GitHubClientProvider } from "./github.ts";
 import {
   buildLibrarianSystemPrompt,
   buildLibrarianUserPrompt,
   buildProvideResultsReminder,
 } from "./prompt.ts";
+import { createLibrarianResourceLoader } from "./resource-loader.ts";
 import { renderFindingsMarkdown } from "./results.ts";
 import type { LibrarianSettings } from "./settings.ts";
 import { createCheckoutRepoTool } from "./tools/checkout-repo.ts";
+import { LIBRARIAN_RUN_TOOL_NAMES } from "./tools/names.ts";
 import type { Findings } from "./tools/provide-results.ts";
 import { createProvideResultsTool } from "./tools/provide-results.ts";
 import { createReadGitHubFileTool } from "./tools/read-github-file.ts";
@@ -26,9 +25,12 @@ import { createSearchReposTool } from "./tools/search-repos.ts";
 import { asRepoToolDetails, summarizeToolResult } from "./trace.ts";
 
 const MAX_PROVIDE_RESULTS_REMINDERS = 3;
-const HARDCODED_EXCLUDED_TOOLS = ["write", "edit"];
+const DEFAULT_EXCLUDED_TOOLS = ["write", "edit"];
+
+class LibrarianRunError extends Error {}
 
 export type LibrarianRunStatus = "running" | "done" | "error" | "aborted";
+type FailedLibrarianRunStatus = "error" | "aborted";
 
 export interface TraceCall {
   id: string;
@@ -49,6 +51,7 @@ export interface LibrarianRunDetails {
   findings?: Findings;
   checkouts: Record<string, string>;
   error?: string;
+  runId?: string;
   startedAt: number;
   endedAt?: number;
 }
@@ -57,14 +60,30 @@ export interface LibrarianRunOptions {
   query: string;
   repos: string[];
   owners: string[];
+  continueFrom: string | undefined;
   model: Model<Api>;
   thinkingLevel: ThinkingLevel;
   settings: LibrarianSettings;
+  extraTools: ExtraToolsResolution;
   githubClient: GitHubClientProvider;
   signal: AbortSignal | undefined;
   onUpdate: ((details: LibrarianRunDetails) => void) | undefined;
 }
 
+async function openContinuedSession(
+  runId: string,
+  sessionsDir: string,
+  cacheDir: string,
+  fail: (status: FailedLibrarianRunStatus, content: string) => never,
+): Promise<SessionManager> {
+  const sessions = await SessionManager.listAll(sessionsDir);
+  const sessionFile = sessions.find((candidate) => candidate.id === runId)?.path;
+  if (!sessionFile) {
+    fail("error", `Librarian run not found: ${runId}`);
+  }
+  return SessionManager.open(sessionFile, sessionsDir, cacheDir);
+}
+
 export async function runLibrarian(
   options: LibrarianRunOptions,
 ): Promise<AgentToolResult<LibrarianRunDetails>> {
@@ -88,26 +107,37 @@ export async function runLibrarian(
     options.onUpdate?.({ ...details, trace: [...details.trace] });
   };
 
-  const finish = (
-    status: LibrarianRunStatus,
-    content: string,
-    isError: boolean,
-  ): AgentToolResult<LibrarianRunDetails> => {
+  const finalizeDetails = (status: LibrarianRunStatus, content: string): string => {
+    const resultContent = details.runId ? `${content}\n\nrun: ${details.runId}` : content;
     details.status = status;
     details.endedAt = Date.now();
-    if (isError) {
+    if (status !== "done") {
       details.error = content.split("\n")[0] ?? content;
     }
     emit(true);
-    return {
-      content: [{ type: "text", text: content }],
-      details: { ...details, trace: [...details.trace] },
-      ...(isError ? { isError: true } : {}),
-    };
+    return resultContent;
+  };
+
+  const finish = (
+    status: LibrarianRunStatus,
+    content: string,
+  ): AgentToolResult<LibrarianRunDetails> => ({
+    content: [{ type: "text", text: finalizeDetails(status, content) }],
+    details: { ...details, trace: [...details.trace] },
+  });
+
+  const fail = (status: FailedLibrarianRunStatus, content: string): never => {
+    throw new LibrarianRunError(finalizeDetails(status, content));
   };
 
   await fs.mkdir(options.settings.cacheDir, { recursive: true });
 
+  const sessionsDir = path.join(options.settings.cacheDir, "sessions");
+  const sessionManager = options.continueFrom
+    ? await openContinuedSession(options.continueFrom, sessionsDir, options.settings.cacheDir, fail)
+    : SessionManager.create(options.settings.cacheDir, sessionsDir);
+  details.runId = sessionManager.getSessionId();
+
   let findings: Findings | undefined;
   const repoTools = [
     createSearchReposTool(options.githubClient),
@@ -120,21 +150,27 @@ export async function runLibrarian(
     }),
   ];
 
-  const resourceLoader = new DefaultResourceLoader({
-    cwd: options.settings.cacheDir,
-    agentDir: getAgentDir(),
-    noExtensions: true,
-    ...(options.settings.extensions.length > 0
-      ? { additionalExtensionPaths: options.settings.extensions }
-      : {}),
-    noSkills: true,
-    noPromptTemplates: true,
-    noThemes: true,
+  const resourceLoader = createLibrarianResourceLoader({
+    cacheDir: options.settings.cacheDir,
+    extensionPaths: options.extraTools.extensionPaths,
     systemPromptOverride: () => buildLibrarianSystemPrompt(options.settings.cacheDir),
-    skillsOverride: () => ({ skills: [], diagnostics: [] }),
   });
   await resourceLoader.reload();
 
+  const extensionLoadErrors = resourceLoader.getExtensions().errors;
+  for (const [index, error] of extensionLoadErrors.entries()) {
+    const now = Date.now();
+    details.trace.push({
+      id: `extension-load-${index}`,
+      name: "load_extension",
+      args: { path: error.path },
+      startedAt: now,
+      endedAt: now,
+      isError: true,
+      resultSummary: error.error,
+    });
+  }
+
   emit(true);
 
   let session: AgentSession | undefined;
@@ -145,20 +181,21 @@ export async function runLibrarian(
     const created = await createAgentSession({
       cwd: options.settings.cacheDir,
       resourceLoader,
-      sessionManager: SessionManager.inMemory(options.settings.cacheDir),
+      sessionManager,
       model: options.model,
       thinkingLevel: options.thinkingLevel,
       customTools: repoTools,
-      excludeTools: [...HARDCODED_EXCLUDED_TOOLS, ...options.settings.disabledTools],
+      excludeTools: DEFAULT_EXCLUDED_TOOLS.filter(
+        (toolName) => !options.extraTools.toolNames.includes(toolName),
+      ),
     });
     session = created.session;
 
-    const excluded = new Set([...HARDCODED_EXCLUDED_TOOLS, ...options.settings.disabledTools]);
-    const allToolNames = session
-      .getAllTools()
-      .map((tool) => tool.name)
-      .filter((name) => !excluded.has(name));
-    session.setActiveToolsByName(allToolNames);
+    session.setActiveToolsByName([
+      ...LIBRARIAN_BASELINE_TOOL_NAMES,
+      ...LIBRARIAN_RUN_TOOL_NAMES,
+      ...options.extraTools.toolNames,
+    ]);
 
     unsubscribe = session.subscribe((event: AgentSessionEvent) => {
       switch (event.type) {
@@ -198,7 +235,7 @@ export async function runLibrarian(
     });
 
     if (options.signal?.aborted) {
-      return finish("aborted", "Librarian run aborted before it started.", true);
+      fail("aborted", "Librarian run aborted before it started.");
     }
 
     const activeSession = session;
@@ -214,30 +251,34 @@ export async function runLibrarian(
     let reminders = 0;
     while (!findings && !options.signal?.aborted && reminders < MAX_PROVIDE_RESULTS_REMINDERS) {
       reminders += 1;
-      await session.prompt(buildProvideResultsReminder(), { expandPromptTemplates: false });
+      await session.prompt(buildProvideResultsReminder(), {
+        expandPromptTemplates: false,
+      });
     }
 
     if (options.signal?.aborted) {
-      return finish("aborted", "Librarian run aborted.", true);
+      fail("aborted", "Librarian run aborted.");
     }
 
     if (findings) {
       details.findings = findings;
-      return finish("done", renderFindingsMarkdown(findings, details.checkouts), false);
+      return finish("done", renderFindingsMarkdown(findings, details.checkouts));
     }
 
     const lastText = session.getLastAssistantText() ?? "";
-    return finish(
+    fail(
       "error",
       `Librarian did not report structured findings after ${MAX_PROVIDE_RESULTS_REMINDERS} reminders.${lastText ? `\n\nRaw final message:\n${lastText}` : ""}`,
-      true,
     );
   } catch (error) {
+    if (error instanceof LibrarianRunError) {
+      throw error;
+    }
     if (options.signal?.aborted) {
-      return finish("aborted", "Librarian run aborted.", true);
+      fail("aborted", "Librarian run aborted.");
     }
     const message = error instanceof Error ? error.message : String(error);
-    return finish("error", `Librarian run failed: ${message}`, true);
+    fail("error", `Librarian run failed: ${message}`);
   } finally {
     if (onAbort) {
       options.signal?.removeEventListener("abort", onAbort);
@@ -245,4 +286,6 @@ export async function runLibrarian(
     unsubscribe?.();
     session?.dispose();
   }
+
+  throw new Error("Unreachable librarian run state.");
 }

package/extensions/librarian/settings.ts

@@ -18,7 +18,7 @@ const LIBRARIAN_FILE_SETTINGS_SCHEMA = Type.Object({
   model: Type.Optional(Type.String()),
   thinkingLevel: Type.Optional(THINKING_LEVEL_SCHEMA),
   extensions: Type.Optional(Type.Array(Type.String())),
-  disabledTools: Type.Optional(Type.Array(Type.String())),
+  tools: Type.Optional(Type.Array(Type.String())),
   cacheDir: Type.Optional(Type.String()),
 });
 
@@ -43,7 +43,7 @@ export interface LibrarianSettings {
   model: ModelReference | undefined;
   thinkingLevel: ThinkingLevel | undefined;
   extensions: string[];
-  disabledTools: string[];
+  tools: string[];
   cacheDir: string;
 }
 
@@ -102,12 +102,20 @@ function normalizeExtensionPaths(values: string[] | undefined): string[] {
     .map(expandHome);
 }
 
+function normalizeToolNames(values: string[] | undefined): string[] {
+  if (!values) {
+    return [];
+  }
+
+  return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
+}
+
 export function resolveLibrarianSettings(fileSettings: LibrarianFileSettings): LibrarianSettings {
   return {
     model: parseModelReference(fileSettings.model),
     thinkingLevel: fileSettings.thinkingLevel,
     extensions: normalizeExtensionPaths(fileSettings.extensions),
-    disabledTools: fileSettings.disabledTools ?? [],
+    tools: normalizeToolNames(fileSettings.tools),
     cacheDir: normalizeCacheDir(fileSettings.cacheDir),
   };
 }

package/extensions/librarian/tools/checkout-repo.ts

@@ -64,24 +64,9 @@ export function createCheckoutRepoTool(cacheDir: string) {
             : error instanceof Error
               ? error.message
               : String(error);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `${message}\nIf the repo name is uncertain, resolve it with search_repos first.`,
-            },
-          ],
-          details: {
-            kind: "checkout_repo",
-            repo: params.repo,
-            path: "",
-            headSha: "",
-            ref: params.ref ?? "",
-            fileCount: 0,
-            reusedClone: false,
-          },
-          isError: true,
-        };
+        throw new Error(
+          `${message}\nIf the repo name is uncertain, resolve it with search_repos first.`,
+        );
       }
     },
   });

package/extensions/librarian/tools/provide-results.ts

@@ -3,10 +3,16 @@ import { type Static, Type } from "typebox";
 import { LIBRARIAN_TOOL_NAMES } from "./names.ts";
 
 export const LocationSchema = Type.Object({
-  repo: Type.String({ description: "Repository as owner/repo or a repository URL." }),
-  file: Type.String({ description: "File path within the repository." }),
+  repo: Type.String({
+    description: "Repository as owner/repo or a repository URL.",
+  }),
+  file: Type.String({
+    description: "Validated file path within the repository.",
+  }),
   lines: Type.Optional(
-    Type.String({ description: 'Line range like "80-140" or a single line like "42".' }),
+    Type.String({
+      description: 'Line range like "80-140" or a single line like "42".',
+    }),
   ),
   note: Type.String({ description: "Relevance of the file." }),
 });
@@ -16,7 +22,8 @@ export const FindingsSchema = Type.Object({
     description: "1-3 sentence direct answer to the query. No preamble.",
   }),
   locations: Type.Array(LocationSchema, {
-    description: "Evidence locations.",
+    description:
+      "Evidence source-file locations. Include only repository files you validated by reading.",
   }),
   description: Type.Optional(
     Type.String({
@@ -50,9 +57,15 @@ export function createProvideResultsTool(onFindings: (findings: Findings) => voi
       onFindings(params);
       return {
         content: [
-          { type: "text", text: "Findings recorded. You are done; do not call more tools." },
+          {
+            type: "text",
+            text: "Findings recorded. You are done; do not call more tools.",
+          },
         ],
-        details: { kind: "provide_results", locationCount: params.locations.length },
+        details: {
+          kind: "provide_results",
+          locationCount: params.locations.length,
+        },
         terminate: true,
       };
     },

package/extensions/librarian/tools/read-github-file.ts

@@ -22,8 +22,10 @@ const ReadGitHubFileParams = Type.Object({
     Type.String({ description: "Branch, tag, or commit sha. Default: the default branch." }),
   ),
   range: Type.Optional(
-    Type.Tuple([Type.Number({ minimum: 1 }), Type.Number({ minimum: 1 })], {
+    Type.Array(Type.Number({ minimum: 1 }), {
       description: "[startLine, endLine] (1-based, inclusive) for large files.",
+      minItems: 2,
+      maxItems: 2,
     }),
   ),
 });
@@ -42,6 +44,11 @@ export function createReadGitHubFileTool(githubClient: GitHubClientProvider) {
     parameters: ReadGitHubFileParams,
 
     async execute(_toolCallId, params) {
+      const range = params.range ? (params.range as [number, number]) : undefined;
+      if (range && range[1] < range[0]) {
+        throw new Error("range end must be greater than or equal to range start.");
+      }
+
       try {
         const github = await githubClient();
         const contents = await github.readContents({
@@ -72,9 +79,9 @@ export function createReadGitHubFileTool(githubClient: GitHubClientProvider) {
         let end = allLines.length;
         let clipNote = "";
 
-        if (params.range) {
-          start = Math.min(params.range[0], allLines.length);
-          end = Math.min(params.range[1], allLines.length);
+        if (range) {
+          start = Math.min(range[0], allLines.length);
+          end = Math.min(range[1], allLines.length);
         } else if (allLines.length > MAX_LINES_WITHOUT_RANGE) {
           end = MAX_LINES_WITHOUT_RANGE;
           clipNote = `\n... clipped at line ${MAX_LINES_WITHOUT_RANGE} of ${allLines.length}; pass range to read further.`;
@@ -104,18 +111,7 @@ export function createReadGitHubFileTool(githubClient: GitHubClientProvider) {
             : error instanceof Error
               ? error.message
               : String(error);
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            kind: "read_github_file",
-            owner: params.owner,
-            repo: params.repo,
-            path: params.path,
-            lineCount: 0,
-            isDirectory: false,
-          },
-          isError: true,
-        };
+        throw new Error(message);
       }
     },
   });

package/extensions/librarian/tools/search-repos.ts

@@ -85,16 +85,7 @@ export function createSearchReposTool(githubClient: GitHubClientProvider) {
             : error instanceof Error
               ? error.message
               : String(error);
-        return {
-          content: [{ type: "text", text: message }],
-          details: {
-            kind: "search_repos",
-            query: params.query,
-            resultCount: 0,
-            totalCount: 0,
-          },
-          isError: true,
-        };
+        throw new Error(message);
       }
     },
   });

package/extensions/librarian/view.ts

@@ -189,6 +189,17 @@ function renderFooter(details: LibrarianRunDetails, theme: Theme): string {
   );
 }
 
+function isLibrarianRunDetails(value: unknown): value is LibrarianRunDetails {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof (value as { status?: unknown }).status === "string" &&
+    typeof (value as { query?: unknown }).query === "string" &&
+    typeof (value as { modelLabel?: unknown }).modelLabel === "string" &&
+    Array.isArray((value as { trace?: unknown }).trace)
+  );
+}
+
 function renderTrace(
   details: LibrarianRunDetails,
   expanded: boolean,
@@ -245,7 +256,7 @@ export function renderLibrarianResult(
   const container = new Container();
   const details = result.details;
 
-  if (!details) {
+  if (!isLibrarianRunDetails(details)) {
     const firstText = result.content.find((part) => part.type === "text");
     container.addChild(
       new Text(firstText && "text" in firstText ? firstText.text : "(no output)", 0, 0),
@@ -275,6 +286,9 @@ export function renderLibrarianResult(
   }
 
   container.addChild(new Spacer(1));
+  if (!running && details.runId) {
+    container.addChild(new Text(theme.fg("muted", `run ${details.runId}`), 0, 0));
+  }
   container.addChild(new Text(renderFooter(details, theme), 0, 0));
   return container;
 }

package/extensions/librarian.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, SessionStartEvent } from "@earendil-works/pi-coding-
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { applyAttachState, readAttachState, setAttachState } from "./librarian/attach.ts";
+import { collectExtraToolWarnings, resolveExtraTools } from "./librarian/extra-tools.ts";
 import { createGitHubClientProvider } from "./librarian/github.ts";
 import { resolveLibrarianModel } from "./librarian/model.ts";
 import { type LibrarianRunDetails, runLibrarian, type TraceCall } from "./librarian/run.ts";
@@ -36,6 +37,12 @@ const LibrarianParams = Type.Object({
       maxItems: 20,
     }),
   ),
+  continue_from: Type.Optional(
+    Type.String({
+      description:
+        "Run id from an earlier librarian result. Pass this for follow-up questions for that prior run.",
+    }),
+  ),
 });
 
 export default function librarianExtension(pi: ExtensionAPI): void {
@@ -84,41 +91,33 @@ export default function librarianExtension(pi: ExtensionAPI): void {
       const thinkingLevel = settings.thinkingLevel ?? pi.getThinkingLevel();
       const resolution = resolveLibrarianModel(ctx, settings.model, thinkingLevel);
       if (!resolution) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: "No model available for the librarian. Configure librarian.model or select a session model.",
-            },
-          ],
-          details: {
-            status: "error",
-            query: params.query,
-            modelLabel: "(none)",
-            thinkingLevel,
-            trace: [],
-            checkouts: {},
-            startedAt: Date.now(),
-            endedAt: Date.now(),
-            error: "No model available.",
-          } satisfies LibrarianRunDetails,
-          isError: true,
-        };
+        throw new Error(
+          "No model available for the librarian. Configure librarian.model or select a session model.",
+        );
       }
 
+      const extraTools = resolveExtraTools(pi.getAllTools(), settings);
+
       return runLibrarian({
         query: params.query,
         repos: params.repos ?? [],
         owners: params.owners ?? [],
+        continueFrom: params.continue_from,
         model: resolution.model,
         thinkingLevel: resolution.thinkingLevel,
         settings,
+        extraTools,
         githubClient,
         signal,
         onUpdate: onUpdate
           ? (details) => {
               onUpdate({
-                content: [{ type: "text", text: `Researching: ${shorten(params.query, 80)}` }],
+                content: [
+                  {
+                    type: "text",
+                    text: `Researching: ${shorten(params.query, 80)}`,
+                  },
+                ],
                 details,
               });
             }
@@ -177,5 +176,10 @@ export default function librarianExtension(pi: ExtensionAPI): void {
 
   pi.on("session_start", async (_event: SessionStartEvent, ctx) => {
     applyAttachState(pi, readAttachState(ctx));
+
+    const warnings = await collectExtraToolWarnings(pi.getAllTools(), settings);
+    for (const warning of warnings) {
+      ctx.ui.notify(warning.message, "warning");
+    }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thurstonsand/pi-librarian",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "GitHub research subagent for pi: deep-dive specific repos, discover across the ecosystem",
   "license": "MIT",