pi-scout 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-09
+
+### Added
+
+- Return declared `{ repo }` / `{ removed, deletedClone }` structured results with public repo fields, `scout` namespace discovery, behavior annotations and sequential tool dispatch.
+
+### Changed
+
+- Store reference context in the named `scout_repos` prompt section using Pi's structured API. Remove empty sections, preserve unrelated prompt changes, and leave deliberate full-prompt overrides intact.
+- Update the shared Pi development and contract-test baseline to 1.1.0; require Node.js >=22.19.0 to match the host runtime. Pi remains a host-supplied peer dependency.
+- Share install telemetry mechanics through `@mocito/install-telemetry` while preserving Pi-specific settings and state paths.
+
+### Fixed
+
+- Keep origin credentials out of tool text/details/results, inferred URL-based names and Git failure diagnostics; terminate Git options before source arguments.
+- Preserve removal-tool deactivation across prompts/reload and respect explicit default-tool exclusions during conditional registration.
+- Let `enableInstallTelemetry: false` override an enabled `PI_TELEMETRY` environment flag.
+
+## [0.1.4] - 2026-07-17
+
+### Fixed
+
+- Store temporary clones in a private per-user directory and reject unsafe clone roots.
+- Serialize repository state mutations and persist state through atomic file replacement.
+
 ## [0.1.3] - 2026-07-01
 
 ### Changed
@@ -18,13 +43,13 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 - Update `author` field to full name for monorepo consistency.
 
-## [0.1.1] - TBD
+## [0.1.1] - 2026-05-22
 
 ### Added
 
 - Add install/update telemetry ping to `mocito.dev`, gated by Pi telemetry/offline settings and disabled in CI.
 
-## [0.1.0] - TBD
+## [0.1.0] - 2026-05-21
 
 ### Added
 

package/CONTRIBUTING.md

@@ -30,6 +30,14 @@ pi -e /path/to/pi-mono/packages/pi-scout --print "list your tools"
 
 ## Pull request checklist
 
+For prompt changes, also run the shared real-session contracts from the monorepo root:
+
+```bash
+node --import tsx --test tests/structured-prompts.test.mjs
+```
+
+These load both Scout and Skillful through Pi's SDK and inspect serialized provider requests and session history. They use disposable profiles, synthetic credentials, temporary reference directories, and mocked provider responses; they do not contact Git remotes, use a live model, or change existing Scout records. Coverage includes stale-reference pruning, section removal, extension load order, explicit prompt overrides, codemode, reload, resume, fork/tree navigation, and providers that collapse system updates.
+
 Before opening a pull request:
 
 - Run `npm run check`.

package/README.md

@@ -1,19 +1,21 @@
 # pi-scout
 
