See which tools Pi declares to the model

Pi declares an active tool set to the model; that set is what the model may ask for. Three inputs compose it: built-in tools, tools registered by extensions, and MCP tools. defaultTools edits the user’s selection, --tools replaces it for one invocation, and the same syntax means different things in the two places.

The default selection and its two edits

settings.md defaults defaultTools to read, bash, edit, and write. Within a settings list a plain name replaces the selection, +name adds, and -name removes, in order:

`defaultTools` list	Meaning
`["read","bash","edit","write"]`	The defaults, unchanged
`["+grep","+find","+ls"]`	Adds three search tools on top of the defaults
`["read","powershell"]`	A two-tool agent: the plain list replaces
`["-bash"]`	The defaults minus Bash
`["+codemode"]`	Adds the off-by-default codemode built-in extension tool

codemode and tool_search come from built-in extensions and are off by default; they switch on when an MCP server with that exposure needs them. A project settings file applies on top of the user file (Chapter 7 owns that merge in detail).

The one-shot override is a different syntax

On the command line, --tools replaces the whole selection, and +name / -name are rejected there:

pi --tools read,grep,find,ls --no-mcp --print "Review this project"
pi --tools read,bash,edit,write,codemode

pi --tools read,grep,find,ls --no-mcp --print "Review this project"
pi --tools read,bash,edit,write,codemode

The override lasts for that invocation (including across /reload).

The 1.0.4 exception

--tools narrows built-in, extension, and custom tools — but not MCP tools. On 1.0.4, if a server is configured, the MCP tools stay even when --tools does not name them, so --no-mcp is needed to remove them. There is no way to say “all tools except these” on the command line.

Mechanism and limitations

Documented: settings.md describes the defaults and the plain/+/− rules; the off-by-default built-in extensions are documented in extensions.md. Observed: the Chapter 7 tests assert defaultTools edit-versus-replace semantics through the real SettingsManager; headless.test.ts shows --tools narrowing an agent — a model that asks for Bash gets a failed result and nothing runs; tool-allowlist.test.ts exercises disabledBuiltinExtensions and the mcp__ naming. The MCP exception is recorded in the chapter as a 1.0.4 behaviour, so it is version-sensitive.

Declaring a tool makes it available; it does not make the model use it, and it does not make a use authorised — tools run with the operating-system permissions of the Pi process. This example shows how the declared set is composed, not what a real model does with it.

Read the chapter and the examples directory .

Understand this example

Copy this prompt into your AI tool. No code runs here.


Canonical example context
Chapter: The Built-In Tools
https://aibussin.com/books/pi/06-chapter/
Example: See which tools Pi declares to the model
https://aibussin.com/examples/pi/06-chapter/


Pi declares an **active tool set** to the model; that set is what the model may ask for.
Three inputs compose it: built-in tools, tools registered by extensions, and MCP tools.
`defaultTools` edits the user's selection, `--tools` replaces it for one invocation, and
the same syntax means different things in the two places.

## The default selection and its two edits

`settings.md` defaults `defaultTools` to `read`, `bash`, `edit`, and `write`. Within a
settings list a plain name *replaces* the selection, `+name` adds, and `-name` removes,
in order:

| `defaultTools` list | Meaning |
|---|---|
| `["read","bash","edit","write"]` | The defaults, unchanged |
| `["+grep","+find","+ls"]` | Adds three search tools on top of the defaults |
| `["read","powershell"]` | A two-tool agent: the plain list **replaces** |
| `["-bash"]` | The defaults minus Bash |
| `["+codemode"]` | Adds the off-by-default codemode built-in extension tool |

`codemode` and `tool_search` come from built-in extensions and are off by default; they
switch on when an MCP server with that exposure needs them. A project settings file
applies on top of the user file (Chapter 7 owns that merge in detail).

## The one-shot override is a different syntax

On the command line, `--tools` **replaces the whole selection**, and `+name` / `-name`
are rejected there:

```sh
pi --tools read,grep,find,ls --no-mcp --print "Review this project"
pi --tools read,bash,edit,write,codemode
```

The override lasts for that invocation (including across `/reload`).

## The 1.0.4 exception

`--tools` narrows built-in, extension, and custom tools — but **not** MCP tools. On
1.0.4, if a server is configured, the MCP tools stay even when `--tools` does not name
them, so `--no-mcp` is needed to remove them. There is no way to say "all tools except
these" on the command line.

## Mechanism and limitations

**Documented:** `settings.md` describes the defaults and the plain/+/− rules; the
off-by-default built-in extensions are documented in `extensions.md`. **Observed:** the
Chapter 7 tests assert `defaultTools` edit-versus-replace semantics through the real
`SettingsManager`; `headless.test.ts` shows `--tools` narrowing an agent — a model that
asks for Bash gets a failed result and nothing runs; `tool-allowlist.test.ts` exercises
`disabledBuiltinExtensions` and the `mcp__` naming. The MCP exception is recorded in the
chapter as a 1.0.4 behaviour, so it is version-sensitive.

Declaring a tool makes it *available*; it does not make the model *use* it, and it does
not make a use *authorised* — tools run with the operating-system permissions of the Pi
process. This example shows how the declared set is composed, not what a real model does
with it.

