@fradser/pi-context 0.6.0 → 0.6.1

package/README.md

@@ -1,6 +1,4 @@
-# Context Pi Package
-
-**Version:** 0.5.1
+# @fradser/pi-context
 
 `@fradser/pi-context` exposes one tool: `context_get`.
 
@@ -10,8 +8,6 @@ It starts an independent Pi child process for repository, library, codebase, and
 
 ```bash
 pi install npm:@fradser/pi-context
-# or from this repository:
-pi install /path/to/pi-packages/packages/context
 ```
 
 ## Usage
@@ -31,12 +27,12 @@ Pi recognizes these requests and invokes `context_get` automatically. Users do n
 The child runs as:
 
 ```text
-pi --print --mode json --no-session --tools read,bash --exclude-tools edit,write
+pi --print --mode json --no-session -ne -ns -np -nc --no-themes --tools read,bash
 ```
 
-The child starts in a unique temporary working directory under `/tmp`. It is instructed to use only read-only investigation. If line-level evidence from a public repository is necessary, it may run `git clone --depth=1` in that directory, inspect the clone, and removes the entire temporary directory before completing. It must not modify the caller's working directory or run package-management, deployment, or interactive commands.
+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.
 
-Results are bounded before entering the main session and render as compact, expandable context lifecycle rows.
+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.
 
 ## Structure
 
@@ -46,7 +42,8 @@ context/
 ├── extensions/context-tools.ts
 ├── extensions/context-command.ts
 ├── references/workflow.md
-└── agents/context-researcher.md
+├── extensions/context-prompt.ts
+└── prompts/context-research.md
 ```
 
 ## License

package/extensions/context-command.ts

@@ -3,7 +3,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 const CONTEXT_GUIDANCE = `
 ## Isolated research
 
