Write-via-approval

Agents read the knowledge base freely — but they never write to it directly. The only agent write path into the KB is kb_propose_note: the agent proposes a note, the run suspends into the approvals inbox, and a human decision either materializes a vault document or resumes the run with a rejection. The KB stays a human-curated asset.

The flow

The kb_propose_note tool

kb_propose_noteis a built-in tool available to agents. A call carries the proposed note — title, markdown body, and the sources it was derived from — and behaves like any other gated tool call: the run's status becomes suspended, the full resume cursor is persisted, and the proposal lands in the workspace's approvals inbox alongside gated MCP calls.

{
  "name": "kb_propose_note",
  "input": {
    "title": "Q3 renewal risk — Acme Corp",
    "body": "## Summary\nAcme flagged budget pressure in the 2026-07-14 call…",
    "sources": ["doc_01J8…", "conv_01J9…"]
  }
}

Approve or reject

• Approve — the proposal is materialized as a real vault document: markdown on disk, indexed, extractable, citable — indistinguishable from a document a human wrote, except its provenance records the proposing run. The run resumes with the new document's id and can reference it in its final answer.
• Reject — nothing is written. The run resumes with a rejection result (and your optional note), which the model sees as the tool outcome and can react to — revise the proposal, continue without it, or report why the note was declined.

Because the suspend/resume record is durable, the human can take hours or days; the run picks up from its persisted cursor either way — even across a process restart.

Why agents never write directly

This is a deliberate architectural line, not a missing feature:

• The KB is the asset.Retrieval, extraction, coverage scoring, and every downstream answer are grounded in vault documents. One hallucinated "fact" written directly would be laundered into a citable source and poison everything built on it.
• Prompt-injection containment. Agents read untrusted content — imported documents, MCP tool output, the web. A write gate means injected instructions can at worst propose a note a human will read, never silently plant one.
• Provenance and audit.Every agent-originated document traces to a proposal, a run, and a named approver — the story an enterprise client expects when they ask "who put this here?".
• Quality stays measurable. Approval decisions are captured as feedback signal, so the proposal-acceptance rate becomes a measurable quality metric per agent version.

Related

• Approvals & feedback — the inbox where proposals land, and the feedback loop approvals feed.
• Tools, MCP & HITL — the suspend/resume machinery underneath.
• Knowledge base & vault — what a materialized document becomes part of.