Agneta

Agneta for apps: the protocol

How a Mac app runs AI work through Agneta. Agneta speaks the Agent Client Protocol (ACP, JSON-RPC 2.0) and adds a few namespaced extensions, each listed in initialize. An app that ignores them still gets plain ACP.

Project Chat is a runnable Electron example with pairing, streamed replies, and app-owned MCP tools.

Every step on this page is exercised by the test suite: Tests/AgnetaKitTests/AppScenarioTests.swift runs it against a real engine, and RouterContractTests.swift pins each decision. How Agneta works inside is in Architecture; what each engine can do is in Engines.

Connecting

  • Address: ws://127.0.0.1:47321/acp for releases, 47331 for development builds. Loopback only, one JSON-RPC message per text frame, frames up to 16 MB.
  • Before it has a grant (until pairing or initialize succeeds), a connection is anything on this Mac and gets little: at most 16 such connections at once, messages up to 256 KB, and 10 minutes to pair. Past any of these, Agneta closes it.
  • Browsers can’t connect: a WebSocket upgrade with an Origin header is refused, so a web page can’t drive Agneta.
  • Sandboxed (Mac App Store) apps need com.apple.security.network.client to connect to Agneta, and com.apple.security.network.server as well if they serve their own MCP server on loopback.
  • Folders for sandboxed apps. A folder inside an app container (~/Library/Containers, ~/Library/Group Containers) can’t be a session’s folder: Agneta keeps apps’ private storage out of reach. Ask in the pairing scope for folders the user chose (an open panel or a security-scoped bookmark gives the real path, outside the container), or let tasks work in the workspace Agneta makes for the app and hand results back through the app’s MCP tools: the sandbox keeps the app itself out of that workspace.
  • When Agneta isn’t running, the connection is refused. Ask the user whether to open it, and when they say yes, open agneta://open (agneta-dev://open for a development build), wait for its port, and connect. Never open it without asking: quitting Agneta is how the user stops all of it. Opening the URL only launches Agneta; nothing in the URL is acted on.

Pairing, once per app

  1. Send agneta/pair {"name": "Example App", "scope": {"tools": "workspace", "folders": ["/Users/me/Documents/Example Project"]}}. Agneta opens its approval window, which shows what the scope asks for; the user ticks the providers the app may use (one is ticked to start with), then Allow Once or Always Allow. Every engine is allowed too, unless the user narrows them under Advanced: your app picks the provider and engine of each task, among what it may use (Access).
    • scope is what the app will need: tools, the most built-in tools its sessions will use (app-only, read or workspace, as in the policy), and folders, the user’s folders its sessions will work in (absolute paths, under the policy’s folder rules). Without a scope the app gets app-only tools and no folders of the user’s. Either way it also gets a workspace of its own, made by Agneta. Ask for what the app’s features need, and no more: the user sees it all before deciding.
    • Allowed: {"token": "…", "remembered": true, "access": {…}} (Access). Agneta stores only the token’s hash.
    • Always Allow (remembered: true): keep the token in the app’s Keychain and connect with it next time (initialize), without asking again. When initialize answers -32001 (needsPairing), the user removed the app’s access: forget the token, and pair again when the user asks to connect. Agneta also closes the app’s open connections when its access is removed.
    • Allow Once (remembered: false) grants this connection only: the token stops working when it closes, and Agneta keeps nothing. Pair again next time.
    • Pairing again with Always Allow, for an app that has remembered access already, replaces that access instead of adding to it, and the old token stops working. The approval window says so.
      • A verified app (the same signing identity) keeps its grant: its workspace and tasks to resume, with what the user just allowed. Its other open connections get the new access at once, as agneta/accessChanged; their sessions outside it stop, with agneta/sessionStopped.
      • An app Agneta can’t verify is known only by its name, which another program could give, so its new grant starts afresh: a new workspace, and none of the earlier tasks to resume. The earlier grant is removed, and connections still using it are closed.
    • A scope Agneta can’t accept (a folder it protects, an unknown field) is refused with -32602 before the user is asked.
    • Don’t Allow: error -32002. Closing the approval window, or leaving it unanswered for 5 minutes, is the same.
    • Several apps asking at once are shown one at a time. An app that disconnects while waiting withdraws its request.
  2. Agneta identifies the connecting process by its code signature (see Architecture). An app signed with an Apple-issued certificate and a team ID is shown as verified, by its signing identifier (for example com.example.app).
  3. If Agneta can’t verify the app (ad hoc or unsigned builds), it first sends agneta/pairingCode {"code", "name"} with six digits. Show the code prominently while the request waits. Agneta’s approval window shows the same code, and the user allows the app only if the two match.
  4. Every session must fit the grant. No more built-in tools than granted, and every folder a session names (cwd, readable, writable, readOnly) inside a granted folder or the app’s own workspace. Anything else is refused with -32602, data.agneta.unenforceable naming the field. To need more, pair again with a wider scope.

