@archmax-ai/harness 0.7.1 → 0.8.0

package/dist/machine/tool-paths.js

@@ -18,9 +18,10 @@ export const PATH_ACCESSES = ["read", "list", "search", "write", "remove", "exec
 /** The accesses that change what is stored: refused wherever a write is. */
 export const MUTATING_ACCESSES = new Set(["write", "remove"]);
 /**
- * The accesses the always-open `scratchpad/` permits an essential tool in every
- * state, whatever the state's `allow` list says. Searching and executing are not
- * among them, and a tool a state must grant gets nothing from it.
+ * The accesses the always-open `scratchpad/` permits a default file tool the
+ * state is granted (or a host `essentialTools` tool), whatever the granting
+ * entry narrows. Searching and executing are not among them, and a tool the
+ * state is not granted gets nothing from it.
  */
 export const SCRATCHPAD_ACCESSES = new Set(["read", "list", "write", "remove"]);
 /** The accesses the context-offload areas permit: readable, never writable. */

package/dist/machine/tool-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-paths.js","sourceRoot":"","sources":["../../src/machine/tool-paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-paths.js","sourceRoot":"","sources":["../../src/machine/tool-paths.ts"],"names":[],"mappings":"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"}

package/dist/machine/types.d.ts

@@ -15,11 +15,13 @@ import type { allowEntrySchema, hookSchema, forbidEntrySchema, hookSpecSchema, m
  */
 export type TransitionType = z.infer<typeof transitionTypeSchema>;
 /**
- * One outgoing edge of a state. `description` is **required and non-empty**: the
- * agent is disclosed the active state's edges and nothing else of the graph, so
- * this is the whole of what it routes on — write it for a reader standing in the
- * source state, which knows nothing of the target ("Refunds over $50", never "go
- * to refund-review"). At a human state it is also the decision's button label.
+ * One outgoing edge of a state. The agent is disclosed the active state's edges
+ * and nothing else of the graph, so `description` is what it routes on — write it
+ * for a reader standing in the source state, which knows nothing of the target
+ * ("Refunds over $50", never "go to refund-review"). An **undescribed** edge
+ * (absent, empty or blank) routes on the target state's `instructions` instead,
+ * which the edge then discloses; it loads only when the target has some. At a
+ * human state the description is also the decision's button label, and required.
  */
 export type MachineTransition = z.infer<typeof machineTransitionSchema>;
 /**
@@ -44,8 +46,9 @@ export type StateBudget = z.infer<typeof stateBudgetSchema>;
 export type AllowEntry = z.infer<typeof allowEntrySchema>;
 /**
  * Per-state tool governance. Allow-only: a state with `allow` permits exactly the
- * listed tools/arg-shapes (plus workflow-level `allow_always` grants and the
- * essential surface); a state without one gets the essential surface only.
+ * listed tools/arg-shapes plus the workflow-wide grant (the declared
+ * `allow_always`, else the default tools) and the host's `essentialTools`; a
+ * state without one gets those two only.
  */
 export type ToolsBlock = z.infer<typeof toolsBlockSchema>;
 /**
@@ -100,7 +103,10 @@ export type StateType = z.infer<typeof stateTypeSchema>;
  * `model` → the assembly's default, read once through `WorkflowMachine.modelFor`.
  */
 export type MachineState = z.infer<typeof machineStateSchema>;
-/** Workflow-level tool grants. */
+/**
+ * Workflow-level tool governance. A declared `allow_always` is the whole
+ * workflow-wide grant; an absent one grants the default tools.
+ */
 export type WorkflowToolsConfig = z.infer<typeof workflowToolsConfigSchema>;
 /**
  * Workflow-level skill governance: `allow_always` is enabled in every state and

package/dist/machine/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/machine/types.ts"],"names":[],"mappings":"AA+OA;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAoC;IAC/D,MAAM,QAAQ,GAAI,IAAkD,EAAE,QAAQ,CAAC;IAC/E,OAAO,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,KAAK,CAAC;AAC3E,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/machine/types.ts"],"names":[],"mappings":"AAqPA;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAoC;IAC/D,MAAM,QAAQ,GAAI,IAAkD,EAAE,QAAQ,CAAC;IAC/E,OAAO,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,KAAK,CAAC;AAC3E,CAAC"}

package/dist/public/spec.d.ts

@@ -122,11 +122,11 @@ isReservedToolName,
 HARNESS_CONTROL_TOOLS, 
 /** Tools permitted in every state regardless of `allow`. */
 ALWAYS_ALLOWED_TOOLS, 
-/** The always-on built-ins a state's own entry may narrow but `allow_always` cannot add to. */
-ESSENTIAL_TOOLS, 
+/** The workflow-wide grant when `tools.allow_always` is absent; a declared list replaces it. */
+DEFAULT_TOOLS, 
 /** Tools no list may grant (`task`). */
 UNGRANTABLE_TOOLS, ReservedToolNameError, 
-/** The runtime's file operations, always on in every agent. */
+/** The runtime's file operations, registered in every agent and among the default tools. */
 COPY_FILE_TOOL, MOVE_FILE_TOOL, REMOVE_FILE_TOOL, RUNTIME_FILE_TOOLS, } from "../machine/tool-names.js";
 /** Each built-in tool's path arguments and how a call uses each. */
 export { BUILT_IN_TOOL_PATHS, PATH_ACCESSES } from "../machine/tool-paths.js";

package/dist/public/spec.js

@@ -120,11 +120,11 @@ isReservedToolName,
 HARNESS_CONTROL_TOOLS, 
 /** Tools permitted in every state regardless of `allow`. */
 ALWAYS_ALLOWED_TOOLS, 
-/** The always-on built-ins a state's own entry may narrow but `allow_always` cannot add to. */
-ESSENTIAL_TOOLS, 
+/** The workflow-wide grant when `tools.allow_always` is absent; a declared list replaces it. */
+DEFAULT_TOOLS, 
 /** Tools no list may grant (`task`). */
 UNGRANTABLE_TOOLS, ReservedToolNameError, 
-/** The runtime's file operations, always on in every agent. */
+/** The runtime's file operations, registered in every agent and among the default tools. */
 COPY_FILE_TOOL, MOVE_FILE_TOOL, REMOVE_FILE_TOOL, RUNTIME_FILE_TOOLS, } from "../machine/tool-names.js";
 /** Each built-in tool's path arguments and how a call uses each. */
 export { BUILT_IN_TOOL_PATHS, PATH_ACCESSES } from "../machine/tool-paths.js";

