The AI assistant

Every AI prompt surface uses the same composer: Assistant, Plugin Builder, and Inline Assist share keyboard behavior, image cards, context chips, the Run with catalog, the permission-intent menu, Stop, and voice dictation. Each destination still owns its draft and run lifecycle. Builder does not borrow or reroute the Assistant conversation; Inline Assist owns its compact draft but intentionally sends into the active Assistant conversation.

Every assistant conversation—whether it's Wrengle's built-in chat or an external coding agent you've connected—also shares one transcript, tool-card, permission-prompt, edit-review, and saved-conversation interface. Pick which one answers you from the Run with picker in the composer footer. A clean install starts on Wrengle AI · Fast; upgrading preserves the existing explicit or Auto choice.

Run with stays docked at the bottom of the Agent panel even while the selected destination needs setup, sign-in, reconnection, or recovery. During those states Wrengle replaces the message field with the relevant status card, but leaves the picker available so you can choose another model or agent without leaving the panel. The full composer returns when the destination is ready.

Persistent Agent and Terminal tabs live in the right panel's header bar. Switching between them keeps your current agent conversation going and leaves terminal sessions running, whether you're mid-reply from the assistant or mid-command in the shell. Terminal is a place your notes and drafts go—it does not change which assistant answers you. Both tabs stay available even if you haven't installed any plugin panels.

Sharing one interface doesn't mean every backend can do the same things. Wrengle only turns on the continuation, MCP, tool, and review behavior that your selected backend actually supports, and it tells you when a saved conversation can be shown but not picked back up.

Approval policies

The composer has one Assistant permissions menu. Its main choices change Wrengle's approval policy and, where supported, the external agent's own session mode together:

Plan only and Full access are unavailable for built-in OpenAI and Anthropic chat. For external agents, Wrengle enables a named choice only for the exact package version in its reviewed registry and only when the live agent advertises the exact mapped mode ID. It does not infer authority from a mode's display name. If a version or advertised mode set does not match, the named choice stays unavailable rather than guessing.

Open Advanced in the same menu to inspect or select the two raw layers independently: Wrengle approvals and Agent behavior. A raw combination that does not match a reviewed preset is labelled Custom. Advanced can lower the current conversation's Wrengle approval policy but cannot raise it above the durable global ceiling.

Wrengle starts with Ask. You can change the durable host default under Settings → Agents → Permission approvals:

The durable global setting is a hard ceiling for raw conversation overrides. A named Auto approve or Full access transition can raise that ceiling only after the menu confirms the durable Settings change. A new thread or a different saved conversation otherwise returns to the global setting. While durable Full Auto is active, once both Full Auto and Full access have been acknowledged, a new external-agent worktree/thread starts in Full access automatically. Reconnecting or restoring an existing conversation does not reapply that default. Lowering the policy applies to the live native session immediately. Raising authority reconnects the same conversation and revalidates the newly advertised mode set before it sends another prompt, so an older session never gains authority in place. When Full Auto is active, Settings keeps a persistent warning and Pause control. The composer signals the elevated state through its shield and prompt border without showing a second Pause action. During a turn, Stop requests cancellation without changing Full Auto or the agent's mode. After the turn, choose Ask me in the composer to lower both reviewed layers, or use the Settings Pause control to lower Wrengle's durable policy.

Automatic approval never trusts an agent's button text. Wrengle uses the protocol option's typed meaning, chooses only Allow once, waits for native acknowledgement, and records Auto-approved in the transcript. Automatic note edits still pass through the same vault containment, editor serialization, stale-base conflict check, and active-session ownership guards. If delivery is ambiguous, the exact decision stays visible with Retry. If Pause or a global policy reduction wins the race first, Wrengle restores the manual choices instead of retrying a now-disallowed automatic decision.

No composer preset is an external-process sandbox. Wrengle approval policy controls requests that pass through Wrengle's permission and terminal-proposal surfaces. An external ACP program keeps the ordinary operating-system authority described below, even while the policy is Ask.

Assistant connections and turns have no overall elapsed-time limit. Cancel abandons an opening request. Stop requests cooperative turn cancellation; while that request is pending, Force stop is available as a separate explicit teardown. Wrengle does not force-stop assistant work just because 60 seconds—or any other interval—has passed.

While a turn, Force Stop checkpoint, or terminal-command outcome is still being saved, Wrengle keeps agent, model, credential, conversation, and vault route changes unavailable. Finish or stop that work and let its save settle first.

Force stop atomically saves the visible partial transcript with the exact pre-turn context. The partial tail is marked display-only and is excluded from future model context. If saving fails, Wrengle keeps the exact commit available for retry before reconnecting. An interrupted external-agent turn resumes only with an explicit context gap or as transcript-only; Wrengle does not silently trust opaque context that may contain unseen work.

