@openshain/mcp 0.3.1 → 0.4.1

package/NOTICE

@@ -0,0 +1,4 @@
+openshain
+Copyright 2026 openshain contributors
+
+Licensed under the Apache License, Version 2.0.

package/dist/server.js

@@ -1,6 +1,7 @@
+import { relative } from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { ASK_USER, compileInputValidator, countToolCalls, createToolCaller, createToolRegistry, isKnownEventType, isOpenshainError, isTerminal, loadConfig, parsePayloadFile, parseWorkId, pendingQuestions, RUNTIME_PROVIDER_ID, resolveWorkspacePath, SESSION_WORK_TYPE, uuidv7, verifyArtifact, WorkStore, workHistory, } from "@openshain/core";
+import { ASK_USER, businessDate, companyTime, compileInputValidator, countToolCalls, createToolCaller, createToolRegistry, DecisionFileSchema, isKnownEventType, isOpenshainError, isTerminal, loadAuthority, loadConfig, parsePayloadFile, parseWorkId, pendingApprovals, pendingQuestions, RUNTIME_PROVIDER_ID, resolveWorkspacePath, SESSION_WORK_TYPE, uuidv7, verifyArtifact, WorkStore, workHistory, writeDecision, } from "@openshain/core";
 import pkg from "../package.json" with { type: "json" };
 import { Session } from "./session.js";
 /** The tools every session has, before the workspace's own. Their names are reserved in the runtime. */
@@ -116,6 +117,67 @@ const WORK_TOOLS = [
             additionalProperties: false,
         },
     },
