stitchkit 0.83.2 → 0.84.0

package/CHANGELOG.md

@@ -15,6 +15,56 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.84.0] — 2026-09-07
+
+### ⚠️ Breaking changes
+
+**Who must act:** anyone using `createAgentCodingTools`. The separator fix
+below reaches BOTH callbacks — the required `authorize({ operation, path })`
+and the optional `authorizePath`. The recursion fix reaches `authorizePath`
+only. Anyone passing a non-canonical `cwd` to `run_command` is affected by the
+separator fix even if they implement neither policy shape.
+
+- **A backslash in a requested path is refused instead of silently becoming a
+  separator.** `contained-files` splits a relative path on `[\/]`, so
+  `credentials\token.txt` reached `openat` as two segments while every
+  authorization callback was handed the string whole and read it as one name.
+  A rule denying `credentials/token.txt` refused that spelling and served — then
+  overwrote — the same file spelled with a backslash. This bypassed the
+  **required** `authorize` callback, not only the `authorizePath` added in
+  0.83.2, and it has been reachable since 0.70.0. Requests carrying `\` now get
+  a typed `FORBIDDEN`; `run_command`'s `cwd` goes through the same segment and
+  separator validation as every file tool.
+  `// before: read_file('a\b.txt') → served past a rule denying 'a/b.txt'` →
+  `// after: read_file('a\b.txt') → FORBIDDEN, use 'a/b.txt'`
+
+- **`authorizePath` denies a directory on every surface it governs.** Direct
+  read, write and edit asked the path policy only about the leaf, so `authorizePath: p => p !== 'credentials'`
+  hid the directory from `glob` and served `credentials/token.txt` to
+  `read_file`, created files under it through `write_file` and rewrote it
+  through `edit_file`; `list_directory` and `glob` given a base path *inside* a
+  denied directory disclosed its contents and disagreed about the refusal shape.
+  Direct access and discovery base paths now ask about `.` and each ancestor,
+  outermost first, short-circuiting on the first refusal — segment-wise, so
+  denying `credentials` does not deny `credentials-backup`.
+  `// before: authorizePath asked once, about the leaf` →
+  `// after: asked about '.', then each ancestor, then the leaf`
+
+  **The policy must now admit every directory on the way to a file**, the way
+  POSIX needs `+x` on each directory in a path. A DENY-list is unaffected:
+  refusing `credentials` now refuses everything under it, which is what the rule
+  always read as. An ALLOW-list must be widened to name the directories it
+  leads through — `p => p.startsWith('src/')` refuses `src` itself and so loses
+  `src/index.ts`; write `p => p === 'src' || p.startsWith('src/')`. The
+  workspace root is not asked about: it is the boundary the tools already own.
+  A path of depth N costs N questions, and a policy keeping an audit no longer
+  sees the leaf once an ancestor refused.
+
+  This recursion is `authorizePath` only. The required `authorize({ operation,
+  path })` is still asked once, about the operation's own path, and a broad
+  `search` or `glob` is still one decision covering every file the walk opens —
+  which is the reason `authorizePath` exists at all. → ADR 0172 (amended).
+
 ## [0.83.2] — 2026-09-07
 
 ### Added

package/dist/agent-runtime/coding-tool-paths.d.ts