Each app renderer has explicit native ownership. An orderly window close runs the same recovery barrier before destruction. It waits without an elapsed-time cutoff for a just-settled turn's atomic transcript/context save and keeps the window open if an assistant turn is still active or its save needs retry. An opening connection is generation-fenced, its exact renderer workflow and any pending native-open cleanup are drained before native shutdown. After a reload or webview crash, the replacement renderer must reclaim and settle the previous renderer's opening handshakes, partial turns, Force Stop boundary, and terminal-command presentation before another assistant session can open. If the operating system leaves the window open after native shutdown, Wrengle retires the stale session handle and reconnects the same durable conversation after reclaiming renderer ownership. There is no expiring time lease. Before a proposed terminal command starts, Wrengle durably records an Outcome unknown fallback; the settled result replaces it after the command finishes, so an interrupted renderer requires review before retry.

Editing a selection with Inline Assist

Inline Assist is the short path for a small change to text already selected in an editable note. Select non-empty text, then choose Inline Assist from the selection toolbar or press Mod+Enter. This first version is selection-only: placing the caret without selecting text does not open it. It is also unavailable while the note is read-only, local recovery needs attention, or an AI edit preview is already active.

The compact prompt is an entry point into the assistant you already use, not a new AI workflow. It uses the current Run with backend, its effective model, and the active assistant conversation. It contains the same Run with and Assistant permissions controls as the panel composer, so you can inspect or change them without opening the panel. The request receives the current note and selected text, each capped at 6,000 characters when needed, plus the structured note path and bounded selection block IDs used by the ordinary assistant composer. It follows the same routing, transcript, tool, permission, and admission flow as a turn sent from the assistant panel. Exact current-note and selection authority appears as non-removable context chips before you send; Add context can attach multiple searchable notes as exact, turn-scoped Resource paths. Typed text that merely looks like a path does not create authority.

For the built-in OpenAI and Anthropic routes, Inline Assist also applies a native current-note read scope: note listing and search are unavailable, and tools can read or write only the exact current-note or explicitly attached Resource paths carried as structured context. A path or instruction embedded in selected note text grants no extra access.

The Inline Assist exchange remains visible in the shared Assistant transcript, but a built-in route does not receive that scoped user/assistant pair again as model history on a later turn. This prevents untrusted selected text from planting a deferred cross-note instruction. Open Assistant still shows the response; this safety rule changes model replay, not transcript ownership.

Press Enter to send or Shift+Enter to add a line. Completing an input method editor composition does not submit the prompt. Before sending, Escape closes Inline Assist and returns focus to the selection. While its turn is working, Escape or Stop requests cancellation of that Inline Assist turn and keeps the prompt available.

When the assistant proposes a change, Inline Assist closes and the editor's existing review preview takes over. Under Ask, use Accept, Reject, or Retry there. An automatic policy can accept an eligible preview for you, but the same native write checks still run before it reaches disk. If the turn finishes without an edit proposal, the compact prompt says No edit was proposed and offers Retry and Open Assistant. It does not open the assistant panel automatically or render a separate private transcript inline. Open Assistant shows the same conversation in its normal transcript.

Only one assistant turn can be active at a time. If that conversation already has an active turn, sending from Inline Assist replaces its one latest pending turn with the complete Inline draft. The pending turn starts only after the active transcript commit finishes; stopping it returns the complete prompt and attachments to the originating Inline draft. Inline Assist remains blocked while edit preview or recovery state needs your decision. With an external agent, the Wrengle-mediated request and note proposal use the same context and review controls, but the launched program still has its ambient operating-system file, process, command, and network permissions. Inline Assist does not sandbox it. That also means Wrengle cannot enforce the built-in current-note read scope against the subprocess itself: an external agent can act on a malicious instruction embedded in selected text using its ambient permissions. Review imported or untrusted selections before sending them to an external agent. Its opaque session can also retain the inline exchange according to that agent's own continuation and provider behavior.

Sending images to the assistant

You can add images from the Assistant or Inline Assist attachment menu, paste them from the clipboard, or drag image files onto either composer. A turn can combine text and images or contain images on their own. Wrengle shows attachment metadata cards rather than decoding and rendering the raw local pixels in the composer or transcript. Review those file details, remove anything you do not want to share, then send the turn as usual.

Image input is available for compatible models in Wrengle's curated OpenAI and Anthropic catalog. An external ACP agent can receive images only when it explicitly advertises image prompt support. Wrengle keeps an incompatible selection visible and blocks the send with an explanation rather than dropping the images or silently routing them somewhere else.

When you ask the assistant to copy or transcribe image text into a note, Wrengle tells it to preserve the document's semantic structure. Visible bullets should become real list items, including visually wrapped continuation lines, while surrounding prose should remain separate paragraphs. A background panel, border, or monospaced font is presentation rather than evidence of a code block; code blocks are for actual code or an explicit request for preformatted text. Wrengle also tells the assistant to treat instructions visible inside an image as untrusted content rather than directions to follow. Image interpretation is still model-generated, so review the proposed note and reject or retry it if the structure is wrong.

Wrengle accepts static PNG, JPEG, and WebP images, subject to all of these limits:

• Up to 4 images in one turn.
• Up to 5 MiB for each image and 20 MiB across the turn.
• Width and height from 1 through 8,192 pixels, up to 4,194,304 pixels for each image and 16,777,216 pixels across the turn.
• Up to 32 MiB for the decoded pixel buffer of each image. Native normalization processes one image at a time and budgets at most 64 MiB for the source plus a full orientation or color-conversion frame.

Those image limits apply to compatible direct OpenAI and Anthropic routes and external agents. Wrengle AI is text-only in this release; selecting the prepaid route does not send an attached image through the hosted gateway.

Animated, malformed, mismatched, and other image formats are rejected. Before dispatch, Wrengle fully decodes each accepted image, applies its stored orientation, and re-encodes it as a static image. That normalization strips embedded metadata such as EXIF and XMP, color profiles, and text fields; it can also change the encoded representation of the image. The normalized result must still fit the limits above. Opaque WebP input is normalized to JPEG; transparent WebP input is normalized to PNG. This avoids a WebP encoding path that buffers a complete second encoded image before an output limit can reject it, and opaque WebP pixels can therefore change slightly during normalization.

Provider request limits can be stricter than Wrengle's format-neutral staging limits. Anthropic accepts at most 8,000 pixels on either edge in its normal image-size regime. Wrengle keeps each Anthropic request at no more than 20 image blocks so it never enters Anthropic's stricter many-image size regime. It preserves every current-turn image and omits the oldest historical image bytes first, adding an omission marker to the model context.

Wrengle also budgets the initial prompt and live image history against Anthropic's 32 MB request-body limit, including base64 growth and provider/tool envelope room. Before every later model call in the same tool-using turn, it rechecks the accumulated conversation at its JSON-escaped wire size. If the current prompt still cannot fit, Wrengle blocks it before dispatch and asks you to remove images or shorten the prompt. If accumulated tool results make a continuation too large, Wrengle stops the turn before sending that continuation to Anthropic. The original omitted history bytes remain in local live-session memory until the ordinary history and residency rules release them.

Those per-turn limits are separate from a process-wide live-residency limit. Across every assistant conversation in the running desktop app, staged images, requests in flight, and images retained in live history can hold no more than 64 images, 40 MiB of normalized encoded data, or 33,554,432 decoded pixels in total. A new attachment fails closed when any shared limit is full. To release capacity, start a new thread or close live conversations that still contain images. You can also continue without new attachments until an older image turn falls out of the bounded live history, which keeps at most ten completed user/assistant pairs and 24,000 characters and applies its own 20 MiB/16,777,216-pixel image cap.

Native staging is leased rather than permanent. An unsent staged draft expires five minutes after its most recent image is staged and is removed by scheduled or opportunistic native cleanup, including after a renderer reload leaves no working clear request behind.

Normalized image bytes are kept in Wrengle's local memory for the live session, so compatible assistants can answer follow-up questions about an image while that session remains available. Saved conversations contain only a safe format-and-dimensions descriptor and an Image not retained placeholder—not the image bytes, preview URL, filename, path, or staging ID. After reopening the conversation or restarting Wrengle, attach the image again before asking about its contents. This memory-only storage boundary is not a promise of secure erasure from operating-system memory, swap, or crash state.

Sending an image transmits the normalized bytes to the selected cloud provider or external agent. Its own logging and retention rules apply, and an external agent may retain context in its live or resumable session. Cancelling a turn stops work where possible but cannot recall bytes that were already dispatched. While a built-in OpenAI or Anthropic conversation still retains an image, a follow-up can transmit those bytes again. A tool-using turn can also make multiple provider requests with the same image. Each transmission is subject to the provider's exposure, logging, retention, token or image billing, and rate limits.

Built-in cloud conversations also treat retained images as untrusted instructions. While an image remains in their live model history, Wrengle fails closed on model-requested note listing and searching, and on reading or editing unrelated notes. Context you explicitly attach to the prompt is still available to the model. A create-only write proposal can still ask for your explicit approval, but it does not first probe whether the requested path exists and the atomic write fails if it does. Attach the exact note or selection you want to use before sending the image, or start a fresh conversation before asking the assistant to explore unrelated notes.

For ordinary use, renderer-side checks reject over-limit files before staging. The desktop IPC transport still has to receive an attachment as a base64 string before the native command can enforce its own encoded-size limit. That is not a transport-layer allocation cap, and neither the temporary encoded value nor the normalized bytes come with a secure-erasure guarantee.

Continuing saved conversations

OpenAI and Anthropic each keep a limited amount of back-and-forth history across turns. Reopening a saved built-in conversation restores that history, so you can pick up a follow-up where the discussion left off. What doesn't come back: live permission requests, pending tool calls, and other in-progress state from the moment you left. Click New Thread to start fresh, with none of the earlier conversation carried over.

At the end of each turn, Wrengle saves the visible transcript and the model-facing continuation together in one revision-checked commit. The next prompt waits for that acknowledgement. If it fails, the composer keeps the exact turn payload and shows Retry; if another writer changed the saved conversation, Wrengle reloads that saved version instead of merging two different histories behind your back. A broken event sequence or disconnected agent likewise preserves the visible transcript and offers reconnection rather than treating a stale session as live.

