@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/permissions/file-rules.d.ts

@@ -0,0 +1,384 @@
+export type FileRuleKind = "edit" | "read";
+/**
+ * SV-7 (the router same-view test): claude's file-rule grammar has only TWO pattern kinds --
+ * `Edit(...)` and `Read(...)`. Dump-confirmed: `ln`'s own dispatch switch has exactly two cases
+ * (`case"edit":return tn;case"read":return wt`, each a SINGLE literal tool-name string `ub` filters
+ * `ruleValue.toolName` against by exact equality) -- there is no third "write" kind anywhere in the
+ * data model. Claude's own WRITE decision function (`zC`) ALWAYS consults `"edit"`-kind rules,
+ * regardless of which literal write-shaped tool called it -- this is what makes an `Edit(...)` ask
+ * rule fire before a **Write** on claude (the router's own SV-7 measurement), and what makes a
+ * `Write(...)`-toolName rule a Winter-only spelling with no claude analogue at all: `ub` filtering
+ * on the literal string "Write" never runs, because nothing ever calls it with that string.
+ *
+ * Every `FILE_RULE_TOOLS` member (grammar.ts) routes to exactly one kind, on every direction (allow,
+ * ask, deny alike -- the ruling's own "for both ALLOW and DENY" instruction, extended to ask since
+ * ask shares deny's conservative "cross tools" posture throughout this codebase already).
+ */
+export declare function fileRuleKindFor(toolName: string): FileRuleKind | undefined;
+/**
+ * The ONE literal tool name a rule must be AUTHORED under to ever be consulted for `kind` -- claude's
+ * own `ub` filters `ruleValue.toolName` by EXACT STRING EQUALITY against a single literal per kind
+ * (`tn`/`"Edit"` for `"edit"`, `wt`/`"Read"` for `"read"`; dump-confirmed, `ln`'s own two-case
+ * switch), never against every tool that happens to share the kind. This is what makes SV-7's
+ * "reverse" finding true: a rule AUTHORED as `Write(...)`, `NotebookEdit(...)`, `Glob(...)` or
+ * `Grep(...)` is dead code claude never reads for ANY call -- not even a call from that SAME literal
+ * tool -- because `ub` was never invoked with that string. `Write`/`NotebookEdit`/`Glob`/`Grep`
+ * remain valid rule-authoring tool names SYNTACTICALLY (grammar.ts's `FILE_RULE_TOOLS` still parses
+ * them -- Winter does not forbid authoring one), but this function is what `findMatchingFileRuleEntry`
+ * (evaluator.ts) filters CANDIDATES with, so only `Edit(...)`/`Read(...)`-authored rules ever reach
+ * a group.
+ */
+export declare function canonicalFileRuleAuthoringToolName(kind: FileRuleKind): "Edit" | "Read";
+/** A sentinel distinct from `null` ("resolve against cwd"): a `/`-anchored rule with no resolvable settings-source directory is INERT, never falls back to cwd. */
+declare const INERT_ANCHOR: unique symbol;
+export interface FileRuleAnchor {
+    /** The pattern text, relative to `root`, in `ignore`-package (gitignore) grammar. */
+    relativePattern: string;
+    /** `null` means "resolve against cwd" (`Ma`'s own `P ?? te()`, ported as `root ?? opts.cwd`); the sentinel means the anchor can never match anything. */
+    root: string | null | typeof INERT_ANCHOR;
+}
+/**
+ * `jOe` (dump-confirmed): the FOUR anchor spellings WS-07 §3.1 documents, resolved to a
+ * `{relativePattern, root}` pair -- ported exactly, including the leading-slash-KEPT behaviour on
+ * the three anchored forms (`//x`, `~/x`, `/x`) that is what makes them root-anchored in gitignore
+ * terms, and its ABSENCE on `./x`/bare `x` that is what lets `deny ./.env` reach `pkg/.env` (C-1's
+ * own example) -- a bare pattern with no leading slash and no inner slash is exactly the shape the
+ * `ignore` package's own `^(?=[^^])` -> `(?:^|\/)` replacer un-anchors.
+ *
+ * A bare `~` (no trailing slash) is NOT specially handled by claude's own `jOe` either -- it falls
+ * through to the final else branch as a literal filename pattern `"~"`, cwd-anchored. Ported
+ * faithfully rather than "fixed", matching this module's own "port what was measured" discipline.
+ *
+ * `sourceDir` is claude's `bl(source)` -- the settings-source-derived root for a `/`-anchored rule.
+ * Since fix round 11 a settings-tier rule carries it (`SourcedRuleEntry.sourceDir`, set by
+ * production-wiring.ts's `buildSettingsRuleSeed` per claude's `Wyt`), and a `/`-anchored rule resolves
+ * against it. When it is absent -- a rule from Options, canUseTool or a plugin -- the rule is inert
+ * (the `INERT_ANCHOR` root below, treated as "no group to match against" by `matchFileRulesGrouped`).
+ */
+export declare function resolveFileRuleAnchor(pattern: string, opts: {
+    home: string;
+    sourceDir?: string | undefined;
+}): FileRuleAnchor;
+/**
+ * WS-21 fix round 10, item C: a Read/Edit rule's own pattern, resolved to ONE absolute filesystem
+ * path -- for the sandbox's own `subpath` rule (sandbox/profile.ts's `denyWritePaths`/
+ * `denyReadPaths`/`writableRoots`), which has no glob grammar of its own to hand a pattern string
+ * to; a real Seatbelt `subpath` already means "this directory and everything under it," so it needs
+ * ONE real path, never a pattern.
+ *
+ * `undefined` in two cases, matching claude's own observable posture (dump-confirmed, `Jm`: `let{
+ * allowOnly:t}=at.getFsWriteConfig();if(t.some(eg))return!0` -- ANY glob-shaped entry in the
+ * write-allow set makes claude's OWN sandbox stop trying to restrict writes via that mechanism at
+ * all, relying on the separate, glob-aware PERMISSION-RULE layer instead, which is unaffected by
+ * this and stays the real enforcement point):
+ *   - the pattern is INERT (a bare `/`-anchored rule with no resolvable settings-source root --
+ *     `resolveFileRuleAnchor`'s own pre-existing posture, unchanged here);
+ *   - the pattern is genuinely GLOB-SHAPED once a single TRAILING `/**` is stripped (redundant with
+ *     `subpath`'s own "and everything under it" semantics, so it is not itself disqualifying --
+ *     `Edit(//repo/secrets/**)` becomes the plain path `/repo/secrets`) -- a glob ANYWHERE else
+ *     (`src/*.ts`, `[wip]`, `a?b`) cannot become one exact path at all.
+ * A caller that gets `undefined` back simply does not add this rule to the sandbox's own filesystem
+ * lists; the permission-rule layer (`evaluate()`) still enforces it in full, exactly as it always has.
+ */
+export declare function resolveFileRuleAbsolutePath(pattern: string, opts: {
+    cwd: string;
+    home: string;
+    sourceDir?: string;
+}): string | undefined;
+/**
+ * WS-21 fix round 11 ("important" item): the sibling of `resolveFileRuleAbsolutePath` that does NOT
+ * drop a genuinely glob-shaped pattern -- it resolves the SAME anchor/root as that function but
+ * returns the absolute text WITH any remaining glob characters intact (a redundant trailing `/**` is
+ * still stripped first, identically, since `subpath`'s/the recursive-regex-suffix's own "and
+ * everything under it" semantics already cover it). `undefined` only for the one case that has no
+ * absolute form at all -- an INERT `/`-anchored pattern with no resolvable settings-source root,
+ * unchanged from `resolveFileRuleAbsolutePath`'s own posture.
+ *
+ * Exists because claude's own deny-rendering path (`dR`, dump byte 15365699 region) does NOT drop a
+ * glob-shaped deny the way `Jm`'s write-ALLOW-only short-circuit does (round 10's own `Jm` finding,
+ * `resolveFileRuleAbsolutePath`'s own header) -- a glob-shaped DENY instead becomes an SBPL `(regex
+ * ...)` clause (claude's `Li` (dump byte 15365905) / `Rt` (dump byte 15282610)) rather than being silently
+ * unenforced by the sandbox layer. Callers check `isGlobShapedFileRulePattern` on the result to
+ * decide `subpath` vs a `globToSbplRegexSource`/`recursiveGlobToSbplRegexSource` conversion; ALLOW
+ * entries keep using `resolveFileRuleAbsolutePath` (glob-shaped dropped), per the controller's own
+ * explicit ruling: "Dropping glob-shaped ALLOW rules stays as it is, because that's stricter."
+ */
+export declare function resolveFileRuleAbsoluteGlobText(pattern: string, opts: {
+    cwd: string;
+    home: string;
+    sourceDir?: string;
+}): string | undefined;
+/**
+ * claude's own `Rt` (dump byte 15282610: `e.includes("*")||e.includes("?")||e.includes("[")||e.includes("]")`),
+ * confirmed byte-equivalent to this module's own pre-existing glob-char test. Kept as the pure claude
+ * primitive; the sandbox DENY split (`splitDenyPathsByGlobShape`/`globDenyEntriesOf`) classifies with
+ * `scanDenyPathGlob` below instead (fix round 17, R.3 C-1).
+ */
+export declare function isGlobShapedFileRulePattern(text: string): boolean;
+/**
+ * Fix round 12 ("Important" item, claude's own `ed`, dump byte 15367994, found in the SAME chunk as
+ * `Ch`/`mR`/`pR` below): every ANCESTOR directory of `path`, walking up via `dirname` until reaching
+ * `/` or a fixed point -- does NOT include `path` itself, nor `/`. Feeds the ancestor-rename-bypass
+ * fix: claude's own write/read sandbox profiles additionally deny `file-write-unlink`/
+ * `file-write-create` on every ancestor of a denied path (and of a glob deny's own fixed prefix), so
+ * a sandboxed `mv <ancestor> <elsewhere> && <write inside where it used to be> && mv <elsewhere>
+ * <ancestor>` cannot rename the ancestor out of the way and back to slip a write past the deny.
+ */
+export declare function ancestorDirectoriesOf(path: string): string[];
+export declare function globToSbplRegexSource(absoluteGlob: string): string;
+/**
+ * claude's own `td` (dump byte 15365977: `Po(e).slice(0,-1)+"(/.*)?$"`) -- `globToSbplRegexSource`'s
+ * own whole-string match, WIDENED to also match "the pattern's own match point, optionally followed
+ * by `/` and anything deeper" -- the regex equivalent of `subpath`'s own implicit recursive semantics
+ * (a plain, non-glob deny already renders as `subpath`, which covers a directory AND everything under
+ * it with no extra syntax). claude's own `dR` (the deny-clause builder, same dump region) always uses
+ * this recursive form for a glob-shaped deny's OWN base clause -- never the bare `Li`/
+ * `globToSbplRegexSource` form, which claude reserves for an ALLOW-carve-out entry nested inside a
+ * deny (a feature this port does not carry -- see `resolveFileRuleAbsoluteGlobText`'s own header).
+ */
+export declare function recursiveGlobToSbplRegexSource(absoluteGlob: string): string;
+/**
+ * WS-21 fix round 11: the ONE place a plain `sandbox.filesystem.denyWrite`/`denyRead` string list
+ * (settings.json's own, user-typed, and `deriveSandboxPathsFromRules`'s own rule-derived denies,
+ * which now may ALSO contain glob-shaped text -- see `resolveFileRuleAbsoluteGlobText`'s own header)
+ * gets split by glob-shape before reaching `SeatbeltProfileInput`/`RunCommandOptions`: a non-glob
+ * entry stays a plain path (`subpath`, unchanged); a glob-shaped one is converted via
+ * `recursiveGlobToSbplRegexSource` (the recursive form, matching `subpath`'s own implicit
+ * "and everything under it" semantics and claude's own `dR`, which always uses the recursive form for
+ * a deny's own base clause). Called once per caller (tools/impl/bash.ts, tools/impl/monitor.ts) --
+ * kept as one shared, tested primitive rather than two hand-copies, per this codebase's own
+ * "a second copy would be exactly the kind of drift risk this whole phase's review lens exists to
+ * catch" precedent (evaluator.ts's `extractCandidateWritePaths`, verbatim).
+ *
+ * Fix round 12: also returns `globFixedPrefixes` -- for each glob-shaped entry, its OWN canonicalized
+ * fixed-prefix directory (claude's own `Rh(u)`, `undefined`/dropped when it resolves to `/`, matching
+ * `Ch`'s own `if(p==="/")continue`). Feeds the ancestor-rename-bypass port
+ * (`SeatbeltProfileInput.denyWriteGlobFixedPrefixes`/`denyReadGlobFixedPrefixes`, sandbox/profile.ts):
+ * the plain `paths` entries need only their OWN ancestors walked (`ed`, `ancestorDirectoriesOf`
+ * above) to close the bypass; a glob-shaped deny ALSO needs its fixed prefix walked, and the prefix
+ * itself added as a literal deny target (claude's own `Ch` adds both).
+ *
+ * Fix round 17 (R.3 C-1): classified by `scanDenyPathGlob`, not by claude's `Rt` alone -- an entry
+ * whose only glob syntax is one-character bracket classes (`/x/[[]wip] app/.winter/skills`, a literal
+ * path spelled for the glob grammar) lands in `paths` UNESCAPED (`/x/[wip] app/.winter/skills`), and a
+ * glob entry's fixed prefix runs through such classes. Winter-only hardening (R.3 C-1); claude's
+ * `Rt`/`Li` stop at the first `[` -- see `scanDenyPathGlob`'s own header.
+ */
+export declare function splitDenyPathsByGlobShape(paths: readonly string[]): {
+    paths: string[];
+    regexes: string[];
+    globFixedPrefixes: string[];
+};
+/** One glob-shaped deny entry, its recursive SBPL regex source PAIRED with its own fixed-prefix
+ * directory -- `splitDenyPathsByGlobShape`'s own `regexes`/`globFixedPrefixes` are two independently
+ * FILTERED flat arrays (the latter drops a "/" prefix entirely) with no positional correspondence
+ * once any entry is dropped from one but not the other; `fixedPrefix` here is NEVER dropped -- it is
+ * always the literal string `"/"` in that case (claude's own `Rh` returns `"/"` too, and `fR`'s own
+ * skip/ancestor logic reads that value directly rather than treating "no prefix" as a distinct case). */
+export interface GlobDenyEntry {
+    regex: string;
+    fixedPrefix: string;
+}
+/**
+ * Fix round 13 ("Important" item 1, claude's own `fR`, dump byte 15367091): the PAIRED form
+ * `buildReadDenyKeepInPlaceBlock` (sandbox/profile.ts) needs -- see `GlobDenyEntry`'s own header for
+ * why `splitDenyPathsByGlobShape`'s own two flat arrays cannot answer this. Scoped to glob-shaped
+ * entries only (a plain entry needs no pairing at all -- its own path IS both its recursive-clause
+ * anchor and its ancestor-walk root, `buildReadDenyKeepInPlaceBlock` uses `paths` directly for that).
+ */
+export declare function globDenyEntriesOf(paths: readonly string[]): GlobDenyEntry[];
+/**
+ * `xi` (dump-confirmed): collapses repeated slashes, and specially handles a LEADING BOM so it
+ * cannot accidentally trigger gitignore's own `!`/`#` line-directive meaning (negation/comment). A
+ * bare leading BOM with no `!`/`#` after it is DELETED outright (empirically verified: the first of
+ * the two `.replace()` calls below always consumes a leading BOM, since `^` in its own regex
+ * is unconditional and only the FOLLOWING `[!#]?` is optional -- the second `.replace(/^/,
+ * "[]")` is therefore unreachable dead code in the pinned binary's own source whenever the
+ * input genuinely starts with a BOM, ported here as harmless dead code too rather than "corrected"
+ * into a change of behaviour this module was not asked to make). A leading BOM immediately followed
+ * by `!` or `#` becomes an escaped literal `!`/`#` (so the directive character survives as TEXT to
+ * match, not as a line-level instruction).
+ */
+export declare function normalizeFileRulePattern(relativePattern: string): string;
+/**
+ * `ki` (dump-confirmed): a pattern ending in `/**` is rewritten before being fed to `ignore()`.
+ * - For DENY/ASK (`isAllow: false`): the trailing `/**` is simply dropped (`x/**` -> `x`), and the
+ *   result is left UNANCHORED (no leading `/` added) whenever it already has an inner `/`, is not an
+ *   allow rule, or already starts with `!`/`#` -- i.e. almost always for deny/ask. This is C-1's own
+ *   "`ki` turns a deny `x/**` into an unanchored `x`" finding: the bare `x` then matches at ANY
+ *   depth under the `ignore` package's own un-anchoring rule, covering everything under a directory
+ *   named `x` anywhere, not merely the literal anchor-relative `x/`.
+ * - For ALLOW, when the stripped form has NO inner `/` (a single segment) and does not start with
+ *   `!`/`#`: the result is instead explicitly re-anchored (`x/**` -> `/x`), so `allow x/**` stays
+ *   scoped to the anchor root rather than becoming an anywhere-match the way the deny/ask case does.
+ *   This asymmetry is real and claude's own (not the allow-exact-only asymmetry the controller
+ *   retired) -- it survives because it is measured, not invented.
+ * - A pattern whose stripped form is empty or all-slashes (`/**`, `//**`) is left as `/**`.
+ * - Any pattern that does NOT end in `/**` passes through unchanged.
+ */
+export declare function unanchorTrailingDoubleStar(pattern: string, isAllow: boolean): string;
+export interface FileRuleCandidate<TEntry> {
+    entry: TEntry;
+    /** The rule's own specifier text, exactly as authored (the `jOe`/`xi`/`ki` chain runs on this). */
+    pattern: string;
+    /** `bl(source)`'s stand-in for a `/`-anchored rule -- see `resolveFileRuleAnchor`'s own header. Absent = every `/`-anchored candidate is inert. */
+    sourceDir?: string | undefined;
+}
+/**
+ * Item 2 (fix round 9), REVISED by round 10's own item-3 ruling: a malformed pattern's own compile
+ * failure is a THROW out of `matchFileRulesGrouped`, not a direction-aware return value. Round 9
+ * tried to resolve the failure INSIDE this function (denyAsk -> the broken group's first entry,
+ * allow -> null); round 10's controller ruling is that this is not what claude does -- claude's own
+ * `Ma` has no per-group catch at all (only the per-TOOL-CALL one far above it, at `d8t`/`ome`'s own
+ * boundary), so ONE throwing group aborts the WHOLE permission check for that call, exactly the same
+ * way regardless of which direction (deny/ask/allow) was being evaluated when it happened. This
+ * class is what makes that propagation typed rather than "any thrown Error" -- caught exactly once,
+ * at `evaluator.ts`'s own `evaluate()` (the "decide this one call" boundary), and turned into the
+ * generic fail-closed deny `d8t`'s own hardcoded fallback produces.
+ */
+export declare class FileRuleCompileError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * `ln`+`Ma`, combined into one grouped match: builds ONE `ignore()` instance per anchor ROOT from
+ * every candidate (see this module's header for why grouping is load-bearing, not cosmetic), then
+ * tests `path` against each root's group in turn, returning the FIRST candidate's own `entry` whose
+ * group matched -- `null` when nothing matched anywhere. `behavior` is `"allow"` or `"denyAsk"`,
+ * mirroring `matchFileRule`'s own existing direction vocabulary (never allow AND denyAsk on the
+ * page a caller passed to `ki`, exactly as `ln`'s `r==="allow"` check is exactly `behavior==="allow"`
+ * here too).
+ *
+ * THROWS `FileRuleCompileError` (fix round 10, item 3) when any consulted anchor root's own
+ * candidate patterns fail to compile into a real `ignore()` instance -- never resolved to `null`
+ * or a particular entry here; see that class's own header for why, and `evaluator.ts`'s `evaluate()`
+ * for the one place it is caught.
+ */
+export declare function matchFileRulesGrouped<TEntry>(candidates: readonly FileRuleCandidate<TEntry>[], path: string, opts: {
+    cwd: string;
+    home: string;
+}, behavior: "allow" | "denyAsk"): TEntry | null;
+/**
+ * `Smt`'s own job (round 5's `QCt`): rewrite a path through its REAL prefix (e.g. `/private/tmp/x`, what
+ * `realpathSync` actually returns) back to the commonly-typed TRUSTED alias (`/tmp/x`) -- the
+ * direction a real, resolved path needs to go to be compared against a rule an author wrote in the
+ * short form. A path with no matching real prefix passes through unchanged.
+ */
+export declare function canonicalizeTrustedSymlinkPath(path: string): string;
+/**
+ * SV-8 (the router same-view test on the 57e7fef binary): claude's own acceptEdits
+ * working-directory boundary check is `sm` (dump-confirmed by content search) -- a plain RELATIVE-
+ * PATH PREFIX test, never a compiled glob at all. Winter's own `isWithinBounds` (evaluator.ts) used
+ * to reuse the general file-rule matcher with a `"**"` sentinel pattern -- harmless before SV-6/C-1,
+ * but once the general matcher started interpreting `[`, `]`, `*` and `\` as glob metacharacters, a
+ * cwd or additional-directory root containing any of them (e.g. `[wip] app`) made `"**"` fail to
+ * compile the way the caller intended, and acceptEdits asked for every write inside that cwd instead
+ * of auto-approving them.
+ *
+ * This function sidesteps the escaping question SV-8 raises entirely, the same way claude's own `sm`
+ * does: a plain path-prefix test never interprets EITHER path as glob syntax, so a root containing a
+ * glob-special character needs no escaping here at all -- unlike a real RULE pattern (I-G's own
+ * concern), which does.
+ *
+ * Ported: `caseFold` (default `true`, matching `sm`'s own default and I-D's case-insensitivity
+ * finding generally) folds BOTH paths before computing the relative path between them; the macOS
+ * `/private/var` -> `/var` and `/private/tmp` -> `/tmp` aliasing is real-symlink-aware -- macOS
+ * itself maintains both as symlinks to the `/private/...` originals, so a session cwd resolved
+ * through one spelling and a root configured with the other name the SAME real directory (this
+ * matters in practice: `os.tmpdir()` on macOS resolves through `/private/var/folders/...`, which is
+ * exactly the shape every mkdtemp-based fixture in this codebase's own test suite produces). Not
+ * ported: `sm`'s own `uncShapeParity` and `skipPrivateAlias` options (Windows-only concerns) and its
+ * `Gn`/`Ha` UNC-path checks -- this codebase supports macOS only (CLAUDE.md's own "latest-OS
+ * floors" rule).
+ *
+ * Fix round 6 (R5-2, the re-review against the pinned 2.1.250 dump): ONLY these TWO pairs -- round
+ * 5 widened this to the full six-pair `ni()`/`Sl()` map (`/private/etc`, `/usr/bin`, `/usr/lib`,
+ * `/usr/sbin` included), which was WRONG for `sm` specifically: content search against the pinned
+ * 2.1.250 dump (not the 2.1.280 build round 5 was cited against) found `sm`'s own alias regexes
+ * verbatim -- `g=r?/^\/private\/var\//i:/^\/private\/var\//,w=r?/^\/private\/tmp(\/|$)/i:/^\/private\/
+ * tmp(\/|$)/` -- exactly these two, unconditionally, never the wider six-pair set. Reverted to match;
+ * the six-pair map (`trustedSymlinkEquivalences`/`canonicalizeTrustedSymlinkPath`) stays, but is now
+ * used ONLY by the allow-rule retry in evaluator.ts (`cqe`'s own scope, confirmed at the same dump
+ * site), never by this function.
+ */
+export declare function isPathWithinRoot(childPath: string, rootPath: string, opts?: {
+    caseFold?: boolean;
+}): boolean;
+/**
+ * The traversal fence for a plugin MANIFEST's own declared component paths (`commands`/`agents`/
+ * `skills`/`output-styles`/`workflows`/`hooks`).
+ *
+ * Fix round 6 (R5-1 + a promoted minor, the re-review against the PINNED 2.1.250 dump): claude's own
+ * check here is `nV` (dump-confirmed by content search against the pinned dump directly, at the
+ * scratchpad path the controller named -- superseding fix round 5's citation of `KGe`/`Aoe` against
+ * the INSTALLED 2.1.280 binary, which this round's own ruling says is not the parity authority):
+ * `nV(root,entry)` resolves `entry` against `root`, computes `u=path.relative(root,resolved)`, and
+ * refuses (`return null`) when `u.startsWith("..")`. Three ways this DIFFERS from `isPathWithinRoot`/
+ * `sm` above, all ported exactly rather than reused:
+ *   1. CASE-SENSITIVE, always -- `nV`'s own body has no folding call anywhere (confirmed by reading
+ *      it in full), unlike `sm`'s own `r?/.../i:/.../ ` case-fold branching. Fix round 5's own
+ *      `resolvesWithinPluginRoot` wrongly delegated to `isPathWithinRoot`'s DEFAULT `caseFold:true`,
+ *      so on a case-sensitive volume a manifest entry like `../FOO/agents` under a root
+ *      `.../plugins/foo` was admitted (folded, `FOO` read as `foo`) where claude's own `nV` (and
+ *      this rewrite) refuses it.
+ *   2. NAIVE STRING-PREFIX, not segment-aware -- `u.startsWith("..")` is a bare string test, unlike
+ *      `sm`'s own `uj` (`/(?:^|[\\/])\.\.(?:[\\/]|$)/`, confirmed by reading ITS full definition too),
+ *      which requires a `..` SEGMENT bounded by a separator or a string edge. This means a component
+ *      name that merely STARTS WITH the two characters `..` -- e.g. `"..x/agents"`, a real,
+ *      non-escaping subdirectory name -- is REFUSED by claude too, not only a genuine `"../"` escape.
+ *      Matched here rather than "fixed", per the ruling: claude's own inconsistency between its two
+ *      path-safety mechanisms is not this codebase's to resolve by choosing the more correct one.
+ *   3. NO trusted-symlink alias mapping at all -- `nV`'s own body never calls anything resembling
+ *      `Smt`/`canonicalizeTrustedSymlinkPath`. Moot in practice here regardless, since both operands
+ *      below are ALREADY realpath'd before this comparison runs (a real, resolved path from
+ *      `/tmp`/`/var` already comes back in its long `/private/...` form either way).
+ *
+ * DISCLOSED DIVERGENCE FROM THE PINNED 2.1.250, kept as DELIBERATE HARDENING (the controller's own
+ * explicit ruling): `nV` itself is PURELY LEXICAL -- 2.1.250 has no symlink-following/realpath step
+ * for a plugin component path at all. This function still realpaths both the candidate and the
+ * plugin root first (originally ported from the INSTALLED 2.1.280 binary's own `KGe`/`Aoe`, which DID
+ * add this in a build newer than the pin), refusing a symlinked override that points outside the
+ * plugin where 2.1.250 would load it -- the safe direction, and it matches claude's own newer
+ * behaviour. `nV`'s own comparison shape (case-sensitive, naive-prefix, no alias) is then applied to
+ * the REALPATH'D forms rather than to the raw ones `nV` itself compares. `resolveRealTarget` (paths.ts)
+ * has the graceful "walk up to the nearest existing ancestor" fallback for a candidate that does not
+ * exist YET, and rethrows a non-ENOENT failure (ELOOP on a symlink cycle, EACCES, ...), caught here
+ * and treated as a refusal rather than letting a malformed manifest entry crash the whole
+ * plugin-loading pass.
+ */
+export declare function resolvesWithinPluginRoot(candidatePath: string, pluginRoot: string): boolean;
+/**
+ * Fix round 4 (I-G): a real, resolved filesystem path (e.g. `resolve(winterHome)`) can legitimately
+ * contain `[`, `]`, `*` or `\` -- none of which were glob-special under Winter's pre-fix-round-4
+ * grammar, but all four are now, since `matchFileRulesGrouped` compiles every pattern through the
+ * real `ignore` package. A caller building a rule PATTERN out of a real path (`buildBaselineDenyRules`,
+ * engine.ts) must escape these four before interpolating the path into pattern text, or a home
+ * directory literally named e.g. `/Users/name[wip]` would have its OWN floor's `[wip]` read back as
+ * a character class instead of the four literal characters it names on disk.
+ *
+ * `?` is DELIBERATELY LEFT RAW, per the controller's own ruling: claude's grammar has no working
+ * escape for `?` at all (this module's own `unanchorTrailingDoubleStar`/`\?`-quirk sibling
+ * documentation) -- an escaped `\?` would require a literal backslash the real path never has, so it
+ * would never match the floor's own intended directory at all. A bare `?` in the pattern instead acts
+ * as a single-character wildcard, which still MATCHES a real `?` in the path (a wildcard matches
+ * anything, including the literal character) -- over-matching by one character class is the safe
+ * direction for a DENY floor (WS-07 §3.1's own posture: a deny that reaches slightly too far is a
+ * false-negative-avoiding cost, never a hole), where an escape that matches NOTHING would be a hole.
+ */
+export declare function escapeFileRulePathSegment(path: string): string;
+/**
+ * A SINGLE pattern against a SINGLE path -- for a caller that is already iterating rule entries one
+ * at a time for a reason unrelated to C-1/SV-7 (e.g. evaluator.ts's own cross-tool
+ * `findFileDenyBlockingEdit`, a Winter-invented safety net with no claude analogue: claude's own
+ * Write decision never consults `Read(...)` rules at all, so "a Read deny also blocks a Write" is
+ * this codebase's own extension, not a ported behaviour). Grouping (this module's own header)
+ * therefore does not apply across DIFFERENT callers' unrelated single-pattern checks the way it does
+ * within one `matchFileRulesGrouped` call -- this is a thin, no-negation-support convenience, not a
+ * second matching engine.
+ */
+export declare function matchesSingleFileRulePattern(pattern: string, path: string, opts: {
+    cwd: string;
+    home: string;
+}, behavior: "allow" | "denyAsk"): boolean;
+export {};

