@cmgmyr/hive 1.2.2 → 1.4.0

package/dist/tools/agents.js

@@ -2,16 +2,18 @@ import { existsSync, rmSync, statSync, realpathSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { db } from "../db.js";
+import { confirmQueenWrite } from "../queenAudit.js";
+import { captureQueenWriteIdentity } from "../context.js";
 import { agentBriefPath, mergedBriefVars, readAgentBrief, workerBrief, workerCommandString, writeAgentBrief, } from "../brief.js";
-import { codexHomeDir, codexInstructionsPhrase, codexLaunchArgs, ensureCodexHome, ensureCodexHooksFile } from "../codexHome.js";
+import { codexHomeDir, codexInstructionsPhrase, codexLaunchArgs, ensureCodexHome, ensureCodexHooksFile, refreshCodexMcpEnv } from "../codexHome.js";
 import { currentActor, findProjectForDir, getProject, linkedWorktreePrimaryRoot, resolveProject } from "../context.js";
-import { commandHead, harnessFor, harnessNames, paneClassifierFor, resolvedCommandPrefix, screenClassifiable, } from "../harnesses.js";
+import { commandHead, harnessFor, harnessNames, readOnlyExtraArgsAllowed, paneClassifierFor, resolvedCommandPrefix, screenClassifiable, } from "../harnesses.js";
 import { ensureWorkerHooksFile } from "../hooks.js";
 import { activeProfile, allowedAgents, loadProjectYml } from "../projectYml.js";
 import { classifyMiss, LEAD_MESSAGE_THRESHOLD, leadPointerMarker, missMessage, readLeadMessage, renderLeadPointer, senderTag, shortenedSendFailureClause, shortenedSendNote, storeLeadMessage, } from "../leadMessage.js";
 import { run } from "../result.js";
 import { markGoneReported } from "../scheduler.js";
-import { branchAt, closeAgentRow, discardOrphanedPane, isReservedAgentName, isRunningLeadActor, killAgentPane, launchAgent, LEAD_KIND, parkAgentRow, reapCodexHomeForClosedAgent, releaseParkRow, renameAgent, resumeAgent, } from "../spawn.js";
+import { agentIdentityEnv, branchAt, closeAgentRow, discardOrphanedPane, isReservedAgentName, isRunningLeadActor, killAgentPane, launchAgent, LEAD_KIND, parkAgentRow, reapCodexHomeForClosedAgent, releaseParkRow, renameAgent, resumeAgent, storedLaunchOptions, } from "../spawn.js";
 import { COMMAND_KIND, runningCommandRow, stopLine, stopProcess, STOP_REASONS } from "../processes.js";
 import { readContextTokens, readContextFill, resolveTranscriptDir } from "../transcript.js";
 import { capturePane, captureFinalScreen, DEFAULT_LAYOUT, cancelCopyMode, describePaneChoice, ensureAttached, findUnsafeControlChar, holdsHumanInput, liveTargets, paneCurrentCommand, paneInCopyMode, paneWindow, pollPaneReadiness, rowAlive, rowLive, sendText, sessionName, setRemainOnExit, sleep, TEXT_ALLOWED_CONTROL_CHARS, tmux, TmuxTimeoutError, WINDOW_LAYOUTS, } from "../tmux.js";
@@ -161,17 +163,67 @@ function requireNameFree(projectId, name, exceptAgentId) {
         throw new Error(`A running agent named "${taken.name}" already exists. Pick another name.`);
     }
 }
-// Recovers a flag's value from a row's own recorded command string - the only place agent_resume
-// can read it back from, since ResumeSpec is built fresh and does not carry agent_spawn's original
-// args. Model ids are shell-safe by construction (gpt-5.6-luna, sonnet), so shellQuote never quotes
-// this token and a plain whitespace split is enough - no quote-stripping to get wrong.
+function commandTokens(command) {
+    const tokens = [];
+    let token = "";
+    let quote = null;
+    let escaped = false;
+    for (const char of command) {
+        if (escaped) {
+            token += char;
+            escaped = false;
+        }
+        else if (char === "\\" && quote !== "'") {
+            escaped = true;
+        }
+        else if (quote) {
+            if (char === quote)
+                quote = null;
+            else
+                token += char;
+        }
+        else if (char === "'" || char === '"') {
+            quote = char;
+        }
+        else if (/\s/.test(char)) {
+            if (token) {
+                tokens.push(token);
+                token = "";
+            }
+        }
+        else {
+            token += char;
+        }
+    }
+    if (escaped)
+        token += "\\";
+    if (token)
+        tokens.push(token);
+    return tokens;
+}
 function extractCommandFlag(command, flag) {
-    const tokens = command.split(/\s+/);
+    const tokens = commandTokens(command);
     const i = tokens.indexOf(flag);
     if (i === -1 || i + 1 >= tokens.length)
         return undefined;
     return tokens[i + 1];
 }
