@sema-agent/core 7.18.0 → 7.19.0

package/dist/core/sensitive-path-policy.d.ts

@@ -3,6 +3,22 @@ import type { ToolPolicy } from "./tool-policy.js";
 /** fs hand tools that take a `path` and write — the reliably-guardable surface. NotebookEdit joined
  *  in [886]①a (mirror of the fs-write-gate's covered set): its target is `notebook_path`, and a
  *  guard that ignored notebook writes to the same paths by default was the same hole one tool away. */
+/**
+ * The agent-configuration block of {@link RECOMMENDED_SENSITIVE_PATTERNS} MIRRORS the read tier (spelled as
+ * literals so the closed set stays statically readable; a set-equality pin keeps the mirror exact): the read tier's rows already encode this severity's predicate ("an agent's own config
+ * FILE, whose `env`/`mcpServers` block is a credential or a command line the host launches") and argue
+ * each one. Shared is the VOCABULARY, not the judgment.
+ *
+ * @contract sensitive_paths.agent_config_tier_is_shared — the write deny set's agent-configuration
+ * block IS the read face's `agent-config` tier, row for row: one table, two judges, and the two faces
+ * cannot drift into disagreeing about which files are an agent's own configuration. The CONFIGURATION
+ * DIRECTORIES (`.claude`, `.sema`) are on neither face's deny side — their write guard is ASK
+ * severity, where an approver or a persisted allow rule can clear it. Their `hooks/` and `agents/`
+ * sub-directories are the two exceptions and they are NOT part of this mirror: a hook script is an executable
+ * body and an agent definition re-authorizes the agent on load, both guarded on the write face only, by
+ * hand-kept rows of the list below.
+ */
+export declare function agentConfigDenyPatterns(): readonly string[];
 /**
  * RECOMMENDED default pattern set for {@link createSensitivePathPolicy} (additive export).
  * NO upstream verbatim anchor exists (cc-anchors/2.1.209 carries no sensitive/dangerous file-pattern
@@ -20,13 +36,15 @@ import type { ToolPolicy } from "./tool-policy.js";
  *
  * HRD-PRM-10 — sema's own data root (`$AGENT_DATA_DIR ?? ~/.ai-agent`) is excluded BY CONSTRUCTION,
  * not by the absence of an entry. The exclusion used to be "just don't add a pattern that names it",
- * which held only as long as no entry happened to match one of its ANCESTOR segments. That assumption
- * died the moment the shell's own config root joined the list: the shell sets
+ * which held only as long as no entry happened to match one of its ANCESTOR segments — and that
+ * assumption died the first time a directory-wide config-root entry was on this list: the shell sets
  * `AGENT_DATA_DIR = <configRoot>/engine-data` with a configRoot of `~/.sema`, so every path under the
- * data root carries a `.sema` segment, and a pattern guarding the config root swallowed the whole data
- * root with it — including the memory library the model is INSTRUCTED to write with the Write tool
+ * data root carries a `.sema` segment, and the entry swallowed the whole data root with it —
+ * including the memory library the model is INSTRUCTED to write with the Write tool
  * (`MEMORY_INSTRUCTION_TEMPLATE`), i.e. every memory write refused, on a default server wiring.
- * So the exclusion is now mechanical: a target INSIDE the data root is matched on its path RELATIVE to
+ * That entry is gone (see the severity layering below), but the exclusion stays mechanical — a
+ * deployment may site its data root beneath ANY guarded directory, and both tiers honour it. A
+ * target INSIDE the data root is matched on its path RELATIVE to
  * that root (see {@link createSensitivePathPolicy}'s `dataRoot`), so the root's own ancestry is not the
  * target's business, while a genuinely sensitive path INSIDE it (`<dataRoot>/x/.ssh/id_rsa`) still
  * matches. The `sessions/` subtree keeps its own owner: `createTranscriptIntegrityPolicy` is wired
@@ -34,8 +52,22 @@ import type { ToolPolicy } from "./tool-policy.js";
  * transcripts is routine» and a legitimate operator write must remain clearable by judgment — and a
  * deny here would outrank that ask under the deny > ask > allow fold and silently convert it into a
  * hard refusal for every deployment that wires this list.
+ *
+ * SEVERITY LAYERING for the agent-configuration class: the law is {@link agentConfigDenyPatterns} —
+ * configuration FILES here, the DIRECTORY one step down on {@link RECOMMENDED_SENSITIVE_ASK_PATTERNS}
+ * (same judge, so the severity drops and the reach does not); a directory also holds the person's own
+ * material, and the directory-wide entry turned an explicit instruction to edit `.claude/projects/…`
+ * into a refusal nobody could lift (a deny outranks an ask under the fold).
  */
 export declare const RECOMMENDED_SENSITIVE_PATTERNS: readonly string[];
