Skip to documentation
eli.aidocs

Ports

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

propose → suspend → human decision → materialize or resume with rejection.

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.

a kb_propose_note calljson
{
  "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.

One gate, no exceptions

There is no configuration that lets an agent bypass the inbox — no auto-approve flag, no trusted-agent mode. If a workflow seems to need direct writes, the answer is a faster approval loop, not a hole in the gate.

Related