pi-roundtable 0.15.2 → 0.15.4

package/CHANGELOG.md

@@ -5,6 +5,18 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.15.4] - 2026-10-15
+
+### Changed
+
+- With `discord.agentSpeakers: "owners"`, a schedule whose turn would run below the owner tier no longer starts its precheck or its container: the scheduler asks the channel's claim before the precheck, and the run is recorded `skipped:` with the reason the turn would have been skipped with (`the agent server answers owners only (speakers: "owners")`). A new optional `ChannelClaim.backgroundRefusal(turn)` answers that for a claim, with the turn and the speaker the router checked; `ConversationPort.runsAs` and `ChannelRouter.runsAs` now include it, and the agent server's claim uses it for its own `background` skips (the owner target only, no groups, owners only). A claim without it is unaffected.
+
+## [0.15.3] - 2026-10-15
+
+### Added
+
+- `effortPolicy` in the configuration (`EffortPolicy`, `EffortRequest` and `EffortRule` in `pi-roundtable/kit`): a host chooses, per turn that thinks at the judge's choice, how the level is decided. The policy gets the turn's `channel`, `kind`, `agent` and `origin` and answers `{ fixed: level }` to run the turn at that level without asking the judge, `{ requiredMass: [0, medium, high, xhigh] }` to run the highest level whose share of the judge's answer at or above it meets its entry (the previous turn's level does not carry over, and a judge that fails gives low), or `undefined` for the default. The `kind` of an agent-server agent's turn is `"agent"`. A `requiredMass` that is not four finite numbers in [0, 1], or a policy that throws, fails the turn with a clear error. Without a policy nothing changes.
+
 ## [0.15.2] - 2026-10-15
 
 ### Fixed

package/docs/plugins.md

@@ -80,7 +80,7 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
   Two adapters log each skip as `Jev leaves the compaction to Pi's summary` with `reason`, `detail` and `tokensBefore` through the `logger` they take: `jevCompactionExtension({ logger, ...options })`, the `compaction` session tool's extension, placed as `session.compaction.wrap(jevCompactionExtension({ logger }))` under the engine `JEV_COMPACTION_ENGINE` (`pi-jev-compaction`), and `jevCompactor({ logger, ...options })`, a `JevCompactor` for pi-roundtable-sandbox's `compaction` option that returns the compaction or `undefined` and logs with the `channel`.
   A `no_key` skip is logged once per adapter, as `Jev is not configured, so compaction uses Pi's summary`, and then not again; every other skip is logged each time.
   The types are `JevCompactInput`, `JevCompactOptions`, `JevCompactOutcome`, `JevCompactor`, `JevCompactRequest`, `JevExtensionOptions` and `JevSkipReason`.
