@bevel-software/platform-core-backend 0.26.0 → 0.27.0

package/src/modules/tool-helpers/route-tool-schemas.ts

@@ -0,0 +1,171 @@
+import { logger } from '../../shared/logging.js';
+import type { JsonSchema } from '../tool-registry/tool.contract.js';
+
+const log = logger('tools');
+
+/**
+ * What a route-hosted tool declared about its own arguments, so the route that
+ * hosts it can check a call against it.
+ *
+ * Written by {@link declareRouteTool} — which `toolDef` calls for every tool it
+ * builds, the platform's own and a deployment's alike — and read by the tool
+ * handler. That is what makes the check free for a deployment: it declares its
+ * tool exactly as it does today and its route refuses a call that does not
+ * match, with no code of its own.
+ *
+ * Keyed by the ROUTE the tool is hosted at (its `toolDef` `path`), so the
+ * handler finds the schema from the request path alone, without every module
+ * having to hand it over a second time — and a tool whose route does not end
+ * in its name (`my_plugin` is `POST /api/plugins/personal`) is found all
+ * the same. Also readable by tool name, for the tests.
+ */
+export interface RouteToolSchemas {
+  /** The tool's name: what the refusal calls it. */
+  name: string;
+  /** The route it is hosted at, e.g. `/api/agent/tools/grep`. */
+  path: string;
+  /**
+   * The LOGICAL (flat) schema: what the handler receives as `args`, and what a
+   * script calling `POST /api/agent/tools/<name>` sends as its JSON body. The
+   * arguments are checked against this one.
+   */
+  flat: JsonSchema;
+  /**
+   * The WIRE schema: the flat one inside the `{ body: … }` envelope, which is
+   * what an agent passes over MCP or inside a chain. Only the call example in a
+   * refusal is generated from it — so the line the agent is invited to copy is
+   * the line it would actually type.
+   */
+  wire: JsonSchema;
+  /**
+   * Arguments this tool refuses BY NAME ITSELF, with a message of its own — so
+   * the generic check says nothing about them and that message is what the
+   * caller reads. `create_branch`'s `name` is one: it answers
+   * `name-required`, which says what the name is for.
+   */
+  refusesItself: ReadonlySet<string>;
+}
+
+/**
+ * What every route-hosted tool declared, by the last segment of its route and
+ * then by the whole route. Process-wide, because the declarations are made by
+ * CODE — a module's or a deployment's `toolDef` — which is the same for every
+ * tenant a process serves: two tenants mount the same tools with the same
+ * arguments. A route re-declared with DIFFERENT arguments would break that, so
+ * it is logged (once per route) rather than passing silently.
+ */
+const byLastSegment = new Map<string, RouteToolSchemas[]>();
+/** Tool name → its declaration. */
+const byName = new Map<string, RouteToolSchemas>();
+/** Routes already reported as re-declared with other arguments. */
+const conflicting = new Set<string>();
+
+/** A route path as declarations and requests are compared: no query, no trailing slash. */
+function normalizePath(path: string): string {
+  const withoutQuery = path.split('?')[0] ?? '';
+  return withoutQuery.length > 1 ? withoutQuery.replace(/\/+$/, '') : withoutQuery;
+}
+
+/** Does this flat input schema require any argument at all? */
+function requiresAnything(inputs: JsonSchema): boolean {
+  const required = (inputs as { required?: unknown }).required;
+  return Array.isArray(required) && required.length > 0;
+}
+
+/**
+ * The flat inputs inside the `body` envelope every module-hosted tool advertises
+ * — the only standard-http way to ride multiple fields in a JSON body.
+ *
+ * The envelope is required only when something inside it is. A tool whose flat
+ * inputs are all optional is legitimately called as `Bevel.<name>({})` — agents
+ * have always called `list_branches` and `start_session` that way, and the
+ * endpoint reads `req.body` as `{}` either way — so declaring `body` required
+ * would make the schema disagree with the tool, and a check must never refuse a
+ * call the tool accepts.
+ */
+export function bodyEnvelope(inputs: JsonSchema): JsonSchema {
+  return {
+    type: 'object',
+    properties: { body: inputs },
+    ...(requiresAnything(inputs) ? { required: ['body'] } : {}),
+    additionalProperties: false,
+  } as JsonSchema;
+}
+
+/**
+ * Record what the route-hosted tool `name` takes, and answer with the wire
+ * schema its def must advertise.
+ *
+ * `toolDef` calls this for every tool it builds, so declaring a tool IS
+ * declaring its arguments to the check. A module that builds its def lazily
+ * (the skill tools rebuild theirs per catalog listing, to name the skills that
+ * exist now) calls it once at registration as well, so a direct REST call that
+ * lands before the first catalog listing is checked too.
+ *
+ * Idempotent in effect: a tool whose def is rebuilt re-declares the same
+ * arguments, and the last declaration for a name is the one in force.
+ */
+export function declareRouteTool(
+  name: string,
+  inputs: JsonSchema,
+  refusesItself: readonly string[] = [],
+  path = `/api/agent/tools/${name}`,
+): JsonSchema {
+  const wire = bodyEnvelope(inputs);
+  if (!name) return wire;
+  const route = normalizePath(path);
+  const entry: RouteToolSchemas = { name, path: route, flat: inputs, wire, refusesItself: new Set(refusesItself) };
+  const segment = routeToolName(route);
+  const same = (byLastSegment.get(segment) ?? []).filter((e) => e.path !== route);
+  const previous = (byLastSegment.get(segment) ?? []).find((e) => e.path === route);
+  if (previous && !conflicting.has(route) && JSON.stringify(previous.flat) !== JSON.stringify(inputs)) {
+    conflicting.add(route);
+    log.warn(`the route "${route}" was declared again with other arguments; calls are checked against the latest.`);
+  }
+  byLastSegment.set(segment, [...same, entry]);
+  byName.set(name, entry);
+  return wire;
+}
+
+/** What the tool named `name` takes, or `undefined` when nothing declared it. */
+export function routeToolSchemas(name: string): RouteToolSchemas | undefined {
+  return byName.get(name);
+}
+
+/**
+ * What the tool hosted at the route a request arrived on takes, or
+ * `undefined` when no tool is declared there. `requestPath` is the request's
+ * WHOLE path (`req.originalUrl`): it ends with the declared route whatever
+ * the app is mounted under — a tenant's loopback prefix included.
+ */
+export function routeToolSchemasForRequest(requestPath: string): RouteToolSchemas | undefined {
+  const path = normalizePath(requestPath);
+  const candidates = byLastSegment.get(routeToolName(path)) ?? [];
+  // The route that fits the request BEST wins, not the first one declared: an
+  // exact match, then the longest declared route the path ends with, so
+  // `/api/foo` is never checked against a `/foo` declared before it. A path
+  // shorter than every declaration (a test mounting a route bare) comes last.
+  const exact = candidates.find((e) => path === e.path);
+  if (exact) return exact;
+  const longest = (list: RouteToolSchemas[]): RouteToolSchemas | undefined =>
+    [...list].sort((a, b) => b.path.length - a.path.length)[0];
+  return (
+    longest(candidates.filter((e) => path.endsWith(e.path))) ??
+    longest(candidates.filter((e) => e.path.endsWith(path)))
+  );
+}
+
+/**
+ * The tool a request to `/api/agent/tools/<name>` is for: the last segment of
+ * the path, query and trailing slash left out.
+ *
+ * Read off the path rather than taken as a parameter, because the path is the
+ * only thing every mounting style agrees on — the modules mount their routes on
+ * a router at `/api`, the tests mount theirs wherever they like, and a
+ * deployment mounts its own.
+ */
+export function routeToolName(path: string): string {
+  const withoutQuery = path.split('?')[0] ?? '';
+  const segments = withoutQuery.split('/').filter((s) => s.length > 0);
+  return segments[segments.length - 1] ?? '';
+}

