Write tools

Tools that mutate the vault. Each returns a result describing what was written. The same business rules as the CLI apply (append-only notes, auto-logged project state, the project cap).

Every write is verified

A tool result that only said “success” could not be told apart from a write that silently never landed — which over a remote connection is exactly how a lost note goes unnoticed. So every write tool re-reads its target before answering, and the result carries the evidence:

{
  "path": "journal/2026/daily/2026-08-26.md",
  "message": "Logged to journal/2026/daily/2026-08-26.md",
  "verification": {
    "verified": "content",
    "bytes_written": 412,
    "content_hash": "84bc0919e867576f",
    "appended_tail": "- **09:14**: baseline sweep finished\n"
  }
}

If the target cannot be read back, the tool returns an error rather than a success. The wording says the write is unverified, not failed: it may still have landed, so the right response is to re-read the note, not to blindly repeat the write.

The appended tail

appended_tail is scoped to the section the write targeted, not to the last bytes of the file. append_to_log and start_action both write into ## Logs, so that is the section you get back. note_to_daily writes into both ## Notes and ## Logs; its tail is the last 512 bytes of ## Notes, which end with the entry just written (the pointer line is already in the result’s log_line). (start_unplanned_action also logs, but it rewrites the project map in the same commit and so verifies as a whole-file rewrite — its appended_tail is null.)

The distinction matters because ## Logs is not always last. Cuaderno pins the effective daily template’s last ## section to the bottom of the note — for the built-in template that is ## Logs, but a custom .cuaderno/templates/daily.md ending in, say, ## Reflection keeps Reflection last and leaves the log line in the middle of the file. Reading the end of the file would then show you Reflection’s text while claiming to be the line that landed.

If the section cannot be located — an unparseable note, a ## Logs heading that is missing or duplicated — the field is null. The write is still verified by bytes_written and content_hash; only the extra evidence is withheld, because a window over the wrong bytes is worse than no window.

The content hash

content_hash is the same non-cryptographic xxh3-64 fingerprint (16 lowercase hex characters) the index uses for change detection, so a client can recompute it over a note it has read and compare. Two uses in practice:

• confirm a note is byte-identical to the one the server saw;
• notice a no-op. update_project_state with a state that already matches deliberately writes nothing and still reports success — an unchanged content_hash across two calls is how you tell.

It is a change detector, not tamper evidence: it does not defend against someone who also chooses the content.

Logging, capture, triage

When a focus is open, append_to_log, capture, note_to_daily and discard_inbox_item tag what they write with it; see The during: tag.

Evidence

Projects, actions, milestones, waiting-on

Every tool in this table takes an open project, active or parked: a parked map is a complete map, so add_action, update_project_state, the milestone and waiting-on tools, set_core_question, promote_action, complete_action, drop_action and hand_off_project write to it as it is. Never activate a parked project just to write on it; the cap is checked only when a project begins to count (activate_project, or a take-back of an active project). Only starting or picking up work (start_action, start_unplanned_action, switch_action, switch_unplanned_action, resume_action) needs an active map, as does park_project; on a parked one they return project_not_active with status: "parked" (see the rejection codes). A completed or dropped project takes none of these writes.

Focus tools

Four tools move the focus, the one “what I am on” slot that current_focus reads back. They are the MCP forms of cdno action pause, switch and resume. Each writes one entry in today’s ## Logs and, like every write, is verified.

switch_action and switch_unplanned_action return paused (the focus that was set aside, or null) and started (the new focus). resume_action returns resumed (the focus now open) and resumed_from:

{"resumed": {"project": "surrogate-model", "action": "Draft the methods section (deep)",
             "started": "11:12", "date": "2026-10-04", "carried": false, "origin": null},
 "resumed_from": {"kind": "paused", "date": "2026-10-04",
                  "next": "pick up at Prior approaches", "reason": "call"}}

resumed_from.kind is carried or paused, next and reason are the pause’s (always null for a carried focus). With project, a carried focus wins over that project’s pause, so read kind and resumed.action back to the person rather than assuming the pause they were shown, and read next out as the re-entry cue. pause_action and resume_action are for the person’s word: the tool descriptions tell an agent never to call them unasked.

Rejections: focus_open and no_focus

Two refusals are returned as coded rejections, so an agent can act on them without parsing prose. Nothing is written.

focus_open comes from start_action, start_unplanned_action, switch_action, switch_unplanned_action and resume_action:

{"code": "focus_open",
 "message": "An action is already in focus. Ask the person before switching; do not retry.",
 "details": {"focus": {"project": "surrogate-model", "action": "Draft the methods section (deep)",
                       "started": "09:10", "date": "2026-10-04", "carried": false},
             "attempted": {"project": "other-project", "query": "CI"},
             "same_action": false,
             "remedy": "switch_action"}}

The message tells the agent to ask the person before switching and not to retry. The server never switches on its own.

no_focus comes from pause_action (Nothing is in focus to pause.) and resume_action (Nothing to resume: no focus carried over and no pause.), with empty details. Tell the person there is nothing to act on rather than retrying.

focus on write results

The success payload of these eighteen tools carries a focus field: start_action, start_unplanned_action, switch_action, switch_unplanned_action, pause_action, resume_action, complete_action, drop_action, promote_action, add_action, append_to_log, capture, note_to_daily, park_project, activate_project, complete_project, drop_project and hand_off_project. It is the focus as current_focus reads it right after the write, so an agent sees what is open without a second call: the same shape, and null means nothing is open. It is read in the same call that verifies the write, and a focus that cannot be read after a write has landed comes back as null rather than as an error, because an error would tell the agent that a successful write failed. Every other write tool’s result is unchanged.