-When the user asks to research, investigate, compare, or understand an external repository, library, codebase, or current technical topic, call \`context_get\`. It starts a separate read-only Pi process and keeps research work out of the main session. The child may inspect public repositories with a depth-1 temporary clone under /tmp.
+When the user asks to research, investigate, compare, or understand an external repository, library, codebase, or current technical topic, call \`context_get\`. It starts a separate Pi process with a read/bash allowlist, disabled extension discovery, and prompt-level no-modification guidance; research stays out of the main session. The child may inspect public repositories with a depth-1 temporary clone under /tmp.
 `;
 
 export function registerContextGuidance(pi: ExtensionAPI): void {

package/extensions/context-prompt.ts

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+
+export interface ContextResearchPromptBindings {
+  userResearchRequest: string;
+  workingDirectory: string;
+}
+
+const CONTEXT_REVIEW_COMPLETION = [
+  "Return one self-contained review of the requested context.",
+  "State the conclusion, cite concrete evidence, and distinguish observed facts from uncertainty.",
+  "Finish with a textual final answer rather than ending after a tool call.",
+].join(" ");
+
+const CONTEXT_RESEARCH_TEMPLATE_URL = new URL("../prompts/context-research.md", import.meta.url);
+const PLACEHOLDER_PATTERN = /\{\{([A-Z][A-Z0-9_]*)\}\}/g;
+const PLACEHOLDER_TOKEN_PATTERN = /\{\{[^{}]+\}\}/g;
+const REQUIRED_PLACEHOLDERS = ["USER_RESEARCH_REQUEST"] as const;
+
+function templatePlaceholders(template: string): string[] {
+  return [...template.matchAll(PLACEHOLDER_PATTERN)].map((match) => match[1]);
+}
+
+function placeholderTokens(template: string): string[] {
+  return template.match(PLACEHOLDER_TOKEN_PATTERN) ?? [];
+}
+
+export function validateContextPromptTemplate(template: string): void {
+  const placeholders = templatePlaceholders(template);
+  const allowedTokens = new Set(REQUIRED_PLACEHOLDERS.map((placeholder) => `{{${placeholder}}}`));
+  const unknown = [...new Set(placeholderTokens(template).filter((token) => !allowedTokens.has(token)))];
+  if (unknown.length > 0) {
+    throw new Error(`Context prompt has unknown placeholder(s): ${unknown.join(", ")}`);
+  }
+  const missing = REQUIRED_PLACEHOLDERS.filter((placeholder) => !placeholders.includes(placeholder));
+  if (missing.length > 0) {
+    throw new Error(`Context prompt has missing placeholder(s): ${missing.join(", ")}`);
+  }
+}
+
+export function renderContextPromptTemplate(
+  template: string,
+  bindings: ContextResearchPromptBindings,
+): string {
+  validateContextPromptTemplate(template);
+  const rendered = template.replace(
+    "{{USER_RESEARCH_REQUEST}}",
+    () => bindings.userResearchRequest,
+  );
+  const bindingTokens = new Set(placeholderTokens(bindings.userResearchRequest));
+  const unexpected = placeholderTokens(rendered).filter((token) => !bindingTokens.has(token));
+  if (unexpected.length > 0) {
+    throw new Error(`Context prompt has unresolved placeholder(s): ${[...new Set(unexpected)].join(", ")}`);
+  }
+  return rendered;
+}
+
+const CONTEXT_RESEARCH_TEMPLATE = readFileSync(CONTEXT_RESEARCH_TEMPLATE_URL, "utf8").trim();
+
+export function buildContextResearchPrompt(bindings: ContextResearchPromptBindings): string {
+  const protocol = renderContextPromptTemplate(CONTEXT_RESEARCH_TEMPLATE, bindings);
+  return [
+    "# Context Review",
+    "",
+    "## Current Research Task",
+    `Working directory: ${bindings.workingDirectory}`,
+    "",
+    bindings.userResearchRequest,
+    "",
+    "## Reference Protocol",
+    protocol,
+    "",
+    "## Completion Contract",
+    CONTEXT_REVIEW_COMPLETION,
+  ].join("\n");
+}

package/extensions/context-tools.ts

@@ -1,194 +1,162 @@
-import type { ChildProcess } from "node:child_process";
-import { mkdtempSync, realpathSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { DEFAULT_MAX_LINES, truncateHead, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type Component, Markdown, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import {
-  createToolLifecycleResultRenderer,
+  createLiveActivityWidget,
+  createStaticToolLifecycleResultRenderer,
   eventToolLifecycle,
-  resolvePiCli,
-  spawnPiChild,
-  terminateChildProcess,
+  runPiWorker,
+  type PiLiveWidgetContext,
+  type PiWorkerProgressUpdate,
 } from "@fradser/pi-kit";
 import { Type } from "typebox";
+import { buildContextResearchPrompt } from "./context-prompt.ts";
 
-const READ_ONLY_TOOLS = ["read", "bash"];
-const EXCLUDED_TOOLS = ["edit", "write"];
-const MAX_CHARS = 60_000;
-const CHILD_TIMEOUT_MS = 180_000;
+const RESEARCH_TOOLS = ["read", "bash"];
+const FINAL_ANSWER_RETRY_INSTRUCTION = `
+
+Completion requirement: the previous attempt produced no textual final answer. Complete the original research request now without relying on hidden reasoning, transient tool output, or state from the prior attempt; repeat any inspection needed to support the answer. Your final assistant message must be a self-contained plain-text answer with the conclusion and concrete evidence. Do not finish immediately after a tool call.`;
 
 interface ToolTextResult {
   content: [{ type: "text"; text: string }];
   details: Record<string, unknown>;
 }
 
-interface ToolResultForRendering {
-  content: unknown;
-  details?: unknown;
-}
-
 interface ChildResult {
   text: string;
   stderr: string;
   exitCode: number;
   cancelled: boolean;
-  timedOut: boolean;
 }
 
+interface ResearchAttemptResult extends ChildResult {
+  retried: boolean;
+}
+
+type ResearchRunner = (
+  query: string,
+  signal: AbortSignal | undefined,
+  onUpdate: ((update: PiWorkerProgressUpdate) => void) | undefined,
+  finalAnswerRetry: boolean,
+) => Promise<ChildResult>;
+
 function textResult(text: string, details: Record<string, unknown> = {}): ToolTextResult {
   return { content: [{ type: "text", text }], details };
 }
 
-function emptyToolCall(): Text {
-  return new Text("", 0, 0);
+export function formatResearchSubject(query: unknown): string {
+  if (typeof query !== "string") return "context request";
+  return query.replace(/\s+/g, " ").trim() || "context request";
+}
+
+function renderContextCall(
+  query: unknown,
+  theme: { fg(color: string, text: string): string; bold(text: string): string },
+): Component {
+  return {
+    render: (width) => {
+      if (width <= 0) return [];
+      const prefix = theme.fg("customMessageLabel", theme.bold("[context]"));
+      const title = `research started · ${formatResearchSubject(query)}`;
+      return new Text(`${prefix} ${title}`, 0, 0).render(width)
+        .map((line) => truncateToWidth(line, width, "")).concat("");
+    },
+    invalidate: () => {},
+  };
 }
 
-function compactSubject(value: unknown): string {
-  const normalized = String(value ?? "research").replace(/\s+/g, " ").trim();
-  return normalized.length <= 120 ? normalized : `${normalized.slice(0, 117)}...`;
+function resultText(result: ToolTextResult): string {
+  return result.content.find((part) => part.type === "text")?.text ?? "";
 }
 
-function truncate(text: string): string {
-  if (text.length <= MAX_CHARS) return text;
-  const result = truncateHead(text, { maxLines: DEFAULT_MAX_LINES, maxBytes: MAX_CHARS });
-  return `${result.content}\n\n…[truncated ${text.length - MAX_CHARS} chars]`;
+export function buildResearchPrompt(query: string, finalAnswerRetry = false): string {
+  const prompt = buildContextResearchPrompt({
+    userResearchRequest: query,
+    workingDirectory: process.cwd(),
+  });
+  return finalAnswerRetry ? `${prompt}${FINAL_ANSWER_RETRY_INSTRUCTION}` : prompt;
 }
 
-function renderContextResult(
-  result: ToolResultForRendering,
-  options: { expanded?: boolean },
-  theme: { fg(color: string, text: string): string; bg(color: string, text: string): string; bold(text: string): string },
-  context: { isError?: boolean },
-  subject: string,
-) {
-  return createToolLifecycleResultRenderer<ToolResultForRendering, Text>({
-    createSpec: (_result, _text, details) => eventToolLifecycle("context", subject, {
-      label: "researched",
-      details,
-      detailLimit: 50,
-    }),
-    expandHint: "ctrl+o to expand",
-    fit: truncateToWidth,
-    visibleWidth,
-    renderError: (line, errorTheme) => new Text(errorTheme.fg("error", line), 0, 0),
-  })(result, options, theme, context);
+/** Minimal structural view of the tool-execution context: only what the research widget needs. */
+export type ResearchWidgetContext = PiLiveWidgetContext;
+
+interface ActiveResearch {
+  token: number;
+  ctx: ResearchWidgetContext | undefined;
+  activity?: string;
 }
 
-export function buildResearchPrompt(query: string): string {
-  return [
-    "Research the user's request independently and return a concise, evidence-based answer.",
-    "You are in a child Pi process. Use only read and bash; never edit or write files.",
-    "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.",
-    "Cite concrete source URLs, repository paths, or documentation names when available.",
-    "Keep raw findings compact and synthesize the answer rather than dumping large payloads.",
-    "",
-    "User research request:",
-    query,
-  ].join("\n");
+let researchToken = 0;
+let activeResearch: ActiveResearch | undefined;
+const researchWidget = createLiveActivityWidget({
+  key: "context-research",
+  placement: "aboveEditor",
+  fit: truncateToWidth,
+  formatIdentity: (identity, theme) => theme.fg("success", theme.bold(identity)),
+  formatActivity: (activity, theme) => new Markdown(
+    activity, 0, 0, getMarkdownTheme(), { color: (text) => theme.fg("accent", text) },
+  ).render(Math.max(1, visibleWidth(activity))).map((line) => line.trim()).filter(Boolean).join(" "),
+});
+
+/** Show the running-research status above the editor; returns a token for updates/clear. */
+export function startResearchWidget(ctx: ResearchWidgetContext | undefined): number {
+  const token = ++researchToken;
+  activeResearch = { token, ctx };
+  researchWidget.update(ctx, [{ id: String(token), identity: "researcher" }]);
+  return token;
 }
 
-function parseChildOutput(stdout: string): string {
-  let text = "";
-  for (const line of stdout.split("\n")) {
-    try {
-      const event = JSON.parse(line) as { type?: string; message?: { role?: string; content?: Array<{ type?: string; text?: string }> } };
-      if (event.type !== "message_end" || event.message?.role !== "assistant") continue;
-      const candidate = (event.message.content ?? [])
-        .filter((part) => part.type === "text" && typeof part.text === "string")
-        .map((part) => part.text)
-        .join("");
-      if (candidate.trim()) text = candidate;
-    } catch {
-      // JSON mode may include non-event output; it is not part of the result.
-    }
-  }
-  return text.trim();
+/** Refresh the live activity line; stale tokens are ignored. */
+export function updateResearchWidget(token: number, activity: string | undefined): void {
+  if (activeResearch?.token !== token) return;
+  if (activity) activeResearch.activity = activity;
+  researchWidget.update(activeResearch.ctx, [{
+    id: String(token),
+    identity: "researcher",
+    activity: activeResearch.activity,
+  }]);
 }
 
-function sandboxProfile(researchDirectory: string): string {
-  const temporaryDirectory = researchDirectory.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-  return [
-    "(version 1)",
-    "(deny default)",
-    "(allow process*)",
-    "(allow sysctl-read)",
-    "(allow file-read*)",
-    `(allow file-write* (subpath \"${temporaryDirectory}\"))`,
-    "(allow network*)",
-  ].join("\n");
+/** Remove the status widget; stale tokens are ignored. */
+export function clearResearchWidget(ctx: ResearchWidgetContext | undefined, token: number): void {
+  if (activeResearch?.token !== token) return;
+  activeResearch = undefined;
+  researchWidget.clear(ctx);
 }
 
-export function runResearchChild(query: string, signal?: AbortSignal): Promise<ChildResult> {
-  const cli = resolvePiCli();
-  const researchDirectory = realpathSync(mkdtempSync(join(tmpdir(), "pi-context-")));
-  const piArgs = [
-    ...cli.args,
-    "--print",
-    "--mode",
-    "json",
-    "--no-session",
-    "--tools",
-    READ_ONLY_TOOLS.join(","),
-    "--exclude-tools",
-    EXCLUDED_TOOLS.join(","),
-    buildResearchPrompt(query),
-  ];
-
-  const sandboxed = process.platform === "darwin";
-  const command = sandboxed ? "sandbox-exec" : cli.command;
-  const args = sandboxed ? ["-p", sandboxProfile(researchDirectory), cli.command, ...piArgs] : piArgs;
-
-  return new Promise((resolve, reject) => {
-    let child: ChildProcess;
-    let settled = false;
-    try {
-      child = spawnPiChild(command, args, { cwd: researchDirectory, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
-    } catch (error) {
-      rmSync(researchDirectory, { recursive: true, force: true });
-      reject(error);
-      return;
-    }
-
-    let stdout = "";
-    let stderr = "";
-    let termination: Promise<boolean> | undefined;
-    let timedOut = false;
-    let cancelled = false;
-    const timeout = setTimeout(() => {
-      timedOut = true;
-      termination ??= terminateChildProcess(child);
-    }, CHILD_TIMEOUT_MS);
-    timeout.unref?.();
-    const abort = () => {
-      cancelled = true;
-      termination ??= terminateChildProcess(child);
-    };
-    if (signal?.aborted) abort();
-    else signal?.addEventListener("abort", abort, { once: true });
-
-    child.stdout?.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
-    child.stderr?.on("data", (chunk: Buffer) => { stderr += chunk.toString(); });
-    child.on("error", (error) => {
-      if (settled) return;
-      settled = true;
-      signal?.removeEventListener("abort", abort);
-      clearTimeout(timeout);
-      rmSync(researchDirectory, { recursive: true, force: true });
-      reject(error);
-    });
-    child.on("close", (code) => {
-      if (settled) return;
-      settled = true;
-      signal?.removeEventListener("abort", abort);
-      clearTimeout(timeout);
-      rmSync(researchDirectory, { recursive: true, force: true });
-      resolve({ text: parseChildOutput(stdout), stderr: stderr.trim(), exitCode: code ?? 1, cancelled, timedOut });
-    });
+export function runResearchChild(
+  query: string,
+  signal?: AbortSignal,
+  onUpdate?: (update: PiWorkerProgressUpdate) => void,
+  finalAnswerRetry = false,
+): Promise<ChildResult> {
+  let cancelled = signal?.aborted ?? false;
+  const onAbort = () => { cancelled = true; };
+  if (!signal?.aborted) signal?.addEventListener("abort", onAbort, { once: true });
+  return runPiWorker({
+    prompt: buildResearchPrompt(query, finalAnswerRetry),
+    cwd: process.cwd(),
+    tools: RESEARCH_TOOLS,
+    minimal: true,
+    signal,
+    onUpdate,
+  }).then((result) => {
+    signal?.removeEventListener("abort", onAbort);
+    return { text: result.text.trim(), stderr: result.stderr.trim(), exitCode: result.exitCode, cancelled };
   });
 }
 
+export async function runResearchWithFinalAnswerRetry(
+  query: string,
+  signal?: AbortSignal,
+  onUpdate?: (update: PiWorkerProgressUpdate) => void,
+  runner: ResearchRunner = runResearchChild,
+): Promise<ResearchAttemptResult> {
+  const first = await runner(query, signal, onUpdate, false);
+  if (first.cancelled || first.exitCode !== 0 || first.text) return { ...first, retried: false };
+  const retry = await runner(query, signal, onUpdate, true);
+  return { ...retry, retried: true };
+}
+
 const ResearchParams = Type.Object({
   query: Type.String({ description: "Research request: repository, library, codebase question, or current technical topic." }),
 });
@@ -197,30 +165,65 @@ export function registerContextTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "context_get",
     label: "Isolated Pi research",
-    description: "Research a repository, library, codebase, or technical topic in an independent read-only Pi child process. The child can inspect and temporarily clone public repositories under /tmp.",
-    promptSnippet: "Research independently in a read-only child Pi process",
+    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.",
+    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 read-only Pi process.",
+      "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.",
     ],
     parameters: ResearchParams,
     executionMode: "sequential",
     renderShell: "self",
-    renderCall: emptyToolCall,
-    renderResult(result, options, theme, context) {
-      const params = context.args as { query?: string };
-      return renderContextResult(result, options, theme, context, compactSubject(params.query));
+    renderCall(args, theme, _context) {
+      return renderContextCall(args.query, theme);
     },
-    async execute(_toolCallId, params, signal) {
-      const child = await runResearchChild(params.query, signal);
-      if (child.cancelled) throw new Error("Isolated Pi research was cancelled");
-      if (child.timedOut) throw new Error("Isolated Pi research timed out");
-      if (child.exitCode !== 0) {
-        throw new Error(`Isolated Pi research failed (exit ${child.exitCode}): ${child.stderr.slice(0, 400)}`);
+    renderResult(result, options, theme, context) {
+      // While the async child is still running, live progress already shows
+      // in the `researcher` widget above the editor, so a partial result
+      // renders no transcript row: the `research started` call row stays the
+      // single visible row until the settled `[context] researched` result.
+      if (options.isPartial) {
+        return { render: () => [] as string[], invalidate: () => {} };
       }
-      if (!child.text) {
-        throw new Error("Isolated Pi research returned no answer");
+      const query = (context.args as { query?: string })?.query;
+      const subject = formatResearchSubject(query);
+      const text = resultText(result as ToolTextResult);
+      const details = text.split("\n").map((line) => line.trim()).filter(Boolean);
+      const spec = eventToolLifecycle("context", subject, {
+        label: "researched",
+        details,
+        detailLimit: "all",
+      });
+      return createStaticToolLifecycleResultRenderer({
+        createSpec: () => spec,
+        expandHint: keyHint("app.tools.expand", "to expand"),
+        fit: truncateToWidth,
+        visibleWidth,
+        wrapDetail: (line, width) => wrapTextWithAnsi(line, Math.max(1, width)),
+      })(result as ToolTextResult, options, theme, context);
+    },
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      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...", {
+            operation: "context-review",
+          }));
+        });
+        if (child.cancelled) throw new Error("Isolated Pi research was cancelled");
+        if (child.exitCode !== 0) {
+          const phase = child.retried ? " retry" : "";
+          throw new Error(`Isolated Pi research${phase} failed (exit ${child.exitCode}): ${child.stderr.slice(0, 400)}`);
+        }
+        if (!child.text) throw new Error("Isolated Pi research returned no answer after retry");
+        return textResult(child.text, {
+          exitCode: child.exitCode,
+          operation: "context-review",
+          ...(child.retried ? { retried: true } : {}),
+        });
+      } finally {
+        clearResearchWidget(ctx as ResearchWidgetContext | undefined, widget);
       }
-      return textResult(truncate(child.text), { exitCode: child.exitCode });
     },
   });
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@fradser/pi-context",
-  "version": "0.6.0",
-  "description": "Retrieve context for repositories, libraries, and technical questions with one native tool that launches an isolated read-only Pi research child.",
+  "version": "0.6.1",
+  "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",
     "code-context",
     "isolated-research",
-    "read-only"
+    "prompt-constrained"
   ],
   "author": "Frad LEE <fradser@gmail.com>",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "index.ts",
     "extensions",
     "references",
-    "agents",
+    "prompts",
     "README.md"
   ],
   "pi": {

package/prompts/context-research.md

@@ -0,0 +1,10 @@
+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.
+
+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.
+
+Cite concrete source URLs, repository paths, or documentation names when available. Keep raw findings compact and synthesize the answer rather than dumping large payloads.
+
+User research request:
+{{USER_RESEARCH_REQUEST}}

package/references/workflow.md

@@ -1,7 +1,7 @@
 # Isolated context research workflow
 
-Use `context_get` for a repository, library, codebase, or technical research request. It launches a separate Pi process so exploratory work and its tool calls do not enter the main session.
+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.
 
-The child is read-only: it can use `read` and `bash`, but never `edit` or `write`. 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 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.
 
 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.

package/agents/context-researcher.md

@@ -1,3 +0,0 @@
-# Context researcher
-
-`context_get` is the package's sole Pi tool. It delegates a research request to a fresh read-only Pi process with only `read` and `bash` available. The child may make a depth-1 clone of a public repository in a unique `/tmp` directory when source inspection is needed, then must remove that directory before completing.