diff options
| author | tanaka takashi <isazaka@gmail.com> | 2026-08-10 19:38:55 +0900 |
|---|---|---|
| committer | tanaka takashi <isazaka@gmail.com> | 2026-08-10 19:38:55 +0900 |
| commit | e8b625e22f343d75e1b50d1634b4ab06899d060b (patch) | |
| tree | 80b8d5d045f9402884a75cf2c74d1e15cb3ba9aa /doc | |
| parent | f2001b0c5a0b35e052ba62ef4f2e19bcc64fd870 (diff) | |
feat(tools): add dir internal tool for directory operations
新規Internal Tool `dir` を追加し、ディレクトリの作成・削除・一覧取得を
可能にした。file_editの拡張ではなく独立toolとして実装し、LLMが
「ディレクトリ操作はdir tool」と直感的に判断できるようにした。
追加した機能:
- dir tool (6番目のInternal Tool、MCP非公開)
- mkdir: Write capability要求、Directory.CreateDirectory()で親ディレクトリも含めて作成
- rmdir: Delete capability要求、空ディレクトリのみ削除(非空はToolValidationExceptionで拒否)
- list: Read capability要求、直下エントリ一覧を返す
設計判断:
- file_edit拡張ではなく新規toolとした理由: ツール名から機能が推測しやすく、
LLMが直感的に選択できるため
- rmdirを空ディレクトリのみに制限した理由: rollback時の内容復元の複雑さを排除、
MemoryBackupLimit超過リスクなし、安全側
- mkdir/rmdirは既存のPathPolicy/ACL/Journal/Recovery枠組みを利用
- root継承ACE方式のため新規作成ディレクトリは自動的に親のACEを継承、追加ACL操作不要
変更対象:
- InternalToolCatalog.cs: dir定義追加 (5→6 tool)
- InternalToolDispatcher.cs: FakeInternalToolBackendの効果判定にdir追加
- InternalToolValidator.cs: dir用コメント追記
- WindowsToolBackend.cs: DirectoryOp()メソッド実装
- TransactionalFileEditor.cs: Mkdir()/Rmdir() transaction +
DirectoryMkdirTransaction/DirectoryRmdirTransaction クラス追加
- RecoveryManager.cs: dir.mkdir/dir.rmdir crash recovery追加
- Specifications.md: FS-06追加
- Design.md: 6群表更新、§7.6 dir追加、5群→6群参照更新
テスト:
- InternalToolTests.cs: dir単体テスト、catalog 6群検証、malformed args拒否
- SecurityPolicyTests.cs: mkdir/rmdir/list/許可外deny テスト追加
- PromptAndRuntimeTests.cs: tool count 5→6
- OllamaClientTests.cs: tool catalog配列長 5→6
検証結果:
- Release build: 警告0、エラー0
- Planner tests: 10/10 PASS、skip 0
- Core tests: 56/56 PASS、skip 0
- MCP経由での動作確認: mkdir/list/rmdir/file_edit すべて正常
- Python実行確認: dir mkdir + file_edit + process_run でfib(1)〜fib(10)が正常出力
- Release Bundle publish済み
既知の運用上の知見:
- uv venvのpyvenv.cfgのhomeがjunctionを指す場合、CanonicalPath.Resolveが
reparse pointとして拒否する。実体パスへ書き換えるか、実体ディレクトリを
agent.yamlのread/executeに追加する必要がある
- venvのpython.exeはuv trampolineで子プロセスを生成するため、
sandboxのchild-process制限で拒否される。pyvenv.cfgが指す実体python.exeを
直接起動する必要がある
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Design.md | 16 | ||||
| -rw-r--r-- | doc/Specifications.md | 1 |
2 files changed, 14 insertions, 3 deletions
diff --git a/doc/Design.md b/doc/Design.md index a908441..101a896 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -249,7 +249,7 @@ overrideはTask objectにcopyし、global configurationを変更しない。Sess - 既定上限は4画像、1画像10 MiB、request合計20 MiBとする。 - model capability確認でVision非対応と判定した場合はOllama呼出し前にlocalized error。能力確認不能時は呼出しを行い、Ollama errorを正規化して返す。 ### 6.5 Tool calling -Ollamaに公開するInternal Toolは次の5群に固定する。個々のOS command (`grep.exe`等) をtoolとして増殖させない。 +Ollamaに公開するInternal Toolは次の6群に固定する。個々のOS command (`grep.exe`等) をtoolとして増殖させない。 | Tool | 責務 | 主なoperation | | --- | --- | --- | | file_search | 検索 | glob / name / text / regex / tail相当 | @@ -257,6 +257,7 @@ Ollamaに公開するInternal Toolは次の5群に固定する。個々のOS com | file_edit | 編集 | overwrite / patch / atomic_replace / delete | | process_run | 承認済Process実行 | exe + args + cwd + timeout | | task_update | TaskGraph更新 | add / dependency / state / estimate | +| dir | ディレクトリ操作 | mkdir / rmdir / list | --- ## 7. Internal Tool Schema設計 ### 7.1 file_search @@ -316,7 +317,16 @@ Ollamaに公開するInternal Toolは次の5群に固定する。個々のOS com } ``` PlannerがDAG、不変条件、completed immutable、max_tasksを再検査してから適用する。 -### 7.6 ToolUseGuard +### 7.6 dir +```json +{"path":"string","operation":"mkdir|rmdir|list"} +``` +- mkdir は Write capabilityを要求し、`Directory.CreateDirectory` で親ディレクトリも含めて作成する。 +- rmdir は Delete capabilityを要求し、**空ディレクトリのみ**削除する。非空の場合は `ToolValidationException` で拒否する。内容復元の複雑さとMemoryBackupLimit超過リスクを排除するため、再帰削除は行わない。 +- list は Read capabilityを要求し、直下のエントリ一覧を返す。外部効果ではない。 +- 既存の PathPolicy / CanonicalPath / TaskAclManager (root継承ACE) / TaskResourceJournal / RecoveryManager 枠組みを利用する。新規作成ディレクトリは親の継承ACEを自動取得するため追加ACL操作は不要。 +- mkdir後crash → ディレクトリ削除、rmdir後crash → 空ディレクトリ再作成、でRecoveryする。 +### 7.7 ToolUseGuard Taskには `requires_external_effect` をPlanner内部属性として持たせる。trueのTaskで、当該iteration中のtool callが0かつ完了証拠がない場合、LLMへ「未実行」を示すsystem-generated observationを追加して再試行する。同一失敗fingerprintが5回に達したらTaskをfailedにする。ただし、Policy EngineのdenyおよびSandbox backendの`UnauthorizedAccessException`は`RetryAllowed=false`のterminal Tool resultへ変換する。Runtimeはobserverへ結果を1回記録した直後にTaskをfailedへ遷移させ、LLMへ再投入しない。 --- ## 8. Token Planner設計 @@ -711,7 +721,7 @@ errorは内部codeとlocalized messageを分離し、ログ/auditにはcode、MC ## 22. Codex実装制約 - 新規NuGet dependencyを勝手に追加しない。追加時は標準ライブラリで不能な理由を示す。 - MCP Toolを `agent_run` / `agent_status` 以外に増やさない。 -- Internal ToolをOSコマンド名ごとに増やさず、定義済み5群に収める。 +- Internal ToolをOSコマンド名ごとに増やさず、定義済み6群に収める。 - Legacy HTTP+SSE transport、WebSocket、独自transportを追加しない。 - Streamable HTTPをnon-loopbackへbind可能にしない。 - 認証/TLSを「便利だから」という理由でv1へ追加しない。 diff --git a/doc/Specifications.md b/doc/Specifications.md index cc04762..5d21037 100644 --- a/doc/Specifications.md +++ b/doc/Specifications.md @@ -343,6 +343,7 @@ Context要約を開始する利用率閾値は設定可能でなければならã | FS-03 | symlink、junction、その他reparse pointを経由した許可範囲外への脱出を禁止する。 | | FS-04 | write権限だけではdeleteできない。 | | FS-05 | ACLとAppContainerの両方で強制可能な形にする。 | +| FS-06 | ディレクトリ作成 (mkdir) はwrite権限で許可する。ディレクトリ削除 (rmdir) はdelete権限で許可するが、空ディレクトリのみとする。ディレクトリ列挙 (list) はread権限で許可する。 | ### 11.3 Process Policy |
