pi-extended-teams 2.1.16

package/extensions/tools/coordination-tools.ts

@@ -0,0 +1,304 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Type } from "@sinclair/typebox";
+import * as paths from "../../src/utils/paths";
+import * as teams from "../../src/utils/teams";
+import * as messaging from "../../src/utils/messaging";
+import * as runtime from "../../src/utils/runtime";
+import * as claims from "../../src/utils/claims";
+import * as reportEvents from "../../src/utils/report-events";
+import { canonicalPersistedModelSlot } from "../../src/utils/settings";
+import { createFileClaimTools } from "./file-claim-tools";
+import { formatInboxMessagesForModel, renderInboxMessages } from "../ui/renderers";
+import { unlinkPidFile } from "../internal/session-files";
+import { summarizeSessionUsage } from "../internal/session-usage";
+import { closePersistedRecipient } from "../team/recipient-closure";
+import {
+  generateExtensionInstanceId,
+  withLifecycleTombstoneLock,
+} from "../../src/utils/lifecycle-tombstone";
+
+export interface CoordinationToolsOptions {
+  agentName: string;
+  isTeammate: boolean;
+  terminal: any;
+  getTeamName(): string | null | undefined;
+  requireWriteAgentTeam(): Promise<string>;
+  requireTeamContext(explicitTeamName?: string): string;
+  releaseAllClaimsForAgent(teamName: string, agentName: string): Promise<string[]>;
+  drainWriteQueue(teamName: string): Promise<void>;
+  resolveSkillFile(skillName: string, cwd: string): string;
+  adoptTeamAsLead(teamName: string, ctx?: any): void;
+  renderLeadInboxStatus(): Promise<void>;
+  resetLeadWakeNotifiedCount(): void;
+  deliverMessageToActiveAgent?(teamName: string, recipient: string, content: string): Promise<boolean>;
+  extensionInstanceId?: string;
+}
+
+export function buildReadHelperPrompt(teamName: string, requester: string, prompt: string): string {
+  return [
+    `You are a read-only helper requested by edit agent '${requester}' in Pi session '${teamName}'.`,
+    "Do not edit files, claim files, install packages, start services, commit, push, deploy, or make mutating changes.",
+    "Investigate only what the requester asked for. Keep the final report concise and evidence-backed.",
+    "Mission:",
+    prompt,
+  ].join("\n\n");
+}
+
+function requireCurrentSession(options: CoordinationToolsOptions): string {
+  const teamName = options.getTeamName();
+  if (!teamName) throw new Error("No active agent session. Spawn an agent first.");
+  return teamName;
+}
+
+export function registerCoordinationTools(pi: any, options: CoordinationToolsOptions): void {
+  const extensionInstanceId = options.extensionInstanceId ?? generateExtensionInstanceId();
+  const pendingWriterFinalization = new Map<string, { teamName: string; agentName: string; runId: string }>();
+
+  pi.on?.("session_shutdown", async () => {
+    const pending = Array.from(pendingWriterFinalization.values());
+    for (const item of pending) {
+      let cleared = false;
+      let failed = false;
+      await withLifecycleTombstoneLock(item.teamName, item.agentName, async lifecycleLock => {
+        const fence = lifecycleLock.read();
+        if (fence.status !== "occupied" || fence.tombstone.runId !== item.runId) return;
+
+        lifecycleLock.updateMatching(item.runId, { phase: "finalizing", error: undefined });
+        try {
+          const config = teams.teamExists(item.teamName) ? await teams.readConfig(item.teamName) : null;
+          const currentMember = config?.members.find(member => member.name === item.agentName);
+          if (currentMember && currentMember.lifecycleRunId !== item.runId) {
+            throw new Error(`Refusing to remove replacement run ${currentMember.lifecycleRunId || "unknown"} of ${item.agentName}.`);
+          }
+
+          const currentRuntime = await runtime.readRuntimeStatus(item.teamName, item.agentName);
+          if (currentRuntime && currentRuntime.lifecycleRunId !== item.runId) {
+            throw new Error(`Refusing to remove replacement runtime run ${currentRuntime.lifecycleRunId || "unknown"} of ${item.agentName}.`);
+          }
+
+          const pidFile = path.join(paths.teamDir(item.teamName), `${item.agentName}.pid`);
+          const pidFileExisted = fs.existsSync(pidFile);
+          const pidFileUnlinked = unlinkPidFile(pidFile);
+          if (pidFileExisted && (!pidFileUnlinked || fs.existsSync(pidFile))) {
+            throw new Error(`Could not remove PID file for ${item.agentName} run ${item.runId}.`);
+          }
+          if (currentRuntime) {
+            const removedRuntime = await runtime.deleteRuntimeStatusUnderLifecycleLock(
+              item.teamName,
+              item.agentName,
+              item.runId,
+            );
+            if (!removedRuntime) throw new Error(`Could not remove runtime for ${item.agentName} run ${item.runId}.`);
+          }
+          if (currentMember) {
+            const removedMember = await teams.removeMemberMatchingRun(item.teamName, item.agentName, item.runId);
+            if (!removedMember) throw new Error(`Could not remove member ${item.agentName} run ${item.runId}.`);
+          }
+
+          const remainingMember = teams.teamExists(item.teamName)
+            ? (await teams.readConfig(item.teamName)).members.find(member => member.name === item.agentName)
+            : undefined;
+          if (remainingMember) {
+            throw new Error(`Member ${item.agentName} still exists after run ${item.runId} cleanup.`);
+          }
+          if (fs.existsSync(paths.runtimeStatusPath(item.teamName, item.agentName))) {
+            throw new Error(`Runtime for ${item.agentName} still exists after run ${item.runId} cleanup.`);
+          }
+
+          if (!lifecycleLock.clearMatching(item.runId)) {
+            throw new Error(`Lifecycle fence changed before final clear for ${item.agentName} run ${item.runId}.`);
+          }
+          cleared = true;
+        } catch (error) {
+          failed = true;
+          lifecycleLock.updateMatching(item.runId, {
+            phase: "cleanup_failed",
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      });
+      if (cleared || failed) {
+        pendingWriterFinalization.delete(`${item.teamName}:${item.agentName}`);
+      }
+      if (cleared) {
+        void options.drainWriteQueue(item.teamName).catch(() => {});
+      }
+    }
+  });
+
+  for (const tool of createFileClaimTools({
+    agentName: options.agentName,
+    getAuthorizedWriteTeam: options.requireWriteAgentTeam,
+    getCurrentTeam: () => requireCurrentSession(options),
+    claims,
+  })) {
+    pi.registerTool(tool);
+  }
+
+  pi.registerTool({
+    name: "report_and_exit",
+    label: "Report and Exit",
+    description: "Send a final report to the lead, release this agent's file claims, and shut down.",
+    parameters: Type.Object({
+      content: Type.String({ description: "Final report to send to the lead." }),
+      summary: Type.Optional(Type.String({ description: "Short report summary." })),
+    }),
+    async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
+      const targetTeamName = requireCurrentSession(options);
+      if (!options.isTeammate) throw new Error("report_and_exit is only available to spawned agents.");
+
+      const config = await teams.readConfig(targetTeamName);
+      const member = config.members.find(m => m.name === options.agentName);
+      if (!member) throw new Error(`Agent ${options.agentName} is not active in ${targetTeamName}.`);
+      const processRunId = process.env.PI_LIFECYCLE_RUN_ID;
+      const runId = await teams.ensureMemberLifecycleRunId(targetTeamName, options.agentName, processRunId);
+      if (processRunId && runId !== processRunId) {
+        throw new Error(`Refusing stale report run ${processRunId} for ${options.agentName}; current roster run is ${runId}.`);
+      }
+      member.lifecycleRunId = runId;
+      let runtimeStatus = await runtime.readRuntimeStatus(targetTeamName, options.agentName).catch(() => null);
+      if (runtimeStatus?.lifecycleRunId && runtimeStatus.lifecycleRunId !== runId) {
+        throw new Error(`Refusing to report from stale run ${runId}; runtime status belongs to ${runtimeStatus.lifecycleRunId}.`);
+      }
+      if (runtimeStatus && !runtimeStatus.lifecycleRunId) {
+        runtimeStatus = await runtime.writeRuntimeStatus(targetTeamName, options.agentName, runId, {});
+      }
+      await closePersistedRecipient(targetTeamName, options.agentName, runId, {
+        removeOnFailure: true,
+        role: (member.role ?? "write") === "read" ? "read" : "write",
+        reason: "quit",
+        extensionInstanceId,
+      });
+      pendingWriterFinalization.set(`${targetTeamName}:${options.agentName}`, {
+        teamName: targetTeamName,
+        agentName: options.agentName,
+        runId,
+      });
+      const sessionUsage = summarizeSessionUsage(ctx);
+      const tokensUsed = typeof sessionUsage.tokensUsed === "number" ? sessionUsage.tokensUsed : runtimeStatus?.tokensUsed;
+      const costUsd = sessionUsage.costUsd;
+      const elapsedMs = runtimeStatus?.startedAt ? Date.now() - runtimeStatus.startedAt : undefined;
+      const modelSlot = canonicalPersistedModelSlot(member?.modelSlot);
+      const reportMetadata = {
+        finalReport: true,
+        startedAt: runtimeStatus?.startedAt,
+        elapsedMs,
+        tokensUsed,
+        costUsd,
+        model: member?.model,
+        thinking: member?.thinking,
+        modelSlot,
+        initialPrompt: member?.prompt,
+      };
+
+      let reportPath = "";
+      let releasedClaims: string[] = [];
+      try {
+        const persistedReport = await reportEvents.appendTeamReportEvent(targetTeamName, {
+          agentName: options.agentName,
+          role: member?.role || "write",
+          status: "completed",
+          report: params.content,
+          summary: params.summary || "Final report",
+          startedAt: runtimeStatus?.startedAt,
+          elapsedMs,
+          tokensUsed,
+          costUsd,
+          source: "write-agent",
+          model: member?.model,
+          thinking: member?.thinking,
+          modelSlot,
+          color: member?.color,
+          metadata: { ...(member?.prompt ? { initialPrompt: member.prompt } : {}), ...(modelSlot ? { modelSlot } : {}) },
+        });
+        reportPath = persistedReport.reportPath || "";
+        if (!reportPath) throw new Error("The persisted report did not provide its standalone file path.");
+        await messaging.sendPlainMessage(targetTeamName, options.agentName, "team-lead", params.content, params.summary || "Final report", undefined, { metadata: reportMetadata });
+        releasedClaims = await options.releaseAllClaimsForAgent(targetTeamName, options.agentName);
+      } catch (error) {
+        pendingWriterFinalization.delete(`${targetTeamName}:${options.agentName}`);
+        await withLifecycleTombstoneLock(targetTeamName, options.agentName, async lifecycleLock => {
+          lifecycleLock.updateMatching(runId, {
+            phase: "cleanup_failed",
+            error: error instanceof Error ? error.message : String(error),
+          });
+        });
+        throw error;
+      }
+
+      setTimeout(() => {
+        try { ctx.shutdown(); } catch { process.exit(0); }
+      }, 250);
+
+      return { content: [{ type: "text", text: `Final report sent. Released ${releasedClaims.length} file claim(s). Exiting.` }], details: { session: targetTeamName, releasedClaims, reportPath } };
+    },
+  });
+
+  pi.registerTool({
+    name: "send_message",
+    label: "Send Message",
+    description: "Send a direct message in the current Pi session. Spawned agents default to messaging the lead.",
+    parameters: Type.Object({
+      recipient: Type.Optional(Type.String({ description: "Recipient agent name. Defaults to team-lead for spawned agents." })),
+      content: Type.String(),
+      summary: Type.Optional(Type.String()),
+    }),
+    async execute(_toolCallId: string, params: any) {
+      const targetTeamName = requireCurrentSession(options);
+      const recipient = params.recipient || (options.isTeammate ? "team-lead" : undefined);
+      if (!recipient) throw new Error("recipient is required when the lead sends a message.");
+      const deliveredDirectly = await options.deliverMessageToActiveAgent?.(targetTeamName, recipient, params.content) === true;
+      if (!deliveredDirectly) {
+        await messaging.sendPlainMessageIfRunning(targetTeamName, options.agentName, recipient, params.content, params.summary || "Message");
+      }
+      return {
+        content: [{ type: "text", text: `Message sent to ${recipient}.` }],
+        details: { session: targetTeamName, recipient, delivery: deliveredDirectly ? "active-session" : "inbox" },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "read_inbox",
+    label: "Read Inbox",
+    description: "Read messages from the current Pi session inbox. Defaults to this agent's inbox.",
+    parameters: Type.Object({
+      agent_name: Type.Optional(Type.String({ description: "Whose inbox to read. Defaults to your own." })),
+      unread_only: Type.Optional(Type.Boolean({ default: true })),
+      mark_as_read: Type.Optional(Type.Boolean({ default: true, description: "Set false to peek without marking messages read." })),
+    }),
+    async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, _ctx: any) {
+      const targetTeamName = requireCurrentSession(options);
+      const targetAgent = params.agent_name || options.agentName;
+      const markAsRead = params.mark_as_read !== false;
+      const unreadOnly = params.unread_only !== false;
+      const msgs = await messaging.readInbox(targetTeamName, targetAgent, unreadOnly, markAsRead);
+
+      if (markAsRead && options.isTeammate && targetAgent === options.agentName) {
+        const config = await teams.readConfig(targetTeamName).catch(() => null);
+        const lifecycleRunId = config?.members.find(member => member.name === options.agentName)?.lifecycleRunId;
+        if (lifecycleRunId) {
+          await runtime.writeRuntimeStatus(targetTeamName, options.agentName, lifecycleRunId, {
+            lastHeartbeatAt: Date.now(),
+            lastInboxReadAt: Date.now(),
+            ready: true,
+            currentAction: "thinking",
+            activeToolName: undefined,
+            lastError: undefined,
+          }).catch(() => {});
+        }
+      }
+
+      if (markAsRead && !options.isTeammate && targetAgent === options.agentName) {
+        options.resetLeadWakeNotifiedCount();
+        await options.renderLeadInboxStatus();
+      }
+
+      return { content: [{ type: "text", text: formatInboxMessagesForModel(msgs) }], details: { session: targetTeamName, messages: msgs, targetAgent, markAsRead } };
+    },
+    renderResult(result: any, { expanded }: any, theme: any) {
+      return renderInboxMessages(result, expanded, theme);
+    },
+  });
+}

package/extensions/tools/delegation-guard.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { requestLeadForTeammateSpawn, resolveLeadRequestTeamName } from "./delegation-guard.js";
+import * as paths from "../../src/utils/paths.js";
+import { readInbox } from "../../src/utils/messaging.js";
+
+let root: string;
+
+function installPathSpies() {
+  vi.spyOn(paths, "teamDir").mockImplementation((teamName: unknown) => path.join(root, "teams", paths.sanitizeName(String(teamName))));
+  vi.spyOn(paths, "inboxPath").mockImplementation((teamName: unknown, agentName: unknown) => {
+    return path.join(root, "teams", paths.sanitizeName(String(teamName)), "inboxes", `${paths.sanitizeName(String(agentName))}.json`);
+  });
+}
+
+describe("teammate delegation guard", () => {
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-extended-teams-delegation-"));
+    installPathSpies();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (root && fs.existsSync(root)) fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("resolves the active team before a requested team name", () => {
+    const teamName = resolveLeadRequestTeamName({
+      isTeammate: true,
+      agentName: "reader",
+      getTeamName: () => "active-team",
+    }, "requested-team");
+
+    expect(teamName).toBe("active-team");
+  });
+
+  it("falls back to the requested team name when no active team is available", () => {
+    const teamName = resolveLeadRequestTeamName({
+      isTeammate: true,
+      agentName: "reader",
+      getTeamName: () => undefined,
+    }, "requested-team");
+
+    expect(teamName).toBe("requested-team");
+  });
+
+  it("requires either an active team or a requested team name", () => {
+    expect(() => resolveLeadRequestTeamName({
+      isTeammate: true,
+      agentName: "reader",
+      getTeamName: () => undefined,
+    })).toThrow("Cannot resolve team context without a current team or team_name.");
+  });
+
+  it("sends lead-owned agent requests to team-lead instead of spawning directly", async () => {
+    const result = await requestLeadForTeammateSpawn({
+      isTeammate: true,
+      agentName: "reader",
+      getTeamName: () => "active-team",
+    }, {
+      action: "spawn_teammate",
+      params: {
+        team_name: "requested-team",
+        name: "helper",
+        prompt: "Investigate the failure",
+        role: "read",
+      },
+      reason: "Need independent coverage",
+    });
+
+    expect(result.content[0].text).toContain("Sent a request to team-lead for active-team");
+    expect(result.details).toMatchObject({
+      requested: true,
+      requestedAction: "spawn_teammate",
+      teamName: "active-team",
+      recipient: "team-lead",
+      from: "reader",
+    });
+
+    const inbox = await readInbox("active-team", "team-lead", false, false);
+    expect(inbox).toHaveLength(1);
+    expect(inbox[0]).toMatchObject({
+      from: "reader",
+      summary: "Agent spawn request from reader for helper",
+      color: "yellow",
+      read: false,
+    });
+    expect(inbox[0].text).toContain("Teammates are not allowed to spawn or promote other agents directly.");
+    expect(inbox[0].text).toContain("Requested action: spawn_teammate");
+    expect(inbox[0].text).toContain("Reason: Need independent coverage");
+    expect(inbox[0].text).toContain('"prompt": "Investigate the failure"');
+  });
+});

package/extensions/tools/delegation-guard.ts

@@ -0,0 +1,65 @@
+import * as paths from "../../src/utils/paths";
+import * as messaging from "../../src/utils/messaging";
+
+export interface TeammateDelegationOptions {
+  isTeammate: boolean;
+  agentName: string;
+  getTeamName(): string | null | undefined;
+}
+
+export interface LeadSpawnRequest {
+  action: string;
+  params: Record<string, unknown>;
+  reason?: string;
+}
+
+function compactJson(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+export function resolveLeadRequestTeamName(options: TeammateDelegationOptions, requestedTeamName?: string): string {
+  const currentTeamName = options.getTeamName();
+  const targetTeamName = currentTeamName || requestedTeamName;
+  if (targetTeamName == null || String(targetTeamName).trim().length === 0) {
+    throw new Error("Cannot resolve team context without a current team or team_name.");
+  }
+  return paths.sanitizeName(String(targetTeamName));
+}
+
+export async function requestLeadForTeammateSpawn(
+  options: TeammateDelegationOptions,
+  request: LeadSpawnRequest,
+): Promise<{ content: any[]; details: any }> {
+  const requestedTeamName = typeof request.params.team_name === "string" ? request.params.team_name : undefined;
+  const targetTeamName = resolveLeadRequestTeamName(options, requestedTeamName);
+  const requestedAgentName = typeof request.params.name === "string" && request.params.name.trim().length > 0
+    ? ` for ${request.params.name}`
+    : "";
+  const summary = `Agent spawn request from ${options.agentName}${requestedAgentName}`;
+  const content = [
+    `${options.agentName} requested a lead-owned agent action.`,
+    "",
+    "Teammates are not allowed to spawn or promote other agents directly. The team lead must decide whether to run this request.",
+    "",
+    `Requested action: ${request.action}`,
+    request.reason ? `Reason: ${request.reason}` : undefined,
+    "Requested parameters:",
+    compactJson(request.params),
+    "",
+    `If appropriate, the lead should call ${request.action} with the requested parameters or adjust them before spawning.`,
+  ].filter((line): line is string => line != null).join("\n");
+
+  await messaging.sendPlainMessage(targetTeamName, options.agentName, "team-lead", content, summary, "yellow");
+
+  return {
+    content: [{ type: "text", text: `Teammates cannot spawn agents directly. Sent a request to team-lead for ${targetTeamName}.` }],
+    details: {
+      requested: true,
+      requestedAction: request.action,
+      teamName: targetTeamName,
+      recipient: "team-lead",
+      from: options.agentName,
+      params: request.params,
+    },
+  };
+}

package/extensions/tools/file-claim-tools.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createFileClaimTools } from "./file-claim-tools.js";
+import * as claims from "../../src/utils/claims.js";
+import * as paths from "../../src/utils/paths.js";
+
+let root: string;
+
+type Tool = {
+  name: string;
+  execute: (toolCallId: string, params: any) => Promise<any>;
+};
+
+function makeTools(agentName: string, authorize = vi.fn(async () => "session")) {
+  const tools = createFileClaimTools({
+    agentName,
+    getAuthorizedWriteTeam: authorize,
+    getCurrentTeam: () => "session",
+    claims,
+  });
+  return { authorize, tools: new Map<string, Tool>(tools.map((tool: Tool) => [tool.name, tool])) };
+}
+
+describe("identity-bound file claim tools", () => {
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-extended-teams-file-claims-"));
+    vi.spyOn(paths, "claimsPath").mockImplementation((teamName: string) => path.join(root, `${teamName}.json`));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (root && fs.existsSync(root)) fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("authorizes the bound writer and preserves normalized atomic grants", async () => {
+    const { authorize, tools } = makeTools("writer");
+
+    const result = await tools.get("claim_file")!.execute("claim", {
+      paths: ["./src/a.ts", "src/a.ts/"],
+    });
+
+    expect(authorize).toHaveBeenCalledTimes(1);
+    expect(result.details).toMatchObject({
+      agent: "writer",
+      session: "session",
+      granted: ["src/a.ts"],
+      conflicts: [],
+    });
+    expect(await claims.listClaims("session")).toEqual([
+      expect.objectContaining({ agent: "writer", path: "src/a.ts" }),
+    ]);
+  });
+
+  it("returns conflict holder details without partially granting the request", async () => {
+    await claims.claimFiles("session", "other-writer", ["src/a.ts"]);
+    const { tools } = makeTools("writer");
+
+    const result = await tools.get("claim_file")!.execute("claim", {
+      paths: ["src/a.ts", "src/b.ts"],
+    });
+
+    expect(result.details).toMatchObject({
+      agent: "writer",
+      session: "session",
+      granted: [],
+      conflicts: [{ path: "src/a.ts", heldBy: "other-writer" }],
+    });
+    expect(result.content[0].text).toContain("src/a.ts held by other-writer");
+    expect((await claims.listClaims("session")).map(claim => claim.path)).toEqual(["src/a.ts"]);
+  });
+
+  it("lists active claims and releases only claims owned by the bound writer", async () => {
+    await claims.claimFiles("session", "writer", ["src/b.ts"]);
+    await claims.claimFiles("session", "other-writer", ["src/a.ts"]);
+    const { tools } = makeTools("writer");
+
+    const listed = await tools.get("list_file_claims")!.execute("list", {});
+    expect(listed.details.claims.map((claim: any) => [claim.path, claim.agent])).toEqual([
+      ["src/a.ts", "other-writer"],
+      ["src/b.ts", "writer"],
+    ]);
+
+    const released = await tools.get("release_file")!.execute("release", {
+      paths: ["src/a.ts", "./src/b.ts"],
+    });
+    expect(released.details.released).toEqual(["src/b.ts"]);
+    expect(await claims.listClaims("session")).toEqual([
+      expect.objectContaining({ agent: "other-writer", path: "src/a.ts" }),
+    ]);
+  });
+
+  it("does not touch claim storage when writer authorization fails", async () => {
+    const authorize = vi.fn(async () => {
+      throw new Error("File claim tools are only available to write agents.");
+    });
+    const { tools } = makeTools("reader", authorize);
+
+    await expect(tools.get("claim_file")!.execute("claim", { paths: ["src/a.ts"] }))
+      .rejects.toThrow("only available to write agents");
+    expect(await claims.listClaims("session")).toEqual([]);
+  });
+});

package/extensions/tools/file-claim-tools.ts

@@ -0,0 +1,68 @@
+import { Type } from "@sinclair/typebox";
+import type * as claimOperations from "../../src/utils/claims";
+
+export interface FileClaimOperations {
+  claimFiles: typeof claimOperations.claimFiles;
+  releaseFiles: typeof claimOperations.releaseFiles;
+  listClaims: typeof claimOperations.listClaims;
+}
+
+export interface FileClaimToolsOptions {
+  agentName: string;
+  getAuthorizedWriteTeam(): Promise<string>;
+  getCurrentTeam(): string;
+  claims: FileClaimOperations;
+}
+
+export function createFileClaimTools(options: FileClaimToolsOptions): any[] {
+  return [
+    {
+      name: "claim_file",
+      label: "Claim File",
+      description: "Claim file paths before an edit agent changes them. Claims are scoped to the current Pi session.",
+      parameters: Type.Object({ paths: Type.Array(Type.String({ description: "Repository-relative file path." })) }),
+      async execute(_toolCallId: string, params: any) {
+        const targetTeamName = await options.getAuthorizedWriteTeam();
+        const result = await options.claims.claimFiles(targetTeamName, options.agentName, params.paths);
+        const text = result.conflicts.length > 0
+          ? [
+              `File claim request blocked for ${options.agentName}.`,
+              "Conflicts:",
+              ...result.conflicts.map(conflict => `- ${conflict.path} held by ${conflict.heldBy}`),
+            ].join("\n")
+          : result.granted.length > 0
+            ? [`Claimed ${result.granted.length} file(s) for ${options.agentName}:`, ...result.granted.map(item => `- ${item}`)].join("\n")
+            : `No file paths claimed for ${options.agentName}.`;
+        return { content: [{ type: "text", text }], details: { agent: options.agentName, session: targetTeamName, ...result } };
+      },
+    },
+    {
+      name: "release_file",
+      label: "Release File",
+      description: "Release file claims held by the current edit agent.",
+      parameters: Type.Object({ paths: Type.Array(Type.String({ description: "Repository-relative file path." })) }),
+      async execute(_toolCallId: string, params: any) {
+        const targetTeamName = await options.getAuthorizedWriteTeam();
+        const released = await options.claims.releaseFiles(targetTeamName, options.agentName, params.paths);
+        const text = released.length > 0
+          ? `Released ${released.length} file claim(s) for ${options.agentName}:\n${released.map(item => `- ${item}`).join("\n")}`
+          : `No matching file claims held by ${options.agentName} were released.`;
+        return { content: [{ type: "text", text }], details: { agent: options.agentName, session: targetTeamName, released } };
+      },
+    },
+    {
+      name: "list_file_claims",
+      label: "List File Claims",
+      description: "List file claims in the current Pi session.",
+      parameters: Type.Object({}),
+      async execute() {
+        const targetTeamName = options.getCurrentTeam();
+        const currentClaims = (await options.claims.listClaims(targetTeamName)).sort((a, b) => a.path.localeCompare(b.path));
+        const text = currentClaims.length > 0
+          ? ["Current file claims:", ...currentClaims.map(claim => `- ${claim.path} held by ${claim.agent} since ${new Date(claim.since).toISOString()}`)].join("\n")
+          : "No current file claims.";
+        return { content: [{ type: "text", text }], details: { session: targetTeamName, claims: currentClaims } };
+      },
+    },
+  ];
+}