claude-nexus 0.28.1 → 0.29.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.28.1",
+      "version": "0.29.0",
       "author": {
         "name": "kih"
       },

package/.claude-plugin/plugin.json

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

package/VERSION

@@ -1 +1 @@
-0.28.1
+0.29.0

package/agents/architect.md

@@ -1,6 +1,6 @@
 ---
 description: "Technical design — evaluates How, reviews architecture, advises on implementation approach"
-model: claude-opus-4
+model: opus
 disallowedTools:
   - Edit
   - Write

package/agents/designer.md

@@ -1,6 +1,6 @@
 ---
 description: "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product"
-model: claude-opus-4
+model: opus
 disallowedTools:
   - Edit
   - Write

package/agents/engineer.md

@@ -1,6 +1,6 @@
 ---
 description: "Implementation — writes code, debugs issues, follows specifications from Lead and architect"
-model: claude-sonnet-4
+model: sonnet
 disallowedTools:
   - mcp__plugin_claude-nexus_nx__nx_task_add
 ---

package/agents/lead.md

@@ -1,6 +1,6 @@
 ---
 description: "Primary orchestrator — converses directly with users, composes 9 subagents across HOW/DO/CHECK categories, and owns scope decisions and task lifecycle"
-model: claude-opus-4
+model: opus
 ---
 ## Identity
 

package/agents/postdoc.md

@@ -1,6 +1,6 @@
 ---
 description: "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents"
-model: claude-opus-4
+model: opus
 disallowedTools:
   - Edit
   - Write

package/agents/researcher.md

@@ -1,6 +1,6 @@
 ---
 description: "Independent investigation — conducts web searches, gathers evidence, and reports findings with citations"
-model: claude-sonnet-4
+model: sonnet
 disallowedTools:
   - Edit
   - Write

package/agents/reviewer.md

@@ -1,6 +1,6 @@
 ---
 description: "Content verification — validates accuracy, checks facts, confirms grammar and format of non-code deliverables"
-model: claude-sonnet-4
+model: sonnet
 disallowedTools:
   - Edit
   - Write

package/agents/strategist.md

@@ -1,6 +1,6 @@
 ---
 description: "Business strategy — evaluates market positioning, competitive landscape, and business viability of decisions"
-model: claude-opus-4
+model: opus
 disallowedTools:
   - Edit
   - Write

package/agents/tester.md

@@ -1,6 +1,6 @@
 ---
 description: "Testing and verification — tests, verifies, validates stability and security of implementations"
-model: claude-sonnet-4
+model: sonnet
 disallowedTools:
   - Edit
   - Write

package/agents/writer.md

@@ -1,6 +1,6 @@
 ---
 description: "Technical writing — transforms research findings, code, and analysis into clear documents and presentations for the intended audience"
-model: claude-sonnet-4
+model: sonnet
 disallowedTools:
   - mcp__plugin_claude-nexus_nx__nx_task_add
 ---

package/dist/hooks/agent-bootstrap.js

