@getsnare/mcp 0.1.0

package/dist/src/tools/local.js

@@ -0,0 +1,180 @@
+import { z } from "zod";
+import { toolText } from "../format.js";
+import { tool, write } from "../registry.js";
+/**
+ * Running a Snare here, on the caller's own agent, in the caller's own checkout.
+ *
+ * WHAT IS ACTUALLY HAPPENING. Snare's loop runs on Snare's servers: it decides
+ * which stage the run is in, what that stage is asked to do, whether the output
+ * is acceptable, whether to go back a stage, halt or escalate, what confidence
+ * to score it and what it costs. The MODEL is yours and the FILES are yours.
+ * That is the whole trade — the customer's own subscription and their own
+ * machine, driven by Snare's loop rather than by a prompt somebody wrote once.
+ *
+ * WHICH IS WHY THE PROTOCOL IS A LOOP AND NOT A CALL. `start_local_snare`
+ * returns the first instruction; every `local_snare_step` submits the result of
+ * the last one and returns the next. The agent keeps going until it gets `done`.
+ * That is spelled out in both descriptions, in the response text of every step,
+ * and in the `fix_issue` prompt, because a model that calls the step tool once
+ * and stops leaves a run hanging with a stage half-finished.
+ */
+/**
+ * The one paragraph every instruction carries.
+ *
+ * THE SECOND SENTENCE EXISTS BECAUSE A REAL RUN DIED WITHOUT IT. Snare's first
+ * command on a local run writes to `.git/info/exclude`, to keep its own scratch
+ * directory out of the diff — and a coding agent's own permission rules
+ * routinely treat anything under `.git/` as off limits. The agent was refused,
+ * had no instruction covering "I could not run this", and stopped, leaving the
+ * run open and waiting for an answer that was never coming.
+ *
+ * Reporting the failure is not a fallback, it is the protocol: Snare treats
+ * several of its own commands as best-effort and carries on when they fail. An
+ * agent that goes quiet instead turns a shrug into a dead run.
+ */
+const INSTRUCTION_GUIDE = `Do exactly what the instruction says, then call local_snare_step again with its result. ` +
+    `If you CANNOT do it — a command is denied, a file is unreadable, a tool refuses — say so through ` +
+    `local_snare_step with the same requestId and the \`error\` field describing what stopped you. Never go silent ` +
+    `and never skip a step: Snare is waiting on that requestId, treats some failures as expected and carries on, ` +
+    `and a run nobody answers just times out. Keep going until you get "done".`;
+/**
+ * Renders one instruction as something a model can act on without guessing.
+ *
+ * EVERY BRANCH ENDS WITH WHAT TO DO NEXT. A model handed a stage brief and no
+ * reminder that a result has to come back will do the work and then stop, and
+ * the run sits waiting on a channel until it times out — which looks to the
+ * person watching like Snare hanging rather than like the loop being dropped.
+ */
+function renderInstruction(instruction, runId) {
+    switch (instruction.kind) {
+        case "stage":
+            return toolText(`STAGE: ${instruction.stage}. Do this work in the repository, then submit the result.`, instruction.brief ?? "", instruction.input ? `What you have been given\n${JSON.stringify(instruction.input, null, 2)}` : null, instruction.schema
+                ? `Your answer must match this schema exactly\n${JSON.stringify(instruction.schema, null, 2)}`
+                : null, `When you are done, call local_snare_step with runId "${runId}", requestId "${instruction.requestId}", and your structured output as \`result\`.`);
+        case "exec":
+            return toolText(`RUN THIS COMMAND in the repository root:\n\n${instruction.command}`, `Then call local_snare_step with runId "${runId}", requestId "${instruction.requestId}", and result ` +
+                `{ exitCode, stdout, stderr }. A command that fails is a normal answer — send the real exit code and ` +
+                `output rather than nothing. If you are REFUSED and it never ran, send \`error\` saying so instead; ` +
+                `Snare expects some of its commands to be refused and moves on.`);
+        case "read":
+            return `READ the file "${instruction.path}" and call local_snare_step with runId "${runId}", requestId "${instruction.requestId}", and result { content }. If it does not exist, send result { error: "not found" }.`;
+        case "write":
+            return toolText(`WRITE this content to "${instruction.path}":\n\n${instruction.content ?? ""}`, `Then call local_snare_step with runId "${runId}", requestId "${instruction.requestId}", and result { ok: true }.`);
+        case "list":
+            return `LIST the entries in "${instruction.path}" and call local_snare_step with runId "${runId}", requestId "${instruction.requestId}", and result { entries: [...] }.`;
+        case "exists":
+            return `CHECK whether "${instruction.path}" exists and call local_snare_step with runId "${runId}", requestId "${instruction.requestId}", and result { exists: true|false }.`;
+        case "notice":
+            return toolText(instruction.text ?? "", `Nothing to do. Call local_snare_step again with runId "${runId}" and requestId "${instruction.requestId}" to carry on.`);
+        case "wait":
+            // A poll that returns nothing is normal, not an error: the server holds
+            // the call for up to twenty-five seconds so that every client's own tool
+            // timeout is comfortably clear, and then answers with this.
+            return `Snare is still working. Call local_snare_step again with runId "${runId}" to keep waiting.`;
+        case "done":
+            return toolText(`FINISHED: ${instruction.outcome ?? "done"}.`, instruction.summary ?? "", instruction.confidence !== null && instruction.confidence !== undefined
+                ? `Snare's confidence in this fix: ${Math.round(instruction.confidence * 100)}%.`
+                : null, instruction.filesChanged && instruction.filesChanged.length > 0
+                ? `Files changed in your working tree:\n${instruction.filesChanged.map((file) => `- ${file}`).join("\n")}`
+                : "No files were changed.", instruction.pullRequestUrl ? `Pull request: ${instruction.pullRequestUrl}` : null, "The run is over. Do not call local_snare_step again for this run.");
+        default:
+            return `Unrecognised instruction "${instruction.kind}". Report this and stop.`;
+    }
+}
+export const localTools = [
+    tool({
+        name: "start_local_snare",
+        title: "Run a Snare here",
+        description: "Run Snare's fix loop on THIS machine, against the repository you have open, using your own model. Snare " +
+            "still decides the stages, checks your output against each one's contract, and scores the result — you do " +
+            "the reading and the editing. THIS SPENDS A SNARE from the workspace's plan, the same as a cloud run, " +
+            "because what is being used is the loop rather than the compute.\n\n" +
+            "It WILL change files in the working tree. Make sure the tree is clean and on the right branch first, and " +
+            "tell the person before you start.\n\n" +
+            "Snare cannot enforce anything on this machine — the safety rules it applies in its own sandbox are " +
+            "instructions to you here, not a boundary. Stay inside the repository, do not push, do not deploy.\n\n" +
+            "This returns the run id and either the first instruction or a note that Snare is still setting the run up " +
+            "— reading the issue, its occurrences and what Snare already knows about the project takes a moment, and " +
+            "that often outlasts the first response. Either way the next move is the same: call local_snare_step in a " +
+            "loop until it returns \"done\". Getting \"still working\" back is normal and is not a failure.\n\n" +
+            "ONLY THE FULL LOOP RUNS HERE. Snare Lite and read-only investigations run in Snare's cloud only — for " +
+            "either of those, use launch_snare.",
+        scope: "snares:local",
+        toolset: "local",
+        input: {
+            issue: z.string().describe('The issue, as its key ("ACME-142") or its id.'),
+            // FULL and nothing else, because that is all `POST /v1/local-runs`
+            // accepts. The enum used to offer INVESTIGATE as well, so a model that
+            // was asked to "just look into it locally" chose a value the route
+            // answered with `Invalid enum value` — a control that looked available
+            // and was not. The description above says where those two modes do run.
+            mode: z
+                .enum(["FULL"])
+                .optional()
+                .describe("FULL is the only mode that runs locally, and the default. Nothing else is accepted."),
+            repoRef: z
+                .string()
+                .optional()
+                .describe("The branch or commit the working tree is on, so Snare can check it matches the project."),
+        },
+        annotations: write(),
+        async run(args, { client }) {
+            const data = await client.post("/local-runs", args);
+            return toolText(`Local run ${data.runId} started.`, data.warning, INSTRUCTION_GUIDE, renderInstruction(data.first, data.runId));
+        },
+    }),
+    tool({
+        name: "local_snare_step",
+        title: "Do the next step of a local run",
+        description: "Submit the result of the last instruction and get the next one. Call this REPEATEDLY until it returns " +
+            '"done" — a local run is a loop, and stopping after one call leaves the run hanging.\n\n' +
+            "Pass `requestId` from the instruction you are answering, and `result` as the JSON that instruction asked " +
+            'for. On the very first call after start_local_snare, or when the last instruction was "wait", send neither.',
+        scope: "snares:local",
+        toolset: "local",
+        input: {
+            runId: z.string(),
+            requestId: z
+                .string()
+                .optional()
+                .describe("From the instruction you are answering. Omit when there is nothing to submit."),
+            result: z
+                .unknown()
+                .optional()
+                .describe("The JSON the instruction asked for. Omit when there is nothing to submit."),
+        },
+        annotations: write(),
+        async run(args, { client }) {
+            const data = await client.post(`/local-runs/${encodeURIComponent(args.runId)}/step`, { requestId: args.requestId, result: args.result }, 
+            // Longer than the default, because the server deliberately holds this
+            // for up to twenty-five seconds waiting for the loop to produce
+            // something. A thirty-second ceiling would time out exactly when it
+            // was about to work.
+            //
+            // AND NEVER RETRIED. This call is already a long poll, so three
+            // attempts against a slow or unreachable server is a tool call that
+            // hangs for two minutes before reporting what the first attempt
+            // already knew. Retrying also re-submits the result, which the server
+            // would treat as an answer to an instruction it has already moved past.
+            { timeoutMs: 40_000, retry: false });
+            return renderInstruction(data, args.runId);
+        },
+    }),
+    tool({
+        name: "cancel_local_snare",
+        title: "Stop a local run",
+        description: "Abandon a local run. Use it if the person changes their mind, or if you cannot carry out an instruction. " +
+            "Any changes already made to the working tree stay there — this stops the loop, it does not undo the edits.",
+        scope: "snares:local",
+        toolset: "local",
+        input: {
+            runId: z.string(),
+            reason: z.string().max(500).optional(),
+        },
+        annotations: { destructiveHint: true, openWorldHint: true },
+        async run(args, { client }) {
+            await client.post(`/local-runs/${encodeURIComponent(args.runId)}/cancel`, { reason: args.reason });
+            return "Stopped. Anything already written to your working tree is still there — check `git status`.";
+        },
+    }),
+];