Every connection

initialize:

{"protocolVersion": 1, "clientCapabilities": {}, "_meta": {"agneta": {"token": "…"}}}
  • Result: standard agentCapabilities (loadSession: true, images in prompts, HTTP MCP servers, session/close), plus:
    • _meta.agneta.extensions: the extensions below;
    • _meta.agneta.access: what the app may use (Access).
  • Error -32001 with data.agneta.needsPairing: true means the token is unknown, access was removed, an Allow Once grant has ended, or (for a verified app) the connecting program isn’t the one that paired. Pair again.

Access

What the user allows an app is two lists: the providers (each an account: a ChatGPT or Claude plan, an API key) and the engines (Goose, OpenCode, Claude Code, Codex; all of them unless the user narrowed them). Each task runs on one provider and one engine, which your app picks; the pair must be one the provider supports (Engines) and this Mac can run. agneta/access {} returns, at any time, what that means now, the same object initialize and pairing return:

{
  "providers": [{"id": "a1b2c3d4", "label": "Claude", "kind": "claude", "paused": false, "needsSignIn": false,
                 "engines": ["claude-code", "goose"], "defaultEngine": "claude-code"}],
  "engines": [{"id": "claude-code", "name": "Claude Code", "state": "ready", "capabilities": {…}},
              {"id": "goose", "name": "Goose", "state": "ready", "capabilities": {…}},
              {"id": "opencode", "name": "OpenCode", "state": "downloadable", "size": 113000000}],
  "allowedEngines": "all",
  "scope": {"tools": "workspace", "folders": ["/Users/me/Documents/Example Project"]},
  "workspace": "/Users/me/Library/Application Support/com.objectivecoder.agneta Workspaces/<grant>"
}
  • providers: each provider the app may use. engines are those its tasks there may run on now or after a download, the default first (defaultEngine: the provider’s default in Agneta’s settings when allowed, else the first allowed). A paused provider starts nothing new (Pause, under Turns); one that needsSignIn waits for the user in Agneta.
  • engines: each engine the app may use, with its state on this Mac: ready (with its capabilities, as in the session result), downloading (received, total), downloadable (size: it downloads when first needed), failed (reason; asking for it tries again) or unavailable (reason, such as “Install Codex 0.166 or later”).
  • allowedEngines: "all" (including engines Agneta adds later) or the engine ids the user ticked.
  • scope and workspace: what the user allowed, and the app’s own workspace within it.
  • agneta/accessChanged {"access"} arrives when any of it changes: the user changes the app’s providers or engines in Agneta’s settings (sessions that no longer fit stop, with agneta/sessionStopped), a provider is paused, resumed, signed out or needs signing in, or an engine arrives, starts downloading or goes away. Download progress doesn’t send it: agneta/access and -32015 carry it.
ExtensionWhat it adds
agneta/policyThe session policy: tools, folders, network, approval, limits
agneta/accessagneta/access and agneta/accessChanged: the providers and engines the app may use (Access)
agneta/taskA title and a stop warning shown in Agneta’s menu
agneta/instructionsInstructions at start, and agneta/instructions/set between turns
agneta/steeragneta/steer during a turn
agneta/usageEach prompt result’s usage: model calls, tokens, cost, and what the numbers mean
agneta/limitWhich policy limit stopped a turn
agneta/queueagneta/queued when a turn waits for room
agneta/forkagneta/fork: a new task that starts with a copy of an earlier one’s conversation
agneta/rateLimitedagneta/rateLimited and structured error data when a provider’s limit stops a turn
agneta/traceThe task’s full trace, live and afterwards (Diagnostics)

A session

