@fradser/pi-context 0.5.1 → 0.6.0

package/README.md

@@ -1,10 +1,10 @@
 # Context Pi Package
 
-**Version:** 0.5.0
+**Version:** 0.5.1
 
-Retrieve code context for any repo, library, or natural-language query via 5 methods: DeepWiki, Context7, Exa, git clone, and web search+fetch.
+`@fradser/pi-context` exposes one tool: `context_get`.
 
-The package does **not** ship a skill. Native tool guidance is injected into the system prompt, and the `/context` command loads the full workflow into the current turn.
+It starts an independent Pi child process for repository, library, codebase, and technical-topic research. This isolates exploratory tool calls from the main session while returning a concise, evidence-based result.
 
 ## Installation
 
@@ -16,76 +16,39 @@ pi install /path/to/pi-packages/packages/context
 
 ## Usage
 
-Run `/context` followed by a natural-language question, repository slug, library name, or several targets. For example:
+Use natural language to ask Pi for research or external context:
 
 ```text
-/context React 19 server actions error handling
-/context facebook/react
-/context facebook/react zustand --method=deepwiki,context7
+Research how facebook/react implements server actions.
+Compare the current React Router and Next.js data-loading guidance.
+Investigate https://github.com/owner/repo and explain its architecture.
 ```
 
