# In-Band Internal Messaging: Directives, Parsing, Exec Surface

> **Status: Final** — accepted by the owner on 2026-10-06
> ("i accept the scope contract, mark it Final").

> **Box is the main surface.** All operator work goes through Box
> (box.muse-dev.online). The web UI, `box` CLI, and agents share the same
> API endpoints. No UI-only powers.

## Background (researched facts, not decisions)

- Agents receive timer/job DMs wrapped by `bin/prompt_envelope.py` (`wrap()`),
  currently advertising `[TOOL swarm.spawn]`, `[TOOL cron.create]`,(tmux
  worker pointer, `[RESULT]` verdict rule.
- Agents reply with in-band directives. `bin/response-harvester.py`
  `parse_tool_calls()` extracts `[TOOL op {json}]` / `[EXEC …]`, fenced
  ```box|tool|exec blocks, and curl-to-/exec payloads; each call runs through
  the `exec-constrained` HTTPS daemon (`op` allowlist + per-op
  validate/build) and the result is posted back into the originating thread.
- Implemented this session, uncommitted: balanced-brace JSON scanning (no
  more first-`]` truncation), `[DM {…}]` shorthand for `dm.send`, new
  `box.exec` (read-only box-ctl actions) and `tools.list` (dynamic op
  discovery) ops, native aliases (`dm`, `box`, `tools`, …), expanded
  envelope/tool-hint verb lists, `tests/test_tool_calls.py` (38 tests).
- Related specs: `docs/DM_SPEC.md` (WO + logging layer), `docs/DM_SPEC.md`
  (control plane), `docs/JOB-SPEC.md` (scheduler/distributor),
  `CHAT_POLICY.md` (sidechat-first).

## Scope contract (accepted)

- Artifact boundary: this record covers directive syntax/parsing
  (`[TOOL]`/`[EXEC]`/`[DM]`, fenced blocks), the exec op surface
  (`box.exec`, `tools.list`, native aliases), and timer-message/envelope
  content. Out of scope: gateway/browser transport, swarm worker
  reliability and the failed-slot backlog, new `box` CLI verbs,
  `CHAT_POLICY.md` changes.
- Done means: D1–D5 settled in writing below; owner explicitly accepts
  this record (Draft → Final). Nothing else is a completion dependency.
- Deferred stages (each needs its own interview): swarm reliability
  target, `box` CLI inspection verbs for in-band traffic.

## Decisions

| # | Decision | Status |
|---|----------|--------|
| D1 | Scope boundary = A (directives + exec surface + envelope; transport, swarm reliability, new CLI verbs, chat policy out) | settled |
| D2 | `box.exec` = read-only v1 (19 no-arg + 8 one-arg reads); side-effecting box actions stay out, dedicated ops cover writes | settled |
| D3 | `[DM …]` = strict JSON-only; bare forms without a JSON object are silently ignored | settled |
| D4 | Broken-JSON directives are skipped silently (no reply, no record) | settled |
| D5 | `tools.list` returns every op with its `side_effecting` flag; enforcement stays in per-op validation + identity permissions | settled |

## Risks / validation (to fill as decisions settle)

- Full suite: 235–244 tests (count varies run to run), 3–4 failures, all
  in `test_approvals` / `test_copy_actions`, which import only
  `approvals` / `gravity` / `muse_tui` — none of this record's modules.
  Pre-existing/environmental, unrelated to the directive changes.
  Focused suites green (38 tool-call + 32 docs/prompts tests).