feat: 新增系统提示词封面，并修正工具结果投影与常驻工具

系统提示词封面（新增能力）：

- extensions/system-prompt-cover.ts：读取 ~/.pi/agent/SYSTEM_COVER.md，
  在 before_agent_start 返回 { systemPrompt }，用文本拼接替换 Pi 默认
  系统提示词的开头，同时保留 tools / rules / docs / skills /
  project_context / cwd 全部分区及其原始顺序。
- 必须走 forceSystemPrompt 投影路径。customPrompt 选项会连带抑制
  tools / rules / docs 三个分区，而回填只能追加到末尾，无法恢复原顺序；
  且 forceSystemPrompt 优先级更高，二者同时存在时 customPrompt 会被
  静默忽略，因此 handler 不得写 customPrompt。
- 分割边界要求独占一行的裸标签：<project_instructions path="..."> 嵌套在
  <project_context> 内，只有裸标签才是分区边界。
- 注册在 tool-routing 之前，否则提示词已被压平，改 systemPromptOptions
  不再影响本轮请求。
- scripts/deploy-system-prompt-cover.mjs：同目录临时文件 + rename 原子
  覆盖，不保留备份；install.sh 从脚本目录、update.sh 从升级后组合包
  定位 helper，禁止回退到可能陈旧的脚本目录。
- 封面缺失、不可读或空白时静默 no-op，Pi 行为保持不变；封面每轮重新
  读取，修改后在下一轮生效，不影响已结束的历史对话。

pi-compaction 投影修正：

- 仅在「摘要 + Source 行」严格短于原文时才替换工具结果。此前命中即
  无条件替换，小结果反而被包壳放大；未替换的结果完整保留原始 content
  parts（含非文本部分）。
- deterministic.maxStubTokens 由 256 提升到 1024。

pi-tool-search 常驻工具：

- alwaysEnabled 增加 context_tree_query：恢复被投影的工具证据不应依赖
  一次 tool_search 激活，常驻同时保持请求前缀稳定。
- BUNDLE_TOOL_SEARCH_DEFAULTS_VERSION 由 3 提升到 4；
  scripts/migrate-tool-search-settings.mjs 新增 version-3 快照常量，
  使其与 version-2 一样可被完整精确匹配并迁移。
- 权限策略为 context_tree_query 显式 allow：它只读扩展自己的 segment
  索引、不触碰工作区，常驻后不应每轮触发 AutoReview 往返。该种子仅在
  全新安装时部署，已存在的用户 policy.jsonc 不会被覆盖。

文档与测试同步：

- AGENTS.md：新增 system-prompt-cover 开发约定，修正加载顺序、
  bundleDefaultsVersion、可迁移旧快照集合与常驻工具范围的描述。
- pi-tool-search 的 README / CHANGELOG 同步 version 4 与新增常驻工具。
- tests/system-prompt-cover.test.ts：覆盖顺序保持、尾部逐字节不变、
  嵌套 project_instructions 不误判、部署幂等与覆盖、缺源时非零退出。
- 修正 pi-tool-search/test/config.test.ts 与
  tests/tool-search-settings-migration.test.ts 中写死的 version 3 与
  工具列表断言。
- update-git-clean-recovery / tool-search-settings-migration 的 mock
  组合包补拷 scripts/，与真实发布包结构一致，避免 helper 定位失败。

测试：根 61/61、pi-compaction 36/36 + tsc、pi-tool-search 16/16 + tsc、
pi-permission-system 2577/2577；sh -n 与 git diff --check 通过。

pi-compaction/CHANGELOG.md

@@ -6,6 +6,9 @@
 - Restore SubAPI native checkpoints on subsequent requests and preserve the existing Codex transport, portable model-switching summary and failure fallback.
 - Cover provider eligibility, URL/authentication handling and both providers' native checkpoint lifecycles with offline tests.
 - Preserve explicit SubAPI Authorization headers over API keys, support header-only Authorization/proxy authentication, and reject missing credentials without weakening Codex JWT requirements.
+- Pass small tool results through unchanged: projection now replaces a tool result only when the summary plus its `Source:` recovery line is strictly shorter than the original text content.
+- Preserve original content parts, including non-text parts, for every tool result that is not replaced. Indexed evidence remains recoverable through `context_tree_query` either way.
+- Align the implementation with the documented "replace large tool results" behavior; add regression tests for pass-through and for recoverability without replacement.
 
 ## 1.0.0
 

pi-compaction/README.md

@@ -6,6 +6,7 @@ High-performance unified context projection and compaction for Pi.
 
 - incrementally index completed tool calls;
 - replace large tool results with deterministic bounded evidence stubs;