-`--method=` accepts `deepwiki,context7,exa,clone,web,all` (comma-separated). With no target, the command reads dependency manifests in the current directory (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`) and uses detected dependencies as targets.
+Pi recognizes these requests and invokes `context_get` automatically. Users do not need to type `context_get` or use a slash command directly; it is an internal native tool with one `query` parameter containing the context request.
 
-The full workflow (target classification, per-method process, fallbacks, selection guide) lives in `references/workflow.md` and is injected into the turn when `/context` runs. Lightweight tool-selection guidance is always present in the system prompt.
+## Child-process constraints
 
-## Runtime requirements
+The child runs as:
 
-| Method | Availability | Notes |
-|--------|--------------|-------|
-| DeepWiki | Always (native tool `context_deepwiki`) | No API key required |
-| Context7 | Always (native tool `context_context7`) | Optional `CONTEXT7_API_KEY` (Bearer) for per-key quota |
-| Exa | Native tool `context_exa` | Requires `EXA_API_KEY` env var |
-| Git clone | Always | Pi `bash` + `read` |
-| Web fetch | Always | `curl`/HTTP via `bash` |
-
-All three retrieval tools are registered by this package's root extension entry (`index.ts`) and call the public REST APIs directly — no MCP servers needed.
-
-## Methods (summary)
-
-1. **DeepWiki** — AI-generated repo docs via `context_deepwiki` (`mode: structure | contents | ask`).
-2. **Context7** — up-to-date library docs via `context_context7` (`query` + optional `topic`).
-3. **Exa** — web/code search via `context_exa` (`query` + optional `numResults`, requires `EXA_API_KEY`).
-4. **Git clone** — `git clone --depth=1` to `/tmp`, `read` key files, clean up.
-5. **Web search+fetch** — `bash` + `curl` against official docs, GitHub issues, changelogs.
-
-If a native tool is unavailable or errors, fall back to clone/web. The `/context` workflow reference contains the full selection matrix and per-method process.
+```text
+pi --print --mode json --no-session --tools read,bash --exclude-tools edit,write
+```
 
-## Optional manual brief
+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.
 
-`agents/context-researcher.md` is an optional manual prompt brief for an isolated research pass. Pi does not load it as an invocable agent; use the `/context` command for the executable workflow.
+Results are bounded before entering the main session and render as compact, expandable context lifecycle rows.
 
 ## Structure
 
-```
+```text
 context/
-├── index.ts                     # Package-root extension entry point
-├── extensions/
-│   ├── context-tools.ts         # Native pi tools: context_deepwiki / context_context7 / context_exa
-│   └── context-command.ts       # /context command + system-prompt guidance
-├── references/
-│   └── workflow.md              # Full workflow injected by /context
-├── agents/
-│   └── context-researcher.md    # Isolated research brief (manual)
-└── README.md
+├── index.ts
+├── extensions/context-tools.ts
+├── extensions/context-command.ts
+├── references/workflow.md
+└── agents/context-researcher.md
 ```
 
-## Prerequisites
-
-- Pi with extensions + custom tools
-- Network access for external lookups
-- `EXA_API_KEY` for the Exa method (optional for the other four)
-
-## Best Practices
-
-- **Local first**: check local context (package.json, imports) before external lookups.
-- **Combine methods**: DeepWiki / clone for architecture, Context7 for API surface, Exa / web for community patterns.
-- **Verify sources**: cross-reference fetched content against actual code.
-- **Clean up**: remove `/tmp` clones when finished.
-
 ## License
 
 MIT
-
-## Author
-
-Frad LEE (fradser@gmail.com)

package/agents/context-researcher.md

@@ -1,36 +1,3 @@
----
-name: context-researcher
-description: Research a library, repository, or code pattern without polluting the main conversation. Uses the native context_deepwiki/context_context7/context_exa tools when applicable, otherwise git clone + HTTP fetch via Pi bash/read. Accepts natural-language queries, repo slugs, library names, or any combination.
----
+# Context researcher
 
-# Context researcher (optional agent brief)
-
-Pi does not load Claude Code agent files automatically. Treat this file as a **prompt brief** when you want an isolated research pass. Prefer the `/context` command for the executable workflow.
-
-## Runtime requirements
-
-| Method | Requirement |
-|--------|-------------|
-| DeepWiki | Native `context_deepwiki` tool |
-| Context7 | Native `context_context7` tool |
-| Exa | Native `context_exa` tool (+ optional `EXA_API_KEY`) |
-| Git clone | `git` + Pi `bash` / `read` (always) |
-| Web | `curl` or host HTTP via Pi `bash` (always) |
-
-If a native context tool is unavailable or fails, skip that method, use clone + web, and report which methods ran and why the fallback was needed.
-
-## Process
-
-1. **Parse the request** — targets and optional `--method=` list (see `/context`).
-2. **Classify** each target (repo / library / natural-language).
-3. **Select methods** per the `/context` workflow's selection guide.
-4. **Execute with Pi tools** — use the applicable native context tools (`context_deepwiki`, `context_context7`, `context_exa`) plus `bash` and `read`. Summarize intermediates; do not dump raw payloads.
-5. **Return** a concise architecture/API/examples summary only.
-
-## Output format
-
-- Target classification
-- Methods used (and skipped, with reason)
-- Key findings (bullets)
-- Copyable snippets only when necessary
-- Open questions / confidence notes
+`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.

package/extensions/context-command.ts

@@ -1,121 +1,15 @@
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-const PKG_DIR =
-  typeof __dirname === "string"
-    ? __dirname
-    : dirname(fileURLToPath(import.meta.url));
-
-const WORKFLOW_PATH = join(PKG_DIR, "..", "references", "workflow.md");
-
-const METHOD_FLAG = "--method=";
-const ALL_METHODS = ["deepwiki", "context7", "exa", "clone", "web", "all"] as const;
-const MANIFEST_FILES = ["package.json", "pyproject.toml", "go.mod", "Cargo.toml"];
-
 const CONTEXT_GUIDANCE = `
-## Context retrieval
+## Isolated research
 
-- Use \`context_deepwiki\` for public GitHub repo architecture and DeepWiki Q&A.
-- Use \`context_context7\` for up-to-date library/API docs (optionally focused by topic).
-- Use \`context_exa\` for web/code search when EXA_API_KEY is set; otherwise fall back to \`bash\` + \`curl\`.
-- Use \`git clone --depth=1\` to /tmp plus \`read\`/\`bash\` for private repos or deep inspection; always clean up.
-- Prefer small intermediate summaries over dumping raw API payloads into the conversation.
-- The \`/context <targets...> [--method=...]\` command loads the full workflow when the user asks to research or understand code.
+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.
 `;
 
-interface ParsedArgs {
-  targets: string[];
-  methods: string[];
-}
-
-function parseArgs(raw: string): ParsedArgs {
-  const targets: string[] = [];
-  let methods: string[] = ["all"];
-  const tokens = raw.match(/(?:[^\s"]+|"[^"]*")+/g) ?? [];
-  for (const token of tokens) {
-    if (token.startsWith(METHOD_FLAG)) {
-      methods = token
-        .slice(METHOD_FLAG.length)
-        .split(",")
-        .map((m) => m.trim().toLowerCase())
-        .filter((m) => (ALL_METHODS as readonly string[]).includes(m));
-      if (methods.length === 0) methods = ["all"];
-      continue;
-    }
-    targets.push(token.replace(/^"|"$/g, ""));
-  }
-  return { targets, methods };
-}
-
-function detectDependencies(cwd: string): string[] {
-  const deps = new Set<string>();
-  for (const file of MANIFEST_FILES) {
-    try {
-      const text = readFileSync(join(cwd, file), "utf8");
-      if (file === "package.json") {
-        const json = JSON.parse(text) as {
-          dependencies?: Record<string, string>;
-          devDependencies?: Record<string, string>;
-        };
-        for (const name of Object.keys(json.dependencies ?? {})) deps.add(name);
-        for (const name of Object.keys(json.devDependencies ?? {})) deps.add(name);
-      } else if (file === "pyproject.toml") {
-        for (const match of text.matchAll(/^\s*"([A-Za-z0-9_.-]+)"\s*[>=<~!]/gm)) {
-          deps.add(match[1]);
-        }
-      } else if (file === "go.mod") {
-        for (const match of text.matchAll(/^\s*([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\s+v/gm)) {
-          deps.add(match[1]);
-        }
-      } else if (file === "Cargo.toml") {
-        for (const match of text.matchAll(/^([A-Za-z0-9_-]+)\s*=\s*"[^"]+"/gm)) {
-          deps.add(match[1]);
-        }
-      }
-    } catch {
-      // Missing or unreadable manifest — skip.
-    }
-  }
-  return [...deps];
-}
-
-function loadWorkflow(): string {
-  return readFileSync(WORKFLOW_PATH, "utf8");
-}
-
-function buildUserPrompt(args: ParsedArgs, cwd: string): string {
-  const workflow = loadWorkflow();
-  const targets = args.targets.length > 0 ? args.targets : detectDependencies(cwd);
-  const header = [
-    "Run the /context workflow.",
-    "",
-    `Targets: ${targets.length > 0 ? targets.join(", ") : "(none provided and no dependencies detected in cwd)"}`,
-    `Allowed methods: ${args.methods.join(",")}`,
-    "",
-    "---",
-    "",
-  ].join("\n");
-  return header + workflow;
-}
-
-export function registerContextCommand(pi: ExtensionAPI): void {
+export function registerContextGuidance(pi: ExtensionAPI): void {
   pi.on("before_agent_start", async (event) => ({
     systemPrompt: event.systemPrompt + CONTEXT_GUIDANCE,
   }));
-
-  pi.registerCommand("context", {
-    description:
-      "Retrieve code context for repos, libraries, or a natural-language question via DeepWiki, Context7, Exa, clone, or web.",
-    handler: async (rawArgs, ctx) => {
-      const args = parseArgs(rawArgs.trim());
-      const prompt = buildUserPrompt(args, ctx.cwd);
-      pi.sendUserMessage(prompt, { deliverAs: "followUp" });
-    },
-  });
 }
 
-export default function register(pi: ExtensionAPI): void {
-  registerContextCommand(pi);
-}
+export default registerContextGuidance;

package/extensions/context-tools.ts

@@ -1,277 +1,228 @@
-/**
- * Native pi tools for DeepWiki / Context7 / Exa retrieval.
- *
- * Replaces the package's `.mcp.json` (MCP servers). pi has no built-in MCP
- * support (docs/usage.md), so these tools call the public REST APIs directly:
- *   - context_deepwiki  → https://mcp.deepwiki.com/mcp (DeepWiki's public JSON-RPC/SSE API)
- *   - context_context7  → https://context7.com/api/v1/{search,docs}
- *   - context_exa       → https://api.exa.ai/search  (needs EXA_API_KEY)
- *
- * Pure HTTP tools — available in interactive and non-interactive runs alike.
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { truncateHead, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
-import { StringEnum } from "@earendil-works/pi-ai";
+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 {
+  createToolLifecycleResultRenderer,
+  eventToolLifecycle,
+  resolvePiCli,
+  spawnPiChild,
+  terminateChildProcess,
+} from "@fradser/pi-kit";
 import { Type } from "typebox";
 
+const READ_ONLY_TOOLS = ["read", "bash"];
+const EXCLUDED_TOOLS = ["edit", "write"];
 const MAX_CHARS = 60_000;
-const TIMEOUT_MS = 30_000;
-const DEEPWIKI_MCP = "https://mcp.deepwiki.com/mcp";
+const CHILD_TIMEOUT_MS = 180_000;
 
 interface ToolTextResult {
-	content: [{ type: "text"; text: string }];
-	details: Record<string, unknown>;
+  content: [{ type: "text"; text: string }];
+  details: Record<string, unknown>;
 }
 
-function textResult(text: string, details: Record<string, unknown> = {}): ToolTextResult {
-	return { content: [{ type: "text", text }], details };
+interface ToolResultForRendering {
+  content: unknown;
+  details?: unknown;
 }
 
-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]`;
+interface ChildResult {
+  text: string;
+  stderr: string;
+  exitCode: number;
+  cancelled: boolean;
+  timedOut: boolean;
 }
 
-function requestSignal(signal: AbortSignal | undefined): AbortSignal {
-	const timeout = AbortSignal.timeout(TIMEOUT_MS);
-	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+function textResult(text: string, details: Record<string, unknown> = {}): ToolTextResult {
+  return { content: [{ type: "text", text }], details };
 }
 
-async function httpJson(
-	url: string,
-	init: RequestInit = {},
-	signal: AbortSignal | undefined,
-): Promise<{ ok: boolean; status: number; body: string }> {
-	const res = await fetch(url, { ...init, signal: requestSignal(signal) });
-	const body = await res.text();
-	return { ok: res.ok, status: res.status, body };
+function emptyToolCall(): Text {
+  return new Text("", 0, 0);
 }
 
-/**
- * DeepWiki's public API is a JSON-RPC-over-HTTP/SSE endpoint (mcp.deepwiki.com).
- * Call a tool directly — no MCP client or sidecar process needed.
- */
-async function deepwikiCall(
-	tool: string,
-	args: Record<string, unknown>,
-	signal: AbortSignal | undefined,
-): Promise<string> {
-	const res = await fetch(DEEPWIKI_MCP, {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/json",
-			Accept: "application/json, text/event-stream",
-		},
-		body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: tool, arguments: args } }),
-		signal: requestSignal(signal),
-	});
-	const body = await res.text();
-	if (!res.ok) throw new Error(`DeepWiki HTTP ${res.status}: ${body.slice(0, 200)}`);
-
-	// SSE frames: `event: message` + one or more `data:` lines, blank-line terminated.
-	// Join multiline payloads, keep the last frame with data.
-	let payload: string | null = null;
-	let currentData: string[] = [];
-	for (const raw of body.split("\n")) {
-		const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
-		if (line === "") {
-			if (currentData.length > 0) payload = currentData.join("\n");
-			currentData = [];
-			continue;
-		}
-		if (line.startsWith(":")) continue; // SSE comment
-		if (line.startsWith("data:")) {
-			currentData.push(line.slice(5).replace(/^ /, ""));
-		}
-	}
-	if (currentData.length > 0) payload = currentData.join("\n");
-	if (payload === null) throw new Error("DeepWiki: no data frame in response");
-
-	const data = JSON.parse(payload);
-	if (data.error) throw new Error(`DeepWiki: ${data.error.message ?? JSON.stringify(data.error)}`);
-	const content = data.result?.content;
-	if (Array.isArray(content)) {
-		return content.map((c) => (typeof c?.text === "string" ? c.text : JSON.stringify(c))).join("\n");
-	}
-	return JSON.stringify(data.result ?? data);
+function compactSubject(value: unknown): string {
+  const normalized = String(value ?? "research").replace(/\s+/g, " ").trim();
+  return normalized.length <= 120 ? normalized : `${normalized.slice(0, 117)}...`;
 }
 
-const DeepWikiParams = Type.Object({
-	owner: Type.String({ description: "GitHub owner, e.g. 'facebook'" }),
-	repo: Type.String({ description: "GitHub repository name, e.g. 'react'" }),
-	mode: StringEnum(["structure", "contents", "ask"], {
-		description: "structure = table of contents; contents = full wiki text; ask = targeted Q&A",
-	}),
-	question: Type.Optional(
-		Type.String({ description: "Required when mode is 'ask'; the question about the repository" }),
-	),
-});
-const Context7Params = Type.Object({
-	query: Type.String({ description: "Library name to find docs for, e.g. 'fastapi' or 'react'" }),
-	topic: Type.Optional(
-		Type.String({ description: "Optional topic focus, e.g. 'auth' or 'ssr' (best results with a topic)" }),
-	),
-});
-
-const ExaParams = Type.Object({
-	query: Type.String({ description: "Precise natural-language or code query" }),
-	numResults: Type.Optional(
-		Type.Number({ description: "Number of results (default 5)", default: 5 }),
-	),
-});
-
-export function registerContextTools(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "context_deepwiki",
-		label: "DeepWiki repo docs",
-		description:
-			"Fetch AI-generated documentation for a public GitHub repository from DeepWiki. " +
-			"mode=structure returns the table of contents; mode=contents returns the full wiki text; " +
-			"mode=ask answers a specific question with sources. No API key required.",
-		promptSnippet: "Look up AI-generated documentation for a public GitHub repo from DeepWiki",
-		promptGuidelines: [
-			"Use context_deepwiki to fetch structured repo documentation via DeepWiki instead of cloning when you only need a high-level understanding.",
-		],
-		parameters: DeepWikiParams,
-		executionMode: "sequential",
-
-		async execute(_toolCallId, params, signal) {
-			const repo = `${params.owner}/${params.repo}`;
-			if (params.mode === "ask") {
-				if (!params.question) {
-					return textResult("context_deepwiki: mode 'ask' requires a question");
-				}
-				const answer = await deepwikiCall("ask_question", { repoName: repo, question: params.question }, signal);
-				return textResult(truncate(answer));
-			}
-			const tool = params.mode === "structure" ? "read_wiki_structure" : "read_wiki_contents";
-			const out = await deepwikiCall(tool, { repoName: repo }, signal);
-			return textResult(truncate(out));
-		},
-	});
-
-	pi.registerTool({
-		name: "context_context7",
-		label: "Context7 library docs",
-		description:
-			"Fetch up-to-date, version-aware documentation snippets for a library from Context7. " +
-			"Searches the library, then retrieves markdown docs (optionally focused on a topic). " +
-			"Anonymous usage is rate-limited; set CONTEXT7_API_KEY (Authorization: Bearer) for per-key quota.",
-		promptSnippet: "Look up version-aware library documentation from Context7",
-		promptGuidelines: [
-			"Use context_context7 to look up library docs instead of guessing APIs from memory. Anonymous usage is rate-limited; set CONTEXT7_API_KEY for higher quota.",
-		],
-		parameters: Context7Params,
-		executionMode: "sequential",
-
-		async execute(_toolCallId, params, signal) {
-			const headers: Record<string, string> = {};
-			if (process.env.CONTEXT7_API_KEY) {
-				headers.Authorization = `Bearer ${process.env.CONTEXT7_API_KEY}`;
-			}
+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]`;
+}
 
-			const { ok, status, body } = await httpJson(
-				`https://context7.com/api/v1/search?query=${encodeURIComponent(params.query)}`,
-				{ headers },
-				signal,
-			);
-			if (!ok) {
-				if (status === 401 || status === 403) {
-					return textResult(
-						`Context7 search needs an API key (HTTP ${status}). Set CONTEXT7_API_KEY ` +
-							`(Authorization: Bearer) or fall back to web/clone methods.`,
-					);
-				}
-				throw new Error(`Context7 search failed (HTTP ${status}): ${body.slice(0, 400)}`);
-			}
+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);
+}
 
-			let data: { results?: Array<{ id?: unknown }> };
-			try {
-				data = JSON.parse(body);
-			} catch {
-				throw new Error(`Context7 search: unexpected response: ${body.slice(0, 400)}`);
-			}
-			const results = Array.isArray(data.results) ? data.results : [];
-			if (results.length === 0) {
-				return textResult(`Context7: no library found for "${params.query}"`);
-			}
-			const libraryId = typeof results[0]?.id === "string" ? results[0].id : "";
-			if (!libraryId) {
-				return textResult(`Context7: search returned no usable library id for "${params.query}"`);
-			}
+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");
+}
 
