agenthub-multiagent-mcp 1.61.0 → 1.65.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/README.md +3 -3
  2. package/dist/brain/memvidBrain.d.ts +22 -0
  3. package/dist/brain/memvidBrain.d.ts.map +1 -1
  4. package/dist/brain/memvidBrain.js +41 -2
  5. package/dist/brain/memvidBrain.js.map +1 -1
  6. package/dist/brain/memvidBrain.test.js +90 -0
  7. package/dist/brain/memvidBrain.test.js.map +1 -1
  8. package/dist/brain/migrate.d.ts +43 -0
  9. package/dist/brain/migrate.d.ts.map +1 -1
  10. package/dist/brain/migrate.js +148 -23
  11. package/dist/brain/migrate.js.map +1 -1
  12. package/dist/brain/migrate.test.js +194 -1
  13. package/dist/brain/migrate.test.js.map +1 -1
  14. package/dist/channel.js +47 -5
  15. package/dist/channel.js.map +1 -1
  16. package/dist/channelDiagnostics.d.ts +36 -0
  17. package/dist/channelDiagnostics.d.ts.map +1 -1
  18. package/dist/channelDiagnostics.js +65 -0
  19. package/dist/channelDiagnostics.js.map +1 -1
  20. package/dist/channelDiagnostics.test.js +81 -1
  21. package/dist/channelDiagnostics.test.js.map +1 -1
  22. package/dist/client.d.ts +17 -0
  23. package/dist/client.d.ts.map +1 -1
  24. package/dist/client.js +32 -0
  25. package/dist/client.js.map +1 -1
  26. package/dist/daemon.js +16 -22
  27. package/dist/daemon.js.map +1 -1
  28. package/dist/index.js +36 -3
  29. package/dist/index.js.map +1 -1
  30. package/dist/lib/pending-items.d.ts +63 -0
  31. package/dist/lib/pending-items.d.ts.map +1 -0
  32. package/dist/lib/pending-items.js +96 -0
  33. package/dist/lib/pending-items.js.map +1 -0
  34. package/dist/pinSweep.d.ts +83 -0
  35. package/dist/pinSweep.d.ts.map +1 -0
  36. package/dist/pinSweep.js +105 -0
  37. package/dist/pinSweep.js.map +1 -0
  38. package/dist/pinSweep.test.d.ts +12 -0
  39. package/dist/pinSweep.test.d.ts.map +1 -0
  40. package/dist/pinSweep.test.js +110 -0
  41. package/dist/pinSweep.test.js.map +1 -0
  42. package/dist/pinSweepCli.d.ts +20 -0
  43. package/dist/pinSweepCli.d.ts.map +1 -0
  44. package/dist/pinSweepCli.js +287 -0
  45. package/dist/pinSweepCli.js.map +1 -0
  46. package/dist/run-claude.sh +36 -5
  47. package/dist/sessionCapture.d.ts.map +1 -1
  48. package/dist/sessionCapture.js +7 -1
  49. package/dist/sessionCapture.js.map +1 -1
  50. package/dist/sessionCapture.test.js +20 -0
  51. package/dist/sessionCapture.test.js.map +1 -1
  52. package/dist/setup.js +11 -0
  53. package/dist/setup.js.map +1 -1
  54. package/dist/shiftFiles.d.ts +33 -0
  55. package/dist/shiftFiles.d.ts.map +1 -0
  56. package/dist/shiftFiles.js +57 -0
  57. package/dist/shiftFiles.js.map +1 -0
  58. package/dist/shiftFiles.test.d.ts +2 -0
  59. package/dist/shiftFiles.test.d.ts.map +1 -0
  60. package/dist/shiftFiles.test.js +141 -0
  61. package/dist/shiftFiles.test.js.map +1 -0
  62. package/dist/skillInstaller.d.ts.map +1 -1
  63. package/dist/skillInstaller.gate.test.js +2 -0
  64. package/dist/skillInstaller.gate.test.js.map +1 -1
  65. package/dist/skillInstaller.js +8 -0
  66. package/dist/skillInstaller.js.map +1 -1
  67. package/dist/skillInstaller.test.js +8 -1
  68. package/dist/skillInstaller.test.js.map +1 -1
  69. package/dist/tools/goshtiRead.d.ts +72 -0
  70. package/dist/tools/goshtiRead.d.ts.map +1 -0
  71. package/dist/tools/goshtiRead.js +274 -0
  72. package/dist/tools/goshtiRead.js.map +1 -0
  73. package/dist/tools/goshtiRead.test.d.ts +8 -0
  74. package/dist/tools/goshtiRead.test.d.ts.map +1 -0
  75. package/dist/tools/goshtiRead.test.js +182 -0
  76. package/dist/tools/goshtiRead.test.js.map +1 -0
  77. package/dist/tools/inboxBounds.d.ts +80 -0
  78. package/dist/tools/inboxBounds.d.ts.map +1 -0
  79. package/dist/tools/inboxBounds.js +105 -0
  80. package/dist/tools/inboxBounds.js.map +1 -0
  81. package/dist/tools/inboxBounds.test.d.ts +15 -0
  82. package/dist/tools/inboxBounds.test.d.ts.map +1 -0
  83. package/dist/tools/inboxBounds.test.js +135 -0
  84. package/dist/tools/inboxBounds.test.js.map +1 -0
  85. package/dist/tools/index.d.ts +11 -0
  86. package/dist/tools/index.d.ts.map +1 -1
  87. package/dist/tools/index.js +106 -102
  88. package/dist/tools/index.js.map +1 -1
  89. package/dist/tools/intakeRequests.d.ts +35 -0
  90. package/dist/tools/intakeRequests.d.ts.map +1 -0
  91. package/dist/tools/intakeRequests.js +344 -0
  92. package/dist/tools/intakeRequests.js.map +1 -0
  93. package/dist/tools/intakeRequests.test.d.ts +8 -0
  94. package/dist/tools/intakeRequests.test.d.ts.map +1 -0
  95. package/dist/tools/intakeRequests.test.js +183 -0
  96. package/dist/tools/intakeRequests.test.js.map +1 -0
  97. package/dist/tools/openspec-viz/taskSync.d.ts +115 -0
  98. package/dist/tools/openspec-viz/taskSync.d.ts.map +1 -0
  99. package/dist/tools/openspec-viz/taskSync.js +144 -0
  100. package/dist/tools/openspec-viz/taskSync.js.map +1 -0
  101. package/dist/tools/openspec-viz/taskSync.test.d.ts +2 -0
  102. package/dist/tools/openspec-viz/taskSync.test.d.ts.map +1 -0
  103. package/dist/tools/openspec-viz/taskSync.test.js +198 -0
  104. package/dist/tools/openspec-viz/taskSync.test.js.map +1 -0
  105. package/dist/tools/pushedItemsSafety.test.d.ts +12 -0
  106. package/dist/tools/pushedItemsSafety.test.d.ts.map +1 -0
  107. package/dist/tools/pushedItemsSafety.test.js +179 -0
  108. package/dist/tools/pushedItemsSafety.test.js.map +1 -0
  109. package/dist/tools/tools.test.js +17 -5
  110. package/dist/tools/tools.test.js.map +1 -1
  111. package/dist/tools/wrapperCost.test.d.ts +13 -0
  112. package/dist/tools/wrapperCost.test.d.ts.map +1 -0
  113. package/dist/tools/wrapperCost.test.js +149 -0
  114. package/dist/tools/wrapperCost.test.js.map +1 -0
  115. package/dist/websocket.d.ts +30 -1
  116. package/dist/websocket.d.ts.map +1 -1
  117. package/dist/websocket.js +40 -3
  118. package/dist/websocket.js.map +1 -1
  119. package/dist/websocketQueue.test.d.ts +10 -0
  120. package/dist/websocketQueue.test.d.ts.map +1 -0
  121. package/dist/websocketQueue.test.js +78 -0
  122. package/dist/websocketQueue.test.js.map +1 -0
  123. package/package.json +4 -4
  124. package/skills/catalog.json +23 -10
  125. package/skills/commands/close-session.md +144 -144
  126. package/skills/commands/start-session.md +25 -6
  127. package/skills/manifest.json +8 -1
  128. package/skills/skills/code-brain-hook/SKILL.md +61 -61
  129. package/skills/skills/file-bug/SKILL.md +75 -75
  130. package/skills/skills/inbox/SKILL.md +99 -0
  131. package/skills/skills/multiagent-brainstorm/SKILL.md +164 -164
