@sema-agent/server 1.322.0 → 2.0.0

package/dist/task-settings.js

@@ -1,12 +1,64 @@
+/**
+ * TaskRequest.settings wire — project a client's per-request `SemaSettings` stamp onto the per-task `TaskSpec`,
+ * TIGHTEN-ONLY (deny-wins), at the SAME seam as runtime-governance (after the approval baseline + operator
+ * governance). Backs the remote-mode settings path: sema runs over HTTP→engine with no local Runner, so the
+ * resolved settings can't be applied by a local `tightenTaskSpec` — they ride on `TaskRequest.settings` and the
+ * SERVICE projects them into the engine here.
+ *
+ * Design: `TaskRequest.settings` is a
+ * PER-REQUEST ephemeral stamp = the v2-design TASK layer (a single-run override, NOT durable). It folds into THIS
+ * spec via {@link tightenTaskSpec} and that is all — it is NEVER written to the durable `SessionPolicyStore` (the
+ * operator/principal axis, design/99 §E6, a different trust axis + lifecycle). Re-applying on a resume leg is
+ * idempotent (the same tighten), so no special resume handling is needed (mirrors runtime-governance).
+ *
+ * 🔒 SECURITY INVARIANTS (SDK settings.ts §3.3):
+ *  - permissions are TIGHTEN-ONLY — folded via `tightenTaskSpec` (deny-wins `combinePolicies`); it THROWS on any
+ *    override that would LOOSEN a stricter base safety field. The client can only ADD denies/asks/handsReadOnly on
+ *    top of the deployment + operator baseline, never widen it.
+ *  - permissionMode(轴B #2 注释保鲜,1.254——[816]/[820] 后的真实现):`defaultMode` 收**五**模式
+ *    (default | acceptEdits | plan | bypassPermissions | auto),bypass/auto 被 HONOR 为 gate-shape 选择
+ *    ——但深层不变量未变:bypass=「不加 ask 门」,恒不越部署基线(tightenTaskSpec deny-wins,基线 deny/
+ *    ask 照压);精化语义见 :2xx 行内注释。旧头注的「NEVER honored/三模式白名单」是 pre-[816] 拍照。
+ *
+ * 🔴 SYNC WITH shell `src/sema/settings/seam.ts`: the permissions→toolPolicy + §6.4 permissionMode derive MIRRORS
+ * the shell's LOCAL-Runner resolver — both compose the SAME core primitives (`createAllowDenyPolicy` /
+ * `combinePolicies` / `tightenTaskSpec`), so the deny-wins ENFORCEMENT is core-single-source. Only the COMPOSITION
+ * is duplicated for the remote path; a proposed follow-up extracts it to `@sema-agent/sdk` for true
+ * single-source. Because the core backstops (deny-wins + tighten-throws-on-loosen + this bypass-reject) hold either
+ * way, a composition drift would be a local/remote CONSISTENCY gap, never a privilege escalation.
+ *
+ * v1 scope: `permissions` + `permissions.defaultMode` + `model` + `outputStyle` + `env` (shipped 1.26.0). DEFERRED
+ * (need a seam, flagged to the team + advertised in capabilities so a caller never silently loses a setting):
+ *  - (`env` is NO LONGER deferred — systematic-audit doc fix: core kept no untrusted `TaskSpec.env` seam (types §7
+ *    Q4), so the SERVICE applies it on the TRUSTED host lane: `settings.env` → `cleanEnvMap` → `shellEnv` on the
+ *    executionEnvFactory, single-user-gated. See `deriveSettings` below + main.ts.)
+ *  - (`hooks` NO LONGER deferred either — 轴B #2 注释保鲜:applied 形已接线(本文件 hooks 分片 +
+ *    main.ts 单用户闸),仅 malformed 才报 deferred;旧「需要 remote hook-runner」是接线前拍照。)
+ */
 import { combinePolicies, createAllowDenyPolicy, createFsWriteGatePolicy, createSensitivePathPolicy, canonicalToolName, tightenTaskSpec, resolveReasoningProfile, rankOf, isThinkingLevel, CYBER_RISK, URL_SAFETY, HARNESS_SECTION_ANCHOR, } from "@sema-agent/core";
 import { parseHooksConfig } from "./hooks/hook-runner.js";
+/**
+ * R4: coerce a raw top-level `body.permissionMode` (the LIGHT per-turn wire — the shell sends the
+ * CC permission mode RAW, axis-agnostic; the service interprets) to a service-honored mode, or undefined.
+ * 🔴 TIGHTEN-ONLY vs the DEPLOYMENT baseline still holds for every value: the mode only selects the CLIENT-derived
+ * gate ({@link deriveSettingsPolicy}); it can never subtract from the deployment/operator policy (applyTaskSettings
+ * folds via tightenTaskSpec, deny-wins). Post-[816] the value set is CC's five modes verbatim — `acceptEdits`,
+ * `bypassPermissions` and `auto` are now HONORED as gate-shape choices (they no longer coerce to `default`, which
+ * would FORCE the manual ask gate onto a caller that explicitly asked for less asking — with the gate live, the old
+ * coercion would have been a behavior change for them, incl. a headless-deny regression for bypass callers). An
+ * UNKNOWN string still coerces to `default` (fail-safe: the most-asking mode).
+ */
 export function coercePermissionMode(raw) {
     if (raw === "plan" || raw === "acceptEdits" || raw === "default" || raw === "bypassPermissions" || raw === "auto")
         return raw;
     if (typeof raw === "string" && raw.length > 0)
-        return "default";
-    return undefined;
+        return "default"; // unknown → default (the most-asking mode, never a widening)
+    return undefined; // absent → no opinion (don't touch the spec)
 }
