sync: update from private repo (2ef0fa6)

docs/tools/updateuseragents.md

@@ -0,0 +1,54 @@
+# 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`）