better-dsh 0.0.0 → 0.2.2-b

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 RimuruW and Yugimob (original pi-hashline-edit / pi-hashline-edit-pro)
+Copyright (c) 2026 pi-hashline-edit-lsz contributors (pi port, hashline core)
+Copyright (c) 2026 dsh-better-edit contributors (dsh port)
+Copyright (c) 2026 DASHR contributors (dsh-url-schema vendoring)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,299 @@
-# better-dsh
+# Better Dsh — Dashr
 
-> **This package name has moved.**
+DASHR is a persistent-kernel REPL for the DeepSeek Harness (dsh): a
+**stateful `ctx.replRuntime` provider** (one persistent IPython kernel
+subprocess **per session**, the run's `principal`, held in a map inside the
+one service instance per mount). Each `run()` is one cell on the calling
+session's kernel; variables, imports, and definitions assigned in run N
+survive into run N+1 — *state codification* (blueprint §1.1 channel ②),
+deliberately NOT the per-run isolation a one-shot execution backend
+provides — and two sessions sharing one service instance never see each
+other's variables.
 
-Install the scoped package instead:
+Naming (v0.1.5 layer model): the runtime class is **`DashrRuntime`** — the
+standing-mount-layer component (one instance per mount holding the
+cross-session kernel map), and therefore the de facto daemon while the
+profile-level `DashrDaemon` concept stays an empty shell; the session layer
+is the ipykernel subprocess itself, a pure interpreter with no harness
+awareness.
+
+The presentation half — the `eval` transport tool, the Python SDK renderer,
+and the tool→binding bridge — lives in the SAME package (merged in v0.1.8;
+the pre-merge `dsh-rlm-mode`/`dashr-presentation` sibling split is gone).
+The runtime registers the service key `replRuntime` through its own vendored
+Service Definition (see `src/vendored/repl-runtime.ts`), so it carries **zero
+dsh runtime package dependencies**: only `@deepseek-ai/cordis` (peer),
+`schemastery`, and `zeromq`.
+
+## Package positioning
+
+- npm name: `better-dsh` (unscoped; formerly `@pgmi-builds/better-dsh`, which
+  now stays published only as a deprecated pointer to this name).
+- A standard Cordis plugin (`Context` + schemastery `Config`, every tunable
+  configurable from `cordis.yml`, no hardcoded tunables).
+- "Registrations are effects": the kernel lifecycle (lazy spawn on a key's
+  first `run()`, teardown on that session's `agent/disposed`, optional
+  snapshot at either teardown) is effect-owned, so plugin disposal tears
+  every subprocess down.
+- Published surface: `lib/` only (`files: ["lib"]`, `main`/`types`/`exports`
+  pointing at `lib/index.js` / `lib/index.d.ts`) — the build emits beside the
+  manifest (`outDir: 'lib'`; the tsdown default `dist/` left the exports map
+  dangling, fixed in M2B). The root also re-exports the vendored Service
+  Definition's public contract (`ReplRuntime` plus the `CodeRun*` /
+  `CodeBinding*` / `CodeJsonValue` types) so consumers depend on the
+  published shape instead of reaching into sources. The declaration keeps
+  dependency imports external (`dts: { resolve: false }`): bundled copies
+  would create duplicate type identities in a consumer's program.
+
+## Install
+
+```sh
+npm install better-dsh
+```
+
+The runtime OWNS its kernel environment. With `python` left at the
+`python3` sentinel (or absent), it provisions a managed venv under the
+package (`.venv-kernel`) on first use, installing `ipykernel` + `dill`
+(CPython 3.11) — no `/tmp` symlink, no blind trust in a host `python3`.
+An explicit `python` (or `DASHR_KERNEL_PYTHON`) is verified instead. For
+development and tests, pre-create the venv:
+
+```sh
+npm run kernel:venv        # uv venv .venv-kernel --python 3.11 + ipykernel + dill
+```
+
+Tests pick the kernel interpreter from `DASHR_TEST_PYTHON`, falling back to
+`./.venv-kernel/bin/python`, then `python3` — see `test/helpers.ts`.
+
+## Configuration
+
+Every field of the plugin `Config` (schemastery defaults shown):
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `python` | `python3` | Explicit interpreter with `ipykernel`; the bare `python3` sentinel (or absent) selects a managed venv under `kernelEnvDir`. |
+| `startupTimeoutMs` | `30000` | Budget for kernel spawn → ready, in milliseconds. |
+| `runTimeoutMs` | `120000` | Wall budget per run; expiry interrupts the kernel then force-settles. |
+| `interruptGraceMs` | `2000` | Grace between a timeout/abort interrupt and the force-settle. |
+| `interruptConfirmMs` | `250` | Confirm window between the control-channel interrupt and the SIGALRM escalation (must be `< interruptGraceMs`); see "Interrupts" below. |
+| `disposeTimeoutMs` | `5000` | Budget for graceful kernel teardown (shutdown_request → SIGKILL). |
+| `snapshotTimeoutMs` | `30000` | Budget for internal snapshot/restore cells (dill dump/load). |
+| `maxOutputBytes` | `67108864` | Hard cap for serialized log-array, completion-value, and failure-message payloads. |
+| `snapshotDir` | *(unset)* | Base directory for per-session namespace snapshots (`<dir>/<principal>/state.dill` + `manifest.json`); none when absent. |
+| `snapshotSizeCapBytes` | `268435456` | Serialized-size cap for a turn-end snapshot; over-cap snapshots are skipped (one-time model warning). |
+| `username` | `dashr` | Jupyter username stamped on wire messages. |
+| `kernelEnvDir` | *(unset)* | Managed venv directory (defaults to `<package>/.venv-kernel`). |
+| `kernelPythonVersion` | *(unset)* | Preferred CPython version for a managed venv (default `3.11`). |
+| `kernelAutoInstall` | `true` | Provision the managed venv (`ipykernel` + `dill`) on first use. |
+
+## Persistent-state semantics
+
+- **Cell semantics**: each `run({ program })` is one cell on the calling
+  session's kernel namespace (`user_ns`) — a pure IPython REPL. Top-level
+  `await` works; a top-level `return` is a SyntaxError, exactly as in a
+  native IPython cell. The completion value is the LAST expression's value
+  (REPL displayhook-style): a statement-ending cell or a `None` final
+  expression yields no `value` field, and a non-JSON value comes back as its
+  repr text.
+- **Session keying** (M3-A): one kernel per distinct `request.principal`
+  (the presentation bridge passes the calling agent's session id); runs
+  without a principal share one default key, preserving M1 semantics. The
+  service instance count is unchanged — one per mount — the keying is a
+  `Map<principal, kernel>` inside the provider.
+- **Kernel lifetime**: lazy start on a key's first `run()`; teardown when
+  that session's agent is disposed (the dsh `agent/disposed` event, payload
+  `{ agent: { id } }`, listened through the untyped cordis event service to
+  keep this package's zero-dsh-dependency rule) and on plugin disposal
+  (`shutdown_request`, then SIGKILL after `disposeTimeoutMs`). A kernel that
+  dies unexpectedly is never reused in-process: it respawns onto its nearest
+  replayable snapshot (or a fresh empty kernel when none exists) and the run
+  that observed the death gets an explicit `worker-exit` naming what was lost.
+- **Turn-end snapshots** (M3-B): with `snapshotDir` configured, every
+  successful run is followed by a size-capped snapshot cell that dumps the
+  user namespace to `<snapshotDir>/<principal>/state.dill` + `manifest.json`
+  (`turn`, `pythonVersion`, `venvPath` = the kernel's own `sys.executable`,
+  `skills`, `names`, `sizeBytes`). A namespace whose serialized size exceeds
+  `snapshotSizeCapBytes` is skipped — estimated BEFORE any dill IO by a
+  bounded walk that reads numpy/pandas in-memory footprints, then confirmed
+  against the actual `.part` dump — and the model is warned once through the
+  run's own logs. Skipped snapshots never replace the previous good one.
+- **Restore-on-first-boot** (M3-B): a key's first kernel boot restores its
+  on-disk snapshot before running user code. The kernel validates the
+  manifest itself (python version, interpreter identity, skills); a
+  non-replayable snapshot degrades to an EMPTY namespace and the first run
+  tells the model so. Variable state and the append-only transcript are NOT
+  transactionally consistent (blueprint §8.3): the snapshot is a point-in-time
+  namespace capture that can lag the transcript, and a degraded restore never
+  fabricates variables the transcript once saw.
+- **Interrupts** (M3-A hardened): aborts/timeouts escalate in two phases —
+  the zmq control `interrupt_request` first, then SIGALRM only after
+  `interruptConfirmMs` if the cell has still not settled. The kernel-side
+  bootstrap installs a busy guard that only raises `KeyboardInterrupt` while
+  a dashr cell is actually executing, so a signal landing on an idle or
+  booting kernel is swallowed instead of terminating the process (the M1
+  same-tick dual send killed idle kernels deterministically — 10/10
+  same-tick, 8/10 at +1-2ms, 40/40 during cold boot; see
+  `test/interrupt-race.spec.ts`). The hard-abort contract is intact: a busy
+  `while True: pass` still breaks inside the grace (blueprint §10.4).
+- **Concurrency**: the bridge serializes cells per kernel (`executeCell`
+  awaits the previous cell), so concurrent `run()` calls on one session
+  queue rather than interleave; see `test/parallel.spec.ts`. Runs on
+  DIFFERENT principals execute on their own kernels concurrently.
+- **What snapshots do NOT carry**: nothing outside the kernel namespace is
+  ever in scope — the v0.1.8b removal deleted the Continual Harness
+  (`refine()`, `harnessDir`) entirely, so the snapshot/restore cycle's only
+  persistence channel is the kernel namespace itself (blueprint §8.4).
+  Anything a cell stores in ordinary variables follows the snapshot rules
+  above as before.
+
+## Testing
+
+```sh
+npm install
+npm run kernel:venv     # once; or export DASHR_TEST_PYTHON=/path/to/python
+npm run typecheck       # tsc --noEmit
+npm test                # vitest --run (fileParallelism: false)
+```
+
+Teardown discipline: every test context is disposed through
+`onTestFinished`, and CI must assert no orphan kernels remain:
 
 ```sh
-npm install @pgmi-builds/better-dsh
+pgrep -cf -- '-[m] ipykernel_launcher' || echo no-orphans
 ```
+
+(The `-[m]` trick prevents `pgrep` from matching itself; 208 orphaned
+kernels once exhausted machine memory while every unit test stayed green —
+blueprint §10.8/§10.9.)
+
+---
+
+# Presentation half (eval transport, SDK, bindings)
+
+The DASHR agent-plane presentation (blueprint §7.4): the plugin half that
+presents the persistent-kernel runtime to the model as **cells on one
+persistent IPython kernel**. It contributes:
+
+- **`eval`** — the cell transport tool: one call = one cell on the calling
+  session's kernel (the `ctx.replRuntime` service). Variables, imports, and
+  definitions survive across calls. Nested tool calls ride the host
+  registry's native scheduling pipeline as `await tool.name({...})` inside
+  the cell — one positional arguments object per call, keyword arguments
+  rejected. Every registry-visible tool is bound as a member; the
+  `send_message` bridge callable joins them in the same catalog block.
+- **`dashr:tool-catalog`** — a generated Python SDK prompt section: one
+  `async def name(args) -> Output` per visible tool (flat `tool.*` shape)
+  plus the cell contract (persistent namespace, completion-value rules,
+  `ToolCallError`, sub-call concurrency).
+- **The model-direct collapse** — an assembly filter leaves `eval` the only
+  contributed tool schema, and a monotonic guard denies a model-direct call
+  naming anything else with the route back into a cell. Both are scoped to
+  the mounting composition, so a PTC (native Code Mode) preset in the same
+  process keeps its own presentation.
+- **Masking (ADR-0002)** — exactly two upstream tool names are displaced
+  from the model's surface (`send_message` and the child-scoped `report`),
+  collapsed into the single dual-direction `send_message` bridge. Every
+  other delegation tool (`subagent`, `subagent_fork`, `list_agents`,
+  `interrupt_agent`, `workflow`, `ralph`) stays **directly exposed** as a
+  native `tool.*` binding — the model calls it exactly as the host ships it.
+  Masking is presentation-only: the registry is never touched.
+
+Removed in v0.1.8b: the `refine` Continual Harness and the `compact` REPL
+bridge (harness/refine became third-party territory; context compaction is
+the host runtime's business, not the REPL's).
+
+## Install
+
+The canonical path is the repo-root one-click installer (`install.sh`): it
+installs the plugin from the npm registry and notes the restart. The
+equivalent manual steps, for reference:
+
+```sh
+# 1. plugin — the pnpm registry-metadata cache can lag a fresh npm publish
+#    by minutes-to-hours, so drop it first, or `@latest` resolves the OLD
+#    version right after a release:
+rm -rf ~/.cache/pnpm
+dsh plugin --profile web add --config.auto-install-peers=false better-dsh@latest
+
+# 2. restart the running instance:  systemctl --user restart dsh
+```
+
+Notes: `--config.auto-install-peers=false` is MANDATORY — the profile
+already resolves `@deepseek-ai/*` peers through the harness install; letting
+the package manager auto-install them adds a second, divergent copy of
+cordis and friends. The version is deliberately unpinned (`@latest`).
+
+## Coexistence with a PTC Code-Mode session
+
+`eval` is our own transport name (the registry reserves `run_code`), so a
+Code-Mode preset (`@deepseek-ai/dsh-agent-tool-presentation` with
+`mode: code` over the host-plane worker-thread `codeRuntime`) composes
+beside a DASHR session in one process: the PTC agent's assembly shows
+`run_code` plus the TS `tools:sdk` section, the DASHR agent's shows `eval`
+plus the Python `dashr:tool-catalog`, and neither execution path touches
+the other's runtime.
+
+## Composition
+
+```ts
+import dashr from 'better-dsh'
+
+ctx.plugin(dashr, { maxParallelSubCalls: 10 })
+```
+
+One plugin, one row: `apply` mounts `DashrRuntime` first (providing
+`ctx.replRuntime`), then the presentation half injects on `replRuntime` —
+a composition without the runtime fails AT MOUNT, named in the preset's
+activation audit, instead of at the first prompt. The dashr bundle patch
+mounts the row on the HOST plane, so every agent in every preset sees the
+`eval` tool (`agent → preset → global`).
+
+## Delegation and messaging
+
+The upstream delegation tools stay REGISTERED, EXECUTABLE, and directly
+bound — `subagent`, `subagent_fork`, `list_agents`, `interrupt_agent`,
+`workflow`, `ralph` are ordinary `tool.*` members the model calls exactly
+as the host ships them. Two names are displaced by the single
+`send_message` bridge (ADR-0001): upstream `send_message` (the
+parent→child downlink) and the child-scoped `report` (the child→parent
+uplink) collapse into one dual-direction channel:
+
+- `await tool.send_message({"receiver": "child", "message": ..., "subagent_id": ...})`
+  delivers down through the tool layer;
+- `await tool.send_message({"receiver": "parent", "message": ...})` reports
+  up through the SERVICE layer (`ctx.subagents.reportFrom(...)`) — live
+  continuable children only; a root agent gets a structured `UNAUTHORIZED`.
+
+Every binding returns structured JSON; errors are a FIELD on the result,
+never a host crash — a missing `ctx.subagents` service, a depth cap, an
+unknown id, or an infrastructure rejection all map to an `error` string.
+
+## Config
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `maxParallelSubCalls` | `10` | Cap on one cell's overlapping sub-calls (native scheduler contract; `1` = strictly serial). |
+| *(runtime keys)* | — | The runtime slice (`python`, `snapshotDir`, timeouts, caps, kernel-env knobs) is documented in the Configuration table above. |
+
+## Tests
+
+```sh
+npm install
+npm run kernel:venv     # once; or export DASHR_TEST_PYTHON=/path/to/python
+npm run typecheck
+npm test                # vitest --run
+```
+
+The suite needs a Python interpreter with `ipykernel` (+ `dill` for the
+snapshot tiers) for the real-kernel specs; it resolves one from
+`DASHR_TEST_PYTHON`, then `./.venv-kernel/bin/python`, then `python3` —
+see `test/helpers.ts`.
+
+## Relationship to upstream
+
+Structure mirrors `@deepseek-ai/dsh-agent-tool-presentation` and the Code
+Mode half of `@deepseek-ai/dsh-tools` (0.1.1-rc.2), re-pointed at the
+vendored `replRuntime` Service Definition. See the module docs in
+`src/index.ts` for the deliberate deltas (`eval` vs `run_code`, ordinary
+scoped registration, guard-based collapse, mirrored `tools/code-dispatch-log`
+waterfall).

package/control-prompt.md

@@ -0,0 +1,37 @@
+## The DASHR REPL interface
+
+This agent has TWO ways to act:
+
+1. **Direct tool calls** — call native tools (`read`/`write`/`edit`/`bash`/…) as ordinary function calls. Use these for payload-shaped work: one long read, one edit, one command.
+2. **`eval` cells** — one `eval` call runs one Python program on a session-persistent scripting pad. Use it when you need logic: loops, conditions, fan-out, or composing many tool results into one step.
+
+`eval` takes two required arguments: `cell` (one Python program; top-level `await` works; top-level `return` is a SyntaxError — the cell runs in module scope; variables/imports/definitions from earlier cells are still alive) and `description` (a short summary).
+
+## Tools inside a cell
+
+Inside a cell, every native tool is a member of the `tool` object, called as `await tool.name({...})` with ONE positional arguments object — `await tool.read({"file_path": "x"})`, never `tool.read(file_path="x")`. A failed call raises `ToolCallError`. Tool names that are not plain identifiers (non-identifier characters, e.g. hyphens) have no `tool.<name>` member — call those as direct tool calls. Delegation: `agent` is the unified agent-spawn entry; `subagent` is its native alias — both delegate through the same runtime, so call either.
+
+```python
+# One step cell
+print(await tool.read({"file_path": "docs/README.md"}))
+
+# shell is another tool
+r = await tool.bash({"command": "ls -la src/", "description": "List source directory"})
+print(r["stdout"]["text"])
+
+# fan-out with gather
+import asyncio
+matches, files = await asyncio.gather(
+    tool.grep({"pattern": "TODO", "path": "src"}),
+    tool.glob({"pattern": "**/*.ts", "path": "src"}),
+)
+
+# variables persist across cells and turns
+cfg = await tool.read({"file_path": "config.yaml"})   # cfg stays alive in later cells
+```
+
+## Rules
+
+- Payload-shaped work (a long read, a big write, a single command) → direct tool call. Logic-shaped work (loops, conditions, composition) → an `eval` cell.
+- Only print or return what you need next; everything else stays in the scripting pad.
+- Variables persist across cells and turns, but they live in the pad's process: keep durable state in files.

package/cordis.patch.yml

@@ -0,0 +1,53 @@
+# DASHR bundle patch: mounts `dashr-repl` on the HOST plane. Its `eval` tool
+# and persistent-kernel REPL runtime land in the global scope layer, so every
+# agent in every preset sees them (`agent → preset → global`). One
+# process-global runtime keys one kernel per Session/Agent, torn down on
+# `agent/disposed` — the promotion of the v0.1.5 DashrDaemon shell.
+#
+# The tool is an ordinary registration: upstream's `code` preset still applies
+# its own `tools:code-only` rule (a direct `eval` call in a PTC session resolves
+# to UNKNOWN_TOOL). DASHR ships no PTC mode, so that rule never bites here.
+#
+# `python` is only a hint: the runtime OWNS the kernel environment. An
+# explicit interpreter (DASHR_KERNEL_PYTHON) is verified; the bare
+- insert:
+    - id: dashr-repl
+      name: 'better-dsh'
+      config:
+        python: !!js process.env.DASHR_KERNEL_PYTHON ?? 'python3'
+        # NOTE (v0.2.2a): trustedPageAuthorities' DERIVED default lives in the
+        # plugin's Config schema (src/index.ts), NOT here — a profile/home
+        # layer row with this id whole-row-overrides this config object, which
+        # would wipe any default declared at the bundle layer (empirically
+        # pinned on 4999). Schema defaults fill per-key at plugin load and
+        # survive every overlay layer; the default derives from the
+        # DSH_TRUSTED_HOSTS environment — the same single source the fence
+        # leg reads first. An explicit value in any later layer still wins.
+
+# Native compaction at the host plane: the base bundle ships the engine, the
+# `/compact` command, and the tool-result pruner as host rows; dsh-web-app
+# disables them to move compaction behind per-session presets. DASHR is
+# host-plane, so re-enable them here (upstream defaults: threshold 0.8, retain
+# 0.16). Applied last in bundle order, overriding dsh-web-app's disable.
+- id: compaction-basic
+  disabled: false
+- id: command-compact
+  disabled: false
+- id: tool-result-pruner
+  disabled: false
+
+# Web-trust fence authorities (v0.2.1f): override the connection row the
+# dsh-web-app bundle declares (same id), restating its full shape per the
+# patch-layer contract, with `trustedHosts` merging the DSH_TRUSTED_HOSTS
+# environment (whitespace-separated, operator-declared serving authorities)
+# ahead of the upstream webRuntime-derived ones (LAN literals from an
+# all-interface bind plus --trusted-host extras). Unset/empty env ⇒ identical
+# behavior to the unpatched row. Malformed entries fail plugin load loudly
+# (upstream assertTrustedAuthority). The browser-side twin (page-authority
+# loopback verdict) is the plugin's webserver/index-inject boot script —
+# see src/web-trust.ts.
+- id: connection
+  name: '@deepseek-ai/dsh-client-connection'
+  inject: [webRuntime]
+  config:
+    trustedHosts: !!js (process.env.DSH_TRUSTED_HOSTS ?? '').split(/\s+/).filter(Boolean).concat(ctx.webRuntime.trustedHosts)

package/docs/00_adr/0001-bridge-tool-layer-not-service-layer.md

@@ -0,0 +1,14 @@
+# Bridge the tool layer, not the service layer
+
+DASHR's `rlm()` family dispatches upstream delegation tools through the tool registry (nested sub-dispatch), not `ctx.subagents` service methods. The tool layer carries the deployment's enforcement surface — approval pipeline, sandbox policy, per-instance config (maxDepth, backgroundMode, persona) — that a direct service call would silently bypass. The cost: per-call model selection is impossible, because the tool schema exposes no `model` parameter; `rlm(model=...)` from 0.1.4 is dropped, and `subagentModel` degrades to a static `agentOptions.model` in the preset patch.
+
+## Considered Options
+
+- **Service layer direct** (0.1.4's approach): `ctx.subagents.start()` with a hand-built request. Full control over request fields (including `agentOptions.model` and `maxDepth`), but every policy the tool instance would have applied must be re-implemented or lost.
+- **Tool layer nested dispatch** (chosen): `rlm("spawn")` executes the registry's `subagent` tool with a parent token. Upstream policy is inherited wholesale; the schema boundary is the tool's own contract.
+
+## Consequences
+
+- `rlm(mode, prompt, *, label, run_in_background)` — no `model` kwarg. Parent-model inheritance is the default; a different child model requires a preset patch, not a call argument.
+- Depth enforcement comes from the tool instance's `maxDepth` config, patched to 10 in the preset (see `dev/kernel-refactoring/V0.1.5-development-plan.md` Q22/Q23).
+- The upstream delegation tools (`subagent`, `subagent_fork`, `interrupt_agent`) must stay registered and executable even though the model never sees their names — which is why masking is presentation-only (ADR-0002).

package/docs/00_adr/0002-masking-is-presentation-only.md

@@ -0,0 +1,15 @@
+# Masking is presentation-only
+
+Hiding exactly two upstream A2A tool names (`send_message` — the parent→child downlink — and `report` — the child→parent uplink) from the model is done by excluding them from the generated Tool Catalog text and from the kernel binding names — nothing else. The two tools stay registered, executable, and dispatchable; the single `send_message` bridge dispatches them internally. Every OTHER upstream delegation tool (`subagent`, `subagent_fork`, `list_agents`, `interrupt_agent`, `workflow`, `ralph`) is exposed directly as a native `tool.*` member — no re-wrapping (v0.1.9).
+
+## Considered Options
+
+- **`restrict()` at runtime**: hides names in the registry's model-facing view, but validates against the live view at call time — ordering hazards against late tool registration can fail the whole preset mount.
+- **`disabled: true` include patches**: physically unregisters the tool, which also removes the bridge's dispatch target. Masking must not break the bridge.
+- **Presentation-only exclusion** (chosen): the registry is never touched. The model's surface (wire schema collapse to `eval`, Tool Catalog text, kernel bindings) is entirely DASHR-generated, so exclusion happens at the two points DASHR owns.
+
+## Consequences
+
+- The masked tools remain in the registry and are reachable via nested sub-dispatch with a parent token, which passes the model-direct guard.
+- **Field-verified (v0.1.8d, `both` presentation mode)**: reachable by MODEL-DIRECT native call too — no parent token needed. A probe calling the masked `skill({"name":…})` through the API function-call surface executed in full. Cause: the mask registers no visibility filter, so the name stays in `view(scope).visible`, and `resolveExecution` collapses model-direct calls only under `code` mode. The mask is an ADVERTISING cut, not an enforcement point; the hard gate is the REPL binding allowlist (`unknown binding`). If a deployment ever needs true model-direct rejection, the mechanisms are a visibility-layer `restrict()` (rejected here for ordering hazards) or a `code`-mode collapse — both are deployment-level decisions, not mask-level ones.
+- Zero upstream mutation means zero interference with host-plane modules that enumerate or interact with the delegation tools.