@archmax-ai/harness 0.3.2 → 0.4.0

package/skills/archmax-harness/references/backend-integration.md

@@ -81,6 +81,7 @@ From `@archmax-ai/harness` (`src/index.ts`):
 | `SessionStoreRequiredError`, `SessionStoreCapabilityError` | class | Assembly / capability errors for run storage |
 | `workflowStateSchema`, `workflowPaths`, `sessionPaths`, `runArtifactPaths` | schema/fn | State schema + path helpers |
 | `runTests`, `RunTestsOptions`, `CaseResult` | fn/type | Run a workflow's cases — [against your own agent](#cases-against-your-agent) |
+| `toolsFromMap`, `AgentToolDescriptor`, `ToolContext`, `ToolPaths`, `PathAccess`, `ToolPathsError` | fn/type/class | Host tools: a `name → descriptor` map, each descriptor's declared `paths` and a handler handed the turn's workspace — [host tools](#host-tools) |
 | `SIGNATURE_TYPES`, `normalizeSignature`, `signatureForTrigger`, `signatureJsonSchema`, `signatureValueIssues` | const/fn | A trigger's typed signature as JSON Schema and its conformance rule — [exposing a workflow](#exposing-a-workflow-to-outside-callers); also on `@archmax-ai/harness/spec` |
 
 ## createAgent options
@@ -98,6 +99,10 @@ All optional (`CreateAgentParams`, `src/assembly/index.ts`):
 | `mounts` | `Record<string, MountSpec>` | Authored mounts as a `CompositeBackend` route table: key → backend, or `{ backend, readOnly, governed, searchable }`. Trailing slash = directory mount; no slash = exact-path file mount (`"/AGENTS.md"`). Read-only unless declared otherwise. `governed: true` hands the spec's `mounts` block the decision of **which states** may reach it (closed by default, like a skill bundle) and whether each may write there; a mount not so declared is visible in every state exactly as today, so a table that marks nothing behaves unchanged. `readOnly` is a **ceiling** the spec cannot lift: a grant may narrow a writable mount to reads in a state, never open a read-only one. A key may be several segments deep (`"/catalogs/eu/"`); its **first** segment is what is reserved, so `/workflows/x/` fails as `/workflows/` does. Omitted on the default backend: `defaultMounts(rootDir)` (the conventional table — `/skills/`, `/.platform/`, `/AGENTS.md`, none governed — extend with `{ ...defaultMounts(root), "/templates/": … }`). Omitted with a custom `backend`: nothing authored is served; expose subtrees with `mountSubtree(backend, "skills")`. A key colliding with a run area — or naming the authoring-plane prefix (`/workflows/`) — throws `MountCollisionError`. `searchable: false` declares a mount the runtime never searches on its own initiative: a root-wide `grep`/`glob` fans out over the other mounts only, while a search the agent addresses at the mount (or a path inside it) still reaches its backend and returns the backend's own answer — matches or `{ error }` — verbatim. Use it for a backend that must refuse searches (a remote folder served live). Listing and reading are unchanged, the prompt marks it "browse only", names arrive as `MountPrefixes.unsearchable`, and it is ignored on a file mount. |
 | `sessionStore` | `SessionStore` | Physical storage for run state (checkpoints, artifacts, the per-session `scratchpad/`). Zero-config default: `createFilesystemSessionStore({ dir: "<rootDir>/sessions" })`. Required with a custom `backend` (else `SessionStoreRequiredError`). Build with `createBackendSessionStore({ backend, prefix? })` for S3-style storage or `createMemorySessionStore()` for ephemeral runs. |
 | `systemPrompt` | `string` | Appended after workspace `AGENTS.md`. |
+| `tools` | `StructuredTool[]` | Host tools, granted per state by `tools.allow`. Build them with `toolsFromMap` — see [host tools](#host-tools). A name starting `archmax_`, or naming a runtime file operation (`copy_file`, `move_file`, `remove_file`), throws `ReservedToolNameError`. |
+| `essentialTools` | `string[]` | Host tools treated as always on: disclosed and permitted in every state; a state's own entry still narrows one. |
+| `images` | `boolean \| ImageReadOptions` | Show a model with vision the images it reads: the model's `read_file` of a PNG/JPEG/GIF/WebP answers with one line and the image is added to each later request as a `user` message after that batch of tool results, read per request — no bytes in history, checkpoints, events or scripts. `{ maxBytes?, keep? }` (default 10 MB, every image). Off by default; every other binary stays refused. |
+| `toolPaths` | `Record<string, ToolPaths>` | Each host tool's path arguments and how a call uses each (`read`, `list`, `search`, `write`, `remove`, `execute`): `{ get_markdown: { path: "read" } }`. Every path rule then governs them like the built-ins'. Wins over a descriptor's `paths`; declaring a built-in's paths throws `ToolPathsError`. |
 | `checkpointer` | `BaseCheckpointSaver` | Custom-adapter escape hatch; takes precedence over the session store for checkpoint persistence. Defaults to a durable `BackendCheckpointSaver` writing through the session store. Use `MemorySaver` for ephemeral runs. |
 | `middleware` | `AgentMiddleware[]` | Extra middleware appended after workflow instrumentation. |
 | `onEvent` | `WorkflowEventHandler` | Subscribe to all lifecycle diagnostics; suppresses console output when set. |
@@ -429,7 +434,8 @@ opening, a human park, run-start seeding.
 rides its own event so that rule needs no exception, and it is safe there because
 a title is bounded to one short line by its write check. Indexing a run's title on
 your own record is a handler for this event and nothing else — no checkpoint read,
-which matters when you install your own checkpointer.
+which matters when you install your own checkpointer. A sub-workflow's child is not
+asked to name itself, so it emits none unless its caller passed a `title` down.
 
 ### Reading tokens and cost
 
@@ -595,6 +601,47 @@ A custom `backend` **requires** an explicit `sessionStore` — assembly throws
 Persisting the session zone off-box (an S3-backed session store) is how you share run
 state across a worker fleet and an API.
 
+The file operations (`copy_file`, `move_file`, `remove_file`) want more than
+text. A write to a binary-typed path (an image, a PDF) carries **base64**, which
+the backend's `write` must decode — Deep Agents' convention. Bytes the text
+channel cannot carry (a `.docx`, a `.zip`, Latin-1 text) travel through
+`uploadFiles`, and a move or removal needs `delete`. Every copy is read back
+(`downloadFiles`, else `readRaw`); a store that kept something else is refused,
+never reported as copied. Implement all three methods and the base64 decode on a
+custom backend — mounts and session store alike. A read-only mount refuses an
+upload and a delete itself.
+
+### Host tools
+
+A host tool built with `toolsFromMap` reaches the workspace the way the
+built-in file tools do — no second routing table:
+
+```ts
+const tools = toolsFromMap({
+  get_markdown: {
+    description: "Read a document as Markdown.",
+    inputSchema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+    paths: { path: "read" },              // governed like read_file's file_path
+    handler: async (input, { workspace }) => {
+      const raw = await workspace.readRaw(String(input.path));
+      return raw.error ? `Error: ${raw.error}` : toMarkdown(raw.data!);
+    },
+  },
+});
+const agent = await createAgent({ tools, essentialTools: ["get_markdown"] });
+```
+
+- `paths` declares the arguments that name workspace paths and how the call
+  uses each. Every path rule binds them: the read-only zone, the runtime's own
+  areas, the skills and mounts the state was given (`mount.not-allowed`,
+  `skill.not-allowed`), a mount's `access: read` (`mount.read-only` for a
+  `write` or `remove`), inherited denials and `paths:` guards. A refused call
+  never runs the handler. No declaration, no path rules.
+- `context.workspace` is the turn's workspace, bound to the session — the
+  instance `read_file` uses — with `downloadFiles`/`uploadFiles` and `delete`
+  besides the text methods. The plain agent hands the same context. Outside a
+  turn, reading it throws.
+
 ## Cases against your agent
 
 `runTests` runs a workflow's cases — declarative YAML documents

package/skills/archmax-harness/references/hook-and-test-scripts.md

@@ -163,7 +163,7 @@ export default async function hook({ state, phase, trigger, variables, messages,
 | `variables` | The run's variables as a plain `name → value` map, including the built-in `trigger`. Structured values are present whole (`variables.order.items[0].sku`). **Read-only**: assigning changes nothing, and the variable tools are absent from `tools.*` — a hook that could write variables would be editing the governance inputs of the state it judges. |
 | `messages` | The recent transcript (last 24 messages), newest last, as `{ role, text, toolCalls? }`. `role` is `user`, `assistant`, `tool` (with `tool: <name>`), `system`, or **`runtime`** — a note the runtime wrote (an arrival, a decision, an error route, a completion check; `note` names the kind). A hook that reacts to narration matches `role === "runtime"`, never a `[bracket]` prefix in a user message. |
 | `from`, `to`, `reason` | Present on `after` hooks: the transition the agent is attempting (`reason` is the agent's `archmax_advance` reason). |
-| `tools` | The privileged tool-call bridge (async), camelCased: `await tools.readFile({ file_path: "skills/order-data/assets/orders.json" })` → file text. See [Governance](#governance-of-tools-calls). |
+| `tools` | The privileged tool-call bridge (async), camelCased: `await tools.readFile({ file_path: "skills/order-data/assets/orders.json" })` → file text, or the binary notice for a binary file (see below). See [Governance](#governance-of-tools-calls). |
 
 **The verdict** — the three helpers are globals:
 
@@ -231,6 +231,32 @@ try {
 }
 ```
 
+A **binary file** is not a refusal and does not throw: reads are text only, so
+`tools.readFile` on an image, audio, video, PDF or PowerPoint file, or on any
+file whose content holds a NUL byte (an archive, an Office document), resolves to
+the notice `Error: '<path>' is a binary file (<type>, <size>) and was not read;
+read_file returns text files only.` instead of content — an image too, even when
+the host turned on `images`, which shows images to the model only. A missing file reads as
+an `Error: …` string the same way. A script that parses what it read checks
+first:
+
+```js
+const text = await tools.readFile({ file_path: "scratchpad/upload.json" });
+const upload = text.startsWith("Error:") ? null : JSON.parse(text);
+```
+
+To **duplicate, move or delete** a file — a template, an image, a `.docx` —
+call `tools.copyFile({ source, destination, overwrite? })`,
+`tools.moveFile({ source, destination, overwrite? })` or
+`tools.removeFile({ file_path })` instead of reading and writing it back. The
+bytes move, binary files included, with no `readFile` line limit, and each
+call resolves to one line (`Copied '<source>' to '<destination>' (<size>).`,
+`Moved …`, `Removed '<path>'.`). They are governed by their declared paths like
+any other call, so a governance refusal (a destination in a read-only mount, a
+disabled skill's file) throws. A failure the operation itself meets (a missing
+source, a directory, an existing destination without `overwrite: true`)
+resolves to an `Error: …` string instead.
+
 **Authoring rule for `archmax_run` scripts:** if sandboxed code calls `tools.X`,
 the state's `allow` list must cover `tool: X` (with any argument constraints the
 script's call satisfies), or the call is blocked. Grant it per state with

package/skills/archmax-harness/references/workflow-schema.md

@@ -535,9 +535,15 @@ states:
   wiring the SDK already reads, and a loose declaration that swallowed one would
   start the run somewhere you did not say.
 - `requires:` / `returns:` are the run's **signature**, and both are enforced. A
-  firing that does not supply every `requires` name does not start; a run that
-  reaches a terminal state without every `returns` name set is rejected (a run
-  that *parks* is not checked — it has not finished). Each entry is a bare
+  firing that does not supply every `requires` name does not start. `returns`
+  is checked once as the run finishes, and **nothing is handed back**: a
+  sub-workflow child with a name unset **completes**, and its caller gets the
+  returns it set plus `note: "Not all return variables were set by the
+  sub-workflow: '<name>' was not set."`; a top-level run with a name unset is
+  **rejected**; a typed one mistyped rejects either way. A run that *parks* is
+  not checked — it has not finished. `note` is reserved: a `returns` list may
+  not declare it. Want the model to try again? Check the returns in a terminal
+  `after` hook, which can `correct`. Each entry is a bare
   run-variable name (**untyped**: any value, `null` included) or a strict object
   `{ name, type?, description? }` naming one; the spellings mix in one list and
   names are distinct across both. What the agent must *do* to produce a
@@ -630,8 +636,8 @@ silently granting nothing. A host tool may never claim the prefix. Deep Agents'
 (`read_file`, `task`, …) keep their own names.
 
 - A state with **no `tools` block** gets the **always-on tools only**
-  (`ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `write_todos`,
-  `archmax_eval`, `archmax_run`, `task`, plus the always-allowed `archmax_advance` and `allow_always`
+  (`ls`, `read_file`, `write_file`, `edit_file`, `copy_file`, `move_file`, `remove_file`, `glob`,
+  `grep`, `write_todos`, `archmax_eval`, `archmax_run`, plus the always-allowed `archmax_advance` and `allow_always`
   grants — minus
   whatever a `forbid` list denies there, and read-only-zone protection).
   Governance is closed by default; there is no way to declare a fully open state.
@@ -710,8 +716,8 @@ platform-provided tool resolves through when its collection has several) and
 runtime matches governance by `tool` name alone and never reads `source`.
 
 **The model is closed by default, and a denial beats every grant.** Every state always has the
-**always-on tools** (`ls`, `read_file`, `write_file`, `edit_file`, `glob`,
-`grep`, `write_todos`, `archmax_eval`, `archmax_run`). One built-in is **never
+**always-on tools** (`ls`, `read_file`, `write_file`, `edit_file`, `copy_file`, `move_file`,
+`remove_file`, `glob`, `grep`, `write_todos`, `archmax_eval`, `archmax_run`). One built-in is **never
 disclosed** and grantable by nothing: `task`, the runtime's own dispatch for
 grading rubrics — a rubric grades the agent rather than serving it, so naming
 `task` in an allow entry is a `validate` error and the kernel refuses the call.
@@ -722,7 +728,20 @@ default because the `tools.*` calls its code makes are decided against the activ
 state by the same kernel: it adds computation over what the state permits, not
 access. `archmax_run` — executing an authored script **file** — is always on on
 the same terms (the script is a file the state could already read); declare it
-per state to **narrow** which files may run there. Any other tool
+per state to **narrow** which files may run there. The file operations —
+`copy_file({ source, destination, overwrite? })`, `move_file` (same arguments)
+and `remove_file({ file_path })` — are always on on the same terms: every tool
+**declares its path arguments** with how the call uses each (`read`, `list`,
+`search`, `write`, `remove`, `execute`), and every path rule reads that
+declaration. `copy_file` reads `source` and writes `destination`; `move_file`
+**removes** `source`, so a move out of a read-only mount is refused before
+anything is written; a removal is refused wherever a write is. A call naming
+several paths is refused when any one is, naming the argument. `paths:` in an
+entry guards every declared path argument: a grant needs all of them to match
+(`{ tool: copy_file, paths: [skills/**, reports/**] }`), a denial needs one
+(`{ tool: "*", paths: [secrets/**] }` blocks a copy in or out). A host tool that
+declares its paths (`toolPaths`, or a descriptor's `paths`) is governed the same
+way. Any other tool
 must be declared in the state's `tools.allow` or workflow-level
 `tools.allow_always`. A `tools.allow` entry naming an always-on tool **narrows**
 it for that state.
@@ -984,7 +1003,7 @@ the host at assembly (`variables`, every seed locked), the agent mid-run
 
 | | `trigger` | `title` |
 |---|---|---|
-| Set by | the runtime, at every arrival | the **agent**, prompted by the platform prompt |
+| Set by | the runtime, at every arrival | the **agent**, prompted by the platform prompt (a sub-workflow child is not) |
 | Locked | always | **never**, by any route |
 | Guaranteed set | yes | no — absent until written |
 | In a trigger's `requires:` | accepted | accepted (seeded unlocked) |
@@ -993,7 +1012,10 @@ the host at assembly (`variables`, every seed locked), the agent mid-run
 `trigger` holds the current turn's trigger id. `title` holds a short one-line label
 naming the task the run is doing; the platform system prompt asks the agent to set
 one as its first activity and update it when the task changes significantly, so a
-host can name a run instead of showing a session id. A write must be a non-empty
+host can name a run instead of showing a session id. A sub-workflow's child is not
+asked — its title names a session nothing lists and is never returned — so its
+prompt leaves the step out; do not write "set the title" into a child's state
+`instructions` to bring it back. A write must be a non-empty
 single-line string of at most 200 characters (stored trimmed) and must not pass
 `lock: true` — both are refused, atomically, like every other `set_variables`
 rejection. A host may seed a `title`; it lands **unlocked** (the one exception to
@@ -1286,11 +1308,21 @@ enrich:
   no target may call none; `tools.forbid_always` blocks a delegation tool like any
   other.
 - **A failure is a tool error** the calling agent can handle; the state's
-  `on_error` catches the turn if it cannot. Depth, cycle, missing-input
+  `on_error` catches the turn if it cannot. Each failed call is recorded on
+  its own, with its arguments, and stays the calling state's failure until a
+  **later** successful call of the same workflow from the same state recovers
+  it. One success recovers **one** failed call: the one whose arguments it
+  repeats (compared after `${{…}}` resolves, key order ignored), else the
+  oldest — so two parallel calls that failed need two successes. A sibling
+  call in the same batch, another workflow's success, or a rejection with
+  another cause (a terminal kernel block, exhausted parks) recovers nothing,
+  and the route names every outstanding failure with its arguments. An
+  advance, a park or a reset clears them, as it clears any pending rejection. Depth, cycle, missing-input
   (`missing-param`), mistyped-input (`invalid-param`), unresolvable-reference
   (`unresolved-param`) and **disabled-target** refusals are blocked calls —
-  nothing ran, so correct the call and retry. A child whose returns are unset
-  (`missing-return`) or mistyped (`invalid-return`) is a failure: it ran.
+  nothing ran, so correct the call and retry. A child whose returns are
+  mistyped (`invalid-return`) is a failure: it ran. One that left returns unset
+  is not: the call answers with what it set and a `note`.
 - **A whole-argument reference keeps its type.** `{ quantity: "${{count}}" }`
   seeds the child with the number `count` holds, so it satisfies an `integer`
   parameter; `{ note: "order ${{order_id}}" }` is substituted as text.
@@ -1327,9 +1359,11 @@ enrich:
   reads `manual` either way, so the machine cannot branch on having been called.
 
   A dispatch missing a `requires` name is **refused before the child is
-  composed**; a child that completes without every `returns` name set is
-  **rejected** rather than handing back half a contract (a child that *parks* is
-  not checked — it has not finished). A typed entry is held to its type at both
+  composed**; a child that completes without every `returns` name set
+  **completes anyway**, and the call answers with the returns it set plus a
+  `note` naming the rest — no second attempt is spent, and the caller decides
+  (a child that *parks* is not checked — it has not finished; a child that
+  raises fails the call `raised`). A typed entry is held to its type at both
   ends: a mistyped argument is refused `invalid-param` before the child runs, and
   a mistyped return fails the call `invalid-return`. What the child must *do* to
   produce a variable belongs in the state `instructions` that set it. The names,
@@ -1344,13 +1378,24 @@ enrich:
   agent records what it needs with `archmax_set_variables`, or a script writes it,
   and the calling state's `requires:` is what makes that mandatory.
 - **Mocks are held to the same contract.** An `archmax_workflow_<slug>` mock for a
-  signed target supplies `returns:`, and one that omits a declared name
-  (`missing-return`) or supplies a mistyped typed one (`invalid-return`) fails
-  the mocked dispatch — a mock stands in for the sub-run, never for its agreement.
+  signed target supplies `returns:`. One that supplies a mistyped typed one
+  (`invalid-return`) fails the mocked dispatch, and one that omits a declared
+  name answers like a real child that left it unset: what it supplied, plus a
+  `note` — a mock stands in for the sub-run, never for its agreement.
 - **No prose crosses the boundary.** A sub-run gets no instruction from its
-  caller — it works from its own state `instructions` plus the arguments it was
-  seeded with as locked variables, both of which reach the model through the
-  system prompt. Nothing to author, nothing to keep in sync.
+  caller — it works from its own state `instructions` (system prompt) plus the
+  arguments it was seeded with as locked variables, whose values its opening
+  message lists: strings JSON-quoted, numbers and booleans as written. A list,
+  an object, `null`, a value rendering past 200 characters, or one past the
+  message's 1,000-character total is only named, with `archmax_get_variables`
+  as the way to read it. Nothing to author, nothing to keep in sync, and nothing
+  in the child's state `instructions` should say "read your inputs first".
+- **A child goes straight to its work.** Its prompt leaves out the platform
+  prompt's "Name the run first" step (a child's `title` is never returned), so a
+  one-state child with short scalar inputs spends its first model call on the
+  state's work. A workspace overriding the platform prompt
+  (`.platform/system/GRAPH_STATE.md`) keeps that by wrapping what children skip
+  in `<!-- top-level-only -->` … `<!-- /top-level-only -->` lines.
 - **Same agent, isolated context, shared session.** Same model, backend, host
   tools; its **own** grading rubrics, from its own spec; a fresh transcript; the child's *own* per-state
   `tools.allow`. It shares the run's session, so it writes `scratchpad/…` and

package/skills/archmax-harness/references/workflow-yaml.md

@@ -48,7 +48,8 @@ states:
         requires:                #   variables a firing must supply (a caller's required params):
           - order_id             #     a bare name is untyped (any value, null included)
           - { name: due, type: date, description: The day it is due. }  # typed: held at the boundary
-        returns: [result_file]   #   variables the run guarantees on completion (a caller's result)
+        returns: [result_file]   #   variables the run guarantees on completion (a caller's result);
+                                 #   short of them: a child returns what it set + a `note`; a top-level run is rejected
                                  #   entry types: string integer number boolean date date-time object array
     instructions: >-
       Record the decision in scratchpad/refund.json, then archmax_advance to
@@ -119,7 +120,8 @@ states:
   Host seeds (`--variables`, `createAgent({ variables })`, a delivery) are
   **locked**; the agent uses `archmax_get_variables`/`archmax_set_variables`
   (`lock: true` to freeze). Reserved: `trigger` (current trigger id, always
-  locked) and `title` (the run's one-line task label, agent-owned). A
+  locked) and `title` (the run's one-line task label, agent-owned; a
+  sub-workflow child is not asked for one). A
   `${{name}}` / `${{a.b.-1.c}}` reference works in `tools.allow` globs
   (guard) and inside any text tool argument the model writes (exact
   substitution, no retyping) — but not in scripts, which read
@@ -185,7 +187,16 @@ states:
   `requires` are the parameters (typed where the entries are typed; a
   mistyped argument is refused `invalid-param`, and `"${{count}}"` alone
   passes the value with its own type), its `returns` the result
-  (`{ message, returns }`; a mistyped typed return fails `invalid-return`).
+  (`{ message, returns }`; a child finishing with some unset completes, and
+  `returns` holds what it set plus a `note` naming the rest; a mistyped typed
+  return fails `invalid-return`). Each failed call is the
+  calling state's failure, recorded with its arguments and routed through
+  `on_error` when the agent finishes unless a later successful call of the
+  same workflow from the same state recovers it first. One success recovers
+  one failed call: the one whose arguments it repeats (compared after
+  `${{…}}` resolves, key order ignored), else the oldest. A sibling in the
+  same batch does not count; another workflow's success recovers nothing;
+  the route names every outstanding failure with its arguments.
   The trigger's `description` leads the tool description. Nothing captures the result — the caller records
   what it needs with `archmax_set_variables`, made mandatory by `requires`.
   The child is a separate session with a fresh transcript, sees only its
@@ -239,7 +250,8 @@ no way to see more of the graph.
 Closed by default; **deny beats allow, and no narrower level widens a denial.**
 
 - **Always on, never declared**: `ls`, `read_file`, `write_file`,
-  `edit_file`, `glob`, `grep`, `write_todos`, `archmax_eval`, `archmax_run`,
+  `edit_file`, `copy_file`, `move_file`, `remove_file`, `glob`, `grep`,
+  `write_todos`, `archmax_eval`, `archmax_run`,
   and the controls `archmax_advance`, `archmax_reset`, `archmax_wait`,
   `archmax_raise`, `archmax_get_variables`, `archmax_set_variables`. Any other
   tool needs an
@@ -247,8 +259,15 @@ Closed by default; **deny beats allow, and no narrower level widens a denial.**
   it. `task` is ungrantable (error).
 - **Entries**: bare name; `{ tool, args: { <arg>: ["glob", …] } }` (matches
   if any glob matches; `${{var}}` allowed); `{ tool, paths: [...] }`
-  (shorthand for `args.file_path`). `"*"` as the tool is legal only in a
+  (guards every path argument the tool declares — all must match to grant,
+  any matching denies). `"*"` as the tool is legal only in a
   forbid list. Globs match dot-segments (`secrets/**` covers `secrets/.env`).
+- **Path rules read declared path arguments**: `copy_file`/`move_file` take
+  `{ source, destination, overwrite? }` (copy reads `source`, move removes it;
+  both write `destination`), `remove_file` takes `{ file_path }`. A removal is
+  refused wherever a write is; a call naming several paths is refused when any
+  one is. An existing destination is refused unless `overwrite: true`.
+  `forbid: [{ tool: "*", paths: [secrets/**] }]` blocks a copy in or out.
 - **Skills** are governed by **slug**, never path. Enabling a bundle makes
   `skills/<slug>/**` readable and its scripts runnable with no `tools.allow`
   entry; a disabled bundle is unreachable **and invisible** (not listed, not