# Référence : outils intégrés

> Description neutre des outils déclarés au modèle. Un outil ne renvoie jamais d'erreur Go pour un échec ordinaire : le texte de l'échec est renvoyé au modèle comme sortie de l'outil. Chaque outil enregistre son appel dans le détecteur de boucle ; le même outil, la même entrée et la même sortie trois fois de suite ajoutent `[LOOP_DETECTED: …]` à la sortie.

## `bash`

Toujours déclaré.

| Champ | Type | Description |
|-------|------|-------------|
| `command` | chaîne | La commande shell à exécuter. |

| Aspect | Comportement |
|--------|--------------|
| Shell | `bash -c <command>`, un nouveau shell par appel, pas de stdin. |
| Répertoire de travail | Le répertoire du processus en mode terminal ; le `cwd` de la session en mode ACP. |
| Délai | 30 s ; la sortie se termine alors par `[error: 30s timeout exceeded]`. |
| Sortie | stdout et stderr fusionnés, tronqués à `maxOutput` caractères. |
| Code de sortie non nul | La sortie se termine par `[exit code: exit status N]`. |
| Affichage terminal | `🛠️  bash: <command>` avant exécution, puis jusqu'à `previewLines` lignes grisées et indentées, ou `(no output)`. |
| ACP | Appel d'outil de genre `execute` ; permission demandée avant exécution ; un refus renvoie `[command rejected by the user]` avec le statut `failed`. |

## `read_skill`

Déclaré seulement quand `skillsDir` contient au moins un skill (`<nom>.md` ou `<nom>/SKILL.md`).

| Champ | Type | Description |
|-------|------|-------------|
| `name` | chaîne | Nom du skill, exactement tel que listé dans la description de l'outil. |

| Aspect | Comportement |
|--------|--------------|
| Description | Phrase fixe suivie du catalogue : une ligne `  <name> — <description>` par skill, triées par nom. |
| Sortie | Le markdown complet de `<skillsDir>/<name>.md`, ou de `<skillsDir>/<name>/SKILL.md` s'il n'y a pas de fichier à plat, tronqué à `maxOutput`. |
| Nom inconnu | `No skill named "x". Available skills: a, b, c` |
| Sécurité des chemins | Seul le nom de base de `name` est utilisé ; pas de traversée de répertoire. |
| Affichage terminal | `📖 read_skill: <name>` ; le contenu n'est pas affiché. |
| ACP | Appel d'outil de genre `read` ; pas de dialogue de permission. |

## `read_file`

Déclaré quand `editTools: true`.

| Champ | Type | Défaut | Description |
|-------|------|--------|-------------|
| `path` | chaîne | — | Chemin du fichier, relatif au répertoire de travail. |
| `start` | entier | `0` | Première ligne (base 1) ; `0` = depuis le début. |
| `end` | entier | `0` | Dernière ligne (base 1, incluse) ; `0` = jusqu'à la fin. |
| `numbered` | booléen | `false` | Préfixe chaque ligne de son numéro. |

| Aspect | Comportement |
|--------|--------------|
| Fichier absent | `<path> does not exist. Create it with write_file` |
| Sortie | Les lignes, tronquées à `maxOutput` ; le saut de ligne final n'est conservé que si la fin du fichier est affichée. |
| ACP | Genre `read`, avec le chemin absolu comme emplacement. |

## `write_file`

Déclaré quand `editTools: true`.

| Champ | Type | Description |
|-------|------|-------------|
| `path` | chaîne | Chemin du fichier, relatif au répertoire de travail ; les répertoires parents sont créés. |
| `content` | chaîne | Le contenu entier du fichier. |

| Aspect | Comportement |
|--------|--------------|
| Fichier existant | Entièrement remplacé. |
| Contenu identique | Rien n'est écrit ; le résultat le dit. |
| Sortie | Un en-tête d'une ligne et le diff par rapport au contenu précédent. |
| ACP | Genre `edit` ; permission demandée ; le changement voyage comme un diff (diff de nouveau fichier à la création). |

## `edit_file`

Déclaré quand `editTools: true`.

| Champ | Type | Défaut | Description |
|-------|------|--------|-------------|
| `path` | chaîne | — | Chemin d'un fichier existant. |
| `edits` | tableau de `{old, new}` | — | Remplacements, tous résolus par rapport au fichier original. |
| `edits[].old` | chaîne | — | Texte exact à trouver, présent exactement une fois. |
| `edits[].new` | chaîne | — | Remplacement ; vide supprime le texte trouvé. |
| `dry_run` | booléen | `false` | Rapporte ce qui changerait, n'écrit rien. |

| Règle | Conséquence si violée |
|-------|-----------------------|
| `old` apparaît exactement une fois | Refus : introuvable, ou ambigu. |
| Deux éditions ne doivent ni se chevaucher, ni s'imbriquer, ni se répéter | Refus. |
| Les éditions sont résolues sur le texte original, jamais en cascade | — |
| Toute édition refusée | Rien n'est écrit. |

| Aspect | Comportement |
|--------|--------------|
| Sortie | Un en-tête d'une ligne (éditions appliquées, lignes ajoutées et supprimées, première ligne modifiée) et le diff avec numéros de ligne. |
| ACP | Genre `edit` ; permission demandée ; le changement voyage comme un diff avec ancien et nouveau texte. |

## Compteurs affichés après un tour

| Compteur | Compte |
|----------|--------|
| `⚙ N command(s)` | Réponses de l'outil `bash` dans le tour. |
| `📝 N file op(s)` | Réponses de `read_file`, `write_file`, `edit_file`. |
| `📖 N skill(s)` | Réponses de `read_skill`. |