-A source-distributed [Pi](https://pi.dev) package for registering local reference codebases for agent exploration.
+Give [Pi](https://pi.dev) proven codebases to learn from before it changes yours.
+
+`pi-scout` clones and registers reference repositories, then exposes their local paths to the agent for fast, tool-native exploration across sessions.
 
 > [!WARNING]
 > Pi packages can execute arbitrary code through extensions. Review package source before installing any third-party Pi package.
 
 ## Features
 
-- `/scout` slash command with a simple TUI flow for registering, listing, and removing reference repositories.
-- `scout_add` tool for cloning a Git repository into a local temporary cache.
-- `scout_rm` tool for agent-driven removal once repositories exist.
-- Compact per-turn system prompt guidance with registered repo names and local clone paths.
-- Automatic pruning: if the OS cleans a temporary clone, Pi Scout removes that stale entry before adding prompt context.
+- **Reference-driven coding** — let Pi inspect real implementations, conventions, and patterns instead of guessing.
+- **One-step registration** — add Git URLs, local paths, or GitHub `owner/repo` shorthand from `/scout` or natural-language requests.
+- **Fast local exploration** — shallow-clone references into a reusable private cache compatible with Pi's normal file tools.
+- **Cross-session memory** — keep registered references available while their cached clones exist.
+- **Clean context** — tell the agent only which references exist and where to inspect them; stale clones are pruned automatically.
 
-Registered repositories are cloned under `/tmp/pi-scout/<name>-<id>` on Unix-like systems, or the OS temp directory on Windows. Set `PI_SCOUT_TMPDIR` to override the parent temp directory. Pi Scout uses shallow clones with depth `1` by default because it is for code exploration, not history exploration. Pi Scout keeps records in Pi's agent directory and reuses them across sessions while the cloned directories still exist.
+Registered repositories are cloned in a private, per-user directory under the OS temp directory (`<temp>/pi-scout-<uid>` on Unix-like systems). Root and clone permissions are restricted to the current user on Unix. Set `PI_SCOUT_TMPDIR` to override the parent temp directory. Pi Scout uses shallow clones with depth `1` by default because it is for code exploration, not history exploration. Pi Scout keeps records in Pi's agent directory and reuses them across sessions while the cloned directories still exist.
 
 ## Installation
 
@@ -42,6 +44,7 @@ pi -e /path/to/pi-mono/packages/pi-scout --print "list your tools"
 ```
 
 This is an npm-compatible TypeScript Pi package. There is no runtime build step.
+Use Pi 1.1.0 or newer and Node.js >=22.19.0 for the structured tool contracts.
 
 ## Configuration
 
@@ -74,6 +77,16 @@ Register https://github.com/owner/repo.git with Pi Scout, then inspect how it im
 
 After a repository is registered, the agent sees its local path in the system prompt and can inspect it with local file tools.
 
+### Prompt updates
+
+Pi Scout uses the structured prompt API in Pi 1.1.0 or newer. It owns the `scout_repos` section and updates that section without replacing the full system prompt or other extensions' sections. When the last reference is removed or its directory disappears, the section is removed on the next prompt.
+
+The section contains only repository names, local paths, and read-only usage guidance. Origin URLs, credentials, branch names, and other record metadata are not included.
+
+A deliberate full-prompt override from another extension (`systemPrompt` or `forceSystemPrompt`) takes precedence. Scout does not append to or rewrite that override, so its author controls whether reference context is included. Scout tools remain available according to their normal registration rules.
+
+Pi records section updates in the session transcript. Providers that do not support mid-conversation system changes may require a full prompt checkpoint; this does not guarantee cache savings.
+
 ## Tools
 
 | Tool | Purpose |
@@ -81,12 +94,59 @@ After a repository is registered, the agent sees its local path in the system pr
 | `scout_add` | Clone and register a Git repository as a local reference codebase. Takes only `source`: Git URL, local path, or GitHub `owner/repo` shorthand. |
 | `scout_rm` | Remove a repository from Pi Scout records, optionally deleting the temporary clone. Available to the model only while repos are registered. |
 
+### Script results and discovery
+
+Both tools declare output schemas and return objects, not strings, in codemode:
+
+- `scout_add`: `{ repo }`.
+- `scout_rm`: `{ removed: repo | null, deletedClone: boolean }`.
+- `repo`: `{ id, name, path, branch?, createdAt, lastSeenAt }`. Origin/source
+  metadata is deliberately excluded from text, structured results, and renderer
+  details. Pi still records caller arguments; use Git's credential mechanisms,
+  not credentials embedded in `source`.
+
+After an explicit registration request:
+
+```js
+const { repo } = await tools.scout_add({ source: "owner/repo" });
+text({ id: repo.id, path: repo.path });
+```
+
+The namespace is `scout`; tool names are unchanged. Await
+`describeNamespace("scout")`, `describeTool("scout_add")`, or
+`searchTools("reference repository", { namespace: "scout" })` for discovery,
+including with zero inline budget. When adding the first reference, start a
+**new codemode call** before discovering/calling `scout_rm`: Pi snapshots the
+callable tools at script start.
+
+Clone/process/storage failures throw and reject scripted calls. A missing
+removal target is successful `{ removed: null, deletedClone: false }` data.
+`deletedClone: true` means deletion was requested and the removal completed;
+filesystem errors throw, and state removal may already have happened. These tools
+do not return a structured success object with `isError: true`.
+Human-readable direct results and the `/scout` menu remain available without
+codemode.
+
+Both tools run sequentially within Pi's dispatch queue. Await dependent calls;
+this is not a cross-process transaction. Addition is a non-idempotent local
+mutation that may contact a Git host. Removal is destructive, non-idempotent
+(repeated names can match different records), and local-only. These advisory
+hints do not authorize cloning or deletion; existing approval hooks still run.
+
+No optional deferred/codemode exposure setting is added. Direct activation,
+CLI exclusions, and conditional removal availability remain in force. Explicit
+`defaultTools: ["-scout_rm"]` suppresses automatic removal-tool activation.
+Manually disabling it is retained across prompts and reload, while repos remain.
+If the repo set becomes empty and later gains a reference, the normal availability
+transition can activate it again. Use a CLI exclusion for a lasting prohibition.
+
 ## Notes
 
 - On startup, Pi Scout sends a best-effort install/update telemetry ping once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI.
 - Pi Scout uses local file access for exploration. It does not provide web search or remote content-fetching tools.
 - Registering a Git URL still uses `git clone`, so Git may contact the configured remote.
 - Registered repositories are intended as read-only references unless the user explicitly asks otherwise.
+- Repository state changes are serialized and persisted with atomic file replacement.
 - The system prompt includes only registered repo names and local paths, not origin URLs or branch metadata.
 
 ## Development
@@ -94,5 +154,6 @@ After a repository is registered, the agent sees its local path in the system pr
 ```bash
 npm install
 npm run check
+npm test
 npm run pack:dry-run
 ```

package/SECURITY.md

@@ -23,6 +23,21 @@ The maintainer will acknowledge reports as soon as practical and coordinate disc
 
 Do not commit API keys, tokens, credentials, local settings, or machine-specific paths.
 
-On startup, the extension sends a best-effort install/update telemetry ping to `mocito.dev` once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, repository sources, clone paths, config values, or API keys.
+On startup, `@mocito/install-telemetry` sends a best-effort install/update telemetry ping to the configured telemetry endpoint once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, repository sources, clone paths, config values, or API keys.
 
 `pi-scout` stores repository records under Pi's agent directory and clones registered repositories into the OS temporary directory. It does not provide web search or content-fetching tools, but registering a Git URL uses `git clone`, which may contact the configured remote. Registered repository paths are appended to the system prompt so the agent can inspect them with local file tools.
+
+Direct tool text, structured results and renderer details expose only repository
+IDs, names, local paths, optional branches and timestamps—not origin/source
+metadata. URL userinfo/query/fragment are not used to infer public clone names.
+Git receives arguments without a shell and with an option terminator; clone
+failures do not echo stderr or remote response bodies. This does not remove
+caller-supplied origins from Pi's tool-call transcript, Scout's private records,
+the local `/scout` listing, or Git configuration. Prefer Git's credential
+mechanisms to embedding credentials in URLs.
+
+Scout tool calls run sequentially within one Pi dispatcher; atomic state writes
+remain separate from clone creation/deletion and are not a cross-process
+transaction. Namespaces and behavior hints are not authorization. Registration
+can contact remote hosts; removal can delete a clone when explicitly requested.
+Normal approval hooks and tool exclusions remain effective.

package/extensions/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { Type } from "typebox";
 import { reportInstallTelemetry } from "../src/install-telemetry.js";
 import { buildScoutPrompt, formatRepo, loadPrunedState, registerRepo, removeRepo } from "../src/index.js";
+import { ADD_REPO_OUTPUT, REMOVE_REPO_OUTPUT, SCOUT_NAMESPACE, formatPublicRepo, publicRepo } from "../src/tool-contracts.js";
 
 const RegisterRepoParams = Type.Object({
   source: Type.String({ description: "Git URL/path or owner/repo." }),
@@ -16,6 +17,7 @@ export default function piScout(pi: ExtensionAPI) {
   reportInstallTelemetry();
 
   let scoutRmRegistered = false;
+  let hadRepos = false;
 
   function setToolActive(name: string, active: boolean): void {
     const activeTools = pi.getActiveTools();
@@ -24,11 +26,20 @@ export default function piScout(pi: ExtensionAPI) {
     if (!active && hasTool) pi.setActiveTools(activeTools.filter((tool) => tool !== name));
   }
 
-  async function syncScoutRmTool(): Promise<void> {
+  async function syncScoutRmTool(restoring = false): Promise<void> {
     const hasRepos = (await loadPrunedState()).repos.length > 0;
+    const selection = pi.getSettings?.().defaultTools;
+    const disabled = Array.isArray(selection)
+      && selection.filter(entry => entry === "+scout_rm" || entry === "-scout_rm").at(-1) === "-scout_rm";
     if (hasRepos && !scoutRmRegistered) {
       pi.registerTool({
         name: "scout_rm",
+        namespace: SCOUT_NAMESPACE,
+        outputSchema: REMOVE_REPO_OUTPUT,
+        executionMode: "sequential",
+        defaultActive: !restoring && !disabled,
+        // Repeating a name may remove another clone with that name.
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
         label: "Scout Remove",
         description: "Remove a Scout repo record.",
         promptSnippet: "Remove Scout repo records.",
@@ -40,19 +51,26 @@ export default function piScout(pi: ExtensionAPI) {
           const params = rawParams as { idOrName: string; deleteClone?: boolean };
           const removed = await removeRepo(params.idOrName, { deleteClone: params.deleteClone });
           await syncScoutRmTool();
+          const payload = { removed: removed ? publicRepo(removed) : null, deletedClone: Boolean(params.deleteClone && removed) };
           const text = removed
-            ? `Removed Pi Scout repository from records:\n${formatRepo(removed)}\n\nLocal clone ${params.deleteClone ? "deleted" : "was not deleted"}.`
-            : `No Pi Scout repository matched "${params.idOrName}".`;
-          return { content: [{ type: "text", text }], details: { removed, deletedClone: Boolean(params.deleteClone && removed) } };
+            ? `Removed Pi Scout repository from records:\n${formatPublicRepo(removed)}\n\nLocal clone ${params.deleteClone ? "deleted" : "was not deleted"}.`
+            : "No Pi Scout repository matched.";
+          return { content: [{ type: "text", text }], structuredContent: payload, details: payload };
         },
       });
       scoutRmRegistered = true;
     }
-    if (scoutRmRegistered) setToolActive("scout_rm", hasRepos);
+    if (scoutRmRegistered) {
+      if (!hasRepos) setToolActive("scout_rm", false);
+      // Do not reactivate a manually disabled tool on every prompt. On reload,
+      // Pi restores pending active names; this extension only restores availability.
+      else if (!hadRepos && !restoring && !disabled) setToolActive("scout_rm", true);
+    }
+    hadRepos = hasRepos;
   }
 
-  pi.on("session_start", async () => {
-    await syncScoutRmTool();
+  pi.on("session_start", async (event) => {
+    await syncScoutRmTool(event.reason === "reload");
   });
 
   pi.registerCommand("scout", {
@@ -64,6 +82,10 @@ export default function piScout(pi: ExtensionAPI) {
 
   pi.registerTool({
     name: "scout_add",
+    namespace: SCOUT_NAMESPACE,
+    outputSchema: ADD_REPO_OUTPUT,
+    executionMode: "sequential",
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     label: "Scout Add",
     description: "Clone/register a reference repo.",
     promptSnippet: "Add Scout reference repos.",
@@ -76,19 +98,20 @@ export default function piScout(pi: ExtensionAPI) {
       const repo = await registerRepo(pi, { source: params.source, signal });
       await syncScoutRmTool();
       return {
-        content: [{ type: "text", text: `Registered Pi Scout repository:\n${formatRepo(repo)}` }],
-        details: { repo },
+        content: [{ type: "text", text: `Registered Pi Scout repository:\n${formatPublicRepo(repo)}` }],
+        structuredContent: { repo: publicRepo(repo) },
+        details: { repo: publicRepo(repo) },
       };
     },
   });
 
-
   pi.on("before_agent_start", async (event) => {
     await syncScoutRmTool();
     const state = await loadPrunedState();
     const scoutPrompt = buildScoutPrompt(state.repos);
-    if (!scoutPrompt) return;
-    return { systemPrompt: `${event.systemPrompt}\n\n${scoutPrompt}` };
+    // Change only our section; a deliberate forceSystemPrompt remains authoritative.
+    if (scoutPrompt) event.systemPromptOptions.sections.scout_repos = scoutPrompt;
+    else delete event.systemPromptOptions.sections.scout_repos;
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-scout",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Register local reference codebases for Pi agent exploration.",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
   "scripts": {
     "check": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.mjs",
     "pack:dry-run": "npm pack --dry-run"
   },
   "peerDependencies": {
@@ -51,15 +52,19 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.80.0",
-    "@types/node": "^25.9.3",
-    "typebox": "^1.2.10",
-    "typescript": "^6.0.3"
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@types/node": "^26.6.3",
+    "tsx": "^4.23.15",
+    "typebox": "^1.3.34",
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@mocito/install-telemetry": "0.1.1"
   }
 }

package/src/install-telemetry.ts

@@ -1,12 +1,11 @@
 import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { reportInstallTelemetry as report } from "@mocito/install-telemetry";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const PACKAGE_NAME = "pi-scout";
-const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
-const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const INSTALL_TELEMETRY_ENDPOINT = "https://mocito.dev/api/report-install";
 const CI_ENVIRONMENT_VARIABLES = [
   "APPVEYOR",
   "BITBUCKET_BUILD_NUMBER",
@@ -24,10 +23,6 @@ const CI_ENVIRONMENT_VARIABLES = [
   "VERCEL",
 ];
 
-interface InstallTelemetryState {
-  lastReportedVersion?: string;
-}
-
 interface PiSettingsDocument {
   enableInstallTelemetry?: unknown;
 }
@@ -51,18 +46,15 @@ function isPresentEnvFlag(value: string | undefined): boolean {
   return normalized !== "0" && normalized !== "false" && normalized !== "no";
 }
 
-function isCiEnvironment(): boolean {
-  if (isTruthyEnvFlag(process.env.CI)) return true;
-  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
-}
-
-function isInstallTelemetryEnabled(): boolean {
-  if (isCiEnvironment()) return false;
-  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
-  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+export function isInstallTelemetryEnabled(env: NodeJS.ProcessEnv = process.env, settingsPath = join(getAgentDir(), "settings.json")): boolean {
+  if (isTruthyEnvFlag(env.CI)) return false;
+  if (CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(env[name]))) return false;
+  if (isTruthyEnvFlag(env.PI_OFFLINE)) return false;
 
-  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
-  return settings.enableInstallTelemetry !== false;
+  const settings = readJsonFile(settingsPath) as PiSettingsDocument;
+  if (settings.enableInstallTelemetry === false) return false;
+  if (env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(env.PI_TELEMETRY);
+  return true;
 }
 
 function getPackageVersion(): string {
@@ -70,35 +62,16 @@ function getPackageVersion(): string {
   return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
 }
 
-function getInstallTelemetryUserAgent(version: string): string {
-  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
-  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
-  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
-}
-
-async function reportInstallTelemetryAsync(): Promise<void> {
+export function reportInstallTelemetry(): void {
   try {
-    if (!isInstallTelemetryEnabled()) return;
-
-    const version = getPackageVersion();
-    const extensionsDir = join(getAgentDir(), "extensions");
-    const statePath = join(extensionsDir, "pi-scout-install.json");
-    const state = readJsonFile(statePath) as InstallTelemetryState;
-    if (state.lastReportedVersion === version) return;
-
-    await mkdir(extensionsDir, { recursive: true });
-    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
-
-    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
-    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
-      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
-      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
-    });
+    void report({
+      endpoint: INSTALL_TELEMETRY_ENDPOINT,
+      tool: PACKAGE_NAME,
+      version: getPackageVersion(),
+      statePath: join(getAgentDir(), "extensions", "pi-scout-install.json"),
+      enabled: isInstallTelemetryEnabled(),
+    }).catch(() => undefined);
   } catch {
-    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+    // Best-effort telemetry: ignore local policy and filesystem failures.
   }
 }
-
-export function reportInstallTelemetry(): void {
-  void reportInstallTelemetryAsync();
-}

package/src/repo.ts

@@ -1,9 +1,9 @@
-import { mkdir, rm } from "node:fs/promises";
+import { chmod, lstat, mkdir, rm } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { platform, tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadPrunedState, saveState, type ScoutRepo } from "./state.js";
+import { mutateState, type ScoutRepo } from "./state.js";
 
 export interface RegisterRepoOptions {
   source: string;
@@ -21,19 +21,28 @@ export async function registerRepo(pi: ExtensionAPI, options: RegisterRepoOption
   const name = sanitizeName(options.name?.trim() || inferName(source) || `repo-${id}`);
   const root = getScoutCloneRoot();
   const destination = join(root, `${name}-${id}`);
-  await mkdir(root, { recursive: true });
+  await ensurePrivateCloneRoot(root);
+  await mkdir(destination, { mode: 0o700 });
 
   const args = ["clone"];
   if (options.branch?.trim()) args.push("--branch", options.branch.trim());
   const depth = options.depth && Number.isInteger(options.depth) && options.depth > 0 ? options.depth : 1;
   args.push("--depth", String(depth));
-  args.push(source, destination);
-
-  const result = await pi.exec("git", args, { signal: options.signal, timeout: 120_000 });
+  args.push("--", source, destination);
+
+  let result;
+  try {
+    result = await pi.exec("git", args, { signal: options.signal, timeout: 120_000 });
+  } catch {
+    await rm(destination, { recursive: true, force: true });
+    throw new Error(options.signal?.aborted ? "Git clone cancelled." : "Git clone could not run. Check Git and authentication.");
+  }
   if (result.code !== 0) {
-    const stderr = result.stderr?.trim() || result.stdout?.trim() || "git clone failed";
-    throw new Error(stderr);
+    await rm(destination, { recursive: true, force: true });
+    // Git can echo origin URLs, credentials or arbitrary remote output.
+    throw new Error(`Git clone failed (exit code ${result.code}). Check the source and Git authentication.`);
   }
+  if (platform() !== "win32") await chmod(destination, 0o700);
 
   const now = new Date().toISOString();
   const repo: ScoutRepo = {
@@ -46,9 +55,9 @@ export async function registerRepo(pi: ExtensionAPI, options: RegisterRepoOption
     lastSeenAt: now,
   };
 
-  const state = await loadPrunedState();
-  state.repos.push(repo);
-  await saveState(state);
+  await mutateState((state) => {
+    state.repos.push(repo);
+  });
   return repo;
 }
 
@@ -56,12 +65,11 @@ export async function removeRepo(idOrName: string, options: { deleteClone?: bool
   const needle = idOrName.trim();
   if (!needle) return undefined;
 
-  const state = await loadPrunedState();
-  const index = state.repos.findIndex((repo) => repo.id === needle || repo.name === needle);
-  if (index === -1) return undefined;
-
-  const [removed] = state.repos.splice(index, 1);
-  await saveState(state);
+  const removed = await mutateState((state) => {
+    const index = state.repos.findIndex((repo) => repo.id === needle || repo.name === needle);
+    if (index === -1) return undefined;
+    return state.repos.splice(index, 1)[0];
+  });
 
   if (options.deleteClone && removed) {
     await rm(removed.path, { recursive: true, force: true });
@@ -75,16 +83,41 @@ export function formatRepo(repo: ScoutRepo): string {
   return `${repo.name}${branch}\n  id: ${repo.id}\n  source: ${repo.source}\n  path: ${repo.path}`;
 }
 
-function getScoutCloneRoot(): string {
-  if (process.env.PI_SCOUT_TMPDIR) return join(process.env.PI_SCOUT_TMPDIR, "pi-scout");
-  if (platform() !== "win32") return "/tmp/pi-scout";
-  return join(tmpdir(), "pi-scout");
+export function getScoutCloneRoot(): string {
+  const parent = process.env.PI_SCOUT_TMPDIR || tmpdir();
+  if (platform() === "win32") return join(parent, "pi-scout");
+  return join(parent, `pi-scout-${getCurrentUid()}`);
+}
+
+export async function ensurePrivateCloneRoot(root: string): Promise<void> {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  if (platform() === "win32") return;
+
+  const info = await lstat(root);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new Error(`Unsafe Pi Scout clone root: ${root} is not a real directory.`);
+  }
+  if (info.uid !== getCurrentUid()) {
+    throw new Error(`Unsafe Pi Scout clone root: ${root} is not owned by current user.`);
+  }
+  await chmod(root, 0o700);
+}
+
+function getCurrentUid(): number {
+  if (!process.getuid) throw new Error("Pi Scout cannot determine current user ID.");
+  return process.getuid();
 }
 
 function inferName(source: string): string {
   const shorthand = parseGitHubShorthand(source);
   if (shorthand) return shorthand.repo;
 
+  // URL userinfo/query/fragment may contain credentials. Never use them as a
+  // public name or destination basename, including origins without a path.
+  if (source.includes("://")) {
+    try { source = new URL(source).pathname; }
+    catch { return "repo"; }
+  }
   const withoutTrailingSlash = source.replace(/[\\/]+$/, "");
   const last = basename(withoutTrailingSlash).replace(/\.git$/i, "");
   return last || "repo";

package/src/state.ts

@@ -1,6 +1,7 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
 export interface ScoutRepo {
   id: string;
@@ -36,7 +37,25 @@ export async function loadState(): Promise<ScoutState> {
 
 export async function saveState(state: ScoutState): Promise<void> {
   await mkdir(STATE_DIR, { recursive: true });
-  await writeFile(STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  const temporaryPath = join(dirname(STATE_PATH), `.${basename(STATE_PATH)}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(state, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(temporaryPath, STATE_PATH);
+  } catch (error) {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+export async function mutateState<T>(
+  mutation: (state: ScoutState) => Promise<T> | T,
+): Promise<T> {
+  return withFileMutationQueue(STATE_PATH, async () => {
+    const state = (await pruneMissingRepos(await loadState())).state;
+    const result = await mutation(state);
+    await saveState(state);
+    return result;
+  });
 }
 
 export async function pruneMissingRepos(state: ScoutState): Promise<{ state: ScoutState; removed: ScoutRepo[] }> {
@@ -52,13 +71,15 @@ export async function pruneMissingRepos(state: ScoutState): Promise<{ state: Sco
     }
   }
 
-  const next = { repos };
-  if (removed.length > 0) await saveState(next);
-  return { state: next, removed };
+  return { state: { repos }, removed };
 }
 
 export async function loadPrunedState(): Promise<ScoutState> {
-  return (await pruneMissingRepos(await loadState())).state;
+  return withFileMutationQueue(STATE_PATH, async () => {
+    const { state, removed } = await pruneMissingRepos(await loadState());
+    if (removed.length > 0) await saveState(state);
+    return state;
+  });
 }
 
 async function pathExists(path: string): Promise<boolean> {

package/src/tool-contracts.ts

@@ -0,0 +1,30 @@
+import { Type } from "typebox";
+import type { ScoutRepo } from "./state.js";
+
+export const SCOUT_NAMESPACE = {
+  name: "scout",
+  description: "Register and remove local read-only reference clones.",
+  instructions: "scout_add returns { repo }; scout_rm returns { removed: repo|null, deletedClone: boolean }. Public repo fields exclude origin/source metadata and credentials. Clone/process/storage failures reject; a missing removal target is successful data with removed:null. Both operations mutate state and run sequentially. Await dependent operations. After the first registration, start a new codemode call to discover/use scout_rm: the running script has a snapshot of callable tools. scout_add may access remote Git hosts. scout_rm can delete a clone when requested; use it only with user authorization. Repositories remain read-only references unless the user requests edits. Availability follows the active tool set; scout_rm is present only while references exist.",
+};
+
+const repo = Type.Object({
+  id: Type.String(), name: Type.String(), path: Type.String(),
+  branch: Type.Optional(Type.String()), createdAt: Type.String(), lastSeenAt: Type.String(),
+}, { additionalProperties: false });
+export const ADD_REPO_OUTPUT = Type.Object({ repo }, { additionalProperties: false });
+export const REMOVE_REPO_OUTPUT = Type.Object({
+  removed: Type.Union([repo, Type.Null()]), deletedClone: Type.Boolean(),
+}, { additionalProperties: false });
+
+export function publicRepo(value: ScoutRepo) {
+  return {
+    id: value.id, name: value.name, path: value.path,
+    ...(value.branch ? { branch: value.branch } : {}),
+    createdAt: value.createdAt, lastSeenAt: value.lastSeenAt,
+  };
+}
+
+export function formatPublicRepo(value: ScoutRepo): string {
+  const repo = publicRepo(value);
+  return `${repo.name}${repo.branch ? ` (${repo.branch})` : ""}\n  id: ${repo.id}\n  path: ${repo.path}`;
+}