@fradser/pi-context 0.6.2 → 0.6.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frad LEE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -27,10 +27,10 @@ Pi recognizes these requests and invokes `context_get` automatically. Users do n
 The child runs as:
 
 ```text
-pi --print --mode json --no-session -ne -ns -np -nc --no-themes --tools read,bash
+pi --print --mode json --no-session -ne -ns -np -nc --no-themes --tools read,bash,grep,find
 ```
 
-The child runs in the caller's working directory through pi-kit's minimal `runPiWorker` mode: `-ne -ns -np -nc --no-themes` disables extension, skill, prompt-template, context-file, and theme discovery, while `--tools read,bash` exposes only the two required tools. It has no sandbox, timeout, or display truncation; `bash` remains technically able to write because there is no OS sandbox, so the bundled worker prompt requires no modifications. If line-level evidence from a public repository is necessary, it may use `git clone --depth=1` under `/tmp` with removal after inspection. It must not run package-management, deployment, or interactive commands. The shared worker fails closed if its bounded stdout, stderr, or JSONL line limits are exceeded.
+The child runs in the caller's working directory through pi-kit's minimal `runPiWorker` mode: `-ne -ns -np -nc --no-themes` disables extension, skill, prompt-template, context-file, and theme discovery, while the shared `MINIMAL_PI_WORKER_TOOLS` grant (`read,bash,grep,find`) exposes only those four built-in tools; the `grep` and `find` entries are Pi's own built-in search tools, not an installed search extension, and the set is defined once in pi-kit so this package carries no local tool literal. It has no sandbox, timeout, or display truncation; `bash` remains technically able to write because there is no OS sandbox, so the bundled worker prompt requires no modifications. If line-level evidence from a public repository is necessary, it may use `git clone --depth=1` under `/tmp` with removal after inspection. It must not run package-management, deployment, or interactive commands. The shared worker fails closed if its bounded stdout, stderr, or JSONL line limits are exceeded.
 
 A package-local typed builder reads the bundled Markdown as a reference protocol and builds a task-specific context-review prompt containing the caller working directory, complete research request, reference protocol, and completion contract. The Markdown file itself is never used as an execution identity. Startup renders `[context] research started · <research query>`, using the normalized concrete query that produced the prompt; the row remains width-bounded and does not expose the resource path. While the async child runs, the transcript keeps only that started row with no duplicate progress row; live progress shows in the researcher widget above the editor. The widget shows neutral live research activity. The child always runs with `--no-session`, so separate invocations retain no memory or agent-teams state. A successful empty answer is retried exactly once with a stronger completion requirement that does not rely on hidden reasoning or prior tool output. Results enter the main session untruncated and render as a compact, expandable `[context] researched` lifecycle row.
 

package/extensions/context-command.ts