+/** L2 ultracode (design/111): the effective `thinking` level given the explicit `reasoningEffort` and the ultracode
+ *  preset. ultracode FLOORS at the "ultra" tier — core's single source `resolveReasoningProfile("ultra").thinking`
+ *  (= "max"), never a hardcoded literal — so an explicit higher tier still wins (none exists above max today;
+ *  future-proof). Awareness rides for free: core composes ORCHESTRATION_AWARENESS from thinking∈{xhigh,max}, no field. */
 export function effectiveThinking(reasoningEffort, ultracode) {
     const explicit = isThinkingLevel(reasoningEffort) ? reasoningEffort : undefined;
     if (!ultracode)
@@ -14,15 +66,25 @@ export function effectiveThinking(reasoningEffort, ultracode) {
     const ultra = resolveReasoningProfile("ultra").thinking;
     return explicit && rankOf(explicit) > rankOf(ultra) ? explicit : ultra;
 }
+/** R4: fold a top-level `body.permissionMode` onto the parsed settings as `permissions.defaultMode` (the top-level
+ *  field is the explicit per-turn intent → it WINS over a bundle defaultMode). Creates a minimal settings object when
+ *  no `body.settings` bundle was sent. The result flows through {@link applyTaskSettings} (tighten-only). */
 export function withPermissionMode(settings, mode) {
     const base = settings ?? {};
     return { ...base, permissions: { ...base.permissions, defaultMode: mode } };
 }
+/** Cap on `outputStyle` length — it lands in the system prompt, so it shares the `MAX_SYSTEM_PROMPT_CHARS` (16384)
+ *  posture (an uncapped prompt body is a per-turn token-cost hole; adversarial review). Exported so the HTTP layer
+ *  (prepareSpec) can 400 fail-loud on submit with the SAME bound this defensive parse enforces on every path. */
 export const MAX_SETTINGS_OUTPUT_STYLE_CHARS = 16_384;
+/** Cap on the element count of each permission list (allow/deny/ask) — bounds a pathological rule blast. */
 export const MAX_SETTINGS_PERMISSION_RULES = 1_000;
+/** Caps on `settings.env` — bound a pathological env blast (count + per-value length; values land in the shell env). */
 export const MAX_SETTINGS_ENV_VARS = 256;
 export const MAX_SETTINGS_ENV_VALUE_CHARS = 32_768;
 export const MAX_SETTINGS_ENV_KEY_CHARS = 256;
+/** A `Record<string,string>` of non-empty string keys → string values (capped), or undefined. Untrusted input →
+ *  defensive (drop non-string entries, over-long values, and bound the count). */
 function cleanEnvMap(v) {
     if (v === null || typeof v !== "object" || Array.isArray(v))
         return undefined;
@@ -31,7 +93,7 @@ function cleanEnvMap(v) {
     let seen = 0;
     for (const [k, val] of Object.entries(v)) {
         if (n >= MAX_SETTINGS_ENV_VARS || seen >= MAX_SETTINGS_ENV_VARS * 8)
-            break;
+            break; // bound BOTH accepted + total iterated (adversarial-review LOW)
         seen++;
         if (typeof k === "string" && k.length > 0 && k.length <= MAX_SETTINGS_ENV_KEY_CHARS && typeof val === "string" && val.length <= MAX_SETTINGS_ENV_VALUE_CHARS) {
             out[k] = val;
@@ -40,17 +102,29 @@ function cleanEnvMap(v) {
     }
     return n > 0 ? out : undefined;
 }
+/** A string[] of non-empty strings (capped at {@link MAX_SETTINGS_PERMISSION_RULES}), or undefined. Untrusted input
+ *  → defensive (drop non-strings/empties; cap the count). */
 function cleanStringArray(v) {
     if (!Array.isArray(v))
         return undefined;
     const out = v.filter((x) => typeof x === "string" && x.length > 0).slice(0, MAX_SETTINGS_PERMISSION_RULES);
     return out.length > 0 ? out : undefined;
 }
+/**
+ * Validate an untrusted `body.settings` (raw `unknown` off the wire) into the service-trusted {@link
+ * ParsedTaskSettings}. NEVER trusts the wire type — every field is shape-checked; unknown keys are ignored
+ * (forward-compatible, matching the SDK's open `[k: string]: unknown`). `defaultMode` accepts the FIVE modes
+ * (post-[816]; unknown values coerce to `default` — see the header note). Returns the
+ * present-but-deferred field names so the caller can warn/advertise rather than silently dropping `env`/`hooks`.
+ */
 export function parseTaskSettings(raw) {
     if (raw === null || raw === undefined || typeof raw !== "object")
         return { deferred: [] };
     const s = raw;
     const deferred = [];
+    // `hooks` is NO LONGER deferred(hook-runner 阶段一):契约校验(registry-core HooksConfig +
+    // 服务侧上限)通过 → 进 applied 形状,由 apply 侧单用户闸决定翻不翻;malformed → 报 deferred(镜像 env 的
+    // present-but-malformed 姿势——本函数是 resume 等路径的防御层,submit 路径另有 fail-loud 400)。
     let hooksConfig;
     if (s.hooks !== undefined && s.hooks !== null) {
         const parsedHooks = parseHooksConfig(s.hooks);
@@ -61,7 +135,7 @@ export function parseTaskSettings(raw) {
     }
     const shellEnv = cleanEnvMap(s.env);
     if (s.env !== undefined && s.env !== null && shellEnv === undefined)
-        deferred.push("env");
+        deferred.push("env"); // present but malformed/empty → report
     const out = {};
     const perms = s.permissions;
     if (perms !== null && typeof perms === "object") {
@@ -69,6 +143,10 @@ export function parseTaskSettings(raw) {
         const allow = cleanStringArray(p.allow);
         const deny = cleanStringArray(p.deny);
         const ask = cleanStringArray(p.ask);
+        // 🔒 whitelist the five CC modes; any other value is dropped (absent = no opinion). `bypassPermissions` is
+        // accepted post-[816] because it now means "do not ADD the mode-derived fs-write ask gate" — exactly every
+        // mode's pre-[816] behavior — and can never subtract from the deployment baseline (tightenTaskSpec deny-wins;
+        // the module-header §3.3 invariant is thereby REFINED, not weakened: bypass still cannot LOOSEN anything).
         const mode = p.defaultMode;
         const defaultMode = mode === "default" || mode === "acceptEdits" || mode === "plan" || mode === "bypassPermissions" || mode === "auto" ? mode : undefined;
         if (allow || deny || ask || defaultMode) {
@@ -77,11 +155,15 @@ export function parseTaskSettings(raw) {
     }
     if (typeof s.model === "string" && s.model.length > 0)
         out.model = s.model;
+    // outputStyle is appended to the system prompt → cap it (defense in depth; prepareSpec 400s an over-cap value on
+    // submit, this drops it on any path the HTTP gate didn't cover, e.g. a resume of a pre-cap stored body).
     if (typeof s.outputStyle === "string" && s.outputStyle.length > 0 && s.outputStyle.length <= MAX_SETTINGS_OUTPUT_STYLE_CHARS) {
         out.outputStyle = s.outputStyle;
     }
     if (shellEnv)
         out.shellEnv = shellEnv;
+    // L2 ultracode preset (design/111): a CC-parity boolean. Only `true` opts in; any other value is ignored (a settings
+    // bundle that ONLY sets ultracode still returns `settings` via the hasApplied OR below).
     if (s.ultracode === true)
         out.ultracode = true;
     if (hooksConfig)
@@ -89,12 +171,33 @@ export function parseTaskSettings(raw) {
     const hasApplied = out.permissions !== undefined || out.model !== undefined || out.outputStyle !== undefined || out.shellEnv !== undefined || out.ultracode !== undefined || out.hooks !== undefined;
     return { settings: hasApplied ? out : undefined, deferred };
 }
+/** Defensive acceptance of the `appendSystemPrompt` rider ([1478] R2 + codex F2): the HTTP 400 gate (prepareSpec,
+ *  MAX_SYSTEM_PROMPT_CHARS) only covers FRESH submits — every resume family re-enters resolveSpec on a STORED body,
+ *  and a pre-1.243 store preserved unknown request keys verbatim (the field was INERT then), so an over-cap legacy
+ *  value must not become active prompt content after rollout (context exhaustion / spend hole). Over-cap ⇒ dropped +
+ *  warned — the rider was inert pre-upgrade, so dropping preserves the stored task's prior behavior; a 4xx here would
+ *  permanently brick that task's resume instead (same defensive posture as parseTaskSettings' outputStyle drop).
+ *  Cap value = the submit gate's (16384; MAX_SETTINGS_OUTPUT_STYLE_CHARS — both land in the same spec field). */
+/** TRUE when `text` is an ALREADY-ASSEMBLED system prompt — core's migration guard detects the same three
+ *  constitution anchors and takes the pass-through assembler arm, whose section subset (OPAQUE_KEPT, dist-read)
+ *  has NO `core/role.append`: any append rider (top-level or settings.outputStyle) would be SILENTLY discarded
+ *  there. Shared predicate for the submit 400 gate, the resolveSpec resume mirror, and the center-declaration
+ *  probe — one definition so the three gates can't drift. */
 export function hasConstitutionAnchors(text) {
     return typeof text === "string" && text.includes(CYBER_RISK) && text.includes(URL_SAFETY) && text.includes(HARNESS_SECTION_ANCHOR);
 }
+/** codex R9 (provider-aware append-less detection): mirrors core's ACTUAL pass-through triggers instead of a raw
+ *  body-text heuristic — the assembler's migration guard probes (a) `stableBlocks` identity declarations and
+ *  (b) `stableSystem` OUTPUT for the three anchors; a plain `userSystemPrompt` under the DEFAULT provider (no
+ *  scenario provider) never triggers it and `core/role.append` is retained, so an anchored systemPrompt there
+ *  must NOT block/strip a rider (R9 false-positive: unbranded default / scan rejected valid combos). Probing
+ *  calls the provider hooks with a minimal ctx — server providers (and centerPromptProvider) are pure functions
+ *  of ctx, and the same hooks run again inside core's assembly; a hook throw = conservative false (core will
+ *  fail the task loudly on its own). `replaceAll` owns the whole prompt(legacy free-form `system()` 腿已随 core 2.0.0 删除)
+ *  (REPLACE_ALL_EXCLUDED strips role.append) → append-less true. */
 export function providerDropsAppend(provider, userSystemPrompt) {
     if (!provider)
-        return false;
+        return false; // core defaultPromptProvider — role.append always retained
     if (provider.replaceAll === true)
         return true;
     const ctx = { userSystemPrompt, tools: [], memoryEnabled: false, consolidationEnabled: false };
@@ -114,11 +217,11 @@ export function providerDropsAppend(provider, userSystemPrompt) {
             return false;
         }
     }
-    return false;
+    return false; // core 2.0.0 删除了 legacy free-form `system()` 腿(不存在的腿不需要探测)——结构化 provider 到此都保 append
 }
 export function acceptAppendSystemPrompt(v, warn, packDropsAppend) {
     if (v === undefined)
-        return undefined;
+        return undefined; // absent = the only QUIET arm (codex R8: defined-but-malformed must warn)
     if (typeof v !== "string" || v.length === 0) {
         warn?.(`appendSystemPrompt dropped: defined but malformed (${typeof v === "string" ? "empty string" : `non-string: ${typeof v}`}) — fresh submits 400 this shape; a stored resume body carrying it is normalized to absent`);
         return undefined;
@@ -127,13 +230,26 @@ export function acceptAppendSystemPrompt(v, warn, packDropsAppend) {
         warn?.(`appendSystemPrompt dropped: ${v.length} chars exceeds the ${MAX_SETTINGS_OUTPUT_STYLE_CHARS} cap (pre-cap stored body on a resume leg?)`);
         return undefined;
     }
+    // codex R2/R3/R9: `packDropsAppend` = the caller's PROVIDER-AWARE append-less verdict ({@link
+    // providerDropsAppend} over the effective provider / center snapshot — NOT a raw body-text heuristic, which
+    // false-positived on default-provider scenarios where core retains role.append). Fresh submits 400 the combo
+    // in resolveSpec; this is the resume-family mirror — the rider was INERT pre-1.243, so dropping WITH a warn
+    // preserves the stored task's prior behavior and leaves an audit trail. (core typed error at the assembly
+    // boundary = the structural endgame, requested on the board.)
     if (packDropsAppend === true) {
         warn?.("appendSystemPrompt dropped: the effective prompt pack cannot mount the append rider (assembled-identity/stableSystem pass-through, replaceAll, or legacy provider — no core/role.append section)");
         return undefined;
     }
     return v;
 }
+/** A name-keyed ASK-list ToolPolicy: a tool whose NAME is in `askNames` tightens to `ask` (HITL gate); every other
+ *  tool is out of scope (`allow`). core's `createAllowDenyPolicy` has only allow/deny slots (no `ask`), so the
+ *  CC-parity `permissions.ask` list — "prompt the human before THIS tool" — needs this thin policy. Composed
+ *  deny-wins with the allow/deny base, so `ask` only ever tightens (a baseline `deny` still wins; `allow`→`ask`). */
 function createAskListPolicy(askNames) {
+    // Canonical-space matching, mirroring core's `createAllowDenyPolicy` (1.202): a rule written against a legacy
+    // alias ("MultiEdit"/"Task") keeps asking after a CC-parity rename, and a durable-resume replay carrying a
+    // pre-rename `req.toolName` can't slip a rule written in the new names (ask only ever tightens — widening-safe).
     const askSet = new Set(askNames.map(canonicalToolName));
     return {
         check(req) {
@@ -141,28 +257,53 @@ function createAskListPolicy(askNames) {
                 ? { action: "ask", message: `tool "${req.toolName}" requires approval by your settings`, decisionReason: "rule" }
                 : { action: "allow" };
         },
+        // [931]③ core 1.300 名单池审计面:自定义 closure 无元数据曾是审计盲区(`ask:["*"]`/typo 名静默
+        // no-op)——附 nameSets 后 core prepare 对实挂宇宙交叉核,无匹配名 → onError config.toolpolicy.
+        // unmatched_names(enforcement 字节不变,纯观测)。core combinePolicies 全链透传。
         nameSets: [{ ask: askNames }],
     };
 }
+/** [1245]/[1247]③ — the mode-derived dynamic-workflow ask gate (CC "Run a dynamic workflow?" dialog, engine half).
+ *  core mounts `run_workflow` with effect="write" and NO exemption in the gate stack, but the mode-derived leg here
+ *  only ever gated fs writes — so manual/default mode ran workflows un-asked ([1245] clay dogfood). This leg keys
+ *  the canonical name (`Workflow`; run_workflow/RunWorkflow aliases fold in via canonicalToolName on BOTH sides)
+ *  and attaches on default/auto/acceptEdits, independent of the fs-gate wiring (workflow gating is not
+ *  fs-dependent — sandbox lanes get it too). acceptEdits asks ON PURPOSE: CC's acceptEdits auto-allows file edits
+ *  only, a workflow confirmation is not an edit ([1248]② — cli to verify against the 212 live shell; flip there
+ *  if the real shell differs). bypassPermissions/undefined-mode attach nothing (pre-existing behavior); plan is
+ *  blocked upstream by handsReadOnly (effect="write"). Deployment disable stays `RuntimeCaps.allowWorkflows` —
+ *  this leg is the per-request HITL gate, not the capability switch. */
 const WORKFLOW_ASK_NAMES = ["Workflow"];
 function createWorkflowAskPolicy(isExempt) {
     return {
         async check(req) {
             if (canonicalToolName(req.toolName) !== "Workflow")
                 return { action: "allow" };
+            // codex F2 (durable lane): the "don't ask again this session" grant (decide remember="session" →
+            // approvalExemptionStore) is probed at the POLICY layer here — the durable lane parks every policy `ask`
+            // and its own exempt probe only covers the deployment policy's asks, so without this probe a remembered
+            // Workflow approval would re-park on every later call. Same posture as the fs-write gate's isExempt
+            // (canonical toolName key space, one grant serves all layers); a THROWN probe ⇒ not exempt (fail-closed).
             if (isExempt) {
                 try {
                     if (await isExempt(canonicalToolName(req.toolName)))
                         return { action: "allow", decisionReason: "rule" };
                 }
                 catch {
+                    /* fail-closed: keep asking */
                 }
             }
             return { action: "ask", message: `dynamic workflow "${req.toolName}" requires approval in this permission mode`, decisionReason: "rule" };
         },
-        nameSets: [{ ask: WORKFLOW_ASK_NAMES }],
+        nameSets: [{ ask: WORKFLOW_ASK_NAMES }], // [931]③ audit face, same as createAskListPolicy
     };
 }
+/** codex F1 (plan-mode escape): `run_workflow` mounts off self-orchestration INDEPENDENT of the hands band
+ *  (core prepare-task dist 亲读:handsReadOnly only strips/reads the hand tools; the runtime plan blocker
+ *  `planModeRef` starts INACTIVE and only the model-driven EnterPlanMode tool arms it), so USER-driven plan
+ *  (permissionMode=plan) would run workflows — whose child agents write by default — during "read-only"
+ *  research. Plan therefore composes an explicit canonical-space DENY (not ask: plan is research, CC blocks
+ *  write-effect tools outright), deny-wins under the fold so nothing can un-tighten it. */
 function createWorkflowPlanDenyPolicy() {
     return {
         check(req) {
@@ -173,16 +314,53 @@ function createWorkflowPlanDenyPolicy() {
         nameSets: [{ deny: WORKFLOW_ASK_NAMES }],
     };
 }
+/**
+ * Build the per-request permission ToolPolicy from the parsed settings (mirrors shell `seam.ts` — see header).
+ *  - base = name-keyed allow/deny (`createAllowDenyPolicy`): an `allow` list narrows to those tools; a `deny` list
+ *    hard-blocks — composed deny-wins with an ASK-list ({@link createAskListPolicy}) so `permissions.ask` actually
+ *    forces an approval gate (NOT silently dropped — review finding). `deny` > `ask` > `allow` on overlap.
+ *  - `defaultMode` derive onto that base ([820]/[822] five-mode table; the fs-write gate needs `gate` wiring —
+ *    without it every mode degrades to the base rules only, the pre-[816] behavior):
+ *      `default`           → base + `createFsWriteGatePolicy({rootPath: cwd, exemptDirs:[scratchpad], ask})` — CC
+ *                            manual: every fs write asks (the [816] P0 fix), scratchpad writes ride free.
+ *      `acceptEdits`       → base + the same factory with `acceptDirs:[cwd]` — writes INSIDE the cwd subtree
+ *                            auto-allow, OUTSIDE still ask (CC 207 dirname-variant card). NOT a loosen vs the
+ *                            deployment: the factory only ever emits allow/ask and is folded deny-wins, so a
+ *                            baseline deny/ask still wins; vs `default` it is simply a narrower CLIENT gate, and
+ *                            both are client-side ADDITIONS the client may size itself.
+ *      `plan`              → handsReadOnly + present_plan (unchanged; the write tools never reach an ask).
+ *      `bypassPermissions` → base only, NO factory ([820] table: bypass = "不加门" not "开门" — deployment
+ *                            approval/governance baselines still apply; this is exactly every mode's pre-[816]
+ *                            derive, so bypass grants nothing that wasn't already granted).
+ *      `auto`              → base + the `default` factory (ask 兜底) — core's auto-mode classifier (entitlement-
+ *                            gated: RunnerDeps.autoMode ∧ runtimeCaps.autoMode, 1.276/1.277) screens asks UPSTREAM
+ *                            of resolveAsk, allowing safe calls and leaving suspicious ones on the ask path ([822]②).
+ *      absent (undefined)  → base only, NO factory: an expressed-no-mode request keeps its pre-[816] behavior
+ *                            (attaching the ask gate on a mere allow/deny-list stamp would regress headless callers
+ *                            that never asked for a mode; the shell always sends its mode explicitly).
+ * Returns the composed ToolPolicy + whether `handsReadOnly` should tighten. Returns `undefined` policy when there
+ * is no permission rule and no mode-derived gate (nothing to project).
+ */
 export function deriveSettingsPolicy(settings, gate, workflowGate) {
     const perms = settings.permissions;
     if (!perms)
         return {};
     const { allow, deny, ask, defaultMode } = perms;
+    // The base name-keyed gate: allow/deny via core's helper + an ask-list (FINDING-1: `ask` must enforce, not drop).
+    // Each is composed deny-wins (`deny` > `ask` > `allow`), so the fold can only ever tighten.
     const policies = [];
     if (allow || deny)
         policies.push(createAllowDenyPolicy({ ...(allow ? { allow } : {}), ...(deny ? { deny } : {}) }));
     if (ask)
         policies.push(createAskListPolicy(ask));
+    // The mode-derived fs-write ask gate (core 1.290 factory — real shape read in dist: {env, rootPath?, acceptDirs?,
+    // exemptDirs?, defaultWrite}, gates Write/Edit/NotebookEdit, exempt→accept→default layering, canonicalize inside
+    // the given env, only ever allow/ask). undefined off the host lane / without wiring (see FsWriteGateWiring).
+    // ③ (core 1.295): the sensitive-path DENY policy (patterns from the wiring — config SENSITIVE_WRITE_PATTERNS,
+    // default = core's RECOMMENDED set) composes into the SAME fold, deny-wins — core semantics deny/"safety", so
+    // neither the gate's own allow legs (exemptDirs/acceptDirs/isExempt session exemption) nor a settings allow can
+    // cross it (the 1.199-batch gap: an exempted tool could write .git/hooks — closed here). Same env/rootPath as
+    // the gate (the fs the hands really write; symlink canonicalization inside the policy, dist-read).
     const fsWriteGate = (acceptCwd) => {
         if (!gate)
             return undefined;
@@ -191,9 +369,14 @@ export function deriveSettingsPolicy(settings, gate, workflowGate) {
             rootPath: gate.cwd,
             ...(acceptCwd ? { acceptDirs: [gate.cwd] } : {}),
             ...(gate.scratchpadDir ? { exemptDirs: [gate.scratchpadDir] } : {}),
-            ...(gate.isExempt ? { isExempt: gate.isExempt } : {}),
+            ...(gate.isExempt ? { isExempt: gate.isExempt } : {}), // 1.294 session-exemption probe (see FsWriteGateWiring)
             defaultWrite: "ask",
         });
+        // NotebookEdit coverage is core-native since 1.296.1(我方 [886]① 请修 core 已兑现,1.207 的临时参数桥
+        // 就此撤除):DEFAULT_GUARDED_TOOLS 含 NotebookEdit,且两 policy 共用 `writeTargetPath` 提取器——canonical
+        // NotebookEdit 时 notebook_path 恒先(诱饵 file_path 失效),其余工具 file_path 先(反向诱饵也封);均 dist
+        // 亲读。回归锚保留在 test/task-settings.test.ts(NotebookEdit deny + 双向诱饵),现在锁的是 core 行为经
+        // 我方折叠——core 若回退,锚变红。
         return gate.sensitivePatterns && gate.sensitivePatterns.length > 0
             ? combinePolicies(createSensitivePathPolicy({ env: gate.env, patterns: gate.sensitivePatterns, rootPath: gate.cwd }), gatePolicy)
             : gatePolicy;
@@ -205,6 +388,10 @@ export function deriveSettingsPolicy(settings, gate, workflowGate) {
     const basePolicy = compose();
     switch (defaultMode) {
         case "plan":
+            // plan = read-only hands + the plan workflow: a TIGHTEN (handsReadOnly false→true), honored remotely.
+            // ALSO mount core's `present_plan` (enablePlanMode) so the model explores read-only then
+            // proposes a plan (CC EnterPlanMode→ExitPlanMode parity). Both are tighten/additive — no loosening.
+            // codex F1: run_workflow mounts OUTSIDE the hands band — deny it explicitly (see createWorkflowPlanDenyPolicy).
             return { toolPolicy: compose(createWorkflowPlanDenyPolicy()), handsReadOnly: true, enablePlanMode: true };
         case "acceptEdits": {
             const p = compose(fsWriteGate(true), createWorkflowAskPolicy(workflowGate?.isExempt));
@@ -212,6 +399,12 @@ export function deriveSettingsPolicy(settings, gate, workflowGate) {
         }
         case "default":
         case "auto": {
+            // (historical note kept: the pre-[816] impl fell through to base-only here — with no gate to attach,
+            // acceptEdits-as-loosen could not be honored. The [820] factory inverts the frame: default now ADDS an ask
+            // gate and acceptEdits ADDS a narrower one, both tighten-safe under the deny-wins fold.)
+            // [1557]§四: gate.shellGate opt-in(absent = pre-此批行为 byte-for-byte)rides alongside the fs-write ask
+            // gate on the SAME "CC manual" modes — closes the "echo > file bypasses the write gate" hole (cli[1555]②)
+            // when the deployment explicitly opts in (config MANUAL_MODE_SHELL_GATE).
             const p = compose(fsWriteGate(false), createWorkflowAskPolicy(workflowGate?.isExempt));
             return { ...(p ? { toolPolicy: p } : {}), ...(gate?.shellGate ? { shellGate: gate.shellGate } : {}) };
         }
@@ -220,6 +413,24 @@ export function deriveSettingsPolicy(settings, gate, workflowGate) {
             return basePolicy ? { toolPolicy: basePolicy } : {};
     }
 }
+/**
+ * Apply a client's parsed per-request settings onto a base `TaskSpec`, TIGHTEN-ONLY, in a SINGLE {@link
+ * tightenTaskSpec} pass (so the permission override composes deny-wins onto the baseline — TRAP #1 — and
+ * `handsReadOnly`/`onAsk` can only narrow). `tightenTaskSpec` THROWS `TaskSpecTightenError` if any override would
+ * LOOSEN a stricter base — surfaced by the caller as a 4xx (a client settings stamp that tries to widen is a
+ * client error, never a silent weakening). `model`/`outputStyle` are applied directly (model is the caller's
+ * choice WITHIN the catalog — the caller gates it before calling; outputStyle appends to the system prompt).
+ *
+ * Returns `base` untouched when the parsed settings project nothing onto the spec.
+ */
+// [1557]§四: core's tightenTaskSpec THROWS TaskSpecTightenError when an override's shellGate ranks LOWER than
+// base's (its contract is "the override must itself tighten", not "take the stricter of the two" — unlike
+// handsReadOnly, which ORs). Red-first repro: tightenTaskSpec({shellGate:"always"}, {shellGate:"classify"})
+// throws — so a deployment that layers autonomy=ask (→"always") UNDER this opt-in (→"classify") would 422
+// EVERY request on that mode. Mirrors core's own SHELL_GATE_RANK (tighten-task-spec.js) — only pass the
+// override through when it would not be a downgrade; otherwise the baseline already covers it (tightenTaskSpec's
+// base-only branch keeps `base.shellGate` unchanged either way — omitting is behaviorally identical, never a
+// silent weakening, just avoids the throw).
 const SHELL_GATE_RANK = { off: 0, classify: 1, always: 2 };
 export function applyTaskSettings(base, settings, gate, workflowGate) {
     const { toolPolicy, handsReadOnly, enablePlanMode, shellGate } = deriveSettingsPolicy(settings, gate, workflowGate);
@@ -232,11 +443,15 @@ export function applyTaskSettings(base, settings, gate, workflowGate) {
         if (handsReadOnly !== undefined)
             overrides.handsReadOnly = handsReadOnly;
         if (shellGateSafe !== undefined)
-            overrides.shellGate = shellGateSafe;
-        next = tightenTaskSpec(next, overrides);
+            overrides.shellGate = shellGateSafe; // [1557]§四 opt-in; rank-guarded above
+        next = tightenTaskSpec(next, overrides); // deny-wins compose + THROWS on loosen (fail-loud)
     }
+    // R4: enablePlanMode (mount present_plan) is ADDITIVE — it widens NOTHING (a read-only plan workflow), so it rides
+    // directly (not through tightenTaskSpec, which guards safety fields). Only ever set true (plan), never cleared.
     if (enablePlanMode)
         next = { ...next, enablePlanMode: true };
+    // outputStyle → appended system prompt (additive UX directive; never a safety field). The caller already set any
+    // business systemPrompt; core's appendSystemPrompt rides after the scenario base.
     if (settings.outputStyle) {
         const appended = next.appendSystemPrompt ? `${next.appendSystemPrompt}\n\n${settings.outputStyle}` : settings.outputStyle;
         next = { ...next, appendSystemPrompt: appended };

package/dist/task-workflow.d.ts

@@ -1,25 +1,92 @@
+/**
+ * Workflow super-set unlock — map the per-task `body.selfOrchestration` intent onto
+ * `TaskSpec.selfOrchestration`, the gate that mounts core's LLM-authored `run_workflow` engine (the workflow.ts
+ * agent/parallel/pipeline orchestrator). Same shape as the rank-1 roster gap: the engine (core run_workflow +
+ * workflow.ts) is BUILT, but nothing mapped a body field to the per-task spec flag, so it was unreachable over HTTP
+ * (capabilities advertised `workflows:true` but the LLM could never call run_workflow).
+ *
+ * Gating:
+ *  - DEPLOYMENT: `selfOrchestrationEnabled` must be on (the workflowScriptRunner + stores are wired). Otherwise a set
+ *    flag is a harmless no-op (core fail-closes run_workflow without the sandbox runner), so it's dropped for clarity.
+ *  - MULTI-TENANT: honored ONLY when a per-principal entitlement RESOLVER is wired (`hasEntitlementResolver`). 🔴 core's
+ *    `allowWorkflows` (RuntimeCaps) is TIGHTEN-ONLY — a resolver can only DENY; `undefined` = NO restriction, so the
+ *    deployment capability governs. Therefore WITHOUT a resolver the engine would mount run_workflow UNGATED for every
+ *    tenant. So we fail-closed here (defense-in-depth: a misconfigured multi-tenant deployment with no entitlement
+ *    source must NOT leak the LLM-authored workflow engine). WITH a resolver, core enforces `allowWorkflows`
+ *    per-principal (deny → fail-closed). Single-user (owns its own worker) honors directly. Three-gate: engine-can ∧
+ *    center-may(allowWorkflows) ∧ shell-show.
+ */
 export declare function selfOrchestrationFromBody(body: {
     selfOrchestration?: unknown;
 }, config: {
     selfOrchestrationEnabled: boolean;
     requirePrincipal?: boolean;
 }, hasEntitlementResolver: boolean): true | undefined;
+/**
+ * §4 (Fork) — map the per-task `body.enableFork` intent onto `TaskSpec.enableFork`. core 1.257 (design/136 BREAKING)
+ * RETIRED the standalone `Fork` tool; a fork is now `Agent(subagent_type:"fork")`, and `enableFork` is one of the two
+ * governance axes (`forkGovernanceDenial(spec.enableFork, runtimeCaps.allowFork)`) that gate it.
+ *
+ * 🔴 CONSUME-CRITICAL — the default FLIPPED to opt-OUT: core now treats `enableFork === undefined` as **available**
+ * (only an EXPLICIT `enableFork:false` / `allowFork:false` denies — CC's default posture). So where the SERVICE intends
+ * to DENY, it must return `false` EXPLICITLY — the old "return undefined = not granted" is now fail-OPEN.
+ *  - DEPLOYMENT posture OFF (`!forkEnabled`, e.g. multi-tenant default): `false` (explicit deny — preserve opt-in posture).
+ *  - PER-TASK OPT-OUT (`body.enableFork === false`): `false` (any tenancy).
+ *  - SINGLE-USER TURNKEY: `true` — DEFAULT ON for the LLM (clay 2026-07-01). (core still only lets it fork where the
+ *    session store is fork-capable and never inside a fork / read-only band — graceful degrade, no capability lie.)
+ *  - MULTI-TENANT: `true` ONLY with a per-principal entitlement RESOLVER wired (core then enforces `allowFork`
+ *    tighten-only per-principal); WITHOUT a resolver `false` (fail-closed — `allowFork` is tighten-only so an absent
+ *    resolver = `undefined` = ungated, and now `enableFork:undefined` also auto-grants, so the service must hard-deny).
+ */
 export declare function enableForkFromBody(body: {
     enableFork?: unknown;
 }, config: {
     forkEnabled: boolean;
     requirePrincipal?: boolean;
 }, hasEntitlementResolver: boolean): boolean;
+/**
+ * The workflow-script MODEL allowlist (`agent({model})` picks). core is
+ * fail-closed: NO allowlist configured ⇒ `WorkflowModelNotAllowedError` on ANY model pick, which on a TOC
+ * single-user deployment broke clay's own dual-model scripts (决策 v4-pro + 执行 v4-flash) out of the box —
+ * the operator configured every catalog entry themselves, so there is nothing to protect them from.
+ *  - Explicit `SELF_ORCHESTRATION_MODELS` always wins (any tenancy — the operator's deliberate narrowing).
+ *  - SINGLE-USER: default to the deployment's OWN model catalog (`Object.keys(models)`).
+ *  - MULTI-TENANT: keep core's fail-closed empty default (a model pick is a cost/capability grant the
+ *    operator must make explicitly; a tenant script must not self-select the expensive rung).
+ * Returns undefined when no allowlist should be set (core then fail-closes picks; the script's `agent()`
+ * without a model still runs on the workflow's default role — only PICKING is gated).
+ */
 export declare function workflowModelAllowlistFor(config: {
     selfOrchestrationModels: string[];
     requirePrincipal?: boolean;
     models: Record<string, unknown>;
 }): string[] | undefined;
+/** design/122 caps for a caller-supplied `retainSubagentSessions` object (core defaults 30min/16; the ledger
+ *  is run-scoped and fully released at parent end, so these only bound the WITHIN-RUN memory pin). */
 export declare const RETAIN_SUBAGENT_TTL_MS_CAP: number;
 export declare const RETAIN_SUBAGENT_MAX_CAP = 64;
+/**
+ * design/122 (core 1.225): normalize an untrusted `body.retainSubagentSessions` onto the TaskSpec field.
+ * `true`/`false` pass through (core's own defaults apply); an object keeps only NUMERIC ttlMs/max, each
+ * clamped to a positive integer under the cap (retention pins settled child sessions in memory for the
+ * parent run's lifetime — the knob must not become a caller-controlled resource hold). Anything malformed →
+ * undefined = OFF (core default). Defensive, never throws: RESUME re-runs resolveSpec WITHOUT the HTTP-layer
+ * validation, so this normalizer is the single guard on every path.
+ */
 export declare function normalizeRetainSubagentSessions(raw: unknown): boolean | {
     ttlMs?: number;
     max?: number;
 } | undefined;
+/**
+ * Per-task wall clock by TENANCY POSTURE (clay 2026-07-04, make-real 教训①:600s 默认墙钟砍掉了健康推进的
+ * 长任务/chaos 恢复 run):
+ *  - SINGLE-USER turnkey(`requirePrincipal !== true`)= the user IS the superadmin → **NO wall clock**
+ *    (undefined; core arms none — its separate wedge safety-net still catches a stuck tool call, so "no wall"
+ *    never means "hangs forever"). CC has no whole-task decapitation either.
+ *  - MULTI-TENANT: base 2400s (big tasks — council/debate/team — 3600s). (PAIR-REVIEW F-4 附带修:此行
+ *    曾写 600s/1500s 与代码漂移——真值以下方 base 为准。)
+ *  - Explicit `TASK_TIMEOUT_SEC` wins in ANY tenancy (the operator's deliberate wall) and keeps its documented
+ *    raise-only floor (`Math.max` with the base, so a misconfigured low value cannot shrink a council budget).
+ */
 export declare function taskWallClockSec(envTimeoutSec: number, requirePrincipal: boolean | undefined, big: boolean): number | undefined;
 //# sourceMappingURL=task-workflow.d.ts.map