odai-dsh-agent 0.0.6 → 0.0.7

package/README.md

@@ -53,6 +53,22 @@ The controller calls `odai_routing_config` to persist that explicit choice. The
 
 Planner, executor, and reviewer are independent optional responsibilities. If any needed one has no mapping, high-impact work fails closed and remains read-only; lower-impact work continues only where it does not depend on the missing independent responsibility. Odai never chooses a model on the user's behalf.
 
+## Controller output policy
+
+The Agent defaults to **soft concise** output and shares three controller output modes with the Plugin. A user can naturally ask to inspect or change the mode; `odai_output_config` persists an explicit override in `$DSH_HOME/odai/output.json`:
+
+| Mode | Policy | Behavior |
+|---|---|---|
+| normal | `concise: false`, no `maxTokens` | use the host's normal presentation and controller budget |
+| soft concise (default) | `concise: true`, no `maxTokens` | shorten only the final user-facing presentation without relaxing required results, evidence, risks, blockers, or verification |
+| economy (optional) | `concise: true`, positive `maxTokens` | add a provider output-ceiling request; default to `500` when the user names economy without another value, or use the user's supplied positive value |
+
+Natural requests include `use normal output`, `use soft concise output`, `enable economy mode`, and `set economy mode to 1200 tokens`. Removing the persisted override restores soft concise. Existing pre-mode stores that combined `concise: false` with a ceiling remain readable for compatibility, but new named-mode changes cannot create that legacy combination. The selected mode is stable within one turn and changes from the next user turn.
+
+An economy ceiling only tightens an existing lower host request value and is not a locally enforceable hard billing boundary. A provider may count hidden reasoning inside it, exceed or ignore it, or end before useful final text, especially at a high reasoning effort; strict compliance must be checked from per-request usage. Odai enables economy only when requested and never invents a non-default custom value. The mode does not alter child-agent role budgets, compaction, checkpoints, or other internal context; an incomplete token-capped compaction fails closed instead of replacing history.
+
+A same-provider/model compaction that inherits controller reasoning also requests long prompt-cache retention while keeping its independent summary budget. Explicit compaction retention is preserved. `ODAI_COMPACTION_CACHE_RETENTION=provider-default` restores the host default; `short`, `long`, and `none` are also accepted deployment overrides. The first controller request after a landed summary still rebuilds the changed summary prefix.
+
 ## Skill sources
 
 The Agent keeps the managed preset's complete skill copy as its `bundled` default, so existing installations do not change behavior. When the user explicitly asks to show, set, or reset the Odai skill source, the controller uses `odai_skill_source_config` and stores the choice in `$DSH_HOME/odai/source.json`, outside the managed preset:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odai-dsh-agent",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "完整继承 DSH 标准模式 全部能力的 Odai Agent preset。主要用于治理、规划、测试、验证 等，可当成默认总控使用。",
   "license": "MIT",
   "repository": {

package/preset/odai/runtime/index.mjs

@@ -16,6 +16,7 @@ import {
   activeRouteProtection,
   createChildToolGuard,
   createRouteProtectionGuard,
+  isSubagent,
   summarizeToolResult,
 } from "./governance.mjs";
 import {
@@ -26,6 +27,14 @@ import {
   resolveRoleRoute,
   resolveRoutingConfigPath,
 } from "./routing-config.mjs";
+import {
+  DEFAULT_OUTPUT_POLICY,
+  createOutputConfigTool,
+  effectiveOutputPolicy,
+  renderOutputPolicyPrompt,
+  resolveOutputConfigPath,
+} from "./output-config.mjs";
+import { selectSharedOutputPolicyForTurn } from "./output-policy-state.mjs";
 import { createSessionEvidence, resolveSessionEvidenceRoot } from "./session-evidence.mjs";
 import {
   SKILL_SOURCE_CONFIG_PROMPT,
@@ -50,6 +59,7 @@ export const inject = ["systemPrompt", "tools", "subagents", "sessions"];
 
 const PLUGIN_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const ROUTING_MODES = new Set(["off", "observe", "auto", "execute"]);
+const COMPACTION_CACHE_RETENTIONS = new Set(["provider-default", "short", "long", "none"]);
 const ROUTED_ROLES = CONFIGURABLE_ROLES;
 const DEFAULT_ROUTING_MODE = "auto";
 
@@ -66,6 +76,8 @@ export function resolveConfig(rawConfig = {}) {
   const routing = assertPlainObject(raw.routing, "config.routing");
   const roles = assertPlainObject(routing.roles, "config.routing.roles");
   const governance = assertPlainObject(raw.governance, "config.governance");
+  const output = assertPlainObject(raw.output, "config.output");
+  const compaction = assertPlainObject(raw.compaction, "config.compaction");
   const mode = routing.mode ?? DEFAULT_ROUTING_MODE;
   const provider = routing.provider ?? "spawn";
   const maxInputChars = routing.maxInputChars ?? 12_000;
@@ -73,7 +85,13 @@ export function resolveConfig(rawConfig = {}) {
   const additionalDeniedTools = governance.additionalDeniedTools ?? [];
   const skillSource = governance.skillSource ?? "bundled";
   const skillConfigPath = resolveSkillSourceConfigPath(governance.skillConfigPath);
+  const outputConfigPath = resolveOutputConfigPath(output.configPath);
+  const compactionCacheRetention = compaction.cacheRetention
+    ?? process.env.ODAI_COMPACTION_CACHE_RETENTION
+    ?? "long";
   const unknownRoles = Object.keys(roles).filter((role) => !ROUTED_ROLES.includes(role));
+  const unknownOutputFields = Object.keys(output).filter((field) => field !== "configPath");
+  const unknownCompactionFields = Object.keys(compaction).filter((field) => field !== "cacheRetention");
 
   if (!ROUTING_MODES.has(mode)) {
     throw new TypeError("config.routing.mode must be off, observe, auto, or execute");
@@ -87,6 +105,15 @@ export function resolveConfig(rawConfig = {}) {
   if (unknownRoles.length > 0) {
     throw new TypeError(`config.routing.roles has unknown roles: ${unknownRoles.join(", ")}`);
   }
+  if (unknownOutputFields.length > 0) {
+    throw new TypeError(`config.output has unknown fields: ${unknownOutputFields.join(", ")}`);
+  }
+  if (unknownCompactionFields.length > 0) {
+    throw new TypeError(`config.compaction has unknown fields: ${unknownCompactionFields.join(", ")}`);
+  }
+  if (!COMPACTION_CACHE_RETENTIONS.has(compactionCacheRetention)) {
+    throw new TypeError("config.compaction.cacheRetention must be provider-default, short, long, or none");
+  }
   if (!Array.isArray(additionalDeniedTools)
     || additionalDeniedTools.some((tool) => typeof tool !== "string" || tool.trim() === "")) {
     throw new TypeError("config.governance.additionalDeniedTools must be an array of non-empty strings");
@@ -115,10 +142,12 @@ export function resolveConfig(rawConfig = {}) {
       skillSource,
       skillConfigPath,
     }),
+    output: Object.freeze({ configPath: outputConfigPath }),
+    compaction: Object.freeze({ cacheRetention: compactionCacheRetention }),
   });
 }
 
-export function inheritCompactionReasoning(options, sessions) {
+export function inheritCompactionReasoning(options, sessions, cacheRetention = "long") {
   if (options?.purpose !== "compaction"
     || options.reasoningEffort !== undefined
     || options.sessionId === undefined
@@ -135,6 +164,9 @@ export function inheritCompactionReasoning(options, sessions) {
   }
 
   options.reasoningEffort = route.reasoningEffort;
+  if (options.cacheRetention === undefined && cacheRetention !== "provider-default") {
+    options.cacheRetention = cacheRetention;
+  }
   return true;
 }
 
@@ -315,7 +347,7 @@ function canonicalPrompt(selection) {
     `Canonical skill: ${bundle.manifest.skillVersion}; runtime contract: ${bundle.manifest.runtimeContract}; digest: ${bundle.digest}.`,
     ...(fallback ? [fallback] : []),
     "Apply this governance to every request. Keep the controller as the final delivery owner; use another role only for a real independent gap with observable net benefit.",
-    "Odai governance is already loaded by this runtime; do not call the skill tool to load odai again.",
+    "Odai governance is already loaded by this runtime; do not call the skill tool or read SKILL.md to load odai again.",
     "",
     bundle.skillText,
   ].join("\n");
@@ -351,7 +383,7 @@ export function apply(ctx, rawConfig) {
   };
   const hasSessionEvent = (agent, type, predicate) => evidence.has(agent, type, predicate);
   ctx.on("llm/stream", (options, next) => {
-    inheritCompactionReasoning(options, ctx.sessions);
+    inheritCompactionReasoning(options, ctx.sessions, config.compaction.cacheRetention);
     return next();
   });
   const skillPath = resolveSkillPath(config.skillPath);
@@ -387,6 +419,11 @@ export function apply(ctx, rawConfig) {
     order: -18,
     text: SKILL_SOURCE_CONFIG_PROMPT,
   });
+  ctx.systemPrompt.section({
+    name: "odai:controller-output-policy",
+    order: -17,
+    text: "",
+  });
 
   const optionalSkillRegistry = () => {
     try {
@@ -422,12 +459,28 @@ export function apply(ctx, rawConfig) {
       skills: optionalSkillRegistry(),
     });
   };
+  const selectOutputForAgent = () => {
+    try {
+      return effectiveOutputPolicy(config.output.configPath);
+    } catch (error) {
+      logger.warn(`Odai output configuration is invalid; using the default policy: ${error instanceof Error ? error.message : String(error)}`);
+      return Object.freeze({
+        policy: DEFAULT_OUTPUT_POLICY,
+        source: "default",
+        status: "fallback",
+        reasonCode: "output-config-invalid",
+      });
+    }
+  };
   ctx.on("system-prompt/assemble", async (assembly, context, next) => {
     const downstream = await next();
     const agent = context.agent;
     if (!agent) return downstream;
     const selection = await selectSharedSkillForTurn(agent, () => selectForAgent(agent, context));
     const turn = currentAgentTurn(agent);
+    const outputSelection = isSubagentSession(agent)
+      ? Object.freeze({ policy: DEFAULT_OUTPUT_POLICY, source: "default" })
+      : await selectSharedOutputPolicyForTurn(agent, turn, selectOutputForAgent);
     const selectionEvidence = {
       ...(turn === undefined ? {} : { turn }),
       requestedMode: selection.mode,
@@ -445,11 +498,21 @@ export function apply(ctx, rawConfig) {
     if (selection.status === "fallback") {
       logger.warn(`Odai skill source ${selection.mode} fell back to bundled governance (${selection.reasonCode})`);
     }
+    const outputPrompt = renderOutputPolicyPrompt(outputSelection.policy);
+    if (outputPrompt && !hasSessionEvent(agent, "odai/output-policy-selected", (data) => data?.turn === turn)) {
+      appendEvent(agent, "odai/output-policy-selected", {
+        ...(turn === undefined ? {} : { turn }),
+        source: outputSelection.source,
+        policy: outputSelection.policy,
+      });
+    }
     return {
       ...downstream,
-      sections: downstream.sections.map((section) => section.name === "odai:canonical-governance"
-        ? { ...section, text: canonicalPrompt(selection) }
-        : section),
+      sections: downstream.sections.map((section) => {
+        if (section.name === "odai:canonical-governance") return { ...section, text: canonicalPrompt(selection) };
+        if (section.name === "odai:controller-output-policy") return { ...section, text: outputPrompt };
+        return section;
+      }),
     };
   });
 
@@ -499,6 +562,12 @@ export function apply(ctx, rawConfig) {
       },
     },
   ));
+  ctx.tools.register(createOutputConfigTool(config.output.configPath, {
+    isChild: isSubagent,
+    onConfigured(agent, data) {
+      appendEvent(agent, "odai/output-configured", data);
+    },
+  }));
   ctx.tools.guard((execution) => childGuard(execution) ?? routeProtectionGuard(execution));
 
   ctx.on("tools/result", (execution, result) => {
@@ -508,7 +577,7 @@ export function apply(ctx, rawConfig) {
     appendEvent(execution.agent, "odai/tool-observed", summary, logger);
   });
 
-  ctx.on("agent/request", async ({ agent, turn }, next) => {
+  ctx.on("agent/request", async ({ agent, turn, step }, next) => {
     const proposed = await next();
     const childRole = routedRoleOf(agent);
     const childRoleState = childRole ? configuredRole(childRole) : undefined;
@@ -518,16 +587,37 @@ export function apply(ctx, rawConfig) {
       : upgrade && upgrade.turn === turn
         ? upgrade.route
         : undefined;
-    if (!roleRoute) return proposed;
-
-    const { reasoningEffort: _inheritedEffort, ...withoutInheritedEffort } = proposed;
-    return Object.freeze({
-      ...withoutInheritedEffort,
-      provider: roleRoute.provider,
-      model: roleRoute.model,
-      ...(roleRoute.reasoningEffort === undefined ? {} : { reasoningEffort: roleRoute.reasoningEffort }),
-      ...(childRole && roleRoute.maxTokens !== undefined ? { maxTokens: roleRoute.maxTokens } : {}),
-    });
+    let request = proposed;
+    if (roleRoute) {
+      const { reasoningEffort: _inheritedEffort, ...withoutInheritedEffort } = proposed;
+      request = Object.freeze({
+        ...withoutInheritedEffort,
+        provider: roleRoute.provider,
+        model: roleRoute.model,
+        ...(roleRoute.reasoningEffort === undefined ? {} : { reasoningEffort: roleRoute.reasoningEffort }),
+        ...(childRole && roleRoute.maxTokens !== undefined ? { maxTokens: roleRoute.maxTokens } : {}),
+      });
+    }
+    if (childRole || isSubagentSession(agent)) return request;
+
+    const outputSelection = await selectSharedOutputPolicyForTurn(agent, turn, selectOutputForAgent);
+    const configuredMaxTokens = outputSelection.policy.maxTokens;
+    if (configuredMaxTokens === undefined) return request;
+    const priorMaxTokens = request.maxTokens;
+    const effectiveMaxTokens = priorMaxTokens === undefined
+      ? configuredMaxTokens
+      : Math.min(priorMaxTokens, configuredMaxTokens);
+    if (!hasSessionEvent(agent, "odai/output-budget-applied", (data) => data?.turn === turn && data?.step === step)) {
+      appendEvent(agent, "odai/output-budget-applied", {
+        turn,
+        ...(step === undefined ? {} : { step }),
+        configuredMaxTokens,
+        ...(priorMaxTokens === undefined ? {} : { priorMaxTokens }),
+        effectiveMaxTokens,
+        semantics: "provider-request-ceiling",
+      });
+    }
+    return Object.freeze({ ...request, maxTokens: effectiveMaxTokens });
   }, { prepend: true });
 
   const protectController = (agent, turn, step, decision, source, failure) => {

package/preset/odai/runtime/output-config.mjs

@@ -0,0 +1,304 @@
+import { randomUUID } from "node:crypto";
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+
+import { acquireOwnedStoreLock } from "./store-lock.mjs";
+
+const STORE_SCHEMA_VERSION = 1;
+const POLICY_FIELDS = new Set(["concise", "maxTokens"]);
+const OUTPUT_MODES = new Set(["normal", "concise", "economy"]);
+const DEFAULT_ECONOMY_MAX_TOKENS = 500;
+export const DEFAULT_OUTPUT_POLICY = Object.freeze({ concise: true });
+
+export class OutputPolicyStoreValidationError extends Error {}
+
+function assertPlainObject(value, field) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+  return value;
+}
+
+export function resolveOutputPolicy(value, field = "Odai output policy") {
+  const policy = assertPlainObject(value, field);
+  const unknown = Object.keys(policy).filter((name) => !POLICY_FIELDS.has(name));
+  if (unknown.length > 0) throw new TypeError(`${field} has unknown fields: ${unknown.join(", ")}`);
+  if (!Object.hasOwn(policy, "concise") || typeof policy.concise !== "boolean") {
+    throw new TypeError(`${field}.concise must be an own boolean property`);
+  }
+  if (policy.maxTokens !== undefined
+    && (!Number.isSafeInteger(policy.maxTokens) || policy.maxTokens <= 0)) {
+    throw new TypeError(`${field}.maxTokens must be a positive integer`);
+  }
+  return Object.freeze({
+    concise: policy.concise,
+    ...(policy.maxTokens === undefined ? {} : { maxTokens: policy.maxTokens }),
+  });
+}
+
+export function resolveOutputConfigPath(configuredPath, env = process.env) {
+  if (configuredPath !== undefined) {
+    if (typeof configuredPath !== "string" || configuredPath.trim() === "") {
+      throw new TypeError("config.output.configPath must be a non-empty string");
+    }
+    return resolve(configuredPath.trim());
+  }
+  const dshHome = typeof env.DSH_HOME === "string" && env.DSH_HOME.trim() !== ""
+    ? resolve(env.DSH_HOME.trim())
+    : resolve(homedir(), ".dsh");
+  return resolve(dshHome, "odai", "output.json");
+}
+
+export function readOutputPolicyStore(configPath) {
+  let text;
+  try {
+    text = readFileSync(configPath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return Object.freeze({ schemaVersion: STORE_SCHEMA_VERSION });
+    throw new Error(`cannot read Odai output configuration ${configPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new OutputPolicyStoreValidationError(`Odai output configuration ${configPath} is not valid JSON`, { cause: error });
+  }
+  try {
+    const store = assertPlainObject(parsed, `Odai output configuration ${configPath}`);
+    const unknown = Object.keys(store).filter((field) => !["schemaVersion", "policy"].includes(field));
+    if (unknown.length > 0) {
+      throw new TypeError(`Odai output configuration ${configPath} has unknown fields: ${unknown.join(", ")}`);
+    }
+    if (store.schemaVersion !== STORE_SCHEMA_VERSION) {
+      throw new TypeError(`Odai output configuration ${configPath} has unsupported schemaVersion ${String(store.schemaVersion)}`);
+    }
+    if (store.policy === undefined) return Object.freeze({ schemaVersion: STORE_SCHEMA_VERSION });
+    return Object.freeze({
+      schemaVersion: STORE_SCHEMA_VERSION,
+      policy: resolveOutputPolicy(store.policy, `Odai output configuration ${configPath}.policy`),
+    });
+  } catch (error) {
+    if (error instanceof OutputPolicyStoreValidationError) throw error;
+    throw new OutputPolicyStoreValidationError(
+      `Odai output configuration ${configPath} failed validation: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+export function effectiveOutputPolicy(configPath) {
+  const stored = readOutputPolicyStore(configPath);
+  return Object.freeze({
+    policy: stored.policy ?? DEFAULT_OUTPUT_POLICY,
+    source: stored.policy ? "persisted" : "default",
+  });
+}
+
+function writeOutputPolicyStore(configPath, policy) {
+  mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+  const temporary = `${configPath}.tmp-${process.pid}-${randomUUID()}`;
+  const value = `${JSON.stringify({ schemaVersion: STORE_SCHEMA_VERSION, policy }, null, 2)}\n`;
+  try {
+    writeFileSync(temporary, value, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    renameSync(temporary, configPath);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+function preserveInvalidStore(configPath) {
+  try {
+    renameSync(configPath, `${configPath}.invalid-${Date.now()}-${randomUUID()}`);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function resultFor(configPath, action, selection, recoveredInvalidStore = false) {
+  return {
+    action,
+    configPath,
+    policy: selection.policy,
+    source: selection.source,
+    requiresNextTurn: action !== "show",
+    ...(recoveredInvalidStore ? { recoveredInvalidStore: true } : {}),
+  };
+}
+
+export function renderOutputPolicyPrompt(policy) {
+  if (!policy.concise && policy.maxTokens === undefined) return "";
+  return [
+    "## Odai controller output policy",
+    ...(policy.concise ? [
+      "Keep the final user-facing response concise. Include only the result, decisive evidence, unresolved items, and necessary next action; omit routine process narration and repeated context unless the user explicitly asks for detail.",
+    ] : []),
+    ...(policy.maxTokens === undefined ? [] : [
+      `Each controller model request carries a provider output ceiling request of ${policy.maxTokens} tokens, which may include reasoning. Provider enforcement is not guaranteed; prioritize completion and finish before the requested ceiling.`,
+    ]),
+    "This policy applies only to controller requests and the final user-facing response. It never reduces child-agent, compaction, checkpoint, or other internal context budgets.",
+    "The policy changes presentation and the requested controller budget only; it never permits omitting required results, evidence, risks, blockers, or verification.",
+  ].join("\n");
+}
+
+function resolveSetPolicy(args) {
+  if (args.mode === undefined) {
+    if (args.concise === false && args.maxTokens !== undefined) {
+      throw new TypeError("maxTokens requires concise=true or mode=economy");
+    }
+    return resolveOutputPolicy({
+      concise: args.concise,
+      ...(args.maxTokens === undefined ? {} : { maxTokens: args.maxTokens }),
+    });
+  }
+  if (!OUTPUT_MODES.has(args.mode)) {
+    throw new TypeError("mode must be normal, concise, or economy");
+  }
+  if (args.concise !== undefined) {
+    throw new TypeError("concise must be omitted when mode is supplied");
+  }
+  if (args.mode !== "economy" && args.maxTokens !== undefined) {
+    throw new TypeError("maxTokens is accepted only with economy mode");
+  }
+  return resolveOutputPolicy({
+    concise: args.mode !== "normal",
+    ...(args.mode === "economy"
+      ? { maxTokens: args.maxTokens ?? DEFAULT_ECONOMY_MAX_TOKENS }
+      : {}),
+  });
+}
+
+export function createOutputConfigTool(configPath, options = {}) {
+  const onConfigured = typeof options.onConfigured === "function" ? options.onConfigured : () => {};
+  const isChild = typeof options.isChild === "function"
+    ? options.isChild
+    : (agent) => {
+      const header = agent?.session?.header;
+      return header?.origin === "subagent"
+        || (Number.isSafeInteger(header?.delegationDepth) && header.delegationDepth > 0);
+    };
+  return {
+    name: "odai_output_config",
+    description: [
+      "Inspect, set, or remove the shared Odai controller output policy; the package default is soft concise.",
+      "Normal mode is concise=false with no maxTokens; soft concise is concise=true with no maxTokens; economy mode is concise=true with a user-adjustable maxTokens request ceiling and defaults to 500 only when the user names economy without another value.",
+      "Use only when the user explicitly requests an output mode or supplies a custom maxTokens; never invent a non-default custom value. Remove restores soft concise.",
+      "Changes start next user turn. maxTokens is a provider request ceiling, not locally enforced; providers may include reasoning, exceed or ignore it, or truncate responses. Child-agent, compaction, checkpoint, and other internal budgets stay unchanged.",
+    ].join(" "),
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["action"],
+      properties: {
+        action: {
+          type: "string",
+          enum: ["show", "set", "remove"],
+        },
+        mode: {
+          type: "string",
+          enum: ["normal", "concise", "economy"],
+          description: "Preferred for set; economy defaults maxTokens to 500 unless the user supplies another positive value.",
+        },
+        concise: {
+          type: "boolean",
+          description: "Backward-compatible alternative for set; omit when mode is supplied.",
+        },
+        maxTokens: {
+          type: "integer",
+          description: "Optional positive replacement for economy mode's default 500-token provider request ceiling.",
+        },
+      },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["action", "configPath", "policy", "source", "requiresNextTurn"],
+        properties: {
+          action: { type: "string", enum: ["show", "set", "remove"] },
+          configPath: { type: "string" },
+          policy: {
+            type: "object",
+            additionalProperties: false,
+            required: ["concise"],
+            properties: {
+              concise: { type: "boolean" },
+              maxTokens: { type: "integer" },
+            },
+          },
+          source: { type: "string", enum: ["default", "persisted"] },
+          requiresNextTurn: { type: "boolean" },
+          recoveredInvalidStore: { type: "boolean" },
+        },
+      },
+      render(_args, value) {
+        const settings = [
+          `concise=${value.policy.concise ? "on" : "off"}`,
+          ...(value.policy.maxTokens === undefined ? [] : [`maxTokens=${value.policy.maxTokens}`]),
+        ].join(", ");
+        return [{
+          type: "text",
+          text: [
+            `${value.action === "show" ? "Current" : "Updated"} Odai controller output policy (${value.source}): ${settings}.`,
+            ...(value.policy.maxTokens === undefined ? [] : [" maxTokens is sent as a provider request ceiling; strict provider compliance is not guaranteed and must be checked from usage."]),
+            ...(value.recoveredInvalidStore ? [" An invalid prior store was preserved and replaced."] : []),
+            ...(value.requiresNextTurn ? [" The change applies from the next user turn."] : []),
+          ].join(""),
+        }];
+      },
+    },
+    execute(args, execution) {
+      if (!execution.agent) throw new Error("odai_output_config requires an owning agent session");
+      if (isChild(execution.agent)) throw new Error("child agents may not change Odai output configuration");
+      if (!args || typeof args !== "object" || Array.isArray(args)) throw new TypeError("arguments must be an object");
+      const unknown = Object.keys(args).filter((field) => !["action", "mode", "concise", "maxTokens"].includes(field));
+      if (unknown.length > 0) throw new TypeError(`unknown arguments: ${unknown.join(", ")}`);
+      if (!["show", "set", "remove"].includes(args.action)) throw new TypeError("action must be show, set, or remove");
+      if (args.action === "show") {
+        if (args.mode !== undefined || args.concise !== undefined || args.maxTokens !== undefined) {
+          throw new TypeError("mode, concise, and maxTokens must be omitted for show");
+        }
+        return Promise.resolve(resultFor(configPath, "show", effectiveOutputPolicy(configPath)));
+      }
+      if (args.action === "remove"
+        && (args.mode !== undefined || args.concise !== undefined || args.maxTokens !== undefined)) {
+        throw new TypeError("mode, concise, and maxTokens must be omitted for remove");
+      }
+      const proposed = args.action === "set" ? resolveSetPolicy(args) : undefined;
+
+      const releaseLock = acquireOwnedStoreLock(configPath, "Odai output configuration");
+      try {
+        let recoveredInvalidStore = false;
+        try {
+          readOutputPolicyStore(configPath);
+        } catch (error) {
+          if (!(error instanceof OutputPolicyStoreValidationError)) {
+            throw new Error("Odai output configuration could not be read safely; no changes were made", { cause: error });
+          }
+          recoveredInvalidStore = preserveInvalidStore(configPath);
+        }
+        if (args.action === "set") writeOutputPolicyStore(configPath, proposed);
+        else rmSync(configPath, { force: true });
+        const selection = args.action === "set"
+          ? Object.freeze({ policy: proposed, source: "persisted" })
+          : Object.freeze({ policy: DEFAULT_OUTPUT_POLICY, source: "default" });
+        onConfigured(execution.agent, {
+          action: args.action,
+          policy: selection.policy,
+          ...(recoveredInvalidStore ? { recoveredInvalidStore: true } : {}),
+        });
+        return Promise.resolve(resultFor(configPath, args.action, selection, recoveredInvalidStore));
+      } finally {
+        releaseLock();
+      }
+    },
+  };
+}

package/preset/odai/runtime/output-policy-state.mjs

@@ -0,0 +1,37 @@
+const SHARED_OUTPUT_POLICY_STATE = Symbol.for("odai.dsh.output-policy-state.v1");
+
+function sharedStore() {
+  if (!globalThis[SHARED_OUTPUT_POLICY_STATE]) {
+    Object.defineProperty(globalThis, SHARED_OUTPUT_POLICY_STATE, {
+      configurable: false,
+      enumerable: false,
+      writable: false,
+      value: Object.freeze({ selections: new WeakMap() }),
+    });
+  }
+  return globalThis[SHARED_OUTPUT_POLICY_STATE];
+}
+
+function generationFor(turn) {
+  return Number.isSafeInteger(turn) && turn >= 0 ? turn : "unknown";
+}
+
+export async function selectSharedOutputPolicyForTurn(agent, turn, select) {
+  if (!agent || typeof agent !== "object") throw new TypeError("an agent is required for Odai output policy selection");
+  if (typeof select !== "function") throw new TypeError("an Odai output policy selector is required");
+  const generation = generationFor(turn);
+  const store = sharedStore();
+  const existing = store.selections.get(agent);
+  if (existing?.generation === generation) return existing.promise;
+
+  const state = { generation };
+  state.promise = Promise.resolve().then(select).then((selection) => {
+    state.selection = selection;
+    return selection;
+  }).catch((error) => {
+    if (store.selections.get(agent) === state) store.selections.delete(agent);
+    throw error;
+  });
+  store.selections.set(agent, state);
+  return state.promise;
+}

package/preset/odai/runtime/store-lock.mjs

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+function readLockOwner(lockPath) {
+  try {
+    const value = readFileSync(lockPath, "utf8").trim();
+    const separator = value.indexOf(":");
+    const pid = Number(separator < 0 ? "" : value.slice(0, separator));
+    return Number.isSafeInteger(pid) && pid > 0 && separator < value.length - 1
+      ? { value, pid }
+      : undefined;
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== "ESRCH";
+  }
+}
+
+function createLock(lockPath, owner) {
+  const handle = openSync(lockPath, "wx", 0o600);
+  try {
+    const content = Buffer.from(`${owner}\n`, "utf8");
+    if (writeSync(handle, content, 0, content.length) !== content.length) {
+      throw new Error(`short write while acquiring Odai configuration lock: ${lockPath}`);
+    }
+    fsyncSync(handle);
+    return handle;
+  } catch (error) {
+    closeSync(handle);
+    rmSync(lockPath, { force: true });
+    throw error;
+  }
+}
+
+function releaseLock(handle, lockPath, owner) {
+  closeSync(handle);
+  const current = readLockOwner(lockPath);
+  if (current === undefined) throw new Error(`Odai configuration lock disappeared before release: ${lockPath}`);
+  if (current.value !== owner) throw new Error(`Odai configuration lock ownership changed before release: ${lockPath}`);
+  rmSync(lockPath);
+}
+
+export function acquireOwnedStoreLock(path, label) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const lockPath = `${path}.lock`;
+  const claimPath = `${lockPath}.claim`;
+  const owner = `${process.pid}:${randomUUID()}`;
+  const claimOwner = `${process.pid}:${randomUUID()}`;
+  let claimHandle;
+  try {
+    claimHandle = createLock(claimPath, claimOwner);
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw new Error(`${label} lock acquisition is already in progress; retry the tool call`);
+    }
+    throw error;
+  }
+
+  let handle;
+  try {
+    try {
+      handle = createLock(lockPath, owner);
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const current = readLockOwner(lockPath);
+      if (current === undefined || processIsAlive(current.pid)) {
+        throw new Error(`${label} is being updated; retry the tool call`);
+      }
+      rmSync(lockPath);
+      handle = createLock(lockPath, owner);
+    }
+  } finally {
+    try {
+      releaseLock(claimHandle, claimPath, claimOwner);
+    } catch (error) {
+      if (handle !== undefined) {
+        try {
+          releaseLock(handle, lockPath, owner);
+        } catch {}
+        handle = undefined;
+      }
+      throw error;
+    }
+  }
+
+  if (handle === undefined) throw new Error(`could not lock ${label}`);
+  return () => releaseLock(handle, lockPath, owner);
+}