package/src/modules/tool-helpers/tool-def.ts

@@ -2,6 +2,7 @@ import '@utcp/http';
 import { HttpCallTemplateSerializer } from '@utcp/http';
 import { ToolSerializer } from '@utcp/sdk';
 import type { JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
+import { declareRouteTool } from './route-tool-schemas.js';
 
 const httpTemplate = new HttpCallTemplateSerializer();
 const toolSerializer = new ToolSerializer();
@@ -18,9 +19,99 @@ export const BRANCH_INPUT: JsonSchema = {
   description: 'The branch (draft) whose workspace this operates on — pass the branch you are currently working on.',
 };
 
+/**
+ * The optional `branch` of a tool that declares `defaults-to-default-branch`:
+ * the same input, saying what happens without it.
+ */
+export const DEFAULTED_BRANCH_INPUT: JsonSchema = {
+  type: 'string',
+  minLength: 1,
+  description:
+    "Optional: the branch (draft) to read. Without it the call runs on the deployment's default branch, " +
+    "and the answer's `branch` field names that branch.",
+};
+
+/**
+ * How a tool treats its `branch` input — the declaration the tool handler
+ * resolves the branch from, once, before the tool runs:
+ *
+ *  - `required`: the call must name a branch. A call without one, or with an
+ *    empty or non-string one, is refused with the `branch-required` refusal
+ *    and the tool does not run. The default for a tool whose inputs require
+ *    `branch`.
+ *  - `defaults-to-default-branch`: a call without a branch runs on the
+ *    deployment's default branch, and an object answer without a `branch`
+ *    field gets one naming it. An empty or non-string branch is still refused:
+ *    only an ABSENT one is defaulted. Read-only tools only — a writing tool
+ *    declaring it fails at startup, since its write would land on the default
+ *    branch without the caller having named it.
+ *
+ * A tool that declares neither, and whose inputs have no `branch`, takes no
+ * branch.
+ *
+ * Under both declarations a branch that is given must exist: one that does not
+ * is answered 404 naming it, before the tool runs. The tool reads the resolved
+ * name from `ctx.branch` — or from `args.branch`, which the handler overwrites
+ * with it — and never sees a missing, empty or non-string one.
+ */
+export type BranchDeclaration = 'required' | 'defaults-to-default-branch';
+
+/**
+ * What the tool handler does with a call's `branch`: a {@link BranchDeclaration},
+ * `none` for a tool that takes no branch, or `own` for a tool with an OPTIONAL
+ * `branch` and no declaration (the platform's skill tools, `list_tool_setup`)
+ * — such a tool keeps its own handling of an absent branch, and gets only the
+ * 404 for a named branch that does not exist.
+ */
+export type BranchHandling = BranchDeclaration | 'none' | 'own';
+
+/**
+ * Every route path a `toolDef` was built for, with how its branch is handled.
+ * Kept here rather than on the registry so the tool handler finds a tool's
+ * declaration from its route alone: a deployment's tool is covered by building
+ * its def with `toolDef` and mounting its route with `toolHandler`, as it
+ * already does, with nothing in between to keep in step.
+ */
+const branchHandlingByPath = new Map<string, BranchHandling>();
+
+/** How the tool hosted at `path` treats its branch; `undefined` for a route no `toolDef` described. */
+export function branchHandlingFor(path: string): BranchHandling | undefined {
+  return branchHandlingByPath.get(path);
+}
+
+type ObjectSchema = { properties?: Record<string, JsonSchema>; required?: string[] };
+
+/** A tool's branch handling read off inputs that carry no declaration. */
+function inferBranchHandling(inputs: JsonSchema): BranchHandling {
+  const o = inputs as ObjectSchema;
+  if ((o.required ?? []).includes('branch')) return 'required';
+  return o.properties && 'branch' in o.properties ? 'own' : 'none';
+}
+
+/**
+ * The input schema with `branch` as `declaration` says: required, or optional
+ * with the sentence about the default. A tool that declares its own `branch`
+ * property with its own meaning (a fork base, a switch target) keeps that
+ * property under `required`.
+ */
+export function withBranchDeclaration(inputs: JsonSchema, declaration: BranchDeclaration): JsonSchema {
+  const o = inputs as ObjectSchema;
+  const properties = { ...(o.properties ?? {}) };
+  const others = (o.required ?? []).filter((r) => r !== 'branch');
+  if (declaration === 'required') {
+    properties.branch = properties.branch ?? BRANCH_INPUT;
+    return { ...inputs, properties, required: [...others, 'branch'] } as JsonSchema;
+  }
+  properties.branch = DEFAULTED_BRANCH_INPUT;
+  const out = { ...inputs, properties } as ObjectSchema;
+  if (others.length > 0) out.required = others;
+  else delete out.required;
+  return out as JsonSchema;
+}
+
 /** Add a required `branch` property to an object input schema (KB tools). */
 export function withBranchInput(inputs: JsonSchema): JsonSchema {
-  const o = inputs as { properties?: Record<string, JsonSchema>; required?: string[] };
+  const o = inputs as ObjectSchema;
   return {
     ...inputs,
     properties: { ...(o.properties ?? {}), branch: BRANCH_INPUT },
@@ -38,6 +129,26 @@ export interface ToolDefSpec {
   tags?: string[];
   /** The route the owning module hosts, e.g. `/agent/tools/list_branches`. */
   path: string;
+  /**
+   * Arguments this tool's own handler refuses by name, with a message of its
+   * own. The generic argument check its route runs then says nothing about
+   * them, so that message is what the caller reads — which is the point of
+   * having written it. A missing `branch` needs no entry here: the route
+   * check leaves a call that names no branch to `branch-required`.
+   */
+  refusesItself?: string[];
+  /**
+   * How the tool treats `branch` — see {@link BranchDeclaration}. Given, the
+   * `branch` input is added to `inputs` to match. Omitted, a tool whose
+   * `inputs` require `branch` is `required`, and one without `branch` takes
+   * no branch.
+   */
+  branch?: BranchDeclaration;
+  /**
+   * The tool writes. A `write` tag says the same. A writing tool cannot
+   * declare `defaults-to-default-branch`.
+   */
+  write?: boolean;
 }
 
 /**
@@ -48,17 +159,31 @@ export interface ToolDefSpec {
  * as the flat args. The URL + bearer are `${API_URL}` / `${CONNECTION_KEY}`
  * placeholders the consumer resolves (public URL + key for external; loopback +
  * internal token for our agent), so one def serves both surfaces.
+ *
+ * Also records the tool's branch handling for its route, which is what the
+ * tool handler mounted on that route resolves the branch from. Throws — at
+ * startup, where defs are built — for a writing tool that declares
+ * `defaults-to-default-branch`.
  */
 export function toolDef(spec: ToolDefSpec): UtcpTool {
+  if (spec.branch === 'defaults-to-default-branch' && (spec.write || (spec.tags ?? []).includes('write'))) {
+    throw new Error(
+      `Tool "${spec.name}" writes, so it cannot declare branch: 'defaults-to-default-branch' — a write must ` +
+        "name its branch. Declare branch: 'required' instead.",
+    );
+  }
+  const inputs = spec.branch ? withBranchDeclaration(spec.inputs, spec.branch) : spec.inputs;
+  branchHandlingByPath.set(spec.path, spec.branch ?? inferBranchHandling(inputs));
+  // Declaring the tool IS declaring its arguments to the check that its route
+  // runs, which is why the envelope comes back from the declaration rather than
+  // being built here: a tool declared with this helper — the platform's own and
+  // a deployment's alike — refuses a call whose arguments do not match it on
+  // every way in, the REST route included, with no code of its own.
+  const wire = declareRouteTool(spec.name, inputs, spec.refusesItself, spec.path);
   return toolSerializer.validateDict({
     name: spec.name,
     description: spec.description,
-    inputs: {
-      type: 'object',
-      properties: { body: spec.inputs },
-      required: ['body'],
-      additionalProperties: false,
-    },
+    inputs: wire,
     outputs: spec.outputs ?? { type: 'object', properties: {} },
     tags: spec.tags ?? [],
     tool_call_template: httpTemplate.validateDict({

package/src/modules/tool-helpers/tool-handler.ts

@@ -3,9 +3,16 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('tools');
 import { hasHttpStatus, ToolError, type ToolHandler } from './tool.contract.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import {
+  assertBranchProvided,
+  BranchNotFoundError,
+  DefaultBranchUnsetError,
+  WorkflowDomainError,
+} from '../../shared/domain-errors.js';
+import { branchHandlingFor, type BranchHandling } from './tool-def.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import type { ResolveToolContext } from './tool-context.js';
+import { argumentsRefusal } from './route-argument-check.js';
 import { alwaysWritable, READ_ONLY_CODE, refuseWriteTool, type IWriteAccess } from '../write-access/write-access.js';
 import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
 
@@ -20,18 +27,130 @@ function isAsyncIterable(v: unknown): v is AsyncIterable<unknown> {
 export interface ToolHandlerOptions {
   /** Mutating tool — refuse read-scoped callers up front (defense in depth). */
   write?: boolean;
+  /**
+   * Refuse read-scoped callers up front WITHOUT making the tool a write: the
+   * read-only-deployment gate below is not applied. For a tool a read-only
+   * credential may not use that is nonetheless a read — `request_file_download`
+   * takes bytes out, so a read-only deployment must still serve it.
+   */
+  writeScope?: boolean;
+  /**
+   * How this route treats `branch`, when it must differ from what its
+   * `toolDef` recorded. Only `execute_command` sets it (`own`): it falls back
+   * to an internal caller's focused branch rather than being refused.
+   */
+  branch?: BranchHandling;
+}
+
+/**
+ * What the tool handler needs to know about branches, asked at call time so a
+ * default branch renamed in the settings is the next call's default.
+ */
+export interface ToolBranchPort {
+  /** The deployment's default branch; `''` until one is configured. */
+  defaultBranch(): string;
+  /**
+   * True only when `branch` certainly does not exist. Creates no workspace
+   * and clones nothing. A name it cannot judge — malformed, or a remote it
+   * could not ask — is `false`: opening the branch then answers for it.
+   */
+  isMissing(branch: string): Promise<boolean>;
+}
+
+/**
+ * Refuse a branch that certainly does not exist. A fault while finding out —
+ * a storage error reading the workspaces root, say — is logged here in full
+ * and answered as a 500 that names the branch and nothing else: its message
+ * would carry the deployment's paths to the caller.
+ */
+async function assertBranchExists(branch: string, branches: ToolBranchPort | undefined): Promise<void> {
+  let missing: boolean | undefined;
+  try {
+    missing = await branches?.isMissing(branch);
+  } catch (err) {
+    log.error('branch existence check failed:', { branch, err });
+    throw new ToolError(`Could not check whether branch ${branch} exists.`, 500);
+  }
+  if (missing) throw new BranchNotFoundError(branch);
+}
+
+/**
+ * The branch a call runs on, from the tool's handling and the call's
+ * arguments — or the refusal. `defaulted` says the caller named none.
+ */
+async function resolveBranch(
+  handling: BranchHandling,
+  args: Record<string, unknown>,
+  branches: ToolBranchPort | undefined,
+): Promise<{ branch: string; defaulted: boolean } | null> {
+  if (handling === 'none') return null;
+  const given = args.branch;
+  if (handling === 'own') {
+    // The tool reads its optional branch itself, absence and all; only a
+    // name it was given is ours to check, and only one that names something —
+    // what the tool makes of a value that does not is the tool's to answer.
+    if (namesSomething(given)) await assertBranchExists(given, branches);
+    return null;
+  }
+  // ABSENT, and only absent, is defaulted. An empty or non-string value is a
+  // caller that meant to name a branch and got it wrong: refused by name
+  // under both declarations rather than quietly read as the default.
+  if (handling === 'defaults-to-default-branch' && given === undefined) {
+    const fallback = branches?.defaultBranch() ?? '';
+    if (fallback.length === 0) throw new DefaultBranchUnsetError();
+    return { branch: fallback, defaulted: true };
+  }
+  assertBranchProvided(given);
+  await assertBranchExists(given, branches);
+  return { branch: given, defaulted: false };
+}
+
+function namesSomething(v: unknown): v is string {
+  try {
+    assertBranchProvided(v);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A plain JSON object answer — the only kind a `branch` field can be added to.
+ * A `Date`, a class instance or an array serializes as something else, and
+ * spreading it into `{ branch }` would lose that answer.
+ */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  if (typeof v !== 'object' || v === null) return false;
+  const prototype: unknown = Object.getPrototypeOf(v);
+  return prototype === Object.prototype || prototype === null;
 }
 
 /**
  * Wrap a pure tool handler into an Express handler. Resolves the `ToolContext`
- * from `req.toolAuth` (set by `toolAuth`), enforces write-scope, runs the
- * handler, and serializes the result — JSON for a value, SSE for an
- * async-iterable (streaming). `ToolError`/`hasHttpStatus` map to HTTP status.
- * The handler receives `req.body` as the flat args (UTCP's `body_field` already
- * delivered the inner body as the request body).
+ * from `req.toolAuth` (set by `toolAuth`), enforces write-scope, CHECKS THE
+ * ARGUMENTS against what the tool declared, runs the handler, and serializes the
+ * result — JSON for a value, SSE for an async-iterable (streaming).
+ * `ToolError`/`hasHttpStatus` map to HTTP status. The handler receives
+ * `req.body` as the flat args (UTCP's `body_field` already delivered the inner
+ * body as the request body).
+ *
+ * The argument check is HERE, in the route, because the route is where every
+ * caller of a route-hosted tool arrives: an agent over MCP, a `call_tool_chain`
+ * chain, the in-process agent over loopback, and a script calling
+ * `POST /api/agent/tools/<name>` with a connection key. Checked one layer up,
+ * in the MCP dispatch, the last of those was left answering a 500 for a missing
+ * argument — or running: `grep` without a `pattern` matched every file. Every
+ * tool mounted through this factory gets it, a deployment's included, without
+ * saying so (see `route-argument-check.ts`).
  */
-export function createToolHandlerFactory(resolve: ResolveToolContext, writeAccess: IWriteAccess = alwaysWritable) {
+export function createToolHandlerFactory(
+  resolve: ResolveToolContext,
+  writeAccess: IWriteAccess = alwaysWritable,
+  /** Absent: no default branch to fall back on, and no existence check before the tool runs. */
+  branches?: ToolBranchPort,
+) {
   return function toolHandler(handler: ToolHandler, opts: ToolHandlerOptions = {}) {
+    let warnedHeldToRequired = false;
     return async (req: Request, res: Response): Promise<void> => {
       const auth = req.toolAuth;
       if (!auth) {
@@ -42,6 +161,12 @@ export function createToolHandlerFactory(resolve: ResolveToolContext, writeAcces
         res.status(403).json({ error: 'This tool requires write access.' });
         return;
       }
+      // About the CREDENTIAL, not the deployment: the tool is a read, and a
+      // read-only deployment serves it — the key used here is what may not.
+      if (opts.writeScope && auth.scope === 'read') {
+        res.status(403).json({ error: 'This tool cannot be used with a read-only credential; use a full-scope key.' });
+        return;
+      }
       // Before anything is awaited: a client that goes away during the
       // write-access check below must still abort the call.
       //
@@ -71,6 +196,18 @@ export function createToolHandlerFactory(resolve: ResolveToolContext, writeAcces
         return;
       }
       const args = (body ?? {}) as Record<string, unknown>;
+      // Before the context is resolved and before the handler runs: nothing is
+      // read, written or sent on a call that does not match its tool. The more
+      // specific refusals each tool makes for itself (a missing `branch`,
+      // above all) are left to the handler and keep their own wording — this
+      // reports what the SCHEMA alone can settle.
+      // The WHOLE path: a module mounts its routes on a router, which sees only
+      // the part below its mount point.
+      const mismatch = argumentsRefusal(req.originalUrl, args, req.query);
+      if (mismatch) {
+        res.status(mismatch.status).json({ ...mismatch.details, error: mismatch.message });
+        return;
+      }
       // `sessionId` rides the tool body like `branch` does: the external MCP
       // proxy injects it (ask-tool continuity convention) and the in-process
       // agent passes its thread id. Surfaced on the context so the
@@ -79,8 +216,52 @@ export function createToolHandlerFactory(resolve: ResolveToolContext, writeAcces
         ? args.sessionId
         : undefined;
       try {
+        // The branch is resolved HERE, once, before the tool runs: refused,
+        // defaulted or checked to exist, by what the tool declared — so no
+        // tool, the platform's or a deployment's, carries a guard of its own,
+        // and none can be handed a branch that is missing, empty or not a
+        // string. Its declaration comes from the `toolDef` built for this
+        // route; a route no `toolDef` described is read like an optional
+        // `branch` the tool handles itself.
+        //
+        // A writing route never defaults, whatever was recorded for it:
+        // `toolDef` refuses the declaration at startup for a tool it knows
+        // writes, and one only mounted as writing is held to `required` here,
+        // so its write cannot land on the default branch unasked. Its
+        // published schema still calls `branch` optional — the tool's
+        // declaration is wrong, not the call — so the mismatch is logged,
+        // once per route, for the tool's author to fix by declaring both
+        // `write: true` and `branch: 'required'` (`write` alone with the
+        // defaulting declaration makes `toolDef` throw at startup).
+        const declared =
+          opts.branch ?? branchHandlingFor(req.baseUrl + (req.route?.path ?? req.path)) ?? 'own';
+        const heldToRequired = declared === 'defaults-to-default-branch' && opts.write === true;
+        const handling: BranchHandling = heldToRequired ? 'required' : declared;
+        if (heldToRequired && !warnedHeldToRequired) {
+          warnedHeldToRequired = true;
+          log.warn(
+            `Tool route ${req.baseUrl + (req.route?.path ?? req.path)} is mounted as writing but declared ` +
+              `branch: 'defaults-to-default-branch'; it is held to 'required'. ` +
+              `Declare both \`write: true\` and \`branch: 'required'\` to its toolDef.`,
+          );
+        }
+        const resolved = await resolveBranch(handling, args, branches);
+        // The tool can read no other branch than the resolved one: `args`
+        // carries it under the same name, and a tool that takes no branch
+        // gets none at all.
+        const toolArgs = resolved
+          ? { ...args, branch: resolved.branch }
+          : handling === 'none'
+            ? withoutBranch(args)
+            : args;
         const ctx = await resolve(auth, abort.signal, sessionId);
-        const out = await handler(args, ctx);
+        if (resolved) ctx.branch = resolved.branch;
+        let out = await handler(toolArgs, ctx);
+        // A defaulted call's answer says which branch it ran on, so a caller
+        // that forgot its branch can see it was answered about another.
+        if (resolved?.defaulted && isPlainObject(out) && out.branch === undefined) {
+          out = { ...out, branch: resolved.branch };
+        }
         if (isAsyncIterable(out)) {
           res.setHeader('Content-Type', 'text/event-stream');
           res.setHeader('Cache-Control', 'no-cache');
@@ -126,4 +307,11 @@ export function createToolHandlerFactory(resolve: ResolveToolContext, writeAcces
   };
 }
 
+function withoutBranch(args: Record<string, unknown>): Record<string, unknown> {
+  if (!('branch' in args)) return args;
+  const rest = { ...args };
+  delete rest.branch;
+  return rest;
+}
+
 export type ToolHandlerFactory = ReturnType<typeof createToolHandlerFactory>;

package/src/modules/tool-helpers/tool.contract.ts

@@ -48,6 +48,15 @@ export interface ToolContext {
    * still fails closed regardless of this).
    */
   focusedBranch?: string;
+  /**
+   * The branch this call runs on, resolved by the tool handler before the tool
+   * ran from the tool's branch declaration (see `BranchDeclaration`): the one
+   * the caller named, or the deployment's default branch for a
+   * `defaults-to-default-branch` tool called without one. Set for every tool
+   * that declares a branch, and always a non-empty string then; absent for a
+   * tool that takes no branch.
+   */
+  branch?: string;
   abortSignal: AbortSignal;
   workspaceService: WorkspaceService;
   workflowService: IWorkflowService;