package/dist/permissions/grammar.d.ts

@@ -0,0 +1,113 @@
+export type Specifier = {
+    kind: "wildcardAll";
+} | {
+    kind: "pattern";
+    source: string;
+} | {
+    kind: "param";
+    field: string;
+    value: string | boolean;
+} | {
+    kind: "webFetchDomain";
+    source: string;
+} | {
+    kind: "invalid";
+    reason: string;
+};
+export interface ParsedRule {
+    toolName: string;
+    specifier?: Specifier;
+    isBareEquivalent: boolean;
+}
+export declare const PARSE_LIMIT = 50000;
+export declare const READ_ONLY_COMMANDS: ReadonlySet<string>;
+export declare const DANGEROUS_ASSIGNMENT_NAMES: ReadonlySet<string>;
+export declare const FILE_RULE_TOOLS: ReadonlySet<string>;
+export declare function leadingWord(s: string): {
+    word: string | undefined;
+    afterWord: string;
+};
+/**
+ * Joins backslash-newline continuations the way bash does before it parses: an ODD run of
+ * backslashes before a newline ends in a continuation (the last backslash and the newline vanish);
+ * an even run is escaped backslashes followed by a real newline. Without this, `echo x >
+ * \<newline>.git/config` read its target as `\<newline>.git/config` -- a name with no `.git`
+ * segment -- while bash wrote `.git/config` (claude joins them before its own redirect scan).
+ */
+export declare function joinLineContinuations(command: string): string;
+export declare function splitCompound(rawCommand: string): string[] | null;
+export declare function stripWrappers(rawCmd: string, direction: "allow" | "denyAsk"): string;
+/** One word of a command: its text after quote removal, as written, and whether any of it was quoted. */
+export interface ShellWord {
+    word: string;
+    raw: string;
+    quoted: boolean;
+}
+/**
+ * bash's quote removal (and, with `split`, its word splitting at unquoted blanks) over one command's
+ * text: single quotes, double quotes (a backslash there drops -- stricter than bash, which keeps it
+ * before an ordinary character, and never naming a DIFFERENT protected file), backslash escapes,
+ * ANSI-C `$'…'` (decoded) and locale `$"…"` (as double quotes). Expansions are left as written. An
+ * unterminated quote runs to the end.
+ */
+export declare function shellWords(s: string, split?: boolean): ShellWord[];
+/** `word` after bash's quote removal, as ONE word (blanks inside it are kept). */
+export declare function dequoteShellWord(word: string): string;
+/** One file-writing redirection: the target word as written (`raw`) and after bash's quote removal. */
+export interface RedirectWrite {
+    raw: string;
+    target: string;
+}
+/**
+ * Every FILE-writing redirection at the top level of one (sub)command -- the operators bash writes a
+ * file through: `>`, `>>`, `>|` (noclobber override), `&>`, `&>>`, `<>` (read-write open), any of them
+ * fd-prefixed (`2>`), and `>&word` / `N>&word` whose word is NOT a descriptor (`>&file` is the old
+ * spelling of `&>file`; `2>&1`, `>&2`, `>&-` stay descriptor copies). `<<`/`<<<` feed input and
+ * `>(`/`<(` are process substitutions -- neither is a file target (the permission layer asks for a
+ * process substitution separately). Bash runs without history expansion here, so a target that
+ * begins with `!` is ALSO read with the `!` removed (zsh's `>!` clobber), which only adds a path.
+ *
+ * An unparseable command yields `[]` here; every security caller asks for such a command on its own
+ * (`shellWriteConstraint`), because a scan it could not complete proves nothing about its writes.
+ */
+export declare function extractRedirectWrites(rawCommand: string): RedirectWrite[];
+/** `extractRedirectWrites`, target paths only (quotes removed). */
+export declare function extractRedirectTargets(command: string): string[];
+export declare function isRecognizedReadOnly(command: string): boolean;
+export declare function escapeRegExpLiteral(s: string): string;
+/** The call's `url` as a parsed `URL`, or `undefined` when it is absent, not a string, or unparseable. NEVER throws. */
+export declare function webFetchUrlOf(input: Record<string, unknown>): URL | undefined;
+/**
+ * The hostname a `WebFetch(domain:...)` rule is compared against: `new URL(url).hostname`, lowercase
+ * (the URL parser already lowercases and punycodes it), minus one trailing dot.
+ *
+ * `undefined` -- which matches NO domain rule, on either direction -- for an absent/unparseable `url`
+ * and for a URL with an EMPTY host (`file:///etc/passwd`, `data:`): `domain:*` compiles to a pattern
+ * that matches the empty string, so without this an allow rule written for "any website" would
+ * pre-approve a URL that names no website at all.
+ *
+ * The trailing dot is stripped on BOTH sides (here and at parse) because `https://example.com./` is
+ * the same host as `https://example.com/` and the URL parser keeps the dot: an exact compare would
+ * let that spelling walk past a deny rule.
+ */
+export declare function webFetchHostnameOf(input: Record<string, unknown>): string | undefined;
+/**
+ * True when `rule` is a `WebFetch(domain:<host>)` rule that names `hostname` EXACTLY -- no `*`
+ * anywhere in it. This is what the evaluator means by "a rule naming that host": a glob
+ * (`domain:*`, `domain:*.corp`) matches a host without ever having named it, so it can allow a fetch
+ * but can never stand in for the user's consent to one specific address.
+ */
+export declare function isExactWebFetchDomainRule(rule: ParsedRule, hostname: string): boolean;
+export declare function parseRule(raw: string): ParsedRule;
+export declare function matchesRule(rule: ParsedRule, call: {
+    toolName: string;
+    input: Record<string, unknown>;
+}, opts: {
+    direction: "allow" | "denyAsk";
+}): boolean;
+export interface PermissionRuleValidation {
+    valid: boolean;
+    error?: string;
+    suggestion?: string;
+}
+export declare function validatePermissionRuleString(raw: string, direction: "allow" | "deny" | "ask"): PermissionRuleValidation;

