@sema-agent/core 7.8.0 → 7.9.1

package/dist/core/runner/session-rule-policy.js

@@ -2,6 +2,7 @@ import { canonicalizeTarget, writeTargetPath } from "../../tools/fs/safety.js";
 import { isWinFormPath } from "../../tools/fs/safety.js";
 import { createCoarseCommandNamePolicy, namespacedCoveringEntries, namespacedCoveringHit } from "../tool-policy.js";
 import { declaredPathTargetOf, isProtectedWrite, pathConfinableWriteToolNames, skillScopeWriteToolNames } from "../tool-registry.js";
+import { pathTargetBaseOf } from "../effective-path-target.js";
 export const PATH_WRITE_TOOLS = skillScopeWriteToolNames();
 export const PATH_CONFINABLE_WRITE_TOOLS = pathConfinableWriteToolNames();
 export function isWithin(root, p) {
@@ -65,7 +66,7 @@ export function createSessionRulePolicy(rules, opts) {
                     if (typeof path !== "string" || path.length === 0) {
                         return deny(`write tool "${req.toolName}" denied: session rule confines writes to allowDirs but the call has no resolvable path`);
                     }
-                    const canon = await canonicalizeTarget(env, path, signal, req.cwd ?? rootPath);
+                    const canon = await canonicalizeTarget(env, path, signal, pathTargetBaseOf(declared, { root: rootPath, cwd: req.cwd }));
                     if (!canon.ok) {
                         return deny(`write to "${path}" denied: its real target could not be resolved against the session-rule allowDirs`);
                     }

package/dist/core/runner/tool-end-body.d.ts

@@ -7,24 +7,31 @@
  *
  * Projections over values the caller already holds, with ONE clock read: `toolResultMsg` stamps the message
  * it mints with `Date.now()` (as it did inside the driver — the transcript's timestamp is minted where the
- * message is). Nothing here reads host state through a callback, awaits, or keeps state between calls.
+ * message is). The one callback here is the leg's card projector, handed in by every caller (it keeps the
+ * once-per-leg announce state; this module keeps none). Nothing here awaits.
  * Layer-1 machinery, not a driven lane; the prefix rule it follows is written once, on initial-run-state.ts.
  */
 import { type AgentMessage } from "../../internal/harness.js";
 import type { GateOutcome } from "../gate-outcome.js";
 import { type McpDelivered } from "../mcp-failure.js";
 import type { RecoveredOrphan } from "../session-reconcile.js";
