@thurstonsand/pi-librarian 0.3.0 → 0.4.0

package/README.md

@@ -8,14 +8,21 @@ A GitHub research subagent for the [pi coding agent](https://github.com/badlogic
 
 ## How it works
 
-The `librarian` tool spawns a nested research agent with purpose-built tools:
+The `librarian` tool spawns a research subagent with purpose-built tools:
 
-- **`checkout_repo`** — clone into a local cache; pi's own `grep`/`read`/`find` then work on real files, and `git log -S`/`blame`/`diff` cover history.
-- **`search_repos`** — GitHub repository discovery (stars, topics, language).
+- **`checkout_repo`** — clone into a local cache, where it can be read locally, and `git log -S`/`blame`/`diff` covers history.
+- **`search_repos`** — GitHub repository discovery (stars, topics, other metadata).
 - **`search_code`** — cross-repo public code search via [Grep](https://grep.app/) (regex, global discovery, repo/language/path filters).
 - **`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.
 
+## Usage
+
+- Ask pi a question involving other repos; it asks the `librarian`.
+- Ask follow-up questions to earlier librarian runs.
+- `/librarian` attaches the research tools directly to your session for direct tool usage.
+- Recommended: install [pi-web-access](https://pi.dev/packages/pi-web-access) (or your web search of choice, tho this one is zero-config to get started) and add `web_search`, `fetch_content`, `get_search_content` to `librarian.tools` to expand past GitHub-only research.
+
 ## 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:
@@ -23,13 +30,7 @@ Public GitHub reads work without configuration. To let the librarian search and
 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.
+The token is loaded once per pi session and used for github access in `search_repos`, `search_github_code`, `checkout_repo`, and `read_github_file`. For private repositories, use a token with read access to the target repos.
 
 ## Configuration
 
@@ -40,7 +41,7 @@ In pi's global `settings.json`:
   "librarian": {
     "model": "openai-codex/gpt-5.5",
     "thinkingLevel": "off",
-    "tools": ["search_web", "fetch_web"],
+    "tools": ["web_search", "fetch_content", "get_search_content"],
     "extensions": ["~/.pi/agent/extensions/parallel-web-tools"],
     "cacheDir": "/tmp/pi-librarian",
     "debug": { "persistRuns": false },
@@ -48,16 +49,16 @@ In pi's global `settings.json`:
 }
 ```
 
-| 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`            |
-| `debug.persistRuns` | persist nested session file paths for debugging | `false`                        |
+| Setting             | Recommended                                      | Default                        |
+| ------------------- | ------------------------------------------------ | ------------------------------ |
+| `model`             | `openai-codex/gpt-5.5`                           | current session model          |
+| `thinkingLevel`     | `off`                                            | current session thinking level |
+| `tools`             | names of extra tools to provide the librarian    | `[]`                           |
+| `extensions`        | extra paths to load extensions for the librarian | `[]`                           |
+| `cacheDir`          | `/tmp/pi-librarian`                              | `/tmp/pi-librarian`            |
+| `debug.persistRuns` | persist nested session file paths for debugging  | `false`                        |
 
-`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`.
+`librarian.extensions` dynamically loads extra extensions just for the librarian. Add any tools from that extension to `librarian.tools` for the librarian to actually be able to use them. Librarian excludes `write` and `edit`.
 
 ## Development
 

package/RELEASE.md

@@ -2,6 +2,25 @@
 
 # Release notes
 
+## 0.4.0
+
+### Added
+
+- Added compact, expandable transcript entries for `/librarian` attach and detach changes, including the exact repo tools affected.
+- Added support for Pi's `max` thinking level.
+
+### Changed
+
+- Changed `librarian.model` to use Pi's native model-pattern resolution.
+- Raised the minimum supported Pi version to 0.80.6.
+- Changed persisted attach entries to require tool snapshots. Older attach entries are now ignored.
+
+## 0.3.1
+
+### Changed
+
+- Sharpened the research tools' prompt snippets, guidelines, and descriptions so the librarian names each tool explicitly and reads its guidance as directive instructions.
+
 ## 0.3.0
 
 Hardens librarian research tools and aligns GitHub file reads with pi's native `read` tool.

package/docs/designs/05-pi-0806-attach-and-model-resolution.md

@@ -0,0 +1,171 @@
+# Pi 0.80.6 attach entries, thinking, and model resolution
+
+## Status
+
+Accepted
+
+## Decision Summary
+
+Adopt Pi 0.80.6's custom-entry renderer, CLI model resolver, and `max` thinking level. Attach state changes become durable transcript accordions with historical tool snapshots; configured models follow Pi's native model-pattern semantics and fall back to the current session model only when Pi cannot resolve them.
+
+## Problem Statement / Background
+
+Pi-librarian already persists `/librarian` attach state as `pi-librarian:attach` custom entries, but those entries are invisible in the transcript. The command compensates with transient notifications, so a resumed session can restore its state without showing when or how the state changed.
+
+Pi 0.80.4 added `registerEntryRenderer`, which can present state records without sending them to the model. The rendered entry must snapshot the affected tool names so historical entries remain accurate if pi-librarian's attachable toolset changes later; older incomplete shapes are deliberately unsupported.
+
+Configured librarian models currently use local fuzzy matching over `modelRegistry.getAvailable()`. Pi exports `resolveCliModel`, the canonical resolver for exact references, bare and provider-scoped fuzzy patterns, and custom model IDs. Pi-librarian should use that behavior directly rather than impose a separate availability policy.
+
+Pi 0.80.6 extends the public `ThinkingLevel` type with `max`. Pi exposes model-specific `getSupportedThinkingLevels`, but no public runtime list of every accepted setting value, so settings validation must keep one local runtime list aligned with Pi's public type.
+
+## Goals
+
+- Make actual attach and detach changes visible as durable, compact transcript history without duplicate notifications.
+- Preserve the exact toolset affected by each new historical entry.
+- Reject attach entries that do not match the current data shape without migration behavior.
+- Use Pi's canonical configured-model resolution and fallback to the current session model only on resolution failure.
+- Make every configured-model fallback visible and actionable.
+- Accept and preserve Pi 0.80.6's `max` thinking level from settings through nested runs.
+
+## Non-Goals
+
+- Persist `/librarian status` queries or repeated explicit `on`/`off` no-ops.
+- Send attach state entries to the LLM.
+- Change nested-run extension loading to use `InlineExtension`.
+- Add a separate authentication or availability gate after Pi resolves a configured model.
+- Choose a different fallback model when no current session model exists.
+
+## Exposed Shape
+
+### `/librarian` command feedback
+
+An actual state change appends one `pi-librarian:attach` custom entry and does not also show a notification. `/librarian status` remains a transient notification. `/librarian on` while attached and `/librarian off` while detached remain transient no-ops, using symmetrical wording:
+
+- `Librarian tools already attached.`
+- `Librarian tools already detached.`
+
+### Attach transcript entry
+
+The compact line is stable when expanded:
+
+- `Librarian tools attached`
+- `Librarian tools detached`
+
+Attached state uses success styling; detached state uses muted styling. Expanding a current entry reveals the exact affected tool names beneath the unchanged compact line. Tool names appear in their registered order.
+
+New entries persist:
+
+```ts
+{
+  attached: boolean;
+  tools: string[];
+}
+```
+
+Both attach and detach entries snapshot the complete affected tool list. Any entry that does not match the complete current shape renders `Librarian attach state unavailable` and does not influence restored state.
+
+### Thinking-level settings
+
+`librarian.thinkingLevel` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The selected value crosses settings, model resolution, and nested-run boundaries unchanged; provider/model capability handling remains Pi's responsibility. Because Pi has no public runtime constant for the complete setting vocabulary, pi-librarian keeps one local list checked against Pi's public `ThinkingLevel` type.
+
+### Configured model resolution
+
+`librarian.model` accepts the same patterns as Pi: exact or fuzzy bare patterns such as `opus`, provider-scoped patterns such as `anthropic/opus`, and custom model IDs supported by `resolveCliModel`. `resolveLibrarianModel` passes the pattern directly to Pi against `modelRegistry.getAll()` and accepts any returned model. Resolver warnings, including custom-ID fallback warnings, are shown without rejecting the model.
+
+When configured resolution returns an error or no model, each librarian invocation:
+
+1. falls back to `ctx.model` when present;
+2. emits a warning naming the configured model, the failure reason, and the current fallback model; and
+3. runs with the requested librarian thinking level unchanged.
+
+If no current model exists, the librarian tool retains its existing execution error. No warning is needed in the successful configured-model or unconfigured current-model paths.
+
+## Design Decisions
+
+### 1. Entries record state changes, not every command response
+
+Only actual state changes belong in durable transcript history. Status queries and repeated explicit states do not change session state, so notifications remain the appropriate surface. Removing the transition notification avoids presenting the same event twice.
+
+### 2. New entries snapshot the affected tools
+
+Deriving names from the current `ATTACHABLE_TOOL_NAMES` would make old transcript entries change meaning after the toolset evolves. Storing the names adds minor duplication but preserves historical truth. Detach entries retain the list because removal has the same affected scope as attachment.
+
+### 3. Entry rendering has no compatibility shape
+
+Attach entries either match the complete current `{ attached, tools }` shape or render the generic unavailable-state line. Carrying a legacy branch would preserve data that cannot satisfy the historical-toolset requirement.
+
+### 4. Expansion is additive
+
+Expanded rendering keeps the compact line unchanged and adds details below it. This treats transcript expansion as an accordion rather than substituting one representation for another.
+
+### 5. Pi owns model resolution
+
+`resolveCliModel` owns provider normalization, fuzzy matching, priority, and custom model-ID fallback. Pi-librarian accepts its result directly. Authentication and provider failures belong to nested execution rather than a second model-selection policy.
+
+### 6. Fallback warnings occur on every affected invocation
+
+Repeated warnings are intentional. Every run that differs from configured intent should say so at the point of use; silently deduplicating could hide a continuing configuration problem from later research runs.
+
+## Edge Cases & Failure Modes
+
+- **Old or malformed attach entry:** does not alter restored state and renders a neutral unavailable-state line.
+- **Toolset changes after an entry was written:** new rendering uses the entry's snapshot, preserving historical scope.
+- **Repeated explicit state:** appends no entry and reports that tools are already attached or detached.
+- **Unknown provider:** warns with Pi's resolution reason and falls back to the current model.
+- **Resolved but unauthenticated model:** is selected; nested execution reports any resulting authentication failure.
+- **Resolver-created custom model ID:** is selected and Pi's warning is shown.
+- **No configured model:** uses the current model without warning.
+- **No usable configured or current model:** librarian execution throws the existing no-model error.
+
+## Alternatives
+
+### Keep transient transition notifications alongside entries
+
+- **Status:** Rejected
+- **Decision:** It duplicates one event in two UI surfaces. The durable entry is sufficient feedback for an actual state change.
+
+### Derive tool names while rendering
+
+- **Status:** Rejected
+- **Decision:** Historical entries would silently change when the attachable toolset changes.
+
+### Version the entry immediately
+
+- **Status:** Rejected
+- **Decision:** There is one accepted shape and no migration behavior. A version adds ceremony without distinguishing supported semantics.
+
+### Filter resolved models through `getAvailable()`
+
+- **Status:** Rejected
+- **Decision:** It diverges from Pi's native model-pattern behavior and blocks intentional custom or differently authenticated models. Nested execution owns operational model failures.
+
+### Warn once at startup or once per session
+
+- **Status:** Rejected
+- **Decision:** Each resolver warning or fallback should remain explicit at its point of use.
+
+## Implementation Plan
+
+- [x] Phase 1: Raise the Pi dependency floor
+  - Goal: Make the new Pi APIs and thinking level part of pi-librarian's supported runtime contract.
+  - Files: `package.json`, `package-lock.json`, `extensions/librarian/settings.ts`, tests.
+  - Work: Raise relevant `@earendil-works/pi-*` development and peer dependency minimums to 0.80.6, refresh the npm lockfile, and accept `max` through a local runtime list checked against Pi's public `ThinkingLevel` type.
+  - Validation: Inspect root constraints and resolved package versions; include package validation in the full quality gate.
+
+- [x] Phase 2: Render durable attach state
+  - Goal: Replace duplicate transition notifications with strict-shape transcript accordions.
+  - Files: `extensions/librarian/attach.ts`, `extensions/librarian.ts`, `test/attach.test.ts`.
+  - Work: Define the current entry shape; snapshot tool names from `ATTACHABLE_TOOL_NAMES`; register the entry renderer; preserve compact content while expanded; render every non-current shape generically; remove actual-transition notifications; make no-op wording symmetrical.
+  - Validation: Focused tests for state restoration, persisted snapshots, compact and expanded rendering, generic invalid-shape rendering, and active-tool mutation.
+
+- [x] Phase 3: Adopt canonical model resolution
+  - Goal: Use `resolveCliModel` with Pi-native model-pattern and fallback behavior.
+  - Files: `extensions/librarian/model.ts`, `extensions/librarian.ts`, `test/model.test.ts`.
+  - Work: Resolve bare and provider-scoped configured patterns through Pi; accept returned models and warnings directly; return a specific warning when falling back to the current model; preserve no-model behavior.
+  - Validation: Focused tests for bare and provider-scoped fuzzy resolution, Pi model priority, custom-ID fallback, resolution errors, warning text, current fallback, missing fallback, and preservation of `max`.
+
+- [x] Phase 4: Integration validation
+  - Goal: Prove the upgrade works as one coherent change.
+  - Files: implementation and test files above; design status only if implementation materially diverges.
+  - Work: Run focused tests, typecheck against the upgraded Pi API, and inspect the final staged/unstaged split without altering it.
+  - Validation: `npm test -- test/attach.test.ts test/model.test.ts test/settings.test.ts`; `npm run check`.

package/extensions/librarian/attach.ts

@@ -1,21 +1,28 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { safeParseTypeBoxValue } from "../shared/typebox.ts";
 import { ATTACHABLE_TOOL_NAMES } from "./tools/names.ts";
 
 export const ATTACH_ENTRY_TYPE = "pi-librarian:attach";
 
-const ATTACH_STATE_SCHEMA = Type.Object({
+const ATTACH_ENTRY_SCHEMA = Type.Object({
   attached: Type.Boolean(),
+  tools: Type.Array(Type.String()),
 });
 
+export interface AttachEntryData {
+  attached: boolean;
+  tools: string[];
+}
+
 export function readAttachState(ctx: ExtensionContext): boolean {
   let attached = false;
   for (const entry of ctx.sessionManager.getEntries()) {
     if (entry.type !== "custom" || entry.customType !== ATTACH_ENTRY_TYPE) {
       continue;
     }
-    const parsed = safeParseTypeBoxValue(ATTACH_STATE_SCHEMA, entry.data);
+    const parsed = safeParseTypeBoxValue(ATTACH_ENTRY_SCHEMA, entry.data);
     if (parsed) {
       attached = parsed.attached;
     }
@@ -37,5 +44,25 @@ export function applyAttachState(pi: ExtensionAPI, attached: boolean): void {
 
 export function setAttachState(pi: ExtensionAPI, attached: boolean): void {
   applyAttachState(pi, attached);
-  pi.appendEntry(ATTACH_ENTRY_TYPE, { attached });
+  pi.appendEntry<AttachEntryData>(ATTACH_ENTRY_TYPE, {
+    attached,
+    tools: [...ATTACHABLE_TOOL_NAMES],
+  });
+}
+
+export function renderAttachEntry(data: unknown, expanded: boolean, theme: Theme): Component {
+  const entry = safeParseTypeBoxValue(ATTACH_ENTRY_SCHEMA, data);
+  if (!entry) {
+    return new Text(theme.fg("warning", "Librarian attach state unavailable"), 0, 0);
+  }
+
+  const state = entry.attached ? "attached" : "detached";
+  const color = entry.attached ? "success" : "muted";
+  let text = theme.fg(color, `Librarian tools ${state}`);
+
+  if (expanded) {
+    text += `\n${entry.tools.map((tool) => theme.fg("dim", `  ${tool}`)).join("\n")}`;
+  }
+
+  return new Text(text, 0, 0);
 }

package/extensions/librarian/model.ts

@@ -1,6 +1,6 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ExtensionContext, resolveCliModel } from "@earendil-works/pi-coding-agent";
 import type { ModelReference } from "./settings.ts";
 
 export type LibrarianModelSource = "configured" | "current";
@@ -9,31 +9,21 @@ export interface LibrarianModelResolution {
   model: Model<Api>;
   thinkingLevel: ThinkingLevel;
   source: LibrarianModelSource;
+  warning?: string;
 }
 
-function isAlias(modelId: string): boolean {
-  return modelId.endsWith("-latest") || !/-\d{8}$/.test(modelId);
-}
-
-function bestModelMatch(models: Model<Api>[], pattern: string): Model<Api> | undefined {
-  const normalizedPattern = pattern.toLowerCase();
-  const exactMatches = models.filter((model) => model.id.toLowerCase() === normalizedPattern);
-  if (exactMatches.length === 1) {
-    return exactMatches[0];
+function configuredModelFailure(
+  configuredModel: ModelReference,
+  error: string | undefined,
+  warning: string | undefined,
+): string {
+  if (error) {
+    return error;
   }
-
-  const partialMatches = models.filter(
-    (model) =>
-      model.id.toLowerCase().includes(normalizedPattern) ||
-      model.name?.toLowerCase().includes(normalizedPattern),
-  );
-  if (partialMatches.length === 0) {
-    return undefined;
+  if (warning) {
+    return warning;
   }
-
-  const aliases = partialMatches.filter((model) => isAlias(model.id));
-  const candidates = aliases.length > 0 ? aliases : partialMatches;
-  return candidates.toSorted((a, b) => b.id.localeCompare(a.id))[0];
+  return `Could not resolve configured model "${configuredModel}".`;
 }
 
 export function resolveLibrarianModel(
@@ -41,19 +31,41 @@ export function resolveLibrarianModel(
   configuredModel: ModelReference | undefined,
   thinkingLevel: ThinkingLevel,
 ): LibrarianModelResolution | undefined {
+  let failure: string | undefined;
+
   if (configuredModel) {
-    const providerModels = ctx.modelRegistry
-      .getAvailable()
-      .filter((model) => model.provider === configuredModel.provider);
-    const match = bestModelMatch(providerModels, configuredModel.modelId);
-    if (match) {
-      return { model: match, thinkingLevel, source: "configured" };
+    const resolved = resolveCliModel({
+      ...(configuredModel.provider ? { cliProvider: configuredModel.provider } : {}),
+      cliModel: configuredModel.modelId,
+      modelRegistry: ctx.modelRegistry,
+    });
+    if (resolved.model) {
+      const resolution: LibrarianModelResolution = {
+        model: resolved.model,
+        thinkingLevel,
+        source: "configured",
+      };
+      if (resolved.warning) {
+        resolution.warning = resolved.warning;
+      }
+      return resolution;
     }
+
+    failure = configuredModelFailure(configuredModel, resolved.error, resolved.warning);
   }
 
   if (!ctx.model) {
     return undefined;
   }
 
-  return { model: ctx.model, thinkingLevel, source: "current" };
+  if (!configuredModel) {
+    return { model: ctx.model, thinkingLevel, source: "current" };
+  }
+
+  return {
+    model: ctx.model,
+    thinkingLevel,
+    source: "current",
+    warning: `Configured librarian model "${configuredModel}" is unavailable: ${failure} Using current model "${ctx.model.provider}/${ctx.model.id}".`,
+  };
 }

package/extensions/librarian/settings.ts

@@ -5,13 +5,24 @@ import { SettingsManager } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { parseTypeBoxValue } from "../shared/typebox.ts";
 
+const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const satisfies readonly ThinkingLevel[];
+
 const THINKING_LEVEL_SCHEMA = Type.Union([
-  Type.Literal("off"),
-  Type.Literal("minimal"),
-  Type.Literal("low"),
-  Type.Literal("medium"),
-  Type.Literal("high"),
-  Type.Literal("xhigh"),
+  Type.Literal(THINKING_LEVELS[0]),
+  Type.Literal(THINKING_LEVELS[1]),
+  Type.Literal(THINKING_LEVELS[2]),
+  Type.Literal(THINKING_LEVELS[3]),
+  Type.Literal(THINKING_LEVELS[4]),
+  Type.Literal(THINKING_LEVELS[5]),
+  Type.Literal(THINKING_LEVELS[6]),
 ]);
 
 const LIBRARIAN_FILE_SETTINGS_SCHEMA = Type.Object({
@@ -35,12 +46,12 @@ type LibrarianFileSettings = Static<typeof LIBRARIAN_FILE_SETTINGS_SCHEMA>;
 
 export class ModelReference {
   constructor(
-    readonly provider: string,
+    readonly provider: string | undefined,
     readonly modelId: string,
   ) {}
 
   toString(): string {
-    return `${this.provider}/${this.modelId}`;
+    return this.provider ? `${this.provider}/${this.modelId}` : this.modelId;
   }
 }
 
@@ -92,7 +103,10 @@ function parseModelReference(value: string | undefined): ModelReference | undefi
   }
 
   const slashIndex = trimmed.indexOf("/");
-  if (slashIndex <= 0 || slashIndex === trimmed.length - 1) {
+  if (slashIndex === -1) {
+    return new ModelReference(undefined, trimmed);
+  }
+  if (slashIndex === 0 || slashIndex === trimmed.length - 1) {
     return undefined;
   }
 

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

@@ -29,10 +29,10 @@ export function createCheckoutRepoTool(cacheDir: string) {
     name: LIBRARIAN_TOOL_NAMES.checkoutRepo,
     label: "Checkout repo",
     description: "Clone a repo (blob-less partial clone, cached locally).",
-    promptSnippet: "Clone a repo",
+    promptSnippet: "Clone a repo locally",
     promptGuidelines: [
-      "Use when you want to deep dive on a specific repo. Follow up using grep/read/find/ls on the returned path, and `git -C <path> log/blame/diff` for history.",
-      "Do not checkout repos directly using `git`. Always use this tool instead.",
+      "Use checkout_repo to deep dive on a specific repo, then grep/read/find/ls on the returned path and `git -C <path> log/blame/diff` for history.",
+      "Do not clone repos directly with `git`; always use checkout_repo.",
     ],
     parameters: CheckoutRepoParams,
 

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

@@ -46,10 +46,9 @@ export function createProvideResultsTool(onFindings: (findings: Findings) => voi
     name: LIBRARIAN_TOOL_NAMES.provideResults,
     label: "Provide results",
     description: "Report your findings in structured form.",
-    promptSnippet: "Provide results",
+    promptSnippet: "Report findings",
     promptGuidelines: [
-      "Tool must be called before the turn ends.",
-      "After calling this tool, the turn will end.",
+      "provide_results ends the turn; call it once, after you've gathered your findings.",
     ],
     parameters: FindingsSchema,
 

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

@@ -47,11 +47,11 @@ export function createReadGitHubFileTool(githubClient: GitHubClientProvider) {
     name: LIBRARIAN_TOOL_NAMES.readGitHubFile,
     label: "Read GitHub file",
     description: `Read a single file (or list a directory) from a GitHub repo via the API, without cloning.`,
-    promptSnippet: "Read Github file",
+    promptSnippet: "Read a file/directory from GitHub",
     promptGuidelines: [
-      "For quick peeks — package.json, a README, one source file.",
-      "For multi-file exploration prefer checkout_repo.",
-      "Use offset/limit for larger files.",
+      "Use read_github_file for quick peeks — package.json, a README, one source file.",
+      "For multi-file exploration, prefer checkout_repo over read_github_file.",
+      "Use read_github_file's offset/limit for larger files.",
     ],
     parameters: ReadGitHubFileParams,
 

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

@@ -18,7 +18,8 @@ const SearchCodeParams = Type.Object({
   }),
   regex: Type.Optional(
     Type.Boolean({
-      description: "Treat `pattern` as a regular expression instead of literals.",
+      description:
+        "Treat `pattern` as a regular expression instead of literals. Supports `(?s)` for multi-line patterns.",
     }),
   ),
   repo: Type.Optional(
@@ -59,11 +60,10 @@ export const searchCodeTool = defineTool<typeof SearchCodeParams, SearchCodeDeta
   name: LIBRARIAN_TOOL_NAMES.searchCode,
   label: "Search code across repos",
   description: "Cross-repo code search over public source code.",
-  promptSnippet: "Search code across repos",
+  promptSnippet: "Search public code across repos",
   promptGuidelines: [
-    "When `regex` is true, `pattern` can also use `(?s)` for multi-line patterns.",
-    "Results are CANDIDATES to verify via checkout_repo/read_github_file — never cite them directly.",
-    "This searches public GitHub code only. Use search_github_code when private repository access matters.",
+    "search_code results are candidates to verify via checkout_repo/read_github_file — never cite them directly.",
+    "search_code covers public GitHub code only; use search_github_code when private repository access is required.",
   ],
   parameters: SearchCodeParams,
 

package/extensions/librarian/tools/search-github-code.ts

@@ -89,10 +89,9 @@ export function createSearchGitHubCodeTool(githubClient: GitHubClientProvider) {
     label: "Search GitHub code",
     description:
       "GitHub REST code search over public code and private repositories your configured GitHub auth can access.",
-    promptSnippet: "Search GitHub code",
+    promptSnippet: "Search GitHub code (incl. private repos)",
     promptGuidelines: [
-      "Results are CANDIDATES to verify via checkout_repo/read_github_file — never cite them directly.",
-      "GitHub REST code search is literal/tokenized and does not support regex; use search_code for public regex/global code search.",
+      "search_github_code is literal/tokenized and does not support regex; use search_code for public regex/global search.",
     ],
     parameters: SearchGitHubCodeParams,
 

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

@@ -34,8 +34,8 @@ export function createSearchReposTool(githubClient: GitHubClientProvider) {
     name: LIBRARIAN_TOOL_NAMES.searchRepos,
     label: "Search repos metadata",
     description: "Discover GitHub repositories.",
-    promptSnippet: "Search repos metadata",
-    promptGuidelines: ["Use for questions like 'what are the popular X libraries'."],
+    promptSnippet: "Search GitHub repos by metadata",
+    promptGuidelines: ['Use search_repos for questions like "what are the popular X libraries".'],
     parameters: SearchReposParams,
 
     async execute(_toolCallId, params) {

package/extensions/librarian.ts

@@ -1,7 +1,14 @@
 import type { ExtensionAPI, SessionStartEvent } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { applyAttachState, readAttachState, setAttachState } from "./librarian/attach.ts";
+import {
+  ATTACH_ENTRY_TYPE,
+  type AttachEntryData,
+  applyAttachState,
+  readAttachState,
+  renderAttachEntry,
+  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";
@@ -50,6 +57,10 @@ export default function librarianExtension(pi: ExtensionAPI): void {
   const settings = loadSettings();
   const githubClient = createGitHubClientProvider();
 
+  pi.registerEntryRenderer<AttachEntryData>(ATTACH_ENTRY_TYPE, (entry, { expanded }, theme) =>
+    renderAttachEntry(entry.data, expanded, theme),
+  );
+
   const attachableTools = [
     createSearchReposTool(githubClient),
     searchCodeTool,
@@ -61,7 +72,6 @@ export default function librarianExtension(pi: ExtensionAPI): void {
   for (const tool of attachableTools) {
     pi.registerTool({
       ...tool,
-      description: `${tool.description} (Librarian tool, attached via /librarian: use for quick single lookups; delegate multi-step research to the librarian tool.)`,
       renderCall(args, theme) {
         const { verb, subject } = formatTraceLine(
           { name: tool.name, args, id: "", startedAt: 0 } satisfies TraceCall,
@@ -81,10 +91,9 @@ export default function librarianExtension(pi: ExtensionAPI): void {
     label: "Librarian",
     description:
       "Understand complex, multi-repo codebases, exploring cross-repo relationships, analyzing architectural patterns, finding implementations across codebases, understanding code evolution/commit history, diving deep on specific code bases, getting comprehensive feature explanations, and exploring end-to-end system design across within or across repositories.",
-    promptSnippet:
-      "librarian: research GitHub repos (implementation questions, ecosystem comparisons, usage examples) and return cited findings",
+    promptSnippet: "Research GitHub repos and codebases, returning cited findings",
     promptGuidelines: [
-      "If a single file or reference must be located, you may use other means (search for downloaded dependencies, web search, etc), but for deeper queries that will take multiple steps to resolve, prefer the librarian.",
+      "Use librarian for deep, multi-step research across repos; for a single file or reference, prefer cheaper means (downloaded dependencies, web search or fetch).",
     ],
     parameters: LibrarianParams,
 
@@ -96,6 +105,9 @@ export default function librarianExtension(pi: ExtensionAPI): void {
           "No model available for the librarian. Configure librarian.model or select a session model.",
         );
       }
+      if (resolution.warning) {
+        ctx.ui.notify(resolution.warning, "warning");
+      }
 
       const extraTools = resolveExtraTools(pi.getAllTools(), settings);
 
@@ -169,19 +181,13 @@ export default function librarianExtension(pi: ExtensionAPI): void {
         argument === "on" ? true : argument === "off" ? false : !currentlyAttached;
       if (nextAttached === currentlyAttached) {
         ctx.ui.notify(
-          nextAttached ? "Librarian tools already attached." : "Librarian tools not attached.",
+          nextAttached ? "Librarian tools already attached." : "Librarian tools already detached.",
           "info",
         );
         return;
       }
 
       setAttachState(pi, nextAttached);
-      ctx.ui.notify(
-        nextAttached
-          ? `Attached librarian tools: ${ATTACHABLE_TOOL_NAMES.join(", ")}`
-          : "Detached librarian tools.",
-        "info",
-      );
     },
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thurstonsand/pi-librarian",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "GitHub research subagent for pi: deep-dive specific repos, discover across the ecosystem",
   "license": "MIT",
@@ -43,10 +43,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@earendil-works/pi-agent-core": "^0.80.2",
-    "@earendil-works/pi-ai": "^0.80.2",
-    "@earendil-works/pi-coding-agent": "^0.80.2",
-    "@earendil-works/pi-tui": "^0.80.2",
+    "@earendil-works/pi-agent-core": "^0.80.6",
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-tui": "^0.80.6",
     "@types/node": "^25.6.2",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.3",
@@ -55,10 +55,10 @@
     "vitest": "^4.1.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.80.2",
-    "@earendil-works/pi-ai": ">=0.80.2",
-    "@earendil-works/pi-coding-agent": ">=0.80.2",
-    "@earendil-works/pi-tui": ">=0.80.2",
+    "@earendil-works/pi-agent-core": ">=0.80.6",
+    "@earendil-works/pi-ai": ">=0.80.6",
+    "@earendil-works/pi-coding-agent": ">=0.80.6",
+    "@earendil-works/pi-tui": ">=0.80.6",
     "typebox": ">=1.1.24"
   },
   "lint-staged": {