For image turns, the saved transcript restores only the safe descriptor and an Image not retained placeholder. Image bytes remain available for follow-ups only during the live session; after reopening or restarting, you must attach the image again.

For an external agent conversation, Wrengle first checks whether the agent advertises sessionCapabilities.resume support, then falls back to checking its top-level loadSession support. If neither is available, or the resume attempt fails, Wrengle keeps your saved transcript visible, starts a fresh session with the agent, and shows a notice that this is a transcript-only view. In that case the old transcript is there for you to read—Wrengle does not quietly feed it into the new session.

Automatic backend selection

Auto prefers whichever AI provider had its key most recently connected or verified as available in your operating-system keychain. If that provider isn't available—or you're on an older installation with no history to check—Auto looks for a connected OpenAI key, then an Anthropic key, and uses whichever it finds first with that provider's default model. If neither is available, it shows provider setup rather than dispatching a request.

A connected key is not a verified key. Only a key that's reported as connected and readable from your operating-system keychain counts, and that's not the same as Wrengle checking the key still works: an invalid, revoked, or quota-exhausted credential can still fail once you actually send a request. Adding, replacing, or removing a key makes Auto reconsider its choice, but if you've explicitly picked a specific provider or an external agent, that choice stays in place instead. A saved retired-provider choice is shown as unavailable and is never converted into a cloud request. Resetting the assistant backend puts it back on Auto. If a cloud provider you explicitly selected loses its key, Wrengle tells you the credential is missing—it will not show you a local-model download warning instead, and it will not quietly switch you to a different backend.

When an explicitly selected OpenAI or Anthropic route has no key, its card in the Agent panel accepts the key there and saves it to the operating-system keychain; you do not need to visit Settings first. You can also ask Wrengle to check for a key already saved on the machine. Plaintext is cleared from the field after a successful save. The same key can still be managed under Settings → Models.

That means Auto can hand your conversation to a cloud assistant as soon as it finds a connected key—cloud assistants can receive your prompt along with any note or workspace context you've approved for that request. Turning Cloud voice features off only affects the automatic voice speech and analysis routes; it does not change which assistant you've selected or which one Auto resolved to.

Cloud model catalog

Wrengle offers a curated set of models, each checked against its chat, structured-output, and note-tool requests. It doesn't mirror every model a provider's API happens to list.

New selections only offer current models—in Settings → Models, the assistant's Run with picker, workflow AI steps, and cloud voice analysis. If you'd already picked an older catalog model, that choice stays as it is; Wrengle just shows it as a saved compatibility choice until you switch to a current one. Left on Auto or Wrengle default, an OpenAI route resolves to GPT-5.6 Luna.

For the prepaid route's exact tier-to-model mappings, credit rates, deployment availability, and metering states, see Wrengle AI and credits.

A custom model ID you'd set earlier can still show up under Saved model (unreviewed compatibility). It isn't part of the curated catalog, it may not carry Wrengle's current request guarantees, and either the provider or Wrengle's own safety checks can reject it.

Wrengle doesn't list a generic "GPT-5.6" option—it uses the explicit Luna, Terra, and Sol IDs so you can always see which cost, latency, and quality tier you're getting. Provider access, regional availability, rate limits, and charges still depend on your own API account. Because of that, changing the default model can change request behavior and cost even if you never touch your saved Auto selection—check the provider's current pricing before running cloud models at high volume.

Claude Fable 5 isn't offered in this release. Its mandatory 30-day retention and refusal behavior need a dedicated privacy and fallback design before Wrengle can add it safely. Invitation-only and unreviewed models—including Mythos 5—are also excluded from the catalog. Wrengle blocks Fable and Mythos IDs before they can be used, even if one is still sitting in an older saved setting.

Dictating assistant prompts

Focus the assistant composer and press ⌘⇧V (macOS) or Ctrl+Shift+V (other platforms) to start your selected voice mode. For a quick one-off, hold ⌘⇧D / Ctrl+Shift+D instead—release it to stop and commit whatever you'd said so far. Speech drafts editable text into the composer, cleaned up as Verbatim or Light edit depending on what you've chosen under Settings → Dictation. Wrengle never sends a dictated prompt on its own: you review the draft and send it yourself.

In Quick Dictation, every trigger word is ordinary draft text—it gets drafted like everything else. In Voice Control, though, a focused composer treats those same words as drafting prefixes rather than commands: saying agent summarize this drafts the text summarize this, and saying terminal run tests drafts the text run tests instead of actually running it. To send a request to your configured agent, or to control the editor, workspace, or terminal by voice, use Voice Control from a different focused surface—not the composer.

AI agents in workflows

On the Workflows canvas, an AI step can use the default workspace model, a direct OpenAI or Anthropic model, or an enabled Wrengle AI tier. The selected route receives the workflow's Goal, that step's instructions, and its upstream artifacts; managed content transits Wrengle and OpenAI. Saved steps pinned to a retired provider remain visible as Needs attention and cannot run until you choose a cloud provider.