session/new:

{
  "cwd": "/Users/me/Documents/Example Project/Workspace",
  "mcpServers": [{"type": "http", "name": "app", "url": "http://127.0.0.1:<port>/mcp",
                  "headers": [{"name": "Authorization", "value": "Bearer <per-session token>"}]}],
  "_meta": {
    "agneta": {"account": "<account id>"},
    "agneta/policy": {"tools": "workspace", "network": "none", "approval": "never-ask",
                        "readable": [], "writable": [], "readOnly": [], "denied": [],
                        "limits": {"maxTurns": 200, "maxSeconds": 1800}},
    "agneta/task": {"title": "Tidying the project notes", "stopWarning": "Example App keeps the work so far"},
    "agneta/instructions": {"text": "You are Example App's assistant…"},
    "agneta/trace": {"live": true}
  }
}

cwd is the workspace: the folder the agent works in. It must be an absolute path, and the same rules as the policy’s folders apply to it.

_meta.agneta.account chooses the provider, one of access.providers. If it’s omitted, the first one is used.

_meta.agneta.engine (optional) chooses the engine, one of that provider’s engines; without it the session runs on its defaultEngine. An engine the provider doesn’t support, the app may not use, or this Mac can’t run is refused with -32602 and the current access in data.agneta.access. One that downloads first starts downloading, and the session is refused with -32015 and data.agneta.engineDownloading {"engine", "received", "total"} until it’s done: show the progress and try again shortly. A loaded or forked session always runs on the engine that saved it. A session that was opening while the app’s access changed (in Settings, or by pairing again) is checked against the access as it is then: one that no longer fits is refused with -32602 and data.agneta.accessChanged: true.

mcpServers are the app’s own tools: Streamable HTTP on loopback, with a bearer token.

  • Only type: "http" with a 127.0.0.1, localhost or ::1 URL is accepted. Anything else is refused with -32602 and data.agneta.unenforceable: ["mcpServers"]: a stdio server would be a command run inside the engine’s sandbox, and a remote one a host the policy didn’t allow.
  • The engine’s sandbox may reach exactly those loopback ports. The exceptions: an app-only session on Goose shares one engine per account, which may reach any loopback port, and OpenCode may reach any loopback port (it runs a private server of its own).
  • Your tools run in your app, with your app’s own permissions: Agneta’s sandbox confines the engine that calls them, not what they do.
  • Header values are masked in traces.
  • In tool events, the server’s name comes back as the tool’s extension, and the tool’s own name as tool.

agneta/policy

FieldValues
toolsapp-only: only the app’s MCP tools. read: plus the engine’s read-only built-ins. workspace (the default): plus editing and a shell, confined to the workspace
networknone (the default): shell commands reach nothing but the policy’s toolPorts and toolSockets, and Claude Code’s and Codex’s commands and fetches are refused. The engine itself can reach any host on port 443, since it needs HTTPS for its provider and macOS’s sandbox filters by port, not host name. A list of allowed hosts ({"allow": [hosts]}) isn’t supported yet and is refused; {"allow": []} means none
approvalask-app (the default): tool permission requests reach the app as session/request_permission. never-ask: the policy is the permission, and Agneta answers
readable, writable, readOnly, deniedAbsolute paths. readOnly stays read-only even inside the workspace; denied is neither readable nor writable, even inside allowed folders
toolPorts, toolSocketsLoopback ports and Unix sockets that shell commands may reach (on engines whose shell runs through Agneta’s broker: Goose and OpenCode)
limitsmaxTurns: model calls within one prompt (default 200). maxSeconds: a prompt’s wall time (default 4 hours). maxCostUSD: the task’s known cost so far, across resumes (no default)
  • Nothing is weakened silently. A policy Agneta can’t enforce is refused with -32602 and data.agneta.unenforceable: ["<field>"]. That covers:
    • unknown fields, fields of the wrong type ("tools": 5), and malformed or non-positive limits;
    • relative paths, and folders that contain the home folder, other apps’ containers, Agneta’s own data, ~/Library/LaunchAgents, ~/Library/Keychains or ~/.ssh;
    • a writable folder inside a denied one, or a denied workspace;
    • maxCostUSD on an engine that doesn’t report cost per call (Claude Code, Codex).
  • Sending no policy gives workspace tools in cwd, no network and ask-app approval.
  • Changing the engine’s mode (session/set_mode, or session/set_config_option with configId: "mode") is refused where the mode would leave what Agneta set up: on Claude Code and Codex, a mode that stops the engine asking permission, since Agneta checks each tool call from those questions; on OpenCode, any agent but Agneta’s, which carries the session’s instructions.