+/**
+ * The ASK-severity half of the same guard: the agent-configuration DIRECTORIES, on the SAME judge
+ * ({@link createSensitivePathPolicy}'s `askPatterns` seat, whose ABSENCE reads as this list) — only the
+ * directories, since the configuration FILES inside them are deny material above. It lives HERE and not
+ * only on `WRITE_PROTECTED_DEFAULT_TABLE`, which names the same segments but judges LEXICALLY: a
+ * symlink with an innocent name walks past that one, so demoting to it alone trades severity for REACH.
+ */
+export declare const RECOMMENDED_SENSITIVE_ASK_PATTERNS: readonly string[];
 /**
  * HRD-PRM-10 — the engine data root, read from the same knob its two consumers read
  * (`$AGENT_DATA_DIR ?? ~/.ai-agent`, off the HOST at wiring time, NFC-normalized) and returned in
@@ -53,27 +85,36 @@ export declare const RECOMMENDED_SENSITIVE_PATTERNS: readonly string[];
  */
 export declare function dataRootSpellings(explicit: string | undefined): string[];
 /**
- * Build a composable policy that DENIES writes (via the guarded fs tools) whose canonical target
- * lands on a sensitive path. `patterns` are deployment-supplied (no default list is shipped — the
- * set of escalation-vector paths is deployment-specific); an empty list is a no-op allow.
+ * Build a composable policy that judges writes (via the guarded fs tools) by their CANONICAL target,
+ * at TWO severities from ONE judge. `patterns` is the DENY set — deployment-supplied, no default list
+ * is shipped; `askPatterns` is the ASK set, judged the same way and consulted only where the deny set
+ * misses, so a path on both denies. Both empty = a no-op allow.
+ *
+ * @contract sensitive_paths.two_severities_one_judge — ONE canonicalizing judge answers both
+ * severities: a deny is a refusal no approver and no persisted allow rule can lift, an ask is one
+ * explicit look that either of them may clear. Lowering a path's severity here never lowers its REACH
+ * — both tiers see the real target (symlinks resolved, relative spellings resolved against the call's
+ * live cwd), which the synchronous write-protection TABLE deliberately does not.
  *
  * `env` is the same ExecutionEnv the hands run against (inject the one you pass to the Runner), so
  * canonicalization sees the task's real filesystem (a remote/E2B task resolves in its container).
- * `rootPath` is the FALLBACK base a relative path resolves against (omit = paths resolve as given).
- * When the engine stamps a live cwd onto the request (`ToolCallRequest.cwd` — the tracked
- * directory the shell's `cd` moves and the fs tools resolve with), THAT wins for the call's target, so
- * the guard judges the file the tool will actually write. `rootPath` still serves every deployment that
- * calls this policy outside a Runner.
+ * `rootPath` plays the same fallback-base role it plays on the sibling write gate (see
+ * {@link import("./fs-write-gate-policy.js").FsWriteGatePolicyOptions.rootPath}); the call's live
+ * `ToolCallRequest.cwd` outranks it for the target.
  *
- * Fail-open by design: a tool with no string `path`, or a path that cannot be canonicalized, returns
- * `allow` here — this guard adds a denial on top of the other gates, it is not the only line of
- * defense, and it must not turn an unrelated tool call into a spurious deny. The verdict it owns is
- * narrow and certain: "the real target IS a guarded path → deny".
+ * Fail-open by design: a tool with no string `path` returns `allow` here — this guard adds friction on
+ * top of the other gates, it is not the only line of defense, and it must not turn an unrelated tool
+ * call into a spurious verdict. The verdicts it owns are narrow and certain: "the real target IS a
+ * guarded path → deny / ask". (A target it could not RESOLVE is the one fail-CLOSED arm, below.)
  */
 export declare function createSensitivePathPolicy(opts: {
     env: ExecutionEnv;
     /** `readonly` accepted so {@link RECOMMENDED_SENSITIVE_PATTERNS} can be passed as-is (widening, non-breaking). */
     patterns: readonly string[];
+    /** The ASK-severity set, same syntax and same judge as `patterns`, consulted only where the deny set
+     *  misses. ABSENT ⇒ {@link RECOMMENDED_SENSITIVE_ASK_PATTERNS}, so a deployment already wiring this
+     *  guard keeps its reach over those directories without a code change; `[]` = no ask tier. */
+    askPatterns?: readonly string[];
     rootPath?: string;
     /**
      * HRD-PRM-10 — the engine data root this deployment runs on. Default

package/dist/core/sensitive-path-policy.js

@@ -1,9 +1,12 @@
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { canonicalizeTarget, expandHomeTilde, isAbsoluteForFamily, isWinFormPath, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
-import { compileSegmentPattern, matchSegmentPatterns } from "../tools/fs/read-deny.js";
+import { compileSegmentPattern, matchSegmentPatterns, READ_FACE_BUILTIN_DENY_TABLE } from "../tools/fs/read-deny.js";
 import { isProtectedWrite, protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
+export function agentConfigDenyPatterns() {
+    return READ_FACE_BUILTIN_DENY_TABLE.filter((row) => row.tier === "agent-config").map((row) => row.pattern);
+}
 export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".env",
     ".env.*",
@@ -18,10 +21,25 @@ export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".git/hooks",
     ".git/config",
     ".git/modules",
-    ".mcp.json",
-    ".claude*",
-    ".sema",
+    ".sema/settings.json",
+    ".sema/settings.local.json",
     ".sema.*",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".claude.*",
+    ".mcp.json",
+    ".ai-agent/.env",
+    ".sema/engine-data/.env",
+    ".codex/config.toml",
+    ".cursor/mcp.json",
+    ".continue/config.json",
+    ".continue/config.yaml",
+    ".aider.conf.yml",
+    ".gemini/settings.json",
+    ".claude/hooks",
+    ".sema/hooks",
+    ".claude/agents",
+    ".sema/agents",
     ".sema-notifier-build",
     ".aws",
     ".config/gcloud",
@@ -32,6 +50,7 @@ export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".bash_history",
     ".zsh_history",
 ];
+export const RECOMMENDED_SENSITIVE_ASK_PATTERNS = [".claude", ".sema"];
 const CASE_INSENSITIVE_FS = process.platform === "darwin" || process.platform === "win32";
 export function dataRootSpellings(explicit) {
     const raw = explicit ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent");
@@ -77,6 +96,7 @@ function matchSensitive(canonicalKey, compiled, aliasResolved) {
 }
 export function createSensitivePathPolicy(opts) {
     const compiled = compilePatterns(opts.patterns);
+    const compiledAsk = compilePatterns(opts.askPatterns ?? RECOMMENDED_SENSITIVE_ASK_PATTERNS);
     const dataRootPaths = dataRootSpellings(opts.dataRoot);
     const dataRootKeys = async (signal) => {
         const keys = [];
@@ -94,7 +114,7 @@ export function createSensitivePathPolicy(opts) {
     const guardedByName = opts.tools !== undefined ? new Set(opts.tools) : undefined;
     return {
         async check(req, signal) {
-            if (compiled.length === 0)
+            if (compiled.length === 0 && compiledAsk.length === 0)
                 return { action: "allow" };
             if (guardedByName !== undefined ? !guardedByName.has(req.toolName) : !isProtectedWrite(req))
                 return { action: "allow" };
@@ -129,6 +149,14 @@ export function createSensitivePathPolicy(opts) {
                     decisionReason: "safety",
                 };
             }
+            const askHit = matchSensitive(judged, compiledAsk, canon.aliasResolved === true);
+            if (askHit) {
+                return {
+                    action: "ask",
+                    message: `this write's real target resolves inside the guarded directory "${askHit}" — explicit approval required`,
+                    decisionReason: "safety",
+                };
+            }
             return { action: "allow" };
         },
     };

package/dist/core/skill-listing-budget.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The skills-listing BUDGET SEAT as vocabulary: the two knobs a deployment may declare
+ * (`TaskSpec.skillListingBudgetFraction` / `TaskSpec.skillListingMaxDescChars`), the ONE reader that
+ * lowers them to the numbers the renderer measures against, and the disclosure announced when the
+ * budget costs a skill its description. The reader is pure; the announcer's only effect is the notice.
+ * `runner/synthetic-tools.ts` owns the renderer that consumes the numbers.
+ *
+ * Sibling of `tool-search-setting.ts` in shape and in posture: a value outside its domain REFUSES
+ * loudly rather than folding back to the default, because a knob that is silently dropped reads to the
+ * deployment as a knob that took effect.
+ */
+import { type EngineNotice } from "./engine-notice.js";
+/** Fraction of the model's context window the listing may spend when the deployment declares nothing. */
+export declare const SKILL_LISTING_BUDGET_FRACTION_DEFAULT = 0.01;
+/** Per-skill description cap (code units, ellipsis included) when the deployment declares nothing. */
+export declare const SKILL_LISTING_DESC_MAX_CHARS_DEFAULT = 1536;
+/** Context window assumed for a model that declares none. */
+export declare const SKILL_LISTING_DEFAULT_CONTEXT_TOKENS = 200000;
+/**
+ * The token→byte exchange rate this budget allocates at.
+ *
+ * @contract skills.listing_budget_exchange_rate — deliberately NOT `DEFAULT_CHARS_PER_TOKEN` (3), and
+ * the difference is directional, not an inconsistency. That constant serves the compaction/context
+ * estimators, which convert bytes→tokens and must OVER-estimate the token count to stay inside a
+ * window; a low rate is the conservative choice there. This seat converts tokens→a byte ALLOWANCE,
+ * where a low rate silently SHRINKS what the deployment may spend. Two directions, two numbers, both
+ * named. At 3 the default allowance would be 6 000 bytes rather than 8 000 — a quarter of every
+ * default deployment's listing, removed by an estimator's safety margin.
+ */
+export declare const SKILL_LISTING_BYTES_PER_TOKEN = 4;
+/**
+ * The hard ceiling on the rendered `<skills>` block, in UTF-8 bytes.
+ *
+ * @contract skills.listing_budget_ceiling — this is a STRUCTURAL property of the delivery lane, not a
+ * policy choice and not a superset optimization. The block is not part of the system prompt: it is the
+ * body of the `skills_listing` turn attachment, and every attachment bundle is capped at
+ * `ATTACHMENT_BYTE_CAP` (8 KiB) by the boundary's `capAttachments`, which CLIPS anything over. A
+ * clipped skills frame never satisfies the run loop's intact-survival commit predicate, so the
+ * announced set never advances and the frame is re-rendered and re-clipped at every subsequent
+ * boundary — permanently. The cap is therefore enforced byte-exact over the WHOLE render (fences,
+ * headers, markers, joiners included) and MUST stay ≤ `ATTACHMENT_BYTE_CAP`; the renderer's module
+ * pins that relation, since importing the attachment module here would invert the dependency.
+ *
+ * The consequence is a one-way knob: {@link resolveSkillListingBudget} clamps the declared budget to
+ * this number, so a raised fraction (or a model with a very large window) can LOWER the listing budget
+ * but can never raise it above this ceiling. When the clamp costs a description, both numbers ride the
+ * disclosure ({@link announceSkillListingTruncation}), so the deployment reads what it asked for beside
+ * what it got instead of inferring the ceiling from a short listing.
+ */
+export declare const SKILLS_BLOCK_MAX_BYTES = 8000;
+/** The typed refusal a budget seat outside its domain raises: a bad value never selects a smaller
+ *  listing silently, and never folds back to the default budget. */
+export declare const SKILL_LISTING_BUDGET_INVALID_CODE = "config.skill_listing_budget_invalid";
+/** The notice code minted when the budget cost at least one skill its description or its line. */
+export declare const SKILL_LISTING_TRUNCATED_CODE = "skills.listing_truncated";
+/** The lowered seat: the two numbers the renderer measures against, plus what was asked for. */
+export interface ResolvedSkillListingBudget {
+    /** The budget the renderer enforces over the whole block, in UTF-8 bytes — already clamped to
+     *  {@link SKILLS_BLOCK_MAX_BYTES}. */
+    blockMaxBytes: number;
+    /** What the declared fraction asked for BEFORE the structural clamp. Equal to `blockMaxBytes`
+     *  whenever the ceiling did not bind; strictly greater when it did. */
+    requestedBytes: number;
+    /** Per-skill description cap in code units, ellipsis included. */
+    descMaxChars: number;
+}
+/**
+ * The ONE reader of the two listing-budget seats.
+ *
+ * `skillListingBudgetFraction` must be a finite number in `(0, 1]` — zero is excluded deliberately: a
+ * zero budget is not "spend nothing", it is a listing every skill loses its description to, which the
+ * deployment expresses by declaring fewer skills. `skillListingMaxDescChars` must be a positive safe
+ * integer. Both absent ⇒ the documented defaults, which reproduce the pre-seat render byte for byte
+ * (`200 000 × 4 × 0.01` = 8 000 = {@link SKILLS_BLOCK_MAX_BYTES}).
+ *
+ * The window is `contextTokens ?? contextWindow`, the same physical coordinate the deferral gate
+ * measures against. A window that is absent OR unusable (non-finite, non-positive) reads as
+ * {@link SKILL_LISTING_DEFAULT_CONTEXT_TOKENS}: one rule, not a case per bad shape — a model's own
+ * declaration is judged by the model doors, and this seat must still produce a number a renderer can
+ * compare against.
+ */
+export declare function resolveSkillListingBudget(opts: {
+    fraction?: unknown;
+    maxDescChars?: unknown;
+    model?: {
+        contextTokens?: number;
+        contextWindow?: number;
+    } | undefined;
+}): ResolvedSkillListingBudget;
+/**
+ * Announce a listing the budget degraded — delivered only when a skill actually lost its description
+ * (`nameOnly`) or its line (`dropped`), so a deployment whose roster fits hears nothing.
+ *
+ * Called from the two lanes that DELIVER a listing frame (the leg's first-frame producer and the turn
+ * boundary), never from the config door: the door cannot see the deployment's
+ * `attachments.skillsListing` switch (resolved at run start), it runs per prepared task rather than per
+ * delivered listing, and a resume leg reaches only the boundary.
+ *
+ * Audience is `operator`: the person who can raise the fraction, shorten a description or remove a
+ * skill runs the deployment, not the session. `requestedBudgetBytes` rides beside `budgetBytes`
+ * precisely so the structural ceiling ({@link SKILLS_BLOCK_MAX_BYTES}) is legible at the moment it
+ * costs something — the two differ only when the clamp bound.
+ */
+export declare function announceSkillListingTruncation(onNotice: ((notice: EngineNotice) => void) | undefined, opts: {
+    /** The denominator: how many skills the DELIVERED frame set out to list — the whole roster on an
+     *  initial block, the newly announced set on a drift frame. Read off that frame's own render. */
+    total: number;
+    nameOnly: readonly string[];
+    dropped: readonly string[];
+    budget: ResolvedSkillListingBudget;
+    sessionId?: string | undefined;
+}): void;

package/dist/core/skill-listing-budget.js

@@ -0,0 +1,58 @@
+import { deliverEngineNotice } from "./engine-notice.js";
+import { describeRejectedValue } from "./tool-search-setting.js";
+export const SKILL_LISTING_BUDGET_FRACTION_DEFAULT = 0.01;
+export const SKILL_LISTING_DESC_MAX_CHARS_DEFAULT = 1_536;
+export const SKILL_LISTING_DEFAULT_CONTEXT_TOKENS = 200_000;
+export const SKILL_LISTING_BYTES_PER_TOKEN = 4;
+export const SKILLS_BLOCK_MAX_BYTES = 8_000;
+export const SKILL_LISTING_BUDGET_INVALID_CODE = "config.skill_listing_budget_invalid";
+export const SKILL_LISTING_TRUNCATED_CODE = "skills.listing_truncated";
+function budgetRefusal(problem) {
+    const e = new Error(`TaskSpec.${problem}; a bad value refuses loudly, nothing falls back to the default listing budget.`);
+    e.code = SKILL_LISTING_BUDGET_INVALID_CODE;
+    return e;
+}
+export function resolveSkillListingBudget(opts) {
+    const { fraction, maxDescChars } = opts;
+    if (fraction !== undefined && (typeof fraction !== "number" || !Number.isFinite(fraction) || fraction <= 0 || fraction > 1)) {
+        throw budgetRefusal(`skillListingBudgetFraction: invalid value ${describeRejectedValue(fraction)} — expected a finite fraction in (0, 1]`);
+    }
+    if (maxDescChars !== undefined && (typeof maxDescChars !== "number" || !Number.isSafeInteger(maxDescChars) || maxDescChars <= 0)) {
+        throw budgetRefusal(`skillListingMaxDescChars: invalid value ${describeRejectedValue(maxDescChars)} — expected a positive integer`);
+    }
+    const declaredWindow = opts.model?.contextTokens ?? opts.model?.contextWindow;
+    const windowTokens = typeof declaredWindow === "number" && Number.isFinite(declaredWindow) && declaredWindow > 0
+        ? declaredWindow
+        : SKILL_LISTING_DEFAULT_CONTEXT_TOKENS;
+    const requestedBytes = Math.max(1, Math.floor(windowTokens * SKILL_LISTING_BYTES_PER_TOKEN * (fraction ?? SKILL_LISTING_BUDGET_FRACTION_DEFAULT)));
+    return {
+        blockMaxBytes: Math.min(requestedBytes, SKILLS_BLOCK_MAX_BYTES),
+        requestedBytes,
+        descMaxChars: maxDescChars ?? SKILL_LISTING_DESC_MAX_CHARS_DEFAULT,
+    };
+}
+export function announceSkillListingTruncation(onNotice, opts) {
+    const { total, nameOnly, dropped, budget } = opts;
+    if (nameOnly.length === 0 && dropped.length === 0)
+        return;
+    const clamped = budget.requestedBytes > budget.blockMaxBytes;
+    deliverEngineNotice(onNotice, {
+        code: SKILL_LISTING_TRUNCATED_CODE,
+        message: `The skills listing does not fit its ${budget.blockMaxBytes}-byte budget` +
+            (clamped ? ` (${budget.requestedBytes} bytes were declared; the listing's delivery lane caps it at ${SKILLS_BLOCK_MAX_BYTES})` : "") +
+            `: ${nameOnly.length} of ${total} are listed name-only` +
+            (dropped.length > 0 ? `, and ${dropped.length} did not fit the listing at all` : "") +
+            `. The \`Skill\` tool still serves every one of them. Raise skillListingBudgetFraction, lower` +
+            ` skillListingMaxDescChars, or declare fewer skills.`,
+        detail: {
+            budgetBytes: budget.blockMaxBytes,
+            requestedBudgetBytes: budget.requestedBytes,
+            descMaxChars: budget.descMaxChars,
+            total,
+            kept: total - nameOnly.length - dropped.length,
+            nameOnly: [...nameOnly],
+            dropped: [...dropped],
+            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+        },
+    });
+}

package/dist/core/task-spec.d.ts

@@ -935,6 +935,32 @@ export interface TaskSpec {
      * end-user-authored skills are responsible for vetting them: a skill IS instructions by design.
      */
     skills?: SkillSpec[];
+    /**
+     * Fraction of the model's context window the `<skills>` listing may spend. Absent ⇒ `0.01` (1%).
+     * Domain `(0, 1]`; anything else — including `0`, a string, `NaN` — REFUSES at the door with
+     * `config.skill_listing_budget_invalid` rather than folding back to the default.
+     *
+     * The budget is `(contextTokens ?? contextWindow ?? 200 000) × 4 × fraction`, in UTF-8 bytes, and the
+     * listing degrades inside it: every skill stays listed, the lower-priority ones (declaration order)
+     * lose their descriptions first. Raising this is opting in to a higher per-turn context cost.
+     *
+     * ⚠️ ONE-WAY IN PRACTICE (`@contract skills.listing_budget_ceiling`): the listing rides the turn-
+     * attachment lane, whose bundle cap is a hard structural limit, so the resolved budget is clamped to
+     * 8 000 bytes. A fraction that asks for MORE lowers nothing and raises nothing; a fraction that asks
+     * for less takes effect exactly. When the clamp costs a skill its description, both numbers ride the
+     * `skills.listing_truncated` notice.
+     *
+     * ⚠️ A model declaring a window SMALLER than 200 000 tokens now gets a proportionally smaller listing
+     * budget than the flat 8 000 bytes that preceded this seat.
+     */
+    skillListingBudgetFraction?: number;
+    /**
+     * Per-skill description cap inside the `<skills>` listing, in code units, ellipsis included. Absent ⇒
+     * `1536`. Must be a positive integer; anything else REFUSES with
+     * `config.skill_listing_budget_invalid`. A description longer than the cap is truncated to exactly
+     * this many units; lowering it is how a deployment fits more skills' descriptions inside one budget.
+     */
+    skillListingMaxDescChars?: number;
     /**
      * design/129 — lifetime scope for BACKGROUND children (Agent/Fork `run_in_background`). Default `"task"`:
      * the parent runTask's terminal reaps them (design/115 — no orphans burning tokens; turn-end killed

package/dist/core/tool-policy.d.ts

@@ -1,5 +1,5 @@
 import type { AskOrigin } from "./ask-origin.js";
-import type { Settlement } from "./gate-outcome.js";
+import { type Settlement } from "./gate-outcome.js";
 /** A tool call presented to a policy before it executes. */
 /** design/388 B6 — the per-call face (see {@link ToolCallRequest.face}). */
 export interface ToolCallFace {
@@ -310,6 +310,11 @@ export type PermissionResult = {
      *  in the one direction the stamp cannot reach (a caller composing its own ask) the claim is
      *  tightening-only: it can make an ask outlive a rule, never turn one into an allow. */
     probeMandated?: true;
+    /** The probe named a directory that would clear this ask
+     *  ({@link import("./types.js").ReversibilityVerdict.readRootCandidate}). Display metadata like the two
+     *  `probe*` above; ENGINE-STAMPED and VALIDATED at the tighten, and deliberately NOT merged onto an ask
+     *  another layer raised, which a grant leaves standing. */
+    probeReadRootCandidate?: import("./types.js").ReadRootGrantCandidate;
     /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules`
      *  shape); carries the matched rule's text. Present ⇔ a rule someone WROTE says "ask about this",
      *  never for a `defaultAction:"ask"` fallback (an unmatched call is default-closed posture, not a
@@ -1013,6 +1018,15 @@ export interface AskRequest {
      *  structure: render the entries as data, never re-derive structure by splitting or joining them.
      *  The durable park route carries the same value as `RiskDescriptor.probeCause`. */
     readonly probeCause?: import("./checkpoint-store.js").ProbeCause;
+    /**
+     * The ask-facing face of {@link import("./types.js").ReversibilityVerdict.readRootCandidate}, which owns
+     * the meaning, the absence reading and the spelling contract: PRESENT ⇒ declaring this one directory
+     * clears THIS ask, so a card can offer "add it and stop being asked" beside "yes, this once". Filled at
+     * the synchronous MINT station by the tighten that ran the probe — the three INHERITED-lane sites present
+     * an ancestor's decision from upstream of it and carry none, and the durable park row has NO twin: a
+     * parked out-of-root ask renders the confirmation alone.
+     */
+    readonly readRootCandidate?: import("./types.js").ReadRootGrantCandidate;
     /** design/252 G-2: the RULE-PROVENANCE evidence behind this ask — the org snapshot revision and the
      *  matched rules' own identity keys, each present as a value or as a named absence (see
      *  {@link AskRuleEvidence}). Present on EVERY ask the engine mints, so a consumer never has to tell a
@@ -1121,9 +1135,10 @@ export interface AskRequest {
      *    probe declared structural — for the built-in shell probe, a read outside the directories this
      *    session declared. A surface must NOT point at rule-writing here — "allow rules silence the
      *    classifier's questions, never a mandated one", so a rule minted in answer to this line would
-     *    never take effect where it was minted. It must not point at a directory GRANT either: the
-     *    out-of-root arm has no clearing configuration in this version, and confirming the call is the
-     *    whole of what a person can do about it;
+     *    never take effect where it was minted. Whether a DIRECTORY grant is worth pointing at is not this
+     *    seat's to say: it is answered per ask by {@link readRootCandidate}, which is present exactly when
+     *    widening the session's read directories would clear this one and absent for every other member of
+     *    the family — so a surface reads that seat and never infers an answer from this word;
      *  · `"shadowed"` — a rule the person already wrote is speaking and does not clear this ask (a
      *    matching allow rule that the lane refuses to honor here, or their own explicit `ask` rule);
      *  · `"lane_cannot_speak"` — the lane is armed and this ask IS clearable, but the offer lane

package/dist/core/tool-policy.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { brandPolicyAskClass } from "./ask-class.js";
+import { decidersNote, settledByPerson } from "./gate-outcome.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
@@ -18,9 +19,6 @@ const DECISION_REASON_SET = new Set(DECISION_REASONS);
 function settledByNobody(kind) {
     return { kind, who: { party: "none" }, when: Date.now() };
 }
-function settledByPerson(kind, approver, note) {
-    return { kind, who: { party: "person", ...(approver !== undefined ? { approver } : {}) }, when: Date.now(), ...(note !== undefined ? { note } : {}) };
-}
 const ENGINE_SETTLEMENTS = new WeakMap();
 function attestEngineSettlement(d, record, call) {
     const s = record.settlement;
@@ -1273,7 +1271,7 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
                         settlement: settledByNobody("approver_contract"),
                     };
                 }
-                reasonText = typeof suppliedReason === "string" && suppliedReason !== "" ? suppliedReason : undefined;
+                reasonText = typeof suppliedReason === "string" ? suppliedReason : undefined;
             }
             catch (err) {
                 return {
@@ -1283,15 +1281,16 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
                     settlement: settledByNobody("approver_contract"),
                 };
             }
+            const note = decidersNote(reasonText);
             return {
                 action: "deny",
                 message: supplied === "timeout"
-                    ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${reasonText !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reasonText, REVIEWER_NOTE_MAX_BODY)}` : ""}`
-                    : humanRefusalMessage(req, reasonText),
+                    ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", note, REVIEWER_NOTE_MAX_BODY)}` : ""}`
+                    : humanRefusalMessage(req, note),
                 decisionReason: "mode",
                 settlement: supplied === "timeout"
                     ? { kind: "approval_window_expired", who: { party: "host" }, when: Date.now() }
-                    : settledByPerson("human_refused", attribution.approver, reasonText),
+                    : settledByPerson("human_refused", attribution.approver, note),
             };
         }
         if (suppliedEdit === undefined)

package/dist/core/tool-spec.d.ts

@@ -62,12 +62,45 @@ export interface ReversibilityVerdict {
      * its own deployment a re-confirmation and can never turn an ask into an allow.
      *
      * The built-in shell probe sets it for exactly one family: a listed reader naming a path outside the
-     * session's allowed directories. The engine's own out-of-root demotion has no clearing channel in
-     * this version other than confirming the call each time — a directory-scoped grant that WOULD clear
-     * it is a separate, later mechanism, and until it exists a surface must not word the refusal as
-     * though one already answers it.
+     * session's allowed directories. That demotion HAS a clearing channel — widening the declared read
+     * directories retires it — and where the probe can name the directory, {@link readRootCandidate} carries
+     * it. A mandated ask WITHOUT that member has no configuration behind it: the rest of the family (an
+     * operator `shellGate:"always"`, the tool's egress/irreversibility marks, an org demand, an out-of-root
+     * arm with no named directory) is confirm-or-refuse, and must not be worded as though a grant answers it.
      */
     mandated?: boolean;
+    /**
+     * The directory-scoped GRANT that would clear THIS ask, when the probe can name one: PRESENT ⇒ the only
+     * thing between this call and a plain `reversible: true` verdict is the session's declared read
+     * containment, and adding {@link ReadRootGrantCandidate.dir} to it makes the same call run with no card.
+     *
+     * ABSENT is the ordinary world and no claim that nothing would clear the ask — it covers every demotion
+     * with no directory answer (a deny row, a read the walk could not read, an unenumerable expansion, a
+     * shape refused whatever the roots say) and every probe silent on this member. Read presence, never
+     * absence. ADVISORY display metadata, never adjudication input.
+     */
+    readRootCandidate?: ReadRootGrantCandidate;
+}
+/**
+ * A directory-scoped grant a surface can offer on an approval card — see
+ * {@link ReversibilityVerdict.readRootCandidate} and `AskRequest.readRootCandidate`.
+ *
+ * @contract shell.read_boundary.grant_candidate_is_the_grant — {@link dir} is the string to ADD, not a
+ * string to show: a consumer that renders a shortened or home-relative form must send this exact spelling
+ * back when the person accepts. Core mints one spelling for both errands, and the promise is over THAT
+ * spelling reaching the directories the boundary compares against: a deployment that REWRITES a declared
+ * directory — canonicalizing a symlinked one included — must rewrite the command's spelling the same way,
+ * or it will compare a rewritten root against an unrewritten operand and ask again. Where the two differ
+ * the ask was unclearable before this seat existed and still is; the offer names the directory the command
+ * spelled, which is the only one derivable from the text.
+ */
+export interface ReadRootGrantCandidate {
+    /** An absolute, lexically folded directory in the boundary's own spelling; never a file or a pattern. */
+    readonly dir: string;
+    /** Always the literal `true` — a shape, not a value, so the seat cannot be widened into a "maybe this
+     *  helps" hint without a visible type change. It claims THIS ask: not the deny layer (judged by pattern
+     *  rather than by root, and unmoved by any grant), and not another ask the same call may raise. */
+    readonly clearsThisAsk: true;
 }
 export interface ToolSpec<TParams extends TSchema = TSchema> {
     /**

package/dist/core/types.d.ts

@@ -13,7 +13,7 @@ import type { AgentTool, ThinkingLevel, ToolInputValidationContext, ToolInputVer
 import type { Model, StreamFn } from "../internal/llm.js";
 export type { ModelRef, ModelRole, RoleSpec, ModelRoles, Brain } from "./model-seat.js";
 export type { StaleToolResultOffloadOptions, ImageInput, TaskSpec, ShellGateDoctrine } from "./task-spec.js";
-export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
+export type { ToolEffect, ToolContentOrigin, ReversibilityVerdict, ReadRootGrantCandidate, ToolSpec, ToolReturn, NestedUsage, NestedUsageAccum, ToolExecuteContext } from "./tool-spec.js";
 export type { BeforeWriteRequest, BeforeWriteResult, BeforeWriteHook, TrackEditRequest, TrackEditResult, TrackFileEditHook, FileEditedNotice, FileEditedHook, HandsBandOptions } from "./hands-band.js";
 export type { AgentDefinition, SkillManifest, SkillSpec } from "./agent-definition.js";
 export type { McpServerSpec, A2aServerSpec, McpElicitRequest, McpElicitResponse, OnElicit } from "./mcp-server-spec.js";

package/dist/core/write-protect.d.ts

@@ -51,8 +51,13 @@ export interface WriteProtectionMatcher {
     /** The resolved rows this judge was compiled from (canonical names — the disclosure face). */
     readonly rows: readonly WriteProtectedRow[];
     /** Judge ONE path spelling. Returns the first matching row (basename rows first, then segment,
-     *  then segment-run — deterministic), or null. */
-    matchPath(path: string): WriteProtectedHit | null;
+     *  then segment-run — deterministic), or null.
+     *
+     *  `cwd` = the call's LIVE tracked working directory, read at judgment time off the ONE ref the fs
+     *  hand tools resolve with — the law every path guard here follows: judge the file the tool will write.
+     *  Absent ⇒ judged exactly as given — the historical reading, and the honest answer for a host
+     *  that tracks no cwd. */
+    matchPath(path: string, cwd?: string): WriteProtectedHit | null;
 }
 /**
  * Compile the write-protection judge for a deployment configuration. Returns `undefined` when the
@@ -82,4 +87,4 @@ export declare function compileWriteProtection(entries?: readonly WriteProtected
  */
 export declare function createWriteProtectionCheck(entries?: readonly WriteProtectedEntry[], opts?: {
     dataRoot?: string;
-}): ((toolName: string, args: unknown, face?: ToolCallLike["face"]) => WriteProtectedHit | null) | undefined;
+}): ((toolName: string, args: unknown, face?: ToolCallLike["face"], cwd?: string) => WriteProtectedHit | null) | undefined;

package/dist/core/write-protect.js

@@ -1,4 +1,4 @@
-import { isWinFormPath, writeTargetPath, isUncPath } from "../tools/fs/safety.js";
+import { isWinFormPath, writeTargetPath, isUncPath, isAbsoluteForFamily, joinForFamily, pathFamilyOf } from "../tools/fs/safety.js";
 import { isProtectedWrite } from "./tool-registry.js";
 import { dataRootSpellings } from "./sensitive-path-policy.js";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
@@ -182,8 +182,11 @@ export function compileWriteProtection(entries, opts) {
     }
     return {
         rows,
-        matchPath(path) {
-            const judged = relativeUnderDataRoot(path, rootViews) ?? path;
+        matchPath(path, cwd) {
+            const base = typeof cwd === "string" && cwd.length > 0 ? cwd : undefined;
+            const family = pathFamilyOf({ cwd: base });
+            const spelled = base !== undefined && family !== undefined && !isAbsoluteForFamily(family, path) ? joinForFamily(family, base, path) : path;
+            const judged = relativeUnderDataRoot(spelled, rootViews) ?? spelled;
             const judge = (raw) => {
                 if (raw.length === 0)
                     return null;
@@ -213,13 +216,13 @@ export function createWriteProtectionCheck(entries, opts) {
     const matcher = compileWriteProtection(entries, opts);
     if (matcher === undefined)
         return undefined;
-    return (toolName, args, face) => {
+    return (toolName, args, face, cwd) => {
         const call = { toolName, args, ...(face !== undefined ? { face } : {}) };
         if (!isProtectedWrite(call))
             return null;
         const path = writeTargetPath(call);
         if (typeof path !== "string" || path.length === 0)
             return null;
-        return matcher.matchPath(path);
+        return matcher.matchPath(path, cwd);
     };
 }