# Advisor configuration

## Settings files

The global file is `yaag.advisor.json` under pi's `getAgentDir()`.
`PI_CODING_AGENT_DIR` changes that directory. The project file is
`.pi/yaag.advisor.json` under the current working directory.

Project reads require `ctx.isProjectTrusted()`. Spawned Agents use the saved
trust decision. A worktree without the project file uses the global file.
Commit the project file so other users get the same settings. Do not include
credentials. These files are not the yaag Global Config or Project Config.

Use plain JSON, without comments or trailing commas. Setters write a temporary
file and atomically replace the target file. They use file mode `0600`
(owner read and write only).

This global example configures a model. Select a model that your pi installation
provides and authenticates.

<!-- embed: docs/examples/global.yaag.advisor.json -->
```json yaag.advisor.json
{
  "version": 1,
  "model": "anthropic/claude-sonnet-4-5",
  "thinking": "high",
  "maxConsultations": 3,
  "redact": ["SECRET_[A-Z0-9]+"]
}
```

This project example changes only nested trigger keys.

<!-- embed: docs/examples/project.yaag.advisor.json -->
```json yaag.advisor.json
{
  "version": 1,
  "triggers": {
    "beforeDone": {
      "minToolCalls": 5
    },
    "stuck": {
      "enabled": false
    }
  }
}
```

## Settings table

| Key | Type | Allowed values/range | Default |
| --- | --- | --- | --- |
| `version` | integer | 1 | Required, no default |
| `model` | string | `<provider/id\|off>` | Absent (effective off) |
| `thinking` | string | off, minimal, low, medium, high, xhigh | high |
| `maxConsultations` | integer | 1 to 20 | 3 |
| `maxTranscriptTokens` | integer | 10000 to 1000000 | 100000 |
| `timeoutMs` | integer | 10000 to 600000 | 120000 |
| `redact` | array of strings | Regular expression patterns | [] |
| `triggers.beforeDone.enabled` | boolean | true, false | true |
| `triggers.beforeDone.minToolCalls` | integer | 1 to 20 | 3 |
| `triggers.stuck.enabled` | boolean | true, false | true |
| `triggers.stuck.errors` | integer | 1 to 20 | 3 |
| `triggers.stuck.repeats` | integer | 1 to 20 | 2 |

`timeoutMs` uses milliseconds. `maxTranscriptTokens` limits the transcript token estimate.
`maxConsultations` limits Consultations per Prompt Cycle.
See [Consultation limits](consultations.md#consultation-limits) for counting rules.
See [Advisor Triggers](consultations.md#advisor-triggers) for the trigger conditions.

The version is required, not a default. An absent model means the effective
Advisor State is off. Nested keys use dotted names in this table, not in JSON.

## Precedence

Settings use this precedence, from highest to lowest: flag → environment → project → global → default.

Each key merges separately, including nested trigger keys. Redaction lists
combine instead: global first, then project, with exact duplicates removed.
Only `model` and `thinking` have flag and environment overrides.
See [Redaction](consultations.md#redaction) for pattern scope and privacy limits.

## Environment variables

| Variable | Key | Allowed values |
| --- | --- | --- |
| `YAAG_ADVISOR_MODEL` | `model` | `<provider/id\|off>` |
| `YAAG_ADVISOR_THINKING` | `thinking` | off, minimal, low, medium, high, xhigh |

Spawned Agents inherit environment variables, including these overrides.

## CLI flags

| Flag | Argument | Key | Description |
| --- | --- | --- | --- |
| `--advisor-model` | `<provider/id\|off>` | `model` | `The Advisor model, "<provider>/<id>" or "off", for this session.` |
| `--advisor-thinking` | `<level>` | `thinking` | `The Advisor thinking level (off, minimal, low, medium, high, xhigh) for this session.` |

CLI flags apply only to the Host Session and write no file. yaag does not
forward extension flags to spawned Agents.

## `/advisor`

<!-- embed: src/command/command-texts.ts#ADVISOR_USAGE -->
```text
Usage:
  /advisor                                         Show the advisor status.
  /advisor model <provider/id> [--project]         Set the Advisor model.
  /advisor off [--project]                         Disable the advisor.
  /advisor thinking <level> [--project]            Set the Advisor thinking level.
  /advisor triggers <beforeDone|stuck> <on|off> [--project]
                                                   Enable or disable an Advisor Trigger.
Without --project, a setter writes the global advisor settings file.
With --project, it writes the project advisor settings file.
```

With no arguments, `/advisor` shows:

- The Executor model and Advisor State, with the reason when off.
- The Advisor model and thinking level, with their sources.
- The Consultations used and limit for this Prompt Cycle.
- The enabled state and source of each Advisor Trigger.
- The tool state and the paths and read states of both settings files.

In the native state, thinking shows `n/a (native)`. The status also shows the
reason when Native Consultations are off for the session. Settings errors
appear instead of effective values.

In TUI mode, bare `/advisor` shows the status, then opens the model picker.
A selection writes the global file. `/advisor model` without an argument shows
the usage text instead.

`/advisor model <provider/id>` refuses a model that does not resolve and writes
no file in that case. Setters work in print and RPC modes too. Setters write
the global file unless you give `--project`. A spawned Agent can also write
global settings.

Setters preserve other keys and their order, including unknown keys. They insert
`version: 1` when they create a file. They refuse an existing invalid file or
unknown version. They validate the changed file before writing it. A project
setter refuses an untrusted project.

A higher-precedence override can hide a successful file change. For example,
an environment model override still applies after a global model setter succeeds.

## Validation and refresh

Settings errors disable the Advisor. Unknown keys produce warnings but do not
disable it. Invalid regular expressions fail at Consultation time, not when the
package reads settings.

Settings refresh before each Prompt Cycle and after setters. The tool selection
stays fixed within a Prompt Cycle.
See [Troubleshooting](troubleshooting.md) for notice causes and recovery steps.