@@ -7,9 +7,15 @@ For questions about an external repository, library, codebase, or current techni
 `;
 
 export function registerContextGuidance(pi: ExtensionAPI): void {
-  pi.on("before_agent_start", async (event) => ({
-    systemPrompt: event.systemPrompt + CONTEXT_GUIDANCE,
-  }));
+  pi.on("before_agent_start", async (event) => {
+    const options = event.systemPromptOptions;
+    if (!("sections" in options) || !options.sections || typeof options.sections !== "object" || Array.isArray(options.sections)) {
+      throw new Error("This extension requires Pi structured prompt sections.");
+    }
+    const sections = options.sections;
+    Reflect.deleteProperty(sections, "context_research");
+    Object.assign(sections, { context_research: CONTEXT_GUIDANCE });
+  });
 }
 
 export default registerContextGuidance;

package/extensions/context-tools.ts

@@ -5,15 +5,16 @@ import {
   contentDetailLines,
   createLiveActivityWidget,
   eventToolLifecycle,
+  hiddenThinkingEnabled,
+  MINIMAL_PI_WORKER_TOOLS,
   runPiWorker,
+  visibleWorkerActivity,
   type PiLiveWidgetContext,
   type PiWorkerProgressUpdate,
 } from "@fradser/pi-kit";
 import { Type } from "typebox";
 import { buildContextResearchPrompt } from "./context-prompt.ts";
 
-const RESEARCH_TOOLS = ["read", "bash"];
-
 /** Geometry bound once: the research row shares hint and wrapping. */
 const contextRows = bindLifecycleRenderers({
   fit: truncateToWidth,
@@ -92,6 +93,9 @@ interface ActiveResearch {
 
 let researchToken = 0;
 let activeResearch: ActiveResearch | undefined;
+/** Bound by registerContextTools, which alone owns the ExtensionAPI. Read per
+ *  update so a mid-session settings change reaches the next researcher row. */
+let hiddenThinking: () => boolean = () => false;
 // Identity, marker, and activity rendering all come from pi-kit, so this
 // widget uses the same row language as every other package's status row; the
 // activity format is the only per-package choice.
@@ -140,7 +144,10 @@ export function runResearchChild(
   return runPiWorker({
     prompt: buildResearchPrompt(query, finalAnswerRetry),
     cwd: process.cwd(),
-    tools: RESEARCH_TOOLS,
+    // The grant is pi-kit's canonical minimal worker set (read, bash, grep, and
+    // find): inspection access plus Pi's own built-in discovery tools, so one
+    // research question costs fewer model turns and no search extension is added.
+    tools: MINIMAL_PI_WORKER_TOOLS,
     minimal: true,
     signal,
     onUpdate,
@@ -167,13 +174,14 @@ const ResearchParams = Type.Object({
 });
 
 export function registerContextTools(pi: ExtensionAPI): void {
+  hiddenThinking = () => hiddenThinkingEnabled(pi);
   pi.registerTool({
     name: "context_get",
     label: "Isolated Pi research",
-    description: "Research a repository, library, codebase, or technical topic in an independent prompt-constrained Pi child process. The child has read and bash available and can inspect or temporarily clone public repositories under /tmp.",
+    description: "Research a repository, library, codebase, or technical topic in an independent prompt-constrained Pi child process. The child has read, bash, grep, and find available and can inspect or temporarily clone public repositories under /tmp.",
     promptSnippet: "Research independently in a prompt-constrained Pi child process",
     promptGuidelines: [
-      "Use context_get when the user needs external context for a repository, library, codebase, or current technical topic. It retrieves that context in an isolated Pi process with a read/bash allowlist and prompt-level no-modification guidance.",
+      "Use context_get when the user needs external context for a repository, library, codebase, or current technical topic. It retrieves that context in an isolated Pi process with a read/bash/grep/find allowlist and prompt-level no-modification guidance.",
     ],
     parameters: ResearchParams,
     executionMode: "sequential",
@@ -194,7 +202,6 @@ export function registerContextTools(pi: ExtensionAPI): void {
       const spec = eventToolLifecycle("context", subject, {
         label: "researched",
         details: contentDetailLines(result),
-        detailLimit: "all",
       });
       return contextRows.result(() => spec)(result as ToolTextResult, options, theme, context);
     },
@@ -202,8 +209,12 @@ export function registerContextTools(pi: ExtensionAPI): void {
       const widget = startResearchWidget(ctx as ResearchWidgetContext | undefined);
       try {
         const child = await runResearchWithFinalAnswerRetry(params.query, signal, (progress) => {
-          updateResearchWidget(widget, progress.activity);
-          onUpdate?.(textResult(progress.activity ?? "Working...", {
+          // The above-editor row is the reader's surface, so reasoning becomes
+          // Pi's label when thinking blocks are hidden. Tool and answer activity
+          // keep their own text and the order in which they arrived.
+          const activity = visibleWorkerActivity(progress, hiddenThinking());
+          updateResearchWidget(widget, activity);
+          onUpdate?.(textResult(activity ?? "Working...", {
             operation: "context-review",
           }));
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fradser/pi-context",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Retrieve context for repositories, libraries, and technical questions with one native tool that launches an isolated prompt-constrained Pi research child.",
   "keywords": [
     "pi-package",
@@ -36,6 +36,6 @@
     "typebox": "*"
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.5.0"
+    "@fradser/pi-kit": "0.6.0"
   }
-}
+}

package/prompts/context-research.md

@@ -1,6 +1,6 @@
 You are the stateless one-shot research worker bundled with @fradser/pi-context and invoked by its context_get tool.
 
-Research the supplied request independently and return a concise, evidence-based answer. You have read and bash available. Treat the caller's working directory as read-only: never edit or write files. Bash can technically write, so this boundary is enforced by your instructions rather than an OS sandbox.
+Research the supplied request independently and return a concise, evidence-based answer. You have read, bash, grep, and find available. Prefer grep and find for locating files and matching lines, and reserve bash for commands they cannot express, so the evidence is reached in as few steps as possible. Treat the caller's working directory as read-only: never edit or write files. Bash can technically write, so this boundary is enforced by your instructions rather than an OS sandbox.
 
 For public repository line-level evidence, you may run git clone --depth=1 into a unique /tmp directory, inspect it, and remove it before answering. Never modify the caller's working directory. Do not use package managers, deployment commands, or interactive commands.
 

package/references/workflow.md

@@ -2,6 +2,6 @@
 
 Use `context_get` for a repository, library, codebase, or technical research request. It launches a stateless one-shot Pi worker so exploratory work and its tool calls do not enter the main session.
 
-A package-local typed builder reads the bundled Markdown as a reference protocol and constructs a task-specific context-review prompt from the current request and working directory, then adds an explicit completion contract. The transcript identifies that execution with the normalized concrete request (`[context] research started · <research query>`), never with the Markdown path; while the async child runs, no duplicate progress row is rendered and live progress shows only in the researcher widget. The child has a `read,bash` allowlist and no extension discovery. The prompt requires read-only behavior and forbids edits, writes, package-manager commands, deployment, and interactive commands; `bash` can technically write because the child has no OS sandbox. For public repository evidence it may run `git clone --depth=1` into a unique directory under `/tmp`, inspect only the relevant files, cite the evidence in its answer, and remove the clone before it exits.
+A package-local typed builder reads the bundled Markdown as a reference protocol and constructs a task-specific context-review prompt from the current request and working directory, then adds an explicit completion contract. The transcript identifies that execution with the normalized concrete request (`[context] research started · <research query>`), never with the Markdown path; while the async child runs, no duplicate progress row is rendered and live progress shows only in the researcher widget. The child has pi-kit's canonical minimal worker grant (`MINIMAL_PI_WORKER_TOOLS`: `read,bash,grep,find`, all built-in tools; no search extension, no package-local list) and no extension discovery. The prompt requires read-only behavior and forbids edits, writes, package-manager commands, deployment, and interactive commands; `bash` can technically write because the child has no OS sandbox. For public repository evidence it may run `git clone --depth=1` into a unique directory under `/tmp`, inspect only the relevant files, cite the evidence in its answer, and remove the clone before it exits.
 
 The returned answer should synthesize findings, distinguish facts from uncertainty, and cite useful source URLs or repository paths. It must not modify the caller's working directory.