[Read the chapter](https://github.com/ernanhughes/pi/tree/main/content/books/pi/06-chapter.md)
and the [examples directory](https://github.com/ernanhughes/pi/tree/main/examples).
<!-- pi-source: examples/ch07-settings/settings.test.ts sha256=4c67a142c18fb048490cc0832393396fef4a484b9a82ccdd93f47dd2f0c44fad -->
<!-- pi-source: examples/ch32-headless/headless.test.ts sha256=fe56986245ecaf340e8ffe1a441eb02911a6b36dbb8f319962f60d4db6b05a19 -->
<!-- pi-source: examples/ch21-mcp/tool-allowlist.test.ts sha256=f0b31efe6d1d65158fbeb0e4e71cb8003adfa323f0303b1c5ac3e2cb701e0ab5 -->

Explain how this implementation demonstrates the chapter's mechanism, its expected outcome and its limitations.
Distinguish documented behaviour, observed behaviour and proposed choices. External AI may not be able to access these URLs, especially localhost or private previews. Use the source supplied here; ask for missing material rather than inventing it.

Apply this example

Copy this prompt into your AI tool. No code runs here.


Canonical example context
Chapter: The Built-In Tools
https://aibussin.com/books/pi/06-chapter/
Example: See which tools Pi declares to the model
https://aibussin.com/examples/pi/06-chapter/


Pi declares an **active tool set** to the model; that set is what the model may ask for.
Three inputs compose it: built-in tools, tools registered by extensions, and MCP tools.
`defaultTools` edits the user's selection, `--tools` replaces it for one invocation, and
the same syntax means different things in the two places.

## The default selection and its two edits

`settings.md` defaults `defaultTools` to `read`, `bash`, `edit`, and `write`. Within a
settings list a plain name *replaces* the selection, `+name` adds, and `-name` removes,
in order:

| `defaultTools` list | Meaning |
|---|---|
| `["read","bash","edit","write"]` | The defaults, unchanged |
| `["+grep","+find","+ls"]` | Adds three search tools on top of the defaults |
| `["read","powershell"]` | A two-tool agent: the plain list **replaces** |
| `["-bash"]` | The defaults minus Bash |
| `["+codemode"]` | Adds the off-by-default codemode built-in extension tool |

`codemode` and `tool_search` come from built-in extensions and are off by default; they
switch on when an MCP server with that exposure needs them. A project settings file
applies on top of the user file (Chapter 7 owns that merge in detail).

## The one-shot override is a different syntax

On the command line, `--tools` **replaces the whole selection**, and `+name` / `-name`
are rejected there:

```sh
pi --tools read,grep,find,ls --no-mcp --print "Review this project"
pi --tools read,bash,edit,write,codemode
```

The override lasts for that invocation (including across `/reload`).

## The 1.0.4 exception

`--tools` narrows built-in, extension, and custom tools — but **not** MCP tools. On
1.0.4, if a server is configured, the MCP tools stay even when `--tools` does not name
them, so `--no-mcp` is needed to remove them. There is no way to say "all tools except
these" on the command line.

## Mechanism and limitations

**Documented:** `settings.md` describes the defaults and the plain/+/− rules; the
off-by-default built-in extensions are documented in `extensions.md`. **Observed:** the
Chapter 7 tests assert `defaultTools` edit-versus-replace semantics through the real
`SettingsManager`; `headless.test.ts` shows `--tools` narrowing an agent — a model that
asks for Bash gets a failed result and nothing runs; `tool-allowlist.test.ts` exercises
`disabledBuiltinExtensions` and the `mcp__` naming. The MCP exception is recorded in the
chapter as a 1.0.4 behaviour, so it is version-sensitive.

Declaring a tool makes it *available*; it does not make the model *use* it, and it does
not make a use *authorised* — tools run with the operating-system permissions of the Pi
process. This example shows how the declared set is composed, not what a real model does
with it.

[Read the chapter](https://github.com/ernanhughes/pi/tree/main/content/books/pi/06-chapter.md)
and the [examples directory](https://github.com/ernanhughes/pi/tree/main/examples).
<!-- pi-source: examples/ch07-settings/settings.test.ts sha256=4c67a142c18fb048490cc0832393396fef4a484b9a82ccdd93f47dd2f0c44fad -->
<!-- pi-source: examples/ch32-headless/headless.test.ts sha256=fe56986245ecaf340e8ffe1a441eb02911a6b36dbb8f319962f60d4db6b05a19 -->
<!-- pi-source: examples/ch21-mcp/tool-allowlist.test.ts sha256=f0b31efe6d1d65158fbeb0e4e71cb8003adfa323f0303b1c5ac3e2cb701e0ab5 -->

Help me adapt this example to my project. First identify the mechanism. Ask only for project details necessary to assess applicability. Prefer the smallest useful implementation. Explain adaptations before making changes and define verification. The original example does not prove an adaptation works.
Distinguish documented behaviour, observed behaviour and proposed choices. External AI may not be able to access these URLs, especially localhost or private previews. Use the source supplied here; ask for missing material rather than inventing it.