@aeondave/pi-skill-optimizer 3.0.1 → 3.1.1

package/BENCHMARK.md

@@ -62,7 +62,7 @@ The benchmark asks:
 2. Is the stable base byte-identical across unrelated human requests?
 3. Does bounded prefetch improve first-turn recall without changing that base?
 4. Can `skill_search` recover relevant tail skills through bounded pagination?
-5. Can `tool_search` defer schemas without making required tools unavailable?
+5. Can `optimizer_tool_search` defer schemas without making required tools unavailable?
 6. Do output and history reductions preserve protected evidence and exact recovery?
 7. Is every accepted serialized transformation smaller?
 8. What do providers report for tokens, cache reads, cache writes, and cost?
@@ -174,7 +174,7 @@ Blocking invariants:
 
 - core, configured, and already used tools remain active;
 - inactive schemas are absent from the initial provider request;
-- `tool_search` remains active while searchable definitions remain;
+- `optimizer_tool_search` remains active while searchable definitions remain;
 - activation makes selected tools callable in the same session;
 - activation is additive and cannot strand an active provider tool loop;
 - schema indexing work and response pagination remain bounded;
@@ -188,7 +188,7 @@ Reported metrics:
 tool_recall
 initial_tool_schema_bytes
 activated_tool_schema_bytes
-tool_search_calls
+optimizer_tool_search_calls
 activation_failures
 ```
 

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes are documented here.
 
+## Unreleased
+
+## 3.1.1 - 2026-10-08
+
+### Fixed
+
+- Optimize the native Pi transcript before provider conversion, keeping worker notifications, shell
+  output and summaries out of human-intent routing and prefetch insertion.
+- Preserve structured system sections and tool declarations; respect provider scoping when the
+  request has no selected model.
+- Label prefetch as catalog metadata, not loaded instructions or usage evidence. Emit its actual
+  catalog fingerprint and report selected skills only when an overlay was inserted.
+- Recognize native Pi skill-activation calls without double-counting `skill_search` usage.
+
+## 3.1.0 - 2026-10-03
+
+### Breaking
+
+- Rename the optimizer's model-callable `tool_search` to `optimizer_tool_search`. Explicit tool calls must use the new name. Pi's built-in `tool_search` now loads alongside the optimizer without a replacement warning.
+
+### Fixed
+
+- Preserve an active built-in `tool_search` during optimizer replanning.
+- Retain tools activated later by Pi or another extension, and honor `alwaysTools` for initially inactive `deferred` or `codemode` tools while respecting hidden and inactive direct tools.
+- Capture an explicitly requested benchmark catalog from Pi 1.0's `before_agent_start` skill options.
+
+### Changed
+
+- Require Pi 1.0.0 or newer for this release.
+- Run typechecking and host integration tests against Pi 1.0.0 development packages.
+- Add a reproducible Pi CLI black-box smoke test for the packed artifact.
+
 ## 3.0.1 - 2026-09-30
 
 ### Fixed

package/README.md

@@ -14,7 +14,7 @@ No embedding service or extra model call for ordinary routing. No changes to you
 
 ## Install
 
-Requires **Pi 0.87.1+** and **Node.js 26.3+**. Upgrade both before installing v3.
+Requires **Pi 1.0.0+** and **Node.js 26.3+**. Upgrade both before installing v3.1.
 
 ```bash
 pi install npm:@aeondave/pi-skill-optimizer