-			// v1 doc ids look like "/owner/repo" — strip the leading slash for the path.
-			const path = libraryId.startsWith("/") ? libraryId.slice(1) : libraryId;
-			const topic = params.topic ? `&topic=${encodeURIComponent(params.topic)}` : "";
-			const docUrl = `https://context7.com/api/v1/${path}?type=txt${topic}`;
-			const doc = await httpJson(docUrl, { headers }, signal);
-			if (!doc.ok) {
-				throw new Error(`Context7 docs failed (HTTP ${doc.status}): ${doc.body.slice(0, 400)}`);
-			}
-			return textResult(
-				`Context7 docs for "${params.query}" (${libraryId})${params.topic ? `, topic ${params.topic}` : ""}:\n\n${truncate(doc.body)}`,
-			);
-		},
-	});
+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();
+}
 
-	pi.registerTool({
-		name: "context_exa",
-		label: "Exa web/code search",
-		description:
-			"Search the web for real-world code patterns, comparisons, and up-to-date information via Exa. " +
-			"Requires the EXA_API_KEY environment variable. Returns titles, URLs, and text snippets.",
-		promptSnippet: "Search the web for real-world code patterns, comparisons, and up-to-date information via Exa",
-		promptGuidelines: [
-			"Use context_exa to search the web when you need current information, code patterns, or comparisons. Requires EXA_API_KEY to be set.",
-		],
-		parameters: ExaParams,
-		executionMode: "sequential",
+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");
+}
 
-		async execute(_toolCallId, params, signal) {
-			const apiKey = process.env.EXA_API_KEY;
-			if (!apiKey) {
-				return textResult(
-					"context_exa: EXA_API_KEY is not set. Set EXA_API_KEY to enable Exa search, " +
-						"or fall back to web search via curl / GitHub search.",
-				);
-			}
+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 });
+    });
+  });
+}
 
