# ReadUserAgents / UpdateUserAgents

ユーザーごとの常時指示書 `AGENTS.md` を読み書きするツール。`AGENTS.md` は各タスクのシステムプロンプトに自動注入される「このユーザーが常に守ってほしいこと」を書いた個人ファイル。memory（`UpdateUserMemory`）が事実の断片を貯めるのに対し、`AGENTS.md` は振る舞いの方針そのもの。

両ツールは META_TOOL（常時利用可能）。piece の `allowed_tools` に書かなくても使える。per-user 機能なので、認証済みユーザーのコンテキスト（`ctx.userId`）が必要。

## ReadUserAgents

引数なし。現在の `AGENTS.md` 全文を切り詰めずに返す。**編集前に必ず呼ぶこと** — `replace` は原文と完全一致する文字列が必要で、システムプロンプトへの注入版は 64KB で切り詰められている場合があるため。

ファイルが無い／空のときは、その旨と「`append` で新規作成できる」案内を返す（エラーではない）。

## UpdateUserAgents

`AGENTS.md` を 2 モードで編集する。書き込み前に旧版を `trash/agents-history/AGENTS.md.{timestamp}.bak` に自動退避（直近 10 件を保持）。事故時はそこから復元できる。

### パラメータ

| 名前 | 必須 | 説明 |
|---|---|---|
| `mode` | ○ | `"replace"` または `"append"` |
| `old_text` | replace時○ | 置換対象の既存文字列。**ちょうど 1 回だけ**一致する必要がある |
| `new_text` | ○ | replace の置換後テキスト／append で末尾に足すテキスト |

### mode="replace"

`old_text` を `new_text` に置き換える。コアの `Edit` ツールと同じ「一意一致」セマンティクス。

- 0 回一致 → エラー（`ReadUserAgents` で原文を確認するよう促す）
- 2 回以上一致 → エラー（前後の文脈を含めて一意にするよう促す）
- ファイルが空 → エラー（`append` を案内）

`new_text` 内の `$&` や `$1` は特殊扱いされない（リテラルとして入る）。

### mode="append"

`new_text` を末尾に追記する。既存末尾の空行を整理し、空行 1 行を挟んで足す。ファイルが空なら `new_text` がそのまま新規ファイルになる。

### 制限・エラー

- 結果が 64KB を超えると `writeUserAgentsMd` が拒否（`AGENTS.md exceeds 65536 bytes`）
- `ctx.userId` が無い（認証なし）→ エラー
- 監査ログ `user_agents_updated`（mode / バイト数 / スナップショット有無）を記録

## 典型フロー

1. `ReadUserAgents` で現在の内容を取得
2. ユーザー依頼に応じて `UpdateUserAgents({ mode: "replace", old_text: "...", new_text: "..." })` または `mode: "append"`
3. 戻り値でバイト数とスナップショット退避を確認

## 関連

- `UpdateUserMemory` / `ReadUserMemory` — 事実の断片を貯める個人 memory（`docs/tools` の該当 doc 参照）
- UI からの編集は Settings 経由（HTTP `GET/PUT/DELETE /agents-md`）