package/dist/permissions/paths.d.ts

@@ -0,0 +1,32 @@
+import type { PermissionBehavior } from "@yanlinglabs/winter-agent-sdk";
+export interface MatchFileRuleOptions {
+    path: string;
+    cwd: string;
+    sourceDir?: string;
+    home: string;
+    direction: "allow" | "denyAsk";
+}
+export declare function resolveTargetPath(path: string, cwd: string): string;
+export declare const MAX_DOUBLE_STARS = 8;
+export declare const MAX_STARS_PER_SEGMENT = 8;
+export declare function exceedsStarsPerSegmentCap(pattern: string): boolean;
+export declare function exceedsDoubleStarCap(pattern: string): boolean;
+export declare function matchFileRule(pattern: string, opts: MatchFileRuleOptions): boolean;
+export interface SymlinkBothEndsResult {
+    allowRequiresBoth: boolean;
+    denyIfEither: boolean;
+}
+export declare function resolveRealTarget(path: string): string;
+export declare function resolveSymlinkTargetChain(path: string): string | undefined;
+export declare function checkSymlinkBothEnds(path: string, matcher: (candidatePath: string) => boolean): SymlinkBothEndsResult;
+export declare function matchFileRuleAtBothEnds(pattern: string, opts: MatchFileRuleOptions): boolean;
+export interface FileRuleEntry {
+    toolName: string;
+    pattern: string;
+    behavior: PermissionBehavior;
+    sourceDir?: string;
+}
+export declare function readDenyBlocksEdit(rules: FileRuleEntry[], path: string, ctx: {
+    cwd: string;
+    home: string;
+}): boolean;