Instructions

agneta/instructions.text, or ACP’s systemPrompt, sets the session’s instructions. Goose, OpenCode and Claude Code use them as the system prompt; Codex appends them to its own instructions, which say how to use its tools (Engines).

The result

  • sessionId: Agneta’s id, never the engine’s.
  • _meta.agneta: account, dedicatedEngine (whether the session has an engine process of its own), and capabilities:
FieldMeaning
enginegoose, opencode, claude-code or codex
steeragneta/steer works
forkagneta/fork works
instructionsBetweenTurnsagneta/instructions/set works
reportsCostPer-call cost is known while the turn runs, so maxCostUSD can be enforced
  • configOptions and modes: the engine’s own, passed through (model, thinking effort, mode, …).

Only Agneta’s methods. An app calls only the methods on this page. Anything else, including an engine’s own methods, is refused with -32601, and notifications other than session/cancel are dropped: an engine’s methods would bypass the checks made when the session started. Engine extras are reached through Agneta’s methods (agneta/steer, agneta/instructions/set), which each engine’s adapter maps.

Features differ by engine on purpose. Each engine’s extras are offered where it has them, never trimmed to what all engines share. Check capabilities before offering a feature; a call the engine can’t serve fails with -32014.

GooseOpenCodeClaude CodeCodex
SteeringYesYesYesYes
Instructions between turnsYesNoNoNo
ForkYesNoNoNo
Resume (session/load)YesYesYesYes
CostPer callPer callAt the turn’s endNo

Model and thinking

A session’s settings are the engine’s own ACP config options, in session/new's result (configOptions), each with its choices and current value. Find them by their standard category rather than an engine’s own ids, which differ:

CategoryWhatSeen
modelThe model (every engine also uses the id model)Codex, Claude Code, Goose, OpenCode. Goose on a Claude plan offers one: Claude Code’s own, current
thought_levelReasoning effort (ids differ: reasoning_effort on Codex, effort on Claude Code, thinking_effort on Goose)Codex, Claude Code, Goose on a Claude plan; Goose and OpenCode with an API key for models that have it
  • Change one with session/set_config_option {"sessionId", "configId", "value"}, before the first prompt or between turns. The answer is the options as they are now: another model may offer other efforts, or none.
  • To let people choose before they type, open the session first (it starts the engine but calls no model). Choices may come in groups; a current value may be missing from the choices (Goose reports its configured model without always listing it).
  • Changing provider or engine means a new session.

Turns

session/prompt {"sessionId", "prompt": [content blocks]}. Text and images are supported in prompts and in MCP tool results.

While the turn runs, the engine’s session/update notifications arrive unchanged, with Agneta’s session id:

  • agent_message_chunk and agent_thought_chunk;
  • tool_call and tool_call_update (upserts by toolCallId; the first sighting may be a placeholder);
  • usage_update (cumulative context size and used);
  • plan;
  • session_info_update.

The result:

{"stopReason": "end_turn", "usage": {"inputTokens": 42, "outputTokens": 7, "totalTokens": 49},
 "_meta": {"agneta/usage": {"modelCalls": 2, "models": ["gpt-x"], "inputTokens": 84, "outputTokens": 14,
                              "cacheReadTokens": 0, "cacheWriteTokens": 0, "cost": null, "costKind": "estimated",
                              "taskCost": null, "billing": "api-key", "account": "…", "ms": 196.4, "msToFirstToken": 147.1,
                              "basis": "engine-ledger"},
           "agneta/limit": {"limit": "maxSeconds", "value": 1800}}}
  • agneta/usage comes from the engine’s own records, one entry per model call, summed over the turn. Nothing is counted from stream items.
    • basis says where the numbers come from: engine-ledger (the per-call records) or engine-turn-totals (the engine’s own totals for the turn, which Claude Code needs; see Engines).
    • costKind is estimated for API keys, and plan-equivalent for subscriptions, where the plan pays and nothing is charged per call.
    • Unknown values are null, never guessed.
    • usage is the engine’s own figure for the turn, passed through.
  • agneta/limit appears only when a policy limit stopped the turn. maxTurns ends with ACP’s max_turn_requests; time and cost end as cancelled, with this field saying why. Limits are checked twice a second. A limit is a hard limit: if the engine hasn’t stopped the turn 10 s after Agneta cancels it (stuck in a tool, or ignoring the cancel), Agneta ends the session (which stops its engine), sends agneta/sessionStopped with stoppedBy: "limit", and answers the prompt the same way with "sessionEnded": true in this field. Load the session again to go on.
  • One turn at a time per session. A prompt while one runs is refused with -32011. To add to a running turn, steer it.
