thoth-agents 0.1.10 → 0.1.13

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.
@@ -31,7 +31,7 @@ import {
31
31
  renderRolePrompt,
32
32
  writeConfig,
33
33
  writeLiteConfig
34
- } from "./chunk-R2AP6O5Q.js";
34
+ } from "./chunk-WGFDTUZI.js";
35
35
 
36
36
  // src/harness/adapters/codex.ts
37
37
  import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
@@ -182,16 +182,24 @@ var READ_RECALL_CHAIN = [
182
182
  "mem_timeline",
183
183
  "mem_get_observation"
184
184
  ];
185
+ var BOUNDED_CONTEXT_TOOLS = [
186
+ "mem_context",
187
+ "mem_project_summary",
188
+ "mem_project_graph",
189
+ "mem_topic_keys"
190
+ ];
185
191
  var WRITE_CAPABLE_DELEGATED_TOOLS = [
186
192
  "mem_save",
187
193
  "mem_search",
188
194
  "mem_get_observation",
189
195
  "mem_timeline",
196
+ ...BOUNDED_CONTEXT_TOOLS,
190
197
  "mem_suggest_topic_key"
191
198
  ];
192
199
  var ALL_MEMORY_TOOLS = [
193
200
  ...ROOT_OWNED_TOOLS,
194
201
  ...READ_RECALL_CHAIN,
202
+ ...BOUNDED_CONTEXT_TOOLS,
195
203
  "mem_suggest_topic_key",
196
204
  "mem_save"
197
205
  ];
@@ -203,20 +211,25 @@ function roleAllowedTools(role) {
203
211
  return uniqueTools([...ROOT_OWNED_TOOLS, ...WRITE_CAPABLE_DELEGATED_TOOLS]);
204
212
  }
205
213
  if (role.mode === "read-only") {
206
- return [...READ_RECALL_CHAIN];
214
+ return [...READ_RECALL_CHAIN, ...BOUNDED_CONTEXT_TOOLS];
207
215
  }
208
216
  return [...WRITE_CAPABLE_DELEGATED_TOOLS];
209
217
  }