@@ -1,21 +1,124 @@
+// src/shared/json-store.js
+import fs from "node:fs/promises";
+import { constants as fsConstants, appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+var inProcessQueues = new Map;
+async function runWithInProcessLock(filePath, action) {
+  const previous = inProcessQueues.get(filePath) ?? Promise.resolve();
+  let release = () => {};
+  const gate = new Promise((resolve) => {
+    release = resolve;
+  });
+  const entry = previous.then(() => gate);
+  inProcessQueues.set(filePath, entry);
+  await previous;
+  try {
+    return await action();
+  } finally {
+    release();
+    entry.finally(() => {
+      if (inProcessQueues.get(filePath) === entry) {
+        inProcessQueues.delete(filePath);
+      }
+    });
+  }
+}
+var LOCK_RETRY_INTERVAL_MS = 100;
+var LOCK_MAX_RETRIES = 50;
+var LOCK_STALE_MS = 30000;
+function lockPath(filePath) {
+  return `${filePath}.lock`;
+}
+async function acquireFsLock(filePath) {
+  const lp = lockPath(filePath);
+  for (let attempt = 0;attempt <= LOCK_MAX_RETRIES; attempt++) {
+    try {
+      const fd = await fs.open(lp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL);
+      await fd.close();
+      return;
+    } catch (err) {
+      const e = err;
+      if (e.code !== "EEXIST")
+        throw err;
+      try {
+        const stat = await fs.stat(lp);
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs > LOCK_STALE_MS) {
+          await fs.unlink(lp).catch(() => {
+            return;
+          });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (attempt === LOCK_MAX_RETRIES) {
+        throw new Error(`Failed to acquire lock for "${filePath}" after ${LOCK_MAX_RETRIES} retries`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_INTERVAL_MS));
+    }
+  }
+}
+async function releaseFsLock(filePath) {
+  await fs.unlink(lockPath(filePath)).catch(() => {
+    return;
+  });
+}
+async function readJsonFile(filePath, defaultValue) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT")
+      return defaultValue;
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return defaultValue;
+  }
+}
+async function writeJsonFile(filePath, data) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp.${process.pid}.${Date.now()}.${randomUUID()}`;
+  await fs.writeFile(tmpPath, JSON.stringify(data, null, 2) + `
+`, "utf8");
+  await fs.rename(tmpPath, filePath);
+}
+async function updateJsonFileLocked(filePath, defaultValue, updater) {
+  return runWithInProcessLock(filePath, async () => {
+    await acquireFsLock(filePath);
+    try {
+      const current = await readJsonFile(filePath, defaultValue);
+      const next = await updater(current);
+      await writeJsonFile(filePath, next);
+      return next;
+    } finally {
+      await releaseFsLock(filePath);
+    }
+  });
+}
+var APPEND_SIZE_WARN_THRESHOLD = 4 * 1024;
+
 // assets/hooks/agent-bootstrap/handler.ts
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 var CORE_INDEX_SIZE_LIMIT = 2 * 1024;
 function loadValidRoles(cwd) {
+  const inlined = globalThis.__NEXUS_INLINE_AGENT_ROLES__;
+  if (Array.isArray(inlined))
+    return inlined;
   const agentsDir = join(cwd, "assets/agents");
-  const roles = [];
-  if (existsSync(agentsDir)) {
-    for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
-      if (entry.isDirectory())
-        roles.push(entry.name);
-    }
-  }
-  return roles;
+  if (!existsSync(agentsDir))
+    return [];
+  return readdirSync(agentsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
 }
-function readFirstLine(path) {
+function readFirstLine(path2) {
   try {
-    const content = readFileSync(path, "utf-8");
+    const content = readFileSync(path2, "utf-8");
     const firstNonEmpty = content.split(`
 `).find((l) => l.trim().length > 0) ?? "";
     return firstNonEmpty.replace(/^#+\s*/, "").slice(0, 80);
@@ -76,6 +179,19 @@ var handler = async (input) => {
   const validRoles = loadValidRoles(cwd);
   if (!validRoles.includes(agent_type))
     return;
+  const trackerPath = join(cwd, ".nexus/state", session_id, "agent-tracker.json");
+  await updateJsonFileLocked(trackerPath, [], (tracker) => {
+    const list = Array.isArray(tracker) ? tracker : [];
+    if (list.find((e) => e["agent_id"] === agent_id))
+      return list;
+    list.push({
+      agent_id,
+      agent_type,
+      started_at: new Date().toISOString(),
+      status: "running"
+    });
+    return list;
+  });
   const parts = [];
   const coreIndex = buildCoreIndex(cwd);
   if (coreIndex) {
@@ -100,6 +216,23 @@ ${ruleContent}
 `) };
 };
 var handler_default = handler;
