Onboarding agents to Suggestions mode

You have an agent that’s been writing freely to your vault. You want to put it in propose-only mode without losing what it’s been doing.

Why switch

• You want to see what changed before it ships.

• The agent has gotten ambitious and you’re not sure about its taste.

• You want to share the vault with someone else and need a review gate.

• You want an audit trail of agent decisions.

The switch

1. Issue a propose-only key.

   Propose-only isn’t a scope — it’s a flag (--propose) layered on a normal read/write key. Settings → General → API keys lets you manage keys in the app; or from the CLI, add a new key and remove the old one:

   lettuce keys add --label "Claude Desktop (propose)" --scope all --propose
   lettuce keys remove --label "Claude Desktop"
   

2. Update the agent’s config.

   Claude Desktop: edit ~/Library/Application Support/Claude/claude_desktop_config.json, update LETTUCE_TOKEN.

   Claude Code:

   claude mcp remove lettuce
   claude mcp add lettuce http://127.0.0.1:51234/mcp \
     --header "Authorization: Bearer <new-token>"
   

3. Tell the agent.

   In AGENTS.md (see Agent reference/09 AGENTS.md), add:

   ## You are in propose-only mode
   
   Your write calls don't land directly — they become proposals the
   user reviews. Use `list_my_proposals` to track what's pending and
   `withdraw_proposal` to cancel one you no longer want.
   

4. First chat: nothing special needed.

   A propose-only key keeps the same write tools (write_note, patch_section, apply_edits, …) in tools/list. The agent calls them exactly as before; instead of mutating the vault, each call returns {status: "pending", proposalId, path, operation} and queues a proposal. No new tool to learn, no insufficient-scope error to handle.

What changes from the agent’s perspective

• The same write tools are still advertised; their results change to a pending receipt instead of a committed write.

• file_page (the loop’s keystone) works in propose-only mode by decomposing into a reviewable batch — the page (create), the index.md catalog bullet (prepend), and the log.md ledger entry (append), all sharing one batchId — so the human accepts or rejects the whole compounding step together.

• The folder mutators (create_folder, rename_folder, delete_folder) are still refused in propose-only mode — they touch the directory tree and have no proposal shape yet.

• Read tools are unchanged.

• list_my_proposals and withdraw_proposal let the agent track and cancel its own queue.

Backfilling pending proposals

The agent’s previous live writes are obviously already in your vault — you can’t retroactively “un-apply” them. But going forward, every change shows up in the proposals tab of the Inspector (the tray icon) for review.

Granular control

Instead of propose-only, you can keep a normal write key but confine it to a folder with --allow:

lettuce keys add --label "Inbox-only Claude" --scope all --allow Inbox

Now the agent can freely write notes anywhere under Inbox/ (a low-stakes area) and is rejected with a path-allowlist error everywhere else. Combine --allow with --propose if you want both a folder fence and review.

See Agent reference/03 Authentication for the scope and folder-allowlist syntax.

When to switch back

You probably won’t, but if you do: issue a key without --propose (or untoggle it in Settings). The proposals queue stays — accept or reject what’s there at your leisure.

Related

• Suggestions mode/01 Overview

• Suggestions mode/03 The proposals UI

• Agent reference/03 Authentication