Workflow Action, Terminal, and Coding agent steps all wait for you: nothing runs until you submit it. A terminal draft runs only after you explicitly submit it, with your normal operating-system permissions; orchestration does not sandbox them. Coding-agent targets are draft-only in this release, and terminal or coding-agent output is not automatically fed back into orchestration or other agents.

For how to build a workflow, starters, Dry run versus Run behavior, scheduled activation, pinned live versions, privacy boundaries, and current limits, see Workflows.

How external ACP agents work

When you select an external agent, Wrengle starts its command as a local subprocess on your machine and talks to it using the Agent Client Protocol over standard input and output. If that agent also supports MCP over HTTP, Wrengle exposes the tools below to it, through the same assistant workflow you already use:

MCP reads and searches stay scoped to your open vault and don't need approval. When it reads a note as blocks, read_note_blocks reports each block's nesting depth, its parent, and whether it's directly editable. For code blocks, it also reports a language value, using an empty string when none is set; if an update omits language entirely, Wrengle keeps the current value, but an explicit empty string clears it.

Plain editable tables keep the existing update-ready table.headers and table.rows string arrays. If an editable table contains supported bold, italic, strikethrough, inline-code, or link content, read_note_blocks also returns an additive table.rich representation. The string arrays remain as a plain-text projection for compatibility; table.rich is the authoritative cell content and uses strings for plain cells plus { "content": [...] } objects for formatted cells. Text nodes carry true-only bold, italic, strike, and code style flags, and link nodes carry an http:, https:, or mailto: destination. Styled text runs must be non-empty and cannot begin or end with whitespace; put boundary spaces in a separate unstyled text run.

{
  "table": {
    "headers": ["Name", "Docs"],
    "rows": [["Alpha", "guide"]],
    "rich": {
      "headers": [
        "Name",
        {
          "content": [
            { "type": "text", "text": "Docs", "styles": { "bold": true } }
          ]
        }
      ],
      "rows": [
        [
          {
            "content": [
              { "type": "text", "text": "Alpha", "styles": { "italic": true } }
            ]
          },
          {
            "content": [
              {
                "type": "link",
                "href": "https://example.com/guide",
                "content": "guide"
              }
            ]
          }
        ]
      ]
    }
  }
}

When an agent updates a table it read with table.rich, it must preserve and resubmit that rich representation, including unchanged formatted cells. A legacy-only update is rejected rather than flattening the table. An edit can otherwise send the legacy string form, the rich form, or both forms when their plain-text projections agree; conflicting forms and unsupported rich content are rejected.

A formatted table stays one grouped read-only block when its inline delimiter boundaries cannot be represented losslessly or its structured edit payload would exceed the bounded edit_blocks request. In that case it exposes neither an update-ready table object nor an editable target, so an agent cannot accidentally flatten it.

Inserting, updating, and converting blocks

These three operations have deliberately different jobs:

• insert adds new content. A new bullet or numbered list uses the collection type bulletList or numberedList with an items array; a new checklist uses checklist with { "text", "checked" } items.
• update rewrites one existing block's content. Updating one bullet, numbered, or checklist item uses the singular readback type bulletListItem, numberedListItem, or checkListItem. An update cannot use a collection list type.
• convert changes the type of one or more existing blocks without asking the agent to reproduce their text. It accepts 1–100 unique block IDs in one note.

For example, this turns every selected block into a real bullet-list item:

{
  "path": "notes/today.md",
  "ops": [
    {
      "op": "convert",
      "ids": ["p0", "p1"],
      "type": "bulletList"
    }
  ]
}

The six conversion destinations are paragraph, quote, heading, bulletList, numberedList, and checklist. The list-item readback aliases are accepted as inputs for compatibility, but agents are instructed to send the canonical collection names. Converting to a heading preserves an existing heading level, or defaults a non-heading to level 1, unless level is supplied. Converting to a checklist similarly preserves an existing checked state, or defaults a non-checklist to unchecked, unless checked is supplied.

Wrengle resolves the target blocks from one fresh note snapshot and preserves each block's ID, full inline Markdown text, position, and order. Conversion never moves blocks. A selection only has to touch a block for its ID to be included, so conversion changes the whole first or last block even when only part of it was highlighted. Use replace_selection instead when the intended change is an exact inline-text replacement rather than a block-type change.

All conversion targets must be supported, editable top-level blocks. A stale, duplicate, nested, read-only, unsupported, or otherwise unsafe target rejects the complete conversion instead of applying a subset. If every target already has the requested type and properties, Wrengle reports a semantic no-op: it opens no preview, asks for no approval, and writes nothing.

Surgical edit_blocks operations can only target blocks marked editable: true—the supported top-level blocks. A code block marked with backticks is editable only when its source matches Wrengle's own writer format exactly. Other valid backtick-marked code blocks are grouped together, keep their anchors hidden inside the block, and stay read-only; code marked with tildes or indentation stays opaque and can't be targeted at all. Toggle containers, and everything nested inside them, are read-only context.

