claude-nexus 0.24.1 → 0.25.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "claude-nexus",
       "description": "Agent orchestration plugin for Claude Code. Injects optimized context per agent role with minimal overhead.",
-      "version": "0.24.1",
+      "version": "0.25.0",
       "author": {
         "name": "kih"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nexus",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Agent orchestration plugin for Claude Code — optimized context injection per role",
   "author": {
     "name": "kih"

package/README.en.md

@@ -88,12 +88,13 @@ Typical flow: `[plan]` to discuss and align → `[d]` to decide (within plan)
 
 Claude-callable tools exposed by the Nexus MCP server.
 
-### Core (12 tools)
+### Core (11 tools)
 
 | Tool | Purpose |
 |------|---------|
 | `nx_context` | Current session state lookup (branch, tasks, plan) |
 | `nx_task_list/add/update/close` | Task management + history.json archiving |
+| `nx_history_search` | Search past plan/task cycles (topic/decision query, last N) |
 | `nx_artifact_write` | Save artifacts (branch-isolated) |
 | `nx_plan_start` | Start plan session (topic + issues + research summary) |
 | `nx_plan_status` | Query plan state |
@@ -127,11 +128,12 @@ Nexus registers a single Gate module as a Claude Code hook.
 
 | Event | Role |
 |-------|------|
-| `SessionStart` | Initialize `.nexus/` structure, reset agent-tracker |
+| `SessionStart` | Initialize `.nexus/` structure, reset agent-tracker, write `runtime.json` (teams_enabled), init `tool-log.jsonl` |
 | `UserPromptSubmit` | Tag detection → mode activation + TASK_PIPELINE injection + additionalContext guidance |
 | `PreToolUse` | Edit/Write: blocks when incomplete tasks exist |
-| `SubagentStart` | Auto-inject role-filtered core knowledge index (lazy-read) |
-| `SubagentStop` | Record agent completion. Warn if owned tasks remain incomplete |
+| `PostToolUse` | On Edit/Write/NotebookEdit, append subagent file edits to `tool-log.jsonl` (only when agent_id present) |
+| `SubagentStart` | Auto-inject role-filtered core knowledge index (lazy-read). Upsert `resume_count`/`last_resumed_at` when agent_id recurs |
+| `SubagentStop` | Record agent completion + aggregate `tool-log.jsonl` → inject `files_touched` into agent-tracker entry |
 | `Stop` | Blocks exit with pending tasks. Forces nx_task_close when all completed |
 | `PostCompact` | Snapshot session state (mode, plan, agent status) |
 
@@ -166,8 +168,29 @@ Runtime state is stored under `.nexus/state/` and is excluded from git.
 .nexus/state/
 ├── tasks.json          ← Task list ([run] cycle)
 ├── plan.json           ← Planning session ([plan] cycle)
-├── agent-tracker.json  ← Subagent lifecycle tracking
+├── agent-tracker.json  ← Subagent lifecycle tracking (resume_count, files_touched)
+├── runtime.json        ← teams_enabled flag + session_started_at + plugin_version
+├── tool-log.jsonl      ← Subagent Edit/Write/NotebookEdit call log (append-only)
 └── artifacts/          ← Artifacts
 ```
 
 </details>
+
+<details>
+<summary>Subagent Resume (resume_tier)</summary>
+
+Completed subagents can be resumed within the same parent session via `SendMessage`. Each agent's `resume_tier` frontmatter classifies its policy.
+
+| Tier | Policy | Agents |
+|------|--------|--------|
+| **persistent** | Default-resume within same issue, Lead opt-in across issues, forced fresh on counter-evidence/review | architect, designer, postdoc, strategist, researcher |
+| **bounded** | Conditional resume only when working on the same artifact (file); forced fresh on loop/feedback cycles | engineer, writer |
+| **ephemeral** | Always fresh spawn (preserves verification independence) | tester, reviewer |
+
+**Activation requirement**: environment variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. When absent, automatically falls back to fresh spawn (no errors).
+
+**Rationale**: Agents are classified by their dominant work surface. Reasoning surface (exists only in agent context) → `persistent` (HOW + Researcher). Mixed with artifact surface (persisted to filesystem) → `bounded` (Engineer, Writer). Verification independence as quality metric → `ephemeral` (Tester, Reviewer). See `.nexus/memory/persistence-surface-theory.md` for details.
+
+**Tracking**: `PostToolUse` hook appends subagent file edits to `tool-log.jsonl` → `SubagentStop` aggregates them into `files_touched` on `agent-tracker.json` → Lead uses this for bounded-tier conditional resume decisions.
+
+</details>

package/README.md

@@ -75,12 +75,13 @@ claude plugin install claude-nexus@nexus
 
 Claude가 직접 호출하는 도구입니다.
 
-### Core (12개)
+### Core (11개)
 
 | 도구 | 용도 |
 |------|------|
 | `nx_context` | 현재 세션 상태 조회 (브랜치, 태스크, 플랜) |
 | `nx_task_list/add/update/close` | `.nexus/state/tasks.json` 기반 태스크 관리 + `.nexus/history.json` 아카이브 |
+| `nx_history_search` | 과거 plan/task 사이클 검색 (topic/decision 검색, 최근 N개) |
 | `nx_artifact_write` | 팀 산출물 저장 (`.nexus/state/artifacts/`) |
 | `nx_plan_start` | 플랜 세션 시작 (토픽 + 논점 + 리서치 요약 등록) |
 | `nx_plan_status` | 플랜 상태 조회 |
@@ -114,11 +115,12 @@ Gate 단일 모듈로 동작합니다.
 
 | 이벤트 | 역할 |
 |--------|------|
-| `SessionStart` | `.nexus/` 구조 초기화, agent-tracker 리셋 |
+| `SessionStart` | `.nexus/` 구조 초기화, agent-tracker 리셋, `runtime.json` 기록 (teams_enabled), `tool-log.jsonl` 초기화 |
 | `UserPromptSubmit` | 태그 감지 → 모드 활성화 + TASK_PIPELINE 주입 + additionalContext 안내 |
 | `PreToolUse` | Edit/Write: tasks.json 미완료 시 차단 |
-| `SubagentStart` | 에이전트 역할별 코어 지식 인덱스 자동 주입 (lazy-read) |
-| `SubagentStop` | 에이전트 완료 기록. 미완료 태스크 경고 |
+| `PostToolUse` | Edit/Write/NotebookEdit 호출 시 서브에이전트의 파일 수정을 `tool-log.jsonl`에 append (agent_id 있을 때만) |
+| `SubagentStart` | 에이전트 역할별 코어 지식 인덱스 자동 주입 (lazy-read). 기존 agent_id 재발 시 `resume_count`/`last_resumed_at` upsert |
+| `SubagentStop` | 에이전트 완료 기록 + `tool-log.jsonl` 집계 → `files_touched` 주입 |
 | `Stop` | pending 태스크 있으면 종료 차단. all completed면 nx_task_close 강제 |
 | `PostCompact` | 세션 상태 스냅샷 (모드, 플랜, 에이전트 현황) |
 
@@ -153,8 +155,29 @@ Gate 단일 모듈로 동작합니다.
 .nexus/state/
 ├── tasks.json          ← 태스크 목록 ([run] 사이클)
 ├── plan.json           ← 플랜 세션 ([plan] 사이클)
-├── agent-tracker.json  ← 서브에이전트 라이프사이클
+├── agent-tracker.json  ← 서브에이전트 라이프사이클 (resume_count, files_touched 포함)
+├── runtime.json        ← teams_enabled 플래그 + session_started_at + plugin_version
+├── tool-log.jsonl      ← 서브에이전트 Edit/Write/NotebookEdit 호출 로그 (append-only)
 └── artifacts/          ← 산출물
 ```
 
 </details>
+
+<details>
+<summary>에이전트 Resume (resume_tier)</summary>
+
+같은 부모 세션 내에서 종료된 서브에이전트를 `SendMessage`로 재개할 수 있습니다. 에이전트별 `resume_tier` frontmatter로 정책을 분류합니다.
+
+| Tier | 정책 | 에이전트 |
+|------|------|---------|
+| **persistent** | 같은 이슈 내 default-resume, 이슈 간 Lead 명시적 opt-in, 반증/재검토는 강제 fresh | architect, designer, postdoc, strategist, researcher |
+| **bounded** | 같은 artifact(파일) 연속 작업 시 conditional-resume, loop/feedback 사이클은 강제 fresh | engineer, writer |
+| **ephemeral** | 항상 fresh spawn (검증 독립성 보장) | tester, reviewer |
+
+**활성화 요구사항**: 환경 변수 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. 미감지 시 자동 fresh spawn fallback (에러 없음).
+
+**이론 근거**: 에이전트의 본질적 작업 층위를 두 surface로 구분합니다. Reasoning surface(에이전트 컨텍스트에만 존재)가 지배적인 HOW/Researcher는 `persistent`, Artifact surface(파일 시스템에 persist)에 걸친 Engineer/Writer는 `bounded`, 검증 독립성이 품질 지표인 Tester/Reviewer는 `ephemeral`. 자세한 내용은 `.nexus/memory/persistence-surface-theory.md`.
+
+**연계 추적**: `PostToolUse` 훅이 서브에이전트의 파일 수정을 `tool-log.jsonl`에 append → `SubagentStop`이 집계하여 `agent-tracker.json`의 `files_touched`에 주입 → Lead가 bounded tier 조건부 resume 판단에 활용.
+
+</details>

package/VERSION

@@ -1 +1 @@
-0.24.1
+0.25.0

package/agents/architect.md

@@ -8,6 +8,7 @@ disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_tas
 tags: [architecture, design, review, technical]
 alias_ko: 아키텍트
 category: how
+resume_tier: persistent
 ---
 
 <role>

package/agents/designer.md

@@ -8,6 +8,7 @@ disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_tas
 tags: [design, ux, ui, interaction, experience]
 alias_ko: 디자이너
 category: how
+resume_tier: persistent
 ---
 
 <role>

package/agents/engineer.md

@@ -8,6 +8,7 @@ disallowedTools: [mcp__plugin_claude-nexus_nx__nx_task_add]
 tags: [implementation, coding, debugging]
 alias_ko: 엔지니어
 category: do
+resume_tier: bounded
 ---
 
 <role>

package/agents/postdoc.md

@@ -8,6 +8,7 @@ disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_tas
 tags: [research, synthesis, methodology]
 alias_ko: 포닥
 category: how
+resume_tier: persistent
 ---
 
 <role>

package/agents/researcher.md

@@ -8,6 +8,7 @@ disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_tas
 tags: [research, investigation, web-search, analysis]
 alias_ko: 리서처
 category: do
+resume_tier: persistent
 ---
 
 <role>

package/agents/reviewer.md

@@ -8,6 +8,7 @@ disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_tas
 tags: [review, verification, fact-checking, content, quality]
 alias_ko: 리뷰어
 category: check
+resume_tier: ephemeral
 ---
 
 <role>

package/agents/strategist.md

@@ -8,6 +8,7 @@ disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_tas
 tags: [strategy, business, market, competitive, positioning]
 alias_ko: 전략가
 category: how
+resume_tier: persistent
 ---
 
 <role>

package/agents/tester.md

@@ -8,6 +8,7 @@ disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_tas
 tags: [verification, testing, security, quality]
 alias_ko: 테스터
 category: check
+resume_tier: ephemeral
 ---
 
 <role>

package/agents/writer.md

@@ -8,6 +8,7 @@ disallowedTools: [mcp__plugin_claude-nexus_nx__nx_task_add]
 tags: [writing, documentation, communication, presentation]
 alias_ko: 라이터
 category: do
+resume_tier: bounded
 ---
 
 <role>

package/bridge/mcp-server.cjs

@@ -22040,9 +22040,10 @@ function registerPlanTools(server2) {
       issue_id: external_exports.number().describe("\uACB0\uC815\uD560 \uC548\uAC74 ID"),
       summary: external_exports.string().describe("\uACB0\uC815 \uC694\uC57D"),
       how_agents: external_exports.array(external_exports.string()).optional().describe('\uC774\uC288 \uBD84\uC11D\uC5D0 \uCC38\uC5EC\uD55C HOW \uC5D0\uC774\uC804\uD2B8 \uC774\uB984 \uBAA9\uB85D (\uC608: ["architect", "designer"])'),
-      how_summary: external_exports.record(external_exports.string(), external_exports.string()).optional().describe('\uC5D0\uC774\uC804\uD2B8\uBCC4 \uD575\uC2EC \uC758\uACAC \uC694\uC57D (\uC608: { "architect": "...", "designer": "..." })')
+      how_summary: external_exports.record(external_exports.string(), external_exports.string()).optional().describe('\uC5D0\uC774\uC804\uD2B8\uBCC4 \uD575\uC2EC \uC758\uACAC \uC694\uC57D (\uC608: { "architect": "...", "designer": "..." })'),
+      how_agent_ids: external_exports.record(external_exports.string(), external_exports.string()).optional().describe('\uC5D0\uC774\uC804\uD2B8 \uC774\uB984 \u2192 agentId \uB9E4\uD551 (resume\uC6A9). \uC608: { "architect": "ac01819f1cd295cb8" }')
     },
-    async ({ issue_id, summary, how_agents, how_summary }) => {
+    async ({ issue_id, summary, how_agents, how_summary, how_agent_ids }) => {
       const data = await readPlan();
       if (!data) {
         return textResult({ error: "No active plan session" });
@@ -22055,6 +22056,7 @@ function registerPlanTools(server2) {
       issue2.decision = summary;
       if (how_agents !== void 0) issue2.how_agents = how_agents;
       if (how_summary !== void 0) issue2.how_summary = how_summary;
+      if (how_agent_ids !== void 0) issue2.how_agent_ids = how_agent_ids;
       await writePlan(data);
       const allComplete = data.issues.every((i) => i.status === "decided");
       if (allComplete) {
@@ -22128,9 +22130,11 @@ function registerTaskTools(server2) {
       plan_issue: external_exports.number().optional().describe("plan issue ID this task originates from \u2014 used for tracing back to the plan session"),
       goal: external_exports.string().optional().describe("Set or update the goal for this task list"),
       decisions: external_exports.array(external_exports.string()).optional().describe("Top-level decisions from [plan] session to append"),
-      owner: external_exports.string().optional().describe("Assignee agent name for this task")
+      owner: external_exports.string().optional().describe("Assignee agent name for this task"),
+      owner_agent_id: external_exports.string().optional().describe("\uD2B9\uC815 agentId\uB85C resume\uD560 \uB54C \uC9C0\uC815. \uBBF8\uC124\uC815 \uC2DC fresh spawn."),
+      owner_reuse_policy: external_exports.enum(["fresh", "resume_if_same_artifact", "resume"]).optional().describe("resume \uD310\uB2E8 \uC815\uCC45. fresh=\uAC15\uC81C \uC0C8 \uC2A4\uD3F0, resume_if_same_artifact=\uC774\uC804 owner\uAC00 \uAC19\uC740 artifact(target file) \uB9CC\uC84C\uC744 \uB54C\uB9CC resume, resume=\uBB34\uC870\uAC74 resume \uC2DC\uB3C4. bounded tier\uB294 resume_if_same_artifact \uAD8C\uC7A5.")
     },
-    async ({ title, context, deps, approach, acceptance, risk, plan_issue, goal, decisions, owner }) => {
+    async ({ title, context, deps, approach, acceptance, risk, plan_issue, goal, decisions, owner, owner_agent_id, owner_reuse_policy }) => {
       let data = await readTasks();
       if (!data) {
         data = { goal: "", decisions: [], tasks: [] };
@@ -22153,6 +22157,8 @@ function registerTaskTools(server2) {
         deps: deps ?? [],
         plan_issue,
         owner,
+        owner_agent_id,
+        owner_reuse_policy,
         created_at: (/* @__PURE__ */ new Date()).toISOString()
       };
       data.tasks.push(newTask);
@@ -22242,6 +22248,35 @@ function registerTaskTools(server2) {
       });
     }
   );
+  server2.tool(
+    "nx_history_search",
+    "Search past plan/task cycles in history.json",
+    {
+      query: external_exports.string().optional().describe("Search term to match against topic, decisions, research_summary"),
+      last_n: external_exports.number().optional().describe("Return only the last N cycles (default: 10)")
+    },
+    async ({ query, last_n }) => {
+      const historyPath = (0, import_path8.join)(NEXUS_ROOT, "history.json");
+      if (!(0, import_fs8.existsSync)(historyPath)) return textResult({ cycles: [], total: 0 });
+      const raw = await (0, import_promises3.readFile)(historyPath, "utf-8");
+      const history = JSON.parse(raw);
+      let cycles = history.cycles || [];
+      if (query) {
+        const q = query.toLowerCase();
+        cycles = cycles.filter((c) => JSON.stringify(c).toLowerCase().includes(q));
+      }
+      const total = cycles.length;
+      const limit = last_n || 10;
+      const results = cycles.slice(-limit).map((c) => ({
+        completed_at: c.completed_at,
+        branch: c.branch,
+        topic: c.plan?.topic,
+        decisions: c.plan?.issues?.filter((i) => i.status === "decided").map((i) => ({ title: i.title, decision: i.decision })),
+        task_count: c.tasks?.length
+      }));
+      return textResult({ total, showing: results.length, cycles: results });
+    }
+  );
 }
 
 // src/mcp/tools/artifact.ts