-export {
-  handler_default as default
-};
+
+// ../../../../../tmp/nexus-hook-entry-agent-bootstrap-1776690665703/agent-bootstrap-entry.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+globalThis.__NEXUS_INLINE_AGENT_ROLES__ = ["architect", "designer", "engineer", "reviewer", "strategist", "researcher", "postdoc", "lead", "tester", "writer"];
+async function main() {
+  let raw = "";
+  try {
+    raw = readFileSync2(0, "utf-8");
+  } catch {}
+  const input = raw ? JSON.parse(raw) : {};
+  const result = await handler_default(input);
+  if (result != null && result !== undefined) {
+    process.stdout.write(JSON.stringify(result));
+  }
+}
+main().then(() => process.exit(0), (err) => {
+  process.stderr.write(String(err?.stack ?? err) + `
+`);
+  process.exit(1);
+});

package/dist/hooks/agent-finalize.js

@@ -159,6 +159,22 @@ Subagent "${agent_type}" finished. Tasks still pending with this role: ${ids}. R
   }
 };
 var handler_default = handler;
-export {
-  handler_default as default
-};
+
+// ../../../../../tmp/nexus-hook-entry-agent-finalize-1776690665695/agent-finalize-entry.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+async function main() {
+  let raw = "";
+  try {
+    raw = readFileSync2(0, "utf-8");
+  } catch {}
+  const input = raw ? JSON.parse(raw) : {};
+  const result = await handler_default(input);
+  if (result != null && result !== undefined) {
+    process.stdout.write(JSON.stringify(result));
+  }
+}
+main().then(() => process.exit(0), (err) => {
+  process.stderr.write(String(err?.stack ?? err) + `
+`);
+  process.exit(1);
+});

package/dist/hooks/post-tool-telemetry.js

@@ -0,0 +1,71 @@
+// src/shared/json-store.js
+import { constants as fsConstants, appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+var inProcessQueues = new Map;
+var APPEND_SIZE_WARN_THRESHOLD = 4 * 1024;
+function appendJsonLine(filePath, record) {
+  const line = JSON.stringify(record) + `
+`;
+  if (line.length > APPEND_SIZE_WARN_THRESHOLD) {
+    console.error(`[json-store] appendJsonLine line exceeds ${APPEND_SIZE_WARN_THRESHOLD} bytes ` + `(${line.length}) — write may not be atomic on some filesystems. path=${filePath}`);
+  }
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  appendFileSync(filePath, line);
+}
+
+// assets/hooks/post-tool-telemetry/handler.ts
+import { join, resolve, relative } from "node:path";
+var EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "ApplyPatch", "NotebookEdit"]);
+function isWithinMemory(filePath, projectRoot) {
+  const memRoot = resolve(projectRoot, ".nexus/memory");
+  const abs = resolve(filePath);
+  return abs.startsWith(memRoot + "/") || abs === memRoot;
+}
+var handler = async (input) => {
+  if (input.hook_event_name !== "PostToolUse")
+    return;
+  const { cwd, session_id, tool_name, agent_id } = input;
+  const toolInput = input.tool_input ?? {};
+  if (tool_name === "Read") {
+    const filePath = toolInput.file_path;
+    if (filePath && isWithinMemory(filePath, cwd)) {
+      appendJsonLine(join(cwd, ".nexus/memory-access.jsonl"), {
+        path: relative(cwd, resolve(filePath)),
+        accessed_at: new Date().toISOString(),
+        agent: agent_id ?? null
+      });
+    }
+  }
+  if (EDIT_TOOLS.has(tool_name) && agent_id) {
+    const filePath = toolInput.file_path ?? toolInput.notebook_path;
+    if (filePath) {
+      appendJsonLine(join(cwd, ".nexus/state", session_id, "tool-log.jsonl"), {
+        ts: new Date().toISOString(),
+        agent_id,
+        tool: tool_name,
+        file: relative(cwd, resolve(filePath)),
+        status: "ok"
+      });
+    }
+  }
+};
+var handler_default = handler;
+
+// ../../../../../tmp/nexus-hook-entry-post-tool-telemetry-1776690665643/post-tool-telemetry-entry.ts
+import { readFileSync } from "node:fs";
+async function main() {
+  let raw = "";
+  try {
+    raw = readFileSync(0, "utf-8");
+  } catch {}
+  const input = raw ? JSON.parse(raw) : {};
+  const result = await handler_default(input);
+  if (result != null && result !== undefined) {
+    process.stdout.write(JSON.stringify(result));
+  }
+}
+main().then(() => process.exit(0), (err) => {
+  process.stderr.write(String(err?.stack ?? err) + `
+`);
+  process.exit(1);
+});