MethodEffect
agneta/steer {"sessionId", "prompt": [blocks]}Adds input to the running turn. Returns {"delivery": "accepted", "runId"}. Error -32010 when no turn is running, or it ended before the input arrived
agneta/instructions/set {"sessionId", "text", "mode": "replace" | "append", "key"?}replace (the default) sets the instructions; append adds a named part (key, default app) that a later append with the same key replaces
session/cancel (notification)Ends the running turn with cancelled
session/closeEnds the session and, if it has one of its own, its engine

Waiting for room. At most 8 turns run at once, and at most 3 per account; up to 32 more wait. A turn waits only behind earlier turns on the same account, so a busy account never holds up another. A waiting turn’s app gets agneta/queued {"sessionId", "position"}, and the prompt simply returns later. session/cancel takes a waiting turn out at once (cancelled). A prompt when the queue is full fails with -32012.

Resuming. session/load {"sessionId", "cwd", "mcpServers", "_meta"?} reopens one of the app’s earlier tasks after a close or an Agneta restart, within the history retention.

  • Pass the tool servers again, since their bearers are per session. The policy and instructions default to the original ones; _meta may set new ones, and ask for live trace delivery.
  • The engine returns to the same engine home and replays the conversation as session/updates before the result. The next turn sees the whole history, and the trace continues with the next sequence numbers.
  • The result’s _meta.agneta.resumed is true.
  • It passes the same checks as session/new: the provider (granted, not paused), the engine (still allowed), the policy against the grant, the tool servers and the cost limit.
  • Loading a session that’s already open, or another app’s, fails with -32602. A task that ran without built-in tools must be resumed without them.
  • A task resumes only on the engine that saved it, whatever the provider’s default is now. If the app may no longer use that engine, or it isn’t on this Mac any more, loading fails with -32602 and the current access in data.agneta.access; if it stores sessions differently now, with data.agneta.stateChanged {"engine", "saved", "current"}. Start a new task instead.
  • Its cost goes on from where it was, so maxCostUSD counts the whole task, and so do the trace’s turn and model-call numbers.
  • Instructions appended with agneta/instructions/set aren’t restored. Set them again after loading.

Forking. agneta/fork {"sessionId", "mcpServers", "cwd"?, "_meta"?} starts a new task with a copy of one of the app’s tasks, open or finished: for example, to ask about a run without changing it.

  • The new task has its own id, engine and trace. Its result’s _meta.agneta.forkOf names the source. Prompts to it never touch the original.
  • Its policy is _meta's if given; otherwise it’s the original’s with tools: "read".
  • It keeps the original’s instructions unless _meta["agneta/instructions"] sets new ones.
  • It passes the same checks as session/new, and like a load it needs the engine that saved the original. Its cost starts from zero: it’s a task of its own.

Pause. The user can pause an account in Agneta’s menu. Then nothing new starts on it: session/new, session/load, agneta/fork and session/prompt fail with -32013 and data.agneta.paused, and so does a prompt that was waiting in the queue. A turn already running finishes. Open sessions stay open and take turns again once the user resumes the account.

Provider limits. The engine first retries a provider’s 429 itself. If the limit holds, the turn fails with the engine’s error, and Agneta adds data.agneta.rateLimited {"account", "message", "resetsAt"}. It also sends agneta/rateLimited with the same fields and the sessionId, and Agneta’s menu marks the account. resetsAt (UTC) is read from the provider’s own words, such as “try again in 20s” or “resets 3pm”, and is null when they give none. Retry after it, or use another account.

