@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/src/plugins/anchored-standard.ts

@@ -2,22 +2,38 @@ import type { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { assertKnownConfigKeys } from "../config.js";
+
+const maxAllowedTools = 512;
+const maxToolNameLength = 128;
 
 export interface AnchoredStandardPluginConfig {
   maxToolCalls?: number;
+  allowedTools?: string[];
 }
 
-export const Config: z<AnchoredStandardPluginConfig> = z.object({ maxToolCalls: z.number().default(64) });
+export const Config: z<AnchoredStandardPluginConfig> = z.object({
+  maxToolCalls: z.number().default(64),
+  allowedTools: z.array(z.string().min(1).max(maxToolNameLength).pattern(/\S/u)).max(maxAllowedTools).default([]),
+});
 type AnchorStatus = "idle" | "anchored" | "violated";
-type Violation = { code: "orphan_tool" | "nested_run" | "tool_budget" | "orphan_end"; message: string };
-type AnchorReport = { status: AnchorStatus; events: number; toolCalls: number; maxToolCalls: number; violations: Violation[] };
+type Violation = { code: "orphan_tool" | "nested_run" | "tool_budget" | "orphan_end" | "disallowed_tool"; message: string };
+type AnchorReport = { status: AnchorStatus; events: number; toolCalls: number; maxToolCalls: number; allowedTools: string[]; violations: Violation[] };
 
 export default {
   name: "pi-anchored-standard",
   inject: ["piPluginUi", "piTools"],
   Config,
   apply(context: Context, config: AnchoredStandardPluginConfig) {
-    const maxToolCalls = Math.max(1, Math.min(512, Math.trunc(config.maxToolCalls ?? 64)));
+    assertKnownConfigKeys("anchored-standard", config, ["maxToolCalls", "allowedTools"]);
+    const configuredMaxToolCalls = config.maxToolCalls ?? 64;
+    const maxToolCalls = Number.isFinite(configuredMaxToolCalls) ? Math.max(1, Math.min(512, Math.trunc(configuredMaxToolCalls))) : 64;
+    if ((config.allowedTools?.length ?? 0) > maxAllowedTools) throw new Error(`Anchored-standard allows at most ${maxAllowedTools} tool names`);
+    if ((config.allowedTools ?? []).some((tool) => tool.trim() === "")) throw new Error("Anchored-standard tool names must contain non-whitespace characters");
+    if ((config.allowedTools ?? []).some((tool) => tool.trim().length > maxToolNameLength))
+      throw new Error(`Anchored-standard tool names must contain at most ${maxToolNameLength} characters`);
+    const allowedTools = [...new Set((config.allowedTools ?? []).map((tool) => tool.trim()).filter(Boolean))];
+    const allowedToolSet = new Set(allowedTools);
     let active = false;
     let events = 0;
     let toolCalls = 0;
@@ -25,7 +41,7 @@ export default {
     const record = (violation: Violation): void => {
       if (!violations.some((item) => item.code === violation.code)) violations.push(violation);
     };
-    const inspect = (event: { type: string }): void => {
+    const inspect = (event: { type: string; toolName?: unknown }): void => {
       events += 1;
       if (event.type === "agent_start") {
         if (active) record({ code: "nested_run", message: "检测到未结束的 Agent 运行被再次启动。" });
@@ -38,6 +54,9 @@ export default {
         toolCalls += 1;
         if (!active) record({ code: "orphan_tool", message: "工具调用发生在 Agent 运行锚点之外。" });
         if (toolCalls > maxToolCalls) record({ code: "tool_budget", message: `单次运行工具调用超过 ${maxToolCalls} 次上限。` });
+        const toolName = typeof event.toolName === "string" ? event.toolName.trim() : "";
+        if (allowedToolSet.size > 0 && !allowedToolSet.has(toolName))
+          record({ code: "disallowed_tool", message: `工具 ${toolName || "<unknown>"} 不在当前运行的允许列表中。` });
       }
     };
     const report = (): AnchorReport => ({
@@ -45,6 +64,7 @@ export default {
       events,
       toolCalls,
       maxToolCalls,
+      allowedTools: [...allowedTools],
       violations: [...violations],
     });
     const unsubscribe = context.on("pi/session-event", inspect);
@@ -54,7 +74,8 @@ export default {
         label: "Trajectory anchor check",
         description: "Audit Agent lifecycle and tool-call ordering against the anchored execution standard.",
         promptSnippet: "audit the current agent trajectory for lifecycle violations",
-        parameters: Type.Object({}),
+        parameters: Type.Object({}, { additionalProperties: false }),
+        executionMode: "sequential",
         execute(): Promise<AgentToolResult<AnchorReport>> {
           return Promise.resolve().then(() => {
             const result = report();
@@ -71,14 +92,20 @@ export default {
         },
       }),
     );
-    const disposePanel = context.piPluginUi.register({
-      id: "anchored-standard-panel",
-      pluginId: "@pi-harness/core/plugins/anchored-standard",
-      title: "Anchored Standard",
-      description: "审计 Agent 生命周期和工具调用顺序，发现脱离运行锚点的执行。",
-      icon: "⌁",
-      read: report,
-    });
+    let disposePanel: () => void;
+    try {
+      disposePanel = context.piPluginUi.register({
+        id: "anchored-standard-panel",
+        pluginId: "@pi-harness/core/plugins/anchored-standard",
+        title: "Anchored Standard",
+        description: "审计 Agent 生命周期和工具调用顺序，发现脱离运行锚点的执行。",
+        icon: "⌁",
+        read: report,
+      });
+    } catch (error) {
+      unregisterTool();
+      throw error;
+    }
     context.effect(() => () => {
       unsubscribe();
       unregisterTool();

package/packages/core/src/plugins/annotation.ts

@@ -1,9 +1,11 @@
 import type { Context } from "@deepseek-ai/cordis";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { EmptyConfig } from "../config.js";
 
 const maxQuoteLength = 4_000;
 const maxNoteLength = 1_000;
+const maxQuestionLength = 4_000;
 const maxAnnotations = 50;
 
 export interface Annotation {
@@ -35,23 +37,28 @@ function formatPrompt(annotations: readonly Annotation[], question: string): str
 export default {
   name: "pi-annotation",
   inject: ["piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
     let annotations: Annotation[] = [];
     let lastPrompt: string | undefined;
-    const report = (): AnnotationReport => ({ count: annotations.length, annotations: [...annotations] });
+    const report = (): AnnotationReport => ({ count: annotations.length, annotations: annotations.map((annotation) => ({ ...annotation })) });
     const unregister = context.piTools.register(
       defineTool({
         name: "annotation_manage",
         label: "Manage annotations",
         description: "Collect numbered passage annotations and render them into a model-ready prompt block.",
         promptSnippet: "collect a passage annotation and prepare it for the next question",
-        parameters: Type.Object({
-          action: Type.Union([Type.Literal("add"), Type.Literal("list"), Type.Literal("remove"), Type.Literal("clear"), Type.Literal("prompt")]),
-          quote: Type.Optional(Type.String()),
-          note: Type.Optional(Type.String()),
-          id: Type.Optional(Type.Number()),
-          question: Type.Optional(Type.String()),
-        }),
+        parameters: Type.Object(
+          {
+            action: Type.Union([Type.Literal("add"), Type.Literal("list"), Type.Literal("remove"), Type.Literal("clear"), Type.Literal("prompt")]),
+            quote: Type.Optional(Type.String({ maxLength: maxQuoteLength })),
+            note: Type.Optional(Type.String({ maxLength: maxNoteLength })),
+            id: Type.Optional(Type.Integer({ minimum: 1 })),
+            question: Type.Optional(Type.String({ maxLength: maxQuestionLength })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<AnnotationReport | Annotation | { prompt: string }>> {
           await Promise.resolve();
           if (params.action === "add") {
@@ -66,7 +73,7 @@ export default {
               createdAt: new Date().toISOString(),
             };
             annotations = [...annotations, annotation];
-            return { content: [{ type: "text", text: `Annotation ${annotation.id} added.` }], details: annotation };
+            return { content: [{ type: "text", text: `Annotation ${annotation.id} added.` }], details: { ...annotation } };
           }
           if (params.action === "remove") {
             if (!Number.isInteger(params.id) || params.id === undefined) throw new Error("Annotation id is required");
@@ -82,22 +89,32 @@ export default {
           }
           if (params.action === "prompt") {
             if (annotations.length === 0) throw new Error("Add at least one annotation before rendering a prompt");
-            const prompt = formatPrompt(annotations, params.question ?? "");
+            const question = params.question?.trim();
+            if (!question) throw new Error("Annotation question is required");
+            if (question.length > maxQuestionLength) throw new Error(`Annotation question must contain 1-${maxQuestionLength} characters`);
+            const prompt = formatPrompt(annotations, question);
             lastPrompt = prompt;
             return { content: [{ type: "text", text: prompt }], details: { prompt } };
           }
-          return { content: [{ type: "text", text: `${annotations.length} annotation(s) collected.` }], details: report() };
+          if (params.action === "list") return { content: [{ type: "text", text: `${annotations.length} annotation(s) collected.` }], details: report() };
+          throw new Error("Unknown annotation action");
         },
       }),
     );
-    const disposePanel = context.piPluginUi.register({
-      id: "annotation-panel",
-      pluginId: "@pi-harness/core/plugins/annotation",
-      title: "Annotations",
-      description: "收集回复片段并生成带编号的提问上下文。",
-      icon: "⌁",
-      read: () => ({ ...report(), lastPrompt }),
-    });
+    let disposePanel: () => void;
+    try {
+      disposePanel = context.piPluginUi.register({
+        id: "annotation-panel",
+        pluginId: "@pi-harness/core/plugins/annotation",
+        title: "Annotations",
+        description: "收集回复片段并生成带编号的提问上下文。",
+        icon: "⌁",
+        read: () => ({ ...report(), lastPrompt }),
+      });
+    } catch (error) {
+      unregister();
+      throw error;
+    }
     context.effect(() => () => {
       unregister();
       disposePanel();

package/packages/core/src/plugins/archify.ts

@@ -1,13 +1,16 @@
-import { readFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { readBoundedTextFile } from "../bounded-file.js";
 import { listWorkspaceNodes, type WorkspaceNode } from "./workspace-navigator.js";
+import { EmptyConfig } from "../config.js";
 
 const defaultMaxNodes = 300;
 const maxComponents = 40;
 const maxDependencies = 40;
+const maxManifestBytes = 1024 * 1024;
+const maxDependencyNameLength = 214;
 
 export interface ArchitectureComponent {
   readonly id: string;
@@ -36,35 +39,58 @@ function dependencyId(name: string): string {
 }
 
 function escapeLabel(value: string): string {
-  return value.replace(/["\r\n]/g, (character) => (character === '"' ? """ : " "));
+  return value.replace(/[&<>"\r\n]/g, (character) => {
+    if (character === "&") return "&amp;";
+    if (character === "<") return "&lt;";
+    if (character === ">") return "&gt;";
+    return character === '"' ? "&quot;" : " ";
+  });
 }
 
-function topLevelComponents(nodes: readonly WorkspaceNode[]): ArchitectureComponent[] {
-  return nodes
-    .filter((node) => node.kind === "directory" && node.depth === 1)
-    .slice(0, maxComponents)
-    .map((directory) => {
-      const prefix = `${directory.path}/`;
-      const descendants = nodes.filter((node) => node.path.startsWith(prefix));
-      return {
-        id: componentId(directory.path),
-        label: directory.name,
-        path: directory.path,
-        files: descendants.filter((node) => node.kind === "file").length,
-        directories: descendants.filter((node) => node.kind === "directory").length,
-      };
-    });
+function normalizeMaxNodes(value: number): number {
+  const finite = Number.isFinite(value) ? value : defaultMaxNodes;
+  return Math.max(1, Math.min(500, Math.trunc(finite)));
+}
+
+function topLevelComponents(nodes: readonly WorkspaceNode[]): { components: ArchitectureComponent[]; truncated: boolean } {
+  const directories = nodes.filter((node) => node.kind === "directory" && node.depth === 1);
+  const idCounts = new Map<string, number>();
+  const components = directories.slice(0, maxComponents).map((directory) => {
+    const prefix = `${directory.path}/`;
+    const descendants = nodes.filter((node) => node.path.startsWith(prefix));
+    const baseId = componentId(directory.path);
+    const idCount = (idCounts.get(baseId) ?? 0) + 1;
+    idCounts.set(baseId, idCount);
+    return {
+      id: idCount === 1 ? baseId : `${baseId}_${idCount}`,
+      label: directory.name,
+      path: directory.path,
+      files: descendants.filter((node) => node.kind === "file").length,
+      directories: descendants.filter((node) => node.kind === "directory").length,
+    };
+  });
+  return { components, truncated: directories.length > maxComponents };
 }
 
-async function packageDependencies(root: string): Promise<string[]> {
+async function packageDependencies(root: string): Promise<{ dependencies: string[]; truncated: boolean }> {
   try {
-    const parsed = JSON.parse(await readFile(resolve(root, "package.json"), "utf8")) as Record<string, unknown>;
-    const sections = [parsed.dependencies, parsed.devDependencies, parsed.peerDependencies, parsed.optionalDependencies];
-    return [...new Set(sections.flatMap((section) => (section !== null && typeof section === "object" && !Array.isArray(section) ? Object.keys(section) : [])))]
-      .sort((left, right) => left.localeCompare(right))
-      .slice(0, maxDependencies);
-  } catch {
-    return [];
+    const source = await readBoundedTextFile(resolve(root, "package.json"), maxManifestBytes, "Architecture package manifest");
+    const parsed: unknown = JSON.parse(source);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return { dependencies: [], truncated: true };
+    const record = parsed as Record<string, unknown>;
+    const sections = [record.dependencies, record.devDependencies, record.peerDependencies, record.optionalDependencies];
+    const invalidSection = sections.some((section) => section !== undefined && (section === null || typeof section !== "object" || Array.isArray(section)));
+    const all = [
+      ...new Set(sections.flatMap((section) => (section !== null && typeof section === "object" && !Array.isArray(section) ? Object.keys(section) : []))),
+    ].sort((left, right) => left.localeCompare(right));
+    const valid = all.filter((name) => name.length > 0 && name.length <= maxDependencyNameLength);
+    return {
+      dependencies: valid.slice(0, maxDependencies),
+      truncated: invalidSection || valid.length !== all.length || valid.length > maxDependencies,
+    };
+  } catch (error) {
+    const missing = error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
+    return { dependencies: [], truncated: !missing };
   }
 }
 
@@ -74,8 +100,12 @@ function render(workspace: string, components: readonly ArchitectureComponent[],
     lines.push(`    ${component.id}["${escapeLabel(component.label)}\\n${component.files} files · ${component.directories} dirs"]`);
     lines.push(`    project --> ${component.id}`);
   }
+  const dependencyIdCounts = new Map<string, number>();
   for (const dependency of dependencies) {
-    const id = dependencyId(dependency);
+    const baseId = dependencyId(dependency);
+    const idCount = (dependencyIdCounts.get(baseId) ?? 0) + 1;
+    dependencyIdCounts.set(baseId, idCount);
+    const id = idCount === 1 ? baseId : `${baseId}_${idCount}`;
     lines.push(`    ${id}["${escapeLabel(dependency)}"]`);
     lines.push(`    project --> ${id}`);
   }
@@ -84,15 +114,22 @@ function render(workspace: string, components: readonly ArchitectureComponent[],
 
 export async function buildArchitectureReport(root: string, maxNodes = defaultMaxNodes): Promise<ArchitectureReport> {
   const workspace = resolve(root);
-  const tree = await listWorkspaceNodes(workspace, { maxDepth: 4, maxNodes: Math.max(1, Math.min(500, Math.trunc(maxNodes))) });
-  const components = topLevelComponents(tree.nodes);
-  const dependencies = await packageDependencies(workspace);
-  return { workspace, components, dependencies, truncated: tree.truncated, mermaid: render(workspace, components, dependencies) };
+  const tree = await listWorkspaceNodes(workspace, { maxDepth: 4, maxNodes: normalizeMaxNodes(maxNodes) });
+  const componentScan = topLevelComponents(tree.nodes);
+  const dependencyScan = await packageDependencies(workspace);
+  return {
+    workspace,
+    components: componentScan.components,
+    dependencies: dependencyScan.dependencies,
+    truncated: tree.truncated || componentScan.truncated || dependencyScan.truncated,
+    mermaid: render(workspace, componentScan.components, dependencyScan.dependencies),
+  };
 }
 
 export default {
   name: "pi-archify",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
     let latest: ArchitectureReport | undefined;
     const unregister = context.piTools.register(
@@ -101,10 +138,16 @@ export default {
         label: "Architecture map",
         description: "Build a bounded, read-only architecture map from top-level workspace components and package dependencies.",
         promptSnippet: "map the current workspace architecture",
-        parameters: Type.Object({ maxNodes: Type.Optional(Type.Number({ description: "Maximum scanned workspace nodes, 1-500" })) }),
+        parameters: Type.Object(
+          {
+            maxNodes: Type.Optional(Type.Integer({ description: "Maximum scanned workspace nodes, 1-500", minimum: 1, maximum: 500 })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
         async execute(_toolCallId, params): Promise<AgentToolResult<ArchitectureReport>> {
           latest = await buildArchitectureReport(context.piHarnessLaunch.cwd, params.maxNodes);
-          return { content: [{ type: "text", text: latest.mermaid }], details: latest };
+          return { content: [{ type: "text", text: latest.mermaid }], details: structuredClone(latest) };
         },
       }),
     );
@@ -114,7 +157,11 @@ export default {
       title: "Architecture Map",
       description: "从工作区目录和 package.json 依赖生成可审计的架构图源码。",
       icon: "⌘",
-      read: () => ({ latest: latest ?? null, componentCount: latest?.components.length ?? 0, dependencyCount: latest?.dependencies.length ?? 0 }),
+      read: () => ({
+        latest: latest === undefined ? null : structuredClone(latest),
+        componentCount: latest?.components.length ?? 0,
+        dependencyCount: latest?.dependencies.length ?? 0,
+      }),
     });
     context.effect(() => () => {
       unregister();

package/packages/core/src/plugins/at-file.ts

@@ -1,54 +1,138 @@
-import { readFile, stat } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { isAbsolute } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { BoundedFileSizeError, BoundedFileTypeError, readBoundedFile } from "../bounded-file.js";
+import { assertKnownConfigKeys } from "../config.js";
+import { resolveExistingWorkspacePath } from "../workspace-path.js";
 
 const maxBytes = 256 * 1024;
+const maxPathLength = 512;
 
-function resolveWorkspaceFile(workspace: string, requested: string): string {
-  const root = resolve(workspace);
-  const target = resolve(root, requested);
-  const path = relative(root, target);
-  if (path.startsWith("..") || path.includes("/..")) throw new Error("File path must stay inside the current workspace");
-  return target;
+export type AtFileConfig = Record<never, never>;
+
+export const Config: z<AtFileConfig> = z.object({});
+
+function throwIfCancelled(signal: AbortSignal): void {
+  if (!signal.aborted) return;
+  throw signal.reason instanceof Error ? new Error(signal.reason.message, { cause: signal.reason }) : new Error("File context operation was cancelled");
+}
+
+function fileContextParameters(value: unknown): { path: string } {
+  if (value === null || typeof value !== "object") throw new Error("File context parameters must be a plain object");
+  let descriptors: PropertyDescriptorMap;
+  let prototype: unknown;
+  let array: boolean;
+  try {
+    array = Array.isArray(value);
+    descriptors = Object.getOwnPropertyDescriptors(value);
+    prototype = Object.getPrototypeOf(value) as unknown;
+  } catch (error) {
+    throw new Error("File context parameters must be an accessible plain object", { cause: error });
+  }
+  if (array || (prototype !== Object.prototype && prototype !== null)) throw new Error("File context parameters must be a plain object");
+  if (Reflect.ownKeys(descriptors).some((key) => key !== "path")) throw new Error("File context parameters must contain only path");
+  const descriptor = descriptors.path;
+  if (descriptor === undefined || !("value" in descriptor) || typeof descriptor.value !== "string")
+    throw new Error("File context parameters must contain a path data property");
+  const path = descriptor.value;
+  if (path.trim() === "") throw new Error("File context parameters path must be a non-empty path");
+  if (path !== path.trim()) throw new Error("File context parameters path must not have leading or trailing whitespace");
+  if (path.length > maxPathLength || Buffer.byteLength(path, "utf8") > maxPathLength)
+    throw new Error(`File context parameters path must be at most ${maxPathLength} characters and UTF-8 bytes`);
+  if (isAbsolute(path) || /^[A-Za-z]:[\\/]/u.test(path) || /^[\\/]{2}/u.test(path))
+    throw new Error("File context parameters path must be relative to the current workspace");
+  if (/[\p{Cc}\p{Cf}\p{Cs}]/u.test(path)) throw new Error("File context parameters path cannot contain Unicode control characters");
+  return { path };
+}
+
+function escapeFileAttribute(value: string): string {
+  return value.replace(/[&<>"'\r\n\t]/gu, (character) => {
+    if (character === "&") return "&amp;";
+    if (character === "<") return "&lt;";
+    if (character === ">") return "&gt;";
+    if (character === '"') return "&quot;";
+    if (character === "'") return "&#39;";
+    if (character === "\r") return "&#13;";
+    return character === "\n" ? "&#10;" : "&#9;";
+  });
 }
 
 export default {
   name: "pi-at-file",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-  apply(context: Context) {
+  Config,
+  apply(context: Context, config: AtFileConfig) {
+    assertKnownConfigKeys("at-file", config, []);
     let lastFile: { path: string; bytes: number } | undefined;
+    const lifecycle = new AbortController();
+    context.effect(() => () => lifecycle.abort(new Error("At-file plugin was disposed")));
     const unregisterTool = context.piTools.register(
       defineTool({
         name: "file_context",
         label: "File context",
-        description: "Attach a text file from the current workspace to the model context with a bounded size.",
-        promptSnippet: "attach a workspace file to the current context",
-        parameters: Type.Object({ path: Type.String({ description: "File path relative to the workspace" }) }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<{ path: string; bytes: number }>> {
-          const target = resolveWorkspaceFile(context.piHarnessLaunch.cwd, params.path);
-          const metadata = await stat(target);
-          if (!metadata.isFile()) throw new Error("Context path is not a file");
-          if (metadata.size > maxBytes) throw new Error("Context file exceeds the 256 KiB attachment limit");
-          const path = relative(context.piHarnessLaunch.cwd, target) || ".";
-          const text = await readFile(target, "utf8");
-          lastFile = { path, bytes: metadata.size };
-          return { content: [{ type: "text", text: `<file path="${path}">\n${text}\n</file>` }], details: lastFile };
+        description: "Attach a bounded UTF-8 text file from the current workspace as untrusted model-context data.",
+        promptSnippet: "attach a workspace text file as untrusted context data",
+        parameters: Type.Object(
+          { path: Type.String({ description: "File path relative to the workspace", minLength: 1, maxLength: maxPathLength }) },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
+        async execute(_toolCallId, rawParams, signal): Promise<AgentToolResult<{ path: string; bytes: number }>> {
+          const params = fileContextParameters(rawParams);
+          const operationSignal = signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]);
+          throwIfCancelled(operationSignal);
+          let resolved: Awaited<ReturnType<typeof resolveExistingWorkspacePath>>;
+          try {
+            resolved = await resolveExistingWorkspacePath(context.piHarnessLaunch.cwd, params.path, "File path must stay inside the current workspace");
+          } catch (error) {
+            throw new Error("Could not resolve context file inside the current workspace", { cause: error });
+          }
+          throwIfCancelled(operationSignal);
+          if (
+            resolved.relativePath.trim() === "" ||
+            resolved.relativePath !== resolved.relativePath.trim() ||
+            resolved.relativePath.length > maxPathLength ||
+            Buffer.byteLength(resolved.relativePath, "utf8") > maxPathLength ||
+            /[\p{Cc}\p{Cf}\p{Cs}]/u.test(resolved.relativePath)
+          )
+            throw new Error("Resolved context file path is not safe to display");
+          let source: Buffer;
+          try {
+            source = await readBoundedFile(resolved.target, maxBytes, "Context file");
+          } catch (error) {
+            if (error instanceof BoundedFileTypeError) throw new Error("Context path is not a file", { cause: error });
+            if (error instanceof BoundedFileSizeError) throw new Error("Context file exceeds the 256 KiB attachment limit", { cause: error });
+            throw new Error("Could not read context file", { cause: error });
+          }
+          throwIfCancelled(operationSignal);
+          if (source.includes(0)) throw new Error("Context file must be UTF-8 text without NUL bytes");
+          const path = resolved.relativePath;
+          let text: string;
+          try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(source);
+          } catch (error) {
+            throw new Error("Context file must contain valid UTF-8 text", { cause: error });
+          }
+          const wrappedText = text.replace(/<\/file(?=\s*>)/giu, "<\\/file");
+          lastFile = { path, bytes: source.byteLength };
+          return {
+            content: [{ type: "text", text: `<file path="${escapeFileAttribute(path)}" untrusted="true">\n${wrappedText}\n</file>` }],
+            details: { ...lastFile },
+          };
         },
       }),
     );
+    context.effect(() => unregisterTool);
     const disposePanel = context.piPluginUi.register({
       id: "at-file-panel",
       pluginId: "@pi-harness/core/plugins/at-file",
       title: "@file 上下文",
       description: "将工作区内的文本文件安全附加到当前对话。",
       icon: "⌁",
-      read: () => ({ lastFile: lastFile ?? null, maxBytes }),
-    });
-    context.effect(() => () => {
-      unregisterTool();
-      disposePanel();
+      read: () => ({ lastFile: lastFile === undefined ? null : { ...lastFile }, maxBytes }),
     });
+    context.effect(() => disposePanel);
   },
 };