+- pass small tool results through unchanged whenever a stub would not be shorter;
 - refine large stubs with non-blocking semantic summaries;
 - expose one effective context projection to normal provider requests and Codex/SubAPI native compaction;
 - cancel Pi's raw threshold compaction until the effective lower-bound reaches the configured threshold;
@@ -70,6 +71,8 @@ The gateway must have a compatible deployed version, model and available upstrea
 
 The only custom entry type is `pi-compaction`, version 1. Segment summary entries contain hashes, summaries, and source references; they never duplicate complete raw tool output. Native checkpoints use Pi compaction-entry details with the same kind/version.
 
+Projection replaces a tool result only when the resulting summary plus its `Source:` recovery line is strictly shorter than the original text content. Small tool results are therefore passed through byte-for-byte and keep their original content parts, including any non-text parts. Because a stub is only larger than the text it would replace when the original is short, this comparison is the sole gate; no separate size option exists. Every indexed result remains recoverable through `context_tree_query` whether or not the message was replaced.
+
 This implementation intentionally does not read legacy `context-prune-*` or `openai-codex-native-compaction` entries. Start a new session after switching to this extension.
 
 ## Interfaces

pi-compaction/src/config.ts

@@ -12,7 +12,7 @@ export const DEFAULT_CONFIG: PiCompactionConfig = {
   targetRatio: 0.55,
   deterministic: {
     enabled: true,
-    maxStubTokens: 256,
+    maxStubTokens: 1_024,
   },
   semantic: {
     enabled: true,

pi-compaction/src/segment-index.ts

@@ -346,10 +346,13 @@ export class SegmentIndex {
     if (message?.role !== "toolResult" || typeof message.toolCallId !== "string") return message;
     const record = this.records.get(sourceKey(message.toolCallId, message.timestamp));
     if (!record) return message;
+    const original = contentText(message.content);
     const summary = record.semanticSummary ?? record.deterministicSummary;
+    const projected = `${summary}\nSource: ${record.sourceKey}; recover with context_tree_query.`;
+    if (projected.length >= original.length) return message;
     return {
       ...message,
-      content: [{ type: "text", text: `${summary}\nSource: ${record.sourceKey}; recover with context_tree_query.` }],
+      content: [{ type: "text", text: projected }],
     };
   }
 

pi-compaction/test/extension-runtime.test.ts

@@ -54,7 +54,7 @@ test("one runtime projects tool evidence and recovers it through context_tree_qu
     role: "toolResult",
     toolCallId: "call-1",
     toolName: "bash",
-    content: [{ type: "text", text: "failure evidence" }],
+    content: [{ type: "text", text: `failure evidence\n${"x".repeat(12_000)}\nstack tail` }],
     isError: true,
     timestamp: 11,
   };
@@ -78,6 +78,39 @@ test("one runtime projects tool evidence and recovers it through context_tree_qu
   await h.handlers.get("session_shutdown")![0]!({}, ctx);
 });
 
+test("small tool results are passed through without a stub wrapper", async () => {
+  const h = harness();
+  piCompaction(h.pi);
+  const ctx = context();
+  await h.handlers.get("session_start")![0]!({}, ctx);
+
+  const assistant = {
+    role: "assistant",
+    content: [{ type: "toolCall", id: "call-small", name: "bash", arguments: { command: "ls" } }],
+    timestamp: 20,
+  };
+  const result = {
+    role: "toolResult",
+    toolCallId: "call-small",
+    toolName: "bash",
+    content: [{ type: "text", text: "ok\nfile-a.ts\nfile-b.ts" }],
+    timestamp: 21,
+  };
+
+  await h.handlers.get("turn_end")![0]!({ message: assistant, toolResults: [result] }, ctx);
+  const projected = await h.handlers.get("context")![0]!({ messages: [assistant, result] }, ctx);
+
+  assert.strictEqual(projected.messages[1].content[0].text, "ok\nfile-a.ts\nfile-b.ts");
+  assert.doesNotMatch(projected.messages[1].content[0].text, /pi-compaction tool=/);
+
+  // Original evidence stays recoverable even when the message is passed through.
+  const query = h.tools.get("context_tree_query")!;
+  const recovered = await query.execute("q", { toolCallIds: ["call-small"] }, new AbortController().signal, undefined, ctx);
+  assert.match(recovered.content[0].text, /file-a\.ts/);
+
+  await h.handlers.get("session_shutdown")![0]!({}, ctx);
+});
+
 test("model switching after a native checkpoint projects the portable checkpoint", async () => {
   const h = harness();
   piCompaction(h.pi);