package/dist/permissions/policy-state.d.ts

@@ -0,0 +1,64 @@
+import type { PermissionMode, PermissionUpdate, RuleSource } from "@yanlinglabs/winter-agent-sdk";
+import { type SourcedRuleSet } from "./ruleset.js";
+export type { AutoModeConfig } from "./auto/config.js";
+import type { AutoModeConfig } from "./auto/config.js";
+export interface PolicyState {
+    mode: PermissionMode;
+    version: number;
+    rules: SourcedRuleSet;
+    autoConfig?: AutoModeConfig;
+}
+export declare class WinterPermissionError extends Error {
+    constructor(message: string);
+}
+export declare const PERMISSION_MODES: ReadonlySet<PermissionMode>;
+export declare function isPermissionMode(value: string): value is PermissionMode;
+/**
+ * SDK 0.0.16 (P16-7): claude's fork agent (`Ex`) carries `permissionMode: "bubble"` -- NOT a member
+ * of `PERMISSION_MODES` and never widened into one (`PermissionMode` is a closed 6-value union read
+ * exhaustively elsewhere -- `classifyPermissionMode` in particular). "bubble" is an explicit ALIAS
+ * for "no override": the child keeps whatever mode the parent session is CURRENTLY running (never a
+ * fixed mode of its own), and its own approval prompts surface through the parent's approval path.
+ *
+ * The second half needs no new plumbing here -- every child's `PreToolUse`/hook control_requests
+ * already forward up to the real host and are answered there (`child-engine.ts`'s
+ * `registerChildResponseHandler`/`forwardedHostRequestIds`, Phase 4 Task 8 rider 19); "bubble" only
+ * NAMES, deliberately, the mode value that already produces "inherit the parent's live mode" instead
+ * of leaving it an accident of an unrecognized permissionMode string falling through
+ * `isPermissionMode`'s own false case. `engine.ts`'s `buildChildInheritance` treats this constant
+ * (never the general "value is not a known mode" branch) as that alias -- see its own comment.
+ */
+export declare const BUBBLE_PERMISSION_MODE = "bubble";
+export declare function assertKnownPermissionMode(mode: string | undefined): PermissionMode;
+export interface BypassGateConfig {
+    allowDangerouslySkipPermissions: boolean;
+    disableBypassPermissionsMode: boolean;
+}
+export interface SetModeResult {
+    ok: true;
+    effectiveMode: PermissionMode;
+}
+export interface SetModeError {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+export interface ApplyUpdateOk {
+    ok: true;
+}
+export declare class PolicyStateStore {
+    private state;
+    private readonly gate;
+    constructor(initial: {
+        mode: PermissionMode;
+        rules: SourcedRuleSet;
+        autoConfig?: AutoModeConfig;
+    }, gate: BypassGateConfig);
+    getState(): Readonly<PolicyState>;
+    setMode(mode: PermissionMode): SetModeResult | SetModeError;
+    applyUpdate(update: PermissionUpdate, opts: {
+        authority: RuleSource;
+    }): ApplyUpdateOk | SetModeError;
+}

package/dist/permissions/prompt-stage.d.ts

@@ -0,0 +1,3 @@
+import type { RpcBridge } from "../rpc/bridge.js";
+import type { PromptStage } from "./evaluator.js";
+export declare function createBridgePromptStage(bridge: RpcBridge): PromptStage;