-			const numResults = Math.max(1, Math.min(10, Math.floor(params.numResults ?? 5)));
-			const { ok, status, body } = await httpJson(
-				"https://api.exa.ai/search",
-				{
-					method: "POST",
-					headers: {
-						"Content-Type": "application/json",
-						"x-api-key": apiKey,
-					},
-					body: JSON.stringify({ query: params.query, numResults, contents: { text: true } }),
-				},
-				signal,
-			);
-			if (!ok) throw new Error(`Exa search failed (HTTP ${status}): ${body.slice(0, 400)}`);
+const ResearchParams = Type.Object({
+  query: Type.String({ description: "Research request: repository, library, codebase question, or current technical topic." }),
+});
 
-			let data: { results?: Array<{ title?: string; url?: string; text?: string }> };
-			try {
-				data = JSON.parse(body);
-			} catch {
-				throw new Error(`Exa search: unexpected response: ${body.slice(0, 400)}`);
-			}
-			const results = Array.isArray(data.results) ? data.results : [];
-			if (results.length === 0) {
-				return textResult(`Exa: no results for "${params.query}"`);
-			}
-			const lines = results.map((r, i) => {
-				const title = r.title || r.url || "(untitled)";
-				const url = r.url || "";
-				const text = typeof r.text === "string" ? r.text.slice(0, 1200) : "";
-				return `${i + 1}. ${title}\n   ${url}\n${text ? `   ${text}` : ""}`;
-			});
-			return textResult(truncate(lines.join("\n\n")));
-		},
-	});
+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",
+    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.",
+    ],
+    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));
+    },
+    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)}`);
+      }
+      if (!child.text) {
+        throw new Error("Isolated Pi research returned no answer");
+      }
+      return textResult(truncate(child.text), { exitCode: child.exitCode });
+    },
+  });
 }
 
 export default registerContextTools;

package/index.ts

@@ -1,8 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import registerContextCommand from "./extensions/context-command.ts";
+import registerContextGuidance from "./extensions/context-command.ts";
 import registerContextTools from "./extensions/context-tools.ts";
 
 export default function contextExtension(pi: ExtensionAPI): void {
   registerContextTools(pi);
-  registerContextCommand(pi);
+  registerContextGuidance(pi);
 }

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@fradser/pi-context",
-  "version": "0.5.1",
-  "description": "Retrieve code context for any repo, library, or natural-language query via DeepWiki, Context7, Exa, git clone, and web search+fetch. Native pi tools (context_deepwiki/context_context7/context_exa) call the public REST APIs directly — no MCP servers.",
+  "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.",
   "keywords": [
     "pi-package",
     "code-context",
-    "deepwiki",
-    "context7",
-    "exa"
+    "isolated-research",
+    "read-only"
   ],
   "author": "Frad LEE <fradser@gmail.com>",
   "license": "MIT",
@@ -31,8 +30,12 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
+  },
+  "dependencies": {
+    "@fradser/pi-kit": "0.4.2"
   }
 }

package/references/workflow.md

@@ -1,108 +1,7 @@
-# context workflow
+# Isolated context research workflow
 
-Retrieve code context for any repo, library, or natural-language code/technology question. Five methods are available; pick them per target. Prefer small intermediate summaries over dumping raw API payloads into the long-lived conversation.
+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.
 
-## Native tools
+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.
 
-| Method | Tool | Availability |
-|--------|------|--------------|
-| DeepWiki | `context_deepwiki` | always, no key |
-| Context7 | `context_context7` | always, optional `CONTEXT7_API_KEY` for higher quota |
-| Exa | `context_exa` | requires `EXA_API_KEY` |
-| Git clone | `bash` + `read` | always |
-| Web search+fetch | `bash` + `curl` | always |
-
-If a native tool is unavailable or errors (e.g. `EXA_API_KEY` unset), skip it and use the documented clone/web fallback. Report which methods ran. There are no Pi built-ins named `WebSearch`/`WebFetch`/`Task` — do not invent them.
-
-## Invocation
-
-`/context [targets...] [--method=a,b,...]`
-
-- `--method=` accepts a comma-separated list from `deepwiki,context7,exa,clone,web,all`. Default: `all`.
-- Quoted strings are one target. Multiple positional tokens are multiple targets.
-- No targets: read dependency manifests in cwd (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`) and use detected dependencies as targets.
-
-Classify each target:
-
-- GitHub slug (`owner/repo`) or git URL → repo — DeepWiki (`context_deepwiki`), else clone.
-- Bare package name or `name@version` → library — Context7 (`context_context7`), else web + clone of docs repo when known.
-- Anything else → natural-language — Exa (`context_exa`) when `EXA_API_KEY` is set, else web search via `curl`.
-
-When `--method=` is passed, use the intersection of allowed and applicable methods. Empty intersection → skip and report.
-
-## Method 1: DeepWiki
-
-Best for: public GitHub repos needing an architecture overview quickly.
-
-1. `context_deepwiki` with `owner`/`repo` and `mode: "structure"` (e.g. `facebook` / `react`).
-2. `mode: "contents"` for the full wiki text, or `mode: "ask"` with `question` for targeted Q&A.
-3. Extract architecture summary and key relationships.
-
-Token isolation: structure → relevant pages → short architecture summary.
-Fallback on error: Method 4 (clone) + Method 5 (web) on GitHub docs/README.
-
-## Method 2: Context7
-
-Best for: up-to-date API docs and version-specific examples for packages/frameworks.
-
-1. `context_context7` with the library name as `query` (e.g. `fastapi`, `react`).
-2. Pass a `topic` (e.g. `auth`, `ssr`) for focused snippets; include the version in the query when given (`react@18`).
-3. Extract the minimum viable API surface + examples.
-
-Token isolation: resolve id → query → minimum viable API surface + examples.
-Fallback on error: official docs URLs via `curl`, or clone of the library repo docs.
-
-## Method 3: Exa
-
-Best for: real-world usage patterns and cross-web code examples.
-
-1. Call with a precise query (language/framework/version/identifiers).
-2. Prefer recent sources; dedupe near-identical snippets and mirrors.
-3. Return a short explanation with sources.
-
-Fallback when key missing / error: GitHub code search URLs / known docs via `curl`, or clone representative examples.
-
-## Method 4: Git clone
-
-Best for: private repos, deep implementation review, when other methods lack depth.
-
-1. `git clone <repo-url> /tmp/<repo-name> --depth=1`
-2. `read` key files: entry points, config, core modules.
-3. Map structure with `bash` find/ls; search with `bash` grep.
-4. Cleanup: `rm -rf /tmp/<repo-name>`.
-
-## Method 5: Web search + fetch
-
-Best for: rationale, changelogs, issues, migration guides.
-
-1. Derive version-anchored queries from the question or clone findings.
-2. Fetch high-signal URLs (official docs, GitHub issues/PRs, changelogs).
-3. Extract only relevant sections; cross-check against cloned code when available.
-4. Discard results older than ~2 years unless foundational.
-
-Query patterns:
-- Changelogs: `"<repo> CHANGELOG v<version>"`
-- Rationale: `"<repo> <concept> why OR rationale site:github.com"`
-- Known issues: `"<repo> <symbol> issue OR bug site:github.com"`
-- Migration: `"<repo> migrate from <old> to <new>"`
-
-## Method selection guide
-
-| Scenario | Primary | Fallback |
-|----------|---------|----------|
-| "How does X library work?" | Context7 | Web / clone |
-| "Architecture of Y repo" | DeepWiki | Git clone |
-| "Examples of Z pattern" | Exa | Context7 / web |
-| "Private/internal repo" | Git clone | — |
-| "What changed in v3?" | Context7 | Web |
-| "Why this design?" | Git clone → web | DeepWiki |
-| "Compare X vs Y" | Exa + Context7 | Web |
-| "Best practice for Z" | Web | Exa |
-
-## Combining methods
-
-1. DeepWiki / clone for architecture.
-2. Context7 for API surface.
-3. Exa / web for community patterns.
-4. Always prefer read-only operations; clean up `/tmp` clones.
-5. Return a synthesized summary only — drop raw bulk payloads.
+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.