@@ -1,144 +1,144 @@
1
- ---
2
- name: close-session
3
- description: Deterministic checklist to wrap up an agent session cleanly across all AgentHub persistence layers (org brain, local `.mv2`, auto-memory, session snapshot). The heavy prose + MCP work is delegated to a Sonnet subagent to preserve the Opus budget.
4
- ---
5
-
6
- # Close Session
7
-
8
- Run this at the end of any work session in the Agenthub repo.
9
-
10
- The main session does two cheap steps itself, then delegates the expensive prose-generation + MCP-write work to a Sonnet subagent via the `Agent` tool. Sonnet has a separate usage cap from Opus, so this keeps the Opus budget free for real work.
11
-
12
- ## Step 1 (main session) — Flush + verify local brain capture
13
-
14
- The local `.mv2` brain is only written when the MCP process flushes it — normally on process exit. On Windows that on-exit flush is unreliable (SIGTERM never fires), so the `.mv2` is almost always stale *during* an active session. Don't just check it — **flush it explicitly first**, then verify.
15
-
16
- 1. Call the `mcp__agenthub__brain_flush_session` MCP tool (no args). It flushes this session's journal into the searchable `.mv2` + the server `brain_sessions` table **without** disconnecting. The response is `{ flushed, agent_id, mv2_written }`.
17
-
18
- 2. Confirm `mv2_written: true`. Then sanity-check the file mtime is now fresh:
19
-
20
- ```bash
21
- ls -la ~/.claude/brains/ | grep $(whoami)
22
- ```
23
-
24
- `<agent-id>.mv2` should be modified within the last minute.
25
-
26
- If `brain_flush_session` is unavailable (older MCP build) or returns `mv2_written: false`, fall back to the old behavior — note the staleness and flag it in the handoff. The data is not lost regardless: it stays in `~/.claude/brains/journal/<agent>.jsonl` and is recovered into the `.mv2` on the next MCP startup (`recoverOrphanedJournals`).
27
-
28
- ## Step 2 (main session) — Compile a brief for the subagent
29
-
30
- Produce a *compact* bullet brief (target ~500–1000 output tokens, not 3000+) that the Sonnet subagent will expand into full prose. Collect:
31
-
32
- - **Session topic** — one line.
33
- - **Commits pushed this session** — run `rtk git log --oneline origin/main~10..HEAD` or equivalent to get hashes + subjects.
34
- - **Uncommitted state** — `rtk git status` output, trimmed.
35
- - **Key facts worth sharing to org brain** — 3–10 bullets, each with an implicit category (decision / convention / architecture / blocker / alert / insight). Do NOT write them as final prose — one-line hints are enough; the subagent will polish.
36
- - **Open threads / blockers** — one line each.
37
- - **Next session plan** — 1–3 lines.
38
-
39
- Keep it tight. The subagent will expand; you are not writing the final artifact.
40
-
41
- ## Step 3 (main session) — Delegate everything else to a Sonnet subagent
42
-
43
- Invoke the `Agent` tool:
44
-
45
- ```
46
- Agent(
47
- description: "Close session handoff",
48
- subagent_type: "general-purpose",
49
- model: "sonnet",
50
- prompt: <<<subagent prompt below, with the brief appended>>>
51
- )
52
- ```
53
-
54
- **Subagent prompt (paste the body, append your compact brief from Step 2 after):**
55
-
56
- > You are closing out a work session for the user. You must complete every step below in order. Each step has a concrete side effect — no skipping. Return a short confirmation at the end, not full prose.
57
- >
58
- > Use the **BRIEF** below (provided after this prompt) as your source material. Expand it into the artifacts described.
59
- >
60
- > ### A. Write shareable knowledge to org brain
61
- >
62
- > For each key fact in the BRIEF, call `mcp__agenthub__brain_write_knowledge` with:
63
- > - `category` — one of `decision`, `convention`, `architecture`, `blocker`, `alert`, `insight`.
64
- > - `fact` — one short sentence. Dedup is exact-match normalized on this field; rewordings of something already saved are no-ops.
65
- > - `detail` — the rationale, context, or reference link.
66
- > - `project` — `agenthub`.
67
- >
68
- > If the BRIEF lists no shareable facts, skip — don't fabricate.
69
- >
70
- > ### B. Write a human-readable snapshot
71
- >
72
- > Use the `Write` tool to create `~/.claude/sessions/<YYYY-MM-DD>-<short-topic>.md` with these sections:
73
- >
74
- > - **What shipped** (commits with hashes, features, tests)
75
- > - **What's paused / blocked** and why
76
- > - **Outstanding state** (uncommitted changes, unpushed commits)
77
- > - **Decisions worth remembering** (mirrors the org-brain entries from step A)
78
- > - **Next session prompt** (paste-ready)
79
- >
80
- > Snapshot is for humans. Agents use org brain + local brain + the server report from step C.
81
- >
82
- > ### C. Upload the session report to AgentHub (MANDATORY)
83
- >
84
- > Call `mcp__agenthub__session_close_report` with:
85
- > - `summary` — markdown covering what shipped + outstanding state. Paste-safe; will be passed through verbatim to the next session's `/start-session`.
86
- > - `next_plan` — markdown covering what the next session should pick up.
87
- > - `commits` — array of `{hash, subject}` for commits pushed this session (from the BRIEF).
88
- > - `open_threads` — array of `{topic, blocker}` for unresolved items (from the BRIEF).
89
- >
90
- > This is what `/start-session` reads next, on ANY machine. Without it, cross-machine resume breaks. Server upserts on `(agent_id, session_id)` — idempotent.
91
- >
92
- > ### D. Clear the inbox
93
- >
94
- > Call `mcp__agenthub__check_inbox` with `unread_only: true`. For each message:
95
- > - Addressed to this agent → reply via `mcp__agenthub__reply` or note the required action.
96
- > - Not applicable → note and skip.
97
- >
98
- > Then call `mcp__agenthub__mark_read` to clear the unread flag. Do not mark read without processing — that hides coordination failures.
99
- >
100
- > ### E. Return a compact confirmation
101
- >
102
- > Return this structure (plain text, ~10 lines max):
103
- >
104
- > ```
105
- > close-session complete.
106
- > - Session: <session_display_number from session_close_report response if available, e.g. s-20260425-001>
107
- > - Commits pushed: <N> (<hash short list>)
108
- > - Knowledge entries written: <N> (<categories>)
109
- > - Snapshot: ~/.claude/sessions/<filename>
110
- > - Server report: uploaded (<session_id if available>)
111
- > - Inbox: <N> processed, <M> unread (<brief reason>)
112
- > - Follow-ups: <one line, or "none">
113
- > ```
114
- >
115
- > When `session_close_report` returns, the `session_display_number` field on the response is the canonical short id for this session. Surface it on the first line so the user can refer to "s-YYYYMMDD-NNN" in any follow-up.
116
- >
117
- > Do NOT echo the full summary or next_plan back — the main session doesn't need them in context.
118
- >
119
- > ---
120
- >
121
- > **BRIEF:**
122
- > <<<paste the compact brief from Step 2 here>>>
123
-
124
- ## Step 4 (main session) — Report out
125
-
126
- When the subagent returns, relay its compact confirmation to the user. That's the handoff message. Do not re-generate the summary or next_plan — they are already persisted to AgentHub and the snapshot file.
127
-
128
- ## Why this is structured this way
129
-
130
- - **Determinism** — every step has a concrete side effect (brain entries, snapshot file, server row, inbox state). Missing steps are visible as absent side effects, not as a model "forgetting."
131
- - **Budget** — prose generation (summary, next_plan, snapshot) is the token-heavy part of closing a session. Sonnet generates at equivalent quality for this task and draws from a separate quota, so the Opus budget stays available for actual work.
132
- - **Cross-machine resume** — the server report (Step C) is what `/start-session` reads on the next run, including runs on other machines or instances. Skipping it breaks cross-machine handoff.
133
-
134
- ## Red flags (still apply)
135
-
136
- - "I'll skip the subagent and do it inline since the session was small" — WRONG. The point is to preserve the Opus budget; running inline defeats that regardless of session size.
137
- - "I'll skip the brain writes since nothing felt important" — WRONG. Enumerate all shareable facts in the BRIEF; the subagent dedups via exact-match normalization. Overlap is free.
138
- - "I'll skip the server report since the snapshot is local" — WRONG. Cross-machine resume depends on the server report.
139
- - "I'll trim the BRIEF to save tokens" — WRONG in the other direction. Trim the final artifacts (handled by subagent), not the source facts. Missing facts = missing knowledge.
140
- - "I have 5 minutes — I'll run a partial" — WRONG. A partial close creates worse handoff artifacts than no close. If you truly don't have time, tell the user so they can dispatch a cleanup agent, or run the full checklist when you return.
141
-
142
- ## Time budget
143
-
144
- Main session: ~1–2 minutes (verify + compile brief). Subagent: runs in background while you do other things, typically 2–4 minutes wall-clock. No trimming.
1
+ ---
2
+ name: close-session
3
+ description: Deterministic checklist to wrap up an agent session cleanly across all AgentHub persistence layers (org brain, local `.mv2`, auto-memory, session snapshot). The heavy prose + MCP work is delegated to a Sonnet subagent to preserve the Opus budget.
4
+ ---
5
+
6
+ # Close Session
7
+
8
+ Run this at the end of any work session in the Agenthub repo.
9
+
10
+ The main session does two cheap steps itself, then delegates the expensive prose-generation + MCP-write work to a Sonnet subagent via the `Agent` tool. Sonnet has a separate usage cap from Opus, so this keeps the Opus budget free for real work.
11
+
12
+ ## Step 1 (main session) — Flush + verify local brain capture
13
+
14
+ The local `.mv2` brain is only written when the MCP process flushes it — normally on process exit. On Windows that on-exit flush is unreliable (SIGTERM never fires), so the `.mv2` is almost always stale *during* an active session. Don't just check it — **flush it explicitly first**, then verify.
15
+
16
+ 1. Call the `mcp__agenthub__brain_flush_session` MCP tool (no args). It flushes this session's journal into the searchable `.mv2` + the server `brain_sessions` table **without** disconnecting. The response is `{ flushed, agent_id, mv2_written }`.
17
+
18
+ 2. Confirm `mv2_written: true`. Then sanity-check the file mtime is now fresh:
19
+
20
+ ```bash
21
+ ls -la ~/.claude/brains/ | grep $(whoami)
22
+ ```
23
+
24
+ `<agent-id>.mv2` should be modified within the last minute.
25
+
26
+ If `brain_flush_session` is unavailable (older MCP build) or returns `mv2_written: false`, fall back to the old behavior — note the staleness and flag it in the handoff. The data is not lost regardless: it stays in `~/.claude/brains/journal/<agent>.jsonl` and is recovered into the `.mv2` on the next MCP startup (`recoverOrphanedJournals`).
27
+
28
+ ## Step 2 (main session) — Compile a brief for the subagent
29
+
30
+ Produce a *compact* bullet brief (target ~500–1000 output tokens, not 3000+) that the Sonnet subagent will expand into full prose. Collect:
31
+
32
+ - **Session topic** — one line.
33
+ - **Commits pushed this session** — run `rtk git log --oneline origin/main~10..HEAD` or equivalent to get hashes + subjects.
34
+ - **Uncommitted state** — `rtk git status` output, trimmed.
35
+ - **Key facts worth sharing to org brain** — 3–10 bullets, each with an implicit category (decision / convention / architecture / blocker / alert / insight). Do NOT write them as final prose — one-line hints are enough; the subagent will polish.
36
+ - **Open threads / blockers** — one line each.
37
+ - **Next session plan** — 1–3 lines.
38
+
39
+ Keep it tight. The subagent will expand; you are not writing the final artifact.
40
+
41
+ ## Step 3 (main session) — Delegate everything else to a Sonnet subagent
42
+
43
+ Invoke the `Agent` tool:
44
+
45
+ ```
46
+ Agent(
47
+ description: "Close session handoff",
48
+ subagent_type: "general-purpose",
49
+ model: "sonnet",
50
+ prompt: <<<subagent prompt below, with the brief appended>>>
51
+ )
52
+ ```
53
+
54
+ **Subagent prompt (paste the body, append your compact brief from Step 2 after):**
55
+
56
+ > You are closing out a work session for the user. You must complete every step below in order. Each step has a concrete side effect — no skipping. Return a short confirmation at the end, not full prose.
57
+ >
58
+ > Use the **BRIEF** below (provided after this prompt) as your source material. Expand it into the artifacts described.
59
+ >
60
+ > ### A. Write shareable knowledge to org brain
61
+ >
62
+ > For each key fact in the BRIEF, call `mcp__agenthub__brain_write_knowledge` with:
63
+ > - `category` — one of `decision`, `convention`, `architecture`, `blocker`, `alert`, `insight`.
64
+ > - `fact` — one short sentence. Dedup is exact-match normalized on this field; rewordings of something already saved are no-ops.
65
+ > - `detail` — the rationale, context, or reference link.
66
+ > - `project` — `agenthub`.
67
+ >
68
+ > If the BRIEF lists no shareable facts, skip — don't fabricate.
69
+ >
70
+ > ### B. Write a human-readable snapshot
71
+ >
72
+ > Use the `Write` tool to create `~/.claude/sessions/<YYYY-MM-DD>-<short-topic>.md` with these sections:
73
+ >
74
+ > - **What shipped** (commits with hashes, features, tests)
75
+ > - **What's paused / blocked** and why
76
+ > - **Outstanding state** (uncommitted changes, unpushed commits)
77
+ > - **Decisions worth remembering** (mirrors the org-brain entries from step A)
78
+ > - **Next session prompt** (paste-ready)
79
+ >
80
+ > Snapshot is for humans. Agents use org brain + local brain + the server report from step C.
81
+ >
82
+ > ### C. Upload the session report to AgentHub (MANDATORY)
83
+ >
84
+ > Call `mcp__agenthub__session_close_report` with:
85
+ > - `summary` — markdown covering what shipped + outstanding state. Paste-safe; will be passed through verbatim to the next session's `/start-session`.
86
+ > - `next_plan` — markdown covering what the next session should pick up.
87
+ > - `commits` — array of `{hash, subject}` for commits pushed this session (from the BRIEF).
88
+ > - `open_threads` — array of `{topic, blocker}` for unresolved items (from the BRIEF).
89
+ >
90
+ > This is what `/start-session` reads next, on ANY machine. Without it, cross-machine resume breaks. Server upserts on `(agent_id, session_id)` — idempotent.
91
+ >
92
+ > ### D. Clear the inbox
93
+ >
94
+ > Call `mcp__agenthub__check_inbox` with `unread_only: true`. For each message:
95
+ > - Addressed to this agent → reply via `mcp__agenthub__reply` or note the required action.
96
+ > - Not applicable → note and skip.
97
+ >
98
+ > Then call `mcp__agenthub__mark_read` to clear the unread flag. Do not mark read without processing — that hides coordination failures.
99
+ >
100
+ > ### E. Return a compact confirmation
101
+ >
102
+ > Return this structure (plain text, ~10 lines max):
103
+ >
104
+ > ```
105
+ > close-session complete.
106
+ > - Session: <session_display_number from session_close_report response if available, e.g. s-20260425-001>
107
+ > - Commits pushed: <N> (<hash short list>)
108
+ > - Knowledge entries written: <N> (<categories>)
109
+ > - Snapshot: ~/.claude/sessions/<filename>
110
+ > - Server report: uploaded (<session_id if available>)
111
+ > - Inbox: <N> processed, <M> unread (<brief reason>)
112
+ > - Follow-ups: <one line, or "none">
113
+ > ```
114
+ >
115
+ > When `session_close_report` returns, the `session_display_number` field on the response is the canonical short id for this session. Surface it on the first line so the user can refer to "s-YYYYMMDD-NNN" in any follow-up.
116
+ >
117
+ > Do NOT echo the full summary or next_plan back — the main session doesn't need them in context.
118
+ >
119
+ > ---
120
+ >
121
+ > **BRIEF:**
122
+ > <<<paste the compact brief from Step 2 here>>>
123
+
124
+ ## Step 4 (main session) — Report out
125
+
126
+ When the subagent returns, relay its compact confirmation to the user. That's the handoff message. Do not re-generate the summary or next_plan — they are already persisted to AgentHub and the snapshot file.
127
+
128
+ ## Why this is structured this way
129
+
130
+ - **Determinism** — every step has a concrete side effect (brain entries, snapshot file, server row, inbox state). Missing steps are visible as absent side effects, not as a model "forgetting."
131
+ - **Budget** — prose generation (summary, next_plan, snapshot) is the token-heavy part of closing a session. Sonnet generates at equivalent quality for this task and draws from a separate quota, so the Opus budget stays available for actual work.
132
+ - **Cross-machine resume** — the server report (Step C) is what `/start-session` reads on the next run, including runs on other machines or instances. Skipping it breaks cross-machine handoff.
133
+
134
+ ## Red flags (still apply)
135
+
136
+ - "I'll skip the subagent and do it inline since the session was small" — WRONG. The point is to preserve the Opus budget; running inline defeats that regardless of session size.
137
+ - "I'll skip the brain writes since nothing felt important" — WRONG. Enumerate all shareable facts in the BRIEF; the subagent dedups via exact-match normalization. Overlap is free.
138
+ - "I'll skip the server report since the snapshot is local" — WRONG. Cross-machine resume depends on the server report.
139
+ - "I'll trim the BRIEF to save tokens" — WRONG in the other direction. Trim the final artifacts (handled by subagent), not the source facts. Missing facts = missing knowledge.
140
+ - "I have 5 minutes — I'll run a partial" — WRONG. A partial close creates worse handoff artifacts than no close. If you truly don't have time, tell the user so they can dispatch a cleanup agent, or run the full checklist when you return.
141
+
142
+ ## Time budget
143
+
144
+ Main session: ~1–2 minutes (verify + compile brief). Subagent: runs in background while you do other things, typically 2–4 minutes wall-clock. No trimming.
@@ -28,7 +28,9 @@ Agent(
28
28
 
29
29
  > You are loading the previous session's close report for the user.
30
30
  >
31
- > 1. Call `mcp__agenthub__session_last_report` with no arguments (defaults to the calling agent).
31
+ > **Step 0 — get the tool.** `mcp__agenthub__session_last_report` may be a deferred tool whose schema is not yet loaded, and the `agenthub` MCP server is often still connecting at session start — which is exactly when you run. Call `ToolSearch` with `select:mcp__agenthub__session_last_report`. If the result does not contain the tool's schema, call `ToolSearch` again — up to **5 attempts total**. Each call waits for connecting servers, so repeated attempts are how you wait.
32
+ >
33
+ > 1. Once the schema is loaded, call `mcp__agenthub__session_last_report` with no arguments (defaults to the calling agent).
32
34
  > 2. Inspect the response. It returns `{ "report": null | SessionReport }`.
33
35
  > 3. **If `report` is null** — return this exact text and stop:
34
36
  > ```
@@ -54,24 +56,41 @@ Agent(
54
56
  > - {{open_threads[i].topic}} — {{open_threads[i].blocker}}
55
57
  > ```
56
58
  >
57
- > 5. If the MCP call fails (network, auth, server error), return a one-line error message — do not retry.
59
+ > 5. **If the call was made and failed** (network, auth, server error) — return one line beginning `REPORT FETCH FAILED:` followed by the error. Do not retry.
60
+ > 6. **If after 5 `ToolSearch` attempts the schema never loaded**, so you never made the call — return this exact text and stop:
61
+ > ```
62
+ > TOOL UNAVAILABLE: mcp__agenthub__session_last_report did not load (agenthub MCP still connecting). Previous-session state is UNKNOWN — not confirmed absent.
63
+ > ```
64
+ >
65
+ > **The absent/unreachable distinction is the whole point of this task.** "No previous session report … Starting fresh" is a factual claim that the server was asked and answered *nothing*. You may return it **only** if you received an actual tool response whose `report` field was null.
58
66
  >
59
- > Return ONLY the formatted markdown (or the null/error message). Do not add commentary, headers, or preamble.
67
+ > - Never returned by you if you never called the tool.
68
+ > - Not for "ToolSearch kept saying the server is still connecting."
69
+ > - Not for "I tried several times and gave up."
70
+ > - Not for "there was probably no report anyway."
71
+ > - An unanswered question is not a negative answer. When you could not ask, say you could not ask.
72
+ >
73
+ > Return ONLY the formatted markdown (or the null / TOOL UNAVAILABLE / REPORT FETCH FAILED line). Do not add commentary, headers, or preamble.
60
74
 
61
75
  ## After the subagent returns
62
76
 
63
- Echo the subagent's output to the user verbatim, then append a single line:
77
+ - **Report rendered** — echo it to the user verbatim, then append a single line:
78
+
79
+ > **Pick up where we left off, or take a different direction?**
64
80
 
65
- > **Pick up where we left off, or take a different direction?**
81
+ - **`TOOL UNAVAILABLE` or `REPORT FETCH FAILED`** — do NOT relay it as "starting fresh". The main session then calls `mcp__agenthub__session_last_report` itself once (by this point the MCP has almost always finished connecting) and renders the result. Only if that call also fails do you tell the user the handoff could not be loaded, and say why.
66
82
 
67
83
  ## Rules
68
84
 
69
85
  - Do NOT auto-execute the "next plan" — context may have changed. Render and wait.
70
86
  - Do NOT summarize or rewrite the report body — pass through as-is.
71
- - The main session must not perform the MCP call or format the report itself. That work belongs to the Sonnet subagent so the Opus budget stays reserved for actual work.
87
+ - The main session must not perform the MCP call **on the happy path** — that work belongs to the Sonnet subagent so the Opus budget stays reserved for actual work. The single retry above is the one exception: a few hundred Opus tokens is cheaper than a session that starts blind.
88
+ - Never report a missing handoff on the strength of a tool that would not load. Absent and unreachable are different answers.
72
89
 
73
90
  ## Why this exists
74
91
 
75
92
  Sessions close by writing a report to AgentHub via `mcp__agenthub__session_close_report` (enforced by the `/close-session` command). Any new session on any machine can retrieve that report here, giving cross-machine and cross-instance continuity that the local-filesystem snapshots alone don't provide.
76
93
 
77
94
  Delegation to Sonnet saves the Opus usage cap: the report render is a mechanical formatting task that Sonnet handles at equivalent quality and draws from a separate quota bucket.
95
+
96
+ Step 0 and the two failure exits exist because this command runs at the one moment the `agenthub` MCP server is least likely to be connected. Without them a subagent that never managed to load the tool reports "Starting fresh", and the session silently discards a handoff that was sitting on the server the whole time.
@@ -4,7 +4,8 @@
4
4
  "commands/start-session.md": {
5
5
  "hashes": [
6
6
  "22f4eea1f777318212118f2ffaeb8dbd81f94187bc7060707cdf58540e58ed8a",
7
- "60970d3cc8dc9edfc4cf23b7980cc142b5ab50c3c7772034bba5d98b5735e33b"
7
+ "60970d3cc8dc9edfc4cf23b7980cc142b5ab50c3c7772034bba5d98b5735e33b",
8
+ "b314a7f3dcb179024f5f3334f3d1033386b629cd540768042d4e2c54590ef3c4"
8
9
  ]
9
10
  },
10
11
  "commands/close-session.md": {
@@ -46,6 +47,12 @@
46
47
  "b3792bb7e44a5f581172d94c5b145ef6c1420e28426f796a38594250a28f1de1",
47
48
  "aff7ed284060cd0e157c35b2572047a42144eef80d4299f3592a5caf9ef240e5"
48
49
  ]
50
+ },
51
+ "skills/inbox/SKILL.md": {
52
+ "hashes": [
53
+ "e7cacbf45ac93de3c8b23705fd94d4f03be9f01a3970050e1c3ebf06665d04cb",
54
+ "bf4a56716ecf89534e790e66edcc88a01d0bc8d7e99e13c9c85119c8579fc393"
55
+ ]
49
56
  }
