@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/study/STUDY-0009-claude-code-reporting.md

@@ -0,0 +1,205 @@
+# STUDY-0009 — Claude Code's report structure against this harness's, phase by phase
+
+Status: **checked source and published docs; reporting contract updated by ADR-0079.** This study
+pins Claude Code v2.1.88's leaked prompt (external and internal builds) and the published
+output-styles page against the Harness reporting section before ADR-0079 (3,696 characters). It
+extends
+[STUDY-0006](STUDY-0006-reporting-prompts.md), which measured the reporting rewrite, and
+[STUDY-0007](STUDY-0007-claude-code-prompt.md), which compared 20 prompt areas in brief. It answers
+the header question left by [ADR-0074](../decisions/ADR-0074-report-content-not-report-blocks.md) and
+[ADR-0076](../decisions/ADR-0076-codex-final-answer-verbatim.md).
+
+## The question
+
+The reporting section has been rewritten twice (15.8k → 8.9k → 3.7k characters), and replies stopped
+carrying headers. What exactly does Claude Code ask of the text outside tool calls — at each phase,
+in headers, content and length — and where does each phase line up with the current section?
+
+## Sources and method
+
+| Side | Source | What is measured |
+|---|---|---|
+| Claude Code, external build | `external/claude-code-src/src/constants/prompts.ts` (v2.1.88 source map, 2026-03-31). The text `getSystemPrompt` returns when `USER_TYPE !== 'ant'`: `# System` (`:188`), `# Tone and style` (`:430-441`), `# Output efficiency` (`:416-427`) | Everything an ordinary user's session is told about its text output |
+| Claude Code, internal build | The same file's `USER_TYPE === 'ant'` branches: `# Communicating with the user` (`:405-414`), faithful reporting (`:240`), numeric length anchors (`:534`), the feature-gated verification contract (`:394`); the subagent prompt (`:758`) and its notes (`:765-768`); the away-summary prompt (`services/awaySummary.ts:22`) | The report text Anthropic gives its own staff, which is the most explicit version of Claude Code's style |
+| Claude Code, published | [Output styles](https://code.claude.com/docs/en/output-styles), fetched 2026-11-01 | The documented Default and Concise behavior, from v2.1.237 |
+| This harness | Run `fe134053-24b3-40d0-b9a1-303d99c5140e`'s recorded pack, section `reporting`; `src/prompt/reporting.ts`; `src/prompt/standard.ts` `WRITING_STYLE` | The text a session is actually given — 3,696 characters, 18.9% of the 19,532-character pack |
+
+Measurement notes:
+
+- Character counts are measured from the source text. Quotes are verbatim; `⟨…⟩` marks a runtime
+  value. Token figures, where used, are characters ÷ 4. External-build section sizes are the
+  extracted-section counts also used in STUDY-0006 and STUDY-0007; ant-only sizes use the same
+  method, measured here.
+- The Claude Code text comes from a leaked source map, not an Anthropic publication. The internal
+  branch is version- and build-gated, so it is evidence of Anthropic's own wording, not of what
+  external users receive. The published page is the only official source here.
+- The comparison is of instructions, not observed replies. It does not measure how often Claude Code
+  or this harness actually emits headers.
+
+## Two Claude Code builds, one published style
+
+- **The external build has no report template.** `# Output efficiency` (730 characters) and
+  `# Tone and style` (691) are the whole of its final-reply text, plus a 237-character sentence
+  saying markdown is CommonMark in a monospace renderer. There is no content list, no header rule
+  and no example.
+- **The internal build adds the only real structure.** `# Communicating with the user` (2,395
+  characters) covers the reader, in-flight updates, prose, tables and the inverted pyramid. It is
+  still not a template or a header set. Faithful reporting (641) and numeric length anchors (140)
+  sit beside it; the verification contract is behind a feature flag.
+- **The published Concise style** (v2.1.237 or later) is the documented version of the same idea:
+  "the first sentence of a response states what happened or what the answer is", no lead-in,
+  narration or closing recap, a simple question answered in one to three sentences; error reports,
+  failing test output, security warnings and destructive-action confirmations keep their complete
+  content. It is a session-level style, not the default.
+- **Explanatory, Learning and Proactive change the role**, not the report's structure.
+
+## Sizes
+
+| Text | Characters | Share of its own prompt |
+|---|---:|---:|
+| Claude Code external: `# Output efficiency` | 730 | — |
+| Claude Code external: `# Tone and style` | 691 | — |
+| Claude Code external: the markdown/CommonMark sentence | 237 | — |
+| Claude Code external report text, total | 1,658 | 12.3% of 13,532 |
+| Claude Code internal: `# Communicating with the user` | 2,395 | not measured; the internal pack was not extracted |
+| Claude Code internal: faithful-reporting bullet | 641 | — |
+| Claude Code internal: numeric length anchors | 140 | — |
+| Claude Code subagent: report sentence + notes | 403 + 434 | — |
+| Claude Code away summary | 249 | — |
+| This harness: `reporting` | 3,696 | 18.9% of 19,532 |
+| This harness: the two worked examples inside it | 767 | 20.8% of the section |
+| This harness: `reporting` + `writing` | 5,120 | 26.2% of 19,532 |
+
+The harness spends 2.2 times Claude Code's external report text and 1.5 times its internal
+`# Communicating with the user`, and the only peer text comparable in kind is the latter.
+
+## The phases, side by side
+
+The rows follow the order a person experiences the text: who reads it, the text before the first
+tool call, the updates while work runs, then the final reply from its first sentence to its last.
+
+| Phase | Claude Code, external (v2.1.88) | Claude Code, internal (ant-only) | This harness (1.5.1) |
+|---|---|---|---|
+| What the text is for | "All text you output outside of tool use is displayed to the user" (`prompts.ts:188`) | Same, plus "Assume users can't see most tool calls or thinking — only your text output" (`:406`) | "fully self-contained: users should never need to read earlier commentary updates" (`reporting.ts:5`); "Do not assume the reader will fill in missing steps" (`standard.ts:59`) |
+| Before the first tool call | Nothing | "Before your first tool call, briefly state what you're about to do" (`:406`) | Nothing; `reporting.ts:7` only forbids ending a turn to report work still possible |
+| While work runs | "Focus text output on: Decisions that need the user's input / High-level status updates at natural milestones / Errors or blockers that change the plan" (`:422-425`) | "short updates at key moments: when you find something load-bearing (a bug, a root cause), when changing direction, when you've made progress without an update" (`:406`) | "In progress updates, say what you learned, what is still uncertain, and what the next step will resolve" (`standard.ts:61`; repeated in `reporting.ts:15`) |
+| The reply's first sentence | "Lead with the answer or action, not the reasoning. Skip filler words, preamble, and unnecessary transitions. Do not restate what the user said" (`:420`); published Concise: the first sentence states what happened | "Use inverted pyramid when appropriate (leading with the action)" (`:412`); "Don't overemphasize unimportant trivia about your process or use superlatives to oversell small wins or losses" (`:412`) | "Lead with the outcome and then develop your reasoning" (`:13`); "The first line says what happened and whether it is done" (`:67`) |
+| The body of a change | No content list. Published Concise keeps "error reports, failing test output, security warnings, and confirmations for destructive actions" complete | No content list. Prose and table rules (`:410`); "if something about your reasoning or process is so important that it absolutely must be in user-facing text, save it for the end" (`:412`); faithful reporting (`:240`) | "explain what changed, why, how it was tested, and any material risks or limitations" (`:13`); shape-by-work row "outcome, what changed and why, how it was tested, risks" (`:27`); ordered by "easiest to assess" (`:15`) |
+| Evidence and honesty | Nothing beyond "include only what is necessary for the user to understand" (`:420`) | Faithful reporting, 641 characters: "if tests fail, say so with the relevant output; if you did not run a verification step, say that rather than implying it succeeded… Never claim 'all tests pass' when output shows failures… when a check did pass or a task is complete, state it plainly" (`:240`); a gated verification-agent contract (`:394`) | "Every claim carries the evidence that supports it" (`:68`); the example says "I did not open it in a browser, so the visual result is unverified" (`:50-51`); no explicit anti-false-claim sentence of its own |
+| The person's next step | "Decisions that need the user's input" (`:423`) | Same (`:423`); the away summary names "the concrete next step" and skips "status reports and commit recaps" (`awaySummary.ts:22`) | The code-change row names no next step (`:27`); the blocked-publish example gives the exact command and says "Nothing has been published" (`:59-63`) |
+| Headers | No instruction. GitHub-flavored markdown, CommonMark rendering (`:188`) | "Match responses to the task: a simple question gets a direct answer in prose, not headers and numbered sections" (`:412`); "Write user-facing text in flowing prose while eschewing fragments, excessive em dashes, symbols and notation" (`:410`); "Only use tables when appropriate" | "There is no required heading and no preferred set… A short reply needs no headings… the content decides" (`:21`); "The headings name what is under them" (`:69`); both worked examples are headingless (`:46-63`) |
+| Lists and tables | "If you can say it in one sentence, don't use three" (`:427`) | "Only use tables when appropriate; for example to hold short enumerable facts (file names, line numbers, pass/fail), or communicate quantitative data. Don't pack explanatory reasoning into table cells — explain before or after" (`:410`) | "Use tables for mappings or comparisons" (`:17`); "Write in connected prose. Use lists only when the information is genuinely parallel, sequential, or easier to compare… Use a table when several items share fields" (`:40`) |
+| Length | "Your responses should be short and concise" (`:435`); "If you can say it in one sentence, don't use three" (`:427`); published Concise: a simple question in one to three sentences | "Length limits: keep text between tool calls to ≤25 words. Keep final responses to ≤100 words unless the task requires more detail" (`:534`, ant-only) | "Scale detail to complexity: a simple change usually needs one or two sentences plus the validation, and a larger change needs the reasoning, the evidence and the risks… Never repeat the request, the plan or the previous message" (`:36`) |
+| References and formatting | `file_path:line_number` (`:436`), `owner/repo#123` (`:437`), no colon before a tool call (`:438`), no emoji (`:432`) | The same list (`:432-438`) | Markdown links to files (the pack's `working-folder` section); no line-reference, emoji or colon rule |
+| Examples and the pre-send check | None | None | Two worked examples (`:46-63`, 767 characters) and four checks: first line, evidence, headings, no repetition (`:65-70`) |
+
+## Headers, exactly
+
+Neither Claude Code build asks for a header. The external build never mentions them; its only
+formatting sentence is the CommonMark note. The internal build's single header line is a warning
+about the simple case — "a simple question gets a direct answer in prose, not headers and numbered
+sections" — and it says nothing about a longer change report. Neither provides a header vocabulary,
+and neither has an example with a header.
+
+This harness is the only side that discusses headers at all, and it does so twice: the optional rule
+("no required heading and no preferred set… A short reply needs no headings… the content decides",
+`reporting.ts:21`) and the check ("The headings name what is under them", `:69`). The check assumes
+headers when they exist; it does not ask for one. The section's two worked examples, the only full
+replies a session sees, carry none.
+
+That headerless reply did not follow a Claude Code convention; it followed the Harness's then-current
+optional rule and headingless examples. Claude Code's nearest text is narrower: it discourages
+headers only for simple questions. ADR-0079 later changed the Harness guidance to often use
+content-named `#` / `##` headings in substantive multi-part replies.
+
+## Subagent and recap reports
+
+The same comparison at two smaller scopes:
+
+| Report | Claude Code v2.1.88 | This harness |
+|---|---|---|
+| A subagent's final message | "respond with a concise report covering what was done and any key findings — the caller will relay this to the user, so it only needs the essentials" (`prompts.ts:758`, 403 characters); absolute paths, snippets only when the exact text is load-bearing, no recap of code merely read (`:768`, 434) | No child-specific rule. The `subagents` section (1,288 characters) ends "You own integration, verification and the user-facing report", which tells the parent where the report belongs, not what a child returns. Every pack carries the reporting section (`compile.ts:461`), and a recorded child run's pack does contain it, so a child is given the person-facing report text for a message the parent relays |
+| A "while you were away" recap | "Write exactly 1-3 short sentences. Start by stating the high-level task… Next: the concrete next step. Skip status reports and commit recaps" (`awaySummary.ts:22`, 249 characters) | No recap surface; the progress-update rule shared by `writing` and `reporting` is the nearest text |
+
+Claude Code gives each scope its own small contract. The harness relies on one section for every
+scope, which is consistent but leaves the subagent case unstated.
+
+## What the phases show
+
+- **Both sides put the answer first and ban preamble.** Claude Code: "Lead with the answer or
+  action" and "Do not restate what the user said". The harness: "Lead with the outcome", "The first
+  line says what happened", "Nothing is repeated from the request or the plan". This is the one
+  phase where the two texts agree almost word for word.
+- **Only the harness lists the contents of a change.** Claude Code external has no content list at
+  all; its internal build gives prose and table rules, not questions to answer. The harness's four
+  questions (what changed, why, how it was tested, risks) are its own invention, and its shape-by-work
+  table is the nearest thing either side has to a template.
+- **The harness's evidence rule is structural, Claude Code's is moral.** The harness requires a
+  claim to carry evidence but never says "never claim tests pass when they fail"; Claude Code
+  internal says exactly that, at 641 characters, and keeps the "state a pass plainly too" half.
+  Claude Code external has neither.
+- **The next step is weaker on both sides than it looks.** Claude Code's main prompt only names
+  decisions that need input; its concrete next step lives in the away summary. The harness dropped
+  the next-step block in ADR-0074 and now shows a next step only in the blocked-publish example.
+- **Progress updates are a separate phase in Claude Code and a duplicate in the harness.** Claude
+  Code's internal text puts the before-first-call line and the in-flight updates in the same section
+  as the final reply but treats them as separate moments. The harness carries the same
+  progress-update rule in both `writing` and `reporting` (a 113-character sentence), so the
+  reporting section spends text on a phase that is not the report.
+- **Length is the only place Claude Code is more precise.** The internal build's numbers (≤25 words
+  between tool calls, ≤100 words final) are a research-backed anchor that the harness lacks; the
+  comment beside them says ~1.2% output-token reduction against a qualitative "be concise", with
+  quality impact unmeasured. The harness substitutes work-type guidance and no numbers.
+- **The reader test is the one criterion Claude Code has and the harness lacks.** "Assume the person
+  has stepped away and lost the thread… Write so they can pick back up cold… Err on the side of more
+  explanation. Attend to cues about the user's level of expertise" (`:408`) is a check the harness's
+  "plain language over jargon" and "colleague" voice do not state.
+
+## What this supports
+
+1. **Headers are a house-style choice, not a peer default.** If substantial reports should carry
+   them, the section has to say so; before ADR-0079 it did not. The accepted guidance now often uses
+   content-named `#` / `##` headings for substantive multi-part replies, without a line-count floor,
+   fixed vocabulary or mandatory template.
+2. **Add the reader test, not a template.** Claude Code's "pick back up cold / match expertise"
+   wording fits the harness's existing "colleague" voice and costs ~150 characters. It addresses
+   the same problem as the examples without prescribing sections.
+3. **Restore an explicit honesty line.** The harness's strongest evidence rule is now an example;
+   Claude Code keeps 641 characters on faithful reporting in its internal build. A single sentence
+   ("If you did not run a check, say so; do not claim a check passed when it did not") closes the
+   gap without restoring ADR-0074's blocks.
+4. **Keep progress updates out of `reporting`.** The sentence is already in `writing`; removing the
+   duplicate keeps each phase in one place, as Claude Code does.
+5. **Do not adopt numeric word caps without a measured trial.** The only evidence is ant-only and
+   reports a token saving with unmeasured quality impact; the harness's work-type guidance is the
+   more conservative choice.
+6. **Give a child run its own report sentence.** ADR-0079 adds a concise caller-facing contract,
+   including useful paths and evidence, and omits a recap of code merely read.
+6. **Give a child run its own report sentence.** Claude Code's 403-character subagent contract
+   (essentials only, relayed by the caller) plus its 434-character notes matches what a child
+   actually returns; the harness gives children the person-facing section instead, and the parent is
+   told it owns the user-facing report. A one-line child section, or a scope field on the reporting
+   section, closes the gap.
+
+## Limits
+
+- Claude Code v2.1.88 is a leaked source map, not a publication. The internal `# Communicating with
+  the user` text is gated behind Anthropic's own build, so it may be experimental and is not what
+  external users receive. The published Concise style is documented only from v2.1.237, a later
+  build that was not read here.
+- This compares instructions, not replies: neither side's actual header frequency is measured.
+- The internal build's total prompt size was not extracted, so its sections' shares are not given;
+  the verification-agent contract is feature-gated and was not measured.
+- The harness numbers are one recorded pack (this session, 19,532 characters), captured before
+  ADR-0079. At the time, the captured reporting text matched the installed build and working tree.
+
+## Sources
+
+- `external/claude-code-src/src/constants/prompts.ts` — `# System` (`:188`), faithful reporting
+  (`:240`), `# Communicating with the user` (`:405-414`), `# Output efficiency` (`:416-427`),
+  `# Tone and style` (`:430-441`), numeric anchors (`:534`), subagent prompt (`:758`, `:765-768`).
+- `external/claude-code-src/src/services/awaySummary.ts:22` — the away-summary prompt.
+- [Claude Code: Output styles](https://code.claude.com/docs/en/output-styles), fetched 2026-11-01.
+- This harness: [src/prompt/reporting.ts](../../src/prompt/reporting.ts),
+  [src/prompt/standard.ts](../../src/prompt/standard.ts), and the recorded pack of run
+  `fe134053-24b3-40d0-b9a1-303d99c5140e` (`context.json`).

package/docs/study/arms/00-matrix.md

@@ -0,0 +1,20 @@
+# Wide comparison matrix
+
+One row per source per arm; ≤12 words per cell, verbs first. Detail and
+citations live in the arm docs; this page is an index, not the analysis.
+
+| Arm | this harness | opencode | omp (pi fork) | dsh | harness² | swe-agent | openhands SDK | kimi-cli | smolagents | claude-code |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 01 prompt | compile.ts only; stable prefix + hidden context updates | template + deltas appended to history | parallel compiler; two-block cache; static invariant | ordered per-step sections + user snapshot | tree IS prompt, capped always-on | yaml config templates | pending | pending | step-log replay | CLAUDE.md hierarchy (pending) |
+| 02 tools | providers + per-call gate; `{product}` | Effect plugins, codemode, MCP names | 30 rich builtin tools, tiers | defineTool registry, PTC mode | editable c4 guidance | YAML string bundles | pending | kosong abstract layer (archived) | code actions, @tool | descriptions answer how (pending) |
+| 03 subagents | fresh run children + delivery receipts | subagent tool, fresh sessions, description route | task tool, worktree isolation, speculative | spawn/fork service, continuable | c5 own-context text agents | runs only | per-container opens | pending | none in-source | agents files (pending) |
+| 04 skills | c6 tree skills, trust-gated loader | depth-6 scan, skill lazy-load | manage_skill; memory writes skills | durable capped catalog + skill tool | trigger lines validated | procedures via bundles | microagents (pending) | klips dir | prompt templates | SKILL.md (pending) |
+| 05 context | context message + budgets | compaction agent, fixed template, verbatim tail | method ladder, snapcompact deterministic | formula trigger, prune first, FTS5 query | replica-era limits, trim-to-pay | bounded single shots | condensers pending | pending | full replay memory | auto-compact (pending) |
+| 06 memory | wiki notes on file writes; guarded refine lane | none visible | 5 backends, two-phase consolidation, MEMORY.md | durability only: spill/todo/deliverables | per-domain experience library | none | pending | pending | step log | memory files (pending) |
+| 07 governance | gate last; standing + single-use | per-leaf asserts, always/deny/ask | tier×policy, fails closed | pre-execute pipeline + guard | substrate-dependent | curated blocklists | confirmation policy | archived | executor = gate | permission modes (pending) |
+| 08 execution | account-isolated sessions; host PTY | shell tool + separate pty daemon | in-process rust unix env | sandbox classes + single executor | substrate workspace | container env | workspace containers | kaos (archived) | intercepted exec | desktop app (pending) |
+| 09 observability | runStore-only validated events | bus + UsageRecorded | stats dashboard + ledgers | OTel transport only, FEEDBACK_ONLY | runmark + reports | trajectories + inspector | event stream | klips vis | monitor.py | sentry optional |
+| 10 refinement | ported harness² core (arm 10) | none | autoresearch hillclimb loop | none found | editor→probe→compose + reflector | IC design lessons | none found | archived | none | plan mode only |
+
+Fill rule for later passes: replace `pending` from each source note's audit;
+mark archived designs and reference the note.

package/docs/study/arms/01-system-prompt.md

@@ -0,0 +1,211 @@
+# Arm 01 — System prompt / context assembly
+
+Status: **core four audited** (opencode, omp, dsh, harness²); swe-agent,
+openhands, kimi-cli, smolagents, claude-code pending.
+Sources audited by explorer agents with citations; my own spot-checks marked.
+
+Shape: design space → per-source comparison → trade-offs → adoption candidates.
+
+## 1. Design space
+
+Where the model's instructions come from when a session starts, and how they
+evolve mid-session. Sub-decisions:
+
+1. **Assembly location** — one compiler, a grid-like assembler, or a template
+   engine? Who is *allowed* to contribute (core only, plugins, file discovery)?
+2. **Static vs dynamic** — what is identical across calls of a session (or across
+   sessions, for cross-session cache) vs what must be refreshed; and *where* each
+   is injected (system message at node 0, later system messages, user messages
+   after history, synthetic messages inside history).
+3. **Reach of instructions** — always-on prose vs skills vs hooks vs scripts;
+   caps and budget language.
+4. **Cache discipline** — prefix stability, cache breakpoints, proactive
+   warming, append-only updates.
+5. **Editability/versioning** — how the tree of instruction files is versioned
+   or validated (this harness: never edit, only supersede).
+
+## 2. Comparison
+
+### this harness (reference point)
+
+- The prompt is assembled only in `src/prompt/compile.ts`; sessions launch with a
+  stable system prefix plus a hidden `xingular-context` message appended to
+  native history for changing state (repo rules; `AGENTS.md`). Tree sections
+  c1–c8 are versioned; c1–c4 always-on and capped/validated (`tree/tree.ts`);
+  a version is never edited, only superseded (`tree/store.ts`).
+
+### opencode — compiler + instruction deltas
+
+- Small text template with a tool-guidance placeholder, rendered per tool list
+  (`external/opencode/packages/core/src/session/system-prompt.ts:9-27`; the
+  template is `session/runner/prompt/system.txt`).
+- Per-step transcript: system = agent template **plus an instruction baseline as
+  a second system part**; messages = history (`.../session/model-request.ts:99-119`).
+- Instruction sources composed in a fixed order (codemode catalog, MCP,
+  references, skills, AGENTS.md discovery, builtins, API entries) with a comment
+  stating the order keeps "a reusable prompt-cache prefix"
+  (`.../session/context.ts:137-166`, comment at 152-154).
+- Dynamic updates are **appended as system messages after history, before the
+  new user prompt**: AGENTS.md changes render as a unidiff patch or a full
+  rewrite; date/env/codeMode changes likewise (`.../session/generate.ts:53-57`,
+  `.../session/instruction-discovery.ts:127-149`, `.../session/builtins.ts:30-52`).
+- Discovery: global file, ancestor walk, configured globs/URLs, watcher-driven
+  reload; **no size caps found** in the discovered files (auditor: unverified
+  beyond those files) (`.../config/plugin/instruction.ts:51-62,143-225`).
+- On-demand AGENTS.md: the `read` tool injects ancestors as synthetic history
+  messages deduped by metadata (`.../tool/plugin/read.ts:82-104` →
+  `.../session/instructions.ts:74-79`).
+- Cache hygiene: stable `promptCacheKey` from session affinity
+  (`.../model-request.ts:294-295`), tool definitions kept on the final step to
+  preserve the prefix (`.../runner/llm.ts:237`), prefix-stable image elision
+  (`.../model-request.ts:199-207`).
+- Plugins get a per-request hook over `system`, `messages`, `tools`, `options`,
+  with tool-identity matching to prevent hook-invented tools
+  (`.../model-request.ts:236-320`, `packages/plugin/src/effect/session.ts:25-36`).
+
+### omp (oh-my-pi) — parallel compiler with deadlines, two-block cache
+
+- `buildSystemPrompt` fans out **timed, parallel** preparation (project context
+  files, skills, workspace tree, active-repo context, personality; each with a
+  deadline fallback) (`external/omp/packages/coding-agent/src/system-prompt.ts:630,723-848,954-1009`).
+- All prompt text lives in `.md` Handlebars templates, imported `{type:"text"}` —
+  repo rule "Prompts never in code"
+  (`.../system-prompt.ts:24-31`, `.../prompts/system/system-prompt.md`).
+- **Stable prefix is a separate entry**: the default body renders as block 0;
+  `<project-context>` is appended as a *second prompt entry* so the static
+  prefix is shared across directories — with the comment that the Anthropic head
+  cache breakpoint lands right before it (`.../system-prompt.ts:1026-1036`).
+- **Volatile content (date/cwd) was deliberately moved out of the system
+  prompt** because it "invalidated the whole tool array"; now injected onto the
+  first user turn per request, append-only, with a synthetic developer turn when
+  no new user turn exists (`.../session/date-cwd-reminder.ts:1-11,50-129`;
+  wired at `.../sdk.ts:4333-4340`).
+  **Verified in person**: `.../date-cwd-reminder.ts:1-12` — header comment states
+  the reason (open-weight chat templates render tool schemas *after* system
+  content, so a volatile tail invalidates the whole tool array), and lines 44-48
+  guarantee append-only injection: changed values attach to a newly appended
+  user turn, leaving every earlier message byte-identical.
+- Instructions arrive via a **capability API**, not hard-coding:
+  `contextFileCapability` (project AGENTS.md family with dedupe), `systemPromptCapability`
+  (SYSTEM.md override), `instructionCapability` — extensions add content through
+  named slots (`.../capability/context-file.ts:26-56`,
+  `.../capability/system-prompt.ts:31`).
+- Cache: `CacheWarmer` replays requests at ~90% of cache lifetime when savings
+  clear a floor (`.../session/cache-warmer.ts:1-17`); per-component token
+  usage breakdown (`systemPromptTokens`, `skillsTokens`, …,
+  `.../session/agent-session-types.ts:529-535`); truncating MCP server
+  instructions invalidates the tools cache breakpoint (`.../sdk.ts:1374-1375`).
+- `metaharness` is **not** runtime prompt machinery: it is their benchmark
+  manager (Harbor/SnapCompact experiments over one SQLite store; runner note at
+  `.../packages/metaharness/src/runner.ts:1257-1258`). Their word "harness" in
+  `metaharness` = a harness around the harness, for measurement.
+
+### deepseek-harness (dsh) — ordered sections, snapshot-as-user-message
+
+- Own package `packages/core/system-prompt`; assembled **per step** via an
+  ordered "waterfall" of sections/context entries
+  (`external/deepseek-harness/packages/core/system-prompt/src/index.ts:429,677-680`,
+  `.../agent-loop/src/agent.ts:272,407`).
+- **Plugin contribution contract**: `ctx.systemPrompt.section()`, `.context()`,
+  `.tools(provider)`, `.variable(name, provider)` — sections are sorted by
+  numeric `order` then name, duplicates throw, scoped entries shadow globals,
+  and a `complete: true` section replaces everything else
+  (`.../system-prompt/src/index.ts:53-76,131-179,478-570,653-686`; shadowing
+  tested in `.../system-prompt/tests/scoped.spec.ts:33`).
+- Static = section text at node 0 (identity fixed in code, `index.ts:449-466`);
+  dynamic facts (cwd, sandbox policy, time, plan) are `PromptContext` entries,
+  re-resolved per request and appended as a **durable user-role message**
+  headed "Current runtime context. This snapshot supersedes earlier…"
+  (`.../index.ts:314-318,582-602`, `.../agent-loop/src/agent.ts:411,429-440`).
+- Workspace instructions also inject into history as sourced `user/message`
+  events, not system text (`.../packages/context/agent-instructions/README.md:88-103,158-186`).
+- Tool ordering is part of prompt assembly: providers' tools are `structuredClone`d
+  and ordered by configured `toolOrder` with an `<unlisted-tools>` rest marker
+  (`.../system-prompt/src/index.ts:208-240,633-651,674`).
+- Token metering as a service with fixed-density estimates
+  (`.../packages/llm/token-meter/src/index.ts:4-35`, `estimate.ts:16-27`).
+
+### harness² — the tree is the prompt; caps and economics
+
+- Their editable tree per substrate (here for opencode): `systemprompt.md` (c1),
+  always-on files with caps, skills loaded on demand, subagents in own context,
+  scripts, and a plugin acting inside the tool loop
+  (`external/harness2/harness2/core/prompts.py:424-453`).
+- Always-on prose is framed as an **output-budget** cost: "ALWAYS-ON PROSE IS THE
+  EXPENSIVE OPTION… the most costly failure on this work is a run that reasons
+  until the budget is gone and produces nothing" (`.../prompts.py:129-146,455-458`).
+- Validation discards a whole harness for: a skill without a trigger line naming
+  it in always-on text; template braces in always-on text (Jinja StrictUndefined);
+  a named script that is missing (`.../prompts.py:148-167`,
+  `.../core/tree.py:15-21` — caps, frontmatter rules per `SurfaceSpec`).
+- Notably, their opencode-surface table labels components **c1–c8** — the same
+  eight-component numbering this harness uses (`.../prompts.py:424-431`). Both
+  projects have converged on the same tree taxonomy; treat as confirmation of
+  shape, not shared code.
+- Instruction-bearing text is data, not branches: "Benchmark text arrives as
+  values, never as branches" (`.../prompts.py:15-20`) — prompt templates are
+  parameterized by a `BenchPrompts` value, and each new benchmark gets slots,
+  not edits. Answer-free framing is literally part of the prompt
+  (`ANSWER_FREE`, `.../prompts.py:38-44`).
+
+### claude-code (from public material, no clone) — pending
+
+CLAUDE.md hierarchy + `@` imports + `#` quick-memory; tool descriptions as the
+home of usage guidance. To be filled with dated citations.
+
+### swe-agent / openhands / kimi-cli / smolagents — pending
+
+## 3. Trade-offs
+
+- **Stable prefix vs fresh state.** Everyone converges on stable static +
+  appended dynamic. Two designs for the dynamic: (a) appended *system* messages
+  rendering deltas (opencode), (b) appended *user-role* context snapshot whose
+  text supersedes earlier ones (dsh). (a) is precise (a unidiff names what
+  changed); (b) is simpler and carries whole state per turn, at the cost of
+  re-sending unchanged facts.
+- **Where volatile values live.** omp's lesson is the strongest: even one line
+  of date/cwd inside the system prompt invalidates far more than itself (it
+  invalidated the whole tool-array cache). Moving it into the user turn costs a
+  message but saves the prefix. dsh's snapshot approach (user message) has the
+  same property w.r.t. the system node.
+- **Who may contribute.** Ordered, deterministic contribution with declared
+  order + name ties (dsh) vs deployment-order composition with a cache comment
+  (opencode) vs capability slots with dedupe (omp). The deterministic-order end
+  is friendlier to caching and to reasoning about plugins; the discovery end is
+  friendlier to "just drop a file in the repo" workflows but needs watcher-driven
+  reload and dedupe, and risks unbounded size (opencode has no caps).
+- **Economics of always-on text.** harness² puts the sharpest numbers-language on
+  it: always-on prose competes with output budget; prefer on-demand forms. This
+  matches this harness's capped c1–c4, with the difference that harness² enforces
+  the "cut to pay" rule by validation and this harness by editor review.
+- **Templates in code vs files.** omp keeps every word of prompt text in `.md`
+  templates; harness² inlines exact prompts as Python constants but keeps
+  benchmark text as values; dsh fixes identity prose in the constructor. Pure
+  style until a person wants to review/audit prompt diffs — then files win
+  (reviewable without code knowledge).
+
+## 4. Adoption candidates (Tier 1 unless noted)
+
+| # | Idea | From | Land as | Notes |
+|---|---|---|---|---|
+| A1 | Move volatile date/cwd out of the stable prefix into the first user turn (or the appended context message) | omp `date-cwd-reminder.ts` | prompt sections change in `src/prompt/compile.ts` | **verify our current placement first**; high cache value if our prefix carries date |
+| A2 | Named, ordered prompt sections with deterministic order-name ties and duplicate-name rejection; scoped shadowing | dsh `system-prompt` contract | a rule inside plugin prompt sections (existing surface) | makes section ordering a contract instead of an implementation detail |
+| A3 | Render instruction deltas as unidiff-style "what changed" text in the appended context message | opencode `instruction-state.ts` | the `xingular-context` hidden message mechanism | our channel exists; this is a rendering upgrade |
+| A4 | Proactive cache warming near the provider's cache TTL | omp `cache-warmer.ts` | *not* a harness surface — host/app concern | Tier 2; needs measurement harness first (`probe-chat-cache-app.py` in the App) |
+| A5 | Memory/prompts in reviewable template files rather than inline strings | omp rule | none now — style guidance for future prompt text | Tier 2, low cost, no behavior change |
+
+Carry later: opencode's "no caps on discovered instructions" as an anti-pattern to
+contrast with c1–c4 caps; harness²'s three discard rules (trigger line, no
+template braces, shipped scripts) when tree validation is next touched (arm 04).
+Also carry:
+- **Model-conditioned policy as data.** omp forbids model-conditional branching in
+  code entirely — no `id.includes("claude")`; all model/provider policy lives in a
+  declarative KDL rule tree compiled to `rules.json`
+  (`external/omp/AGENTS.md` — "Model/Provider Policy Lives in KDL"). opencode
+  instead ships per-model prompt adjustments as *plugins*
+  (`external/opencode/packages/plugin/plugin/optimize.ts:16-86` — confirmed by
+  explorer audit). Same problem (per-model prompt/policy deltas), two answers:
+  data tables vs evaluated plugins.
+- omp's **judge-questions convention** — per-feature JSON mapping question ids →
+  `{instructions, criteria?}` — is source material for arm 10 (refinement) and
+  its answer-free selector.

package/docs/study/arms/02-tools.md

@@ -0,0 +1,79 @@
+# Arm 02 — Tools
+
+Status: **core four audited** (opencode, omp, dsh + harness²/tree, smolagents,
+swe-agent in person); kimi-cli archived; claude-code openhands pending.
+
+## Design space
+
+How tools are declared (interface & schema origin), described (who writes the
+model-facing guidance), provided (core vs provider vs plugin vs MCP), named and
+ordered (namespacing, `toolOrder`), gated (tier/policy/event pipeline), and
+whether tools are JSON calls at all — or the model writes code that calls them
+(codemode / PTC / CodeAct).
+
+## 1. Comparison
+
+| Source | Declaration | Gating | Calls |
+|---|---|---|---|
+| this harness | provider extension points; `describeTool` fills `{product}`; definitions in `src/tools/definitions.ts`, dispatch in `src/tools/dispatch.ts` | per-call gate, last extension to see a call | JSON + limited code tool |
+| opencode | internal Effect plugins registering via `ctx.tool.transform(editor.add)`; `Tool.Info{input,execute,output,options{namespace,permission,codemode,pinned}}` | per-leaf `Permission.assert` (`allow\|deny\|ask`, `findLast` wildcard match, default ask; agent rules∪session; missing agent denies) | JSON by default, `codemode:true` folds tools into a code catalog |
+| omp | 30 builtins; rich `AgentTool` (approval tier read\|write\|exec, loadMode, docTopics, per-call concurrency, speculation) | tier × per-tool policy `allow\|deny\|prompt`, modes `always-ask\|write\|yolo`; **fails closed** | JSON; speculative pre-dispatch |
+| dsh | `defineTool` into `ctx.tools`; ToolRuntime self-feeds the system prompt via `.tools(provider)` | fixed pipeline `pre-execute(allow/deny/ask) → ctx.tools.guard() → execute → post-execute → result` | `mode: native` (all schemas) vs `ptc` (model sees only `run_code` + SDK) |
+| harness² | tools = part of the editable tree, c4 tool guidance prose | whatever the agent's substrate does | JSON (substrate tools) |
+| swe-agent | YAML bundles: `signature`/`docstring`/arguments; string parsing; `state_command` for interface state | curated blocklists in bundles | text commands into a stateful shell |
+| smolagents | `@tool` decorated functions, schema from type hints, validated at init | none in-source (executor sandbox is the gate) | **code actions**; MCP tools bridged into code |
+| kimi-cli | kosong async tool-orchestration abstraction (archived) | — | JSON |
+
+Citations: opencode `external/opencode/packages/core/src/tool/plugin/subagent.ts:100-107`,
+`.../tool.ts:161-291,233,293-296`, `.../permission.ts:87-97,158-172`,
+`.../tool/runtime.ts:276-281`, `.../tool/mcp.ts:20-21,52-75`;
+omp `external/omp/packages/agent/src/types.ts:1129-1243`,
+`.../tools/approval.ts:17-18,53-84,100`, `.../tools/builtin-names.ts:1-36`;
+dsh `external/deepseek-harness/packages/core/tools/README.md:30-109`,
+`.../core/tools/src/index.ts:608-612,857,1513-1527`,
+`.../core/system-prompt/README.md:50-52`; swe-agent
+`external/swe-agent/tools/windowed/config.yaml:1-40`; smolagents
+`external/smolagents/src/smolagents/tools.py` (init validation),
+`.../tool_validation.py`.
+
+Instruction-bearing descriptions: opencode embeds whole prose instructions in
+tool descriptions, e.g. the never-poll rule for subagents
+(`.../tool/plugin/subagent.ts:44-47`) and todo's full-file description imported
+verbatim (`.../tool/todowrite.txt`, `.../tool/plugin/todo.ts:12`) — matching
+the claude-code school. omp instead renders descriptions from static `.md`
+templates (`.../tools/read.ts:975-996`; "prompts never in code"). dsh's `ptc`
+moves *all* tool knowledge out of schemas into a generated SDK plus
+`executionInstructions` (`.../core/tools/README.md:68-81`).
+
+## 2. Trade-offs
+
+- **Tool descriptions = prime instruction real estate.** Every source pushes how-to
+  into descriptions; the divergence is *where the text lives*: inline strings
+  (opencode), md templates (omp, self-documenting diffs), schema-erased SDKs (dsh
+  ptc). md templates are cheapest to audit; inline is cheapest to write.
+- **Gate taxonomies.** omp's declared tier × policy is the most legible to users;
+  opencode's per-leaf asserts are the most composable (plugins wrap calls);
+  dsh's pipeline events generalize hooks at the cost of indirection. All three
+  (and ours) converge on `ask` as a first-class outcome that surfaces to a person.
+- **`toolOrder`/namespacing.** dsh validates order config at assembly with a
+  reserved rest margin; opencode mints `server_tool` names with dotted→underscore
+  namespaces; omp caps length at 64. Namespacing rules should be one place; ours
+  has MCP namespaces via the harness's own MCP integration — worth a contract
+  test, not new machinery.
+- **Code-as-action in three strengths.** Full CodeAct (smolagents), opt-out
+  codemode (opencode), mode-switched PTC with SDK (dsh). All reduce schema token
+  cost and multi-call latency, all concentrate risk into the executor. For this
+  harness the gate is per-call and synchronous — free-form code actions are a
+  deliberate non-goal, but `codemode`-style *internal* catalogs remain open
+  behind existing tool providers.
+
+## 3. Adoption candidates
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| A1 | Per-tool **approval tier declaration** (read/write/exec) on the harness ToolSpec; gate consults it when policy is silent | omp `AgentTool.approval` | `ToolPolicy` surface + `src/tools/types.ts` | T1 |
+| A2 | Tool **descriptions from template files** rendered per `{product}` (`.md` in repo, imported `type:"text"`) instead of inline string literals in tool definitions | omp | tool definitions (`src/tools/*`) | T1 |
+| A3 | `toolOrder`-style validated ordering when a caller pins an explicit tool set (fail loudly on unknowns/missing rest-marker) | dsh | capability freezing at `sessions.run` | T2 |
+| A4 | Restrict allow/deny masks scoped to a subexpression that intersect and lift on dispose | dsh `ctx.tools.restrict` | child-run capability narrowing (`capabilities.intersect` already does this — verify equivalence before adding) | T2 verify-first |
+
+Anti-candidates: open-ended code-as-action for model-driven tools (gate model);
+moving gating into per-tool hooks (gate stays the final authority layer).

package/docs/study/arms/03-subagents.md

@@ -0,0 +1,90 @@
+# Arm 03 — Subagents
+
+Status: **core four audited** (opencode, omp, dsh, plus our ADR-0003 lineage);
+openhands/claude-code pending.
+
+## Design space
+
+Spawn model (tool vs scheduler vs server), child context (fresh, forked, or
+continuable), isolation primitives (separate session, separate history, own
+worktree/capabilities), delivery (block vs background + receipts), routing
+(manual naming vs description-based auto-selection), and depth/capacity limits.
+
+## Comparison
+
+**this harness.** `spawn_subagent` + `wait_subagents` tools
+(`src/tools/spawnSubagent.ts`): child is "a fresh child run for independent
+work… no conversation history and no more capabilities than you"; spawn returns
+the child run id immediately; results arrive **automatically before you finish**
+(native-history delivery receipts per ADR-0003); 24k per-report cap
+(`spawnSubagent.ts` `reported()`); depth limits live in
+`src/sessions/subagents.ts` (exported constants). Architectural statement:
+Architectural statement:
+opaque-run children (runStore writes, opaque ids).
+
+**opencode — subagent is a tool, not a scheduler.** Agents registry
+(`mode: primary|subagent`) with selectability excluding subagents from direct
+conversation (`.../core/src/agent.ts:74-75`). The `subagent` tool rejects
+primaries/unknowns, enforces depth via config, asserts permission, then creates
+a child session and prompts it "You are a subagent spawned by another session."
+— **fresh context, nothing inherited** (`.../tool/plugin/subagent.ts:129-218`).
+Foreground variant blocks and wraps the final text in
+`<subagent sessionID=… state="completed">`; background replies immediately with
+an explicit **never-poll instruction** and completion notification
+(`.../subagent.ts:19-27,229-265`). **Routing is description-based**: a context
+hook appends "Available subagents:" with each agent's own description to the
+tool description (`.../subagent.ts:282-309`).
+
+**omp — spawn machinery with isolation budgets.** The `task` tool; agent
+definitions from bundled + `~/.omp/agent/agents/*.md` + `.omp/agents/*.md`
+(`.../task/index.ts:4-10`). `SpawnRun` holds a semaphore permit and streams
+progress; the owner adopts binding abort signal/sinks
+(`.../task/spawn-run.ts:47-88`). **Speculative launch starts the child while
+the `tasks[]` argument is still streaming** (`.../task/speculative-launch.ts`).
+Isolation: pinned settings, advisor forced off, **mid-turn compaction forced on
+(whole assignment is one turn)**, isolated runs get their own **worktree** and
+may not expose roots outside it (`.../task/executor.ts:1132,4033-4055,4339`).
+Structured children get `yield` to stream partial results
+(`docs/task-agent-discovery.md:38`).
+
+**dsh — services + backends, two child topologies.** `ctx.subagents` +
+provider backends (local, ACP, Codex, Claude DSH-SDK) + a tool plugin
+(`.../packages/subagent/README.md:27-35`). Spawn returns `started subagent
+<childId>` immediately; a completion notice delivery later
+(`.../tool-subagent/README.md:59`). `spawn` = fresh child; **`fork` = seeded
+from the parent's completed history** (`.../subagent/README.md:28-29` — the one
+source with tree-history in context children). Local children **continue
+accepting messages** (cold-resume); external backends "execute once"
+(`:12,61`). Defaults: 8 active, depth 1 (`.../subagent/README.md:53,49`).
+The model names presets from an enum allowlist; **no description routing**
+(`.../tool-subagent/README.md:52,68`).
+
+**openhands (pending)** conversation-per-container REST server;
+**claude-code (pending)** `.claude/agents/*.md` description routing.
+
+## Trade-offs
+
+- **Receipts vs block.** Ours receipts-then-auto-deliver; opencode's
+  foreground blocks and the background variant needs a no-poll instruction to
+  stop wasted loops — our "results arrive automatically" tool description does
+  the same thing natively. block variants pay latency, buy simplicity.
+- **What the child sees.** Everyone defaults fresh. dsh's `fork` (parent history
+  as seed) is the only in-history-inherited design — powerful for "continue in
+  the main context's condition", dangerous for either prosecution
+  side-venting or slow joins; ours rejects it by `"no more capabilities than
+  you"` + fresh-run rule.
+- **Isolation granularity.** worktree (omp isolated runs) is the strongest
+  world-isolation; ours ties isolation to account and run records instead. The
+  `tools` CSV narrowing idea maps to our `capabilities.intersect` — same
+  primitive, different vocabulary.
+- **Routing.** Description-based auto-pick (opencode, and claude-code's docs)
+  puts all selection power in the model's reading; ours requires named briefs
+  and a Directory when names exist, which matches the opaque-id
+  contract (no names in the harness; names arrive via Directory).
+
+## Adoption candidates
+
+| # | Idea | From | Land as | Tier |
+|---|---|---|---|---|
+| S1 | Inject capability-set summaries (slots "Current subagents") into the tool description **when names exist via Directory**, instead of static description | opencode context hook | tool provider building the spawn tool's description | T2 (only if app supplies names) |
+| S2 | Receipt text carries child tool limits next to the 24k cap (`reported()` already does this only implicitly; make the receipt self-describing) | ours (deficiency) | `spawnSubagent.ts` | T1 |