> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How a command is read

> Which programs count as named in an agent's command, for the Command differs from declared finding.

This page describes an upcoming agent release for macOS. With that release, Quint reads each shell command an agent declares in the way set out below. Earlier agent versions read commands more loosely: for example, they count `curl` as named in `echo hello curl`, where it is only a word being printed.

When an agent runs a shell command, Quint records which programs the command names and which programs then started on the Mac. **Command differs from declared** is recorded when a watched program starts and the command did not name it. Watched programs are tools that reach the network, decode data or run scripts: `curl`, `wget`, `nc`, `ncat`, `netcat`, `base64`, `xxd`, `osascript`, and the Python, Ruby, Perl and PHP interpreters.

Quint reads the command the way zsh, the default shell on macOS, and bash both read it. Where the two would read part of a command differently, Quint does not guess: nothing from that line on counts as named, so a watched program started there is recorded as a match.

## What counts as named

A program counts as named when the command writes it where the shell starts a program:

* the first word of the command, or of each part after `&&`, `||`, `;`, `|` or a new line, after any settings written before it, such as `DEBUG=1`;
* inside `if`, `while`, `for` and `case` blocks, inside `( … )` and `{ … }`, and inside `<( … )`;
* after `sudo`, `env`, `nohup`, `nice`, `time` and similar starters, the one program they start. Quint skips the starter's own options, with the value an option takes, and the settings `sudo` and `env` take, such as `FOO=1`; the next word is the program. When that program is itself a starter, the program it starts counts too.

Some examples, each with what it names:

* `DEBUG=1 python3 x.py` names `python3`. `DEBUG=1` is a setting handed to the program, and `python3` is the program.
* `diff <(curl -s https://example.com/list) list.txt` names `diff` and `curl`. The shell runs `curl` first and hands what it downloads to `diff`, which compares it with a file.
* `sudo curl https://example.com` names `curl`, the program `sudo` starts.
* `sudo apt-get install -y curl wget` names `apt-get`. Here `curl` and `wget` are the names of packages to install, not programs that run, so neither counts.
* `sudo -u deploy python3 manage.py migrate` names `python3`. `deploy` is the value of the option `-u`, the user to run as.
* `env FOO="a b" curl https://example.com` names `curl`. The setting in quotes is one word, and `curl` is the program `env` starts.

Quotes are read as the shell reads them. `"/Applications/My Tools/python3" x.py` names `python3`: the quotes hold a folder whose name has a space in it. `"$VIRTUAL_ENV"/bin/python -m pytest`, which runs the Python inside a project's own environment folder, names `python`. A program's name used as an argument does not count: `echo "curl"` only prints the word, and `grep curl notes.txt` only searches a file for it, so neither names `curl`.

## Not counted as named

When one of these starts a watched program, the start is recorded as a match:

* a program written only inside `$( … )` or backticks, for example `TOKEN=$(curl -s …)`, which saves what `curl` downloads into a setting called `TOKEN`;
* a program given through a variable, such as `$PY x.py`, where the program is whatever the setting `PY` holds, or with a variable written directly against its name, such as `python${V} x.py`;
* after `exec` or `command`, a program written after an option, such as `prog` in `exec -a name prog`;
* after `sudo`, `env` and similar starters, a program written after a word the shell can turn into no word or into several, such as an unquoted `$USER`, `"$@"`, a `*` pattern or `{a,b}`, as in `sudo -u $USER curl …`;
* after an option with which the starter runs no program, or may not, such as `sudo -l`, which lists what you may run, or `env -S`, which runs a command written inside its value;
* a program written with `=` in front of its name, such as `=curl`, which zsh turns into the program's full path;
* a program name written with a `$'…'` escape or as `$"…"`, two ways of spelling a word in codes: `$'\x63url'` spells `curl` with a character code;
* a here-document (`<<`) whose end word holds anything other than letters, digits, `_`, `.` and `-`, written plainly or inside one pair of quotes: that line and every line after it. A here-document is a block of text written into the command, which ends at a word the command chooses, such as `EOF`;
* a line written in syntax the bash built into macOS cannot read, such as `|&`, `&>>`, `;&`, `coproc` or `{fd}>`, and every line after it. That bash is an older version, and these were added to bash later;
* a program inside `<( … )` when that is itself inside `[[ … ]]`, `${ … }` or double quotes;
* a line that holds a hidden carriage-return or null character, usually from text pasted from another system, and every line after it;
* a line Quint cannot read, for example a mistyped quote, and every line after it;
* a command longer than 64 KB, or with parts nested inside each other more than 64 deep: nothing in it counts as named.

## Inline messages

Agents often write a commit or pull-request description inline, like this:

```bash theme={"dark"}
git commit -m "$(cat <<'EOF'
Fix the login timeout
EOF
)" && python3 scripts/notify.py
```

This saves a commit with the message "Fix the login timeout", then runs a Python script.

The bash built into macOS finds the end of such a message differently from zsh when the message holds certain characters. So when an inline message holds a quote mark, an apostrophe, a backtick, a backslash, `$`, `#` or a parenthesis, nothing written on the line where the message begins, or after it, counts as named, and neither does anything joined to that line by `&&`, `||` or `|` from an earlier line. A watched program the same command starts after the message is then recorded as a match.

A message of plain words, commas and full stops, like the one above, is read past, and `python3` counts as named. If the message were `Fix the parser's timeout` instead, the apostrophe would mean that neither `git` nor `python3` counts as named, and the start of `python3` would be recorded as a match. A comment or a `case` statement inside `$( … )` is treated the same way.

To recognise this on a finding, open its **Overview**: if the program that started is written in the declared command after an inline message, this is the reason, and you can set **False positive**.

## What this check does not catch

The check compares the programs a command names with the programs that start. It does not work out which parts of a command will actually run. A program named in a part that never runs still counts as named, so another start of that program in the same command is not recorded as a match. This includes:

* a part after `false &&`, or another condition that is never true: `false && curl …` never runs `curl`, but `curl` still counts as named;
* a function the command defines under a program's name, which then runs in place of the program;
* a command that stops partway, for example on a missing file, on `exec` of a program that does not exist, or, in zsh, on a `*` pattern that matches no file or a word starting with `=` that is not a program, such as `echo ====`. zsh reads a word starting with `=` as a request for a program's full path, and stops when no such program exists, so nothing written after that point runs;
* after `sudo`, `env` and similar starters, an option Quint does not know is read as taking no value, so the word after it counts as the program even when the option takes that word as its value.

So **Command differs from declared** catches a watched program that the agent's command does not mention. It is not a guarantee about an agent that writes a program's name into its own command to hide another start of it. The program start itself is still recorded in the session's activity.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.