package/dist/hooks/prompt-router.js

@@ -7141,6 +7141,11 @@ var _invocationsCache = null;
 function loadInvocations() {
   if (_invocationsCache)
     return _invocationsCache;
+  const inlined = globalThis.__NEXUS_INLINE_INVOCATIONS__;
+  if (inlined) {
+    _invocationsCache = inlined;
+    return inlined;
+  }
   const selfDir = new URL(".", import.meta.url).pathname;
   let dir = selfDir;
   while (dir !== "/") {
@@ -7175,6 +7180,9 @@ function expand(template, harness) {
   return expandInvocations(template, harness, loadInvocations());
 }
 function loadValidRuleTargets(cwd) {
+  const inlined = globalThis.__NEXUS_INLINE_RULE_TARGETS__;
+  if (inlined && inlined.length > 0)
+    return inlined;
   const targets = [];
   for (const dir of ["assets/agents", "assets/skills"]) {
     const absDir = join(cwd, dir);
@@ -7295,6 +7303,34 @@ var handler = async (input) => {
 `) };
 };
 var handler_default = handler;
-export {
-  handler_default as default
-};
+
+// ../../../../../tmp/nexus-hook-entry-prompt-router-1776690665662/prompt-router-entry.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+globalThis.__NEXUS_INLINE_INVOCATIONS__ = { subagent_spawn: { args: ["target_role", "prompt", "name"], templates: { claude: 'Agent({ subagent_type: "{target_role}", prompt: "{prompt}", description: "{name}" })', opencode: 'task({ subagent_type: "{target_role}", prompt: "{prompt}", description: "{name}" })', codex: 'spawn_agent("{target_role}", "{prompt}")' }, notes: { claude: `description field is optional; omit when name arg is absent. model field may be added to override the spawned agent's model.
+`, opencode: `description is required by OpenCode's Zod schema — use target_role as fallback when name is absent. task_id param enables session resume (§15).
+`, codex: `Agent role must be pre-registered in config.toml [agents.<target_role>]. No description equivalent in spawn_agent call signature.
+` } }, skill_activation: { args: ["skill", "mode"], templates: { claude: 'Skill({ command: "{skill}" })', opencode: 'skill({ name: "{skill}" })', codex: "${skill}" }, notes: { claude: "The Skill tool accepts only the `command` string; mode/args cannot be passed as a separate parameter. Mode must be embedded in the SKILL.md body via $ARGUMENTS placeholder substitution.\n", opencode: "The skill tool accepts only `name`; args passing is unconfirmed per source review. Design skills to be args-free or embed defaults in SKILL.md body.\n", codex: `Positional args: "$skill-name {mode}". Named args: "$skill-name MODE={mode}". Confirmed only for Custom Prompts; treat as best-effort for Skills. $ prefix is literal in composer input, not a tool call.
+` } }, task_register: { args: ["label", "state"], templates: { claude: 'TaskCreate({ subject: "{label}" }) then nx_task_update({ taskId, status: "{state}" })', opencode: 'nx_task_add({ subject: "{label}" }) then nx_task_update({ taskId, status: "{state}" })', codex: 'update_plan([{ name: "{label}", state: "{state}" }])' }, notes: { claude: `TaskCreate is a Claude Code native tool (not MCP). nx_task_update is the nexus-core MCP tool — full name mcp__plugin_claude-nexus_nx__nx_task_update. taskId is returned by TaskCreate and must be threaded to the update call.
+`, opencode: `Both nx_task_add and nx_task_update are nexus-core MCP tools exposed via the nexus MCP server. task_id returned by nx_task_add must be threaded to update.
+`, codex: `update_plan subsumes creation and update in a single call via plan/step/status fields. No separate create/update step is needed.
+` } }, user_question: { args: ["question", "options"], templates: { claude: 'AskUserQuestion({ questions: [{ question: "{question}", options: {options} }] })', opencode: 'question({ question: "{question}", choices: {options} })', codex: 'request_user_input({ prompt: "{question}", options: {options} })' }, notes: { claude: `options is a JSON array of strings. Omit the options field (not an empty array) for free-text responses. Multiple questions can be batched in the questions[] array.
+`, opencode: `choices field name (not options). Omit choices for free-text input.
+`, codex: `Exact request_user_input schema (options field name, types) is not fully documented — treat as best-effort. Verified as a native Codex tool in external-codex-hooks-tools.md §7-4.
+` } } };
+globalThis.__NEXUS_INLINE_RULE_TARGETS__ = ["architect", "designer", "engineer", "reviewer", "strategist", "researcher", "postdoc", "lead", "tester", "writer", "nx-run", "nx-init", "nx-sync", "nx-plan"];
+async function main() {
+  let raw = "";
+  try {
+    raw = readFileSync2(0, "utf-8");
+  } catch {}
+  const input = raw ? JSON.parse(raw) : {};
+  const result = await handler_default(input);
+  if (result != null && result !== undefined) {
+    process.stdout.write(JSON.stringify(result));
+  }
+}
+main().then(() => process.exit(0), (err) => {
+  process.stderr.write(String(err?.stack ?? err) + `
+`);
+  process.exit(1);
+});

package/dist/hooks/session-init.js

@@ -1,6 +1,15 @@
 // assets/hooks/session-init/handler.ts
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join, basename } from "node:path";
+
+// src/shared/paths.ts
+function getParentPid() {
+  const testOverride = parseInt(process.env["NEXUS_TEST_PPID"] ?? "");
+  return testOverride || process.ppid;
+}
+var byPpidCache = new Map;
+
+// assets/hooks/session-init/handler.ts
 var handler = async (input) => {
   if (input.hook_event_name !== "SessionStart")
     return;
@@ -14,8 +23,28 @@ var handler = async (input) => {
   mkdirSync(sessionDir, { recursive: true });
   writeFileSync(join(sessionDir, "agent-tracker.json"), "[]");
   writeFileSync(join(sessionDir, "tool-log.jsonl"), "");
+  const ppid = getParentPid();
+  const byPpidDir = join(input.cwd, ".nexus/state/runtime/by-ppid");
+  mkdirSync(byPpidDir, { recursive: true });
+  writeFileSync(join(byPpidDir, `${ppid}.json`), JSON.stringify({ session_id: input.session_id, updated_at: new Date().toISOString(), cwd: input.cwd }));
 };
 var handler_default = handler;
-export {
-  handler_default as default
-};
+
+// ../../../../../tmp/nexus-hook-entry-session-init-1776690665653/session-init-entry.ts
+import { readFileSync } from "node:fs";
+async function main() {
+  let raw = "";
+  try {
+    raw = readFileSync(0, "utf-8");
+  } catch {}
+  const input = raw ? JSON.parse(raw) : {};
+  const result = await handler_default(input);
+  if (result != null && result !== undefined) {
+    process.stdout.write(JSON.stringify(result));
+  }
+}
+main().then(() => process.exit(0), (err) => {
+  process.stderr.write(String(err?.stack ?? err) + `
+`);
+  process.exit(1);
+});

package/hooks/hooks.json

@@ -1,5 +1,17 @@
 {
   "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Read|Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/hooks/post-tool-telemetry.js",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "*",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nexus",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "type": "module",
   "description": "Agent orchestration plugin for Claude Code — optimized context injection per role",
   "author": "kih",
@@ -36,7 +36,7 @@
     "VERSION"
   ],
   "devDependencies": {
-    "@moreih29/nexus-core": "^0.15.1"
+    "@moreih29/nexus-core": "^0.17.0"
   },
   "dependencies": {}
 }