package/dist/src/tools/memory.d.ts

@@ -0,0 +1,12 @@
+import { type ToolDef } from "../registry.js";
+/**
+ * What a project's runs are told, and what they have worked out.
+ *
+ * THE ASYMMETRY IS THE DESIGN. Rules and instructions are writable, because
+ * they are a person's channel to every future run and an agent acting for a
+ * person belongs in it. Memory entries are read-only, because they are Snare's
+ * own record of what happened across real attempts — an agent writing into that
+ * would put invented history into the one place that holds real history, and
+ * afterwards nothing could tell the two apart.
+ */
+export declare const memoryTools: ToolDef[];

package/dist/src/tools/memory.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { bullets, clip, count, label, toolText } from "../format.js";
+import { readOnly, tool, write } from "../registry.js";
+/**
+ * What a project's runs are told, and what they have worked out.
+ *
+ * THE ASYMMETRY IS THE DESIGN. Rules and instructions are writable, because
+ * they are a person's channel to every future run and an agent acting for a
+ * person belongs in it. Memory entries are read-only, because they are Snare's
+ * own record of what happened across real attempts — an agent writing into that
+ * would put invented history into the one place that holds real history, and
+ * afterwards nothing could tell the two apart.
+ */
+export const memoryTools = [
+    tool({
+        name: "list_project_rules",
+        title: "List a project's rules",
+        description: "The standing rules every run on this project is told to follow. Read them before fixing anything here — " +
+            "they are where a team writes down the things that are not obvious from the code.",
+        scope: "projects:memory",
+        toolset: "memory",
+        input: { projectId: z.string() },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/projects/${encodeURIComponent(args.projectId)}/rules`);
+            if (data.rules.length === 0)
+                return "This project has no rules yet.";
+            return toolText(count(data.rules.length, data.total, "rule"), bullets(data.rules.map((rule) => `${rule.enabled ? "" : "(off) "}${rule.body}  [${rule.source.toLowerCase()}, ${rule.id}]`), ""));
+        },
+    }),
+    tool({
+        name: "create_project_rule",
+        title: "Write a rule for future runs",
+        description: "Record something every future run on this project should know — 'the retry wrapper in api/client.ts is " +
+            "load-bearing, do not simplify it'. This is where knowledge from a session survives the session. One " +
+            "sentence, stated as an instruction. Saying the same thing twice updates the existing rule rather than " +
+            "making a second, so you do not have to check first.",
+        scope: "projects:memory",
+        toolset: "memory",
+        input: {
+            projectId: z.string(),
+            body: z.string().min(1).max(2000).describe("One sentence, written as an instruction."),
+        },
+        annotations: write(),
+        async run(args, { client }) {
+            const data = await client.post(`/projects/${encodeURIComponent(args.projectId)}/rules`, { body: args.body });
+            return `Recorded. Every run on this project will be told: ${data.rule.body}`;
+        },
+    }),
+    tool({
+        name: "delete_project_rule",
+        title: "Delete a rule",
+        description: "Remove a standing rule. Get the id from list_project_rules. Be careful with rules somebody else wrote — a " +
+            "rule that looks wrong to you may be the reason something has not broken.",
+        scope: "projects:memory",
+        toolset: "memory",
+        input: { projectId: z.string(), ruleId: z.string() },
+        annotations: { destructiveHint: true, openWorldHint: true },
+        async run(args, { client }) {
+            await client.delete(`/projects/${encodeURIComponent(args.projectId)}/rules`, { ruleId: args.ruleId });
+            return "Deleted. Future runs will not be told it.";
+        },
+    }),
+    tool({
+        name: "get_instructions",
+        title: "Read a project's standing instructions",
+        description: "The free-form brief every run on this project reads before it starts. Longer and less structured than the " +
+            "rules — conventions, architecture notes, things to avoid.",
+        scope: "projects:memory",
+        toolset: "memory",
+        input: { projectId: z.string() },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/projects/${encodeURIComponent(args.projectId)}/instructions`);
+            return data.instructions.trim() || "This project has no standing instructions.";
+        },
+    }),
+    tool({
+        name: "set_instructions",
+        title: "Rewrite a project's standing instructions",
+        description: "REPLACES the whole brief with what you send. Read it with get_instructions first and send the full text " +
+            "back with your changes in it — sending only your addition will delete everything somebody else wrote.",
+        scope: "projects:memory",
+        toolset: "memory",
+        input: {
+            projectId: z.string(),
+            instructions: z.string().max(20_000).describe("The complete document, not an addition to it."),
+        },
+        annotations: { idempotentHint: true, openWorldHint: true },
+        async run(args, { client }) {
+            await client.put(`/projects/${encodeURIComponent(args.projectId)}/instructions`, {
+                instructions: args.instructions,
+            });
+            return "Saved. Every run on this project reads it from now on.";
+        },
+    }),
+    tool({
+        name: "list_memory_entries",
+        title: "What Snare has worked out about this project",
+        description: "Patterns Snare has noticed across its own runs here: files that keep causing bugs, approaches that keep " +
+            "failing, conventions it has learned, and where its confidence has been wrong before. Worth reading before " +
+            "you start — 'the auth middleware has caused three of the last five null-pointer bugs' is worth more than " +
+            "reading the file. Read-only: these are Snare's record of what actually happened, so write a rule instead " +
+            "if you have something to say to future runs.",
+        scope: "projects:memory",
+        toolset: "memory",
+        input: {
+            projectId: z.string(),
+            category: z
+                .enum(["RECURRING_PATTERN", "DEAD_END", "CONVENTION", "CONFIDENCE_CALIBRATION"])
+                .optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const { projectId, ...query } = args;
+            const data = await client.get(`/projects/${encodeURIComponent(projectId)}/memory`, query);
+            if (data.entries.length === 0)
+                return "Snare has not learned anything about this project yet.";
+            return toolText(count(data.entries.length, data.total, "entry", "entries"), 
+            // The count is on the line because it says how much weight to give the
+            // claim: an entry that has mattered eleven times has earned its place,
+            // one at zero is a guess nothing has confirmed since.
+            data.entries
+                .map((entry) => `${label(entry.category)}  (mattered ${entry.relevanceCount}×)\n${clip(entry.content, 400)}`)
+                .join("\n\n"));
+        },
+    }),
+];