@@ -15,6 +15,34 @@ export declare function editableCodingPath(root: string, requested: string, maxP
 export declare function authorizeCodingTool(config: AgentCodingToolConfig, request: AgentCodingToolAuthorization): Promise<void>;
 export declare function isCodingPathAuthorized(config: AgentCodingToolConfig, path: string): Promise<boolean>;
 export declare function authorizeCodingPath(config: AgentCodingToolConfig, path: string): Promise<void>;
+/**
+ * Ask the policy about the target AND every directory above it.
+ *
+ * A denied directory means two different things until this exists. The walk
+ * refuses to descend into one, so denial is recursive during discovery; direct
+ * access asked only about the leaf, so a host writing the obvious rule —
+ * `path !== 'credentials'` — got a listing that hid the directory and a
+ * `read_file` that served the secret inside it, plus a `write_file` that
+ * created directories under it and an `edit_file` that rewrote it.
+ *
+ * Outermost first, so the broadest refusal is the one the caller is told about
+ * and nothing below a denied directory is ever asked about. Segment-wise, not
+ * `startsWith`: a rule denying `credentials` must not also deny
+ * `credentials-backup`.
+ *
+ * The chain asks about the ANCESTORS OF THE PATH, and `.` is one only when the
+ * path itself is `.`. Asking about `.` unconditionally looks symmetrical with
+ * the walk — `search_files` and `list_directory('.')` do ask it — but there `.`
+ * is the base path the caller named, not an ancestor of it. Asked on every
+ * direct access it silently inverts every ALLOW-list: a host exposing one
+ * subtree with `p => p.startsWith('src/')` answers `false` for `.` and loses
+ * `src/index.ts` too, having denied nothing.
+ *
+ * The cost is stated rather than hidden: a path of depth N costs N questions,
+ * and a policy that keeps an audit no longer sees the leaf once an ancestor has
+ * refused.
+ */
+export declare function authorizeCodingPathChain(config: AgentCodingToolConfig, relative: string): Promise<void>;
 /** Serialize framework-owned compare-and-replace transactions for one canonical target. */
 export declare function withCodingPathLock<T>(target: string, work: () => Promise<T>): Promise<T>;
 export declare function textOccurrences(source: string, search: string): number;

package/dist/agent-runtime/coding-tool-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coding-tool-paths.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-paths.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,4BAA4B,EAEjC,KAAK,qBAAqB,EAE3B,MAAM,wBAAwB,CAAC;AAkChC,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAezF;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;;;GAKrB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;;;GAarB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;;;GAQrB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAIf;AAID,2FAA2F;AAC3F,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAeZ;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUtE"}
+{"version":3,"file":"coding-tool-paths.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-paths.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,4BAA4B,EAEjC,KAAK,qBAAqB,EAE3B,MAAM,wBAAwB,CAAC;AAkChC,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAmCzF;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;;;GAKrB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;;;GAarB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM;;;GAQrB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAIlB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,qBAAqB,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAMf;AAID,2FAA2F;AAC3F,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAeZ;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUtE"}

package/dist/agent-runtime/coding-tool-search-patch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coding-tool-search-patch.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-search-patch.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,qBAAqB,EACrB,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAyHhC,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,qBAAqB,GAC5B,SAAS,yBAAyB,EAAE,CAuMtC"}
+{"version":3,"file":"coding-tool-search-patch.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-search-patch.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,qBAAqB,EACrB,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AA0HhC,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,qBAAqB,GAC5B,SAAS,yBAAyB,EAAE,CAuMtC"}

package/dist/agent-runtime/coding-tool-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coding-tool-shell.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-shell.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAG3B,MAAM,wBAAwB,CAAC;AAgKhC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,qBAAqB,GAC5B,yBAAyB,CAkD3B"}
+{"version":3,"file":"coding-tool-shell.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-shell.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAG3B,MAAM,wBAAwB,CAAC;AAoKhC,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,qBAAqB,GAC5B,yBAAyB,CA4D3B"}

package/dist/agent-runtime-coding-tools.js

@@ -243,7 +243,13 @@ function inputPath(root, requested, maxPathBytes) {
 }
 function boundedCodingRelativePath(requested, maxPathBytes) {
   inputPath(path.parse(process.cwd()).root, requested, maxPathBytes);
-  const segments = requested.split(/[\\/]/u);
+  if (requested.includes("\\")) {
+    codingRefusal("FORBIDDEN", "Path separators must be `/`", {
+      details: { path: requested },
+      hint: "Use `/` between segments; a backslash is refused because the workspace walk reads it as a separator."
+    });
+  }
+  const segments = requested.split("/");
   if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
     codingRefusal("FORBIDDEN", "Path segments must name real entries under the root", {
       details: { path: requested },
@@ -271,7 +277,18 @@ async function isCodingPathAuthorized(config, path2) {
 }
 async function authorizeCodingPath(config, path2) {
   if (!await isCodingPathAuthorized(config, path2)) {
-    forbidden("Coding tool path permission denied");
+    codingRefusal("FORBIDDEN", "Coding tool path permission denied", {
+      details: { path: path2 },
+      hint: "The host policy refused this path or a directory above it."
+    });
+  }
+}
+async function authorizeCodingPathChain(config, relative) {
+  if (!config.authorizePath)
+    return;
+  const segments = relative === "." ? ["."] : relative.split("/");
+  for (let depth = 1;depth <= segments.length; depth += 1) {
+    await authorizeCodingPath(config, segments.slice(0, depth).join("/"));
   }
 }
 var codingPathLocks = new Map;
@@ -332,7 +349,7 @@ function createFileCodingTools(config, limits) {
     handler: async ({ input }) => {
       const root = await realpath2(config.root);
       const relative = boundedCodingRelativePath(input.path, limits.maxPathBytes);
-      await authorizeCodingPath(config, relative);
+      await authorizeCodingPathChain(config, relative);
       const handle = await openContainedFile(root, relative).catch((error) => refuseMissingCodingPath(error, relative));
       const maximum = Math.min(input.maxBytes ?? limits.maxReadBytes, limits.maxReadBytes);
       let selected;
@@ -379,7 +396,7 @@ function createFileCodingTools(config, limits) {
     handler: async ({ input }) => {
       const root = await realpath2(config.root);
       const relative = boundedCodingRelativePath(input.path, limits.maxPathBytes);
-      await authorizeCodingPath(config, relative);
+      await authorizeCodingPathChain(config, relative);
       const bytes = Buffer.byteLength(input.content);
       if (bytes > limits.maxWriteBytes) {
         codingPathRefusal("BAD_REQUEST", `The content is ${bytes} bytes, over the ${limits.maxWriteBytes}-byte limit`, relative, {
@@ -514,7 +531,7 @@ function createListingCodingTools(config, limits) {
     handler: async ({ input }) => {
       const root = await realpath3(config.root);
       const relative = input.path === "." ? "." : boundedCodingRelativePath(input.path, limits.maxPathBytes);
-      await authorizeCodingPath(config, relative);
+      await authorizeCodingPathChain(config, relative);
       await authorizeCodingTool(config, { operation: "list", path: relative });
       const listing = await listContainedDirectory(root, relative, limits.maxListEntries, (candidate) => isCodingPathAuthorized(config, candidate)).catch((error) => {
         if (error instanceof Error && error.message.includes("ancestor is not a directory")) {
@@ -548,7 +565,7 @@ function createListingCodingTools(config, limits) {
     transports: ["AGENT"],
     handler: async ({ input }) => {
       const relative = input.path === "." ? "." : boundedCodingRelativePath(input.path, limits.maxPathBytes);
-      await authorizeCodingPath(config, relative);
+      await authorizeCodingPathChain(config, relative);
       await authorizeCodingTool(config, {
         operation: "glob",
         pattern: input.pattern,
@@ -745,7 +762,7 @@ function createSearchAndPatchCodingTools(config, limits) {
     handler: async ({ input }) => {
       const root = await realpath4(config.root);
       const relative = boundedCodingRelativePath(input.path, limits.maxPathBytes);
-      await authorizeCodingPath(config, relative);
+      await authorizeCodingPathChain(config, relative);
       const parent = await openContainedParent(root, relative).catch((error) => refuseMissingCodingPath(error, relative));
       try {
         return await withCodingPathLock(`${root}:${relative}`, async () => {
@@ -989,7 +1006,7 @@ function createShellCodingTool(config, limits) {
       if (!executable)
         throw new Error("Coding tool executable is not declared");
       const root = await realpath5(config.root);
-      const cwd = await existingCodingPath(root, input.cwd, limits.maxPathBytes);
+      const cwd = await existingCodingPath(root, input.cwd === "." ? "." : boundedCodingRelativePath(input.cwd, limits.maxPathBytes), limits.maxPathBytes);
       if (!(await stat(cwd.absolute)).isDirectory()) {
         throw new Error("Coding tool cwd is not a directory");
       }

package/llms-full.txt

@@ -63,11 +63,11 @@ own, recorded as an ADR.
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 28 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 29 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 12 of the 28 minors since 0.56.2, most recently 0.83.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 15 of the 29 minors since 0.56.2, most recently 0.84.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -75,7 +75,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 28 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 29 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -4719,8 +4719,13 @@ approval input fails the run with a private diagnostic rather than starting a fr
 `read_output`. Every call passes a required host authorization callback. An optional async/sync
 `authorizePath({ path })` is the one operation-independent policy for direct file access and
 discovery: direct read/write/edit refuses a denied path, while listing, glob and search omit it.
-Directory decisions happen before descent; file decisions and `search_files.include` happen before
-opening content. File paths are relative, bounded and contained after
+Denial is recursive on every surface — direct access and discovery base paths ask about `.` and each
+ancestor, outermost first, stopping at the first refusal, so denying `credentials` denies everything
+under it. The comparison is segment-wise, so it does not deny `credentials-backup`, and a path of
+depth N costs N+1 questions. Directory decisions happen before descent; file decisions and
+`search_files.include` happen before opening content. Requested paths use `/`: a backslash is
+refused rather than normalised, because the workspace walk reads it as a separator and every
+authorization callback would otherwise be asked about a different decomposition than the one opened. File paths are relative, bounded and contained after
 descriptor-relative resolution: each ancestor is opened without following symlinks and remains
 pinned through authorization and the filesystem effect. Reads revalidate the pinned file identity;
 writes and patches revalidate the pinned parent identity; search and resource discovery descend
@@ -11031,6 +11036,59 @@ makes one thing your job rather than the resolver's:
 The mechanical part is identical either way. Only the *noticing* differs, and an
 exact pin moves it onto you.
 
+## Released migration: 0.84.0
+
+Only if you call `createAgentCodingTools`.
+
+```bash
+rg -n "createAgentCodingTools"
+```
+
+**1. Backslashes are refused.** If anything in your system hands the tools a Windows-style path,
+it now gets `FORBIDDEN`. Convert to `/` at the boundary:
+
+```ts
+// before: read_file({ path: 'src\\index.ts' })   // reached openat as two segments
+// after:  read_file({ path: 'src/index.ts' })
+```
+
+This is the half that matters most: until now a backslash bypassed your **required**
+`authorize({ operation, path })` callback, not just `authorizePath`. A rule denying
+`credentials/token.txt` refused that spelling and served — and overwrote — the same file spelled
+`credentials\token.txt`. If your policy denies specific files, re-read your audit logs for
+backslash spellings.
+
+**2. Denying a directory now denies everything under it — and a policy must admit every directory
+on the way to a file**, the way POSIX needs `+x` on each directory in a path.
+
+If your policy is a DENY-list, it now does what it read as:
+
+```ts
+authorizePath: ({ path }) => path !== 'credentials'
+// before: hid `credentials` from glob, served `credentials/token.txt` to read_file
+// after:  refuses `credentials/token.txt`, `credentials/nested/deep.txt` and writes under it
+```
+
+If you relied on the old behaviour — a directory hidden from discovery but readable directly — you
+were relying on a defect, and the two halves of one callback disagreeing. Name the paths you
+actually want reachable instead.
+
+If your policy is an ALLOW-list, widen it to the directories it leads through, or nothing under
+them is reachable:
+
+```ts
+// before: allowed src/index.ts, because only the leaf was ever asked
+authorizePath: ({ path }) => path.startsWith('src/')
+// after: `src` itself is asked first and refused, so the file is refused too
+authorizePath: ({ path }) => path === 'src' || path.startsWith('src/')
+```
+
+The workspace root is not asked about — it is the boundary the tools already own.
+
+**3. The policy is called more often.** A path of depth N costs N+1 calls (`.`, then each ancestor,
+then the leaf), outermost first, stopping at the first refusal. A policy that logs or meters will
+see a different sequence, and will no longer see the leaf once an ancestor has refused.
+
 ## Released migration: 0.83.0
 
 Two things, both mechanical, and only if you touch an observability sink.
@@ -15274,8 +15332,12 @@ boundary, not an OS sandbox; executable behavior, process
 isolation, credentials and external-effect idempotency remain host responsibilities.
 
 When `authorizePath` denies a path, direct read/write/edit returns `FORBIDDEN`, while
-`list_directory`, `glob` and `search_files` omit it. Directory admission happens before descent and
-file admission before opening; `search_files.include` is also applied before content is read.
+`list_directory`, `glob` and `search_files` omit it. Denial is recursive: direct access and
+discovery base paths are checked against `.` and every ancestor, outermost first and segment-wise,
+so denying `credentials` denies `credentials/token.txt` but not `credentials-backup`. Directory
+admission happens before descent and file admission before opening; `search_files.include` is also
+applied before content is read. Requested paths must use `/` — a backslash is refused, because the
+containment walk reads it as a separator while a callback would read it as one name.
 `run_command` is intentionally outside this guarantee because an executable needs process isolation,
 not path filtering, to constrain its filesystem access. → ADR 0172.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.83.2",
+  "version": "0.84.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",