@crewhaus/tool-executor 0.7.0 → 0.8.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+CrewHaus Factory
+Copyright 2026 Max Meier
+
+This product includes software developed by Max Meier
+(operating as StudioMax — https://studiomax.io) and contributors.
+
+The CrewHaus name and logo are trademarks of Max Meier. See
+https://github.com/crewhaus/factory/blob/main/TRADEMARK.md for the
+use-of-marks policy.

package/README.md

@@ -0,0 +1,11 @@
+# @crewhaus/tool-executor
+
+Execute a single tool: validate → permission-check → invoke → format result
+
+Part of [CrewHaus](https://github.com/crewhaus/factory). Most people install the CLI (`npm install -g crewhaus`) rather than this package.
+
+Which tools a spec can turn on, and how: [tools reference](https://github.com/crewhaus/docs/blob/main/TOOLS-REFERENCE.md).
+
+Requires [Bun](https://bun.sh) `>=1.3.14`; plain Node is not supported.
+
+[Source](https://github.com/crewhaus/factory/tree/main/packages/tool-executor)

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { CrewhausError } from "@crewhaus/errors";
 import type { RegisteredTool, ToolExecuteModel, ToolExecuteResult } from "@crewhaus/tool-catalog";
+import { type PathCanonicalizer } from "./permission-subject";
+export { type PathCanonicalizer, type PermissionSubject, type PermissionSubjectOptions, type ProgramPathReader, type ProgramPathReaderOptions, type ProgramPathReading, lexicalPathValues, operativeValuesFor, operativeValuesOf, preparePermissionSubject, readOperativeField, } from "./permission-subject";
 /**
  * Section 14 — `content` widened from `string` to `string | ToolResultContent`
  * so tools like `ReadImage` can return Anthropic image content blocks. Error
@@ -13,8 +15,18 @@ export type ToolResult = {
 };
 export type ExecutionContext = {
     readonly toolUseId: string;
-    /** When present, the tool call must match at least one pattern. Absent = allow all. */
+    /**
+     * When present, the tool call must match at least one pattern, read as an
+     * allow rule: every operative value of the PARSED input must match its
+     * argument glob. Absent = allow all.
+     */
     readonly allowedPatterns?: ReadonlyArray<string>;
+    /**
+     * How a path-kind operative value is canonicalised for `allowedPatterns`.
+     * Default: {@link lexicalPathValues}, which needs no filesystem. A Node
+     * caller that has a workspace passes one that also follows symlinks.
+     */
+    readonly canonicalizePath?: PathCanonicalizer;
     /** Optional cooperative-cancellation signal forwarded to the tool. */
     readonly signal?: AbortSignal;
     /**

package/dist/index.js

@@ -1,6 +1,8 @@
 import { CrewhausError, isRunFailedError } from "@crewhaus/errors";
 import { compilePattern, matchesPattern } from "@crewhaus/tool-permission-matcher";
 import { validateToolInput } from "@crewhaus/tool-validate";
+import { operativeValuesFor } from "./permission-subject";
+export { lexicalPathValues, operativeValuesFor, operativeValuesOf, preparePermissionSubject, readOperativeField, } from "./permission-subject";
 export class ToolPermissionError extends CrewhausError {
     name = "ToolPermissionError";
     toolName;
@@ -16,8 +18,20 @@ export async function executeTool(tool, rawInput, context) {
         return { toolUseId, content: validation.error.message, isError: true };
     }
     if (allowedPatterns !== undefined) {
+        // Match what the tool will run on — the parsed input, with its operative
+        // values canonicalised — never the raw input, which can carry a decoy key
+        // the schema strips (#145, security-1#0).
         const compiled = allowedPatterns.map(compilePattern);
-        const permitted = compiled.some((p) => matchesPattern(p, tool.name, rawInput));
+        const operativeValues = operativeValuesFor(tool, validation.value, {
+            ...(context.canonicalizePath !== undefined
+                ? { canonicalizePath: context.canonicalizePath }
+                : {}),
+            ...(context.toolConfig !== undefined ? { toolConfig: context.toolConfig } : {}),
+        });
+        const permitted = compiled.some((p) => matchesPattern(p, tool.name, validation.value, {
+            polarity: "allow",
+            ...(operativeValues !== undefined ? { operativeValues } : {}),
+        }));
         if (!permitted) {
             return {
                 toolUseId,

package/dist/permission-subject.d.ts

@@ -0,0 +1,365 @@
+/**
+ * What a permission rule is checked against, for one tool call.
+ *
+ * A rule used to be matched against the raw input the model sent, while the
+ * tool ran on that input AFTER its schema had parsed it — unknown keys
+ * stripped, defaults filled in. The two could disagree, and every
+ * disagreement was a way past a rule: a decoy key the tool never reads, an
+ * extra argument that stopped a deny from matching, a left-out field the tool
+ * then filled with the very value a deny named. And a path was matched as a
+ * string, so `build/../src` passed `build/**` and a symlinked directory led
+ * somewhere no rule had looked.
+ *
+ * So a call is described the way the tool will see it:
+ *
+ * 1. The input is parsed with the tool's own schema. A call that does not
+ *    parse cannot run, and is refused before any rule is read.
+ * 2. When the tool declares `operativeArgs`, the values of those fields are
+ *    read from the PARSED input (a declared `default` stands in for an
+ *    omitted field) and canonicalised by kind:
+ *    - a `path` goes through `canonicalizePath`. The Node runtime passes one
+ *      that resolves the path against the workspace root, collapses `..` and
+ *      follows symlinked directories, so the rule sees the place the tool
+ *      will actually touch (runtime-core's `workspacePathCanonicalizer`).
+ *      Without one — the edge worker has no filesystem to ask — `..` is
+ *      collapsed lexically and a relative path that climbs above its start
+ *      is flagged as outside, which no allow rule matches and every deny
+ *      does.
+ *    - a `url` is parsed (WHATWG) and matched as its `href`.
+ *    - a `command` held as an array (an argv) is joined with spaces; each
+ *      word is kept as another spelling, so a deny or ask rule naming one
+ *      word (`RunCommand(rm)`) still fires on the whole argv. A word that
+ *      names a file through `.`, `..` or a doubled `/` is also read with
+ *      them collapsed (and with the `./` it was written with kept), so
+ *      `scripts//release.sh` is `scripts/release.sh`.
+ *    - the words of a command that name a file are read where the kernel
+ *      finds them (`readProgramPath`; runtime-core's reader walks each name
+ *      from the directory the command runs in, a `..` after a symlink
+ *      climbing out of the link's target): its program when written with a
+ *      `/` (also through wrappers such as `env` or `sudo`), a bare program on
+ *      each entry of a PATH a wrapper or the line sets (`env PATH=dir x`,
+ *      `PATH=dir x`), and each script an interpreter (`sh`, `node`, `bun`,
+ *      `python`, …) is handed — from a file on its input too (`sh < x.sh`).
+ *      One that lands elsewhere than it reads is put in its place for an
+ *      allow: `./scripts/../evil.sh` is `./evil.sh`, which
+ *      `RunCommand(./scripts/**)` does not grant, and a deny or ask reads
+ *      that place too — `link/../run.sh` with `link → secrets/deep` is
+ *      `secrets/run.sh`. Such a word is also read with its `..` folded as
+ *      text first, the way node, `bun run` and a `#!/usr/bin/env node`
+ *      script open it — `node lnk/../x.mjs` with `lnk → safe/sub` runs
+ *      `./x.mjs` — and where the two readings land apart, a deny or ask reads
+ *      both and an allow must name both, unless the word is the script of
+ *      a shell, Python 3, Perl or Ruby, which open it where the kernel walks.
+ *      A program reached through a symlink to it
+ *      (`node_modules/.bin/eslint`) is named by the link; a deny or ask also
+ *      reads where the link leads. A program named by an absolute path
+ *      outside the workspace is read as written unless it has a `..` after
+ *      a name: the system's own links (`/bin → usr/bin`) are not the call's
+ *      to move. One read where a wrapper moved the command (`env -C`), or
+ *      found on a PATH entry, cannot be put in its place in the argv: no
+ *      scoped allow grants it. Every other word of an argv with a `/` (any
+ *      word, where a wrapper moved it) is read the same way, for a deny or
+ *      ask only — another program may run it (`arch x`, `find -exec x`) —
+ *      and a grant is bound to where it lands.
+ *    - a line a shell parses runs each command where the `cd`s before it
+ *      leave it: joined as text the way `cd` does by default, walked when it
+ *      is `cd -P`, and each place a `cd` that may not have run leaves it
+ *      (`cd a; x` may run x in either). A wrapper's directory (`env -C`) is
+ *      walked as the kernel walks it. A line cannot have a word put in its
+ *      place, so an allow must also name each command whose words moved,
+ *      with them put in: `Bash(./scripts/**)` does not grant
+ *      `./scripts/lnk/run.sh` (`lnk → ../evil`), and `Bash(node **)` still
+ *      grants a script reached through a linked package directory. `$PWD`
+ *      is the directory the command runs in; folded as text, it is the
+ *      `cd`s the shell joined, a link's name and all, so after `cd lnk` node
+ *      runs `$PWD/../x.mjs` as `./x.mjs` (where that text cannot be told —
+ *      after a wrapper's or a `cd -P`'s move — one that climbs out of it
+ *      cannot be placed). Spelled any other way (`${PWD%/*}`, `$OLDPWD`),
+ *      the shell's own directory cannot be placed. A word read from a directory
+ *      that cannot be told (`cd "$X"`, `cd -`, a `cd` in a loop), or that a
+ *      variable the line does not set or a `~` starts, is read as written;
+ *      with a `..` after a name it cannot be placed. A pattern the shell
+ *      expands is read as every path it can list; a script that is one with
+ *      a wildcard before its last name cannot be placed. A word that cannot
+ *      be placed — also one with a `..` after a name and no reader (the edge
+ *      worker) — is flagged `outsideWorkspace`.
+ *    - a field declared `within` another is written `<qualifier>/<value>` —
+ *      except a `command`, whose `within` names the directory it runs in:
+ *      the program `./build.sh` names is another program in `src/`. A
+ *      command run anywhere but the workspace root loses its canonical
+ *      value, so no scoped allow covers it (the call asks) except one that
+ *      names every command (`RunCommand(**)`). A deny or ask reads it as
+ *      written, and each word that may name a file also as that file from
+ *      the root, so `alwaysDeny RunCommand(*scripts/release.sh*)` fires on
+ *      `[sh, release.sh]` run in `scripts/`. Only the directory's
+ *      workspace-relative spellings (and the one the call wrote) are joined:
+ *      the workspace's own absolute path is not something the call named,
+ *      so `RunCommand(**prod**)` does not fire because the workspace lives
+ *      in `prod-agent/`. A bare program name (`git`) is not joined — PATH
+ *      finds it, not the directory. A command inside an array of objects
+ *      (`steps.argv`) runs in its element's own directory field when it has
+ *      one, else the top-level one.
+ *      A path declared `within` a directory the call leaves out is read from
+ *      the root, or from its declared `withinDefault` (TempDir's `.tmp`).
+ *      A path declared `within` a directory that is absolute or has a `..`
+ *      segment — the call's directory or the root when it gives none — is
+ *      flagged `outsideWorkspace`: the tool hands it on as written to a
+ *      program running there, and the OS follows a symlink before the `..`
+ *      after it, so `../x.ts` run in `link/` (`link → secrets/deep`) is
+ *      `secrets/x.ts`, not the `x.ts` a collapsed reading names (see
+ *      `leavesItsDirectory`).
+ *      Unless it is a path or a command, the value alone and the qualifier
+ *      alone are kept as other spellings, so a deny or ask rule written
+ *      without the qualifier — `alwaysDeny EvmCall(0xdAC17F…)`,
+ *      `EvmCall(*)`, the way 0.7.0 matched every string in the call — still
+ *      fires. An allow must name the qualified value, so it cannot be
+ *      widened by leaving the qualifier out.
+ *    - a `command` declared `shell` and held as a string is a line a shell
+ *      parses: it is marked `shell`, and the matcher reads each simple
+ *      command in it (an allow must match every one, a deny or ask fires on
+ *      any). A `command` held as an argv is never split — no shell reads it
+ *      — but when the program it names is a shell given `-c`, an `eval` or
+ *      an `env -S` (after wrappers such as `env` or `sudo`), the line that
+ *      runs is added as a value only a deny or ask reads, marked `shell`:
+ *      `alwaysDeny RunCommand(rm **)` fires on `["sh", "-c", "a && rm x"]`.
+ *    - a `command` declared with an `env` field — the variables the call
+ *      sets in the child's environment — can run another program than its
+ *      words say: PATH decides what a bare program name is, and BASH_ENV,
+ *      NODE_OPTIONS, LD_PRELOAD and the like load code of their own. So a
+ *      call that sets any variable loses its canonical value (only an
+ *      allow naming every command covers it), and a deny or ask also reads
+ *      a bare program as it is found on each PATH entry the call sets, and
+ *      every value it sets — each word that may name a file also joined to
+ *      where it resolves. An
+ *      environment too large to read that way (more than
+ *      {@link MAX_ENV_VARS} variables, {@link MAX_ENV_WORDS} words in a
+ *      value, or a value longer than {@link MAX_ENV_VALUE_CHARS} characters)
+ *      is flagged `outsideWorkspace`: which program runs could not be worked
+ *      out, so every deny or ask fires, and only an allow naming every
+ *      command covers it.
+ *    - a field left out whose declared default is `*` stands for every
+ *      value (`standsForAny`), whatever its kind: a deny or ask naming any
+ *      one value there fires on it, and an allow grants it only when it
+ *      covers every value there. A path stands for every path under its
+ *      directory (the workspace root when it has none); a URL, or a
+ *      command, for any at all. When the field is declared `within` another
+ *      that the call leaves out as well, it stands for every
+ *      `<qualifier>/<value>` (`anyQualifier`): a code search naming no owner
+ *      reaches every repository.
+ *    - a field declared `prefix` (KvList's `prefix`) stands for every value
+ *      that starts with it, whether the call gives it or leaves it out (the
+ *      empty prefix): `<qualifier>/<prefix>` followed by any run, since a
+ *      key may hold `/`, and the prefix alone for a deny written without
+ *      the qualifier (read one segment on, so a deny naming another
+ *      namespace's key does not fire on every listing).
+ *    - an `id` or `recipient` declared with a `service` field (codehost's
+ *      `baseUrl`, a Chat tool's `apiBaseUrl`) is matched with the origin of
+ *      the API the call goes to in front (`https://ghe.example.com/acme/app`):
+ *      the one it names, else the one the tool's `serviceDefaults` says it
+ *      goes to (read from `toolConfig`). An allow must name the origin,
+ *      unless the API is the one the tool is set up for (its `home`): a call
+ *      to it, named or not, is also matched without one. A deny or ask also
+ *      reads the value without the origin, after the origin's other
+ *      spellings (no root dot, no port, the other of http and https) and
+ *      after its host alone (`ghe.example.com/acme/app`), and the URL itself
+ *      as a URL. A URL with no http or https origin, or with a user name or
+ *      password, cannot be placed: the value is flagged `outsideWorkspace`
+ *      (see {@link servedValue}). A tool with no `serviceDefaults` reads a
+ *      call that names no API without an origin.
+ *    - a `url` declared as its own `service` (RateLimitStatus's `baseUrl`)
+ *      is the API the call goes to, matched as a URL: the one it names, else
+ *      the one the tool's `serviceDefaults` say it goes to, read as the tool
+ *      joins its request paths to it. A deny or ask also reads it after the
+ *      origin's other spellings and its host alone (see {@link apiRootValue}).
+ *    - an `id` or `recipient` declared with an `overlay` field (a deploy
+ *      tenant), on a call that names it, is matched with its value in front
+ *      (`acme/billing/staging`): the call acts on that owner's own copy. A
+ *      deny or ask also reads the value without it, and its value alone
+ *      (see {@link overlaidValue}).
+ *    - a `path` declared `beneath` (a directory the tool walks: RemovePath,
+ *      Grep, a git pathspec) also carries its spellings as `beneath`
+ *      prefixes, so a deny or ask naming anything under it fires —
+ *      unless the canonicaliser marked it `notDirectory`. A walk that
+ *      skips hidden names reads them too when the call sets the switch its
+ *      `hiddenWhen` names (Tree's `includeHidden`), and one declared with a
+ *      `beneathWhen` switch (TempDir's `clear`) is read beneath only when
+ *      the call sets it: otherwise the tool acts on the path alone. One declared
+ *      `defaultAtRoot` and left out is the workspace root, not its `within`
+ *      directory: a git command given no path acts on the whole repository.
+ *      Each relative prefix is also read with a leading `./`, as a direct
+ *      path is, so `alwaysDeny Tree(./secrets/**)` fires on `Tree .`.
+ *    - a `path` declaring `opens` (the fixed files a tool opens inside the
+ *      directory it names: ApprovalStatus's ledger) also carries each of
+ *      them, joined to the directory and canonicalised, as a value only a
+ *      deny or ask reads.
+ *    - a `path` declared `glob` (the Glob tool's pattern) is marked
+ *      `globPattern`: the matcher reads it as every path it can list.
+ *    - a `relocates` field left out stands in with its default, which a
+ *      deny or ask reads; when the call carries another operative value an
+ *      allow skips it (`restrictOnly`), because the grant is about the
+ *      record the call names, not the store it lives in. One declared
+ *      `beneath` too (a store the tool reads whole) carries its prefixes.
+ *    - an `id` declared `secretRef` is a secret reference, trimmed as the
+ *      tool trims it; a `file:` or `envfile:` one is matched with the file
+ *      it names canonicalised in it, and the file is also a value only a
+ *      deny or ask reads; a bare NAME and an `env:NAME` are also read, by a
+ *      deny or ask only, as the env files they are looked up in or loaded
+ *      from (see {@link secretRefValues}).
+ *    - a field declared `source` (where the tool takes a value from) is read
+ *      by a deny or ask only, and so is one declared `ignoredWhen` another
+ *      field the call names (ChatPost's `channel` beside `webhookUrlEnv`):
+ *      the tool does not use it then.
+ *    - an `id`, `recipient` or `text` value that is `0x` hex (an address, a
+ *      hash — `0x` or `0X`, both of which a node accepts) is marked
+ *      `caseInsensitive`: its letter case is at most an EIP-55 checksum, so
+ *      a deny or ask rule must not be dodged by it.
+ *    A tool that declares `[]` has no field that decides where it acts, and
+ *    is matched on its string values like a tool that declares nothing.
+ *
+ * Nothing here touches the filesystem or imports a `node:` builtin: this
+ * package is part of the worker runtime's import graph.
+ */
+import type { OperativeArg, RegisteredTool } from "@crewhaus/tool-catalog";
+import { type OperativeValue } from "@crewhaus/tool-permission-matcher";
+/** Turns one path-kind operative value into the value(s) a rule is matched against. */
+export type PathCanonicalizer = (raw: string) => ReadonlyArray<OperativeValue>;
+/**
+ * Where a word of a command that names a file lands — a program run by its
+ * path, or a script handed to an interpreter — read the way the kernel reads
+ * it from the directory the command runs in (`runsIn` as the call wrote it;
+ * `undefined` for the workspace root): each directory on the way followed,
+ * and each `..` applied AFTER the link before it, so `link/../run.sh` with
+ * `link → secrets/deep` is `secrets/run.sh`. `undefined` when that cannot be
+ * worked out (a loop of links, a directory that cannot be searched, a path
+ * longer than any path can be): no tool can run the word either.
+ */
+export type ProgramPathReader = (word: string, runsIn: string | undefined, opts?: ProgramPathReaderOptions) => ProgramPathReading | undefined;
+/** How a {@link ProgramPathReader} is asked about one word. */
+export type ProgramPathReaderOptions = {
+    /**
+     * The word is an argument of the command, or a candidate on a PATH it
+     * sets, rather than its program or script: a reader that keeps a record
+     * of where words land (for an approval to be bound to) keeps it only
+     * when the word lands elsewhere than it reads, or is a symlink.
+     */
+    readonly argument?: boolean;
+    /**
+     * Where the command moved from `runsIn` before the word is opened,
+     * walked as the kernel walks it: a wrapper's directory (`env -C dir`), a
+     * `cd -P`. The word is read from there; `asWritten` joins all three as
+     * text.
+     */
+    readonly prefix?: string;
+};
+/** One word read by a {@link ProgramPathReader}. */
+export type ProgramPathReading = {
+    /** Absolute: where the word lands, its last name as written (not followed). */
+    readonly at: string;
+    /** `at` relative to the workspace root (`.` for the root, never `./`), when it is inside it. */
+    readonly inWorkspace?: string;
+    /** Absolute: the same word read as text — joined to the directory, `..` collapsed, nothing followed. */
+    readonly asWritten: string;
+    /** Whether {@link asWritten} is inside the workspace. */
+    readonly writtenInWorkspace: boolean;
+    /** Where the last name leads when it is a symlink: the file the kernel runs. */
+    readonly target?: {
+        readonly at: string;
+        readonly inWorkspace?: string;
+    };
+};
+export type PermissionSubject = {
+    readonly ok: true;
+    /** The schema-parsed input: what the tool's `execute` will receive. */
+    readonly input: unknown;
+    /** Canonical values of the tool's `operativeArgs`; absent when the tool declares none. */
+    readonly operativeValues?: ReadonlyArray<OperativeValue>;
+} | {
+    readonly ok: false;
+    /** The schema's validation message, naming what is wrong with the input. */
+    readonly reason: string;
+};
+export type PermissionSubjectOptions = {
+    /**
+     * How a path-kind value is canonicalised. Default: {@link lexicalPathValues}
+     * — `..` collapsed, no symlinks followed, no workspace root known.
+     */
+    readonly canonicalizePath?: PathCanonicalizer;
+    /**
+     * Where a command word that names a file lands. Default: none — the words
+     * are read as text, and one with a `..` after a name is flagged outside,
+     * since a symlink before the `..` could not be seen.
+     */
+    readonly readProgramPath?: ProgramPathReader;
+    /**
+     * The tool's block of the serving candidate's `tool_config`, as the tool
+     * will be handed it (`ToolExecuteContext.toolConfig`); left out, the tool
+     * reads the config it was registered with. The tool's `serviceDefaults`
+     * read it to tell which API a call that names none goes to.
+     */
+    readonly toolConfig?: unknown;
+};
+/**
+ * Parse `rawInput` with the tool's schema and read its operative values. The
+ * input passed here must be exactly the one that will be handed to
+ * `executeTool`, so the rule and the tool see the same call.
+ */
+export declare function preparePermissionSubject(tool: RegisteredTool, rawInput: unknown, opts?: PermissionSubjectOptions): PermissionSubject;
+/**
+ * The canonical operative values of an ALREADY PARSED input, or `undefined`
+ * when the tool declares no `operativeArgs`, or declares `[]` (the matcher
+ * then falls back to the input's string values).
+ */
+export declare function operativeValuesFor(tool: RegisteredTool, parsedInput: unknown, opts?: PermissionSubjectOptions): ReadonlyArray<OperativeValue> | undefined;
+/**
+ * {@link operativeValuesFor} from a declaration alone — for a caller that has
+ * a tool's `operativeArgs` as data (the builtin manifest) but not the tool.
+ * The values are read the same way, except that a call naming no API in a
+ * `service` field is read without an origin: which API it goes to is the
+ * tool's to say. The caller is responsible for passing an input the tool's
+ * schema has parsed, when it can.
+ */
+export declare function operativeValuesOf(operativeArgs: ReadonlyArray<OperativeArg> | undefined, parsedInput: unknown, opts?: PermissionSubjectOptions): ReadonlyArray<OperativeValue> | undefined;
+/**
+ * Every value of one declared field. Dots descend into objects; an array
+ * anywhere on the way is walked element by element — except a `command`
+ * field that IS an array of strings, which is one argv and is joined. A
+ * field declared `within` another comes back as `<qualifier>/<value>` — a
+ * `..` path too, so a row shows the directory it climbs from — and an
+ * absolute path as it is.
+ */
+export declare function readOperativeField(input: unknown, arg: OperativeArg): string[];
+/**
+ * The most variables, words in one value, and characters in one value, of an
+ * environment a command's call sets that a deny or ask reads one by one. A
+ * call past any of them is flagged `outsideWorkspace` instead: which program
+ * it runs could not be worked out, so every deny or ask fires on it.
+ */
+export declare const MAX_ENV_VARS = 64;
+export declare const MAX_ENV_WORDS = 64;
+export declare const MAX_ENV_VALUE_CHARS = 8192;
+/**
+ * `text` without its trailing `/` and `\`: what `text.replace(/[\\/]+$/, "")`
+ * returned, in one pass from the end. That pattern tries every start inside
+ * a run of separators that is not at the end and rescans the rest of the run
+ * from each, so it was quadratic in the run's length, and a directory or a
+ * PATH entry is whatever the call wrote.
+ */
+export declare function withoutTrailingSeparators(text: string): string;
+/**
+ * A command word with its `.` and `..` folded as text, as `path.resolve`
+ * folds them before anything is opened — the way node and `bun run` read
+ * the script they are handed, and a `#!/usr/bin/env node` script the path it
+ * was run by. A `..` after a name takes the name off; one at the start of a
+ * relative word stays, climbing from the directory the command runs in; one
+ * at the root of an absolute word stays at the root. A relative result
+ * without a `/` keeps a `./`, so it still names a file in that directory,
+ * not a program to look up.
+ */
+export declare function foldedAsText(word: string): string;
+/**
+ * The filesystem-free reading of a path: `..` and `.` collapsed, nothing
+ * followed. A relative path that climbs above its start is flagged as
+ * outside. Used where there is no workspace to ask (the edge worker); the
+ * Node runtime passes a canonicaliser that also follows symlinks.
+ */
+export declare function lexicalPathValues(raw: string): OperativeValue[];