Updating an editable top-level list item keeps its existing sub-items intact. But a direct edit aimed at a nested list item or a continuation paragraph is rejected outright—Wrengle never silently ignores it or moves it somewhere else. When a change needs to touch those descendants, the editor's own review flow can replace the whole top-level list item, sub-items and all, as one unit.

Every material MCP create, edit, or selection replacement goes through Wrengle's preview and approval policy. Under Ask it needs your explicit approval; the automatic policies can decide eligible work. Right before writing, Wrengle re-checks the vault and the note against your approval, writes the note in the editor's own format, and rejects the write if it's gone stale, conflicts with other changes, or falls outside what was approved.

Structured block reads and edits stop working, safely, once a note's Markdown body passes 262,144 physical lines. That line limit keeps very newline-dense notes—even within the 16 MiB file-size limit—from using an outsized amount of memory. Shorten the note before using read_note_blocks or edit_blocks on it.

Agents that don't support MCP over HTTP fall back to file-only access, through Wrengle's own filesystem hooks—they never receive the named note tools above. What an agent can actually do always depends on the capabilities it advertises, not on which preset you picked.

In Assistant and Inline Assist, the external agent process is not an operating-system sandbox. It runs with the current desktop user's file, command, process, and network authority, and it can use that authority without ever showing you a Wrengle approval card. Wrengle clears the app's ambient environment before launch and passes only a small platform/configuration allowlist plus preset-owned values; it does not forward unrelated app tokens. The allowed HOME/profile and configuration variables still let the CLI find its own login and config, so this is credential minimization, not isolation. Wrengle's prompts and previews cover only work routed through its host tools and callbacks; everything else the process does is outside that review. Run only approved presets you trust.

Plugin Builder has a stricter destination boundary. Its reviewed external-agent Claude Code route preserves native HOME for macOS Keychain discovery while using a fresh scratch CLAUDE_CONFIG_DIR, workspace, XDG directories, and temporary directories. The model sees only the Builder tools that Wrengle exposes over MCP. Native agent file, shell, and web tools are disabled. Builder can reuse the same app-scoped secure-store account identity that you establish in Assistant, but it does not import your ordinary CLI configuration or ambient API-key, Application Default Credentials, or service-account environment. The route fails before sending a prompt unless Wrengle recognizes the exact pinned adapter version and can apply its reviewed, host-enforced MCP-only options. The upstream adapter does not provide a runtime policy acknowledgement. The separate npm preparation phase still uses scratch HOME. See Build one with the Builder.

An Assistant or Inline Assist subprocess receives the validated login PATH needed for npx to find Node. Its reviewed npm package is downloaded over the network into a Wrengle-owned agent cache, separate from your global npm/npx cache. The approved Claude Code preset uses its app-scoped account sign-in and does not inherit an ambient ANTHROPIC_API_KEY. For the npm bootstrap only, Wrengle uses app-owned user/global npm config files, forces the public npm registry for the default, @agentclientprotocol, and @google scopes, and starts npx from an app-cache directory. A .npmrc in the selected worktree or your home directory therefore cannot redirect these reviewed packages. The adapter receives the selected vault path through ACP when its session starts. Before the long-lived adapter starts, Wrengle verifies the installed package name, version, and reviewed executable, removes the bootstrap-only npm variables, and restores the validated login PATH. Package commands the agent later runs therefore use the user's ordinary npm configuration rather than Wrengle's download policy. The short node --version and npx --version readiness probes receive that validated PATH and the same bootstrap-only platform/configuration allowlist, but no preset or provider credentials. In Assistant and Inline Assist, Gemini CLI can receive GEMINI_API_KEY, GOOGLE_API_KEY, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and GOOGLE_GENAI_USE_VERTEXAI. These names are preset-specific. Codex does not receive the app's ambient OPENAI_API_KEY; complete codex login first, as described below. Unrelated proxy, CA, provider, database, and integration variables are not inherited. Plugin Builder excludes all of those API-key, ADC, and service-account variables and relies only on a supported app-scoped account sign-in.

Wrengle owns the ordinary launched process tree and tears it down on close or Force stop. On Unix, a deliberately detached process that creates a different session/process group can escape that ownership; platform failures can also make complete descendant cleanup impossible to prove. Work already sent to a provider or another network service cannot be recalled.

The bundled Wrengle renderer is a trusted policy controller. Native code validates saved approval settings and ACP permission metadata against untrusted external-agent input, but the policy is not a security boundary against code already executing inside Wrengle's own renderer. Such code could submit a manual approval or change the global policy through the same native commands as the legitimate UI.

For note edits, Wrengle previews the proposed document by converting it into the editor's block format before you approve anything. When you approve an ACP note write, Wrengle writes the note the same way the editor always writes it—not the raw text the agent proposed. That keeps standard Markdown lists, checklists, tables, code blocks, headings, and block anchors consistent with the structured editor. If Wrengle can't safely convert what's proposed into that format, it rejects the write rather than save a lossy raw version. Right now, one approval writes one note at a time. A single approval can contain several compatible edits or a multi-block conversion within that note, but requests that touch multiple notes or rewrite an existing note's frontmatter are rejected until they can be split into separate approved writes.