package/dist/src/tools/snares.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDef } from "../registry.js";
+export declare const snareTools: ToolDef[];

package/dist/src/tools/snares.js

@@ -0,0 +1,197 @@
+import { z } from "zod";
+import { DASH, bullets, clip, count, label, percent, stamp, toolText } from "../format.js";
+import { snareRun } from "../render.js";
+import { destructive, readOnly, tool, write } from "../registry.js";
+/**
+ * Runs: starting one, watching it, answering it, stopping it.
+ *
+ * TWO OF THESE SPEND MONEY and their descriptions say so in the first sentence,
+ * because a model choosing between tools reads the first sentence. A client
+ * that auto-approves read-only tools must stop at `launch_snare`, which is why
+ * it carries no read-only and no idempotent hint even though calling it twice
+ * is refused upstream.
+ */
+const issueRef = z.string().describe('The issue, as its key ("ACME-142") or its id.');
+export const snareTools = [
+    tool({
+        name: "launch_snare",
+        title: "Start a fix run",
+        description: "Start Snare on an issue in the cloud. THIS SPENDS A SNARE from the workspace's plan and starts an agent " +
+            "against a real repository — check get_usage first if you are not sure there is allowance left. Three modes: " +
+            "FULL is the five-stage loop, LITE is one cheaper pass, INVESTIGATE only finds where the bug lives and " +
+            "changes nothing. Returns immediately with a run id; poll get_snare to see how it goes. To run it on THIS " +
+            "machine with your own model instead, use start_local_snare.",
+        scope: "snares:launch",
+        toolset: "snares",
+        input: {
+            issue: issueRef,
+            mode: z
+                .enum(["FULL", "LITE", "INVESTIGATE"])
+                .optional()
+                .describe("Default FULL. INVESTIGATE is read-only and the right choice when you only want a diagnosis."),
+        },
+        annotations: write(),
+        async run(args, { client }) {
+            const data = await client.post("/snares", args);
+            return toolText(`Started a ${label(data.mode)} run. Run id ${data.snareId ?? DASH}.`, `Watch it at ${data.url}, or poll get_snare with that id.`);
+        },
+    }),
+    tool({
+        name: "get_snare",
+        title: "Check on a run",
+        description: "What a run is doing right now: its stage, its cost, its confidence when it has one, any pull request, and " +
+            "— most importantly — whether it has STOPPED TO ASK something. A run waiting on a question looks exactly " +
+            "like a run that is thinking, so read the first line before concluding it is still working.",
+        scope: "snares:read",
+        toolset: "snares",
+        input: { snareId: z.string() },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/snares/${encodeURIComponent(args.snareId)}`);
+            return snareRun(data.snare);
+        },
+    }),
+    tool({
+        name: "list_snares",
+        title: "List runs",
+        description: "Runs across the workspace, newest first, optionally narrowed to one issue or one status. Use it to answer " +
+            "'what is Snare doing' or 'has anything tried to fix this before'. For one run in detail, use get_snare.",
+        scope: "snares:read",
+        toolset: "snares",
+        input: {
+            issue: issueRef.optional(),
+            projectId: z.string().optional(),
+            status: z
+                .enum([
+                "PENDING",
+                "RUNNING",
+                "SUCCEEDED",
+                "FAILED",
+                "ABORTED_COST_CAP",
+                "ABORTED_ITERATION_CAP",
+                "ABORTED_WALL_CLOCK",
+                "ABORTED_REQUIRES_ESCALATION",
+            ])
+                .optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+            cursor: z.string().optional(),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get("/snares", args);
+            if (data.snares.length === 0)
+                return "No runs match.";
+            return toolText(count(data.snares.length, data.total, "run"), data.snares
+                .map((run) => `${stamp(run.startedAt)}  ${label(run.mode)}  ${label(run.status)}${run.waitingOn ? "  WAITING" : ""}  ` +
+                `${run.confidence !== null ? percent(run.confidence) : DASH}  ${run.issueKey ?? DASH}  ${clip(run.issueTitle, 60)}  run ${run.id}`)
+                .join("\n"), data.nextCursor ? `More: call again with cursor "${data.nextCursor}".` : null);
+        },
+    }),
+    tool({
+        name: "answer_snare_question",
+        title: "Answer a running Snare",
+        description: "Answer the question a run stopped to ask. Snare asks at most one per run, only where the codebase genuinely " +
+            "cannot settle it, and it proceeds on its own guess if nobody replies before the window closes — so " +
+            "answering is the highest-value thing you can do for a waiting run. The question and its id come from " +
+            "get_snare. A closed question is refused rather than silently ignored.",
+        scope: "snares:respond",
+        toolset: "snares",
+        input: {
+            questionId: z.string(),
+            option: z.string().describe("One of the option keys the question offered."),
+        },
+        annotations: write(),
+        async run(args, { client }) {
+            const data = await client.post(`/snare-questions/${encodeURIComponent(args.questionId)}/answer`, { option: args.option });
+            return data.usedDefault
+                ? `Answered, but Snare recorded "${data.answered}" instead — something else answered first.`
+                : `Answered "${data.answered}". The run carries on from there.`;
+        },
+    }),
+    tool({
+        name: "decide_snare_approval",
+        title: "Approve or refuse a risky action",
+        description: "Decide a request from a run that wants to do something Snare stops for: merging directly, deploying, " +
+            "touching CI configuration or secrets, or sending anything outward. THIS IS A REAL DECISION, not a " +
+            "formality — granting it lets the run do the thing. If you are not certain the person who asked you would " +
+            "grant it, say so and let them decide instead. A decision made after the window closes is recorded as late " +
+            "rather than as a grant.",
+        scope: "snares:respond",
+        toolset: "snares",
+        input: {
+            approvalId: z.string(),
+            granted: z.boolean(),
+        },
+        annotations: write(),
+        async run(args, { client }) {
+            const data = await client.post(`/snare-approvals/${encodeURIComponent(args.approvalId)}/decide`, { granted: args.granted });
+            return `Recorded as ${label(data.status)} for: ${data.action}.`;
+        },
+    }),
+    tool({
+        name: "send_snare_directive",
+        title: "Steer a running Snare",
+        description: 'Tell a run something while it is still going — "the bug is actually in the retry wrapper", "do not touch ' +
+            'the auth module". It lands at the next stage boundary. What you write decides what it does: a correction ' +
+            "about what is true sends the run back to explore, a scope change sends it back to plan, anything else is " +
+            "folded in as a note. The response says which it was read as, so check that if you meant to redirect it.",
+        scope: "snares:respond",
+        toolset: "snares",
+        input: {
+            snareId: z.string(),
+            body: z.string().min(1).max(4000),
+        },
+        annotations: write(),
+        async run(args, { client }) {
+            const data = await client.post(`/snares/${encodeURIComponent(args.snareId)}/directives`, { body: args.body });
+            return toolText(`Sent. Read as a ${data.kind.toLowerCase()} instruction${data.rewindTo ? `, which sends the run back to ${label(data.rewindTo)}` : ", which changes no stage"}.`, data.confident
+                ? null
+                : "Nothing in it matched a known instruction shape, so it was treated as a note rather than a correction. Rephrase if you meant to redirect the run.", "It takes effect at the next stage boundary, not immediately.");
+        },
+    }),
+    tool({
+        name: "cancel_snare",
+        title: "Stop a run",
+        description: "Ask a run to stop. It stops at the NEXT STAGE BOUNDARY, not immediately — there is no way to kill a stage " +
+            "mid-flight safely, so the run may report progress for another minute or two before it ends. Do not call " +
+            "this again in that window; it has already been asked.",
+        scope: "snares:respond",
+        toolset: "snares",
+        input: {
+            snareId: z.string(),
+            reason: z.string().max(500).optional(),
+        },
+        annotations: destructive(),
+        async run(args, { client }) {
+            await client.post(`/snares/${encodeURIComponent(args.snareId)}/cancel`, { reason: args.reason });
+            return "Asked it to stop. It will finish the stage it is on first, so give it a minute before checking.";
+        },
+    }),
+    tool({
+        name: "get_pull_request",
+        title: "Read what a run changed",
+        description: "The diff a run produced, with its root cause, the files it touched and the tests it added. Takes either " +
+            "the pull request's id or the run's. Use it to review a fix without a GitHub token of your own — the patch " +
+            "is stored here, so it works even after the branch is gone.",
+        scope: "snares:read",
+        toolset: "snares",
+        input: {
+            id: z.string().describe("A pull request id, or the run id from get_snare."),
+            includeDiff: z.boolean().optional().describe("Default true. Set false for just the summary and file list."),
+        },
+        annotations: readOnly(),
+        async run(args, { client }) {
+            const data = await client.get(`/pull-requests/${encodeURIComponent(args.id)}`);
+            const pr = data.pullRequest;
+            const wantsDiff = args.includeDiff !== false;
+            return toolText(
+            // Which bug this fixes, on the first line, because that is what a
+            // reader needs before they can judge any of the rest.
+            `#${pr.number} (${label(pr.status)}) for ${pr.issueKey ?? pr.issueTitle} — ${pr.url}`, pr.issueKey ? `Fixes: ${pr.issueTitle}` : null, `Summary\n${pr.summary}`, `Root cause\n${pr.rootCause}`, `Files changed\n${bullets(pr.filesTouched, "None.")}`, pr.testsAdded.length > 0 ? `Tests added\n${bullets(pr.testsAdded, "")}` : null, wantsDiff && pr.fileDiffs
+                ? pr.fileDiffs.map((file) => `--- ${file.path}\n${file.patch}`).join("\n\n")
+                : wantsDiff
+                    ? "No stored diff for this pull request — it was opened before diffs were kept."
+                    : null);
+        },
+    }),
+];

package/dist/src/tools/workspace.d.ts

@@ -0,0 +1,12 @@
+import { type ToolDef } from "../registry.js";
+/**
+ * The workspace itself: projects, people, plan limits, and how things are going.
+ *
+ * NOT IN THE DEFAULT SET, and that is a judgement about attention rather than
+ * about value. Somebody debugging reaches for issues and runs on every turn;
+ * they ask what plan they are on roughly never, and a tool schema registered
+ * for that is schema the model reads on every turn instead.
+ */
+export declare const workspaceTools: ToolDef[];
+export declare const setupTools: ToolDef[];
+export declare const feedbackTools: ToolDef[];