@sema-agent/core 7.9.0 → 7.9.1

package/dist/core/permission-rules.js

@@ -1,8 +1,9 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
-import { isUsablePathBase, lexicalNormalAbsolutePathOf, parseRuleText, pathRuleReaches, ruleReachesProgramRun } from "./permission-rule-model.js";
-import { pathTargetValue, protectivePathTargetOf } from "./tool-registry.js";
+import { isUsablePathBase, parseRuleText, pathRuleReaches, programRunReachOf } from "./permission-rule-model.js";
+import { effectivePathTargetOf } from "./effective-path-target.js";
+import { protectivePathTargetOf } from "./tool-registry.js";
 export { parsePermissionRule };
 export const BASH_GENERIC_PARAMS = new Set(catalogRuleFaceOf("Bash")?.params ?? []);
 const DEFAULT_CAPS = {
@@ -317,18 +318,34 @@ export function createPermissionRulePolicy(rules, opts) {
     const coveringHit = (lane, toolName) => lane.length === 0 ? undefined : lane.find((r) => namespacedRuleNameCovers(r.ruleName, toolName));
     const hasCovering = namespacedCovering.deny.length > 0 || namespacedCovering.ask.length > 0 || namespacedCovering.allow.length > 0;
     const commandParam = catalogRuleFaceOf("Bash")?.primaryParams[0] ?? "command";
-    const cwdBase = (pathBases.cwd ?? pathBases.root ?? "").replace(/\/+$/, "");
     const contentHit = (lane, req) => {
         if (lane.length === 0)
             return undefined;
-        const pt = protectivePathTargetOf(req);
-        const spelled = pt !== undefined ? pathTargetValue(req.args, pt) : undefined;
-        const target = spelled === undefined ? undefined : lexicalNormalAbsolutePathOf(spelled.startsWith("/") ? spelled : `${cwdBase}/${spelled}`);
+        const target = effectivePathTargetOf(req, protectivePathTargetOf(req), pathBases);
         const command = isPlainObjectArgs(req.args) ? req.args[commandParam] : undefined;
-        return lane.find((r) => r.parsed.match === "subpath" || r.parsed.match === "path"
-            ? target !== undefined && pathRuleReaches(r.parsed, target, pathBases)
-            : typeof command === "string" && ruleReachesProgramRun(r.parsed, command));
+        let unreadable;
+        for (const r of lane) {
+            if (r.parsed.match === "subpath" || r.parsed.match === "path") {
+                if (target !== undefined && pathRuleReaches(r.parsed, target, pathBases))
+                    return { rule: r };
+                continue;
+            }
+            if (typeof command !== "string")
+                continue;
+            const outcome = programRunReachOf(r.parsed, command);
+            if (outcome.reach === "reached")
+                return { rule: r };
+            if (outcome.reach === "unreadable")
+                unreadable ??= { rule: r, unreadable: outcome.reason };
+        }
+        return unreadable;
     };
+    const unreadableAsk = (hit, req) => ({
+        action: "ask",
+        message: `tool "${req.toolName}" needs approval: the command could not be read against the permission rule ${hit.rule.ruleText} (${hit.unreadable}) — a person must decide`,
+        matchedAskRule: hit.rule.ruleText,
+        requiresRealApproval: true,
+    });
     return {
         nameSets: [nameSets],
         check(req) {
@@ -342,15 +359,19 @@ export function createPermissionRulePolicy(rules, opts) {
                 if (coveringDeny)
                     return { action: "deny", message: ruleMessage("denied", coveringDeny.ruleText, coveringDeny.source) };
             }
+            const contentDeny = entry !== undefined ? contentHit(entry.content.deny, req) : undefined;
+            if (contentDeny !== undefined && contentDeny.unreadable === undefined) {
+                return { action: "deny", message: ruleMessage("denied", contentDeny.rule.ruleText, contentDeny.rule.source) };
+            }
             if (entry) {
-                const contentDeny = contentHit(entry.content.deny, req);
-                if (contentDeny) {
-                    return { action: "deny", message: ruleMessage("denied", contentDeny.ruleText, contentDeny.source) };
-                }
                 const paramDeny = matchParamRules(entry.param.deny, req.args, caps.maxScalarValueChars);
                 if (paramDeny) {
                     return { action: "deny", message: ruleMessage("denied", paramDeny.ruleText, paramDeny.source) };
                 }
+            }
+            if (contentDeny?.unreadable !== undefined)
+                return unreadableAsk({ rule: contentDeny.rule, unreadable: contentDeny.unreadable }, req);
+            if (entry) {
                 if (entry.bare.ask) {
                     return { action: "ask", message: ruleMessage("flagged", entry.bare.ask.ruleText, entry.bare.ask.source), matchedAskRule: entry.bare.ask.ruleText };
                 }
@@ -362,8 +383,10 @@ export function createPermissionRulePolicy(rules, opts) {
             }
             if (entry) {
                 const contentAsk = contentHit(entry.content.ask, req);
-                if (contentAsk) {
-                    return { action: "ask", message: ruleMessage("flagged", contentAsk.ruleText, contentAsk.source), matchedAskRule: contentAsk.ruleText };
+                if (contentAsk !== undefined) {
+                    if (contentAsk.unreadable !== undefined)
+                        return unreadableAsk({ rule: contentAsk.rule, unreadable: contentAsk.unreadable }, req);
+                    return { action: "ask", message: ruleMessage("flagged", contentAsk.rule.ruleText, contentAsk.rule.source), matchedAskRule: contentAsk.rule.ruleText };
                 }
                 const paramAsk = matchParamRules(entry.param.ask, req.args, caps.maxScalarValueChars);
                 if (paramAsk) {

package/dist/core/persisted-rule-arms.d.ts

@@ -18,6 +18,9 @@ import type { PersistedRuleHit, PersistedRuleHitRule } from "./hooks.js";
 export interface PersistedRuleRead {
     readonly hit?: PersistedRuleHit;
     readonly unreadable?: true;
+    /** The lexer's reason when the CALL could not be read against the person's deny/ask rows (absent for
+     *  a store read failure) — the message says which it was; the decision is the same. */
+    readonly reason?: string;
 }
 /** Display form of a rule set (design/375 §5.1): every rule text is a DISPLAY value on a human trust
  *  boundary, and the set must stay readable however large a lane makes it — each member rides
@@ -42,8 +45,10 @@ export declare function disclosedRuleSet(rules: readonly PersistedRuleHitRule[])
  *    ask, the marker is stamped if absent and the message names the rule — the standing question
  *    outranks a remembered yes across lanes, exactly as the DSL's own order says within one; a deny
  *    stays a deny.
- *  · UNREADABLE — the wired store could not be read (a read failure, a timeout): the person's deny/ask
- *    rows cannot be enforced, so the call fails CLOSED the way an unreadable org snapshot does — an
+ *  · UNREADABLE — the wired store could not be read (a read failure, a timeout), or the CALL could not be
+ *    read against the person's standing deny/ask rows (`reason` carries the lexer's word: an expansion
+ *    where a rule reads a word, an unterminated quote, a syntax error): the person's deny/ask rows
+ *    cannot be enforced for this call, so it fails CLOSED the way an unreadable org snapshot does — an
  *    allow tightens to an ask carrying `requiresRealApproval` (no automatic lane clears it; the gate
  *    derives the origin `rule_store_unavailable` from its own record of the read), an ask acquires the
  *    bit, a deny stays a deny. Reading an unreadable store as "no rule" would erase every deny the

package/dist/core/persisted-rule-arms.js

@@ -8,7 +8,9 @@ export function applyPersistedTightening(decision, read) {
     if (read?.unreadable === true) {
         if (decision.action === "deny")
             return { decision };
-        const message = "the persisted permission-rule store could not be read for this call — the person's own deny/ask rules cannot be enforced, so this call needs a real approval until the store is readable";
+        const message = read.reason !== undefined
+            ? `this call could not be read against the person's standing deny/ask rules (${read.reason}) — whether one of them forbids it is unknown, so it needs a real approval`
+            : "the persisted permission-rule store could not be read for this call — the person's own deny/ask rules cannot be enforced, so this call needs a real approval until the store is readable";
         return {
             decision: decision.action === "allow"
                 ? { action: "ask", message, decisionReason: "persisted_rule", requiresRealApproval: true, ...(decision.updatedInput !== undefined ? { updatedInput: decision.updatedInput } : {}) }

package/dist/core/runner/active-skill-scope.js

@@ -1,5 +1,6 @@
 import { canonicalizeTarget } from "../../tools/fs/safety.js";
 import { pathTargetValue } from "../tool-registry.js";
+import { pathTargetBaseOf } from "../effective-path-target.js";
 import { PATH_WRITE_TOOLS, isWithin } from "./session-rule-policy.js";
 import { parseSkillToolEntry, skillSpecifierRejection } from "../skill-tool-specifier.js";
 export class ActiveSkillScope {
@@ -99,7 +100,7 @@ export function createActiveSkillScopePolicy(opts) {
                             decisionReason: "safety",
                         };
                     }
-                    const canon = await canonicalizeTarget(env, path, signal, req.cwd ?? rootPath);
+                    const canon = await canonicalizeTarget(env, path, signal, pathTargetBaseOf(declaredTarget, { root: rootPath, cwd: req.cwd }));
                     if (!canon.ok) {
                         return {
                             action: "deny",

package/dist/core/runner/permission-rule-lanes.d.ts

@@ -26,7 +26,7 @@
  * silence the ungated-write warning for deployments that wired no policy at all.
  */
 import type { AskRuleEvidence, ToolCallRequest } from "../tool-policy.js";
-import { persistedRuleMandateOf, type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit } from "../hooks.js";
+import { persistedRuleMandateOf, type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit, type PersistedRuleUnreadable } from "../hooks.js";
 import type { PersistedRule, PersistedRuleVerdict, RuleOffer, SegmentCoverage } from "../permission-rule-model.js";
 import { type OrgRuleResolution } from "../permission-rule-org.js";
 import type { PermissionRuleStoreProvider } from "../permission-rule-provider.js";
@@ -79,11 +79,19 @@ export declare function orgRevisionEvidenceOf(resolution: OrgRuleResolution, onD
  * aliased: the evidence must not change under a store that reuses its row objects.
  */
 export declare function persistedRuleHitOf(verdict: PersistedRuleVerdict | undefined): PersistedRuleHit | undefined;
+/** The COMMAND arm's projection of a verdict: a call the lexer could not read against a standing deny/ask
+ *  row is the lane's UNREADABLE answer — the same fail-closed shape an unreadable store takes (a
+ *  real-approval ask no automatic lane clears), with the lexer's reason in place of the store's — never a
+ *  matched ask rule, which would let a blanket `onAsk: "allow"` clear a question nobody can answer. Every
+ *  other verdict is {@link persistedRuleHitOf}'s hit. */
+export declare function persistedRuleAnswerOf(verdict: PersistedRuleVerdict | undefined): PersistedRuleHit | PersistedRuleUnreadable | undefined;
 /**
  * design/382 §2.5-1, widened to every path-targeting tool — the persisted-rule lane's PATH arm: the call's
- * target path in the SAME lexical identity the rule family is defined over — absolute as spelled, relative
- * resolved against the LIVE tracked working directory (the very base the file tools themselves resolve
- * against; task root when no tracker moved), then normalized lexically, zero IO.
+ * target path in the SAME lexical identity the rule family is defined over, resolved by the ONE reader every
+ * fence and every tool goes through (`effectivePathTargetOf`), so the lane judges the path the tool will
+ * really open. The tool's own declaration decides which base a relative spelling takes and what an ABSENT
+ * slot means — the lane no longer guesses `liveCwd ?? root` for every tool, which was wrong for the two
+ * search tools in three separate shapes (see effective-path-target.ts). Still zero IO.
  *
  * TWO readings of the call's path slot, one per direction (design/388 B6/B17): the tightening arms judge
  * the PROTECTIVE target (the object face's declaration, the catalog's for the name as the floor — reading

package/dist/core/runner/permission-rule-lanes.js

@@ -1,6 +1,7 @@
 import { persistedRuleMandateOf } from "../hooks.js";
-import { adjudicatePersistedPathRules, adjudicatePersistedRules, lexicalNormalAbsolutePathOf, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
-import { declaredPathTargetOf, pathTargetValue, protectivePathTargetOf } from "../tool-registry.js";
+import { adjudicatePersistedPathRules, adjudicatePersistedRules, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { effectivePathTargetOf } from "../effective-path-target.js";
+import { declaredPathTargetOf, protectivePathTargetOf } from "../tool-registry.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 export const PERSISTED_RULE_TOOL = "Bash";
 const HANDOFF_BOUND = 256;
@@ -24,21 +25,18 @@ export function persistedRuleHitOf(verdict) {
         ? undefined
         : { behavior: verdict.behavior, rules: verdict.rules.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
 }
+export function persistedRuleAnswerOf(verdict) {
+    if (verdict?.unreadable !== undefined)
+        return { unreadable: true, reason: verdict.unreadable };
+    return persistedRuleHitOf(verdict);
+}
 export function pathRuleLaneAnswer(table, req, ctx) {
-    const base = (ctx.liveCwd ?? ctx.root ?? "").replace(/\/+$/, "");
-    const resolve = (pt) => {
-        if (pt === undefined)
-            return undefined;
-        const spelled = pathTargetValue(req.args, pt);
-        if (spelled === undefined)
-            return undefined;
-        return lexicalNormalAbsolutePathOf(spelled.startsWith("/") ? spelled : `${base}/${spelled}`);
-    };
-    const tighten = resolve(protectivePathTargetOf(req));
-    const allow = resolve(declaredPathTargetOf(req));
+    const bases = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}) };
+    const tighten = effectivePathTargetOf(req, protectivePathTargetOf(req), bases);
+    const allow = effectivePathTargetOf(req, declaredPathTargetOf(req), bases);
     if (tighten === undefined && allow === undefined)
         return undefined;
-    return persistedRuleHitOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}) }));
+    return persistedRuleHitOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, bases));
 }
 export function createPermissionRuleLanes(cfg) {
     const provider = cfg.provider;
@@ -137,7 +135,7 @@ export function createPermissionRuleLanes(cfg) {
                 const execCwd = liveCwd !== undefined ? { execCwd: liveCwd } : {};
                 const verdict = adjudicatePersistedRules(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
                 if (verdict !== undefined)
-                    return persistedRuleHitOf(verdict);
+                    return persistedRuleAnswerOf(verdict);
                 const coverage = segmentCoverageOf(command, { persisted: table }, { tool: req.toolName, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
                 return coverage !== undefined ? { segmentCoverage: coverage } : undefined;
             },

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-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/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;