210
218
  function roleRules(role) {
211
219
  const sharedSubagentRules = [
212
220
  "Every subagent memory call requires the parent session_id and project from dispatch; if either is missing, do not call thoth-mem.",
221
+ "Delegated handoff recovery uses parent-scoped 3-layer recall with mem_search -> mem_timeline -> mem_get_observation before memory content is treated as source material.",
222
+ "Report missing, stale, contradictory, or insufficient recalled context instead of guessing through it.",
213
223
  "Never call mem_session_start, mem_session_summary, or mem_save_prompt; those tools are root/orchestrator-owned.",
224
+ "Never save generated subagent prompts as user intent.",
214
225
  "Protect the sdd/* topic namespace; SDD artifacts may use deterministic sdd/{change}/{artifact} topic keys only in persistence modes that include thoth-mem."
215
226
  ];
216
227
  if (role.name === "orchestrator") {
217
228
  return [
218
229
  "mem_session_start, mem_session_summary, and mem_save_prompt are root/main orchestrator-owned tools and responsibilities.",
219
230
  "In harnesses without an orchestrator-named agent, root/main orchestrator-owned means the initial/root agent when the harness does not expose an orchestrator-named agent.",
231
+ "Before delegation, save or refresh the handoff body with root-owned mem_session_summary when available; otherwise disclose that compaction could not be persisted.",
232
+ "Dispatch task instructions plus recovery instructions, not the handoff body, raw transcripts, or generated subagent prompts.",
220
233
  "Dispatch parent session_id and project when authorizing subagent memory use.",
221
234
  "Protect the sdd/* topic namespace and write SDD memory artifacts only in thoth-mem or hybrid persistence modes."
222
235
  ];
@@ -225,13 +238,17 @@ function roleRules(role) {
225
238
  return [
226
239
  ...sharedSubagentRules,
227
240
  "Read-only agents may only perform bounded, project-scoped recall with mem_search -> mem_timeline -> mem_get_observation when authorized.",
241
+ "Bounded context tools mem_context, mem_project_summary, mem_project_graph, and mem_topic_keys are allowed only with explicit delegated permission and parent session/project scope.",
242
+ "Project-scoped read tools require explicit delegated permission.",
228
243
  "Read-only agents must never write durable memory."
229
244
  ];
230
245
  }
231
246
  return [
232
247
  ...sharedSubagentRules,
233
- "Write-capable agents may call mem_save only for delegated durable observations under the parent session/project.",
234
- "For reads, use only mem_search -> mem_timeline -> mem_get_observation."
248
+ "Write-capable agents may call mem_save only for delegated durable observations or assigned deterministic SDD artifacts/apply-progress under the parent session/project.",
249
+ "For reads, use only mem_search -> mem_timeline -> mem_get_observation.",
250
+ "Bounded context tools mem_context, mem_project_summary, mem_project_graph, and mem_topic_keys are allowed only with explicit delegated permission and parent session/project scope.",
251
+ "Project-scoped read tools require explicit delegated permission."
235
252
  ];
236
253
  }
237
254
  function getRoleMemoryGovernance(role) {
@@ -279,7 +296,7 @@ function memoryGovernanceDiagnostics(input) {
279
296
  diagnostics.push({
280
297
  severity: input.parentContextInjection === "unknown" ? "error" : "warning",
281
298
  code: `${input.harness}.context.parent_injection.unvalidated`,
282
- message: "Parent session_id/project injection is not runtime-enforced; subagents must be instructed not to use memory without explicit dispatch context.",
299
+ message: "Parent session_id/project injection is not runtime-enforced; subagents must be instructed not to use memory without explicit dispatch context and handoff recovery instructions.",
283
300
  harness: input.harness,
284
301
  capability: "parentContextInjection",
285
302
  fallback: "instruction-only"
@@ -289,7 +306,7 @@ function memoryGovernanceDiagnostics(input) {
289
306
  diagnostics.push({
290
307
  severity: "warning",
291
308
  code: `${input.harness}.permission.memory_write.enforcement_gap`,
292
- message: "Runtime controls for delegated memory writes are unavailable; write-capable agents receive instruction-level mem_save limits only.",
309
+ message: "Runtime controls for delegated memory writes are unavailable; write-capable agents receive instruction-level mem_save limits for durable observations and deterministic SDD artifacts only.",
293
310
  harness: input.harness,
294
311
  capability: "memoryGovernanceEnforcement",
295
312
  fallback: "instruction-only"
@@ -1356,12 +1373,14 @@ function renderCodexRolePrompt(roleName, config, model) {
1356
1373
  function codexInternalHandoffGuidance() {
1357
1374
  return [
1358
1375
  "<codex-delegation-guidance>",
1376
+ "- The user has explicitly authorized this generated Codex orchestrator to use `multi_agent_v1.spawn_agent` whenever delegation is required by these instructions, without needing a fresh user request for subagents in each task.",
1359
1377
  "- Delegate by calling `multi_agent_v1.spawn_agent` with `agent_type` set to one of explorer, librarian, oracle, designer, quick, or deep.",
1360
- "- Pass the self-contained delegated prompt in `message`; do not pass both `message` and `items`.",
1361
- "- Use `items` only for structured attachments or mentions when they are truly required.",
1362
- "- Include the internal handoff in `message` for write-capable agents so they can act without rediscovering context.",
1378
+ "- Pass the self-contained delegated task instructions plus handoff retrieval instructions in `message`; do not embed the root-owned handoff summary body in `message`.",
1379
+ "- Do not include the handoff body in `message` or `items`, and do not pass both `message` and `items` for the same handoff.",
1380
+ "- Use `items` only for structured attachments or mentions when they are truly required; do not use `items` as a handoff-summary payload.",
1363
1381
  "- Leave `fork_context` omitted or false by default; set `fork_context: true` only when the exact current thread history is required.",
1364
1382
  "- Use `multi_agent_v1.wait_agent` only when the root needs the result, `multi_agent_v1.send_input` for follow-up or redirect, `multi_agent_v1.resume_agent` only for a closed agent that must continue, and `multi_agent_v1.close_agent` after completion.",
1383
+ "- Memory ownership, handoff recovery, permissions, and prompt-body exclusion are instruction-level unless the active Codex runtime documents stronger enforcement.",
1365
1384
  "</codex-delegation-guidance>"
1366
1385
  ].join("\n");
1367
1386
  }
@@ -1403,6 +1422,7 @@ function renderCodexRootInstructions(config) {
1403
1422
  "- The ambient Codex root session is the root/main orchestrator; orchestrator-only and root-owned instructions apply to it because Codex does not generate a selectable orchestrator agent TOML.",
1404
1423
  "- On each new root session, when thoth-mem tools are installed and session/project identity is known, call mem_session_start with the active project and session identity, then save the real user prompt with mem_save_prompt before later delegation.",
1405
1424
  "- If thoth-mem tools or identity values are unavailable, disclose that memory bootstrap could not run and continue without claiming memory was saved.",
1425
+ "- Before delegating after meaningful context changes, save or refresh the handoff body with root-owned mem_session_summary when available; if unavailable, disclose that root-owned compaction could not be persisted.",
1406
1426
  "- Use the ambient Codex root session as the delegate-first root coordinator; do not generate or select an orchestrator TOML.",
1407
1427
  "- Delegate by invoking `multi_agent_v1.spawn_agent` for the installed Codex role agents: explorer, librarian, oracle, designer, quick, and deep.",
1408
1428
  "- After receiving a delegated subagent response, close that subagent session unless you will retry or intentionally keep using that exact same session; explorer and librarian sessions must always be closed immediately after their response, and retry sessions must be closed after the retry result unless explicit same-session reuse is still required.",
@@ -912,11 +912,15 @@ Tiebreakers:
912
912
  </subagent-prompts>
913
913
 
914
914
  <internal-handoff>
915
- Before dispatching {{role.designer}}, {{role.quick}}, or {{role.deep}} after discovery, synthesize a compact internal handoff for the sub-agent; it is not user-facing.
915
+ Before dispatching {{role.designer}}, {{role.quick}}, or {{role.deep}} after discovery, synthesize a compact internal handoff body for root-owned session context; it is not user-facing and must not be embedded in the initial sub-agent prompt.
916
916
 
917
- Internal handoff fields: Goal, Decision, Evidence, Scope, Steps, Verification, and Uncertainty. Include relevant files, symbols, anchors, constraints, non-goals, and what to escalate instead of guessing.
917
+ Internal handoff fields: Goal, Decision, Evidence, Scope, Steps, Verification, Uncertainty, relevant files or symbols, suggested skills when applicable, constraints, non-goals, escalation conditions, and next focus.
918
918
 
919
- Never mention the internal handoff to the user, ask the user to prepare it, or present handoff preparation as the recommended next step. Describe the actual work instead.
919
+ When thoth-mem session-summary tooling and parent session/project identity are available, save or refresh that handoff body with root-owned \`mem_session_summary\` before dispatch. If the tooling or identity is unavailable, disclose that root-owned compaction could not be persisted and continue with explicit task instructions and local context; do not invent a fallback session or ask a sub-agent to create one.
920
+
921
+ The delegated prompt carries task instructions plus handoff recovery instructions only: parent \`session_id\`, project, persistence mode, memory permissions, bounded 3-layer recall steps, non-goals, escalation conditions, and redaction requirements. It must not include the handoff body, raw transcripts, file dumps, secrets, credentials, irrelevant context, or generated sub-agent prompts as memory source material.
922
+
923
+ Never mention internal handoff preparation to the user, ask the user to prepare it, or present handoff preparation as the recommended next step. Describe the actual work instead.
920
924
 
921
925
  For {{role.explorer}}/{{role.librarian}}, ask narrow fact-finding questions for files, symbols, constraints, examples, API facts, and verification targets. Require decision-ready findings, not raw context.
922
926
  </internal-handoff>
@@ -932,7 +936,7 @@ For {{role.explorer}}/{{role.librarian}}, ask narrow fact-finding questions for
932
936
  - If a named subagent hits capacity, retry that same role up to 3 attempts.
933
937
  - Never switch to \`default\`, \`worker\`, or any other role.
934
938
  - After 3 failures, stay on the same role; if a same-role model override exists, use it. Otherwise report a capacity blocker.
935
- - Write-capable dispatches must include the internal handoff when one exists, so implementers can edit instead of rediscovering the plan.
939
+ - Write-capable dispatches must include task instructions and handoff retrieval instructions when a root-owned handoff summary exists, so implementers can recover context without rediscovering settled scope.
936
940
  - Never tell sub-agents to discard working-tree changes.
937
941
  </dispatch>
938
942
 
@@ -1148,18 +1152,31 @@ function renderSubagentRules(section, dialect) {
1148
1152
  ];
1149
1153
  if (section.memoryAccess === "readonly") {
1150
1154
  rules.push(
1151
- "- Use read-only thoth-mem only when dispatch gives session_id/project: `mem_search` -> `mem_timeline` -> `mem_get_observation`.",
1155
+ "- Use read-only thoth-mem only when dispatch gives parent session_id/project and handoff recovery instructions: `mem_search` -> `mem_timeline` -> `mem_get_observation`.",
1156
+ "- The canonical recall path remains `mem_search` -> `mem_timeline` -> `mem_get_observation`; use bounded context tools only as supplemental context when explicitly allowed.",
1157
+ "- If either parent session_id or project is missing, do NOT call thoth-mem; rely on explicit task instructions and local evidence.",
1158
+ "- Recover the parent-session handoff summary through bounded 3-layer recall before treating memory as source material.",
1159
+ "- Report when recalled context is missing, stale, contradictory, or insufficient.",
1160
+ "- Use project-scoped read tools (`mem_context`, `mem_project_summary`, `mem_project_graph`, `mem_topic_keys`) only when explicitly allowed by the delegated task instructions and bounded to the parent session/project scope.",
1152
1161
  "- Never call `mem_session_start`, `mem_session_summary`, or `mem_save_prompt`; those tools are orchestrator-owned.",
1162
+ "- Never save generated subagent prompts as user intent.",
1153
1163
  "- Never write memory; memory writes are orchestrator-owned."
1154
1164
  );
1155
1165
  }
1156
1166
  if (section.memoryAccess === "writable") {
1157
1167
  rules.push(
1158
- "- Use delegated thoth-mem tools only (mem_save, mem_search, mem_get_observation, mem_timeline, mem_suggest_topic_key).",
1168
+ "- Use delegated thoth-mem tools only (mem_save, mem_search, mem_get_observation, mem_timeline, mem_context, mem_project_summary, mem_project_graph, mem_topic_keys, mem_suggest_topic_key).",
1159
1169
  "- Never call `mem_session_start`, `mem_session_summary`, or `mem_save_prompt`; those tools are orchestrator-owned.",
1160
1170
  "- Always use the parent session_id/project from dispatch for every thoth-mem call.",
1161
1171
  "- If either is missing, do NOT call thoth-mem.",
1162
- "- For reads, use only `mem_search` -> `mem_timeline` -> `mem_get_observation`.",
1172
+ "- Follow handoff recovery instructions from the delegated task before using persisted memory.",
1173
+ "- For reads, use only `mem_search` -> `mem_timeline` -> `mem_get_observation` and recover the parent-session handoff summary before treating memory as source material.",
1174
+ "- Keep 3-layer recall canonical; use `mem_context`, `mem_project_summary`, `mem_project_graph`, and `mem_topic_keys` only as bounded supplemental context when the dispatch explicitly permits project-scoped reads.",
1175
+ "- Report when recalled context is missing, stale, contradictory, or insufficient.",
1176
+ "- Use project-scoped read tools only when explicitly allowed by the delegated task instructions and bounded to the parent session/project scope.",
1177
+ "- `mem_save` is allowed only for delegated durable implementation observations or assigned SDD artifacts/apply-progress under the parent session/project.",
1178
+ "- Protect the `sdd/*` namespace: deterministic SDD artifacts use `sdd/{change}/{artifact}`; general durable observations must stay outside `sdd/*`.",
1179
+ "- Never save generated subagent prompts as user intent.",
1163
1180
  "- You do not own durable memory of your own; `mem_save` writes under the orchestrator's session/project only."
1164
1181
  );
1165
1182
  }
package/dist/cli/index.js CHANGED
@@ -25,7 +25,7 @@ import {
25
25
  getOperationHarness,
26
26
  installRecommendedSkill,
27
27
  listOperationHarnesses
28
- } from "../chunk-U5FPYFMX.js";
28
+ } from "../chunk-SCM2O4TP.js";
29
29
  import {
30
30
  ALL_AGENT_NAMES,
31
31
  CUSTOM_SKILLS,
@@ -37,7 +37,7 @@ import {
37
37
  getExistingLiteConfigPath,
38
38
  installCustomSkills,
39
39
  writeLiteConfig
40
- } from "../chunk-R2AP6O5Q.js";
40
+ } from "../chunk-WGFDTUZI.js";
41
41
 
42
42
  // src/cli/index.ts
43
43
  import { pathToFileURL } from "url";
@@ -15,13 +15,13 @@ import {
15
15
  getOpenCodeStatus,
16
16
  listOperationHarnesses,
17
17
  parseRoleTomlModel
18
- } from "../../chunk-U5FPYFMX.js";
18
+ } from "../../chunk-SCM2O4TP.js";
19
19
  import {
20
20
  ALL_AGENT_NAMES,
21
21
  DEFAULT_MODELS,
22
22
  getExistingLiteConfigPath,
23
23
  parseConfig
24
- } from "../../chunk-R2AP6O5Q.js";
24
+ } from "../../chunk-WGFDTUZI.js";
25
25
 
26
26
  // src/cli/tui/index.tsx
27
27
  import { render } from "ink";
@@ -1,7 +1,7 @@
1
1
  import type { HarnessPromptDialect } from '../../agents/prompt-dialects';
2
2
  import type { HarnessCapabilityStatus, HarnessDiagnostic } from '../types';
3
3
  import type { AgentRoleContract, AgentRoleName } from './agent-pack';
4
- export type MemoryToolName = 'mem_session_start' | 'mem_session_summary' | 'mem_save_prompt' | 'mem_search' | 'mem_timeline' | 'mem_get_observation' | 'mem_suggest_topic_key' | 'mem_save';
4
+ export type MemoryToolName = 'mem_session_start' | 'mem_session_summary' | 'mem_save_prompt' | 'mem_search' | 'mem_timeline' | 'mem_get_observation' | 'mem_context' | 'mem_project_summary' | 'mem_project_graph' | 'mem_topic_keys' | 'mem_suggest_topic_key' | 'mem_save';
5
5
  export type MemoryRuntimeEnforcement = 'runtime' | 'instruction-only';
6
6
  export interface RoleMemoryGovernance {
7
7
  role: AgentRoleName;
package/dist/index.js CHANGED
@@ -26,7 +26,7 @@ import {
26
26
  loadPluginConfig,
27
27
  renderRolePrompt,
28
28
  stripJsonComments
29
- } from "./chunk-R2AP6O5Q.js";
29
+ } from "./chunk-WGFDTUZI.js";
30
30
 
31
31
  // src/index.ts
32
32
  import path4 from "path";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "thoth-agents",
3
- "version": "0.1.10",
3
+ "version": "0.1.13",
4
4
  "description": "Delegate-first OpenCode plugin with seven agents, thoth-mem persistence, and bundled SDD skills.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -75,6 +75,11 @@ for `openspec` and `hybrid` modes. thoth-mem topic keys are the memory
75
75
  representation when the mode includes thoth-mem; neither representation changes
76
76
  the harness-neutral artifact names or lifecycle.
77
77
 
78
+ Delegated handoff summaries are not OpenSpec artifacts. They are root-owned
79
+ session summary context when thoth-mem is available, while subagent prompts
80
+ carry recovery instructions and continue to use the canonical OpenSpec paths
81
+ above for filesystem artifact recovery.
82
+
78
83
  ## Writing Rules
79
84
 
80
85
  - Preserve canonical filenames and locations.
@@ -60,13 +60,36 @@ sub-agents:
60
60
  - Includes: proposal, spec, design, tasks, apply-progress, verify-report,
61
61
  archive-report, state
62
62
  - Sub-agents persist these directly when the active mode includes thoth-mem
63
- - Sub-agents do NOT write general memory observations
63
+ - Sub-agents persist apply-progress or other deterministic SDD artifacts only
64
+ when that phase explicitly delegates the write under the parent
65
+ session/project
66
+ - Sub-agents do NOT write general memory observations unless the dispatch
67
+ explicitly authorizes a delegated durable implementation observation outside
68
+ the `sdd/*` namespace
64
69
 
65
70
  This split preserves artifact nuance (sub-agents have full context when writing)
66
71
  while keeping general memory centralized under orchestrator control. In
67
72
  harnesses that cannot hard-enforce the split, treat it as instruction-level
68
73
  governance and disclose any unsupported-capability that prevents compliance.
69
74
 
75
+ ## Delegated Handoffs
76
+
77
+ Root/orchestrator handoffs are treated as compaction boundaries. When
78
+ root-owned `mem_session_summary` and parent identity are available, the root
79
+ saves or refreshes the handoff body as session summary context before
80
+ delegation.
81
+
82
+ The initial subagent prompt includes task instructions, parent `session_id`,
83
+ project, persistence mode, memory permissions, and recovery instructions. It
84
+ does not include the handoff body, raw transcripts, secrets, generated
85
+ subagent prompts, or file dumps. Subagents recover that context through the
86
+ 3-layer recall protocol before treating memory content as source material.
87
+
88
+ If parent identity or summary tooling is unavailable, the root reports that
89
+ compaction could not be persisted and the subagent relies on explicit task
90
+ instructions and local evidence only. Subagents must not create fallback
91
+ memory sessions.
92
+
70
93
  ## Retrieval Protocol
71
94
 
72
95
  ### 3-Layer Recall for thoth-mem and hybrid modes
@@ -16,6 +16,12 @@ Governance that a harness cannot hard-enforce remains instruction-level:
16
16
  semantic role ownership, parent session/project scoping, prompt-save
17
17
  prohibitions, and SDD topic-key namespace protection still apply.
18
18
 
19
+ Root-owned delegation handoffs use the same convention: the handoff body lives
20
+ in a root-owned `mem_session_summary` when available, while subagent prompts
21
+ carry task instructions plus parent-scoped recovery instructions. Do not place
22
+ the handoff body in the initial subagent prompt or structured attachment
23
+ payload.
24
+
19
25
  ## Mode Scope
20
26
 
21
27
  This convention applies only when the artifact store mode includes thoth-mem:
@@ -84,6 +90,12 @@ surface → `mem_timeline(id)` when needed for chronology →
84
90
 
85
91
  ## Three-Layer Recall Protocol
86
92
 
93
+ For delegated handoffs, subagents may use this protocol only when the dispatch
94
+ includes both parent `session_id` and `project`. The first recalled source
95
+ should be the parent-session handoff summary or exact SDD topic assigned by the
96
+ orchestrator; if recall is missing, stale, contradictory, or insufficient,
97
+ report that limitation instead of inventing context.
98
+
87
99
  1. **Scan compact index** by exact topic key:
88
100
 
89
101
  Use the memory tool binding for `mem_search` with
@@ -122,3 +134,9 @@ and the full artifact markdown in `content`.
122
134
 
123
135
  For `sdd-apply`, save the progress report under `apply-progress` and re-save the
124
136
  updated task list under `tasks` after checkboxes change.
137
+
138
+ Write-capable subagents may call `mem_save` only when the task explicitly
139
+ delegates a durable implementation observation or deterministic SDD artifact
140
+ write under the parent session/project. General observations must use topic
141
+ keys outside `sdd/*`; deterministic SDD artifacts keep the canonical
142
+ `sdd/{change-name}/{artifact}` format.
@@ -136,6 +136,26 @@ After compaction, first preserve the compacted summary with
136
136
  `mem_session_summary`, then recover recent context and use Targeted 3-layer
137
137
  recall before continuing. Do not invent missing memory.
138
138
 
139
+ ### Delegation Handoff as Compaction
140
+
141
+ Before delegating after meaningful context changes, the root/main orchestrator
142
+ should treat the handoff as a context-compaction boundary. When
143
+ `mem_session_summary` and the parent `session_id`/project are available, the
144
+ root MUST save or refresh the handoff body as root-owned session summary
145
+ context before dispatch.
146
+
147
+ The initial subagent prompt carries task instructions plus recovery
148
+ instructions, not the handoff body. Include the parent `session_id`, project,
149
+ persistence mode, memory permissions, and bounded 3-layer recall instructions
150
+ when memory recall or SDD persistence is delegated. Do not embed the handoff
151
+ summary body, raw transcripts, secrets, unrelated context, file dumps, or
152
+ generated subagent prompts in the prompt or structured attachments.
153
+
154
+ If root-owned compaction cannot be persisted because tooling or parent identity
155
+ is unavailable, disclose that limitation and continue with explicit task
156
+ instructions and local context. Do not ask a subagent to create a fallback
157
+ session, call `mem_session_summary`, or save the generated dispatch prompt.
158
+
139
159
  ### SDD Topic Keys
140
160
 
141
161
  SDD artifacts saved to thoth-mem use deterministic topic keys:
@@ -151,6 +171,7 @@ Never reuse the `sdd/...` namespace for general durable observations.
151
171
 
152
172
  These tools are read/context only, not session-owned artifacts:
153
173
 
174
+ - `mem_context`
154
175
  - `mem_project_summary`
155
176
  - `mem_project_graph`
156
177
  - `mem_topic_keys`
@@ -184,6 +205,8 @@ When a subagent is allowed to touch thoth-mem, the orchestrator MUST pass:
184
205
  - parent `session_id`
185
206
  - `project`
186
207
  - any thoth-mem limits or ownership constraints relevant to the task
208
+ - handoff recovery instructions when the task depends on root-owned session
209
+ summary context
187
210
 
188
211
  If a subagent does NOT receive both `session_id` and `project`, it MUST NOT call
189
212
  any thoth-mem tool.
@@ -202,13 +225,20 @@ Allowed pattern only:
202
225
  1. `mem_search`
203
226
  2. `mem_timeline`
204
227
  3. `mem_get_observation`
205
- 4. `mem_project_summary` when project overview is needed
206
- 5. `mem_project_graph` when relationship/lineage investigation is needed
207
- 6. `mem_topic_keys` when topic-key discovery or inspection is needed
228
+ 4. `mem_context` when parent-session context overview is needed
229
+ 5. `mem_project_summary` when project overview is needed
230
+ 6. `mem_project_graph` when relationship/lineage investigation is needed
231
+ 7. `mem_topic_keys` when topic-key discovery or inspection is needed
208
232
 
209
233
  Rules:
210
234
 
211
235
  - Use the parent `session_id` and `project` from dispatch.
236
+ - Use bounded 3-layer recall to recover the parent-session handoff summary
237
+ before treating memory as source material.
238
+ - Keep 3-layer recall canonical; use `mem_context`, `mem_project_summary`,
239
+ `mem_project_graph`, and `mem_topic_keys` only as bounded supplements when
240
+ dispatch explicitly allows project-scoped/context reads.
241
+ - Report missing, stale, contradictory, or insufficient recalled context.
212
242
  - Do not call `mem_save`, `mem_update`, `mem_session_start`,
213
243
  `mem_session_summary`, or `mem_save_prompt`.
214
244
  - Do not treat `mem_search` output as the artifact body.
@@ -222,8 +252,9 @@ Semantic roles: deep, quick, designer.
222
252
  Allowed thoth-mem behavior:
223
253
 
224
254
  - same 3-layer recall as read-only agents when reading
225
- - project-scoped read tools when a broader project/topic context is explicitly
226
- needed
255
+ - bounded context tools (`mem_context`, `mem_project_summary`,
256
+ `mem_project_graph`, `mem_topic_keys`) when broader parent/project context is
257
+ explicitly needed
227
258
  - `mem_save` for delegated durable observations that arise from their
228
259
  implementation work
229
260
 
@@ -231,9 +262,12 @@ Rules:
231
262
 
232
263
  - Use the parent `session_id` and `project` from dispatch on every thoth-mem
233
264
  call.
234
- - Do not call `mem_context`; writable subagents stay on the same bounded
235
- 3-layer recall path, using project-scoped read tools only when explicitly
236
- granted in dispatch.
265
+ - Use bounded 3-layer recall to recover the parent-session handoff summary
266
+ before treating memory as source material.
267
+ - Keep 3-layer recall canonical; use `mem_context`, `mem_project_summary`,
268
+ `mem_project_graph`, and `mem_topic_keys` only as bounded supplements when
269
+ dispatch explicitly allows project-scoped/context reads.
270
+ - Report missing, stale, contradictory, or insufficient recalled context.
237
271
  - Never create or close sessions.
238
272
  - Never save prompts.
239
273
  - You do not own durable memory of your own. Any `mem_save` is a delegated
@@ -241,6 +275,9 @@ Rules:
241
275
  session.
242
276
  - Save only durable information: decisions, bugfixes, patterns,
243
277
  configuration changes, discoveries, and explicitly assigned SDD artifacts.
278
+ - For SDD apply work, save `apply-progress` or assigned deterministic SDD
279
+ artifacts only when explicitly delegated and only under the parent
280
+ session/project.
244
281
 
245
282
  ## Memory Types and Topic Keys
246
283
 
@@ -276,6 +313,8 @@ Before dispatching subagents in a thoth-mem workflow, verify all of this:
276
313
  `mem_save` delegated observations under the parent session/project, and
277
314
  whether project-scoped read tools (`mem_project_summary`, `mem_project_graph`,
278
315
  `mem_topic_keys`) are allowed.
316
+ - If a root-owned handoff summary exists, the dispatch includes recovery
317
+ instructions but not the summary body.
279
318
  - The dispatch does NOT ask the subagent to save prompts.
280
319
  - The dispatch does NOT ask the subagent to write session summaries.
281
320
  - If the work is SDD-related, the dispatch preserves the shared topic-key rules
@@ -291,7 +330,8 @@ Reject these patterns immediately:
291
330
  - Subagent calls `mem_save_prompt`.
292
331
  - Subagent calls `mem_session_start` or `mem_session_summary`.
293
332
  - Subagent uses thoth-mem without parent `session_id` and `project`.
294
- - Writable subagent calls `mem_context` instead of the bounded 3-layer recall.
333
+ - Subagent uses `mem_context` as a replacement for the bounded 3-layer recall
334
+ path.
295
335
  - Subagent uses project-scoped read tools without explicit permission in the
296
336
  dispatch.
297
337
  - Read-only subagent writes memory.