The server never refuses a write for being outside the focus. How an agent should behave when a request is, is stated once in the server’s instructions rather than in each tool description: compare at project level, say one sentence only on a mismatch, offer to capture it, and treat the person’s explicit “let’s switch to Y” as consent. See Focus.

The during: tag

When a focus is open at write time, a carried one included, the writes that park a thought say which project it was written during:

• append_to_log and note_to_daily append an indented continuation to the log line:

  - **11:12**: checked the mesh
    during: [[surrogate-model]]
  

  (note_to_daily also echoes the tag on a second line of the log_line it returns.)

• capture adds captured_during: surrogate-model to the new inbox item’s frontmatter.

• discard_inbox_item copies that tag from the item onto the log line it writes, so it outlives the file.

With no focus open nothing is written differently, and a focus that cannot be read writes untagged rather than failing. The tag is written by the server; an agent does not add it to its own text.

Commitments and tracking

Revising a note

revise_note takes exactly one of two forms:

Text identical to the note’s current text writes and logs nothing and returns changed: false. The result extends the usual write result with changed, new_hash (the note’s hash after the call: pass it as expected_hash on a follow-up revision rather than reading again), log_line (the line written, without its timestamp, or null) and section_target (the anchored link the log line points at, for a section revision); verification is null when nothing changed.

Refusals (a rejection with these codes; nothing is written):

A blank reason, body together with section, section without content, content without section, or body without expected_hash is refused as an invalid argument (-32602) naming the field.

Renaming a note

The preview is the contract. The sequence an agent follows:

1. Preview. Call with dry_run: true. The result is the plan and nothing is written (written: false); a refusal here is exactly the refusal a write would get.
2. Show. Put the plan in front of the person: what moves, how many references in how many notes, the log_line, any warnings. The person decides, not the agent.
3. Write. Call again with the same note, to and reason (the reason is part of the plan) and expected_plan set to the preview’s plan_hash. What is written is the plan that was shown; if the vault changed in between the call is refused with stale_plan (below) and writes nothing.

note takes the references read_note takes, including a former name of the note (found_by_former_name in the result says which); reason is a short clause for the log line. A rename to the note’s current slug is an empty plan: written: false, log_line: null.

Relinking. relink: true in place of to keeps the note’s slug and rewrites every link that reaches it only through a former name, links and reference fields alike (the links are the stragglers lint reports, which a sync merge can bring back), to the current slug. The same preview-then-write sequence applies, with relink: true on both calls. Nothing moves and the aliases stay listed: the result has moves: [] and new_slug equal to from, and the log_line is relinked [[<slug>]] — <title> with an indented references: <n> line. With no straggler the plan is empty and nothing is logged. An archived action note can be relinked, though not renamed. A blank to beside relink: true reads as omitted. relink with to, either with reason, or neither to nor relink, is refused as an invalid argument naming the field (cdno note rename --relink).

The result is the plan, whether or not it was written: dry_run, target, from (the note’s current slug), new_slug, found_by_former_name (the former name note matched, or null), moves ({from, to}), edits (a path with its changes, each of kind links with a count, field with a key, alias or log_line), references, notes, warnings (each with a kind and a message: frozen_prefix_already_diverged, old_slug_already_an_alias, or sync_check), plan_hash, log_line (null when the plan is empty), then written, index_stale (true: the files are written and the rename succeeded; the index catches up on the next open) and verification. A write nudges the sync agent only when the HTTP server runs with --sync-nudge (off by default; the stdio server never does); a preview never does.

Before planning, the tool checks the vault against its upstream as last fetched: it never fetches. A preview is refused exactly as a write would be.

Refusals (a rejection; nothing is written):

Frontmatter

Daily, weekly, and monthly sections

note_to_daily

The entry is appended under the day’s ## Notes, which is created immediately above ## Logs if the day has none (the daily note itself is created if absent). The pointer line noted [[journal/<year>/daily/<date>#<heading>]], followed by the body’s wikilinks in parentheses when it has any, is appended to ## Logs in the same write, so the entry is not logged again with append_to_log. End an entry worth reusing with the tag #concept on its last line, so a later review can find it as a candidate for promotion to a concept note.

The result adds target — the entry’s anchored link, journal/<year>/daily/<date>#<heading>, to cite as [[<target>]] (for example from a concept’s origin) — and log_line, the pointer line without its timestamp.

Refused with code history_entry_heading_invalid (nothing is written) when the heading reuses a daily section name (Standup, Intention, Agenda, Meeting, Notes, Logs), matches a heading already in that day’s note, contains [, ], |, # or inline markup (bold, italics, code), or starts with ^. Headings inside the body must be level 3 or deeper and are held to the same uniqueness rule, so a pasted derivation with its own ## Proof must be demoted first. A blank heading or body is refused as an invalid argument (-32602).

Notes

• append? defaults to replacing the section; set it true to append instead.
• Dates are YYYY-MM-DD; week-scoped tools accept any day in the target week, and month-scoped tools accept any day in the target month.
• vars? is an optional name -> value map supplying values for a custom template’s [variables.prompt] placeholders — the MCP analogue of the CLI’s repeatable --var name=value. Omitting a required prompted variable fails with an “unresolved prompts” error. See Creation and lifecycle tools for the full list of templated tools that accept it.
• See also: Creation and lifecycle tools, JSON output.