에이전트 선택적 탐색 구조 개선과 경고 정리 반영

- claude-code 선택적 탐색 흐름을 참고해 Cowork/Code 시스템 프롬프트에서 folder_map 상시 선행 지시를 완화하고 glob/grep 기반 좁은 탐색을 우선하도록 조정함

- FolderMapTool 기본 depth를 2로, include_files 기본값을 false로 낮추고 MultiReadTool 최대 파일 수를 8개로 줄여 초기 과탐색 폭을 보수적으로 조정함

- AgentLoopExplorationPolicy partial을 추가해 탐색 범위 분류, broad-scan corrective hint, exploration_breadth 성능 로그를 연결함

- AgentLoopService에 탐색 범위 가이드 주입과 실행 중 탐색 폭 추적을 추가하고, 좁은 질문에서 반복적인 folder_map/대량 multi_read를 교정하도록 정리함

- DocxToHtmlConverter nullable 경고를 수정해 Release 빌드 경고 0 / 오류 0 기준을 다시 충족함

- README와 docs/DEVELOPMENT.md에 2026-04-09 10:36 (KST) 기준 개발 이력을 반영함

src/AxCopilot/Services/Agent/PlaybookTool.cs

@@ -63,9 +63,9 @@ public class PlaybookTool : IAgentTool
 
     public async Task<ToolResult> ExecuteAsync(JsonElement args, AgentContext context, CancellationToken ct = default)
     {
-        if (!args.TryGetProperty("action", out var actionEl))
+        if (!args.SafeTryGetProperty("action", out var actionEl))
             return ToolResult.Fail("action이 필요합니다.");
-        var action = actionEl.GetString() ?? "";
+        var action = actionEl.SafeGetString() ?? "";
 
         if (string.IsNullOrEmpty(context.WorkFolder))
             return ToolResult.Fail("작업 폴더가 설정되지 않았습니다.");
@@ -84,8 +84,8 @@ public class PlaybookTool : IAgentTool
 
     private static async Task<ToolResult> SavePlaybook(JsonElement args, string playbookDir, CancellationToken ct)
     {
-        var name = args.TryGetProperty("name", out var n) ? n.GetString() ?? "" : "";
-        var description = args.TryGetProperty("description", out var d) ? d.GetString() ?? "" : "";
+        var name = args.SafeTryGetProperty("name", out var n) ? n.SafeGetString() ?? "" : "";
+        var description = args.SafeTryGetProperty("description", out var d) ? d.SafeGetString() ?? "" : "";
 
         if (string.IsNullOrWhiteSpace(name))
             return ToolResult.Fail("플레이북 name이 필요합니다.");
@@ -94,11 +94,11 @@ public class PlaybookTool : IAgentTool
 
         // steps 파싱
         var steps = new List<string>();
-        if (args.TryGetProperty("steps", out var stepsEl) && stepsEl.ValueKind == JsonValueKind.Array)
+        if (args.SafeTryGetProperty("steps", out var stepsEl) && stepsEl.ValueKind == JsonValueKind.Array)
         {
             foreach (var step in stepsEl.EnumerateArray())
             {
-                var s = step.GetString();
+                var s = step.SafeGetString();
                 if (!string.IsNullOrWhiteSpace(s))
                     steps.Add(s);
             }
@@ -109,11 +109,11 @@ public class PlaybookTool : IAgentTool
 
         // tools_used 파싱
         var toolsUsed = new List<string>();
-        if (args.TryGetProperty("tools_used", out var toolsEl) && toolsEl.ValueKind == JsonValueKind.Array)
+        if (args.SafeTryGetProperty("tools_used", out var toolsEl) && toolsEl.ValueKind == JsonValueKind.Array)
         {
             foreach (var tool in toolsEl.EnumerateArray())
             {
-                var t = tool.GetString();
+                var t = tool.SafeGetString();
                 if (!string.IsNullOrWhiteSpace(t))
                     toolsUsed.Add(t);
             }
@@ -192,10 +192,10 @@ public class PlaybookTool : IAgentTool
 
     private static async Task<ToolResult> DescribePlaybook(JsonElement args, string playbookDir, CancellationToken ct)
     {
-        if (!args.TryGetProperty("id", out var idEl))
+        if (!args.SafeTryGetProperty("id", out var idEl))
             return ToolResult.Fail("플레이북 id가 필요합니다.");
 
-        var id = idEl.ValueKind == JsonValueKind.Number ? idEl.GetInt32() : int.TryParse(idEl.GetString(), out var parsed) ? parsed : -1;
+        var id = idEl.ValueKind == JsonValueKind.Number ? idEl.GetInt32() : int.TryParse(idEl.SafeGetString(), out var parsed) ? parsed : -1;
         var playbook = await FindPlaybookById(playbookDir, id, ct);
 
         if (playbook == null)
@@ -222,10 +222,10 @@ public class PlaybookTool : IAgentTool
 
     private static ToolResult DeletePlaybook(JsonElement args, string playbookDir)
     {
-        if (!args.TryGetProperty("id", out var idEl))
+        if (!args.SafeTryGetProperty("id", out var idEl))
             return ToolResult.Fail("삭제할 플레이북 id가 필요합니다.");
 
-        var id = idEl.ValueKind == JsonValueKind.Number ? idEl.GetInt32() : int.TryParse(idEl.GetString(), out var parsed) ? parsed : -1;
+        var id = idEl.ValueKind == JsonValueKind.Number ? idEl.GetInt32() : int.TryParse(idEl.SafeGetString(), out var parsed) ? parsed : -1;
 
         if (!Directory.Exists(playbookDir))
             return ToolResult.Fail("저장된 플레이북이 없습니다.");