+import { type StructuredProjector } from "./tool-output-projection.js";
 import type { WriteFamily } from "./turn-attachments.js";
 /** design/134 §3.1b — derive the thin `response` digest from a harness tool result: model-facing text
  *  content only (never `details` — the H4 thin-projection discipline), capped with a truncation note. */
 export declare function batchResponseDigest(result: unknown): string | undefined;
 /** The `tool_end` body fields projected from a harness tool result — output/truncated/totalChars via
- *  {@link toolOutputFrom} and the CC card via {@link structuredFrom}. Single construction point for BOTH
+ *  {@link toolOutputFrom} and the CC card via the LEG's projector (`Prepared.structuredProjector`: the engine card set
+ *  ∪ the caller rows' declared `renderHints.resultCards`, an undeclared type dropped and announced once per leg —
+ *  design/388 L4; handed in because the once-per-leg state lives on the leg). Single construction point for BOTH
  *  the live loop's frames and the resumed batch's frames (`resolvePendingCall` + the deferred-sibling
  *  close): the resumed frames used to carry only `isError`, so a client rendering tool output from frames
  *  showed an empty body for every durable-approved call. Same projection = same source as the transcript.
  *  Also the one place the gate outcome reaches a frame — see the parameter. */
 export declare function toolEndBodyFrom(result: unknown, isError: boolean, 
+/** The leg's card projector — see the doc above. A parameter, never a module default: a body minted with the engine
+ *  set alone would silently drop every declared caller card and never announce. */
+structured: StructuredProjector, 
 /** The gate's record of the pass that admitted or refused this call, supplied by the CALLER of this
  *  projection — the live loop reads it off the gate's per-call sideband, the resumed leg off the decide's
  *  minted record. Deliberately a parameter and never derived from `result`: a tool's own `details`
@@ -58,10 +65,10 @@ gatedCallIdOfRun?: string): {
  * disagreed. The projection goes through the same {@link toolEndBodyFrom} every live tool result uses, so
  * `output` = the persisted model-facing text and `errorCode` = the persisted `details.errorKind`
  * (`interrupted_never_started` / `interrupted_outcome_unknown`) — a consumer discriminates on the code
- * instead of prose-matching. No `structured`: the reconcile mints no CC card (no `details.type`), which
- * `structuredFrom`'s allowlist already enforces.
+ * instead of prose-matching. No `structured`: the reconcile mints no CC card (no `details.type`), which the
+ * leg's projector already enforces.
  */
-export declare function reconciledToolEndBody(orphan: Pick<RecoveredOrphan, "text" | "errorKind">): ReturnType<typeof toolEndBodyFrom>;
+export declare function reconciledToolEndBody(orphan: Pick<RecoveredOrphan, "text" | "errorKind">, structured: StructuredProjector): ReturnType<typeof toolEndBodyFrom>;
 /** task #51 F2/F3 — the CANONICAL write-tool → reminder-window mapping (CC qFm :480253-480254
  *  `a.name === bD || a.name === hF` = TaskCreate/TaskUpdate; BFm :480217-480219 = TodoWrite). Live
  *  deployment-alias resolution happens at the call sites (run-local `writeFamilyOf` over the mounted

package/dist/core/runner/tool-end-body.js

@@ -1,7 +1,7 @@
 import {} from "../../internal/harness.js";
 import { MCP_DELIVERY_VERDICTS } from "../mcp-failure.js";
 import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
-import { structuredFrom, toolOutputFrom } from "./tool-output-projection.js";
+import { toolOutputFrom } from "./tool-output-projection.js";
 import { TASK_CREATE_TOOL_NAME, TASK_UPDATE_TOOL_NAME, TODO_WRITE_TOOL_NAME } from "../tool-catalog-entries.js";
 const BATCH_RESPONSE_MAX_CHARS = 500;
 export function batchResponseDigest(result) {
@@ -32,9 +32,9 @@ export function batchResponseDigest(result) {
         ? `${text.slice(0, BATCH_RESPONSE_MAX_CHARS)}…[+${text.length - BATCH_RESPONSE_MAX_CHARS} chars truncated]`
         : text;
 }
-export function toolEndBodyFrom(result, isError, gate, gatedCallIdOfRun) {
+export function toolEndBodyFrom(result, isError, structured, gate, gatedCallIdOfRun) {
     const o = toolOutputFrom(result);
-    const st = structuredFrom(result);
+    const st = structured(result);
     const det = isError ? result?.details : undefined;
     const codeRaw = det?.code;
     const kindRaw = det?.errorKind;
@@ -51,8 +51,8 @@ export function toolEndBodyFrom(result, isError, gate, gatedCallIdOfRun) {
         ...(gate !== undefined ? { gate } : {}),
     };
 }
-export function reconciledToolEndBody(orphan) {
-    return toolEndBodyFrom({ content: orphan.text, details: { code: orphan.errorKind } }, true);
+export function reconciledToolEndBody(orphan, structured) {
+    return toolEndBodyFrom({ content: orphan.text, details: { code: orphan.errorKind } }, true, structured);
 }
 export function writeFamilyOfCanonical(name) {
     if (name === TASK_CREATE_TOOL_NAME || name === TASK_UPDATE_TOOL_NAME)

package/dist/core/runner/tool-face-overlay.js

@@ -1,6 +1,6 @@
 import { MCP_NAMESPACE } from "../protocol-table.js";
 import { mintNamespacePrefix } from "../protocol-naming.js";
-import { TOOL_APPROVAL_CARDS, TOOL_FAMILIES, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, TOOL_KEY_MAX_CHARS } from "../tool-face.js";
+import { TOOL_APPROVAL_CARDS, TOOL_FAMILIES, TOOL_PATH_ABSENCES, TOOL_PATH_ACCESSES, TOOL_PATH_BASES, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, TOOL_KEY_MAX_CHARS, } from "../tool-face.js";
 import { inputKeysOf } from "../tool-roster.js";
 import { deliverEngineNotice } from "../engine-notice.js";
 export const APPROVAL_CARD_REQUIRED_KEYS = Object.freeze({
@@ -26,9 +26,28 @@ export function toolFaceProblem(face, schema) {
     if (face.pathTarget !== undefined) {
         if (typeof face.pathTarget.param !== "string" || !top.has(face.pathTarget.param))
             return `pathTarget.param ${JSON.stringify(face.pathTarget.param)} is not a top-level property of the tool's schema`;
-        if (!["read", "create", "edit"].includes(face.pathTarget.access))
+        if (!TOOL_PATH_ACCESSES.includes(face.pathTarget.access))
             return `pathTarget.access ${JSON.stringify(face.pathTarget.access)} is outside the closed set`;
-        const long = overlong("pathTarget.param", [face.pathTarget.param]) ?? overlong("pathTarget.aliases", face.pathTarget.aliases ?? []);
+        const base = face.pathTarget.base;
+        if (base !== undefined && !TOOL_PATH_BASES.includes(base))
+            return `pathTarget.base ${JSON.stringify(base)} is outside the closed set`;
+        if (base === "root" && face.pathTarget.access !== "read")
+            return `pathTarget.base "root" needs pathTarget.access "read" — two write guards (the session-transcript directory guard and the frozen-spec deny) resolve a write target against the call's working directory only, so a write face declaring a root base would be judged on two different files (#638)`;
+        const absent = face.pathTarget.absent;
+        if (absent !== undefined && !TOOL_PATH_ABSENCES.includes(absent))
+            return `pathTarget.absent ${JSON.stringify(absent)} is outside the closed set`;
+        if (absent === "base" && face.pathTarget.access !== "read")
+            return `pathTarget.absent "base" needs pathTarget.access "read" — it says the call is about the whole base directory when the slot is empty, which is a search SCOPE; a write with no path names no file, and the containment fences judge a write on its own target`;
+        const patternParam = face.pathTarget.patternParam;
+        if (patternParam !== undefined) {
+            if (typeof patternParam !== "string" || !top.has(patternParam))
+                return `pathTarget.patternParam ${JSON.stringify(patternParam)} is not a top-level property of the tool's schema`;
+            if (absent !== "base")
+                return `pathTarget.patternParam ${JSON.stringify(patternParam)} is declared but pathTarget.absent is ${JSON.stringify(absent ?? "none")} — the pattern base is only ever read for an absent slot, so this declaration would be inert`;
+        }
+        const long = overlong("pathTarget.param", [face.pathTarget.param]) ??
+            overlong("pathTarget.aliases", face.pathTarget.aliases ?? []) ??
+            overlong("pathTarget.patternParam", patternParam === undefined ? [] : [patternParam]);
         if (long !== undefined)
             return long;
         vocabulary.add(face.pathTarget.param);

package/dist/core/runner/tool-output-projection.d.ts

@@ -9,14 +9,17 @@ export declare const toolOutputFrom: (result: unknown) => {
     truncated: boolean;
     totalChars?: number;
 } | undefined;
+/** The `tool_end.structured` projection over a harness tool result: the CC card when `details.type` names a card
+ *  the leg admits, else undefined. Minted per leg by {@link createStructuredProjector}; every body projection takes it
+ *  as a parameter — there is no module-level card set to fall back to. */
+export type StructuredProjector = (result: unknown) => unknown;
 /**
  * L4's run-time half (design/388 §2.4): a per-leg projector — the engine card set plus the leg's declared
- * caller cards — that DROPS an undeclared `details.type` exactly as the module-level gate does and announces
- * it ONCE per leg (`config.tool_card_undeclared`, audience operator). The module-level {@link structuredFrom}
- * is this projector over the engine set alone, with no announce seat.
+ * caller cards — that DROPS an undeclared `details.type` and announces it ONCE per leg
+ * (`config.tool_card_undeclared`, audience operator). With no options it is the engine set alone, unannounced —
+ * the shape a caller outside a leg (a test, a fixture) uses.
  */
-export declare function createStructuredProjector(opts: {
+export declare function createStructuredProjector(opts?: {
     declaredCards?: Iterable<string>;
     onUndeclared?: (type: string) => void;
-}): (result: unknown) => unknown;
-export declare const structuredFrom: (result: unknown) => unknown;
+}): StructuredProjector;

package/dist/core/runner/tool-output-projection.js

@@ -58,7 +58,7 @@ export const toolOutputFrom = (result) => {
     return { output: raw, truncated: true, totalChars };
 };
 const CC_DETAIL_TYPES = engineCardTypes();
-export function createStructuredProjector(opts) {
+export function createStructuredProjector(opts = {}) {
     const allowed = new Set([...CC_DETAIL_TYPES, ...(opts.declaredCards ?? [])]);
     const announced = new Set();
     return (result) => {
@@ -89,20 +89,3 @@ function boundedCard(details) {
     }
     return details;
 }
-export const structuredFrom = (result) => {
-    const details = result !== null && typeof result === "object" ? result.details : undefined;
-    if (details === null || typeof details !== "object")
-        return undefined;
-    const t = details.type;
-    if (typeof t !== "string" || !CC_DETAIL_TYPES.has(t))
-        return undefined;
-    try {
-        const serialized = JSON.stringify(details) ?? "";
-        if (serialized.length > MAX_TOOL_END_OUTPUT_CHARS * 4)
-            return undefined;
-    }
-    catch {
-        return undefined;
-    }
-    return details;
-};

package/dist/core/runner/turn-attachments.d.ts

@@ -110,7 +110,7 @@ export interface TurnAttachment {
     source: AttachmentSource;
     body: string;
 }
-/** H4 — the thin projection of a todo list kept run-local (NEVER the wire-capped structuredFrom card).
+/** H4 — the thin projection of a todo list kept run-local (NEVER the wire-capped `tool_end.structured` card).
  *  Pure CONTENT memory: the write-window anchor lives on {@link AttachmentState.todoLastWriteTurn}
  *  (task #51 F3 — the window resets on tool-call INITIATION, which may precede/outlive any ingest). */
 export interface ListProjection {
@@ -273,7 +273,7 @@ export declare const INSTRUCTIONS_CHANGE_BYTE_CAP = 512;
  */
 export declare function createAttachmentState(): AttachmentState;
 /**
- * H4 — thin-projection reducer over a tool's RAW `result.details` (NOT the wire `structuredFrom`
+ * H4 — thin-projection reducer over a tool's RAW `result.details` (NOT the wire card projector
  * projection and its 4×16K caps: a huge todo list must shrink into a bounded snapshot here, never
  * disarm the reminder by being dropped wholesale). Only the first-party discriminants `todo` /
  * `task` / `task-list` are recognized — every other card type (subagent `agent`/`fork`/`task-output`,

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

@@ -2,7 +2,8 @@ import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { canonicalizeTarget, expandHomeTilde, isAbsolutePathForm, isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
 import { compileSegmentPattern, matchSegmentPatterns } from "../tools/fs/read-deny.js";
-import { isProtectedWrite } from "./tool-registry.js";
+import { isProtectedWrite, protectivePathTargetOf } from "./tool-registry.js";
+import { pathTargetBaseOf } from "./effective-path-target.js";
 export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".env",
     ".env.*",
@@ -97,10 +98,11 @@ export function createSensitivePathPolicy(opts) {
                 return { action: "allow" };
             if (guardedByName !== undefined ? !guardedByName.has(req.toolName) : !isProtectedWrite(req))
                 return { action: "allow" };
-            const path = writeTargetPath(req);
+            const protective = protectivePathTargetOf(req);
+            const path = writeTargetPath(req, protective);
             if (typeof path !== "string" || path.length === 0)
                 return { action: "allow" };
-            const canon = await canonicalizeTarget(opts.env, path, signal, req.cwd ?? opts.rootPath);
+            const canon = await canonicalizeTarget(opts.env, path, signal, pathTargetBaseOf(protective, { root: opts.rootPath, cwd: req.cwd }));
             if (!canon.ok) {
                 if (canon.unresolvedSymlink) {
                     return {

package/dist/core/shell-lexer.d.ts

@@ -0,0 +1,47 @@
+/** One argv word as the lexer read it. */
+export interface ShellWord {
+    /** The word's value with quotes and escapes removed — meaningful only when `expands` is `false`. */
+    readonly text: string;
+    /** The unquoted source spelling (assignment and wrapper-flag tests read this, never `text`). */
+    readonly raw: string;
+    /** `false`: a literal word. `"one"`: carries an expansion but yields exactly ONE word (it was double-quoted).
+     *  `"many"`: an unquoted expansion, glob or brace pattern, or a quoted `"$@"` / array expansion — may
+     *  yield zero, one or several words. */
+    readonly expands: false | "one" | "many";
+}
+/** One program run the lexer found, after keyword stripping. */
+export interface ShellSegment {
+    /** The run as SPELLED (a leading keyword removed): the first candidate a rule is compared against. */
+    readonly argv: readonly ShellWord[];
+    /** The deeper candidates, one per peeled layer (leading assignments, then each wrapper of the table):
+     *  `sudo -u root rm -r x` ⇒ `[[rm, -r, x]]`. Empty when nothing peeled. */
+    readonly peeled: readonly (readonly ShellWord[])[];
+    /** Present when this segment's program runs cannot be known from the text at all; `argv` then holds
+     *  whatever was read before the failure and must not be matched as a run. */
+    readonly unreadable?: string;
+    /** Present when the segment's program runs are NOT fully known although its candidates could be read:
+     *  a peel that stopped before the wrapped program could be named (its options carry an expansion, a
+     *  command string, an option of unknown arity), or a command/process substitution anywhere in the
+     *  segment (it runs a program the lexer does not read). The candidates stand — a rule they reach is
+     *  reached — and every other rule reads `unreadable`. */
+    readonly peelUnreadable?: string;
+}
+/** A command line as the tightening reader sees it. */
+export interface ShellCommandShape {
+    readonly segments: readonly ShellSegment[];
+    /** The connector BETWEEN each consecutive pair of segments (`;` `&&` `||` `|` `|&` `&` `\n`). */
+    readonly connectors: readonly string[];
+    /** A subshell, group, control-structure keyword or dropped empty piece bounded the segments: the
+     *  connector list is not one flat chain a compound rule could spell. */
+    readonly grouped: boolean;
+}
+export { SHELL_WRAPPER_TABLE, type ShellWrapperName } from "./shell-wrapper-table.js";
+/** Longer than this and the command is not read at all (one unreadable segment): every pass is linear,
+ *  but a substitution nested inside quoting re-enters the quote reader once per nesting level, and the
+ *  cap is what bounds that on model-supplied text. Upstream's own reader stops at the same size. */
+export declare const MAX_SHELL_READ_CHARS = 10000;
+/** Read `source` as the tightening reader must: every program run the text could perform, or why it cannot be read. */
+export declare function readShellCommand(source: string): ShellCommandShape;
+/** Every program run of `shape` can be NAMED from the text: no segment is unreadable, no peel stopped,
+ *  and every run candidate's program word is literal. The offer/mint side's "judgeable" question. */
+export declare function isFullyReadable(shape: ShellCommandShape): boolean;