@openshain/agent 0.3.1 → 0.4.0

package/NOTICE

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

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { type ClientResult, connectInMemory, jsonOf, type RuntimeClient, wrap }
 export { AGENT_NAMES, pickAgentName } from "./names.ts";
 export { ANTHROPIC_PROVIDER_ID, AnthropicProvider, type AnthropicProviderOptions, anthropicProvider, } from "./providers/anthropic.ts";
 export { OPENAI_COMPATIBLE_PROVIDER_ID, OpenAICompatibleProvider, type OpenAICompatibleProviderOptions, openaiCompatibleProvider, } from "./providers/openai-compatible.ts";
-export { createSession, type Session, type SessionOptions, TURN_LIMITS, type TurnResult, type TurnStop, } from "./session.ts";
+export { type ApprovalAnswer, type ApprovalChoice, createSession, type HeldApproval, type Session, type SessionOptions, TURN_LIMITS, type TurnResult, type TurnStop, } from "./session.ts";

package/dist/session.d.ts

@@ -16,8 +16,40 @@ export interface SessionOptions {
     onEvent?: (workId: WorkId, event: AnyEvent) => void | Promise<void>;
     /** Answers a question a work asks the person. Without it, the work waits for input. */
     onInput?: (workId: WorkId, question: string) => Promise<string>;
+    /**
+     * Asks the person about a call the policy held, while the turn waits. Without it, the turn
+     * ends and the call stays held for `/approve` or for another client.
+     */
+    onApproval?: (held: HeldApproval) => Promise<ApprovalAnswer>;
+}
+export type TurnStop = "turn_limit" | "aborted" | "max_tokens" | "refusal" | "model_error" | "approval";
+/** A tool call the policy holds until a person decides on it. */
+export interface HeldApproval {
+    approvalId: string;
+    workId: WorkId;
+    name: string;
+    input: unknown;
+    /** The rule that held it: the unit a person can say yes to for the rest of the conversation. */
+    ruleId: string;
+    /** review when a qualified reviewer has to decide; a person cannot stand in for one. */
+    kind: "approval" | "review";
+    reviewer?: {
+        role: string;
+        name?: string;
+    };
+}
+/**
+ * What the person answered about a held call. `always` approves this one and every later call
+ * the same rule holds, for this conversation only: nothing is written to authority/, and every
+ * call is still recorded as requested and decided.
+ */
+export type ApprovalChoice = "approve" | "always" | "reject";
+/** The person's answer: what they chose, and what they want the agent to know. */
+export interface ApprovalAnswer {
+    choice: ApprovalChoice;
+    /** Why, in the person's words. Recorded with the decision and handed to the model. */
+    comment?: string;
 }