Signed out. When the engine says the account isn’t signed in, the error keeps the engine’s code (usually -32000, ACP’s auth_required) and gains data.agneta.needsSignIn: "<account id>". Agneta’s menu asks the user to sign in again; tell the user to open Agneta.

Stopped by the user. Someone may press Stop in Agneta’s menu. The app then gets agneta/sessionStopped {"sessionId", "stoppedBy": "user"}, and the running turn ends as cancelled. Show it as stopped by the user, not as an error.

Engine stopped. If the engine process ends on its own (it crashed, or was killed), its sessions end at once: the app gets agneta/sessionStopped {"sessionId", "stoppedBy": "engine"} and a running turn fails. Resume the task with session/load, which starts a fresh engine.

Permissions

With approval: "ask-app", the engine’s session/request_permission requests reach the app with Agneta’s session id. Agneta applies two rules:

  • “Always” becomes “once”. An engine may keep an “always” answer beyond the session (OpenCode keeps it for the whole project), so Agneta answers with the matching “once” option. Where the engine offers no “once” option, the call is declined.
  • Native runners are checked first. Claude Code and Codex run their own tools, so Agneta answers each request for a built-in tool by its contract with every engine (BuiltinTools), before the app is asked: nothing built in under app-only; reading and searching (read, search) under read; also editing (edit, delete, move) under workspace; and never execute or fetch while the network is none. Kinds that run nothing of their own (think, switch_mode, other) pass; a request with no kind, or one ACP doesn’t define, is refused, since Agneta can’t tell what it would run.
  • The app’s own tools are the app’s. A request for a tool of one of the app’s MCP servers isn’t refused by that contract (Codex asks for those as execute). Agneta trusts only what the engine’s adapter vouches for: Codex’s own MCP approval marker, Claude Code’s tool names. A server can’t take a name an engine uses for its own tools (Claude Code’s workspace and acp, Codex’s codex_apps): session/new refuses it with -32602 and unenforceable: ["mcpServers"].

Every decision is in the trace’s permission records: who decided (asked-app, allowed-by-policy, refused-by-policy), the answer, and how long it took.

The trace

Agneta writes a full trace of every task (Diagnostics, format agneta/trace). An app can read its own tasks, and only those.

  • Live: with "agneta/trace": {"live": true} on session/new (or session/load), records arrive as agneta/trace {"sessionId", "records": [...]} notifications. They come in sequence order, batched every 100 ms in groups of up to 64, from meta to end. An app that reads too slowly to keep up (10,000 records waiting) gets one last agneta/trace {"sessionId", "records": [], "overflow": {"after": <seq>}}, and live delivery for that task stops; read on from after with agneta/trace/read. "include": ["acp"] adds the raw JSON-RPC frames of both connections.
  • Afterwards, or after a reconnect: agneta/trace/read {"sessionId", "after": <last seq>, "types"?: [...], "limit"?: 500} returns {"records", "next", "complete"}. Page until complete. It works for running and finished tasks within the history retention, up to 5,000 records or about 8 MB a page (always at least one record).

Every record has v, seq (gapless), t (UTC with microseconds), mono (nanoseconds since the trace was opened or resumed), task, turn and type. Secrets are masked. The record types are listed in Diagnostics.

Errors

CodeMeaning
-32000Usually the engine’s “sign in first”; with data.agneta.needsSignIn, the account needs signing in again in Agneta
-32001Not paired, or access removed (data.agneta.needsPairing)
-32002The user didn’t allow the app
-32010agneta/steer with no turn running
-32011A turn is already running in this session
-32012Too many turns waiting; try again shortly
-32013The account is paused in Agneta (data.agneta.paused); a turn already running finishes
-32014This session’s engine can’t do that (data.agneta.engine); check capabilities first
-32015What the engine needs is still downloading (data.agneta.engineDownloading: engine, received, total bytes); try again shortly
-32601Not a method Agneta offers; engines’ own methods aren’t reachable
-32602Invalid parameters. For a policy, server list or mode, data.agneta.unenforceable names the field. “Unknown session” also uses it: another app’s session, or an ended one
-32603Agneta couldn’t do it: the engine didn’t start (no answer within 60 s) or stopped, or the app disconnected meanwhile

This page is docs/APP_PROTOCOL.md in the repository, on main. History