@@ -26,19 +26,18 @@ Restart Pi, then check that it loaded:
 /skill-optimizer
 ```
 
-Pi 0.99.0+ also includes a built-in `tool-search` extension. This optimizer provides
-its own `tool_search`, so disable the built-in under **Built-in extensions** in
-`pi config` to avoid the startup conflict warning. Use the global setting for a
-personal install, or `pi config -l` for a project-only install. The optimizer
-continues to find registered `deferred` and `codemode` tools. See the
-[tool-search configuration](docs/CONFIGURATION.md#replacing-the-built-in-tool-search).
+On Pi 1.0.0, the optimizer's search tool is `optimizer_tool_search`. Pi's
+built-in `tool_search` can load alongside it without a name conflict. If you
+previously disabled `builtin:tool-search` to avoid the warning, you can remove
+that setting after updating the optimizer. See the
+[tool-search configuration](docs/CONFIGURATION.md#tool-search-and-pi-100).
 
 That's enough to start. Optionally run `/skill-optimizer init` to generate routing hints for your library. **Init uses your current Pi model and may incur cost**; normal discovery does not.
 
 | Need | Command |
 | --- | --- |
 | Install only in this project | `pi install -l npm:@aeondave/pi-skill-optimizer` |
-| Pin the current release | `pi install npm:@aeondave/pi-skill-optimizer@3.0.1` |
+| Pin the current release | `pi install npm:@aeondave/pi-skill-optimizer@3.1.1` |
 | Update an unpinned install | `pi update npm:@aeondave/pi-skill-optimizer` |
 
 Restart after updating. Pinned installs stay pinned until you explicitly install another version.
@@ -62,10 +61,14 @@ Say you have hundreds of skills, but you're asking Pi to fix a database migratio
 
 AUTO keeps a compact, stable index of **all eligible names**, adds relevant descriptions beside your latest request, and exposes `skill_search` for loading complete instructions. The stable index does not change when your question changes.
 
+Prefetch is a catalog, not loaded instructions or evidence that a skill was used. Worker updates,
+extension notifications and summaries do not replace your request as the routing signal or receive
+its overlay; there is no need to acknowledge the catalog.
+
 | Area | What AUTO does | What stays available |
 | --- | --- | --- |
 | Skills | Shortens catalog descriptions; prefetches relevant ones | Every eligible name and exact full-instruction loading |
-| Tools | Defers less relevant schemas behind `tool_search` | Protected, configured, already-used and activated tools |
+| Tools | Defers less relevant schemas behind `optimizer_tool_search` | Protected, configured, already-used and activated tools |
 | Large results | Applies deterministic reduction; lossless columnar JSON where suitable | Complete originals through `retrieve_output` during archive retention |
 | Repeated results | Replaces later exact duplicates with recovery references | The first result, errors, protected evidence and mixed media |
 
@@ -83,7 +86,7 @@ You can leave AUTO running with its defaults.
 
 An optional setup hint appears at the first eligible prompt when initialization is missing or needs attention. It never starts init for you or adds instructions to the model's context.
 
-Pi gets three tools: `skill_search`, `tool_search` and `retrieve_output`. Skill search is paginated and exact loads accept only registered names. Output recovery uses opaque identifiers, not exposed archive paths.
+Pi gets three optimizer tools: `skill_search`, `optimizer_tool_search` and `retrieve_output`. Pi may also provide its built-in `tool_search`. Skill search is paginated and exact loads accept only registered names. Output recovery uses opaque identifiers, not exposed archive paths.
 
 Skills can be useful even when you never mention them. Init can tag architecture,
 testing and behavioral guidance by activity, so a matched specialist can bring

package/docs/ARCHITECTURE.md

@@ -20,8 +20,19 @@ The index contains no filesystem paths. With the same catalog, profile, and conf
 
 AUTO extracts intent only from genuine human text in Anthropic, OpenAI Chat and Responses, Gemini, Mistral, and Pi's structured `pi-messages` request shapes. A catalog may live in a system or developer block, but neither is treated as human intent. Assistant text, tool or function results, injected context, image metadata, and empty input cannot create a ranking signal.
 
+At runtime, catalog optimization and usage extraction run in Pi's `context_with_system` hook,
+before provider conversion erases custom-message provenance. Native `custom`, `bashExecution`,
+`branchSummary`, `compactionSummary` and `toolResult` messages remain intact and cannot become
+the query or overlay target. Structured system sections and tool declarations are preserved;
+request-local clones do not modify persisted conversation entries.
+
 Ranking uses exact matching, BM25F, bounded name and alias typo recovery, reciprocal-rank fusion, diversity, profile evidence, and decayed usage evidence. It scores full source descriptions, then appends a bounded set of verbatim skill names and descriptions (not the full `SKILL.md` instructions) to the latest human block. The overlay is separate from the stable prefix, fingerprinted, idempotent, and omitted when there is no valid target.
 
+The resolver labels prefetch as discovery metadata, not loaded instructions or usage evidence.
+Diagnostics count only overlays actually inserted. Usage follows explicit human mentions and skill
+activations; the `skill_search` executor records its own loads/resources, so transcript scanning
+does not count those calls twice. Catalog selections and assistant acknowledgments are not usage.
+
 Optional init-generated activation tags distinguish specialists, workflow methods
 and behavioral discipline. An admitted specialist can bring one activity-matched
 supporting skill into the ordinary prefetch budget; this does not recursively
@@ -30,9 +41,9 @@ expand dependencies or treat a behavioral tag as universal. See
 
 ## Dynamic tools
 
-AUTO keeps protected and predicted tools active and leaves the rest behind `tool_search`. Search is bounded and paginated. A returned result is activated through Pi's runtime API without replacing already active tools. Core, configured, and previously used tools remain callable, so an in-progress tool loop cannot be stranded. Weak or absent routing signal fails open to every permitted tool; safety wins, but that request may retain the full schema cost.
+AUTO keeps protected and predicted tools active and leaves the rest behind `optimizer_tool_search`. Search is bounded and paginated. A returned result is activated through Pi's runtime API without replacing already active tools. Core, configured, and previously used tools remain callable, so an in-progress tool loop cannot be stranded. Pi's built-in `tool_search` remains active when the host enables it. Weak or absent routing signal fails open to every permitted tool; safety wins, but that request may retain the full schema cost.
 
-Selection is recalculated before each agent run, not just the first request. Used tools and explicit search results stay active for the session. The discoverable set starts from Pi's initially active tools plus the optimizer's own resolvers; tools that were initially unavailable are not silently added. This is schema routing, not authorization: another extension's call-time permission checks remain authoritative.
+Selection is recalculated before each agent run, not just the first request. Used tools and explicit search results stay active for the session. The discoverable set starts from Pi's initially active tools plus the optimizer's own resolvers. Newly activated host tools are retained; inactive `deferred` and `codemode` tools can be selected through search or `alwaysTools`. Inactive direct and hidden tools are not silently added. This is schema routing, not authorization: another extension's call-time permission checks remain authoritative.
 
 See Pi's [extension and dynamic-tool API](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md).
 

package/docs/CONFIGURATION.md

@@ -7,18 +7,18 @@
 | Tool | Purpose |
 | --- | --- |
 | `skill_search` | Paginated skill search plus exact `load`, contained `resource`, and explicit `location` actions |
-| `tool_search` | Search deferred tool definitions and activate bounded matches additively |
+| `optimizer_tool_search` | Search deferred tool definitions and activate bounded matches additively |
 | `retrieve_output` | Recover archived output or a deduplicated history result by opaque identifier |
 
 Exact skill loading accepts only registered names. Resource and location resolution use canonical paths and containment checks to reject traversal and symlink escape. Search cursors bind to the query, catalog and ranked name order; a changed profile or usage prior that reorders results requires a new search, rather than duplicating or skipping a page. This is an exact local resolver guarantee, not a guarantee that the model will select the right skill; see the separate [ranking diagnostics](RANKING.md) and [historical model benchmark](../BENCHMARK.md).
 
 `excludeSkills` removes names from discovery and search, not from explicit exact loading. It is a routing preference, not an access-control boundary. The three resolver tools return their content without another output-reduction pass, so full skill instructions and recovered originals remain readable.
 
-### Replacing the built-in tool search
+### Tool search and Pi 1.0.0
 
-The extension registers `tool_search` itself, so it replaces Pi's built-in `builtin:tool-search` extension (the built-in is marked replaceable and the tool name decides). While both are in the load set, Pi prints a startup warning that the built-in was not loaded. The optimizer indexes eligible registered tools, including ones it deferred from Pi's active set and Pi-registered `deferred` or `codemode` tools. Matching inactive results activate additively; unrelated fallback results remain inactive. Pi's built-in MCP extension can still activate `tool_search` by name when a deferred server connects.
+The extension registers `optimizer_tool_search`, leaving Pi's built-in `tool_search` available under its own name. The optimizer indexes eligible registered tools, including ones it deferred from Pi's active set and Pi-registered `deferred` or `codemode` tools. Matching inactive results activate additively; unrelated fallback results remain inactive. An already active built-in `tool_search` stays active during optimizer replanning. Pi's built-in MCP extension can activate its own `tool_search` when a deferred server connects.
 
-To silence the warning, disable the built-in where the optimizer runs: toggle `tool-search` off under Built-in extensions in `pi config`, or set `"extensions": ["-builtin:tool-search"]` in the applicable `settings.json`. A personal install needs the global setting in `~/.pi/agent/settings.json`; a project-only install can use `.pi/settings.json`. For development with `pi -e ./src/index.ts`, set the toggle locally or globally. Re-enable the built-in if you remove the optimizer.
+If an older optimizer release led you to add `-builtin:tool-search` in `~/.pi/agent/settings.json` or `.pi/settings.json`, remove that entry after updating if you want Pi's built-in search available again. The built-in is inactive by default unless enabled in Pi's `defaultTools` or activated by Pi for deferred MCP tools; the optimizer's search stays available independently. Existing explicit calls to the optimizer's old `tool_search` name must use `optimizer_tool_search` after this update.
 
 ## Commands
 
@@ -55,7 +55,7 @@ Global configuration lives at `~/.pi/agent/skill-optimizer/config.json`. A proje
 | `providers` | `[]` | Provider allowlist; empty means all |
 | `toolPrefetchMax` | `5` | Maximum proactive tool activation |
 | `toolSearchPageSize` | `8` | Default tool-search page size |
-| `alwaysTools` | `[]` | Tools that remain active |
+| `alwaysTools` | `[]` | Keep initially active tools and named `deferred` or `codemode` tools active; hidden tools remain unavailable |
 | `historyDedupMinBytes` | `4096` | Minimum result size for history deduplication |
 | `usageHalfLifeDays` | `30` | Usage-evidence decay half-life |
 | `usageMaxEntries` | `2048` | Persistent usage-evidence bound |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeondave/pi-skill-optimizer",
-  "version": "3.0.1",
+  "version": "3.1.1",
   "private": false,
   "type": "module",
   "description": "Less repeated context for Pi: local skill routing, on-demand tools, and recoverable output reduction.",
@@ -43,12 +43,13 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test test/request.test.ts test/history.test.ts test/skills.test.ts test/skill-loader.test.ts test/tools.test.ts test/optimize.test.ts test/profile.test.ts test/activation.test.ts test/generate.test.ts test/init.test.ts test/init-readiness.test.ts test/config.test.ts test/fuzz.test.ts test/output.test.ts test/output-recovery.test.ts test/runtime.test.ts test/host-runtime.test.ts test/stats.test.ts test/usage.test.ts test/persistence.test.ts test/corpus.test.ts test/evaluation.test.ts test/luna.test.ts test/release-metadata.test.ts",
+    "test": "node --import tsx --test test/request.test.ts test/history.test.ts test/skills.test.ts test/skill-loader.test.ts test/tools.test.ts test/optimize.test.ts test/profile.test.ts test/activation.test.ts test/generate.test.ts test/init.test.ts test/init-readiness.test.ts test/config.test.ts test/fuzz.test.ts test/output.test.ts test/output-recovery.test.ts test/runtime.test.ts test/host-runtime.test.ts test/stats.test.ts test/usage.test.ts test/persistence.test.ts test/corpus.test.ts test/capture-catalog.test.ts test/evaluation.test.ts test/luna.test.ts test/release-metadata.test.ts",
     "measure": "node --import tsx scripts/measure.ts",
     "bench": "node --import tsx scripts/bench.ts",
     "bench:perf": "node --import tsx scripts/perf-bench.ts",
     "bench:ranking": "node --import tsx scripts/ranking-bench.ts",
     "bench:output": "node --import tsx scripts/output-bench.ts",
+    "smoke:blackbox": "node --import tsx scripts/black-box-smoke.ts",
     "corpus:build": "node --import tsx scripts/build-real-corpus.ts",
     "bench:real": "node --import tsx scripts/evaluate-real-corpus.ts"
   },
@@ -69,8 +70,8 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.87.1",
-    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
     "@types/node": "^26.6.3",
     "tsx": "^4.23.13",
     "typebox": "^1.3.34",
@@ -80,6 +81,6 @@
     "extensions": [
       "./src/index.ts"
     ],
-    "image": "https://raw.githubusercontent.com/AeonDave/pi-skill-optimizer/v3.0.1/assets/banner.png"
+    "image": "https://raw.githubusercontent.com/AeonDave/pi-skill-optimizer/v3.1.1/assets/banner.png"
   }
 }

package/src/index.ts

@@ -110,7 +110,8 @@ const FLUSH_INTERVAL_MS = 15_000;
 const LOAD_RETRY_MS = 1_000;
 const MAX_SEEN_EVIDENCE = 4_096;
 const MAX_HISTORY_ARTIFACTS = 128;
-const PROTECTED_RUNTIME_TOOLS = ["skill_search", "tool_search", "retrieve_output"] as const;
+const PROTECTED_RUNTIME_TOOLS = ["skill_search", "optimizer_tool_search", "retrieve_output"] as const;
+const RESOLVER_RESULT_TOOLS = new Set<string>([...PROTECTED_RUNTIME_TOOLS, "tool_search"]);
 
 function isHostSearchableTool(tool: object): boolean {
 	return "exposure" in tool && (tool.exposure === "deferred" || tool.exposure === "codemode");
@@ -574,16 +575,30 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 
 	const rebuildToolCatalog = (state: RuntimeSnapshot): ToolDiscoveryCatalog => {
 		const allTools = pi.getAllTools();
+		const activeNames = new Set(pi.getActiveTools().map((name) => name.toLowerCase()));
+		const alwaysToolPrefixes = state.config.alwaysTools
+			.map((pattern) => pattern.trim().toLowerCase())
+			.filter((pattern) => pattern.length > 0);
 		permittedToolNames ??= new Set([
-			...pi.getActiveTools().map((name) => name.toLowerCase()),
+			...activeNames,
 			...PROTECTED_RUNTIME_TOOLS,
 		]);
 		for (const tool of allTools) {
-			if (!isHostHiddenTool(tool)) continue;
 			const name = tool.name.toLowerCase();
-			permittedToolNames.delete(name);
-			retainedToolNames.delete(name);
-			deactivatedToolNames.delete(name);
+			if (isHostHiddenTool(tool)) {
+				permittedToolNames.delete(name);
+				retainedToolNames.delete(name);
+				deactivatedToolNames.delete(name);
+				continue;
+			}
+			if (activeNames.has(name)) {
+				const newlyActive = !permittedToolNames.has(name);
+				const reactivated = deactivatedToolNames.delete(name);
+				if (newlyActive || reactivated) retainedToolNames.add(name);
+				permittedToolNames.add(name);
+			} else if (isHostSearchableTool(tool) && alwaysToolPrefixes.some((pattern) => name.startsWith(pattern))) {
+				permittedToolNames.add(name);
+			}
 		}
 		const discoverable = allTools.filter((tool) =>
 			!isHostHiddenTool(tool) && permittedToolNames?.has(tool.name.toLowerCase()),
@@ -684,8 +699,8 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 	});
 
 	pi.registerTool({
-		name: "tool_search",
-		label: "Tool Search",
+		name: "optimizer_tool_search",
+		label: "Optimizer Tool Search",
 		description: "Search local tool definitions and activate matching inactive tools without disabling current tools.",
 		promptSnippet: "Search and activate additional tools on demand",
 		parameters: TOOL_SEARCH_PARAMS,
@@ -1069,13 +1084,14 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 		}
 	});
 
-	pi.on("before_provider_request", (event, ctx) => {
+	pi.on("context_with_system", (event, ctx) => {
 		if (isDisabled(ctx.cwd)) return;
 		const config = getRuntimeConfig(ctx);
 		const providers = config.providers.length > 0 ? config.providers : undefined;
-		if (providers && ctx.model && !providers.includes(ctx.model.provider)) return;
+		if (providers && (!ctx.model || !providers.includes(ctx.model.provider))) return;
 		const state = ensureSnapshot(ctx);
-		const transformed = optimizePayload(event.payload, {
+		const payload = { messages: event.messages };
+		const transformed = optimizePayload(payload, {
 			...state.config,
 			profile: state.profile,
 			usagePrior: buildUsagePrior(state.usage, {
@@ -1094,7 +1110,7 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 			addPending(getStatsFilePath(ctx.cwd), { skills: transformed.removedChars, tools: 0, output: 0 });
 		}
 		if (registry) {
-			const evidence = collectSkillUsageEvidence(event.payload, registry.skills.map((skill) => skill.name)).slice(-MAX_SEEN_EVIDENCE);
+			const evidence = collectSkillUsageEvidence(payload, registry.skills.map((skill) => skill.name)).slice(-MAX_SEEN_EVIDENCE);
 			const names: string[] = [];
 			for (const item of evidence) {
 				if (seenEvidence.has(item.key)) continue;
@@ -1109,7 +1125,9 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 		}
 		maybeFlush(ctx);
 		updateStatus(ctx);
-		return transformed.next === event.payload ? undefined : transformed.next;
+		return transformed.next === payload
+			? undefined
+			: { messages: (transformed.next as typeof payload).messages };
 	});
 
 	pi.on("context", (event, ctx) => {
@@ -1177,7 +1195,7 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 
 	pi.on("tool_result", async (event, ctx) => {
 		usedTools.add(event.toolName.toLowerCase());
-		if (PROTECTED_RUNTIME_TOOLS.includes(event.toolName as typeof PROTECTED_RUNTIME_TOOLS[number])) return;
+		if (RESOLVER_RESULT_TOOLS.has(event.toolName)) return;
 		if (isDisabled(ctx.cwd) || event.isError) return;
 		const config = getRuntimeConfig(ctx);
 		const providers = config.providers.length > 0 ? config.providers : undefined;
@@ -1373,7 +1391,7 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 				`  enabled:        ${isDisabled(ctx.cwd) ? "no" : "yes"}`,
 				"  skills mode:    AUTO (stable TSV + skill_search resolver)",
 				`  catalog budget:${lastBudget.usedChars}/${lastBudget.requestedChars} chars, ${lastBudget.nameOnlyCount} name-only`,
-				`  tools:          ${pi.getActiveTools().length}/${pi.getAllTools().length} active; tool_search additive`,
+				`  tools:          ${pi.getActiveTools().length}/${pi.getAllTools().length} active; optimizer_tool_search additive`,
 				`  output:         ${getOutputConfig(state.config).mode}; RTK ${rtkExtensionPresent() ? "detected per result" : "not detected"}`,
 				`  scope:          ${state.config.providers.join(", ") || "all providers"}`,
 				`  init readiness: ${retryAfter !== 0 ? "unavailable (profile could not be read)" : readiness.skillCount === 0 ? "not available (no model-invocable skills)" : initReadinessSummary(readiness)}`,

package/src/optimize.ts

@@ -361,25 +361,24 @@ export function optimizePayload<T>(
   }
 
   let addedPrefetchChars = 0;
-  const selectedSkills =
-    planSkillPrefetch(catalogSkills, query, {
-      profile: config.profile,
-      usagePrior: config.usagePrior,
-      always: uniqueInOrder([
-        ...(config.profile?.critical ?? []),
-        ...(config.alwaysSkills ?? []),
-      ]),
-      never: config.excludeSkills,
-      targetTopK: config.prefetchTarget,
-      minTopK: config.prefetchMin,
-      maxTopK: config.prefetchMax,
-      fullRenderBudgetChars: config.prefetchBudgetChars,
-      fuzzyCandidateLimit: config.fuzzyCandidateLimit,
-    }).selected;
+  let injectedSkills: string[] = [];
+  const prefetchPlan = planSkillPrefetch(catalogSkills, query, {
+    profile: config.profile,
+    usagePrior: config.usagePrior,
+    always: uniqueInOrder([
+      ...(config.profile?.critical ?? []),
+      ...(config.alwaysSkills ?? []),
+    ]),
+    never: config.excludeSkills,
+    targetTopK: config.prefetchTarget,
+    minTopK: config.prefetchMin,
+    maxTopK: config.prefetchMax,
+    fullRenderBudgetChars: config.prefetchBudgetChars,
+    fuzzyCandidateLimit: config.fuzzyCandidateLimit,
+  });
+  const selectedSkills = prefetchPlan.selected;
   if (selectedSkills.length > 0) {
-    const appendix = renderSkillPrefetch({
-      selected: selectedSkills,
-    } as Parameters<typeof renderSkillPrefetch>[0]);
+    const appendix = renderSkillPrefetch(prefetchPlan);
     if (appendix) {
       const withPrefetch = appendToLatestHumanInput(
         next,
@@ -389,6 +388,7 @@ export function optimizePayload<T>(
       if (withPrefetch !== next) {
         addedPrefetchChars = serializedLength(withPrefetch) - serializedLength(next);
         next = withPrefetch;
+        injectedSkills = selectedSkills.map((skill) => skill.name);
       }
     }
   }
@@ -416,7 +416,7 @@ export function optimizePayload<T>(
     removedChars: originalLength - finalLength,
     baseRemovedChars,
     addedPrefetchChars: Math.max(0, addedPrefetchChars),
-    selected: selectedSkills.map((skill) => skill.name),
+    selected: injectedSkills,
     catalogNames: uniqueInOrder(catalogNames),
     fingerprints: uniqueInOrder(fingerprints),
     budget,

package/src/skills.ts

@@ -1058,7 +1058,7 @@ export function renderSkillPrefetch(plan: SkillPrefetchPlan): string {
 	if (plan.selected.length === 0) return "";
 	return [
 		`<skill_prefetch catalog_sha256="${plan.fingerprint}">`,
-		"  <skill_resolver>Use skill_search(name) to load the full skill resource.</skill_resolver>",
+		"  <skill_resolver>Catalog metadata only, not loaded instructions or usage evidence. Load a relevant full skill with skill_search(action=load, name); no acknowledgment is needed.</skill_resolver>",
 		...plan.selected.map(renderFullSkill),
 		"</skill_prefetch>",
 	].join("\n");

package/src/tools.ts

@@ -23,7 +23,7 @@ export const CORE_TOOLS = new Set(
 		"read", "bash", "edit", "write", "multiedit", "str_replace_editor", "notebookedit",
 		"glob", "grep", "ls", "find", "todo", "todowrite", "todoread",
 		"subagent", "fork", "task", "mcp", "skill", "exitplanmode", "enterplanmode",
-		"webfetch", "websearch", "askuserquestion", "powershell",
+		"webfetch", "websearch", "askuserquestion", "powershell", "tool_search",
 	].map((name) => name.toLowerCase()),
 );
 

package/src/usage.ts

@@ -91,16 +91,18 @@ export function collectSkillUsageEvidence(payload: unknown, selectedSkills: read
 		const rawMessage = rawMessages[messageIndex];
 		if (!rawMessage || typeof rawMessage !== "object") continue;
 		const message = rawMessage as Record<string, unknown>;
+		if (message.role !== "assistant") continue;
 		if (!Array.isArray(message.content)) continue;
 		for (let blockIndex = 0; blockIndex < message.content.length; blockIndex++) {
 			const rawBlock = message.content[blockIndex];
 			if (!rawBlock || typeof rawBlock !== "object") continue;
 			const block = rawBlock as Record<string, unknown>;
-			if (block.type !== "tool_use" || typeof block.name !== "string") continue;
+			if ((block.type !== "tool_use" && block.type !== "toolCall") || typeof block.name !== "string") continue;
 			const toolName = block.name.toLowerCase();
 			if (toolName !== "skill" && toolName !== "activate_skill") continue;
-			if (!block.input || typeof block.input !== "object") continue;
-			const input = block.input as Record<string, unknown>;
+			const rawInput = block.type === "toolCall" ? block.arguments : block.input;
+			if (!rawInput || typeof rawInput !== "object") continue;
+			const input = rawInput as Record<string, unknown>;
 			let serialized = "";
 			try { serialized = JSON.stringify(input); } catch { serialized = String(input); }
 			const sourceId = objectId(block);