Persisted settings — Haskell Agent

On this page

Locations and ownership
Root fields
Saved model objects
Model inheritance and worktrees
Account selection records
Malformed files and recovery

Interactive choices are saved separately from config.json and models.json. Prefer the corresponding command or selector to changing these records manually. In particular, a remembered model is not a model definition, and an account selection record is not a credential.

Locations and ownership

Location	Purpose
`<checkout>/.haskell-agent/settings.json`	Checkout approval policy, concurrent-agent limit, remembered model and provider account selections
`~/.haskell-agent/settings.json`	User-level remembered model, title-model selection and mouse-capture preference

The checkout root is the current Git working tree's top level, including a linked worktree. Outside Git it is the working directory. Paths are canonicalized. Do not copy a full-access checkout policy into an untrusted repository.

Root fields

Field	Type / default	Meaning
`version`	Integer / 1	Written schema version. Preserve it; this loader does not enforce the same version rejection as machine configuration.
`autoApprove`	Boolean / false	Persistent checkout approval policy, controlled by /permissions or /always-approve
`mouseCapture`	Boolean / true	User terminal preference for fullscreen mouse capture
`lastModel`	Optional model object / absent	Last selected model; can inherit from the primary clone and user settings
`titleModel`	Optional model object or supported string / absent	User-level automatic naming model; absent restores automatic selection
`lastAccounts`	Account object array / empty	Remembered account identity per provider; excludes secrets and quota responses
`maxConcurrentAgents`	Optional integer / absent	Project limit below explicit CLI priority and above machine priority; use a positive value

For a new checkout settings file, this example keeps ordinary approval prompts enabled and requests a concurrency limit of three. Merge fields into an existing file rather than replacing its other preferences:

{
  "version": 1,
  "autoApprove": false,
  "maxConcurrentAgents": 3
}

Saved model objects

lastModel and an explicitly pinned titleModel use the following shape. These values are normally written by the model picker:

Field	Rule
`provider`	Required supported provider identifier
`model`	Required nonblank local model identifier
`connection`	Defaults to provider identifier; must be nonblank
`transportModel`	Defaults to model; records the wire identifier
`dialect`	Defaults to the provider's legacy dialect; explicit values must be recognized and compatible

Do not paste a models.json entry here: that schema uses id and configuration metadata instead. Use /model NAME to select a catalog entry. Use /title-model NAME to pin naming, or /title-model --auto to clear it. The special title string apple-foundationmodel selects supported on-device Apple naming; ordinary catalog models use the object form.

Model inheritance and worktrees

An existing checkout lastModel wins.
If absent, use the primary clone's remembered model.
If still absent, use the user-level remembered model.

Only this model preference is filled in by that inheritance procedure. It does not merge primary-clone auto-approval or account arrays into a worktree. A top-level interactive model switch writes the checkout, primary clone when different, and user preference. Startup, resume, and delegated/session-local switches are not that persistence event. Explicit launch/session choices still determine the current invocation.

To forget an inherited model completely, stop affected sessions and remove only lastModel from each applicable settings location. Removing it from the worktree alone may simply reveal the primary-clone preference. Choosing another model interactively is usually simpler.

Account selection records

Field in lastAccounts	Rule
`provider`	Required recognized provider identifier
`selectionId`	Required nonblank credential-source selection identifier
`accountId`	String, default empty; provider account identity

The successful choice replaces the remembered entry for that provider. Never put a token in either identifier. To reset a preference, stop the session and remove that provider's entry, preserving the others. This neither disconnects the account nor revokes its provider token. Use the login interface to manage credentials separately.

Malformed files and recovery

A missing, unreadable, or invalid settings file yields defaults. Within an otherwise decodable file, malformed or obsolete model selections are discarded independently, and invalid account entries are removed from the decoded list. This is intentionally different from the explicit machine-configuration errors.

Stop sessions that could save preferences while you repair the file.
Keep a private backup and inspect the exact checkout/user location.
Correct one field or restore the backup; do not delete credential stores.
Restart, inspect /permissions and /session-info, then verify the intended model with a small task.

If a remembered choice vanished, inspect JSON types and the separate model catalog before assuming a provider account was deleted. If a model reappears, check inheritance rather than repeatedly removing the wrong file.