@sweny-ai/core 0.1.189 → 0.1.190

package/dist/harness/tool-bridge/protocol.d.ts

@@ -16,7 +16,7 @@
  * same `isError` status.
  */
 import { z } from "zod";
-import type { JSONSchema, Tool, ToolContext } from "../../types.js";
+import { type JSONSchema, type Tool, type ToolContext } from "../../types.js";
 export declare const BRIDGE_PROTOCOL_VERSION = 1;
 /** Frames longer than this are refused and the connection is dropped. */
 export declare const MAX_FRAME_BYTES: number;
@@ -73,7 +73,11 @@ export declare function createFrameReader(onFrame: (value: unknown) => void, onO
 export declare function tokenMatches(expected: string, given: unknown): boolean;
 /** Structural check of an incoming request frame (token checked separately). */
 export declare function parseRequest(value: unknown): BridgeRequest | undefined;
-/** A handler's return value as MCP content. Strings pass through; anything else is JSON. */
+/**
+ * A handler's return value as MCP content. Strings pass through; anything else
+ * is JSON. A {@link ToolRefusal} is a tool error (#544): the agent and the
+ * tool-call status (and so evals) see that the write did not happen.
+ */
 export declare function toolOutputToMcpResult(output: unknown): McpCallToolResult;
 /** A handler's thrown error as an MCP error result. */
 export declare function toolErrorToMcpResult(err: unknown): McpCallToolResult;

package/dist/harness/tool-bridge/protocol.js

@@ -17,6 +17,7 @@
  */
 import { timingSafeEqual } from "node:crypto";
 import { z } from "zod";
+import { isToolRefusal } from "../../types.js";
 export const BRIDGE_PROTOCOL_VERSION = 1;
 /** Frames longer than this are refused and the connection is dropped. */
 export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
@@ -86,8 +87,15 @@ export function parseRequest(value) {
     return value;
 }
 // ─── Tool result shape (shared with the in-process Claude path) ─────
-/** A handler's return value as MCP content. Strings pass through; anything else is JSON. */
+/**
+ * A handler's return value as MCP content. Strings pass through; anything else
+ * is JSON. A {@link ToolRefusal} is a tool error (#544): the agent and the
+ * tool-call status (and so evals) see that the write did not happen.
+ */
 export function toolOutputToMcpResult(output) {
+    if (isToolRefusal(output)) {
+        return { content: [{ type: "text", text: `Refused: ${output.reason}\n${JSON.stringify(output)}` }], isError: true };
+    }
     return {
         content: [{ type: "text", text: typeof output === "string" ? output : JSON.stringify(output) }],
     };

package/dist/journal.d.ts

@@ -47,6 +47,8 @@
  *                    write intents, written before the write stage runs
  *   output:intent    a write is about to be applied (idempotency key + tool)
  *   output:applied   the write returned (key + the ids it produced)
+ *   output:refused   the write's handler returned a refusal (#544): key, its
+ *                    fixed-wording reason and any ids it names; never applied
  *   node:end         final result of the visit and the write-stage counters
  *   route            the edge taken after the visit (null = the run ended), and the rung that chose it
  *   usage            spend of one agent attempt (cumulative; one per model turn that raised it, written
@@ -84,6 +86,15 @@
  * key with a receipt is not re-applied, and a key with an intent but no receipt
  * (the process died between the API call and the receipt) is looked up on the
  * provider by a marker embedded in the body before anything is re-sent.
+ *
+ * A handler that returns a refusal (`ToolRefusal`) gets `output:refused`
+ * instead of `output:applied`. On resume that refusal is replayed as is: the
+ * handler is not called and the provider is not searched (a marked write the
+ * refusal named would otherwise be taken for an applied one). The one
+ * exception is a refusal marked `transient` that names nothing it produced:
+ * nothing was written, so it goes through the unconfirmed-intent path above
+ * (provider lookup, then a first send). `--allow-repeat-writes` does not
+ * override a refusal: its outcome is known, not unconfirmed.
  */
 import type { Logger, NodeResult, NodeUsage, RouteRung, Skill, Workflow } from "./types.js";
 import type { SafeOutputIntent, WriteStageState } from "./safe-outputs.js";
@@ -335,6 +346,8 @@ export interface PlannedVisit {
     rung?: RouteRung;
     /** Writes the checkpointed write stage already applied (receipts in the journal). */
     applied: number;
+    /** Writes whose handler refused (#544): the refusal is replayed, not re-sent. */
+    refused: number;
     /** Writes with an intent but no receipt: checked on the provider before anything is re-sent. */
     unconfirmed: number;
 }
@@ -356,6 +369,8 @@ export interface ResumePlan {
     ends: Map<string, EndRecord>;
     intents: Map<string, OutputRecord>;
     receipts: Map<string, OutputRecord>;
+    /** Writes whose handler refused (`output:refused`, #544): replayed on resume, never taken for applied. */
+    refusals: Map<string, OutputRecord>;
     /** Spend every earlier attempt journaled: the run budget starts here on resume. */
     priorSpend: Spend;
     /**

package/dist/journal.js

@@ -47,6 +47,8 @@
  *                    write intents, written before the write stage runs
  *   output:intent    a write is about to be applied (idempotency key + tool)
  *   output:applied   the write returned (key + the ids it produced)
+ *   output:refused   the write's handler returned a refusal (#544): key, its
+ *                    fixed-wording reason and any ids it names; never applied
  *   node:end         final result of the visit and the write-stage counters
  *   route            the edge taken after the visit (null = the run ended), and the rung that chose it
  *   usage            spend of one agent attempt (cumulative; one per model turn that raised it, written
@@ -84,11 +86,21 @@
  * key with a receipt is not re-applied, and a key with an intent but no receipt
  * (the process died between the API call and the receipt) is looked up on the
  * provider by a marker embedded in the body before anything is re-sent.
+ *
+ * A handler that returns a refusal (`ToolRefusal`) gets `output:refused`
+ * instead of `output:applied`. On resume that refusal is replayed as is: the
+ * handler is not called and the provider is not searched (a marked write the
+ * refusal named would otherwise be taken for an applied one). The one
+ * exception is a refusal marked `transient` that names nothing it produced:
+ * nothing was written, so it goes through the unconfirmed-intent path above
+ * (provider lookup, then a first send). `--allow-repeat-writes` does not
+ * override a refusal: its outcome is known, not unconfirmed.
  */
 import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isToolRefusal } from "./types.js";
 import { resolveNodePermissions } from "./node-policy.js";
 import { CURRENT_SPEC_VERSION } from "./migrations.js";
 import { spendOf } from "./budget.js";
@@ -840,6 +852,7 @@ const RECORD_TYPES = new Set([
     "node:checkpoint",
     "output:intent",
     "output:applied",
+    "output:refused",
     "node:end",
     "route",
     "usage",
@@ -937,6 +950,7 @@ export function checkRecordSequence(records) {
             }
             case "output:intent":
             case "output:applied":
+            case "output:refused":
                 inVisit(r);
                 if (!checkpointed.has(visitKey(r.node, r.iteration))) {
                     bad(r, "records a write before the visit's checkpoint");
@@ -1057,6 +1071,7 @@ export function buildResumePlan(records) {
     const byKey = new Map();
     const intents = new Map();
     const receipts = new Map();
+    const refusals = new Map();
     let attempts = 1;
     let lastStatus;
     let deciderCounters;
@@ -1113,6 +1128,9 @@ export function buildResumePlan(records) {
             case "output:applied":
                 receipts.set(r.key, r);
                 break;
+            case "output:refused":
+                refusals.set(r.key, r);
+                break;
             case "run:end":
                 lastStatus = r.status;
                 break;
@@ -1129,7 +1147,8 @@ export function buildResumePlan(records) {
         const complete = !!v.end && !(isLast && v.end.result.status === "failed" && typeof v.next !== "string");
         const keys = (rec) => [...rec.values()].filter((o) => o.node === v.node && o.iteration === v.iteration).map((o) => o.key);
         const applied = keys(receipts).length;
-        const unconfirmed = keys(intents).filter((k) => !receipts.has(k)).length;
+        const refused = keys(refusals).filter((k) => !receipts.has(k)).length;
+        const unconfirmed = keys(intents).filter((k) => !receipts.has(k) && !refusals.has(k)).length;
         if (complete && !resumed) {
             visits.push({
                 node: v.node,
@@ -1139,6 +1158,7 @@ export function buildResumePlan(records) {
                 next: v.next,
                 ...(v.rung ? { rung: v.rung } : {}),
                 applied,
+                refused,
                 unconfirmed,
             });
             writeState = v.end.write_state;
@@ -1150,6 +1170,7 @@ export function buildResumePlan(records) {
             iteration: v.iteration,
             action: v.checkpoint ? "write-stage" : "rerun",
             applied,
+            refused,
             unconfirmed,
         });
         break;
@@ -1180,6 +1201,7 @@ export function buildResumePlan(records) {
         ends,
         intents,
         receipts,
+        refusals,
         priorSpend: journaledSpend(records),
         unsandboxed: [...new Set(records.filter((r) => r.type === "agent:unsandboxed").map((r) => String(r.node)))],
         ...(start.decider
@@ -1336,6 +1358,14 @@ function slimOutput(o, depth = 0) {
     if (!o || typeof o !== "object" || Array.isArray(o) || depth > 3)
         return null;
     const out = {};
+    // A refusal keeps what it is and its fixed-wording reason (#544); never `detail`.
+    if (depth === 0 && o.refused === true) {
+        out.refused = true;
+        if (isToolRefusal(o))
+            out.reason = o.reason;
+        if (o.transient === true)
+            out.transient = true;
+    }
     for (const [k, v] of Object.entries(o)) {
         if (["number", "identifier", "id", "html_url", "url", "success", "reused"].includes(k)) {
             if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
@@ -1805,6 +1835,12 @@ export class RunJournal {
                     this.logger.info(`  run journal: ${tool.name} already applied before the crash; not re-sent`, { node });
                     return receipt.output ?? null;
                 }
+                const refusal = plan?.refusals.get(key);
+                if (refusal && !retriesRefusal(refusal.output)) {
+                    this.logger.info(`  run journal: ${tool.name} was refused in an earlier attempt; not re-sent`, { node });
+                    const prior = refusal.output && typeof refusal.output === "object" ? refusal.output : {};
+                    return { reason: "the tool refused the write", ...prior, refused: true };
+                }
                 const replayingStage = !!plan?.checkpoints.has(visitKey(node, iteration));
                 const pending = plan?.intents.has(key) === true;
                 if (pending || replayingStage) {
@@ -1826,12 +1862,30 @@ export class RunJournal {
                 // A write the journal cannot record is never sent: append throws first.
                 this.append("output:intent", { node, iteration, key, tool: tool.name });
                 const output = await tool.handler(withMarker(tool.name, args, key), ctx);
-                this.append("output:applied", { node, iteration, key, tool: tool.name, output: slimOutput(output) });
+                const refused = !!output && typeof output === "object" && output.refused === true;
+                this.append(refused ? "output:refused" : "output:applied", {
+                    node,
+                    iteration,
+                    key,
+                    tool: tool.name,
+                    output: slimOutput(output),
+                });
                 return output;
             },
         };
     }
 }
+/**
+ * Whether a journaled refusal is tried again on resume (#544): only a
+ * transient one that names nothing it produced. Anything else stands.
+ */
+function retriesRefusal(output) {
+    if (!output || typeof output !== "object")
+        return false;
+    const o = output;
+    // Anything besides the refusal itself is something the write produced.
+    return o.transient === true && Object.keys(o).every((k) => k === "refused" || k === "reason" || k === "transient");
+}
 /** What a node result needs to continue a run. Tool call inputs and outputs are dropped. */
 function journalResult(r) {
     return {

package/dist/safe-outputs.d.ts

@@ -114,7 +114,7 @@ export interface ApplySafeOutputsOptions {
 }
 export interface ApplySafeOutputsResult {
     receipts: SafeOutputReceipt[];
-    /** Set when an apply call failed; the node fails with it. */
+    /** Set when an apply call failed or its handler refused (a `ToolRefusal`); the node fails with it. */
     error?: string;
 }
 /** Check, then apply (or stage) one node's intents. See the module comment for the order of checks. */

package/dist/safe-outputs.js

@@ -15,7 +15,7 @@
  */
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { SAFE_OUTPUT_APPLIERS } from "./types.js";
+import { SAFE_OUTPUT_APPLIERS, isToolRefusal } from "./types.js";
 /** Name of the intent-recording tool a node with `outputs` receives. */
 export const EMIT_OUTPUT_TOOL = "emit_output";
 /** Longest title the write stage accepts (after the prefix). */
@@ -574,7 +574,22 @@ export async function applySafeOutputs(o) {
             });
             const ref = refOf(output);
             const url = urlOf(output);
-            receipts[index] = { ...receipts[index], ...(ref !== undefined ? { ref } : {}), ...(url ? { url } : {}) };
+            const produced = { ...(ref !== undefined ? { ref } : {}), ...(url ? { url } : {}) };
+            const refused = !!output && typeof output === "object" && output.refused === true;
+            if (refused) {
+                // #544: the handler declined the write, or could not vouch for it. The
+                // receipt says refused with the handler's fixed-wording reason (and
+                // names anything it did create); the node fails and the rest are
+                // skipped, the same as a failed apply. A refusal without a usable
+                // reason still counts as one.
+                const reason = isToolRefusal(output) ? output.reason.slice(0, 200) : "the tool refused the write";
+                receipts[index] = { ...receipts[index], ...produced, status: "refused", reason };
+                for (const rest of accepted.slice(n + 1)) {
+                    receipts[rest.index] = { ...receipts[rest.index], status: "skipped", reason: "an earlier write was refused" };
+                }
+                return { receipts, error: `safe output ${write.type} via ${write.via} was refused: ${reason}` };
+            }
+            receipts[index] = { ...receipts[index], ...produced };
             o.logger.info(`  safe output: ${write.type} via ${write.via} applied${ref !== undefined ? ` (${ref})` : ""}`, {
                 node: o.nodeId,
             });

package/dist/skills/git-push.d.ts

@@ -110,6 +110,12 @@ export interface PushHeadResult {
     attempted: boolean;
     /** Why nothing was pushed, or why the push failed. Never carries the token. */
     reason?: string;
+    /**
+     * The local commit the push tried to publish. Set when the push ran and
+     * failed: `github_create_pr` then opens the PR only if the remote head is
+     * this commit (#544).
+     */
+    sha?: string;
 }
 /** `owner/repo` from a GitHub remote URL (https, ssh or scp form), lowercased, or undefined. */
 export declare function repoFromRemote(url: string): {

package/dist/skills/git-push.js

@@ -459,7 +459,7 @@ export async function pushHeadBranch(opts) {
         ], pushEnv);
         if (r.code !== 0) {
             const why = (r.stderr || r.stdout).trim().split("\n").at(-1) ?? "";
-            return { pushed: false, attempted: true, reason: `git push failed: ${redact(why, token)}` };
+            return { pushed: false, attempted: true, reason: `git push failed: ${redact(why, token)}`, sha };
         }
         return { pushed: true, attempted: true };
     }

package/dist/skills/github.d.ts

@@ -19,12 +19,13 @@ export declare function githubApiBase(apiUrl: string | undefined): string;
  * remotely is pushed with an empty lease (it must still not exist). One that
  * exists is pushed only when it is unprotected and already has an open PR from
  * this repo into `base`, leased on the sha the API returned. Any API failure
- * means no push.
+ * means no push. A skip carries the remote head sha when the API returned one.
  */
 export declare function headPushLease(repo: string, head: string, base: string, ctx: ToolContext): Promise<{
     remoteSha: string;
 } | {
     skip: string;
+    remoteSha?: string;
 }>;
 /**
  * Encode an LLM-chosen repo file path for safe interpolation into a

package/dist/skills/github.js

@@ -56,7 +56,7 @@ async function gh(path, ctx, init) {
  * remotely is pushed with an empty lease (it must still not exist). One that
  * exists is pushed only when it is unprotected and already has an open PR from
  * this repo into `base`, leased on the sha the API returned. Any API failure
- * means no push.
+ * means no push. A skip carries the remote head sha when the API returned one.
  */
 export async function headPushLease(repo, head, base, ctx) {
     const branch = head.replace(/^refs\/heads\//, "");
@@ -76,7 +76,7 @@ export async function headPushLease(repo, head, base, ctx) {
         return { skip: `cannot check head ${branch} on ${repo}: no branch sha in the API answer` };
     }
     if (info.protected !== false)
-        return { skip: `head ${branch} exists on ${repo} and is protected` };
+        return { skip: `head ${branch} exists on ${repo} and is protected`, remoteSha: sha };
     const owner = repo.split("/")[0];
     let open;
     try {
@@ -85,13 +85,45 @@ export async function headPushLease(repo, head, base, ctx) {
     catch (err) {
         return {
             skip: `cannot check open PRs for ${branch} on ${repo}: ${err instanceof Error ? err.message : String(err)}`,
+            remoteSha: sha,
         };
     }
     if (!Array.isArray(open) || open.length === 0) {
-        return { skip: `head ${branch} already exists on ${repo} with no open PR into ${target}` };
+        return { skip: `head ${branch} already exists on ${repo} with no open PR into ${target}`, remoteSha: sha };
     }
     return { remoteSha: sha };
 }
+const SHA = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+// Fixed-wording refusal reasons for `github_create_pr` (#544). Receipts and PR
+// comments carry these; shas and upstream errors go in the result's `detail`.
+const REFUSE_NO_LOCAL = "the head push failed and the pusher did not report the local commit";
+const REFUSE_UNREADABLE = "the head push failed and the remote head could not be read";
+const REFUSE_MISMATCH = "the head push failed and the remote head is not the commit this run produced";
+const REFUSE_PR_MISMATCH = "the PR was opened but its head is not the commit this run produced";
+const REFUSE_PR_UNVERIFIED = "the PR was opened but its head commit could not be verified";
+/**
+ * The sha the remote `head` branch points at, read through the API (#544), or
+ * an error. A missing branch is `{ sha: null }`; anything unreadable is an error,
+ * so the caller fails closed.
+ */
+async function remoteHeadSha(repo, head, ctx) {
+    const branch = head.replace(/^refs\/heads\//, "");
+    const seg = branch.split("/").map(encodeURIComponent).join("/");
+    let ref;
+    try {
+        ref = (await gh(`/repos/${repo}/git/ref/heads/${seg}`, ctx));
+    }
+    catch (err) {
+        if (err instanceof GitHubApiError && err.status === 404)
+            return { sha: null };
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    const sha = ref?.object?.sha;
+    if (ref?.ref !== `refs/heads/${branch}` || typeof sha !== "string" || !SHA.test(sha)) {
+        return { error: "no matching ref in the API answer" };
+    }
+    return { sha };
+}
 function isAlreadyExistsError(err) {
     if (!(err instanceof GitHubApiError) || err.status !== 422)
         return false;
@@ -280,6 +312,10 @@ export const github = {
             handler: async (input, ctx) => {
                 let pr;
                 let reused = false;
+                // The remote head this run saw, for the result (#544).
+                let observedHead;
+                // Set after sweny's own push failed: the PR's head must be this commit (#544).
+                let mustHead;
                 // #473: push the head branch from sweny with this skill's token, so the
                 // recommended `persist-credentials: false` checkout still ships the
                 // branch and the agent never holds a write token. Skipped unless the
@@ -307,12 +343,49 @@ export const github = {
                             remoteSha: lease.remoteSha,
                             token: ctx.config.GITHUB_TOKEN,
                         });
+                    if (lease.remoteSha)
+                        observedHead = lease.remoteSha;
                     if ("skip" in lease)
                         ctx.logger?.warn?.(`  github_create_pr: not pushing: ${lease.skip}`);
                     else if (push.pushed)
                         ctx.logger?.info?.(`  github_create_pr: pushed ${input.head} to ${input.repo}`);
-                    else if (push.attempted)
-                        ctx.logger?.warn?.(`  github_create_pr: ${push.reason}; requesting the PR anyway`);
+                    else if (push.attempted) {
+                        // #544: a push sweny ran and that failed. The PR would publish
+                        // whatever the remote branch holds, so open it only when that is
+                        // the commit this run would have pushed. Anything else, or a
+                        // remote head that cannot be read, refuses.
+                        const local = typeof push.sha === "string" && SHA.test(push.sha) ? push.sha : null;
+                        const remote = local ? await remoteHeadSha(input.repo, input.head, ctx) : undefined;
+                        const remoteSha = remote && "sha" in remote ? remote.sha : null;
+                        if (!local || !remoteSha || remoteSha !== local) {
+                            const [reason, why] = !local
+                                ? [REFUSE_NO_LOCAL, "the pusher did not report the local commit"]
+                                : remote && "error" in remote
+                                    ? [REFUSE_UNREADABLE, `cannot read the remote head of ${input.head}: ${remote.error}`]
+                                    : remoteSha
+                                        ? [
+                                            REFUSE_MISMATCH,
+                                            `the remote head of ${input.head} is ${remoteSha}, not the local commit ${local}`,
+                                        ]
+                                        : [REFUSE_MISMATCH, `${input.head} does not exist on ${input.repo}; the local commit is ${local}`];
+                            const detail = `sweny's push failed (${push.reason}) and ${why}`;
+                            ctx.logger?.warn?.(`  github_create_pr: refusing to open the PR: ${detail}`);
+                            const refusal = {
+                                refused: true,
+                                reason,
+                                detail,
+                                // A ref read that failed may succeed later; nothing was written.
+                                ...(reason === REFUSE_UNREADABLE ? { transient: true } : {}),
+                                head: input.head,
+                                local_sha: local,
+                                remote_sha: remoteSha,
+                            };
+                            return refusal;
+                        }
+                        observedHead = remoteSha;
+                        mustHead = local;
+                        ctx.logger?.warn?.(`  github_create_pr: ${push.reason}; the remote head is already the local commit ${local}, requesting the PR`);
+                    }
                     else
                         ctx.logger?.debug?.(`  github_create_pr: no sweny-side push (${push.reason})`);
                 }
@@ -347,6 +420,29 @@ export const github = {
                     pr = existing;
                     reused = true;
                 }
+                // #544: the remote could move between the ref read and the request. The
+                // PR exists now; it is not closed (that would be another write nobody
+                // asked for), but the result refuses to vouch for it.
+                const prHead = pr.head?.sha;
+                const prHeadSha = typeof prHead === "string" && SHA.test(prHead) ? prHead : null;
+                if (mustHead && prHeadSha !== mustHead) {
+                    const detail = prHeadSha
+                        ? `the PR's head is ${prHeadSha}, not the local commit ${mustHead}`
+                        : `GitHub did not report the PR's head commit; the local commit is ${mustHead}`;
+                    ctx.logger?.warn?.(`  github_create_pr: ${pr.html_url ?? `#${pr.number}`} is not verified: ${detail}`);
+                    const refusal = {
+                        refused: true,
+                        reason: prHeadSha ? REFUSE_PR_MISMATCH : REFUSE_PR_UNVERIFIED,
+                        detail,
+                        ...(pr.number !== undefined ? { number: pr.number } : {}),
+                        ...(pr.html_url ? { html_url: pr.html_url } : {}),
+                        ...(reused ? { reused: true } : {}),
+                        head: input.head,
+                        local_sha: mustHead,
+                        remote_sha: prHeadSha,
+                    };
+                    return refusal;
+                }
                 try {
                     if (pr.number && !reused) {
                         await gh(`/repos/${input.repo}/issues/${pr.number}/labels`, ctx, {
@@ -364,7 +460,10 @@ export const github = {
                     const msg = err instanceof Error ? err.message : String(err);
                     ctx.logger?.warn?.(`  github_create_pr: label POST failed for ${pr.html_url ?? `#${pr.number}`} — ${msg}`);
                 }
-                return reused ? { ...pr, reused: true } : pr;
+                // The head the PR was opened from: GitHub's answer, else the remote head this run read.
+                const headSha = prHeadSha ?? observedHead;
+                const out = headSha ? { ...pr, head_sha: headSha } : pr;
+                return reused ? { ...out, reused: true } : out;
             },
         },
         {

package/dist/types.d.ts

@@ -48,6 +48,11 @@ export type BranchPusher = (opts: {
     pushed: boolean;
     attempted: boolean;
     reason?: string;
+    /**
+     * The local commit the push tried to publish. Set when a push was attempted
+     * and failed, so the caller can check what the remote head holds (#544).
+     */
+    sha?: string;
 }>;
 /**
  * Side-effect class of a tool. `"read"` only reads. `"write"` can change
@@ -68,6 +73,32 @@ export interface Tool {
     access?: ToolAccess;
     handler: (input: any, ctx: ToolContext) => Promise<unknown>;
 }
+/**
+ * A write handler's structured refusal: it declined the write, or could not
+ * vouch for what it wrote, and says why. Returned, not thrown, so the caller
+ * keeps the details. `refused: true` is the same flag a refused node result
+ * carries (`data: { error, refused: true }`). The write stage records it as
+ * refused, never applied (#544).
+ *
+ * `reason` is fixed wording chosen by the handler, never model, agent or
+ * remote text: receipts and PR comments carry it. Specifics (shas, branch
+ * names, upstream errors) go in `detail` and other fields, which only the
+ * tool result carries. A refusal may still name what exists (`number`,
+ * `html_url`) when the write happened but could not be verified.
+ */
+export interface ToolRefusal {
+    refused: true;
+    reason: string;
+    detail?: string;
+    /**
+     * The refusal may not hold on a later try (an upstream read failed) and
+     * nothing was written. Only such a refusal is tried again when a run is
+     * resumed; any other refusal is final for the run.
+     */
+    transient?: boolean;
+}
+/** Whether a tool handler's output is a {@link ToolRefusal}. */
+export declare function isToolRefusal(output: unknown): output is ToolRefusal;
 /** Config field declaration — skills say what they need */
 export interface ConfigField {
     description: string;

package/dist/types.js

@@ -4,6 +4,13 @@ export { WORKFLOW_INPUT_TYPES } from "./inputs.js";
  * something outside the run: create, update, delete, post, send, invoke.
  */
 export const TOOL_ACCESS = ["read", "write"];
+/** Whether a tool handler's output is a {@link ToolRefusal}. */
+export function isToolRefusal(output) {
+    if (!output || typeof output !== "object" || Array.isArray(output))
+        return false;
+    const o = output;
+    return o.refused === true && typeof o.reason === "string" && o.reason.length > 0;
+}
 /**
  * Skill categories: used for per-node validation and grouping.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.189",
+  "version": "0.1.190",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"