-- Effort: `effortJudge` picks a turn's thinking level from a message with your own brief (`EffortBrief`, `JUDGE_WORK`).
+- Effort: `effortJudge` picks a turn's thinking level from a message with your own brief (`EffortBrief`, `JUDGE_WORK`). A host that wants other turns decided differently sets `effortPolicy` (an `EffortPolicy`) in its configuration: it gets the turn's `channel`, `kind`, `agent` and `origin` and answers `{ fixed: level }` (no judge call), `{ requiredMass: [0, medium, high, xhigh] }` (the highest level whose share of the judge's answer at or above it meets its entry; the previous level does not carry over and a failed judge gives low), or `undefined` for the default. The `kind` of an agent-server agent's turn is `"agent"`; a policy that throws, or a `requiredMass` that is not four finite numbers in [0, 1], fails the turn.
 - Presentation and small helpers: `thinkingLine`, `zonedStamp(date, timeZone)`, `channelQueue()` (a queue of your own, so work does not wait behind a running turn), `checkRepoName` and `SKILL_LIST_TOOL` with `skillListExtension` for repositories and skills, and `searchTerms` for memory search.
 
 The [coding package source][coding-source] shows these helpers in an out-of-process Pi worker.
@@ -1238,7 +1238,7 @@ pi-roundtable-sandbox's `precheckScriptRunner` runs each script in a sealed cont
 - `schedule_create` and `schedule_update` take `precheck_script`, a JavaScript module of at most `PRECHECK_SCRIPT_CHARS` (8,000) characters with a default export; it is parsed, never run, when it is set. A schedule has a `precheck` or a `precheck_script`; setting one removes the other, and `null` removes either.
 - The runner's `run(script, context)` gets the `PrecheckScriptContext`: the schedule, `firedAt`, `tier`, `signal`, the host's `timeZone`, and `today`, the date there. `tier` is the tier the run is for: the schedule's, capped at what its creator holds now, as its turn would run. Its answer is checked like a named precheck's, and its finding is named `script`.
 - `describe({ channel, target, tier })` (a `PrecheckScope`) tells the model how to write one and what it may call there; `schedule_list` shows it, waiting at most 10 seconds. `tier` is the asker's there and the run's `tier` when it runs, so a runner may grant lower tiers less.
-- Before a schedule's precheck, named or a script, the scheduler checks who its turn would run as, as `ConversationPort.runsAs` does: a creator who may not run it now, such as one disabled, runs no precheck, and the run is recorded `skipped:` with the reason.
+- Before a schedule's precheck, named or a script, the scheduler checks who its turn would run as, as `ConversationPort.runsAs` does: a creator who may not run it now, such as one disabled, runs no precheck, and the run is recorded `skipped:` with the reason. The claim that owns the channel is asked too (`ChannelClaim.backgroundRefusal`): with `discord.agentSpeakers: "owners"`, a schedule whose turn would run below the owner tier starts no precheck and no container, and is recorded with the same reason its turn would have been skipped with.
 - When the host stops, the scheduler aborts running scripts and waits up to 15 seconds for the runner to clean up; a precheck that ends then starts no turn.
 - Without a runner, the tools neither take nor mention `precheck_script`, a script is refused with the registered names, and a schedule that already has one wakes with `### Precheck failed: script`, never a silent skip.
 
@@ -3847,6 +3847,9 @@ Import from the entries listed below; source area files are internal.
 | `EffortJudgeOptions` | `pi-roundtable/kit` | type |
 | `EffortLevel` | `pi-roundtable/kit` | type |
 | `EffortPicker` | `pi-roundtable/kit` | type |
+| `EffortPolicy` | `pi-roundtable/kit` | type |
+| `EffortRequest` | `pi-roundtable/kit` | type |
+| `EffortRule` | `pi-roundtable/kit` | type |
 | `GroupMessage` | `pi-roundtable/kit` | type |
 | `JUDGE_WORK` | `pi-roundtable/kit` | value |
 | `McpEndpoint` | `pi-roundtable/kit` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.15.2",
+	"version": "0.15.4",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",
@@ -65,7 +65,7 @@
 		"canvas": "3.2.3",
 		"discord.js": "14.27.0",
 		"pi-jev-compaction": "1.0.0",
-		"pi-mcp-adapter": "5.0.0",
+		"pi-mcp-adapter": "5.2.0",
 		"pino": "10.4.0",
 		"typebox": "1.3.34",
 		"unpdf": "1.8.1"
@@ -78,6 +78,6 @@
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.2",
 		"pi-self-compact": "0.2.0",
-		"pi-web-access": "0.35.0"
+		"pi-web-access": "0.39.0"
 	}
 }

package/src/core/agents/agent-claim.ts

@@ -7,6 +7,7 @@ import {
 import type {
 	Admission,
 	BackgroundTarget,
+	BackgroundTurn,
 	ChannelClaim,
 	InboundMessage,
 } from "../contract/channels.ts";
@@ -19,7 +20,7 @@ import { PERSONAL_TARGET } from "../modules/background/personal-target.ts";
 import { withReference } from "../routing/message-text.ts";
 import { outcome } from "../routing/settle-turn.ts";
 import { systemTurn } from "../routing/system-turns.ts";
-import { addressee, attributed } from "../speakers.ts";
+import { addressee, attributed, type Speaker } from "../speakers.ts";
 import type { DiscordAgentTeam } from "./agent-team.ts";
 import { discordIdOf } from "./team-keys.ts";
 
@@ -104,6 +105,19 @@ export function agentClaim(options: AgentClaimOptions): ChannelClaim {
 		}
 	};
 