50
57
  }
51
58
  }
@@ -1,61 +1,61 @@
1
- ---
2
- name: code-brain-hook
3
- description: add-code-brain — opt-in awareness pattern. When the user asks a question about org-wide code or architecture and brain_org_search returns no written knowledge, call brain_code_recall to surface relevant files, symbols, and docs from indexed org repositories before answering.
4
- license: MIT
5
- ---
6
-
7
- # Code Brain Hook
8
-
9
- The server-side **code brain** clones the configured branch of every registered org repository and indexes the docs + code. The result is queryable via the `brain_code_recall` MCP tool. This skill teaches when and how to use it.
10
-
11
- **Trigger conditions** (any one is enough):
12
-
13
- - The user asks "how does X work", "where does Y live", "what's the architecture of Z", and the answer should be grounded in actual org code.
14
- - `brain_org_search` returns zero results for a code- or architecture-shaped query.
15
- - You're about to suggest an implementation pattern and want to check what already exists in the org first.
16
-
17
- **How to use:**
18
-
19
- ```
20
- brain_code_recall({
21
- query: "payment gateway architecture",
22
- k: 5,
23
- kinds: ["docs", "symbols"]
24
- })
25
- ```
26
-
27
- Returns a ranked list of `{Result: doc|symbol, RepoID, Path, Kind, TitleOrSymbol, Snippet}`. Use the `Path` to read the actual file (via `Read`) or `intel_code_definition` for deeper symbol info.
28
-
29
- **What it is NOT:**
30
-
31
- - Not a replacement for `brain_org_search` — that's still the right tool for human-written decisions, conventions, and blockers. Code brain is for code-derived facts.
32
- - Not a substitute for reading the file. The recall surfaces pointers; the agent reads the source.
33
- - Not write-capable. Read-only.
34
-
35
- **When the code brain is disabled** (operator has explicitly set `AGENTHUB_CODE_BRAIN_ENABLED=false`; default is true), `brain_code_recall` returns `{error: "code_brain_disabled"}`. Treat as a soft signal — fall back to `brain_org_search` and explicit file reads.
36
-
37
- ## Optional: UserPromptSubmit hook
38
-
39
- Operators who want automatic code-aware context can wire a UserPromptSubmit hook that calls `brain_code_recall` on every prompt and prepends top hits. Gated by `AGENTHUB_CODE_HOOK_ENABLED=true`. Off by default — the hook adds latency to every prompt.
40
-
41
- Setup (in `~/.claude/settings.json`):
42
-
43
- ```json
44
- {
45
- "hooks": {
46
- "UserPromptSubmit": [
47
- {
48
- "matcher": ".*",
49
- "hooks": [
50
- {
51
- "type": "command",
52
- "command": "agenthub-code-brain-prepend"
53
- }
54
- ]
55
- }
56
- ]
57
- }
58
- }
59
- ```
60
-
61
- The command reads the prompt from stdin, calls `brain_code_recall` via the MCP server, and writes the augmented prompt back. See `docs/brain-code-recall-mcp.md` for the full reference and example shell wrapper.
1
+ ---
2
+ name: code-brain-hook
3
+ description: add-code-brain — opt-in awareness pattern. When the user asks a question about org-wide code or architecture and brain_org_search returns no written knowledge, call brain_code_recall to surface relevant files, symbols, and docs from indexed org repositories before answering.
4
+ license: MIT
5
+ ---
6
+
7
+ # Code Brain Hook
8
+
9
+ The server-side **code brain** clones the configured branch of every registered org repository and indexes the docs + code. The result is queryable via the `brain_code_recall` MCP tool. This skill teaches when and how to use it.
10
+
11
+ **Trigger conditions** (any one is enough):
12
+
13
+ - The user asks "how does X work", "where does Y live", "what's the architecture of Z", and the answer should be grounded in actual org code.
14
+ - `brain_org_search` returns zero results for a code- or architecture-shaped query.
15
+ - You're about to suggest an implementation pattern and want to check what already exists in the org first.
16
+
17
+ **How to use:**
18
+
19
+ ```
20
+ brain_code_recall({
21
+ query: "payment gateway architecture",
22
+ k: 5,
23
+ kinds: ["docs", "symbols"]
24
+ })
25
+ ```
26
+
27
+ Returns a ranked list of `{Result: doc|symbol, RepoID, Path, Kind, TitleOrSymbol, Snippet}`. Use the `Path` to read the actual file (via `Read`) or `intel_code_definition` for deeper symbol info.
28
+
29
+ **What it is NOT:**
30
+
31
+ - Not a replacement for `brain_org_search` — that's still the right tool for human-written decisions, conventions, and blockers. Code brain is for code-derived facts.
32
+ - Not a substitute for reading the file. The recall surfaces pointers; the agent reads the source.
33
+ - Not write-capable. Read-only.
34
+
35
+ **When the code brain is disabled** (operator has explicitly set `AGENTHUB_CODE_BRAIN_ENABLED=false`; default is true), `brain_code_recall` returns `{error: "code_brain_disabled"}`. Treat as a soft signal — fall back to `brain_org_search` and explicit file reads.
36
+
37
+ ## Optional: UserPromptSubmit hook
38
+
39
+ Operators who want automatic code-aware context can wire a UserPromptSubmit hook that calls `brain_code_recall` on every prompt and prepends top hits. Gated by `AGENTHUB_CODE_HOOK_ENABLED=true`. Off by default — the hook adds latency to every prompt.
40
+
41
+ Setup (in `~/.claude/settings.json`):
42
+
43
+ ```json
44
+ {
45
+ "hooks": {
46
+ "UserPromptSubmit": [
47
+ {
48
+ "matcher": ".*",
49
+ "hooks": [
50
+ {
51
+ "type": "command",
52
+ "command": "agenthub-code-brain-prepend"
53
+ }
54
+ ]
55
+ }
56
+ ]
57
+ }
58
+ }
59
+ ```
60
+
61
+ The command reads the prompt from stdin, calls `brain_code_recall` via the MCP server, and writes the augmented prompt back. See `docs/brain-code-recall-mcp.md` for the full reference and example shell wrapper.