@moreih29/nexus-core 0.12.0 → 0.13.0

package/assets/capability-matrix.yml

@@ -0,0 +1,198 @@
+# capability-matrix.yml
+# SSOT for agent capability[] -> per-harness enforcement mapping
+#
+# Purpose:
+#   Build scripts read this file to emit harness-specific agent configuration
+#   from the canonical `capabilities:` array in each agent's meta.yml.
+#   This is NOT the hook capability matrix (that lives in assets/hooks/capability-matrix.yml);
+#   this file exclusively concerns agent definition denylist enforcement.
+#
+# Schema:
+#   Each top-level key under `capabilities:` is a capability ID that may appear
+#   in assets/agents/*/meta.yml `capabilities:` arrays.
+#
+#   Per-harness sub-keys:
+#     claude:
+#       disallowedTools: [...]   # Appended to the agent .md frontmatter disallowedTools list
+#                                # Source: https://code.claude.com/docs/en/sub-agents
+#                                # Verified in: .nexus/memory/external-harness-agent-permissions.md §2
+#
+#     opencode:
+#       permission: {}           # Merged into the agent .md frontmatter `permission:` block
+#                                # Source: https://opencode.ai/docs/agents/
+#                                # Verified in: .nexus/memory/external-harness-agent-permissions.md §3
+#
+#     codex:
+#       sandbox_mode: ...        # If set, written as sandbox_mode key in agent TOML
+#                                # Source: https://developers.openai.com/codex/config-reference
+#                                # Verified in: .nexus/memory/external-harness-agent-permissions.md §4
+#       disabled_tools: [...]    # Appended to [mcp_servers.nx] disabled_tools in agent TOML
+#
+# MCP tool name convention:
+#   Claude:   mcp__plugin_claude-nexus_nx__<tool>
+#   OpenCode: permission key uses tool name directly (server-namespaced wildcard supported)
+#   Codex:    disabled_tools uses bare tool names as registered in [mcp_servers.nx]
+#   Source:   .nexus/memory/external-harness-agent-permissions.md §2-4
+#
+# Decision basis:
+#   "Agent definition denylist is the single portable enforcement mechanism
+#    across all 3 harnesses — caller propagation is not reliable on any."
+#   Source: .nexus/memory/external-harness-agent-permissions.md §5-6
+#
+# Updated: 2026-04-19
+# Maintained by: nexus-core team
+
+capabilities:
+
+  # ── no_file_edit ────────────────────────────────────────────────────────────
+  # Blocks all file creation and modification by the agent.
+  # Applied to: HOW agents (architect, designer, postdoc, strategist),
+  #             CHECK agents (reviewer), DO agents (researcher).
+  # These agents are advisory/analysis roles that must never write to disk.
+  #
+  # Claude disallowedTools:
+  #   Edit, Write, MultiEdit, NotebookEdit cover all first-class file-write tools.
+  #   Source: https://code.claude.com/docs/en/sub-agents (disallowedTools field)
+  #   Verified: .nexus/memory/external-claude-code-hooks-tools.md §6 (tool catalog)
+  #   Note: LSP-based rename/write is blocked via the Edit/Write entries.
+  #
+  # OpenCode permission:
+  #   edit: deny blocks the `edit` and `write` built-in tools (OpenCode v1.1.1+).
+  #   apply_patch also requires edit permission; denied transitively.
+  #   Source: https://opencode.ai/docs/agents/ (permission field)
+  #   Verified: .nexus/memory/external-harness-agent-permissions.md §3
+  #
+  # Codex sandbox_mode:
+  #   "read-only" activates an OS-level sandbox that blocks all file writes.
+  #   This is the only reliable mechanism in Codex — there are no independent
+  #   Edit/Write tools to deny (Codex uses apply_patch, which goes through shell).
+  #   Source: https://developers.openai.com/codex/config-reference
+  #   Verified: .nexus/memory/external-harness-agent-permissions.md §4
+
+  no_file_edit:
+    claude:
+      disallowedTools:
+        - Edit
+        - Write
+        - MultiEdit
+        - NotebookEdit
+    opencode:
+      permission:
+        edit: deny
+    codex:
+      sandbox_mode: read-only
+      disabled_tools: []   # OS sandbox is sufficient; no tool-level entries needed
+
+  # ── no_task_create ──────────────────────────────────────────────────────────
+  # Blocks the agent from creating new tasks via nx_task_add.
+  # Applied to: all non-Lead agents (9 agents total).
+  # Task creation is a Lead-only operation. Soft-gating via denylist is the
+  # only portable enforcement; caller propagation is unreliable across harnesses.
+  # Source: .nexus/memory/external-harness-agent-permissions.md §5-6
+  #
+  # Claude disallowedTools:
+  #   Full MCP tool name with plugin namespace prefix.
+  #   Wildcard mcp__* syntax is supported in disallowedTools but not confirmed
+  #   stable across all Claude versions; explicit name is used here for safety.
+  #   Source: https://code.claude.com/docs/en/sub-agents
+  #   Verified: .nexus/memory/external-harness-agent-permissions.md §2
+  #
+  # OpenCode permission:
+  #   MCP tool names are used directly as permission keys.
+  #   Wildcard mymcp_*: false pattern is supported per OpenCode agent permission docs.
+  #   Source: https://opencode.ai/docs/agents/
+  #   Verified: .nexus/memory/external-harness-agent-permissions.md §3
+  #
+  # Codex disabled_tools:
+  #   Bare tool name as registered in [mcp_servers.nx] block of agent TOML.
+  #   Source: https://developers.openai.com/codex/config-reference (disabled_tools key)
+  #   Verified: .nexus/memory/external-harness-agent-permissions.md §4
+
+  no_task_create:
+    claude:
+      disallowedTools:
+        - mcp__plugin_claude-nexus_nx__nx_task_add
+    opencode:
+      # UNVERIFIED: OpenCode's permission block is documented for built-in tools
+      # (edit, bash) and wildcard patterns (mymcp_*). Using a bare MCP tool name
+      # as a key is plausible but unconfirmed. Consider switching to a wildcard
+      # (nx_*: deny) if this proves ineffective at runtime.
+      permission:
+        nx_task_add: deny
+    codex:
+      sandbox_mode: null   # No sandbox needed; tool-level block is sufficient
+      disabled_tools:
+        - nx_task_add
+
+  # ── no_task_update ──────────────────────────────────────────────────────────
+  # Blocks the agent from updating task state via nx_task_update.
+  # Applied to: HOW agents (architect, designer, postdoc, strategist).
+  # These advisory agents must not modify task lifecycle — they advise Lead,
+  # who then updates tasks. DO/CHECK agents may update (engineer can update
+  # tasks it works on; reviewer/tester/researcher report to Lead).
+  # Source: .nexus/memory/external-harness-agent-permissions.md §2 (table)
+  #
+  # See no_task_create for per-harness source citations.
+
+  no_task_update:
+    claude:
+      disallowedTools:
+        - mcp__plugin_claude-nexus_nx__nx_task_update
+    opencode:
+      permission:
+        nx_task_update: deny
+    codex:
+      sandbox_mode: null
+      disabled_tools:
+        - nx_task_update
+
+# ── model_tier ──────────────────────────────────────────────────────────────
+# Maps the abstract `model_tier` field in meta.yml to concrete model slugs
+# per harness. The build script substitutes these into agent definitions at
+# build time.
+#
+# Rationale:
+#   Agents declare `model_tier: high | standard | low` rather than hard-coding
+#   model IDs so that model upgrades require only this file to change, not
+#   every agent definition.
+#
+# opencode: null means "inherit from user config" (opencode has no forced model
+#   override in the agent definition by default — the user or project config
+#   supplies the active model).
+#   Source: https://opencode.ai/docs/agents/ (model field is optional)
+#   Verified: .nexus/memory/external-opencode-plugin.md §5
+#
+# claude model slugs (partial-match basis — Claude Code resolves to latest in series):
+#   Source: https://code.claude.com/docs/en/sub-agents (model field)
+#   Verified: .nexus/memory/external-claude-code-hooks-tools.md §6 (Agent tool: model param)
+#
+# codex model slugs:
+#   Source: https://developers.openai.com/codex/config-reference (model key in agent TOML)
+#   Verified: .nexus/memory/external-harness-agent-permissions.md §4 (model field example)
+#   Note: gpt-5.4 / gpt-5.3-codex / gpt-5.4-mini reflect current Codex-tier naming
+#   as documented in config-reference. Update this section when OpenAI releases
+#   new model versions.
+
+model_tier:
+
+  # high — used by: architect, designer, postdoc, strategist
+  # Reasoning-intensive advisory roles that require deep analysis.
+  high:
+    claude: claude-opus-4
+    codex: gpt-5.4          # UNVERIFIED slug — confirm against current Codex model list
+    opencode: null          # inherits user config
+
+  # standard — used by: engineer, researcher, reviewer, tester, writer
+  # Execution and verification roles where throughput matters more than
+  # top-tier reasoning.
+  standard:
+    claude: claude-sonnet-4
+    codex: gpt-5.3-codex    # UNVERIFIED slug — confirm against current Codex model list
+    opencode: null          # inherits user config
+
+  # low — reserved tier; no agents currently assigned.
+  # Intended for lightweight utility agents (fast, cheap, simple tasks).
+  low:
+    claude: claude-haiku-4
+    codex: gpt-5.4-mini     # UNVERIFIED slug — confirm against current Codex model list
+    opencode: null          # inherits user config