The built-in OpenAI and Anthropic options don't launch a separate process at all. They use the API keys stored in your Wrengle settings, and they still show up with the same transcript, context, and permission UI as any other agent in the assistant panel.

Reviewing note edits

Built-in assistants and MCP-capable external agents read your existing notes as anchored blocks and propose surgical edits against those specific block IDs. Creating a brand-new note uses a separate, create-only write_note tool instead—so changing an existing table should update that table in place, not reproduce the rest of the note or add a second copy of the table. File-only ACP agents, without MCP, can still use Wrengle's own whole-file review path, as long as their filesystem callbacks produce a note proposal Wrengle supports.

Wrengle shows every supported change before anything gets written. Fully rendered, same-type text-block edits get per-block Keep and Skip controls. A table is a single approval unit instead: its rows and changed cells all show together, and Keep or Skip applies to the whole table at once; there's no row-by-row or cell-by-cell approval. Some changes don't fit that inline view. Block-type conversions use a whole-note preview so the structural markers and relationships are visible, and all converted targets are accepted or rejected together. Changes that move a block's identity, alter its descendants, or include structure or styling the inline diff can't display use the same Accept / Reject all fallback rather than quietly dropping part of what was proposed.

If your note changed after you approved the preview, Wrengle won't overwrite it. Clicking Accept submits everything you didn't skip, and the editor treats those changes as provisional until the vault confirms the write went through. Wrengle checks the note again right at write time; if it changed since you approved the preview, the write fails and the editor reloads the newer version from disk instead.

Once the vault confirms the write, the accepted AI edit is one Cmd+Z/Ctrl+Z step, including a partially accepted set of inline changes. Undo returns to the exact note from before the preview and redo reapplies the accepted result. Preview revisions, rejection, and failed or conflicting writes do not add undo steps. A later disk reload establishes a new undo baseline and clears older note undo entries.

Requirements

External presets launch through npx, so you'll need npx and a compatible Node.js version on your PATH. The release-pinned Claude Code and Codex adapters require Node 22 or newer; Gemini CLI requires Node 20 or newer. Wrengle checks the selected preset's requirement before starting it and shows a setup notice when the runtime is missing or too old. Built-in backends don't need Node at all. The host-owned node --version and npx --version setup probes run in managed process trees, are cancelled with the opening request, and are capped at 10 seconds each. This setup bound does not limit an assistant connection or turn after launch.

Each Wrengle release carries a reviewed snapshot of the public ACP registry and pins the exact top-level npm package version for every approved preset. A publisher's newer latest release does not start running merely because you open a new worktree or reconnect; Wrengle changes a pin only in a later app release after review. --engine-strict still makes a raised Node requirement fail closed. The pin covers the named top-level distribution, while npm remains responsible for downloading and verifying the dependency tree declared by that distribution. A release pin and registry integrity do not sandbox publisher or dependency code.

Wrengle keeps these downloads in an app-owned cache so a damaged extraction can be repaired without deleting or changing your normal ~/.npm cache. If a stopped agent reports a damaged cached executable, choose Repair and reconnect. Wrengle quarantines only that preset and version's failed cache generation, switches the preset to a new empty generation, and makes one reconnect attempt with the same release-pinned version. The quarantined generation is not modified while another live session could still hold files from it. Wrengle retains the two newest quarantined generations and can reclaim an older one only when its OS-backed live-session lease is no longer held. A later preparation or repair can therefore remove an unlocked marker left by an app or system crash without touching a generation that a live session still uses. Repair normally needs network access to populate the new generation, cannot recall work already sent to an agent or provider, and does not clear that CLI's login, provider-side data, or saved Wrengle transcript. Whether the external conversation itself resumes still depends on the continuation capabilities described above.

Login and billing

Each agent authenticates through its own CLI, and billing follows whichever account or API credential that CLI uses. Wrengle chooses the app-scoped secure-store identity used by an approved shared-auth route, but it does not copy the secret into settings, Builder scratch, an ACP message, or a generated plugin. Advertised sign-in methods are capabilities, not proof that the CLI is signed out. Wrengle first tries to resume a saved session, falls back to loading it when needed, and otherwise starts a new session. It shows the authentication card only after an explicit authentication-required response from that lifecycle or a prompt. A prompt-time failure first settles and saves the interrupted turn, then shows the sign-in card. Recovery discovers login methods in a separate session even when the agent accepted session creation before rejecting the prompt. When the agent offers an interactive login, choose one of its methods and Wrengle opens the Terminal tab, launches the advertised login command, and waits for it to finish. Complete the CLI or browser flow there. A successful login starts a fresh agent connection and checks the lifecycle again before returning to the initiating surface. In Assistant, it reconnects the same Wrengle conversation; it does not resend the prompt that failed before login.

The Run with picker remains at the bottom while this authentication card is visible. You can complete the advertised login or immediately switch to another cloud model or coding agent.