+function stripSessionArgs(args) {
+    const stripped = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--resume" || arg === "--session-id" || arg === "-r") {
+            i++;
+        }
+        else if (arg === "--last" || arg === "--fork-session" || arg.startsWith("--resume=") || arg.startsWith("--session-id=")) {
+            continue;
+        }
+        else {
+            stripped.push(arg);
+        }
+    }
+    return stripped;
+}
 function requestsExistingSession(extraArgs) {
     return (extraArgs ?? []).some((arg) => arg === "--resume" ||
         arg.startsWith("--resume=") ||
@@ -261,6 +313,7 @@ function agentSummary(row, snapshot) {
         provenance,
         ...lastLogEventField(row),
         ...permissionModeField(row),
+        read_only: storedLaunchOptions(row.extra_args).readOnly,
         ...contextFillField(row),
         ...(row.parked_at ? { parked_at: row.parked_at, parked_branch: row.parked_branch || null } : {}),
         tmux_target: row.tmux_target,
@@ -285,7 +338,13 @@ export function worktreeInstallNotice(cwd, projectPath, config) {
 }
 export function registerAgents(server) {
     server.registerTool("agent_spawn", {
-        description: "Spawn a worker agent (default: claude, or the project's hive.yml agents: default). A claude worker is briefed automatically: the full brief is appended to its system prompt, so send it its assignment directly. A command or harness that resolves to a known harness (claude, codex) not listed in the project's hive.yml agents: is refused; absent agents: means claude only. A command hive cannot classify the screen of (claude and codex both do; a harness with no entry does not) can be spawned but NOT typed into: the receipt carries brief_path and says so, and agent_send's text path and wakes both refuse that pane. The worker is locked to this project. Humans can watch with: tmux attach -t hive-main.",
+        description: "Spawn a worker agent (default: claude, or the project's hive.yml agents: default). A claude worker is briefed automatically: the full brief is appended to its system prompt, so send it its assignment directly. A command or harness that resolves to a known harness (claude, codex) not listed in the project's hive.yml agents: is refused; absent agents: means claude only. A command hive cannot classify the screen of (claude and codex both do; a harness with no entry does not) can be spawned but NOT typed into: the receipt carries brief_path and says so, and agent_send's text path and wakes both refuse that pane. Set read_only: true to block local file writes and mutating shell while keeping Hive MCP available; agent_resume preserves this mode and agent_status reports it. Only bare claude/codex executables are supported in this mode, with only effort-setting extra_args. The worker is locked to this project. Humans can watch with: tmux attach -t hive-main.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             name: z
                 .string()
@@ -301,6 +360,7 @@ export function registerAgents(server) {
                 .optional()
                 .describe("Spawn a known harness by name (e.g. \"codex\") instead of a raw command. Ignored when command is also given. Must be in the project's hive.yml agents: list (default: claude only)."),
             extra_args: z.array(z.string()).optional().describe("Extra CLI arguments."),
+            read_only: z.boolean().optional().describe("Prevent local file writes and mutating shell commands while allowing Hive MCP tools. Only bare claude/codex executables. Extra args allow codex -c model_reasoning_effort=low|medium|high|xhigh, or claude --effort low|medium|high|xhigh|max; all other arguments are refused."),
             cwd: z
                 .string()
                 .optional()
@@ -326,6 +386,7 @@ export function registerAgents(server) {
             worktree_install: z.string().optional(),
             brief_path: z.string().optional(),
             codex_home: z.string().optional(),
+            read_only: z.boolean().optional(),
             codex_instructions: z.string().optional(),
             ready: z.boolean().optional(),
             exited: z.boolean().optional(),
@@ -378,6 +439,11 @@ export function registerAgents(server) {
             throw new Error(`[agent_spawn:harness-not-allowed] "${harness.name}" is not in this project's hive.yml ` +
                 `agents: list (${allowed.join(", ")}). Add it to agents: to allow spawning it.`);
         }
+        if (args.read_only && (!["claude", "codex"].includes(harness.name) ||
+            !/^[A-Za-z0-9_./-]+$/.test(baseCommand) ||
+            !readOnlyExtraArgsAllowed(harness.name, args.extra_args))) {
+            throw new Error("read_only requires a bare claude or codex executable and no extra_args; launch overrides can bypass its restrictions.");
+        }
         const mintsSession = harness.mintsSessionId;
         const sessionId = mintsSession && !requestsExistingSession(args.extra_args) ? randomUUID() : "";
         const worktreeInstall = worktreeInstallNotice(cwd, project.path, projectConfig);
@@ -401,7 +467,7 @@ export function registerAgents(server) {
             const briefPath = harness.briefDelivery ? writeAgentBrief(agentId, brief) : undefined;
             let homeArgs = [];
             if (codexHomeKey) {
-                const home = ensureCodexHome({ key: codexHomeKey, actorId, cwd, brief: brief, includePostToolUse: projectConfig?.context_checkpoint_percent != null });
+                const home = ensureCodexHome({ key: codexHomeKey, actorId, serverEnv: agentIdentityEnv(actorId, name, project.path), cwd, brief: brief, readOnly: args.read_only, includePostToolUse: projectConfig?.context_checkpoint_percent != null });
                 homeArgs = home.extraArgs;
                 codexInstructionLayers = home.instructionLayers;
             }
@@ -415,7 +481,7 @@ export function registerAgents(server) {
                         ? [...(sessionId ? ["--session-id", sessionId] : []), ...(args.extra_args ?? [])]
                         : (args.extra_args ?? [])),
                 ],
-                settingsPath: harness.briefDelivery ? ensureWorkerHooksFile(agentId, { includePostToolUse: projectConfig?.context_checkpoint_percent != null }) : undefined,
+                settingsPath: harness.briefDelivery ? ensureWorkerHooksFile(agentId, { readOnly: args.read_only, includePostToolUse: projectConfig?.context_checkpoint_percent != null }) : undefined,
                 briefPath,
             });
         };
@@ -439,6 +505,9 @@ export function registerAgents(server) {
                 parentActor: parent,
                 sessionId,
                 codexHome: codexHomeKey,
+                model: args.model,
+                extraArgs: args.extra_args,
+                readOnly: args.read_only,
                 retainOnExit: harness.classifiesPaneScreen,
             });
         }
@@ -497,6 +566,7 @@ export function registerAgents(server) {
         const codexInstructions = codexHomeKey ? codexInstructionsPhrase(codexInstructionLayers) : undefined;
         return {
             agent_id: agentId,
+            ...(args.read_only ? { read_only: true } : {}),
             actor_id: actorId,
             name,
             tmux_target: target,
@@ -546,6 +616,12 @@ export function registerAgents(server) {
     }));
     server.registerTool("agent_resume", {
         description: "Resume a CLOSED claude or codex worker from its recorded session id (claude --resume / codex resume): a fresh pane, the same actor_id, and the worker's full prior context. Addressed by name or agent_id among closed agents (agent_list(include_closed: true)). Send it its next instruction with agent_send once resumed - this tool does not.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             name: agentNameParam,
             agent_id: agentIdParam,
@@ -614,6 +690,7 @@ export function registerAgents(server) {
         const { config: projectConfig } = loadProjectYml(project.path);
         const placement = projectConfig?.placement ?? (process.env.HIVE_SPAWN_PLACEMENT === "window" ? "window" : "split");
         const layout = projectConfig?.layout ?? DEFAULT_LAYOUT;
+        const launchOptions = storedLaunchOptions(agent.extra_args);
         let commandString;
         let resumeEnv = contextCheckpointEnv(projectConfig);
         if (resumeHarness.name === "codex") {
@@ -622,23 +699,34 @@ export function registerAgents(server) {
                 // Recovered from the row's own recorded command: every codex worker hive spawns
                 // carries a pinned model (codex has no bare alias), so dropping this would silently
                 // resume on codex's default model instead of the one the lane actually chose.
-                model: extractCommandFlag(agent.command, "--model"),
+                model: agent.model ?? extractCommandFlag(agent.command, "--model"),
                 displayName: agent.name,
                 // Subcommand positional, not a flag - live-verified on v0.149.0 (`codex resume --help`:
                 // "Usage: codex resume [OPTIONS] [SESSION_ID] [PROMPT]"). No --settings/hooks file: a
                 // codex worker's hooks come from its own home's hooks.json, never claude's shared one.
-                extraArgs: [...codexLaunchArgs(agent.cwd), "resume", agent.session_id],
+                extraArgs: [
+                    ...codexLaunchArgs(agent.cwd, launchOptions.readOnly),
+                    ...stripSessionArgs(launchOptions.args),
+                    "resume",
+                    agent.session_id,
+                ],
             });
             resumeEnv = { ...resumeEnv, CODEX_HOME: codexHomeDir(agent.codex_home) };
             ensureCodexHooksFile(agent.codex_home, { includePostToolUse: projectConfig?.context_checkpoint_percent != null });
+            refreshCodexMcpEnv(agent.codex_home, agentIdentityEnv(agent.actor_id, agent.name, project.path));
         }
         else {
             const claudeBinary = resolvedCommandPrefix(agent.command) || "claude";
             commandString = workerCommandString({
                 command: claudeBinary,
                 displayName: agent.name,
-                extraArgs: ["--resume", agent.session_id],
-                settingsPath: ensureWorkerHooksFile(agent.id, { includePostToolUse: projectConfig?.context_checkpoint_percent != null }),
+                model: agent.model ?? undefined,
+                extraArgs: [
+                    ...stripSessionArgs(launchOptions.args),
+                    "--resume",
+                    agent.session_id,
+                ],
+                settingsPath: ensureWorkerHooksFile(agent.id, { readOnly: launchOptions.readOnly, includePostToolUse: projectConfig?.context_checkpoint_percent != null }),
             });
         }
         const { target, landedInProjectId } = resumeAgent({
@@ -671,6 +759,12 @@ export function registerAgents(server) {
     }));
     server.registerTool("agent_park", {
         description: "Park a claude or codex worker for the night: kill its pane, mark the row PARKED rather than plain closed, record the branch, and hand back a board line plus the one call that brings it back. Use this instead of agent_close when the lane is paused, not finished - `closed` alone cannot tell a next-morning lead which is which. Resume it with agent_resume.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             name: agentNameParam,
             agent_id: agentIdParam,
@@ -746,6 +840,12 @@ export function registerAgents(server) {
     }));
     server.registerTool("agent_rename", {
         description: "Change a worker's display name. Its actor_id (agent:N) does not change, so every pad write, todo comment and lease it has already made stays attributable. A live claude worker is also told to retitle its own session, which shows up in its pane; that arrives as a user turn, so rename between assignments rather than mid-task. Refuses a lead target outright.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             name: agentNameParam,
             agent_id: agentIdParam,
@@ -838,6 +938,12 @@ export function registerAgents(server) {
     }));
     server.registerTool("agent_list", {
         description: "List this project's agents with live status. Without include_closed, this is every running agent, in full. With include_closed, it is every agent (running and closed/parked), newest first, bounded by limit (default 20, max 100); when the receipt carries next_before_id, page through the rest by passing it back as before_id.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             include_closed: z.boolean().optional(),
             limit: z
@@ -907,6 +1013,12 @@ export function registerAgents(server) {
     }));
     server.registerTool("agent_status", {
         description: "Detailed status for one agent, addressed by name (or agent_id), including a short tail of its terminal. include_brief=true returns the exact brief this worker was given; hive keeps that copy because an appended system prompt appears in no transcript.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             name: agentNameParam,
             agent_id: agentIdParam,
@@ -937,6 +1049,12 @@ export function registerAgents(server) {
     }));
     server.registerTool("agent_send", {
         description: "Type into an agent's terminal, addressed by name (or agent_id). text of any shape is prefixed with the sender tag, delivered as one bracketed paste and submitted with Enter unless submit=false. ONE EXCEPTION: text over 300 characters sent to a LEAD by anyone who is not that lead is stored and delivered as a one-line pointer instead, because a lead's pane is a human's own window; the receipt says so and names agent_message_get for the full text. Worker-bound text is never shortened at any length. Alternatively pass keys (tmux key names like Escape, C-c, Enter). wait_ms (250-10000) returns the terminal tail after sending. A claude worker is already briefed by agent_spawn. A worker whose screen hive cannot classify is REFUSED on the text path entirely (its brief is at the spawn receipt's brief_path); keys still reaches it. A pane in tmux copy mode is REFUSED too, and retriably: tmux clears its bracketed-paste flag there, so the paste would lose its markers and the Enter would be eaten - leave copy mode (or agent_send(keys: [\"-X\", \"cancel\"]) to cancel it deliberately) and send again.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             name: agentNameParam,
             agent_id: agentIdParam,
@@ -951,6 +1069,7 @@ export function registerAgents(server) {
         const agent = findAgent(project.id, args);
         requireLive(agent);
         const target = agent.tmux_target;
+        const auditIdentity = captureQueenWriteIdentity(project.id);
         let outgoing = args.text ?? "";
         const tag = senderTag(project.id, currentActor());
         let shortened = null;
@@ -1094,6 +1213,7 @@ export function registerAgents(server) {
                         : `That target is a LEAD session, so agent_send's keys path is refused against it from a non-lead caller: you cannot finish this yourself. A human at that terminal, or another lead, has to press Enter there. Leave it and try again later.${shortened === null ? "" : " Pressing Enter there is the INTENDED finish, not a stray paste: that stranded line is hive's own pointer, and submitting it is exactly what this send was supposed to do."}`) +
                     shortenedClause, { cause: err });
             }
+            confirmQueenWrite("agent_send", project.id, args, { sent: true, agent_id: agent.id }, auditIdentity);
         }
         else {
             throw new Error("Pass text or keys.");
@@ -1121,6 +1241,12 @@ export function registerAgents(server) {
     }));
     server.registerTool("agent_message_get", {
         description: "Read one agent-to-lead message in full, by the id in a \"[hive:worker NAME] [message #N ...]\" pointer line. hive stores a message here only when it shortens one: text over 300 characters sent to a lead by someone who is not that lead. Every other send is typed with its sender tag and stores nothing, so there is no id to read. Messages are pruned after 7 days, and a lookup for a pruned id says so rather than reporting it missing.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             message_id: idParam,
             project_id: projectIdParam,
@@ -1143,6 +1269,12 @@ export function registerAgents(server) {
     }));
     server.registerTool("agent_output", {
         description: "Read the rendered terminal of an agent (default 50 lines, max 200), addressed by name or agent_id. Read REAL output before declaring a worker done.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             name: agentNameParam,
             agent_id: agentIdParam,
@@ -1172,6 +1304,12 @@ export function registerAgents(server) {
     }));
     server.registerTool("agent_close", {
         description: "Kill an agent's tmux window and mark it closed, addressed by name (or agent_id). Capture handoffs (todo comments, pads) BEFORE closing; terminal output is not retained. Closing yourself requires confirm_self=true. Refuses a lead target whose pane is live; retires one whose pane is confirmed dead. A worker may never close a lead, live or dead.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             name: agentNameParam,
             agent_id: agentIdParam,

package/dist/tools/kv.js

@@ -9,6 +9,12 @@ function purgeExpired(projectId) {
 export function registerKv(server) {
     server.registerTool("kv_set", {
         description: "Set a small shared JSON value other sessions can discover. Optional TTL in seconds.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             key: z.string(),
             value: z.any().describe("Any JSON value."),
@@ -31,6 +37,12 @@ export function registerKv(server) {
     }));
     server.registerTool("kv_get", {
         description: "Get a shared JSON value by key.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: { key: z.string(), project_id: projectIdParam },
     }, (args) => run(() => {
         const projectId = effectiveProjectId(args.project_id);
@@ -52,6 +64,12 @@ export function registerKv(server) {
     }));
     server.registerTool("kv_list", {
         description: "List shared values, optionally filtered by key prefix.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: { prefix: z.string().optional(), project_id: projectIdParam },
     }, (args) => run(() => {
         const projectId = effectiveProjectId(args.project_id);
@@ -77,6 +95,12 @@ export function registerKv(server) {
     }));
     server.registerTool("kv_delete", {
         description: "Delete a shared value by key.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: { key: z.string(), project_id: projectIdParam },
         outputSchema: { project_id: idParam, key: z.string(), deleted: z.boolean() },
     }, (args) => run(() => {

package/dist/tools/leases.js

@@ -18,9 +18,15 @@ export function extendOwnedLease(projectId, key, actor, ttlSeconds) {
 }
 export function registerLeases(server) {
     server.registerTool("lease_acquire", {
-        description: "Try to take a named lease on a shared work area (non-blocking). Re-taking your own lease extends it. Leases expire on their own.",
+        description: "Try to take a named lease on state another session could also change, such as a shared checkout, a dev database or a port (non-blocking). Re-taking your own lease extends it. Leases expire on their own.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
-            key: z.string().describe('Stable and specific, like "file:src/api/routes.ts".'),
+            key: z.string().describe('Stable and specific, like "db:dev".'),
             ttl_seconds: z.number().int().positive(),
             project_id: projectIdParam,
         },
@@ -75,6 +81,12 @@ export function registerLeases(server) {
     }));
     server.registerTool("lease_release", {
         description: "Release a lease you own.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: { key: z.string(), project_id: projectIdParam },
         outputSchema: { project_id: idParam, key: z.string(), released: z.boolean() },
     }, (args) => run(() => {

package/dist/tools/meta.js

@@ -24,6 +24,12 @@ function existsWhere(table, column, value) {
 function projectOwnsRows(projectId) {
     return PROJECT_OWNER_TABLES.some((table) => existsWhere(table, "project_id", projectId));
 }
+function ownedRowCounts(projectId) {
+    return PROJECT_OWNER_TABLES.flatMap((table) => {
+        const n = db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE project_id = ?`).get(projectId).n;
+        return n > 0 ? [`${table}: ${n}`] : [];
+    });
+}
 const pruneProjectIfEmpty = db.transaction((projectId) => {
     if (projectOwnsRows(projectId))
         return false;
@@ -60,6 +66,12 @@ const pruneActorIfInert = db.transaction((actorId) => {
 export function registerMeta(server) {
     server.registerTool("whoami", {
         description: "Show this session's actor identity and effective project scope. Call this first in a new session.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {},
     }, () => run(() => {
         const actorId = currentActor();
@@ -83,6 +95,12 @@ export function registerMeta(server) {
     }));
     server.registerTool("help", {
         description: `Hive usage guidance. Omit topic for an overview, or pass one of: ${Object.keys(HELP_TOPICS).join(", ")}.`,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: { topic: z.string().optional() },
     }, ({ topic }) => run(() => {
         if (!topic)
@@ -95,6 +113,12 @@ export function registerMeta(server) {
     }));
     server.registerTool("project_list", {
         description: "List registered projects and the currently selected one.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {},
     }, () => run(() => ({
         projects: listProjects(),
@@ -102,6 +126,12 @@ export function registerMeta(server) {
     })));
     server.registerTool("project_add", {
         description: "Register a directory as a project. Defaults to the current working directory. Returns the existing project if the path is already registered.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             path: z.string().optional(),
             name: z.string().optional(),
@@ -110,19 +140,45 @@ export function registerMeta(server) {
     }, ({ path, name }) => run(() => addProject(path, name)));
     server.registerTool("project_select", {
         description: "Set which project later tools act on in this session.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: { project_id: idParam },
     }, ({ project_id }) => run(() => selectProjectById(project_id)));
     server.registerTool("project_prune", {
-        description: "Delete every registered project that owns no rows anywhere in the store (pads, todos, kv, leases, agents, wakes, command_trust), verified individually before each delete. Never prunes the caller's own project. Refuses under HIVE_PROJECT_LOCK=1: this is a whole-store sweep, and a project-locked session may only touch its own project. Immediate, permanent: no dry-run mode.",
-        inputSchema: {},
+        description: "Delete every registered project that owns no rows anywhere in the store (pads, todos, kv, leases, agents, wakes, command_trust), verified individually before each delete. Never prunes the caller's own project. With project_id, removes exactly that one project instead of sweeping, and only if it owns no rows; otherwise refuses and names what it owns. Refuses under HIVE_PROJECT_LOCK=1: this is a whole-store sweep, and a project-locked session may only touch its own project. Immediate, permanent: no dry-run mode.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        inputSchema: { project_id: idParam.optional() },
         outputSchema: {
             deleted: z.array(z.object({ id: idParam, name: z.string() })),
             held_back: z.object({ project_id: idParam, reason: z.string() }),
             errors: z.array(z.object({ id: idParam, name: z.string(), error: z.string() })).optional(),
         },
-    }, () => run(() => {
+    }, ({ project_id }) => run(() => {
         refuseIfLocked("project_prune");
         const homeId = resolveProject().id;
+        if (project_id !== undefined) {
+            if (project_id === homeId)
+                throw new Error(`project_prune: project ${project_id} is the caller's own project and is never pruned.`);
+            const target = listProjects().find((p) => p.id === project_id);
+            if (!target)
+                throw new Error(`project_prune: no project ${project_id}. List them with project_list.`);
+            if (!pruneProjectIfEmpty.immediate(project_id)) {
+                throw new Error(`project_prune: project ${project_id} ("${target.name}") is not empty, nothing deleted. It owns ${ownedRowCounts(project_id).join(", ")}.`);
+            }
+            return {
+                deleted: [{ id: target.id, name: target.name }],
+                held_back: { project_id: homeId, reason: "caller's own project" },
+            };
+        }
         const deleted = [];
         const errors = [];
         for (const project of listProjects()) {
@@ -145,6 +201,12 @@ export function registerMeta(server) {
     }));
     server.registerTool("actor_prune", {
         description: "Delete every actor that owns no rows anywhere in the store and has not been active in the last minute: agents.actor_id, agents.parent_actor_id, todos.locked_by, todo_comments.author, kv.updated_by, leases.owner, pads.updated_by, wakes.owner, wakes.deliver_actor, agent_state_log.actor_id. The scan is global across every project, never scoped to the caller's: actors carry no project_id, so an actor can own rows in a project the caller cannot see, and a project-scoped scan would misread that actor as inert and delete it. Never prunes the caller's own actor. Refuses under HIVE_PROJECT_LOCK=1: this is a whole-store sweep. Run this after project_prune when sweeping the store: an empty project owns no agents rows either, so today the order cannot orphan an actor, but that stops being true the day project deletion ever covers a non-empty project, and this ordering is the one that stays safe if it does. Immediate, permanent: no dry-run mode.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {},
         outputSchema: {
             deleted: z.array(z.object({ id: z.string(), name: z.string() })),

package/dist/tools/pads.js

@@ -80,6 +80,12 @@ export function createPad(projectId, name, content, tags) {
 export function registerPads(server) {
     server.registerTool("pad_write", {
         description: "Create a pad, or fully overwrite one by passing pad_id plus expected_revision. Pad names are unique per project. Prefer pad_append/pad_edit for targeted changes.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             name: z.string(),
             content: z.string(),
@@ -105,6 +111,12 @@ export function registerPads(server) {
     }));
     server.registerTool("pad_read", {
         description: "Read a pad's content, revision, and metadata by pad_id or name.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             pad_id: idParam.optional(),
             name: z.string().optional(),
@@ -139,6 +151,12 @@ export function registerPads(server) {
     }));
     server.registerTool("pad_append", {
         description: "Append content to the end of a pad. Optional expected_revision guards against concurrent writes.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             pad_id: idParam,
             content: z.string(),
@@ -155,6 +173,12 @@ export function registerPads(server) {
     }));
     server.registerTool("pad_edit", {
         description: "Replace one literal occurrence of old_text with new_text in a pad. old_text must match exactly once; include surrounding context to disambiguate.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             pad_id: idParam,
             old_text: z.string(),
@@ -180,6 +204,12 @@ export function registerPads(server) {
     }));
     server.registerTool("pad_archive", {
         description: "Archive a pad (or unarchive with archived=false). Archiving frees the name for a new active pad; the old content stays readable by pad_id.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         inputSchema: {
             pad_id: idParam,
             archived: z.boolean().optional().describe("Default true. Pass false to unarchive."),
@@ -207,6 +237,12 @@ export function registerPads(server) {
     }));
     server.registerTool("pad_delete", {
         description: "Permanently delete a pad. Irreversible; prefer pad_archive. Optional expected_revision guards against deleting a pad someone just updated.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             pad_id: idParam,
             expected_revision: idParam.optional(),
@@ -223,6 +259,12 @@ export function registerPads(server) {
     }));
     server.registerTool("pad_list", {
         description: "List pads without full content. query matches names and content (returns a snippet); tags matches any listed tag.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         inputSchema: {
             query: z.string().optional(),
             tags: z.array(z.string()).optional(),