-export type TurnStop = "turn_limit" | "aborted" | "max_tokens" | "refusal" | "model_error";
 export interface TurnResult {
     /** What the model said to the person, possibly empty when the turn stopped early. */
     reply: string;
@@ -26,6 +58,8 @@ export interface TurnResult {
     detail?: string;
     /** The work the turn left open, when it stopped inside one. It can be continued with select. */
     work?: WorkId;
+    /** The call held for approval, when the turn stopped for one. */
+    approval?: HeldApproval;
 }
 export interface Session {
     readonly id: WorkId;
@@ -37,6 +71,31 @@ export interface Session {
     }): Promise<TurnResult>;
     /** Names a stopped work as the candidate for the next request. The model decides whether to continue it. */
     select(workId: WorkId): Promise<Work>;
+    /** Decides a held call as the person. approve runs it; either way the work becomes the candidate. */
+    decide(approvalId: string, decision: "approve" | "reject", comment?: string): Promise<{
+        workId: WorkId;
+        text: string;
+    }>;
+    /** Records what a qualified reviewer decided about a call held for review. */
+    review(input: {
+        approvalId: string;
+        decision: "approve" | "reject";
+        reviewer: {
+            name: string;
+            role: string;
+            qualification?: string;
+        };
+        interpretation: string;
+        appliesTo?: {
+            action?: string;
+            path?: string;
+        };
+    }): Promise<{
+        workId: WorkId;
+        text: string;
+    }>;
+    /** The calls held for approval across the workspace. */
+    approvals(): Promise<HeldApproval[]>;
     /** The work the model is on right now, if any. */
     currentWork(): WorkId | undefined;
     /** Ends the conversation. The record stays; a work left in progress stays in progress. */

package/dist/session.js

@@ -4,8 +4,41 @@ import { pickAgentName } from "./names.js";
 /** How much one turn of the conversation may do before it stops and the person is told. */
 export const TURN_LIMITS = { modelCalls: 25, toolCalls: 40 };
 /** The tools of the runtime that the loop itself drives; the model never sees them. */
-const LOOP_ONLY_TOOLS = new Set(["work_record", "work_answer"]);
-const ROLE = "あなたはこの会社の社員エージェントとして、受付の役で、この人と話す。作業が要るときは work_create で Work を作り(objective は人の言葉で書き、会話で分かった前提を添える)、その Work の中で Tool を呼び、終わったら work_complete で summary を人の言葉で書いて閉じる。会話の中では Tool を呼べないので、ファイルの中身を見ないと答えられない質問も Work を作って調べる。件数や金額は Tool が返した値をそのまま書き、計算し直さない。/work resume で候補として示された Work は、人の依頼がその objective に沿うときだけ work_select で続ける。沿わなければ続けず、その旨を伝えて新しい Work を作るか work_list で探し直す。返答は端末の画面に出るので、Markdown の記法や絵文字は使わず、短い文で書く。過去の作業は work_list と work_get で答える。";
+const LOOP_ONLY_TOOLS = new Set([
+    "work_record",
+    "work_answer",
+    // Deciding is the person's, or a qualified reviewer's. A model that could call these would
+    // approve the very calls the policy held.
+    "approval_decide",
+    "review_decide",
+]);
+/**
+ * What the conversation adds to the profession's own instructions. Written as sections, and as
+ * what to do rather than what to avoid: models differ in how much they say after a tool call,
+ * so the screen's side of the contract is stated here instead of left to a model's default.
+ */
+const ROLE = [
+    "# 画面",
+    "あなたの返答は端末の画面に出る。人に見えるのは、あなたが書いた文と、Tool 呼び出しの名前と引数の 1 行だけ。Tool が返した中身と、work_complete に書いた summary は人には見えない。依頼の答えは返答に書く。",
+    "",
+    "# 返答の書き方",
+    "- 結果から書く。前置き(「承知しました」)と後置き(「ご不明な点があれば」)は書かない",
+    "- 依頼が終わったターンでは、何をしたか、答えになる数字(件数、金額、書いたファイルの場所)を書く。次にできることがあれば 1 行で添える",
+    "- 見出し、箇条書き、番号、太字、コードブロック、引用が使える。画面がそのまま書式として描く。表は書式にならないので、箇条書きにする",
+    "- 数字は Tool が返した値をそのまま書く",
+    "- 長さは依頼の大きさに合わせる。1 行で足りる依頼には 1 行で答える",
+    "",
+    "# 仕事の進め方",
+    "- あなたは受付の役でこの人と話す。作業が要るときは work_create で Work を作り(objective は人の言葉で書き、会話で分かった前提を添える)、その Work の中で Tool を呼び、work_complete の summary に記録用の要約を書いて閉じる。summary は記録に残すもの、返答は人に伝えるもの",
+    "- 会話の中では Tool を呼べない。ファイルの中身を読まないと答えられない質問も、Work を作って調べる",
+    "- /work resume で候補として示された Work は、人の依頼がその objective に沿うときだけ work_select で続ける。沿わなければ続けず、その旨を伝えて新しい Work を作るか work_list で探し直す",
+    "- 過去の作業は work_list と work_get で答える",
+    "",
+    "# 承認と資格者の判断",
+    "- 承認が要る呼び出しは止まる。人が決めるまで待ち、同じ呼び出しを繰り返さない",
+    "- 実行しないと決められた呼び出しは、理由を読んで別の案を出す。同じ入力で呼び直さない",
+    "- 承認と判断は人と資格者の仕事で、あなたの仕事ではない",
+].join("\n");
 /**
  * Opens a conversation, recorded as a work of type "session", between the person and the model.
  * The loop is a client of the runtime: it creates works, calls tools and closes works through
@@ -49,6 +82,16 @@ export async function createSession(client, options) {
     }));
     let task;
     let candidate;
+    let held;
+    /** Rules the person said yes to for the rest of this conversation. */
+    const standing = new Set();
+    // The basics (time, business date, folder) enter the conversation as a recorded prompt, so the
+    // projection stays a function of the record. The model can refresh them with the context tool.
+    const basics = await client.call("context", {});
+    const info = basics.isError ? undefined : jsonOf(basics);
+    const basicsText = info
+        ? `現在時刻は ${info.now}(${info.timezone})、今日の業務日は ${info.business_date}。会社フォルダは ${info.workspace}。日付や時刻が要るときは context を呼ぶ。`
+        : undefined;
     /** Records one of the client's own events on a work through the runtime, and reports it. */
     const record = async (workId, type, payload) => {
         const event = local(type, payload);
@@ -69,6 +112,10 @@ export async function createSession(client, options) {
         if (task)
             await record(task.id, type, payload);
     };
+    if (basicsText) {
+        events.push(local("prompt.expanded", { name: "context", source: "runtime", text: basicsText }));
+        await record(id, "prompt.expanded", { name: "context", source: "runtime", text: basicsText });
+    }
     const describedTools = async () => (await client.listTools()).filter((t) => !LOOP_ONLY_TOOLS.has(t.name));
     const promptConfig = {
         ...config,
@@ -160,10 +207,13 @@ export async function createSession(client, options) {
                     return { reply: text };
                 case "tool_call": {
                     const calls = response.message.content.filter((p) => p.type === "tool_call");
-                    for (const call of calls) {
-                        if (signal?.aborted)
+                    for (const [index, call] of calls.entries()) {
+                        if (signal?.aborted) {
+                            await closeRest(calls, index, "the turn stopped before this call ran");
                             return { reply: text, stopped: "aborted" };
+                        }
                         if (toolCalls >= TURN_LIMITS.toolCalls) {
+                            await closeRest(calls, index, "the turn reached its limit before this call ran");
                             return {
                                 reply: text,
                                 stopped: "turn_limit",
@@ -172,8 +222,14 @@ export async function createSession(client, options) {
                         }
                         toolCalls += 1;
                         const outcome = await callTool(call, signal);
-                        if (outcome === "withdrawn")
+                        if (outcome === "withdrawn") {
+                            await closeRest(calls, index + 1, "the turn stopped before this call ran");
                             return { reply: text, stopped: "aborted" };
+                        }
+                        if (outcome === "held" && held) {
+                            await closeRest(calls, index + 1, "the turn stopped for an approval before this call ran");
+                            return { reply: text, stopped: "approval", approval: held };
+                        }
                     }
                     break;
                 }
@@ -197,6 +253,13 @@ export async function createSession(client, options) {
      */
     async function callTool(call, signal) {
         const workId = task?.id ?? id;
+        events.push(local("tool.called", {
+            callId: call.id,
+            provider: "runtime",
+            name: call.name,
+            input: call.input,
+        }));
+        await options.onEvent?.(workId, events.at(-1));
         // The loop drives these itself; a model that calls them is refused before the runtime sees it.
         const refusal = LOOP_ONLY_TOOLS.has(call.name)
             ? `${call.name} is the loop's own; it is not a tool for the model`
@@ -204,16 +267,13 @@ export async function createSession(client, options) {
                 ? `${call.name} needs a work of its own: no work is open; start one with work_create`
                 : undefined;
         if (refusal) {
-            finish(call.id, { content: [{ type: "text", text: refusal }], isError: true, text: "" });
+            await finish(call.id, {
+                content: [{ type: "text", text: refusal }],
+                isError: true,
+                text: "",
+            });
             return "done";
         }
-        events.push(local("tool.called", {
-            callId: call.id,
-            provider: "runtime",
-            name: call.name,
-            input: call.input,
-        }));
-        await options.onEvent?.(workId, events.at(-1));
         const input = call.name === "work_create" && call.input && typeof call.input === "object"
             ? { ...call.input, parent: id, agent_name: agentName }
             : call.input;
@@ -252,7 +312,7 @@ export async function createSession(client, options) {
             if (call.name === "work_select" && data.status === "waiting_input") {
                 const answered = await answerPending(workId, signal);
                 if (answered === "withdrawn") {
-                    finish(call.id, result);
+                    await finish(call.id, result);
                     return "withdrawn";
                 }
                 if (answered.length > 0) {
@@ -289,7 +349,7 @@ export async function createSession(client, options) {
                 }
                 catch {
                     // The person took the question back: the work stays waiting_input.
-                    finish(call.id, {
+                    await finish(call.id, {
                         content: [{ type: "text", text: "the person withdrew the question; the work waits" }],
                         isError: true,
                         text: "",
@@ -302,11 +362,125 @@ export async function createSession(client, options) {
                     : { content: [{ type: "text", text: answer }], isError: false, text: answer };
             }
         }
-        finish(call.id, result);
+        if (!result.isError && (data?.pending === "approval" || data?.pending === "review") && task) {
+            const reviewer = data.reviewer;
+            const pending = {
+                approvalId: String(data.approval_id),
+                workId: task.id,
+                name: call.name,
+                input: call.input,
+                ruleId: String(data.rule_id ?? ""),
+                kind: data.pending === "review" ? "review" : "approval",
+                ...(reviewer && { reviewer }),
+            };
+            // A review needs a qualified person, so the turn stops whatever the screen can ask.
+            if (pending.kind === "review") {
+                held = pending;
+                await finish(call.id, {
+                    content: [
+                        {
+                            type: "text",
+                            text: `held for a review by a ${reviewer?.role ?? "reviewer"} (${pending.approvalId}); the work waits until the reviewer decides`,
+                        },
+                    ],
+                    isError: false,
+                    text: "",
+                });
+                return "held";
+            }
+            // With a way to ask, the person decides here and the turn goes on. Without one, the turn
+            // ends and the call stays held for /approve or for another client.
+            if (!options.onApproval) {
+                held = pending;
+                await finish(call.id, {
+                    content: [
+                        {
+                            type: "text",
+                            text: `held for approval ${pending.approvalId}; the person decides before the work goes on`,
+                        },
+                    ],
+                    isError: false,
+                    text: "",
+                });
+                return "held";
+            }
+            let answer;
+            if (pending.ruleId !== "" && standing.has(pending.ruleId)) {
+                answer = { choice: "approve" };
+            }
+            else {
+                try {
+                    answer = await options.onApproval(pending);
+                }
+                catch {
+                    // The person left it undecided: the work stays waiting_approval and the turn ends.
+                    held = pending;
+                    await finish(call.id, {
+                        content: [
+                            {
+                                type: "text",
+                                text: "the person left this call undecided; it is still waiting for their approval and the work stops here",
+                            },
+                        ],
+                        isError: true,
+                        text: "",
+                    });
+                    return "held";
+                }
+                if (answer.choice === "always" && pending.ruleId !== "")
+                    standing.add(pending.ruleId);
+            }
+            const standingNote = answer.choice === "always"
+                ? `この会話では規則 ${pending.ruleId} を常に承認する、と決めた`
+                : undefined;
+            const comment = [answer.comment, standingNote].filter(Boolean).join(" / ");
+            const decided = await client.call("approval_decide", {
+                approval_id: pending.approvalId,
+                decision: answer.choice === "reject" ? "reject" : "approve",
+                ...(comment !== "" && { comment }),
+            }, signal);
+            const outcome = jsonOf(decided);
+            if (decided.isError) {
+                // The work is still waiting; nothing the model does next can move it.
+                held = pending;
+                await finish(call.id, decided);
+                return "held";
+            }
+            if (answer.choice === "reject") {
+                const said = answer.comment ? ` They said: ${answer.comment}` : "";
+                await finish(call.id, {
+                    content: [
+                        {
+                            type: "text",
+                            text: `the person refused this call; it did not run and the work is not waiting for anyone.${said} Do not call it again unchanged: say what you would need, or propose another way.`,
+                        },
+                    ],
+                    isError: true,
+                    text: "",
+                });
+            }
+            else {
+                await finish(call.id, {
+                    content: outcome?.result?.content ?? [{ type: "text", text: "approved" }],
+                    isError: outcome?.result?.isError ?? false,
+                    text: "",
+                });
+            }
+            return "done";
+        }
+        await finish(call.id, result);
         if (!result.isError && (call.name === "work_complete" || call.name === "work_fail") && task) {
             const closed = task;
             task = undefined;
             foldAway(closed, call.id);
+            // The rule that matters most is stated where it is needed, not only in the system prompt:
+            // the work is closed and its summary went to the record, so the person has read nothing
+            // yet. Smaller models end the turn with an acknowledgement without this.
+            const note = call.name === "work_complete"
+                ? `Work ${closed.id} を閉じた。summary は記録に残るだけで、人の画面には出ない。この後の返答で、何をしたかと結果の数字を人に伝える。`
+                : `Work ${closed.id} は失敗として閉じた。この後の返答で、どこまで進んで何が起きたかを人に伝える。`;
+            events.push(local("prompt.expanded", { name: "work closed", source: "runtime", text: note }));
+            await record(id, "prompt.expanded", { name: "work closed", source: "runtime", text: note });
             await options.onEvent?.(closed.id, local(call.name === "work_complete" ? "work.completed" : "work.failed", call.name === "work_complete"
                 ? { summary: String(call.input?.summary ?? "") }
                 : { reason: String(call.input?.reason ?? ""), detail: "" }));
@@ -335,14 +509,24 @@ export async function createSession(client, options) {
         }
         return answers;
     }
-    function finish(callId, result) {
+    /**
+     * Gives every call from `from` on a result, so that the projection stays well formed: a tool
+     * call without a result cannot be sent to a model, and the next turn would refuse to build.
+     */
+    async function closeRest(calls, from, text) {
+        for (const call of calls.slice(from)) {
+            await finish(call.id, { content: [{ type: "text", text }], isError: true, text: "" });
+        }
+    }
+    async function finish(callId, result) {
         const event = local("tool.completed", {
             callId,
             content: result.content,
             isError: result.isError,
         });
         events.push(event);
-        void options.onEvent?.(task?.id ?? id, event);
+        // The screen draws from these in order, so the result waits for the caller as the call did.
+        await options.onEvent?.(task?.id ?? id, event);
     }
     /** Once a work is closed, only its summary stays in the conversation: the tool results are folded away. */
     function foldAway(closed, closingCallId) {
@@ -364,6 +548,7 @@ export async function createSession(client, options) {
         id,
         agentName,
         async turn(text, turnOptions = {}) {
+            held = undefined;
             events.push(local("human.message", { text }));
             await record(id, "human.message", { text });
             if (candidate) {
@@ -396,6 +581,70 @@ export async function createSession(client, options) {
             return work;
         },
         currentWork: () => task?.id,
+        async decide(approvalId, decision, comment) {
+            const decided = await client.call("approval_decide", {
+                approval_id: approvalId,
+                decision,
+                ...(comment !== undefined && { comment }),
+            });
+            if (decided.isError)
+                throw new Error(decided.text);
+            const data = jsonOf(decided);
+            const workId = data.work_id;
+            const outcome = decision === "reject"
+                ? "拒否"
+                : data.result?.isError
+                    ? `実行して失敗: ${data.result.content.map((c) => c.text ?? "").join("")}`
+                    : "実行して成功";
+            const note = `承認 ${approvalId} を${decision === "approve" ? "承認" : "拒否"}した(${outcome})。Work ${workId} は続けられる。`;
+            events.push(local("prompt.expanded", { name: "approval", source: "runtime", text: note }));
+            await record(id, "prompt.expanded", { name: "approval", source: "runtime", text: note });
+            const got = await client.call("work_get", { id: workId });
+            const work = jsonOf(got);
+            if (work && !isTerminal(work.status)) {
+                candidate = { id: work.id, objective: work.objective, status: work.status };
+            }
+            return { workId, text: note };
+        },
+        async review(input) {
+            const decided = await client.call("review_decide", {
+                approval_id: input.approvalId,
+                decision: input.decision,
+                reviewer: input.reviewer,
+                interpretation: input.interpretation,
+                ...(input.appliesTo && { applies_to: input.appliesTo }),
+            });
+            if (decided.isError)
+                throw new Error(decided.text);
+            const data = jsonOf(decided);
+            const workId = data.work_id;
+            const note = input.decision === "approve"
+                ? `${input.reviewer.name}(${input.reviewer.role})が承認し、判断を ${data.decision_file} に記録した。Work ${workId} は続けられる。`
+                : `${input.reviewer.name}(${input.reviewer.role})が認めなかった。理由: ${input.interpretation}。Work ${workId} は続けられる。`;
+            events.push(local("prompt.expanded", { name: "review", source: "runtime", text: note }));
+            await record(id, "prompt.expanded", { name: "review", source: "runtime", text: note });
+            const got = await client.call("work_get", { id: workId });
+            const work = jsonOf(got);
+            if (work && !isTerminal(work.status)) {
+                candidate = { id: work.id, objective: work.objective, status: work.status };
+            }
+            return { workId, text: note };
+        },
+        async approvals() {
+            const listed = await client.call("approval_list", {});
+            if (listed.isError)
+                throw new Error(listed.text);
+            const { approvals } = jsonOf(listed);
+            return approvals.map((a) => ({
+                approvalId: a.approvalId,
+                workId: a.work_id,
+                name: a.call.name,
+                input: a.call.input,
+                ruleId: a.ruleId,
+                kind: a.kind,
+                ...(a.reviewer && { reviewer: a.reviewer }),
+            }));
+        },
         async close() {
             const selected = await client.call("work_select", { id });
             if (selected.isError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openshain/agent",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Tool loop and model providers (bring your own key)",
   "keywords": [
     "openshain",
@@ -30,7 +30,8 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "exports": {
     ".": {
@@ -51,12 +52,12 @@
   "dependencies": {
     "@anthropic-ai/sdk": "0.123.0",
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@openshain/core": "0.3.1",
+    "@openshain/core": "0.4.0",
     "openai": "7.10.0"
   },
   "devDependencies": {
-    "@openshain/mcp": "0.3.1",
-    "@openshain/tools": "0.3.1"
+    "@openshain/mcp": "0.4.0",
+    "@openshain/tools": "0.4.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -15,7 +15,10 @@ export {
   openaiCompatibleProvider,
 } from "./providers/openai-compatible.ts";
 export {
+  type ApprovalAnswer,
+  type ApprovalChoice,
   createSession,
+  type HeldApproval,
   type Session,
   type SessionOptions,
   TURN_LIMITS,

package/src/session.ts

@@ -13,6 +13,7 @@ import {
   type ModelResponse,
   newEventId,
   SESSION_WORK_TYPE,
+  type ToolContent,
   type ToolDefinition,
   type Work,
   type WorkId,
@@ -24,10 +25,42 @@ import { pickAgentName } from "./names.ts";
 export const TURN_LIMITS = { modelCalls: 25, toolCalls: 40 } as const;
 
 /** The tools of the runtime that the loop itself drives; the model never sees them. */
-const LOOP_ONLY_TOOLS: ReadonlySet<string> = new Set(["work_record", "work_answer"]);
+const LOOP_ONLY_TOOLS: ReadonlySet<string> = new Set([
+  "work_record",
+  "work_answer",
+  // Deciding is the person's, or a qualified reviewer's. A model that could call these would
+  // approve the very calls the policy held.
+  "approval_decide",
+  "review_decide",
+]);
 
-const ROLE =
-  "あなたはこの会社の社員エージェントとして、受付の役で、この人と話す。作業が要るときは work_create で Work を作り(objective は人の言葉で書き、会話で分かった前提を添える)、その Work の中で Tool を呼び、終わったら work_complete で summary を人の言葉で書いて閉じる。会話の中では Tool を呼べないので、ファイルの中身を見ないと答えられない質問も Work を作って調べる。件数や金額は Tool が返した値をそのまま書き、計算し直さない。/work resume で候補として示された Work は、人の依頼がその objective に沿うときだけ work_select で続ける。沿わなければ続けず、その旨を伝えて新しい Work を作るか work_list で探し直す。返答は端末の画面に出るので、Markdown の記法や絵文字は使わず、短い文で書く。過去の作業は work_list と work_get で答える。";
+/**
+ * What the conversation adds to the profession's own instructions. Written as sections, and as
+ * what to do rather than what to avoid: models differ in how much they say after a tool call,
+ * so the screen's side of the contract is stated here instead of left to a model's default.
+ */
+const ROLE = [
+  "# 画面",
+  "あなたの返答は端末の画面に出る。人に見えるのは、あなたが書いた文と、Tool 呼び出しの名前と引数の 1 行だけ。Tool が返した中身と、work_complete に書いた summary は人には見えない。依頼の答えは返答に書く。",
+  "",
+  "# 返答の書き方",
+  "- 結果から書く。前置き(「承知しました」)と後置き(「ご不明な点があれば」)は書かない",
+  "- 依頼が終わったターンでは、何をしたか、答えになる数字(件数、金額、書いたファイルの場所)を書く。次にできることがあれば 1 行で添える",
+  "- 見出し、箇条書き、番号、太字、コードブロック、引用が使える。画面がそのまま書式として描く。表は書式にならないので、箇条書きにする",
+  "- 数字は Tool が返した値をそのまま書く",
+  "- 長さは依頼の大きさに合わせる。1 行で足りる依頼には 1 行で答える",
+  "",
+  "# 仕事の進め方",
+  "- あなたは受付の役でこの人と話す。作業が要るときは work_create で Work を作り(objective は人の言葉で書き、会話で分かった前提を添える)、その Work の中で Tool を呼び、work_complete の summary に記録用の要約を書いて閉じる。summary は記録に残すもの、返答は人に伝えるもの",
+  "- 会話の中では Tool を呼べない。ファイルの中身を読まないと答えられない質問も、Work を作って調べる",
+  "- /work resume で候補として示された Work は、人の依頼がその objective に沿うときだけ work_select で続ける。沿わなければ続けず、その旨を伝えて新しい Work を作るか work_list で探し直す",
+  "- 過去の作業は work_list と work_get で答える",
+  "",
+  "# 承認と資格者の判断",
+  "- 承認が要る呼び出しは止まる。人が決めるまで待ち、同じ呼び出しを繰り返さない",
+  "- 実行しないと決められた呼び出しは、理由を読んで別の案を出す。同じ入力で呼び直さない",
+  "- 承認と判断は人と資格者の仕事で、あなたの仕事ではない",
+].join("\n");
 
 export interface SessionOptions {
   /** The model the conversation runs on. The client owns it; the runtime never calls one. */
@@ -40,9 +73,47 @@ export interface SessionOptions {
   onEvent?: (workId: WorkId, event: AnyEvent) => void | Promise<void>;
   /** Answers a question a work asks the person. Without it, the work waits for input. */
   onInput?: (workId: WorkId, question: string) => Promise<string>;
+  /**
+   * Asks the person about a call the policy held, while the turn waits. Without it, the turn
+   * ends and the call stays held for `/approve` or for another client.
+   */
+  onApproval?: (held: HeldApproval) => Promise<ApprovalAnswer>;
 }
 
-export type TurnStop = "turn_limit" | "aborted" | "max_tokens" | "refusal" | "model_error";
+export type TurnStop =
+  | "turn_limit"
+  | "aborted"
+  | "max_tokens"
+  | "refusal"
+  | "model_error"
+  | "approval";
+
+/** A tool call the policy holds until a person decides on it. */
+export interface HeldApproval {
+  approvalId: string;
+  workId: WorkId;
+  name: string;
+  input: unknown;
+  /** The rule that held it: the unit a person can say yes to for the rest of the conversation. */
+  ruleId: string;
+  /** review when a qualified reviewer has to decide; a person cannot stand in for one. */
+  kind: "approval" | "review";
+  reviewer?: { role: string; name?: string };
+}
+
+/**
+ * What the person answered about a held call. `always` approves this one and every later call
+ * the same rule holds, for this conversation only: nothing is written to authority/, and every
+ * call is still recorded as requested and decided.
+ */
+export type ApprovalChoice = "approve" | "always" | "reject";
+
+/** The person's answer: what they chose, and what they want the agent to know. */
+export interface ApprovalAnswer {
+  choice: ApprovalChoice;
+  /** Why, in the person's words. Recorded with the decision and handed to the model. */
+  comment?: string;
+}
 
 export interface TurnResult {
   /** What the model said to the person, possibly empty when the turn stopped early. */
@@ -52,6 +123,8 @@ export interface TurnResult {
   detail?: string;
   /** The work the turn left open, when it stopped inside one. It can be continued with select. */
   work?: WorkId;
+  /** The call held for approval, when the turn stopped for one. */
+  approval?: HeldApproval;
 }
 
 export interface Session {
@@ -62,6 +135,22 @@ export interface Session {
   turn(text: string, options?: { signal?: AbortSignal }): Promise<TurnResult>;
   /** Names a stopped work as the candidate for the next request. The model decides whether to continue it. */
   select(workId: WorkId): Promise<Work>;
+  /** Decides a held call as the person. approve runs it; either way the work becomes the candidate. */
+  decide(
+    approvalId: string,
+    decision: "approve" | "reject",
+    comment?: string,
+  ): Promise<{ workId: WorkId; text: string }>;
+  /** Records what a qualified reviewer decided about a call held for review. */
+  review(input: {
+    approvalId: string;
+    decision: "approve" | "reject";
+    reviewer: { name: string; role: string; qualification?: string };
+    interpretation: string;
+    appliesTo?: { action?: string; path?: string };
+  }): Promise<{ workId: WorkId; text: string }>;
+  /** The calls held for approval across the workspace. */
+  approvals(): Promise<HeldApproval[]>;
   /** The work the model is on right now, if any. */
   currentWork(): WorkId | undefined;
   /** Ends the conversation. The record stays; a work left in progress stays in progress. */
@@ -124,6 +213,17 @@ export async function createSession(
   );
   let task: TaskState | undefined;
   let candidate: { id: WorkId; objective: string; status: string } | undefined;
+  let held: HeldApproval | undefined;
+  /** Rules the person said yes to for the rest of this conversation. */
+  const standing = new Set<string>();
+
+  // The basics (time, business date, folder) enter the conversation as a recorded prompt, so the
+  // projection stays a function of the record. The model can refresh them with the context tool.
+  const basics = await client.call("context", {});
+  const info = basics.isError ? undefined : (jsonOf(basics) as Record<string, unknown> | undefined);
+  const basicsText = info
+    ? `現在時刻は ${info.now}(${info.timezone})、今日の業務日は ${info.business_date}。会社フォルダは ${info.workspace}。日付や時刻が要るときは context を呼ぶ。`
+    : undefined;
 
   /** Records one of the client's own events on a work through the runtime, and reports it. */
   const record = async <T extends EventType>(
@@ -148,6 +248,11 @@ export async function createSession(
     if (task) await record(task.id, type, payload);
   };
 
+  if (basicsText) {
+    events.push(local("prompt.expanded", { name: "context", source: "runtime", text: basicsText }));
+    await record(id, "prompt.expanded", { name: "context", source: "runtime", text: basicsText });
+  }
+
   const describedTools = async (): Promise<ToolDefinition[]> =>
     (await client.listTools()).filter((t) => !LOOP_ONLY_TOOLS.has(t.name));
 
@@ -246,9 +351,13 @@ export async function createSession(
           return { reply: text };
         case "tool_call": {
           const calls = response.message.content.filter((p) => p.type === "tool_call");
-          for (const call of calls) {
-            if (signal?.aborted) return { reply: text, stopped: "aborted" };
+          for (const [index, call] of calls.entries()) {
+            if (signal?.aborted) {
+              await closeRest(calls, index, "the turn stopped before this call ran");
+              return { reply: text, stopped: "aborted" };
+            }
             if (toolCalls >= TURN_LIMITS.toolCalls) {
+              await closeRest(calls, index, "the turn reached its limit before this call ran");
               return {
                 reply: text,
                 stopped: "turn_limit",
@@ -257,7 +366,18 @@ export async function createSession(
             }
             toolCalls += 1;
             const outcome = await callTool(call, signal);
-            if (outcome === "withdrawn") return { reply: text, stopped: "aborted" };
+            if (outcome === "withdrawn") {
+              await closeRest(calls, index + 1, "the turn stopped before this call ran");
+              return { reply: text, stopped: "aborted" };
+            }
+            if (outcome === "held" && held) {
+              await closeRest(
+                calls,
+                index + 1,
+                "the turn stopped for an approval before this call ran",
+              );
+              return { reply: text, stopped: "approval", approval: held };
+            }
           }
           break;
         }
@@ -283,18 +403,8 @@ export async function createSession(
   async function callTool(
     call: { id: string; name: string; input: unknown },
     signal: AbortSignal | undefined,
-  ): Promise<"done" | "withdrawn"> {
+  ): Promise<"done" | "withdrawn" | "held"> {
     const workId = task?.id ?? id;
-    // The loop drives these itself; a model that calls them is refused before the runtime sees it.
-    const refusal = LOOP_ONLY_TOOLS.has(call.name)
-      ? `${call.name} is the loop's own; it is not a tool for the model`
-      : !task && (call.name === "work_complete" || call.name === "work_fail")
-        ? `${call.name} needs a work of its own: no work is open; start one with work_create`
-        : undefined;
-    if (refusal) {
-      finish(call.id, { content: [{ type: "text", text: refusal }], isError: true, text: "" });
-      return "done";
-    }
     events.push(
       local("tool.called", {
         callId: call.id,
@@ -304,6 +414,20 @@ export async function createSession(
       }),
     );
     await options.onEvent?.(workId, events.at(-1) as AnyEvent);
+    // The loop drives these itself; a model that calls them is refused before the runtime sees it.
+    const refusal = LOOP_ONLY_TOOLS.has(call.name)
+      ? `${call.name} is the loop's own; it is not a tool for the model`
+      : !task && (call.name === "work_complete" || call.name === "work_fail")
+        ? `${call.name} needs a work of its own: no work is open; start one with work_create`
+        : undefined;
+    if (refusal) {
+      await finish(call.id, {
+        content: [{ type: "text", text: refusal }],
+        isError: true,
+        text: "",
+      });
+      return "done";
+    }
     const input =
       call.name === "work_create" && call.input && typeof call.input === "object"
         ? { ...(call.input as Record<string, unknown>), parent: id, agent_name: agentName }
@@ -348,7 +472,7 @@ export async function createSession(
       if (call.name === "work_select" && data.status === "waiting_input") {
         const answered = await answerPending(workId, signal);
         if (answered === "withdrawn") {
-          finish(call.id, result);
+          await finish(call.id, result);
           return "withdrawn";
         }
         if (answered.length > 0) {
@@ -383,7 +507,7 @@ export async function createSession(
           answer = await options.onInput(asked, question);
         } catch {
           // The person took the question back: the work stays waiting_input.
-          finish(call.id, {
+          await finish(call.id, {
             content: [{ type: "text", text: "the person withdrew the question; the work waits" }],
             isError: true,
             text: "",
@@ -400,11 +524,129 @@ export async function createSession(
           : { content: [{ type: "text", text: answer }], isError: false, text: answer };
       }
     }
-    finish(call.id, result);
+    if (!result.isError && (data?.pending === "approval" || data?.pending === "review") && task) {
+      const reviewer = data.reviewer as { role: string; name?: string } | undefined;
+      const pending: HeldApproval = {
+        approvalId: String(data.approval_id),
+        workId: task.id,
+        name: call.name,
+        input: call.input,
+        ruleId: String(data.rule_id ?? ""),
+        kind: data.pending === "review" ? "review" : "approval",
+        ...(reviewer && { reviewer }),
+      };
+      // A review needs a qualified person, so the turn stops whatever the screen can ask.
+      if (pending.kind === "review") {
+        held = pending;
+        await finish(call.id, {
+          content: [
+            {
+              type: "text",
+              text: `held for a review by a ${reviewer?.role ?? "reviewer"} (${pending.approvalId}); the work waits until the reviewer decides`,
+            },
+          ],
+          isError: false,
+          text: "",
+        });
+        return "held";
+      }
+      // With a way to ask, the person decides here and the turn goes on. Without one, the turn
+      // ends and the call stays held for /approve or for another client.
+      if (!options.onApproval) {
+        held = pending;
+        await finish(call.id, {
+          content: [
+            {
+              type: "text",
+              text: `held for approval ${pending.approvalId}; the person decides before the work goes on`,
+            },
+          ],
+          isError: false,
+          text: "",
+        });
+        return "held";
+      }
+      let answer: ApprovalAnswer;
+      if (pending.ruleId !== "" && standing.has(pending.ruleId)) {
+        answer = { choice: "approve" };
+      } else {
+        try {
+          answer = await options.onApproval(pending);
+        } catch {
+          // The person left it undecided: the work stays waiting_approval and the turn ends.
+          held = pending;
+          await finish(call.id, {
+            content: [
+              {
+                type: "text",
+                text: "the person left this call undecided; it is still waiting for their approval and the work stops here",
+              },
+            ],
+            isError: true,
+            text: "",
+          });
+          return "held";
+        }
+        if (answer.choice === "always" && pending.ruleId !== "") standing.add(pending.ruleId);
+      }
+      const standingNote =
+        answer.choice === "always"
+          ? `この会話では規則 ${pending.ruleId} を常に承認する、と決めた`
+          : undefined;
+      const comment = [answer.comment, standingNote].filter(Boolean).join(" / ");
+      const decided = await client.call(
+        "approval_decide",
+        {
+          approval_id: pending.approvalId,
+          decision: answer.choice === "reject" ? "reject" : "approve",
+          ...(comment !== "" && { comment }),
+        },
+        signal,
+      );
+      const outcome = jsonOf(decided) as
+        | { result?: { content: ToolContent[]; isError: boolean } }
+        | undefined;
+      if (decided.isError) {
+        // The work is still waiting; nothing the model does next can move it.
+        held = pending;
+        await finish(call.id, decided);
+        return "held";
+      }
+      if (answer.choice === "reject") {
+        const said = answer.comment ? ` They said: ${answer.comment}` : "";
+        await finish(call.id, {
+          content: [
+            {
+              type: "text",
+              text: `the person refused this call; it did not run and the work is not waiting for anyone.${said} Do not call it again unchanged: say what you would need, or propose another way.`,
+            },
+          ],
+          isError: true,
+          text: "",
+        });
+      } else {
+        await finish(call.id, {
+          content: outcome?.result?.content ?? [{ type: "text", text: "approved" }],
+          isError: outcome?.result?.isError ?? false,
+          text: "",
+        });
+      }
+      return "done";
+    }
+    await finish(call.id, result);
     if (!result.isError && (call.name === "work_complete" || call.name === "work_fail") && task) {
       const closed = task;
       task = undefined;
       foldAway(closed, call.id);
+      // The rule that matters most is stated where it is needed, not only in the system prompt:
+      // the work is closed and its summary went to the record, so the person has read nothing
+      // yet. Smaller models end the turn with an acknowledgement without this.
+      const note =
+        call.name === "work_complete"
+          ? `Work ${closed.id} を閉じた。summary は記録に残るだけで、人の画面には出ない。この後の返答で、何をしたかと結果の数字を人に伝える。`
+          : `Work ${closed.id} は失敗として閉じた。この後の返答で、どこまで進んで何が起きたかを人に伝える。`;
+      events.push(local("prompt.expanded", { name: "work closed", source: "runtime", text: note }));
+      await record(id, "prompt.expanded", { name: "work closed", source: "runtime", text: note });
       await options.onEvent?.(
         closed.id,
         local(
@@ -443,14 +685,25 @@ export async function createSession(
     return answers;
   }
 
-  function finish(callId: string, result: ClientResult): void {
+  /**
+   * Gives every call from `from` on a result, so that the projection stays well formed: a tool
+   * call without a result cannot be sent to a model, and the next turn would refuse to build.
+   */
+  async function closeRest(calls: { id: string }[], from: number, text: string): Promise<void> {
+    for (const call of calls.slice(from)) {
+      await finish(call.id, { content: [{ type: "text", text }], isError: true, text: "" });
+    }
+  }
+
+  async function finish(callId: string, result: ClientResult): Promise<void> {
     const event = local("tool.completed", {
       callId,
       content: result.content,
       isError: result.isError,
     });
     events.push(event);
-    void options.onEvent?.(task?.id ?? id, event);
+    // The screen draws from these in order, so the result waits for the caller as the call did.
+    await options.onEvent?.(task?.id ?? id, event);
   }
 
   /** Once a work is closed, only its summary stays in the conversation: the tool results are folded away. */
@@ -472,6 +725,7 @@ export async function createSession(
     id,
     agentName,
     async turn(text, turnOptions = {}) {
+      held = undefined;
       events.push(local("human.message", { text }));
       await record(id, "human.message", { text });
       if (candidate) {
@@ -504,6 +758,86 @@ export async function createSession(
       return work;
     },
     currentWork: () => task?.id,
+    async decide(approvalId, decision, comment) {
+      const decided = await client.call("approval_decide", {
+        approval_id: approvalId,
+        decision,
+        ...(comment !== undefined && { comment }),
+      });
+      if (decided.isError) throw new Error(decided.text);
+      const data = jsonOf(decided) as {
+        work_id: string;
+        result?: { content: { type: string; text?: string }[]; isError: boolean };
+      };
+      const workId = data.work_id as WorkId;
+      const outcome =
+        decision === "reject"
+          ? "拒否"
+          : data.result?.isError
+            ? `実行して失敗: ${data.result.content.map((c) => c.text ?? "").join("")}`
+            : "実行して成功";
+      const note = `承認 ${approvalId} を${decision === "approve" ? "承認" : "拒否"}した(${outcome})。Work ${workId} は続けられる。`;
+      events.push(local("prompt.expanded", { name: "approval", source: "runtime", text: note }));
+      await record(id, "prompt.expanded", { name: "approval", source: "runtime", text: note });
+      const got = await client.call("work_get", { id: workId });
+      const work = jsonOf(got) as Work | undefined;
+      if (work && !isTerminal(work.status)) {
+        candidate = { id: work.id, objective: work.objective, status: work.status };
+      }
+      return { workId, text: note };
+    },
+    async review(input) {
+      const decided = await client.call("review_decide", {
+        approval_id: input.approvalId,
+        decision: input.decision,
+        reviewer: input.reviewer,
+        interpretation: input.interpretation,
+        ...(input.appliesTo && { applies_to: input.appliesTo }),
+      });
+      if (decided.isError) throw new Error(decided.text);
+      const data = jsonOf(decided) as {
+        work_id: string;
+        decision_id?: string;
+        decision_file?: string;
+        result?: { isError: boolean };
+      };
+      const workId = data.work_id as WorkId;
+      const note =
+        input.decision === "approve"
+          ? `${input.reviewer.name}(${input.reviewer.role})が承認し、判断を ${data.decision_file} に記録した。Work ${workId} は続けられる。`
+          : `${input.reviewer.name}(${input.reviewer.role})が認めなかった。理由: ${input.interpretation}。Work ${workId} は続けられる。`;
+      events.push(local("prompt.expanded", { name: "review", source: "runtime", text: note }));
+      await record(id, "prompt.expanded", { name: "review", source: "runtime", text: note });
+      const got = await client.call("work_get", { id: workId });
+      const work = jsonOf(got) as Work | undefined;
+      if (work && !isTerminal(work.status)) {
+        candidate = { id: work.id, objective: work.objective, status: work.status };
+      }
+      return { workId, text: note };
+    },
+    async approvals() {
+      const listed = await client.call("approval_list", {});
+      if (listed.isError) throw new Error(listed.text);
+      const { approvals } = jsonOf(listed) as {
+        approvals: {
+          approvalId: string;
+          work_id: string;
+          ruleId: string;
+          kind: "approval" | "review";
+          reviewer?: { role: string; name?: string };
+          call: { name: string; input: unknown };
+        }[];
+      };
+      return approvals.map((a) => ({
+        approvalId: a.approvalId,
+        workId: a.work_id as WorkId,
+        name: a.call.name,
+        input: a.call.input,
+        ruleId: a.ruleId,
+        kind: a.kind,
+        ...(a.reviewer && { reviewer: a.reviewer }),
+      }));
+    },
     async close() {
       const selected = await client.call("work_select", { id });
       if (selected.isError) {