External coding agent authentication in Plugin Builder can reuse the same account identity only for an exact adapter version with Wrengle's reviewed shared-auth and MCP-only policy. The current Builder policy covers Claude Code 0.70.0. An existing account sign-in from Assistant or Builder is reused through the same app-scoped secure-store identity; fixing Keychain discovery does not require another login. If you have not signed in since moving to the app-scoped identity, complete one fresh Claude account sign-in from Assistant or the Sign in action in Builder. That sign-in puts the CLI credential in the shared identity; a login held only in your ordinary CLI home or supplied through ANTHROPIC_API_KEY is not a Builder credential. Gemini CLI and Codex return an unsupported Builder outcome and remain Assistant-only. Builder still keeps Claude Code configuration and workspace state in scratch while preserving native HOME for macOS Keychain discovery.

Builder offers Sign in where an authentication failure appears. Its login card uses a separate recovery session for the agent that ran the failed build; it does not switch Assistant's selected agent or send it the Builder prompt. Recovery sessions receive no conversation history and save no transcript. If the shared credential is missing, expired, inaccessible, or unsupported, or if Wrengle cannot apply the exact adapter's reviewed MCP-only policy, Builder stops before sending the prompt, creates no generated draft, and installs nothing. It restores the complete editable submission and never automatically resends it. Choose Sign in, select a supported login method, and complete the terminal or browser flow. After sign-in, explicitly retry the restored build submission.

If the credential expires after generation has already begun, Builder stops the turn and keeps any generated draft or visible work available for review. It still never replays the provider turn automatically; retry is an explicit new action.

The login command runs as a transient terminal session with the desktop user's normal operating-system authority. Wrengle starts the exact reviewed preset and the login arguments advertised by that agent rather than constructing a shell command. The agent CLI or identity provider owns credential entry and storage; Wrengle does not copy login credentials into its settings. Login terminal output is available only for the current app runtime and is excluded from saved terminal sessions, command history, agent transcripts, logs, and telemetry. That non-persistence is not secure erasure from process memory, operating-system memory, swap, crash data, or storage maintained by the CLI or provider.

If you cancel the terminal or the login exits unsuccessfully, Wrengle returns to the initiating surface with a retryable error. Use Show Terminal to inspect the transient output, then choose a method again. For Claude Code, use the authentication terminal opened from Assistant or Builder: an ordinary terminal targets Claude's default credential namespace and does not update Wrengle's app-scoped identity. Manual login in your usual terminal is a fallback only for Gemini CLI or Codex, which remain Assistant-only in Plugin Builder. Closing the login tab with its X cancels the attempt and discards that transient tab, so its Show Terminal action is not retained.

If Gemini CLI or Codex does not provide a supported in-app sign-in method, sign in with its command-line tool and select Reconnect on the authentication card. If an interactive Claude login exits successfully but the agent still reports that authentication is required, review the transient login Terminal output and choose the advertised account method again.

The available methods come from the selected agent and may vary by release:

• Claude Code — follow the current Claude Code authentication setup. Choose the Claude account or Anthropic Console method from Wrengle's Assistant authentication card so the reviewed preset runs the corresponding login inside the app-scoped identity. Wrengle does not inherit an ambient ANTHROPIC_API_KEY for this preset.
• Gemini CLI — follow the current Gemini CLI authentication setup. Sign in with Google, set GEMINI_API_KEY for a Gemini API key, or configure supported Vertex AI authentication such as Application Default Credentials, a service-account key, or a Google Cloud API key. Account eligibility, quotas, and billing depend on the selected Google service.
• Codex — Wrengle uses the maintained @agentclientprotocol/codex-acp adapter; the former @zed-industries/codex-acp package is retired. Authenticate Codex CLI with ChatGPT first by running codex login. Wrengle does not provide an API-key entry flow or pass its ambient OPENAI_API_KEY into this subprocess.

To check or change Claude Code's account, use the transient authentication terminal and methods shown by Wrengle Assistant. For Gemini CLI or Codex, use the provider's CLI in your usual terminal and then reconnect the agent.

Add an approved preset

The assistant's Run with picker lists every release-reviewed coding-agent preset. An agent you haven't added yet appears as Agent name · Set up…. Selecting that entry opens Settings → Agents → Add an agent without closing your current assistant session or changing its backend. Click Add, then approve the inline confirmation showing the reviewed package, version, and adapter arguments. Setup registers the agent but does not start it; return to Run with and select it when you're ready to connect. That explicit-selection requirement survives an app restart and also blocks saved conversations from starting the newly registered agent first. If you re-register more than one agent before selecting them, Wrengle tracks each one independently; selecting one does not authorize any of the others.

You can also open Settings → Agents directly and add a preset there. Wrengle adds its private cache, registry, and verified-launcher flags internally; the displayed line is intentionally not a byte-for-byte process command:

Each preset you add becomes a selectable destination in Run with. A preset you've already added shows a disabled Added button in Settings instead. If you remove an optional preset, its setup entry returns to the picker.

Custom subprocess agents aren't enabled yet—the dropdown only starts built-in chat backends and the approved external presets above.