package/assets/hooks/agent-bootstrap/handler.test.ts

@@ -0,0 +1,368 @@
+/**
+ * agent-bootstrap handler tests
+ *
+ * Scenarios:
+ * (1) fresh + registered role (assets/agents/architect exists) → additional_context contains core index + rules
+ * (2) fresh + unregistered role ("general") → silent skip (no additional_context)
+ * (3) resume_count > 0 → skip (not fresh)
+ * (4) .nexus/rules/<role>.md absent → core index only
+ * (5) core index > 2KB → truncated to recent-modified N entries
+ * (6) tracker write side-effect absent (agent-tracker.json unchanged before/after)
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync, rmSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import handler from "./handler.ts";
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+/** Create a temp directory tree suitable for agent-bootstrap tests.
+ *  Returns the cwd (root of the fixture).
+ *
+ *  Layout:
+ *    <root>/
+ *      assets/agents/architect/          ← registered role
+ *      .nexus/memory/                    ← memory .md files
+ *      .nexus/context/                   ← context .md files
+ *      .nexus/rules/architect.md         ← role rule
+ *      .nexus/state/sessions/<sid>/      ← session dir (no tracker by default)
+ */
+function makeFixture(opts: {
+  withRule?: boolean;
+  memoryFiles?: number;
+  contextFiles?: number;
+  withTracker?: { agentId: string; resumeCount: number };
+  sessionId?: string;
+} = {}): { cwd: string; sessionId: string; cleanup: () => void } {
+  const {
+    withRule = true,
+    memoryFiles = 1,
+    contextFiles = 1,
+    withTracker,
+    sessionId = "sess-test",
+  } = opts;
+
+  const cwd = mkdtempSync(join(tmpdir(), "nexus-bootstrap-"));
+
+  // Registered role directory
+  mkdirSync(join(cwd, "assets/agents/architect"), { recursive: true });
+
+  // Memory files
+  const memDir = join(cwd, ".nexus/memory");
+  mkdirSync(memDir, { recursive: true });
+  for (let i = 0; i < memoryFiles; i++) {
+    writeFileSync(join(memDir, `mem-${i}.md`), `# Memory file ${i}\nsome content`);
+  }
+
+  // Context files
+  const ctxDir = join(cwd, ".nexus/context");
+  mkdirSync(ctxDir, { recursive: true });
+  for (let i = 0; i < contextFiles; i++) {
+    writeFileSync(join(ctxDir, `ctx-${i}.md`), `# Context file ${i}\nsome content`);
+  }
+
+  // Rules
+  const rulesDir = join(cwd, ".nexus/rules");
+  mkdirSync(rulesDir, { recursive: true });
+  if (withRule) {
+    writeFileSync(join(rulesDir, "architect.md"), "Always think in systems.");
+  }
+
+  // Session dir
+  const sessionDir = join(cwd, ".nexus/state", sessionId);
+  mkdirSync(sessionDir, { recursive: true });
+
+  // Optional tracker
+  if (withTracker) {
+    writeFileSync(
+      join(sessionDir, "agent-tracker.json"),
+      JSON.stringify([
+        { agent_id: withTracker.agentId, resume_count: withTracker.resumeCount },
+      ])
+    );
+  }
+
+  return {
+    cwd,
+    sessionId,
+    cleanup: () => rmSync(cwd, { recursive: true, force: true }),
+  };
+}
+
+/** Build a SubagentStart input */
+function makeInput(
+  cwd: string,
+  sessionId: string,
+  agentType: string,
+  agentId = "agent-001"
+) {
+  return {
+    hook_event_name: "SubagentStart" as const,
+    session_id: sessionId,
+    cwd,
+    agent_type: agentType,
+    agent_id: agentId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Scenario (1): fresh + registered role → additional_context with core index + rules
+// ---------------------------------------------------------------------------
+
+describe("scenario 1: fresh + registered role", () => {
+  let cleanup: () => void;
+
+  afterAll(() => cleanup?.());
+
+  test("additional_context contains core index and role rule", async () => {
+    const { cwd, sessionId, cleanup: c } = makeFixture({ withRule: true });
+    cleanup = c;
+
+    const result = await handler(makeInput(cwd, sessionId, "architect"));
+
+    expect(result).toBeDefined();
+    expect(result!.additional_context).toBeDefined();
+    const ctx = result!.additional_context!;
+
+    // Core index header
+    expect(ctx).toContain("Available memory/context:");
+    // At least one .md entry
+    expect(ctx).toMatch(/\.nexus\/(memory|context)\/.*\.md/);
+    // Role rule injection
+    expect(ctx).toContain("Custom rule for architect:");
+    expect(ctx).toContain("Always think in systems.");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenario (2): fresh + unregistered role → silent skip
+// ---------------------------------------------------------------------------
+
+describe("scenario 2: fresh + unregistered role", () => {
+  let cleanup: () => void;
+
+  afterAll(() => cleanup?.());
+
+  test("returns undefined (no additional_context) for unknown role", async () => {
+    const { cwd, sessionId, cleanup: c } = makeFixture({ withRule: false });
+    cleanup = c;
+
+    const result = await handler(makeInput(cwd, sessionId, "general"));
+
+    // Silent skip: handler returns void / undefined
+    expect(result == null).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenario (3): resume_count > 0 → skip entirely
+// ---------------------------------------------------------------------------
+
+describe("scenario 3: resume — skip on resume_count > 0", () => {
+  let cleanup: () => void;
+
+  afterAll(() => cleanup?.());
+
+  test("returns undefined when agent has been resumed", async () => {
+    const agentId = "agent-resume";
+    const { cwd, sessionId, cleanup: c } = makeFixture({
+      withTracker: { agentId, resumeCount: 1 },
+    });
+    cleanup = c;
+
+    const result = await handler(makeInput(cwd, sessionId, "architect", agentId));
+
+    expect(result == null).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenario (4): no .nexus/rules/<role>.md → core index only (no rule block)
+// ---------------------------------------------------------------------------
+
+describe("scenario 4: no role rule file → core index only", () => {
+  let cleanup: () => void;
+
+  afterAll(() => cleanup?.());
+
+  test("additional_context has core index but no rule block", async () => {
+    const { cwd, sessionId, cleanup: c } = makeFixture({ withRule: false });
+    cleanup = c;
+
+    const result = await handler(makeInput(cwd, sessionId, "architect"));
+
+    expect(result).toBeDefined();
+    const ctx = result!.additional_context!;
+
+    expect(ctx).toContain("Available memory/context:");
+    expect(ctx).not.toContain("Custom rule for architect:");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenario (5): core index > 2KB → truncated to recent N entries
+// ---------------------------------------------------------------------------
+
+describe("scenario 5: 2KB truncation of core index", () => {
+  let cleanup: () => void;
+
+  afterAll(() => cleanup?.());
+
+  test("core index is truncated when total size exceeds 2KB", async () => {
+    // Create enough files to exceed 2KB.
+    // Each entry line looks like:
+    //   "- .nexus/memory/mem-XX.md: Memory file XX" (~45 chars + newline)
+    // 2048 / 46 ≈ 44 entries needed; create 60 to be safe.
+    const LOTS = 60;
+    const { cwd, sessionId, cleanup: c } = makeFixture({
+      withRule: false,
+      memoryFiles: LOTS,
+      contextFiles: 0,
+    });
+    cleanup = c;
+
+    // Spread mtimes so "recent" ordering is deterministic:
+    // give each file a distinct mtime (oldest → newest = index 0 → LOTS-1)
+    for (let i = 0; i < LOTS; i++) {
+      const filePath = join(cwd, ".nexus/memory", `mem-${i}.md`);
+      const t = new Date(Date.now() - (LOTS - i) * 10_000); // older files have smaller index
+      utimesSync(filePath, t, t);
+    }
+
+    const result = await handler(makeInput(cwd, sessionId, "architect"));
+
+    expect(result).toBeDefined();
+    const ctx = result!.additional_context!;
+    expect(ctx).toContain("Available memory/context:");
+
+    // The raw section between <system-notice> tags for the core index
+    const indexSection = ctx.split("</system-notice>")[0];
+
+    // Should NOT contain all 60 files — truncation must have kicked in
+    const entryCount = (indexSection.match(/- \.nexus\/memory\/mem-/g) ?? []).length;
+    expect(entryCount).toBeGreaterThan(0);
+    expect(entryCount).toBeLessThan(LOTS);
+
+    // The index section must not exceed 2KB (plus small wrapper overhead)
+    const indexBytes = new TextEncoder().encode(indexSection).length;
+    // Allow a generous margin for the header line and wrapping
+    expect(indexBytes).toBeLessThan(2048 + 200);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scenario (6): no tracker write side-effects
+// ---------------------------------------------------------------------------
+
+describe("scenario 6: handler produces no file write side-effects", () => {
+  let cleanup: () => void;
+
+  afterAll(() => cleanup?.());
+
+  test("agent-tracker.json is not created or modified by handler", async () => {
+    const { cwd, sessionId, cleanup: c } = makeFixture({ withTracker: undefined });
+    cleanup = c;
+
+    const trackerPath = join(cwd, ".nexus/state", sessionId, "agent-tracker.json");
+
+    // Tracker must not exist before the call
+    expect(existsSync(trackerPath)).toBe(false);
+
+    await handler(makeInput(cwd, sessionId, "architect"));
+
+    // Tracker must still not exist after the call
+    expect(existsSync(trackerPath)).toBe(false);
+  });
+
+  test("pre-existing agent-tracker.json is not modified by handler", async () => {
+    const agentId = "agent-side-effect";
+    const { cwd, sessionId, cleanup: c } = makeFixture({
+      withTracker: { agentId, resumeCount: 0 },
+    });
+    cleanup = c;
+
+    const trackerPath = join(cwd, ".nexus/state", sessionId, "agent-tracker.json");
+    const before = readFileSync(trackerPath, "utf-8");
+
+    await handler(makeInput(cwd, sessionId, "architect", agentId));
+
+    const after = readFileSync(trackerPath, "utf-8");
+    expect(after).toBe(before);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 모듈 전역 상태 격리
+// ---------------------------------------------------------------------------
+
+describe("모듈 전역 상태 격리", () => {
+  // Test A: two different cwds with different agent sets produce independent results
+  test("Test A: different cwds return only their own roles", async () => {
+    const tmpDir1 = mkdtempSync(join(tmpdir(), "nexus-isolation-a1-"));
+    const tmpDir2 = mkdtempSync(join(tmpdir(), "nexus-isolation-a2-"));
+
+    try {
+      // tmpDir1: only "architect"
+      mkdirSync(join(tmpDir1, "assets/agents/architect"), { recursive: true });
+      mkdirSync(join(tmpDir1, ".nexus/memory"), { recursive: true });
+      writeFileSync(join(tmpDir1, ".nexus/memory/mem.md"), "# mem\ncontent");
+      mkdirSync(join(tmpDir1, ".nexus/state/sess1"), { recursive: true });
+
+      // tmpDir2: only "engineer"
+      mkdirSync(join(tmpDir2, "assets/agents/engineer"), { recursive: true });
+      mkdirSync(join(tmpDir2, ".nexus/memory"), { recursive: true });
+      writeFileSync(join(tmpDir2, ".nexus/memory/mem.md"), "# mem\ncontent");
+      mkdirSync(join(tmpDir2, ".nexus/state/sess2"), { recursive: true });
+
+      // Call with tmpDir1 as architect → should return context
+      const r1a = await handler(makeInput(tmpDir1, "sess1", "architect"));
+      expect(r1a).toBeDefined();
+
+      // Call with tmpDir1 as engineer → should be skipped (engineer not in tmpDir1)
+      const r1b = await handler(makeInput(tmpDir1, "sess1", "engineer"));
+      expect(r1b == null).toBe(true);
+
+      // Call with tmpDir2 as engineer → should return context
+      const r2a = await handler(makeInput(tmpDir2, "sess2", "engineer"));
+      expect(r2a).toBeDefined();
+
+      // Call with tmpDir2 as architect → should be skipped (architect not in tmpDir2)
+      const r2b = await handler(makeInput(tmpDir2, "sess2", "architect"));
+      expect(r2b == null).toBe(true);
+    } finally {
+      rmSync(tmpDir1, { recursive: true, force: true });
+      rmSync(tmpDir2, { recursive: true, force: true });
+    }
+  });
+
+  // Test B: adding a new role directory is picked up on the next call
+  test("Test B: newly added role is reflected in subsequent call", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "nexus-isolation-b-"));
+
+    try {
+      // Start with only "architect"
+      mkdirSync(join(tmpDir, "assets/agents/architect"), { recursive: true });
+      mkdirSync(join(tmpDir, ".nexus/memory"), { recursive: true });
+      writeFileSync(join(tmpDir, ".nexus/memory/mem.md"), "# mem\ncontent");
+      mkdirSync(join(tmpDir, ".nexus/state/sess"), { recursive: true });
+
+      // "foo" does not exist yet → should be skipped
+      const r1 = await handler(makeInput(tmpDir, "sess", "foo"));
+      expect(r1 == null).toBe(true);
+
+      // Add "foo" role directory
+      mkdirSync(join(tmpDir, "assets/agents/foo"), { recursive: true });
+
+      // Now "foo" should be recognized on the next call
+      const r2 = await handler(makeInput(tmpDir, "sess", "foo"));
+      expect(r2).toBeDefined();
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

package/assets/hooks/agent-bootstrap/handler.ts

@@ -0,0 +1,119 @@
+import type { HookHandler } from "../../../src/hooks/types.js";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const CORE_INDEX_SIZE_LIMIT = 2 * 1024; // 2KB
+
+function loadValidRoles(cwd: string): string[] {
+  const agentsDir = join(cwd, "assets/agents");
+  const roles: string[] = [];
+  if (existsSync(agentsDir)) {
+    for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) roles.push(entry.name);
+    }
+  }
+  return roles;
+}
+
+function readFirstLine(path: string): string {
+  try {
+    const content = readFileSync(path, "utf-8");
+    const firstNonEmpty =
+      content.split("\n").find((l) => l.trim().length > 0) ?? "";
+    return firstNonEmpty.replace(/^#+\s*/, "").slice(0, 80);
+  } catch {
+    return "";
+  }
+}
+
+function buildCoreIndex(cwd: string): string {
+  const entries: Array<{ path: string; mtime: number; line: string }> = [];
+
+  for (const sub of [".nexus/memory", ".nexus/context"]) {
+    const absDir = join(cwd, sub);
+    if (!existsSync(absDir)) continue;
+    for (const f of readdirSync(absDir, { withFileTypes: true })) {
+      if (!f.isFile() || !f.name.endsWith(".md")) continue;
+      const full = join(absDir, f.name);
+      entries.push({
+        path: `${sub}/${f.name}`,
+        mtime: statSync(full).mtimeMs,
+        line: readFirstLine(full),
+      });
+    }
+  }
+
+  entries.sort((a, b) => b.mtime - a.mtime);
+
+  const lines: string[] = [];
+  let bytes = 0;
+  for (const e of entries) {
+    const formatted = `- ${e.path}: ${e.line}`;
+    if (bytes + formatted.length + 1 > CORE_INDEX_SIZE_LIMIT) break;
+    lines.push(formatted);
+    bytes += formatted.length + 1;
+  }
+
+  return lines.length > 0
+    ? "Available memory/context:\n" + lines.join("\n")
+    : "";
+}
+
+function getResumeCount(
+  cwd: string,
+  sessionId: string,
+  agentId: string
+): number {
+  const trackerPath = join(
+    cwd,
+    ".nexus/state",
+    sessionId,
+    "agent-tracker.json"
+  );
+  if (!existsSync(trackerPath)) return 0;
+  try {
+    const tracker = JSON.parse(readFileSync(trackerPath, "utf-8"));
+    const entry = Array.isArray(tracker)
+      ? tracker.find((e: { agent_id?: string }) => e.agent_id === agentId)
+      : null;
+    return (entry as { resume_count?: number } | null)?.resume_count ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+const handler: HookHandler = async (input) => {
+  if (input.hook_event_name !== "SubagentStart") return;
+
+  const { cwd, session_id, agent_type, agent_id } = input;
+
+  // fresh only — skip on resume
+  const resumeCount = getResumeCount(cwd, session_id, agent_id);
+  if (resumeCount > 0) return;
+
+  // unregistered role: silent skip
+  const validRoles = loadValidRoles(cwd);
+  if (!validRoles.includes(agent_type)) return;
+
+  const parts: string[] = [];
+
+  const coreIndex = buildCoreIndex(cwd);
+  if (coreIndex) {
+    parts.push(`<system-notice>\n${coreIndex}\n</system-notice>`);
+  }
+
+  const rulePath = join(cwd, ".nexus/rules", `${agent_type}.md`);
+  if (existsSync(rulePath)) {
+    const ruleContent = readFileSync(rulePath, "utf-8").trim();
+    if (ruleContent) {
+      parts.push(
+        `<system-notice>\nCustom rule for ${agent_type}:\n${ruleContent}\n</system-notice>`
+      );
+    }
+  }
+
+  if (parts.length === 0) return;
+  return { additional_context: parts.join("\n\n") };
+};
+
+export default handler;

package/assets/hooks/agent-bootstrap/meta.yml

@@ -0,0 +1,10 @@
+name: agent-bootstrap
+description: Inject core memory index and role-specific rules on fresh subagent spawn
+events: [SubagentStart]
+matcher: "*"
+timeout: 10
+fallback: warn
+priority: 0
+requires_capabilities:
+  - event.subagent_start
+  - output.additional_context.session_start