package/dist/public/spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/public/spec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/public/spec.ts"],"names":[],"mappings":"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"}

package/dist/workflow/render-prompt.d.ts

@@ -17,7 +17,8 @@
  * No other state's slug, `title`, `summary`, hooks, budget or transitions is
  * rendered anywhere, and neither is a count of the states: a state the agent
  * cannot advance to is a state it cannot name. A state's `instructions` body is
- * surfaced only for the active state, by the caller.
+ * surfaced for the active state, by the caller, and — quoted, for choosing — for
+ * the target of an undescribed edge of the active state, by this renderer.
  */
 import type { WorkflowMachine } from "../machine/machine.js";
 /** What {@link renderStateGraph} needs about the run, beyond the state it is in. */

package/dist/workflow/render-prompt.js

@@ -17,20 +17,27 @@
  * No other state's slug, `title`, `summary`, hooks, budget or transitions is
  * rendered anywhere, and neither is a count of the states: a state the agent
  * cannot advance to is a state it cannot name. A state's `instructions` body is
- * surfaced only for the active state, by the caller.
+ * surfaced for the active state, by the caller, and — quoted, for choosing — for
+ * the target of an undescribed edge of the active state, by this renderer.
  */
 import { afterHookLabel, hookKind, normalizeHooks } from "../lifecycle/hook-shape.js";
 import { ADVANCE_TOOL, SET_VARIABLES_TOOL } from "../machine/tool-names.js";
 /**
  * One outgoing edge: the target's slug (the exact token `archmax_advance` takes),
- * its declared `type`, and the required `description` the agent routes on.
+ * its declared `type`, and the `description` the agent routes on.
  *
  * The two markers a target may carry are disclosed because each changes what the
  * call must carry or what follows it — `evidence` is accepted only when the
  * target is a human state, and both markers mean *stop* rather than *continue*.
  * They disclose the **consequence of taking the edge**, not the state on the
- * other side of it: nothing of the target's own title, summary, instructions,
- * hooks or transitions is rendered.
+ * other side of it: nothing of the target's own title, summary, hooks or
+ * transitions is rendered.
+ *
+ * An **undescribed** edge (no description, or a blank one) is transparent: the
+ * target's `instructions` stand in for the description, quoted under the line
+ * and framed as what the agent will do once there — given for choosing the edge,
+ * not to be followed now. The author opts in per edge by leaving it undescribed;
+ * the schema refuses one whose target has no instructions to show.
  */
 function renderTransition(machine, edge) {
     const notes = [];
@@ -41,7 +48,19 @@ function renderTransition(machine, edge) {
     if (machine.isTerminal(edge.to))
         notes.push("terminal");
     const suffix = notes.length ? ` (${notes.join(", ")})` : "";
-    return `- to \`${edge.to}\`${suffix} — ${edge.description.trim()}`;
+    const head = `- to \`${edge.to}\`${suffix}`;
+    const description = edge.description?.trim();
+    if (description)
+        return `${head} — ${description}`;
+    const instructions = machine.spec.states[edge.to]?.instructions?.trim() ?? "";
+    const quoted = instructions
+        .split("\n")
+        .map((line) => (line.trim() ? `  > ${line.trimEnd()}` : "  >"));
+    return [
+        `${head} — no description; the instructions you will follow once in \`${edge.to}\`, ` +
+            `given only for choosing this edge:`,
+        ...(instructions ? quoted : []),
+    ].join("\n");
 }
 /**
  * The active state's hooks, by phase. A **rubric** hook renders as its bare kind

package/dist/workflow/render-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"render-prompt.js","sourceRoot":"","sources":["../../src/workflow/render-prompt.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render-prompt.js","sourceRoot":"","sources":["../../src/workflow/render-prompt.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archmax-ai/harness",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "type": "module",
   "description": "Agents can't reliably follow a process. archmax harness makes them: a governed layer over LangChain Deep Agents that enforces a declarative workflow state machine on every step.",
   "keywords": [

package/skills/archmax-harness/SKILL.md

@@ -55,8 +55,10 @@ then verify. Do not write a file, validate, and discover the next file.
    `triggers: { manual: }` (plus any host trigger ids that enter there),
    terminal states (no `transitions`), the edges between them — and for each
    edge, the *condition* under which it is taken. That condition is the edge's
-   required `description`, and it is the only thing the agent will know about
-   where the edge leads. If something outside the session calls the workflow
+   `description`, which is what the agent knows about where the edge leads. Leave
+   an edge undescribed only when the target's `instructions` already say when it
+   applies: the agent is then shown them instead (never on a human state's
+   transitions, whose description is the button label). If something outside the session calls the workflow
    (another workflow, a host's MCP tool or form), give its trigger a
    `description` for the caller and a `requires`/`returns` signature, typing an
    entry (`{ name, type, description }`; `string` `integer` `number` `boolean`
@@ -77,7 +79,9 @@ then verify. Do not write a file, validate, and discover the next file.
    `skills/<capability>/` bundle only for data, an `archmax_run` script, or
    guidance two or more states share identically; `AGENTS.md` only for a
    workspace-wide persona.
-3. **Write `workflow.yaml`** from the skeleton in [`references/workflow-yaml.md`](references/workflow-yaml.md). Each state's behaviour
+3. **Write `workflow.yaml`** from the skeleton in [`references/workflow-yaml.md`](references/workflow-yaml.md),
+   keeping its `tools.allow_always` list of the twelve default tools: a declared
+   list replaces them, so drop only a tool this workflow must not have. Each state's behaviour
    goes inline in its `instructions`; run-wide rules once in the top-level
    `instructions`; nothing about the machine itself (the platform prompt and
    the disclosed edges already say it, and prose is billed on every call), and
@@ -212,8 +216,8 @@ Rules that follow:
   (`script.skill-only`): a script in `scratchpad/` or `hooks/` is unrunnable.
 - **Paths have no leading slash** (`skills/order-data/assets/orders.json`,
   `scratchpad/refund.json`); never author a `run/` prefix. `scratchpad/` is
-  writable in every state regardless of `tools.allow`, so an allow entry
-  inside it narrows nothing (warning); to govern *where* a result lands, name
+  writable in every state that is granted `write_file`, whatever its entry
+  narrows, so an allow entry inside it narrows nothing (warning); to govern *where* a result lands, name
   a non-reserved run path (`reports/*.json`) and allow it.
 - **Guidance has three homes, one per rule**: every workflow → `AGENTS.md`;
   the whole run → top-level `instructions` (`|-` literal block, since `>-`

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

@@ -100,7 +100,7 @@ All optional (`CreateAgentParams`, `src/assembly/index.ts`):
 | `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. |
+| `essentialTools` | `string[]` | Host tools treated as always on: disclosed and permitted in every state, whatever the workflow's `tools.allow_always` declares; 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. |
@@ -681,7 +681,8 @@ const agent = await createAgent({ tools, essentialTools: ["get_markdown"] });
   never runs the handler. No declaration, no path rules. An argument may hold a
   list of paths (`files: string[]`), each governed; any other shape is refused.
   Declaring paths only narrows: `scratchpad/` is open in every state to the
-  always-on tools, so a tool a state must grant stays refused where it is not.
+  default file tools the state is granted and to `essentialTools`, so a tool a
+  state must grant stays refused where it is not.
 - `context.workspace` is the turn's workspace, bound to the session — the
   instance `read_file` uses — with `downloadFiles`, `uploadFiles` (when the
   session store has it) and `delete` besides the text methods. The plain agent

package/skills/archmax-harness/references/diagnostics.md

@@ -27,12 +27,14 @@ message alone. Migrations for removed keys in full:
 | not a skill slug (path/glob given) | Use the bundle directory name; narrow paths with a `tools.allow` entry |
 | `${{…}}` not a valid variable reference | `${{name}}` or `${{name.path}}`; snake_case names |
 | guards on `${{x}}` but no state requires it (warning) | Add `x` to an earlier state's `requires`, or seed it at assembly |
-| `allow` on a path in `scratchpad/` (warning) | Drop it, or govern a non-reserved run path instead |
-| `tools.allow_always` constrains essential tool (warning) | Narrow per state with `tools.allow` |
+| `allow` or `allow_always` on a path in `scratchpad/` (warning) | Drop it, or govern a non-reserved run path instead |
+| `tools.allow_always` is declared but grants none of the default tools (warning) | A declared list replaces the default tools: list the ones the workflow needs (`ls`, `read_file`, `write_file`, … as in the skeleton), or remove the key to grant them all |
 | state both allows and forbids / forbids what nothing enables / enables what allow_always already does / `skills: { allow: [] }` reads like a deny (warnings) | Drop the redundant entry; use `forbid` to subtract |
 | no top-level `instructions` (warning) | Add the standing block |
 | state has several transitions but no `instructions` (warning) | Add routing guidance so the agent classifies the request before it advances |
-| `transitions.<i>.description` must be a non-empty string (error) | Add the condition under which that edge is taken — it is the only thing the agent knows about it. Say *when*, not *where* |
+| `transitions.<i>.description` must be a non-empty string here: '<target>' declares none (error) | The edge is undescribed and its target has no `instructions` to route on. Add the condition under which the edge is taken (say *when*, not *where*), or give the target instructions |
+| `transitions.<i>.description` must be a non-empty string on a human state's transition (error) | It is the decision's button label: say what choosing it means |
+| `transitions.<i>.description` must be a string (error) | Quote it, or omit it to route on the target's instructions |
 | trigger declares unknown key (warning) | Keys read: `session`, `message`, `connection`, `requires`, `returns`; others are preserved |
 | `maxConcurrency` above 1 | Set to 1 or remove |
 | `WORKFLOW.md` has frontmatter | Strip it; the machine is `workflow.yaml` |

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

@@ -275,8 +275,9 @@ 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
-`tools.allow`, or workflow-wide with `tools.allow_always`. Lifecycle hooks need
-no such grant.
+`tools.allow`, or workflow-wide with `tools.allow_always`; a default tool such as
+`read_file` is covered wherever the workflow-wide grant includes it. Lifecycle
+hooks need no such grant.
 
 ### `archmax_run` scripts: the `args` contract
 
@@ -775,8 +776,8 @@ steps:
 Two operational notes:
 
 - Seeding writes the file; **reading it is still governed** — the triggered
-  start state must allow the read tool the agent needs (`read_file` is an
-  always-on tools unless a state narrows it).
+  start state must allow the read tool the agent needs (`read_file` is granted
+  wherever the workflow-wide grant includes it, unless a state narrows it).
 - Hosts that pin case sessions via `sessionIdForCase` reuse sessions across test
   runs: declared files are overwritten each run, but a file seeded by an
   _earlier_ run whose declaration was since removed can linger. The default

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

@@ -80,8 +80,8 @@ instructions?: string         # the workflow's STANDING instructions — free-fo
                               # simply ignored; use `instructions:`, rereading the
                               # text as direction, not narration.
                               # A test case's `description` is UNAFFECTED. A
-                              # TRANSITION's `description` is now REQUIRED and
-                              # non-empty (see `transitions` below).
+                              # TRANSITION's `description` is what the agent routes
+                              # on (see `transitions` below).
 
 disabled?: boolean            # `true` = this machine STARTS NO NEW TURNS. Bounds
                               # STARTING, not finishing.
@@ -146,7 +146,13 @@ tests?:                       # cases suite config (declarative data;
                               #      factory's `judge` role; other keys are errors
 
 tools?:
-  allow_always?: AllowEntry[] # grants added to every state's allowlist
+  allow_always?: AllowEntry[] # the WORKFLOW-WIDE GRANT, in every state. ABSENT = the
+                              #      default tools (ls, read_file, write_file, edit_file,
+                              #      glob, grep, copy_file, move_file, remove_file,
+                              #      write_todos, archmax_eval, archmax_run). DECLARED
+                              #      ([] included) = exactly what it lists: it REPLACES
+                              #      the default tools, so list each one you want. A
+                              #      new workflow lists all twelve.
   forbid_always?: ForbidEntry[]
                               # DENIED in EVERY state, and absolute: nothing reaches
                               #      past it — no state grant, allow_always entry,
@@ -312,8 +318,9 @@ states:
                                # NO PART OF THE PROMPT — the model never reads it,
                                # so it is free, and it can NOT carry routing logic.
                                # The routing text the agent reads is the SOURCE
-                               # state's transition `description`s; nothing about a
-                               # target state is disclosed at all.
+                               # state's transition `description`s, or a target's
+                               # `instructions` where an edge is undescribed; a
+                               # target's summary is never disclosed.
 
     instructions?: string      # behavior guidance.
                                #   agent node: surfaced to the LLM while active.
@@ -328,13 +335,14 @@ states:
                                #   for a terminal state)
 
     tools?:
-      allow?: AllowEntry[]     # grants beyond the always-on tools (plus
-                               # allow_always grants and the always-allowed
-                               # archmax_advance); an entry naming
-                               # an always-on tool NARROWS it.
+      allow?: AllowEntry[]     # grants beyond the workflow-wide grant (plus the
+                               # always-allowed archmax_advance); an entry naming
+                               # a tool that grant includes NARROWS it, and one
+                               # naming a default tool a declared allow_always
+                               # leaves out GRANTS it here.
       forbid?: ForbidEntry[]   # what this state DENIES while active — beating the
-                               # workflow's allow_always, this state's own allow,
-                               # and the always-on surface alike. Deny beats allow.
+                               # workflow-wide grant, this state's own allow,
+                               # and a host's essentialTools alike. Deny beats allow.
                                # Not inherited by a sub-workflow; a lifecycle hook
                                # is exempt from it (runtime authority).
 
@@ -421,25 +429,35 @@ states:
                                #
                                # Transition = {
                                #   to: string          # a declared state's SLUG
-                               #   description: string # REQUIRED, non-empty
+                               #   description?: string # what the agent routes on
                                #   type?: "approve" | "reject" | "refine" | "none"
                                # }
                                #
                                # THE AGENT SEES THIS STATE'S EDGES AND NOTHING
                                # ELSE OF THE GRAPH — no other state's slug, title,
                                # summary, hooks or transitions, and no count of
-                               # the states. So `description` is the whole of what
-                               # it knows about where an edge leads, and a missing
-                               # or blank one is a LOAD ERROR naming
-                               # states.<slug>.transitions.<i>.description.
+                               # the states. So `description` is what it knows
+                               # about where an edge leads. An UNDESCRIBED edge
+                               # (absent/empty/blank) routes on the TARGET's
+                               # `instructions` instead: the edge's line carries
+                               # them, quoted, and nothing else of the target.
+                               # LOAD ERRORS (states.<slug>.transitions.<i>.description):
+                               # an undescribed edge whose target has no
+                               # instructions; an undescribed transition of a
+                               # HUMAN state (it is the button label); a
+                               # non-string. An undescribed edge INTO a human
+                               # state discloses that state's reviewer-facing
+                               # instructions to the agent — describe it to keep
+                               # them private.
                                #
                                # Write it for a reader standing in THIS state,
                                # which knows nothing about the target:
                                #   GOOD: "The refund is over $50."   (when)
                                #   BAD:  "Go to refund-review."      (where)
                                # A routing condition CANNOT live in the target's
-                               # summary/instructions — those are never disclosed
-                               # to the state routing into it.
+                               # summary, which is never disclosed; it lives in the
+                               # target's instructions only when the edge is left
+                               # undescribed.
                                #
                                # The rendered line marks a target that is a human
                                # decision node or terminal (each changes the call
@@ -666,11 +684,12 @@ an entry naming an unprefixed variant governs a tool that does not exist,
 silently granting nothing. A host tool may never claim the prefix. Deep Agents' built-ins
 (`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`, `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).
+- A state with **no `tools` block** gets the **workflow-wide grant only**: what
+  `tools.allow_always` lists, or the default tools (`ls`, `read_file`, `write_file`,
+  `edit_file`, `copy_file`, `move_file`, `remove_file`, `glob`, `grep`, `write_todos`,
+  `archmax_eval`, `archmax_run`) when the key is absent, plus the always-allowed
+  `archmax_advance` and a host's `essentialTools`, 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.
 - `tools.forbid` on a state **denies** while that state is active, beating every
   grant that would otherwise reach it (see [Tool governance](#tool-governance)).
@@ -712,7 +731,8 @@ success.
 ```yaml
 transitions:
   - to: string                 # REQUIRED target state SLUG (must exist); never a title
-    description?: string        # shown to the agent (or human) to pick the edge
+    description?: string        # shown to the agent (or human) to pick the edge; absent =
+                                #   the agent is shown the target's instructions instead
     type?: "approve" | "reject" | "refine" | "none"   # default "none"
 ```
 
@@ -746,22 +766,30 @@ platform-provided tool resolves through when its collection has several) and
 `source` (any string: a host's own label for where the tool came from) — the
 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`, `copy_file`, `move_file`,
-`remove_file`, `glob`, `grep`, `write_todos`, `archmax_eval`, `archmax_run`). One built-in is **never
+**The model is closed by default, and a denial beats every grant.** Every state has the
+**workflow-wide grant**: what `tools.allow_always` lists, or, when the workflow does not
+declare that key, the **default tools** (`ls`, `read_file`, `write_file`, `edit_file`,
+`copy_file`, `move_file`, `remove_file`, `glob`, `grep`, `write_todos`, `archmax_eval`,
+`archmax_run`). A declared list **replaces** the default tools, never adds to them:
+`allow_always: []` grants no tool workflow-wide, and a list without `write_file` leaves
+every state that does not name it unable to write. So a new workflow lists all twelve and
+removes only what it must not have. Every state also has the always-allowed controls and
+any tool the host passes as `essentialTools`, whatever the workflow declares. 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.
 The planning scratchpad `write_todos` and the sandbox
-`archmax_eval` are standard equipment — always disclosed, always permitted,
-no setting; only a `forbid` list refuses them. The interpreter is safe as a
+`archmax_eval` are default tools: granted wherever the workflow-wide grant includes
+them (everywhere, in a workflow without `allow_always`). `write_todos`'s prompt
+guidance appears only when some state is granted it, and hooks run in the sandbox
+whether or not the agent is granted `archmax_eval`. The interpreter is safe as a
 default because the `tools.*` calls its code makes are decided against the active
 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
+access. `archmax_run` — executing an authored script **file** — is a default tool 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. 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
+and `remove_file({ file_path })` — are default tools 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`
@@ -774,16 +802,19 @@ entry guards every declared path argument: a grant needs all of them to match
 declares its paths (`toolPaths`, or a descriptor's `paths`) is governed the same
 way; an argument may hold a list of paths, each one governed (and each one
 tested by a `paths:` guard), and any other shape is refused
-(`tool.path-argument`). `scratchpad/` is open in every state to the always-on
-tools only — a host tool a state must grant stays refused where it is not
-granted, whatever its paths. Any other tool
+(`tool.path-argument`). `scratchpad/` is open in every state to each default file tool the state
+is granted, whatever the granting entry narrows, and to a host's `essentialTools`.
+A file tool the state is not granted gets nothing from it, and a host tool a state
+must grant stays refused where it is not granted, whatever its paths. 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.
+`tools.allow_always`. A `tools.allow` entry naming a tool the workflow-wide grant
+includes **narrows** it for that state. A guard on an `allow_always` entry is
+enforced like any other (`{ tool: write_file, paths: [reports/**] }` binds in every
+state that does not name `write_file`).
 Denial is declared beside the grant, in the same two positions and with the same
 entries: `tools.forbid_always` at the root denies in every state,
 `tools.forbid` on a state denies while it is active — subtracting from the
-workflow's grant, the state's own `allow` and the always-on surface alike.
+workflow-wide grant, the state's own `allow` and a host's `essentialTools` alike.
 **Deny beats allow, and no narrower level widens a denial.** A forbid entry may
 name the tool `*` (every tool); `*` in an allow list is a load error. A lifecycle
 hook is exempt from the state's `allow` **and** its `forbid` — runtime authority,
@@ -803,17 +834,18 @@ Precedence (highest first):
    (and regardless of always-allowed): deny beats allow, and no narrower level
    widens a denial.
 2. **Always allowed**: `archmax_advance` (baked in, every state).
-3. **Per-state `tools.allow`** — the listed tools/arg-shapes. An entry for an
-   always-on tool (or one also in `allow_always`) takes precedence
-   (**narrower wins** — the state's arg globs apply, not the broader grant).
-4. **Essential built-ins** — always permitted when no state entry narrows
-   them. Listing one in `allow_always` is inert (`archmax validate` warns).
-5. **Workflow `tools.allow_always`** — grants tools that are not always on in every
-   state.
+3. **Per-state `tools.allow`** — the listed tools/arg-shapes. An entry for a
+   tool the workflow-wide grant includes takes precedence (**narrower wins** —
+   the state's arg globs apply, not the broader grant); an entry for a default
+   tool a declared `allow_always` omits grants it in this state.
+4. **The workflow-wide grant** — the declared `tools.allow_always`, guards
+   included, or the default tools, unconstrained, when the key is absent.
+5. **The host's `essentialTools`** — always permitted when no state entry
+   narrows them, whatever the workflow declares.
 6. **Default**: everything else is blocked.
 
 **Progressive disclosure.** The model is only shown the active state's tool
-surface: always-on tools + `allow_always` + the state's entries + `archmax_advance`
+surface: the workflow-wide grant + a host's `essentialTools` + the state's entries + `archmax_advance`
 (hidden in terminal states), minus every tool denied there by name. Disclosure is
 name-level (arg-constrained tools stay visible; the kernel enforces args at
 call time) and never replaces enforcement. **Skills are disclosed the same way**:
@@ -1839,7 +1871,7 @@ them. Its shape:
 - `orders-question` (terminal) answers from `skills/order-data/assets/orders.json`; an
   `after: { rubric: order-reply-tone }` grades the reply at completion.
 - `refund-request` records a decision to `scratchpad/refund.json` (no allow entry
-  narrows it — the working area is open in every state; what holds the agent to a
+  narrows it — the working area is open to `write_file` wherever it is granted; what holds the agent to a
   correct file is the hook), runs `after: check-refund.js`, and pairs
   `budget.maxTurns: 24` with `on_error: escalation` so a terminal failure
   (hook error, exhausted corrections, exhausted budget) routes to escalation