+    {
+        name: "context",
+        description: "Where and when you are working: the current time with its offset, the time zone, today's business date, the company folder, the company, the person you work for, and the current work. Call it when a date or a time matters; the answer is recorded.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "approval_list",
+        description: "Every tool call held for a person's approval across the works of this workspace, oldest first: approval_id, work_id, the call, the rule, and who may approve.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "approval_decide",
+        description: "Decide a held tool call as the person this connection acts for. approve runs the call now and returns its result; reject refuses it. Either way the work continues.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                approval_id: { type: "string", maxLength: 100 },
+                decision: { type: "string", enum: ["approve", "reject"] },
+                comment: { type: "string", maxLength: 2000 },
+            },
+            required: ["approval_id", "decision"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "review_decide",
+        description: "Record what a qualified reviewer decided about a call the policy held for review. approve and modify write a decision under authority/decisions/ and run the call (modify runs the reviewer's input); reject refuses it. The reviewer is named by the company; openshain does not verify a qualification.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                approval_id: { type: "string", maxLength: 100 },
+                decision: { type: "string", enum: ["approve", "reject", "modify"] },
+                reviewer: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", maxLength: 200 },
+                        role: { type: "string", maxLength: 100 },
+                        qualification: { type: "string", maxLength: 500 },
+                    },
+                    required: ["name", "role"],
+                    additionalProperties: false,
+                },
+                interpretation: { type: "string", maxLength: 20_000 },
+                modified_input: { type: "object" },
+                effective_from: { type: "string", maxLength: 10 },
+                effective_until: { type: "string", maxLength: 10 },
+                applies_to: {
+                    type: "object",
+                    properties: {
+                        action: { type: "string", maxLength: 200 },
+                        path: { type: "string", maxLength: 1000 },
+                    },
+                    additionalProperties: false,
+                },
+            },
+            required: ["approval_id", "decision", "reviewer"],
+            additionalProperties: false,
+        },
+    },
     {
         name: "work_record",
         description: "Record an event of the client itself on a work: what the person said (human.message), a prompt command expanded for the model (prompt.expanded), a model call (model.requested, model.completed, model.failed) or its usage (usage.recorded with kind model_inference). The payload is in the file form of spec/schemas/events.v1.json. Tool calls are recorded by the runtime and cannot be recorded here.",
@@ -164,7 +226,14 @@ export async function createMcpServer(options) {
     const { workspaceRoot } = options;
     const config = await loadConfig(workspaceRoot);
     const registry = await createToolRegistry(workspaceRoot, config, options.tools);
-    const callTool = createToolCaller({ registry, config, workspaceRoot });
+    // Reloaded when a reviewer writes a decision, so the next call can cite it.
+    let authority = await loadAuthority(workspaceRoot);
+    const callTool = createToolCaller({
+        registry,
+        config,
+        workspaceRoot,
+        authority: () => authority,
+    });
     const works = new WorkStore(workspaceRoot);
     const session = new Session();
     const server = new Server({ name: "openshain", version: pkg.version }, { capabilities: { tools: {} } });
@@ -315,6 +384,200 @@ export async function createMcpServer(options) {
                     await opened.close();
                 }
             }
+            case "context": {
+                const now = new Date();
+                const timezone = config.company.timezone;
+                const info = {
+                    now: companyTime(timezone, now),
+                    timezone,
+                    business_date: businessDate(timezone, now),
+                    workspace: workspaceRoot,
+                    company: config.company.name,
+                    principal: { id: config.principal.id, name: config.principal.name },
+                    profession: config.profession.id,
+                    work: session.current ?? null,
+                };
+                const result = json(info);
+                // Recorded on the current work when there is one, even a session: it touches no file.
+                const current = session.current;
+                if (current && !isTerminal((await works.get(current)).status)) {
+                    const callId = newCallId();
+                    const opened = await works.open(current);
+                    try {
+                        await opened.append({
+                            type: "tool.called",
+                            payload: { callId, provider: RUNTIME_PROVIDER_ID, name: "context", input: {} },
+                        });
+                        await opened.append({
+                            type: "tool.completed",
+                            payload: { callId, content: [{ type: "json", value: info }], isError: false },
+                        });
+                    }
+                    finally {
+                        await opened.close();
+                    }
+                }
+                return result;
+            }
+            case "approval_list": {
+                const held = [];
+                const { works: all } = await works.list();
+                for (const w of all) {
+                    if (w.status !== "waiting_approval")
+                        continue;
+                    for (const a of pendingApprovals(await works.events(w.id))) {
+                        held.push({ ...a, work_id: w.id, objective: w.objective });
+                    }
+                }
+                return json({ approvals: held });
+            }
+            case "approval_decide": {
+                const { approval_id: approvalId, decision, comment, } = input;
+                const found = await findApproval(works, approvalId);
+                if (!found)
+                    return failure(`no pending approval ${approvalId}`);
+                const { workId, approval } = found;
+                const by = config.principal.id;
+                if (approval.kind === "review") {
+                    return failure(`${approvalId} waits for a qualified reviewer, not a person's approval; use review_decide`);
+                }
+                if (approval.approvers && !approval.approvers.includes(by)) {
+                    return failure(`${by} may not decide ${approvalId}; approvers: ${approval.approvers.join(", ")}`);
+                }
+                const opened = await works.open(workId);
+                try {
+                    // Under the lock: another connection may have decided this approval in between.
+                    if (!pendingApprovals(await opened.events()).some((a) => a.approvalId === approvalId)) {
+                        return failure(`approval ${approvalId} was already decided`);
+                    }
+                    await opened.append({
+                        type: "approval.decided",
+                        payload: { approvalId, decision, by, ...(comment !== undefined && { comment }) },
+                    });
+                    if (decision === "reject") {
+                        await opened.append({
+                            type: "tool.rejected",
+                            payload: {
+                                callId: approval.call.callId,
+                                name: approval.call.name,
+                                code: "rejected_by_person",
+                                reason: comment ?? `${by} rejected ${approvalId}`,
+                            },
+                        });
+                        await opened.transition("in_progress", `${by} rejected ${approvalId}`);
+                        return json({ approval_id: approvalId, decision, work_id: workId });
+                    }
+                    await opened.transition("in_progress", `${by} approved ${approvalId}`);
+                    const result = await callTool(opened, { id: approval.call.callId, name: approval.call.name, input: approval.call.input }, { approvedBy: approvalId });
+                    return json({
+                        approval_id: approvalId,
+                        decision,
+                        work_id: workId,
+                        result: { content: result.content, isError: result.isError ?? false },
+                    });
+                }
+                finally {
+                    await opened.close();
+                }
+            }
+            case "review_decide": {
+                const { approval_id: approvalId, decision, reviewer, interpretation, modified_input: modifiedInput, effective_from: effectiveFrom, effective_until: effectiveUntil, applies_to: appliesTo, } = input;
+                const found = await findApproval(works, approvalId);
+                if (!found)
+                    return failure(`no pending approval ${approvalId}`);
+                const { workId, approval } = found;
+                if (approval.kind !== "review") {
+                    return failure(`${approvalId} waits for a person's approval, not a review; use approval_decide`);
+                }
+                if (decision !== "reject" && (interpretation ?? "") === "") {
+                    return failure("a decision needs the reviewer's interpretation in their own words");
+                }
+                if (approval.reviewer && approval.reviewer.role !== reviewer.role) {
+                    return failure(`rule ${approval.ruleId} asks for a ${approval.reviewer.role}; the decision names a ${reviewer.role}`);
+                }
+                if (decision === "modify" && modifiedInput) {
+                    // Checked before anything is recorded: a refused input leaves the approval pending.
+                    const before = (approval.call.input ?? {});
+                    const after = modifiedInput;
+                    if (before.path !== after.path) {
+                        return failure(`a modified call must touch the same path: ${String(before.path)} was held, ${String(after.path)} was given`);
+                    }
+                }
+                // Built and checked before anything is recorded: an input the decision refuses must not
+                // consume the approval and leave the work waiting with nobody able to move it.
+                const today = new Date();
+                let record;
+                if (decision !== "reject") {
+                    const parsed = DecisionFileSchema.safeParse({
+                        id: `dec_${uuidv7()}`,
+                        reviewer,
+                        approval_id: approvalId,
+                        decided_at: today.toISOString(),
+                        effective_from: effectiveFrom ?? today.toISOString().slice(0, 10),
+                        effective_until: effectiveUntil ?? null,
+                        interpretation,
+                        applies_to: appliesTo ?? {},
+                    });
+                    if (!parsed.success) {
+                        return failure(`the decision is not well formed: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+                    }
+                    record = parsed.data;
+                }
+                const opened = await works.open(workId);
+                try {
+                    // Under the lock: another connection may have decided this approval in between.
+                    if (!pendingApprovals(await opened.events()).some((a) => a.approvalId === approvalId)) {
+                        return failure(`approval ${approvalId} was already decided`);
+                    }
+                    await opened.append({
+                        type: "approval.decided",
+                        payload: {
+                            approvalId,
+                            decision,
+                            by: reviewer.name,
+                            ...(interpretation !== undefined && { comment: interpretation }),
+                            ...(decision === "modify" && modifiedInput && { modifiedInput }),
+                        },
+                    });
+                    if (decision === "reject") {
+                        await opened.append({ type: "review.decided", payload: { approvalId } });
+                        await opened.append({
+                            type: "tool.rejected",
+                            payload: {
+                                callId: approval.call.callId,
+                                name: approval.call.name,
+                                code: "rejected_by_person",
+                                reason: interpretation ?? `${reviewer.name} did not approve ${approvalId}`,
+                            },
+                        });
+                        await opened.transition("in_progress", `${reviewer.name} rejected ${approvalId}`);
+                        return json({ approval_id: approvalId, decision, work_id: workId });
+                    }
+                    const written = record;
+                    const file = await writeDecision(workspaceRoot, written);
+                    await opened.append({
+                        type: "review.decided",
+                        payload: { approvalId, decisionId: written.id },
+                    });
+                    await opened.transition("in_progress", `${reviewer.name} decided ${approvalId}`);
+                    const ranWith = decision === "modify" && modifiedInput ? modifiedInput : approval.call.input;
+                    const ran = await callTool(opened, { id: approval.call.callId, name: approval.call.name, input: ranWith }, { approvedBy: approvalId });
+                    // The decision is on disk; a rule that cites its id can use it from here on. Reloaded
+                    // so that a rule already written for it takes effect without a restart.
+                    authority = await loadAuthority(workspaceRoot);
+                    return json({
+                        approval_id: approvalId,
+                        decision,
+                        work_id: workId,
+                        decision_id: written.id,
+                        decision_file: relative(workspaceRoot, file),
+                        result: { content: ran.content, isError: ran.isError ?? false },
+                    });
+                }
+                finally {
+                    await opened.close();
+                }
+            }
             case "work_list": {
                 const { works: all, problems } = await works.list();
                 return json({
@@ -368,6 +631,9 @@ export async function createMcpServer(options) {
                 if (work.status === "waiting_input") {
                     return failure(`work ${gate.id} is waiting for the person's answer; record it with work_answer before calling tools`);
                 }
+                if (work.status === "waiting_approval") {
+                    return failure(`work ${gate.id} is waiting for an approval; decide it with approval_decide (see approval_list) before calling tools`);
+                }
                 const opened = await works.open(gate.id);
                 try {
                     const limit = config.limits.maxToolCalls;
@@ -471,3 +737,15 @@ function failure(text) {
 function newCallId() {
     return `call_${uuidv7()}`;
 }
+/** The work holding a pending approval, found by scanning the works that wait for one. */
+async function findApproval(works, approvalId) {
+    const { works: all } = await works.list();
+    for (const w of all) {
+        if (w.status !== "waiting_approval")
+            continue;
+        const approval = pendingApprovals(await works.events(w.id)).find((a) => a.approvalId === approvalId);
+        if (approval)
+            return { workId: w.id, approval };
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openshain/mcp",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "MCP server that exposes an openshain workspace to any agent",
   "keywords": [
     "openshain",
@@ -30,7 +30,8 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "exports": {
     ".": {
@@ -45,10 +46,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@openshain/core": "0.3.1"
+    "@openshain/core": "0.4.1"
   },
   "devDependencies": {
-    "@openshain/tools": "0.3.1"
+    "@openshain/tools": "0.4.1"
   },
   "publishConfig": {
     "access": "public"

package/src/server.ts

@@ -1,3 +1,4 @@
+import { relative } from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
@@ -9,19 +10,26 @@ import {
   type AnyEvent,
   type Artifact,
   ASK_USER,
+  businessDate,
+  companyTime,
   compileInputValidator,
   countToolCalls,
   createToolCaller,
   createToolRegistry,
+  DecisionFileSchema,
+  type DecisionRecord,
   type Event,
   type EventType,
   type InputValidation,
   isKnownEventType,
   isOpenshainError,
   isTerminal,
+  loadAuthority,
   loadConfig,
+  type PendingApproval,
   parsePayloadFile,
   parseWorkId,
+  pendingApprovals,
   pendingQuestions,
   RUNTIME_PROVIDER_ID,
   type RuntimeProviders,
@@ -35,6 +43,7 @@ import {
   type WorkId,
   WorkStore,
   workHistory,
+  writeDecision,
 } from "@openshain/core";
 import pkg from "../package.json" with { type: "json" };
 import { Session } from "./session.ts";
@@ -163,6 +172,71 @@ const WORK_TOOLS: Tool[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: "context",
+    description:
+      "Where and when you are working: the current time with its offset, the time zone, today's business date, the company folder, the company, the person you work for, and the current work. Call it when a date or a time matters; the answer is recorded.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "approval_list",
+    description:
+      "Every tool call held for a person's approval across the works of this workspace, oldest first: approval_id, work_id, the call, the rule, and who may approve.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "approval_decide",
+    description:
+      "Decide a held tool call as the person this connection acts for. approve runs the call now and returns its result; reject refuses it. Either way the work continues.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        approval_id: { type: "string", maxLength: 100 },
+        decision: { type: "string", enum: ["approve", "reject"] },
+        comment: { type: "string", maxLength: 2000 },
+      },
+      required: ["approval_id", "decision"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "review_decide",
+    description:
+      "Record what a qualified reviewer decided about a call the policy held for review. approve and modify write a decision under authority/decisions/ and run the call (modify runs the reviewer's input); reject refuses it. The reviewer is named by the company; openshain does not verify a qualification.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        approval_id: { type: "string", maxLength: 100 },
+        decision: { type: "string", enum: ["approve", "reject", "modify"] },
+        reviewer: {
+          type: "object",
+          properties: {
+            name: { type: "string", maxLength: 200 },
+            role: { type: "string", maxLength: 100 },
+            qualification: { type: "string", maxLength: 500 },
+          },
+          required: ["name", "role"],
+          additionalProperties: false,
+        },
+        interpretation: { type: "string", maxLength: 20_000 },
+        modified_input: { type: "object" },
+        effective_from: { type: "string", maxLength: 10 },
+        effective_until: { type: "string", maxLength: 10 },
+        applies_to: {
+          type: "object",
+          properties: {
+            action: { type: "string", maxLength: 200 },
+            path: { type: "string", maxLength: 1000 },
+          },
+          additionalProperties: false,
+        },
+      },
+      required: ["approval_id", "decision", "reviewer"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "work_record",
     description:
@@ -222,7 +296,14 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
   const { workspaceRoot } = options;
   const config = await loadConfig(workspaceRoot);
   const registry = await createToolRegistry(workspaceRoot, config, options.tools);
-  const callTool = createToolCaller({ registry, config, workspaceRoot });
+  // Reloaded when a reviewer writes a decision, so the next call can cite it.
+  let authority = await loadAuthority(workspaceRoot);
+  const callTool = createToolCaller({
+    registry,
+    config,
+    workspaceRoot,
+    authority: () => authority,
+  });
   const works = new WorkStore(workspaceRoot);
   const session = new Session();
   const server = new Server(
@@ -385,6 +466,237 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
           await opened.close();
         }
       }
+      case "context": {
+        const now = new Date();
+        const timezone = config.company.timezone;
+        const info = {
+          now: companyTime(timezone, now),
+          timezone,
+          business_date: businessDate(timezone, now),
+          workspace: workspaceRoot,
+          company: config.company.name,
+          principal: { id: config.principal.id, name: config.principal.name },
+          profession: config.profession.id,
+          work: session.current ?? null,
+        };
+        const result = json(info);
+        // Recorded on the current work when there is one, even a session: it touches no file.
+        const current = session.current;
+        if (current && !isTerminal((await works.get(current)).status)) {
+          const callId = newCallId();
+          const opened = await works.open(current);
+          try {
+            await opened.append({
+              type: "tool.called",
+              payload: { callId, provider: RUNTIME_PROVIDER_ID, name: "context", input: {} },
+            });
+            await opened.append({
+              type: "tool.completed",
+              payload: { callId, content: [{ type: "json", value: info }], isError: false },
+            });
+          } finally {
+            await opened.close();
+          }
+        }
+        return result;
+      }
+      case "approval_list": {
+        const held: unknown[] = [];
+        const { works: all } = await works.list();
+        for (const w of all) {
+          if (w.status !== "waiting_approval") continue;
+          for (const a of pendingApprovals(await works.events(w.id))) {
+            held.push({ ...a, work_id: w.id, objective: w.objective });
+          }
+        }
+        return json({ approvals: held });
+      }
+      case "approval_decide": {
+        const {
+          approval_id: approvalId,
+          decision,
+          comment,
+        } = input as { approval_id: string; decision: "approve" | "reject"; comment?: string };
+        const found = await findApproval(works, approvalId);
+        if (!found) return failure(`no pending approval ${approvalId}`);
+        const { workId, approval } = found;
+        const by = config.principal.id;
+        if (approval.kind === "review") {
+          return failure(
+            `${approvalId} waits for a qualified reviewer, not a person's approval; use review_decide`,
+          );
+        }
+        if (approval.approvers && !approval.approvers.includes(by)) {
+          return failure(
+            `${by} may not decide ${approvalId}; approvers: ${approval.approvers.join(", ")}`,
+          );
+        }
+        const opened = await works.open(workId);
+        try {
+          // Under the lock: another connection may have decided this approval in between.
+          if (!pendingApprovals(await opened.events()).some((a) => a.approvalId === approvalId)) {
+            return failure(`approval ${approvalId} was already decided`);
+          }
+          await opened.append({
+            type: "approval.decided",
+            payload: { approvalId, decision, by, ...(comment !== undefined && { comment }) },
+          });
+          if (decision === "reject") {
+            await opened.append({
+              type: "tool.rejected",
+              payload: {
+                callId: approval.call.callId,
+                name: approval.call.name,
+                code: "rejected_by_person",
+                reason: comment ?? `${by} rejected ${approvalId}`,
+              },
+            });
+            await opened.transition("in_progress", `${by} rejected ${approvalId}`);
+            return json({ approval_id: approvalId, decision, work_id: workId });
+          }
+          await opened.transition("in_progress", `${by} approved ${approvalId}`);
+          const result = await callTool(
+            opened,
+            { id: approval.call.callId, name: approval.call.name, input: approval.call.input },
+            { approvedBy: approvalId },
+          );
+          return json({
+            approval_id: approvalId,
+            decision,
+            work_id: workId,
+            result: { content: result.content, isError: result.isError ?? false },
+          });
+        } finally {
+          await opened.close();
+        }
+      }
+      case "review_decide": {
+        const {
+          approval_id: approvalId,
+          decision,
+          reviewer,
+          interpretation,
+          modified_input: modifiedInput,
+          effective_from: effectiveFrom,
+          effective_until: effectiveUntil,
+          applies_to: appliesTo,
+        } = input as {
+          approval_id: string;
+          decision: "approve" | "reject" | "modify";
+          reviewer: { name: string; role: string; qualification?: string };
+          interpretation?: string;
+          modified_input?: Record<string, unknown>;
+          effective_from?: string;
+          effective_until?: string;
+          applies_to?: { action?: string; path?: string };
+        };
+        const found = await findApproval(works, approvalId);
+        if (!found) return failure(`no pending approval ${approvalId}`);
+        const { workId, approval } = found;
+        if (approval.kind !== "review") {
+          return failure(
+            `${approvalId} waits for a person's approval, not a review; use approval_decide`,
+          );
+        }
+        if (decision !== "reject" && (interpretation ?? "") === "") {
+          return failure("a decision needs the reviewer's interpretation in their own words");
+        }
+        if (approval.reviewer && approval.reviewer.role !== reviewer.role) {
+          return failure(
+            `rule ${approval.ruleId} asks for a ${approval.reviewer.role}; the decision names a ${reviewer.role}`,
+          );
+        }
+        if (decision === "modify" && modifiedInput) {
+          // Checked before anything is recorded: a refused input leaves the approval pending.
+          const before = (approval.call.input ?? {}) as { path?: unknown };
+          const after = modifiedInput as { path?: unknown };
+          if (before.path !== after.path) {
+            return failure(
+              `a modified call must touch the same path: ${String(before.path)} was held, ${String(after.path)} was given`,
+            );
+          }
+        }
+        // Built and checked before anything is recorded: an input the decision refuses must not
+        // consume the approval and leave the work waiting with nobody able to move it.
+        const today = new Date();
+        let record: DecisionRecord | undefined;
+        if (decision !== "reject") {
+          const parsed = DecisionFileSchema.safeParse({
+            id: `dec_${uuidv7()}`,
+            reviewer,
+            approval_id: approvalId,
+            decided_at: today.toISOString(),
+            effective_from: effectiveFrom ?? today.toISOString().slice(0, 10),
+            effective_until: effectiveUntil ?? null,
+            interpretation,
+            applies_to: appliesTo ?? {},
+          });
+          if (!parsed.success) {
+            return failure(
+              `the decision is not well formed: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+            );
+          }
+          record = parsed.data;
+        }
+        const opened = await works.open(workId);
+        try {
+          // Under the lock: another connection may have decided this approval in between.
+          if (!pendingApprovals(await opened.events()).some((a) => a.approvalId === approvalId)) {
+            return failure(`approval ${approvalId} was already decided`);
+          }
+          await opened.append({
+            type: "approval.decided",
+            payload: {
+              approvalId,
+              decision,
+              by: reviewer.name,
+              ...(interpretation !== undefined && { comment: interpretation }),
+              ...(decision === "modify" && modifiedInput && { modifiedInput }),
+            },
+          });
+          if (decision === "reject") {
+            await opened.append({ type: "review.decided", payload: { approvalId } });
+            await opened.append({
+              type: "tool.rejected",
+              payload: {
+                callId: approval.call.callId,
+                name: approval.call.name,
+                code: "rejected_by_person",
+                reason: interpretation ?? `${reviewer.name} did not approve ${approvalId}`,
+              },
+            });
+            await opened.transition("in_progress", `${reviewer.name} rejected ${approvalId}`);
+            return json({ approval_id: approvalId, decision, work_id: workId });
+          }
+          const written = record as DecisionRecord;
+          const file = await writeDecision(workspaceRoot, written);
+          await opened.append({
+            type: "review.decided",
+            payload: { approvalId, decisionId: written.id },
+          });
+          await opened.transition("in_progress", `${reviewer.name} decided ${approvalId}`);
+          const ranWith =
+            decision === "modify" && modifiedInput ? modifiedInput : approval.call.input;
+          const ran = await callTool(
+            opened,
+            { id: approval.call.callId, name: approval.call.name, input: ranWith },
+            { approvedBy: approvalId },
+          );
+          // The decision is on disk; a rule that cites its id can use it from here on. Reloaded
+          // so that a rule already written for it takes effect without a restart.
+          authority = await loadAuthority(workspaceRoot);
+          return json({
+            approval_id: approvalId,
+            decision,
+            work_id: workId,
+            decision_id: written.id,
+            decision_file: relative(workspaceRoot, file),
+            result: { content: ran.content, isError: ran.isError ?? false },
+          });
+        } finally {
+          await opened.close();
+        }
+      }
       case "work_list": {
         const { works: all, problems } = await works.list();
         return json({
@@ -438,6 +750,11 @@ export async function createMcpServer(options: McpServerOptions): Promise<Server
             `work ${gate.id} is waiting for the person's answer; record it with work_answer before calling tools`,
           );
         }
+        if (work.status === "waiting_approval") {
+          return failure(
+            `work ${gate.id} is waiting for an approval; decide it with approval_decide (see approval_list) before calling tools`,
+          );
+        }
         const opened = await works.open(gate.id);
         try {
           const limit = config.limits.maxToolCalls;
@@ -556,3 +873,19 @@ function failure(text: string): CallToolResult {
 function newCallId(): string {
   return `call_${uuidv7()}`;
 }
+
+/** The work holding a pending approval, found by scanning the works that wait for one. */
+async function findApproval(
+  works: WorkStore,
+  approvalId: string,
+): Promise<{ workId: WorkId; approval: PendingApproval } | undefined> {
+  const { works: all } = await works.list();
+  for (const w of all) {
+    if (w.status !== "waiting_approval") continue;
+    const approval = pendingApprovals(await works.events(w.id)).find(
+      (a) => a.approvalId === approvalId,
+    );
+    if (approval) return { workId: w.id, approval };
+  }
+  return undefined;
+}