knowledge_record: the tool never states its block grammar, and a malformed block writes nothing and reports success

[drewstone]

What two directors did today

Both directors of the capability-per-parameter pursuit (press c, 2026-09-15, agent-knowledge 16.0.0 under agent-runtime 0.226.0) spent turns discovering the input grammar of knowledge_record by trial. From their retained streams:

• DeepSeek V4.1 Flash: "The record silently wrote nothing. Let me test the exact file-block format with a minimal page." → "Let me brute-force the block terminator with parallel probes." → "Closer found: ---END FILE---. Now writing my real scope and stake pages."
• GLM-5.3: registered checks/20260915c-record-format-probe4.md, its fourth probe page, before its first real page.

On the previous press the DeepSeek director gave up on the tool and wrote six pages with the shell write tool under <workspace>/pages/, where no peer or successor could retrieve them (discovery-lab#766 patches the brief; this issue is the tool).

Why

The tool's whole description is Write pages into the store of this run from ---FILE: ...--- blocks. The grammar (---FILE: <path>--- newline, frontmatter and body, newline ---END FILE---) is only visible in the code that formats blocks (dist/index.js:4773), never to the model. And an input from which the parser extracts zero blocks is accepted: the call returns without an error, so the model reads "ok" and finds nothing in the store.

Ask

1. Put the grammar in the description with a one-block example, including the terminator.
2. Refuse an input that yields zero pages with an error that repeats the grammar, and refuse a block that opens without closing. Silent success on a no-op write is the defect that turns a tool problem into a research loss.

🤖 Generated with Claude Code

[drewstone]

Decisive evidence, from a live 8-hour director run (capability-per-parameter-cpp-glm-20260915c, agent-knowledge 16.0.0). 30 knowledge_record calls, all returning status: completed. The opener form predicts the outcome almost perfectly:

opener form	wrote nothing	wrote
---FILE: <path>--- (terminator on the same line)	1	15
---FILE: <path> then a newline	14	0

Every failed call returned exactly {"written":[],"warnings":[]} — success status, zero pages, zero warnings. Nothing tells the caller its block was not parsed.

The cost, measured:

• At 22:22–22:24 the director burned four calls and three throwaway probe pages discovering the same-line rule.
• It then wrote eleven pages correctly over eight hours.
• At 06:44 it drifted back to the newline form while recording its headline result, 20260915c-e1-specialization-fleet-refuted-mechanism.md, and got {"written":[]}.
• It has since spent twelve more calls and seven probe pages (probe5 … probe11-nofm, probe8-table, probe9-posttable) re-bisecting the grammar it had already found, and has fallen back to writing its results into its local workspace where no peer or successor can retrieve them.

The director's own reading of the situation, from its retained stream, is the part that matters: "Reads fine, writes rejected — falling back to local workspace pages while retrying the store periodically." It concluded the store was rejecting writes. The store was accepting the call and discarding the payload. An agent cannot debug a silent success, so it builds a theory about infrastructure instead, and the theory is wrong in a way that costs hours.

This is the same defect as the original report, with two additions that sharpen the ask:

1. A no-op write must be an error, not a warning-free success. {"written":[],"warnings":[]} on a non-empty proposal is the whole bug. Refuse it and name the grammar.
2. The same-line terminator is not discoverable. The tool description says "from ---FILE: ...--- blocks", which reads as naming a path followed by a fence. Two directors independently guessed the newline form first, and one of them guessed it twice, eight hours apart. One worked example in the description would have cost nothing.

Related, from the operator side: discovery-lab#766 patched the brief to say a page exists only through this tool, after a director wrote six pages to its workspace instead. That patch does not help when the tool accepts the call and drops it.

🤖 Generated with Claude Code

[drewstone]

Fixed by #213 and shipped in 17.0.2 (published 03:35:23Z). Verified against the installed package rather than the diff, replaying the two shapes from the 8-hour cpp-glm run:

same-line terminator:                 blocks=1 warnings=0 -> tool writes
newline after path (the failing form): blocks=0 warnings=0 -> tool THROWS

Both asks are met. knowledge_record now throws knowledge_record rejected the proposal without writing any pages… when blocks.length === 0 || warnings.length > 0, so the silent {"written":[],"warnings":[]} success is gone, and the tool description carries a complete worked example with the same-line terminator and ---END FILE--- instead of the one-line summary two directors had to guess at.

One note for anyone reproducing this: parseKnowledgeWriteBlocks(text) called without the allowed-prefix argument rejects an ordinary pages/... path as unsafe. The tool passes [\${pagesDirectory}/`]`. My first replay omitted it and produced a false "the working form is now rejected" reading; the prefix-correct replay above is the real behaviour.

Closing from my side. The bug outlived its fix in one place only: a director that launched before 17.0.2 holds agent-knowledge 16.0.0 in the Runtime process it started with, and a running pursuit cannot be reinstalled under. That run lost roughly three hours of store writes and fell back to workspace files — an argument for the throw landing in the tool layer, where an older caller at least sees an error, rather than only in a reader.

🤖 Generated with Claude Code