+	/** Why the agent server would skip a background turn for its checked speaker; the turn's own skips. */
+	const backgroundRefusal = (
+		turn: BackgroundTurn & { speaker: Speaker },
+	): string | undefined => {
+		// Fail closed: a turn for any target but the owner's never reaches the owner's tools.
+		if (turn.target !== PERSONAL_TARGET.name)
+			return `the agent server answers only "${PERSONAL_TARGET.name}" background turns`;
+		if (team.owns(turn.channel) === "group") return "groups have no schedules";
+		if (options.speakers === "owners" && turn.speaker.tier !== "owner")
+			return 'the agent server answers owners only (speakers: "owners")';
+		return undefined;
+	};
+
 	const webhookReport = (message: InboundMessage): Admission | undefined => {
 		const text = message.text.trim();
 		if (!text) return undefined;
@@ -201,16 +215,8 @@ export function agentClaim(options: AgentClaimOptions): ChannelClaim {
 				failure: "agent message handling failed",
 			};
 		},
+		backgroundRefusal,
 		background: async (turn) => {
-			// Fail closed: a turn for any target but the owner's never reaches the owner's tools.
-			if (turn.target !== PERSONAL_TARGET.name)
-				return {
-					status: "skipped",
-					reason: `the agent server answers only "${PERSONAL_TARGET.name}" background turns`,
-				};
-			const owned = team.owns(turn.channel);
-			if (owned === "group")
-				return { status: "skipped", reason: "groups have no schedules" };
 			// Who the turn runs as, checked by the router: its author's principal, at a tier they hold.
 			const { speaker } = turn;
 			if (!speaker)
@@ -219,11 +225,8 @@ export function agentClaim(options: AgentClaimOptions): ChannelClaim {
 					reason:
 						"a background turn reaches the agent server through the router, which says whom it runs as",
 				};
-			if (options.speakers === "owners" && speaker.tier !== "owner")
-				return {
-					status: "skipped",
-					reason: 'the agent server answers owners only (speakers: "owners")',
-				};
+			const reason = backgroundRefusal({ ...turn, speaker });
+			if (reason !== undefined) return { status: "skipped", reason };
 			return outcome(
 				await team.answerBackground(
 					turn.channel,

package/src/core/config/config.ts

@@ -8,6 +8,7 @@ import { isLocale, type Locale } from "../i18n/index.ts";
 import type { AccessRules } from "../identity/access-policy.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import {
+	type EffortPolicy,
 	type ModelRef,
 	parseModelRef,
 	THINKING_LEVELS,
@@ -109,6 +110,8 @@ export interface RoundtableConfig {
 	thinking?: ThinkingLevel;
 	/** The model that judges small questions and the delegated tasks' model; default the agents' model. */
 	judge?: { model?: string; threshold?: number };
+	/** How each turn that thinks at the judge's choice is decided, instead of the default; see `EffortPolicy`. */
+	effortPolicy?: EffortPolicy;
 	delegation?: { model?: string; thinking?: ThinkingLevel };
 	/** The language of what the bot shows in Discord; default "en". */
 	locale?: Locale;
@@ -200,6 +203,8 @@ const tierMembers = shape({
 	everyone: optional(bool),
 });
 
+const isPolicy = (value: unknown): value is EffortPolicy =>
+	typeof value === "function";
 const isPlugin = (value: unknown): value is RoundtablePlugin =>
 	typeof value === "object" &&
 	value !== null &&
@@ -225,6 +230,9 @@ const schema = shape({
 	judge: optional(
 		shape({ model: optional(text), threshold: optional(number(0, 1)) }),
 	),
+	effortPolicy: optional(
+		guarded("a function from a turn to its effort rule", isPolicy),
+	),
 	delegation: optional(
 		shape({
 			model: optional(text),
@@ -320,6 +328,7 @@ export interface ResolvedConfig {
 	model: ModelRef;
 	thinking: ThinkingLevel;
 	judge: { model: ModelRef; threshold: number };
+	effortPolicy?: EffortPolicy;
 	delegation: { model: ModelRef; thinking: ThinkingLevel };
 	locale: Locale;
 	timeZone: string;
@@ -443,6 +452,7 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 				: model,
 			threshold: config.judge?.threshold ?? 0.6,
 		},
+		...(config.effortPolicy ? { effortPolicy: config.effortPolicy } : {}),
 		delegation: {
 			model: config.delegation?.model
 				? modelOf(config.delegation.model, "delegation.model")

package/src/core/contract/channels.ts

@@ -197,6 +197,15 @@ export interface ChannelClaim {
 	admit(message: InboundMessage): Admission | undefined;
 	/** A background turn in an owned channel; a claim without one skips them. */
 	background?(turn: BackgroundTurn): Promise<ScheduledOutcome>;
+	/**
+	 * Why `background` would skip the turn for its checked speaker, without running it; undefined
+	 * when it would not. The router asks it in `runsAs`, so work that must not happen for a turn
+	 * the claim will skip, such as a schedule's precheck, does not start. It decides from the turn
+	 * and its speaker alone, and its reasons are the ones `background` skips with.
+	 */
+	backgroundRefusal?(
+		turn: BackgroundTurn & { speaker: Speaker },
+	): string | undefined;
 	/** Starts the channel's conversation over, saying whose it was. */
 	startFresh(channel: ChannelKey): Promise<string>;
 	/**
@@ -230,7 +239,8 @@ export interface ConversationPort {
 	background(turn: BackgroundTurn): Promise<ScheduledOutcome>;
 	/**
 	 * Who a background turn would run as now, checked as `background` checks it, without running
-	 * it: for work that must not happen for an author who may not run the turn, such as a
+	 * it: for work that must not happen for an author who may not run the turn, or one the channel's
+	 * claim would skip for that speaker (an agent server that answers owners only), such as a
 	 * schedule's precheck. Throws when the identity service cannot tell.
 	 */
 	runsAs(turn: BackgroundTurn): Promise<BackgroundRunsAs>;

package/src/core/define-roundtable.ts

@@ -329,6 +329,7 @@ export async function defineRoundtable(
 				model: config.model,
 				thinking: config.thinking,
 				judgeThreshold: config.judge.threshold,
+				...(config.effortPolicy ? { effortPolicy: config.effortPolicy } : {}),
 				agents: agentSessions,
 				interimText: config.interimText,
 				interimPrimaryChars: config.interimPrimaryChars,

package/src/core/judging/effort-judge.ts

@@ -72,6 +72,7 @@ export interface EffortPicker<Fallback extends ThinkingLevel = ThinkingLevel> {
 	judge(
 		message: string,
 		previous?: PreviousTurn<EffortLevel | Fallback>,
+		rule?: { requiredMass: readonly [number, number, number, number] },
 	): Promise<EffortLevel | Fallback>;
 }
 
@@ -96,6 +97,7 @@ export class EffortJudge<Fallback extends ThinkingLevel = ThinkingLevel>
 	async judge(
 		message: string,
 		previous: PreviousTurn<EffortLevel | Fallback> = {},
+		rule?: { requiredMass: readonly [number, number, number, number] },
 	): Promise<EffortLevel | Fallback> {
 		const { judge, brief, fallback, threshold, logger } = this.#options;
 		try {
@@ -113,10 +115,13 @@ export class EffortJudge<Fallback extends ThinkingLevel = ThinkingLevel>
 					criteria: brief.criteria,
 				},
 			);
-			const from = EFFORT_LEVELS.indexOf(previous.level as EffortLevel);
+			// A rule picks each turn on its own: the previous turn's level does not carry over.
+			const from = rule
+				? -1
+				: EFFORT_LEVELS.indexOf(previous.level as EffortLevel);
 			const index =
 				from === -1
-					? levelIndex(probabilities)
+					? levelIndex(probabilities, rule?.requiredMass)
 					: moveIndex(from, probabilities, threshold);
 			const level =
 				index === from && previous.level
@@ -128,7 +133,7 @@ export class EffortJudge<Fallback extends ThinkingLevel = ThinkingLevel>
 			);
 			return level;
 		} catch (error) {
-			const level = previous.level ?? fallback;
+			const level = rule ? "low" : (previous.level ?? fallback);
 			logger.warn({ err: error, level }, "effort request failed");
 			return level;
 		}
@@ -140,11 +145,14 @@ export class EffortJudge<Fallback extends ThinkingLevel = ThinkingLevel>
  * meets REQUIRED_MASS. Below the top level that is the median of an ordinal answer, which
  * unlike the mean never lands on a middle level nothing voted for.
  */
-export function levelIndex(probabilities: readonly number[]): number {
+export function levelIndex(
+	probabilities: readonly number[],
+	requiredMass: readonly number[] = REQUIRED_MASS,
+): number {
 	let reached = 0;
 	for (let index = probabilities.length - 1; index > 0; index--) {
 		reached += probabilities[index] ?? 0;
-		if (reached >= (REQUIRED_MASS[index] ?? 0.5)) return index;
+		if (reached >= (requiredMass[index] ?? 0.5)) return index;
 	}
 	return 0;
 }

package/src/core/models.ts

@@ -1,4 +1,5 @@
 import { messages } from "./i18n/index.ts";
+import type { ChannelKey } from "./sessions.ts";
 /** Models and thinking levels as Pi names them, and the settings built on them. */
 
 export type ThinkingLevel =
@@ -43,10 +44,40 @@ export function parseModelRef(text: string): ModelRef | undefined {
 export const formatModelRef = (model: ModelRef): string =>
 	`${model.provider}/${model.id}`;
 
+/** What a host's effort policy is told about a turn that thinks at the judge's choice. */
+export interface EffortRequest {
+	/** Where the turn's message arrived, as `<surface>:<channel id>`. */
+	channel: ChannelKey;
+	/** The conversation's kind, as a claim's `startFresh` set it; "agent" for an agent-server agent's turn; absent otherwise (an owner's turn). */
+	kind?: string;
+	/** The agent-server agent's name, for an agent's turn. */
+	agent?: string;
+	/** Where the request came from, as the transport knows it; see `TurnRequest.origin`. */
+	origin?: string;
+}
+
+/**
+ * How one turn's level is chosen, instead of the default. `fixed` runs the turn at that level
+ * without asking the judge. `requiredMass` asks the judge and runs the highest level whose share
+ * of the answer at or above it meets its entry (index 0 is low and never read; 1 medium, 2 high,
+ * 3 xhigh, each a finite number in [0, 1], else the turn fails); the previous turn's level does not
+ * carry over, and a judge that fails gives low.
+ */
+export type EffortRule =
+	| { fixed: ThinkingLevel }
+	| { requiredMass: readonly [number, number, number, number] };
+
+/**
+ * Picks the rule of a turn, or undefined for the default (sticky judging with the host's threshold).
+ * A policy that throws, or returns an invalid `requiredMass`, fails that turn.
+ */
+export type EffortPolicy = (request: EffortRequest) => EffortRule | undefined;
+
 /** Picks one turn's thinking level from its message and the previous turn's reply and level. */
 export interface ThinkingPicker {
 	judge(
 		message: string,
 		previous?: { reply?: string; level?: ThinkingLevel },
+		rule?: Exclude<EffortRule, { fixed: ThinkingLevel }>,
 	): Promise<ThinkingLevel>;
 }

package/src/core/routing/channel-router.ts

@@ -336,10 +336,23 @@ export class ChannelRouter implements ConversationPort {
 	/**
 	 * Who a background turn runs as: the system principal for the host's own turn, at its tier;
 	 * otherwise its author's principal, which must exist, be enabled, and hold a tier now, at the
-	 * lower of the turn's tier and theirs. Why not, when it may not run; throws when the identity
+	 * lower of the turn's tier and theirs; and the claim that owns the channel must not refuse it
+	 * for that speaker (`backgroundRefusal`). Why not, when it may not run; throws when the identity
 	 * service cannot tell.
 	 */
 	async runsAs(turn: BackgroundTurn): Promise<BackgroundRunsAs> {
+		const runs = await this.#speakerOf(turn);
+		if ("skipped" in runs) return runs;
+		// The claim that owns the channel has the last word, so work that must not start for a turn it
+		// would skip, such as a schedule's precheck, does not.
+		const refusal = this.#owner(turn.channel)?.backgroundRefusal?.({
+			...turn,
+			speaker: runs.speaker,
+		});
+		return refusal === undefined ? runs : { skipped: refusal };
+	}
+
+	async #speakerOf(turn: BackgroundTurn): Promise<BackgroundRunsAs> {
 		const { author, tier } = turn;
 		if (!author?.principalId || !tier)
 			return {

package/src/core/runtime/pi-agent-runtime.ts

@@ -151,6 +151,7 @@ export class PiAgentRuntime implements AgentRuntime {
 			{
 				modelRuntime: this.#modelRuntime,
 				effort: this.#options.effort,
+				policy: this.#options.effortPolicy,
 				judged: this.#sessions.judged,
 			},
 			key,

package/src/core/runtime/runtime-plugin.ts

@@ -12,6 +12,7 @@ import type { OwnerIdentity } from "../identity.ts";
 import type { PromptScope } from "../interactions/prompts.ts";
 import { AGENT_BRIEF, EffortJudge } from "../judging/effort-judge.ts";
 import {
+	type EffortPolicy,
 	formatModelRef,
 	type ModelRef,
 	type ThinkingLevel,
@@ -69,6 +70,8 @@ export interface RuntimePluginOptions {
 	thinking: ThinkingLevel;
 	/** How sure the effort judge must be before its answer is used. */
 	judgeThreshold: number;
+	/** Picks a rule per turn instead of the judge's default; see `EffortPolicy`. */
+	effortPolicy?: EffortPolicy;
 	/** The agent server's settings, bound when it sets up; without a slot no agent turn runs. */
 	agents?: AgentSessionsSlot;
 	/** Whether turns post the text they write before their final answer as they go; default "on". */
@@ -159,6 +162,9 @@ export function runtimePlugin(
 						dataDir: options.dataDir,
 						model: options.model,
 						thinking: options.thinking,
+						...(options.effortPolicy
+							? { effortPolicy: options.effortPolicy }
+							: {}),
 						effort: new EffortJudge({
 							judge: providers.judge,
 							brief: AGENT_BRIEF,

package/src/core/runtime/runtime-types.ts

@@ -13,7 +13,7 @@ import type { Principal } from "../identity/principal-store.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import type { PromptScope, Prompts } from "../interactions/prompts.ts";
 import type { Logger } from "../log.ts";
-import type { ThinkingLevel, ThinkingPicker } from "../models.ts";
+import type { EffortPolicy, ThinkingLevel, ThinkingPicker } from "../models.ts";
 import type { LinkedSessions } from "../plugin.ts";
 import {
 	planOrder,
@@ -60,6 +60,8 @@ export interface PiAgentRuntimeOptions {
 	thinking: ThinkingLevel;
 	/** Picks the level of the assistant's turns and of agents whose thinking is `auto`. */
 	effort: ThinkingPicker;
+	/** Chooses a turn's rule for the picker, or a fixed level; absent = the judge decides alike for every turn. */
+	effortPolicy?: EffortPolicy;
 	/** Held actions survive a restart here, so a confirmation after one still runs. */
 	confirmations: Pick<PendingConfirmationStore, "load" | "save">;
 	logger: Logger;

package/src/core/runtime/thinking-level.ts

@@ -4,7 +4,11 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { ChannelKey } from "../domain/conversation.ts";
 import type { TurnRequest } from "../domain/ports.ts";
-import { AUTO_THINKING, type ThinkingLevel } from "../models.ts";
+import {
+	AUTO_THINKING,
+	type EffortPolicy,
+	type ThinkingLevel,
+} from "../models.ts";
 import {
 	type AgentModelSettings,
 	useChosenAgentModel,
@@ -12,6 +16,20 @@ import {
 import type { PiAgentRuntimeOptions } from "./runtime-types.ts";
 import { lastReply } from "./turn-answer.ts";
 
+function checkRequiredMass(mass: readonly number[]): void {
+	if (
+		!Array.isArray(mass) ||
+		mass.length !== 4 ||
+		!mass.every(
+			(n) => typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= 1,
+		)
+	) {
+		throw new Error(
+			`effortPolicy requiredMass must be four finite numbers in [0, 1], got ${JSON.stringify(mass)}`,
+		);
+	}
+}
+
 /** Uses the checked model snapshot; auto thinking keeps the last pick while the judge is unsure. */
 export async function thinkingLevel(
 	parts: {
@@ -19,6 +37,8 @@ export async function thinkingLevel(
 		effort: PiAgentRuntimeOptions["effort"];
 		/** The level last judged for each conversation. */
 		judged: Map<ChannelKey, ThinkingLevel>;
+		/** The host's rule for a turn that thinks at the judge's choice. */
+		policy?: EffortPolicy | undefined;
 	},
 	key: ChannelKey,
 	session: AgentSession,
@@ -38,10 +58,23 @@ export async function thinkingLevel(
 		judged.delete(key);
 		return setting;
 	}
-	const level = await effort.judge(request.text, {
-		reply: lastReply(session.messages),
-		level: judged.get(key),
+	const kind = request.kind ?? (request.agent ? "agent" : undefined);
+	const rule = parts.policy?.({
+		channel: request.channel,
+		...(kind !== undefined ? { kind } : {}),
+		...(request.agent ? { agent: request.agent.name } : {}),
+		...(request.origin !== undefined ? { origin: request.origin } : {}),
 	});
+	if (rule && "requiredMass" in rule) checkRequiredMass(rule.requiredMass);
+	if (rule && "fixed" in rule) {
+		judged.delete(key);
+		return rule.fixed;
+	}
+	const level = await effort.judge(
+		request.text,
+		{ reply: lastReply(session.messages), level: judged.get(key) },
+		rule,
+	);
 	judged.set(key, level);
 	return level;
 }

package/src/kit/index.ts

@@ -133,6 +133,9 @@ export type {
 	ChannelMessage,
 	DashboardBoard,
 	DelegationWorker,
+	EffortPolicy,
+	EffortRequest,
+	EffortRule,
 	GroupMessage,
 	Notifier,
 	OwnerNotifier,

package/src/kit/support.ts

@@ -14,7 +14,12 @@ export type { Backlog, GroupMessage } from "../core/agents/agent-rules.ts";
 export type { AgentOps } from "../core/agents/agent-tools.ts";
 export type { ThreadHost } from "../core/discord/dispatch-threads.ts";
 export type { Notifier, OwnerNotifier } from "../core/domain/ports.ts";
-export type { ThinkingPicker } from "../core/models.ts";
+export type {
+	EffortPolicy,
+	EffortRequest,
+	EffortRule,
+	ThinkingPicker,
+} from "../core/models.ts";
 export type { DelegationWorker } from "../core/modules/delegation/delegator.ts";
 export type { AgentChannelLookup } from "../core/modules/schedules/schedules.ts";
 export type { AssistantLike } from "../core/shared/session-messages.ts";