@namzu/sdk 1.0.0 → 1.1.0

package/src/registry/tool/execute.ts

@@ -19,7 +19,35 @@ export type { ToolExecutionResult }
 // Tokens too generic to identify a tool by name — ignored when matching a
 // batched `search_tools` query so they can't activate the whole catalog
 // (every bridged tool name shares the `clawtool` prefix, for instance).
-const SEARCH_STOP_TOKENS = new Set(['clawtool', 'tool', 'tools', 'mcp', 'the', 'and', 'for', 'use'])
+// Generic CRUD verbs are stopped too: a query like "list deals" must rank
+// by "deals", not token-match every `list_*` tool in the deferred catalog.
+const SEARCH_STOP_TOKENS = new Set([
+	'clawtool',
+	'tool',
+	'tools',
+	'mcp',
+	'the',
+	'and',
+	'for',
+	'use',
+	'list',
+	'read',
+	'create',
+	'update',
+	'get',
+	'find',
+	'delete',
+	'search',
+])
+
+// Weighted-scoring weights mirroring ToolCatalog.searchTools (the richer,
+// otherwise-unused catalog scorer): exact name 12, name substring 8,
+// description 5 — extended here with argument-name indexing (3), following
+// Anthropic's tool-search practice of searching argument names too.
+const SEARCH_WEIGHT_NAME_EXACT = 12
+const SEARCH_WEIGHT_NAME_PARTIAL = 8
+const SEARCH_WEIGHT_DESCRIPTION = 5
+const SEARCH_WEIGHT_ARGUMENT = 3
 
 export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	private availability: Map<string, ToolAvailability> = new Map()
@@ -118,28 +146,58 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 		return this.availability.get(name) ?? 'active'
 	}
 
+	/**
+	 * Ranked lexical search over DEFERRED tools, score-descending (ties broken
+	 * by name) so callers can cap activation at a top-k. Each meaningful query
+	 * term (≥3 chars, not a stop token) is scored against the tool name
+	 * (exact/substring), description, and argument names; only tools with a
+	 * positive score are returned. Description matching is safe here precisely
+	 * because the result is RANKED — the `search_tools` builtin activates only
+	 * the top slice, so a shared word can no longer drag in the whole catalog.
+	 *
+	 * PARKED (phase 5 of the tool-loading plan): an embedding-backed semantic
+	 * upgrade was evaluated and deliberately NOT built — at ≤~35 deferred
+	 * in-house tools with distinct names, weighted lexical scoring sits inside
+	 * the literature's safe zone, and a weak retriever underperforms no
+	 * retriever at all. Revisit only when (a) the deferred catalog grows past
+	 * ~75-100 tools (realistic driver: connector-MCP growth), or (b) telemetry
+	 * shows a search_tools miss-rate above ~10%. Sticky activation is also
+	 * deliberate: activating inserts the schema into the tools array at its
+	 * registry position (a one-time prompt-cache prefix bust); re-defer/TTL
+	 * would churn that prefix repeatedly and is rejected.
+	 */
 	searchDeferred(query: string): ToolDefinition[] {
 		const q = query.toLowerCase().trim()
 		if (q.length === 0) return []
-		// Per-token matching exists only so a batched query naming several tools
-		// at once ("A2aCard PeerRegister PeerList") activates each. Restrict it
-		// to the tool NAME and drop short/generic tokens — matching tokens
-		// against descriptions (or letting a shared word like "clawtool"/"list"
-		// through) would activate the whole catalog and defeat deferral.
-		const tokens = q.split(/\s+/).filter((tok) => tok.length >= 3 && !SEARCH_STOP_TOKENS.has(tok))
-		// A bare generic token ("clawtool") identifies nothing specific — skip the
-		// broad whole-query match for it so it can't activate the whole catalog.
-		const wholeQueryUseful = q.length >= 3 && !SEARCH_STOP_TOKENS.has(q)
-		return this.getByAvailability(['deferred']).filter((t) => {
-			const name = t.name.toLowerCase()
-			// Whole-query match (single-term capability search) against name or
-			// description — the deliberate, narrow behaviour.
-			if (wholeQueryUseful && (name.includes(q) || t.description.toLowerCase().includes(q))) {
-				return true
+		const terms = q.split(/\s+/).filter((tok) => tok.length >= 3 && !SEARCH_STOP_TOKENS.has(tok))
+		if (terms.length === 0) return []
+
+		const scored: Array<{ tool: ToolDefinition; score: number }> = []
+		for (const tool of this.getByAvailability(['deferred'])) {
+			const name = tool.name.toLowerCase()
+			const description = tool.description.toLowerCase()
+			const argumentNames = listArgumentNames(tool)
+			let score = 0
+			for (const term of terms) {
+				if (name === term) {
+					score += SEARCH_WEIGHT_NAME_EXACT
+				} else if (name.includes(term)) {
+					score += SEARCH_WEIGHT_NAME_PARTIAL
+				}
+				if (description.includes(term)) {
+					score += SEARCH_WEIGHT_DESCRIPTION
+				}
+				if (argumentNames.some((arg) => arg.includes(term))) {
+					score += SEARCH_WEIGHT_ARGUMENT
+				}
 			}
-			// Batched multi-name query: any meaningful token, name only.
-			return tokens.some((tok) => name.includes(tok))
-		})
+			if (score > 0) {
+				scored.push({ tool, score })
+			}
+		}
+
+		scored.sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name))
+		return scored.map((entry) => entry.tool)
 	}
 
 	assignTiers(mapping: Record<string, string>): void {
@@ -176,12 +234,24 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 </tool_runtime_contract>`
 
 		if (active.length > 0) {
-			const entries = active.map((t) => `- ${t.name}: ${t.description}`).join('\n')
+			// Name-only: every active tool's full description + JSON schema
+			// already rides the runtime tools parameter on each request —
+			// repeating descriptions here double-bills the same tokens.
+			const entries = active.map((t) => `- ${t.name}`).join('\n')
 			parts.push(`<available_tools>\n${entries}\n</available_tools>`)
 		}
 
 		if (deferred.length > 0) {
-			const entries = deferred.map((t) => `- ${t.name}`).join('\n')
+			// Name + one-line hint: deferred schemas stay off the wire, so the
+			// hint is the model's only signal of what a deferred tool does. A
+			// bare name list caused a real discovery failure in production
+			// (the agent never found read_document behind search_tools).
+			const entries = deferred
+				.map((t) => {
+					const hint = toolDiscoveryHint(t.description)
+					return hint.length > 0 ? `- ${t.name}: ${hint}` : `- ${t.name}`
+				})
+				.join('\n')
 			const deferredIntro =
 				this.has('search_tools') && this.getAvailability('search_tools') === 'active'
 					? 'Use search_tools to load these before use:'
@@ -372,6 +442,39 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 	}
 }
 
+/**
+ * One-line discoverability hint for a deferred tool: the first sentence of
+ * its description, capped at ~100 chars. Used for the `<deferred_tools>`
+ * prompt listing and for `search_tools` near-miss suggestions, where the
+ * full description would re-import the token weight deferral avoids.
+ */
+export function toolDiscoveryHint(description: string, maxLength = 100): string {
+	const normalized = description.trim().replace(/\s+/g, ' ')
+	if (normalized.length === 0) return ''
+	const sentenceMatch = normalized.match(/^.*?[.!?](?=\s|$)/)
+	const sentence = sentenceMatch ? sentenceMatch[0] : normalized
+	if (sentence.length <= maxLength) return sentence
+	return `${sentence.slice(0, maxLength - 1).trimEnd()}…`
+}
+
+/**
+ * Lower-cased argument (property) names of a tool's input schema, used by
+ * `searchDeferred` ranking. Walks the JSON-Schema rendering (already a
+ * registration dependency) instead of Zod internals; opaque schemas simply
+ * contribute no argument matches.
+ */
+function listArgumentNames(tool: ToolDefinition): string[] {
+	try {
+		const json = zodToJsonSchema(tool.inputSchema, {
+			target: 'jsonSchema7',
+			$refStrategy: 'none',
+		}) as { properties?: Record<string, unknown> }
+		return Object.keys(json.properties ?? {}).map((key) => key.toLowerCase())
+	} catch {
+		return []
+	}
+}
+
 /**
  * Build a one-sentence "Required: <field>: <type>, <field>: <type>"
  * hint from a Zod schema, used to enrich tool-input validation

package/src/registry/toolset/catalog.test.ts

@@ -81,6 +81,74 @@ describe('ToolCatalog', () => {
 		expect(catalog.toLLMTools().map((t) => t.function.name)).toEqual(['bash'])
 	})
 
+	it('scores and reports the matched facets: partial name, source text, toolset text', () => {
+		const catalog = new ToolCatalog()
+		catalog.registerSource({
+			id: 'host',
+			kind: 'host_tool',
+			name: 'GitHub',
+			description: 'repository automation',
+		})
+		catalog.registerToolset({
+			id: 'issues',
+			sourceId: 'host',
+			name: 'Issue toolset',
+			defaultPolicy: { enabled: true, loading: 'eager' },
+		})
+		catalog.registerTool({
+			name: 'create_issue',
+			description: 'open a ticket',
+			sourceId: 'host',
+			toolsetId: 'issues',
+			policy: { enabled: true, loading: 'eager' },
+		})
+
+		// 'issue' hits the tool NAME (create_issue, partial) AND the TOOLSET name.
+		const byIssue = catalog.searchTools('issue')
+		expect(byIssue).toHaveLength(1)
+		expect([...(byIssue[0]?.matched ?? [])].sort()).toEqual(['name', 'toolset'])
+
+		// 'github' hits only the SOURCE text.
+		const bySource = catalog.searchTools('github')
+		expect(bySource[0]?.matched).toEqual(['source'])
+
+		// An exact name match outscores a partial one.
+		const exact = catalog.searchTools('create_issue')
+		expect(exact[0]?.matched).toContain('name')
+		expect(exact[0]?.score ?? 0).toBeGreaterThan(byIssue[0]?.score ?? 0)
+	})
+
+	it('adds the preferred boost so a preferred tool outranks an equal match', () => {
+		const catalog = new ToolCatalog()
+		catalog.registerSource({ id: 'host', kind: 'host_tool', name: 'Host' })
+		catalog.registerToolset({
+			id: 'ts',
+			sourceId: 'host',
+			name: 'Tools',
+			defaultPolicy: { enabled: true, loading: 'eager' },
+		})
+		catalog.registerTool({
+			name: 'search_plain',
+			description: 'search things',
+			sourceId: 'host',
+			toolsetId: 'ts',
+			policy: { enabled: true, loading: 'eager' },
+		})
+		catalog.registerTool({
+			name: 'search_pref',
+			description: 'search things',
+			sourceId: 'host',
+			toolsetId: 'ts',
+			policy: { enabled: true, loading: 'eager', preferred: true },
+		})
+
+		const results = catalog.searchTools('search')
+		expect(results.map((r) => r.tool.name)).toEqual(['search_pref', 'search_plain'])
+		const pref = results.find((r) => r.tool.name === 'search_pref')?.score ?? 0
+		const plain = results.find((r) => r.tool.name === 'search_plain')?.score ?? 0
+		expect(pref - plain).toBe(1)
+	})
+
 	it('preserves registry availability as catalog loading policy', () => {
 		const registry = new ToolRegistry()
 		registry.register(makeTool('read_file'))

package/src/runtime/query/__tests__/deferred-tools.test.ts

@@ -159,10 +159,12 @@ describe('query deferred tool discovery', () => {
 	it('does not let search_tools reveal or activate deferred tools outside allowedTools', async () => {
 		const tools = new ToolRegistry()
 		registerDeferredDocumentTool(tools)
-		registerDeferredDocumentTool(tools, 'dangerous_delete_document')
+		registerDeferredDocumentTool(tools, 'dangerous_purge_document')
 
+		// 'dangerous' matches only the out-of-allowlist tool ('delete'-style
+		// CRUD verbs are stop tokens and never match anything by themselves).
 		const result = await SearchToolsTool.execute(
-			{ query: 'delete' },
+			{ query: 'dangerous' },
 			{
 				runId: 'run_deferred_allowed_tools' as RunId,
 				workingDirectory: '/tmp',
@@ -175,9 +177,54 @@ describe('query deferred tool discovery', () => {
 		)
 
 		expect(result.success).toBe(true)
-		expect(result.output).toContain('No deferred tools matching "delete"')
-		expect(result.output).not.toContain('dangerous_delete_document')
+		expect(result.output).toContain('No deferred tools matching "dangerous"')
+		expect(result.output).not.toContain('dangerous_purge_document')
 		expect(tools.getAvailability('generate_document')).toBe('deferred')
-		expect(tools.getAvailability('dangerous_delete_document')).toBe('deferred')
+		expect(tools.getAvailability('dangerous_purge_document')).toBe('deferred')
+	})
+
+	it('activates only the top-5 ranked matches and reports near-misses without activating', async () => {
+		const tools = new ToolRegistry()
+		// Eight deferred tools that all match "invoice" equally by name; the
+		// alphabetical tie-break makes the top-5 cut deterministic.
+		const names = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'].map((s) => `invoice_${s}`)
+		for (const name of names) {
+			tools.register(
+				{
+					name,
+					description: `Billing helper ${name.slice(-1)}.`,
+					inputSchema: z.object({ id: z.string() }),
+					execute: async () => ({ success: true, output: 'ok' }),
+				},
+				'deferred',
+			)
+		}
+
+		const result = await SearchToolsTool.execute(
+			{ query: 'invoice' },
+			{
+				runId: 'run_deferred_top_k' as RunId,
+				workingDirectory: '/tmp',
+				abortSignal: new AbortController().signal,
+				env: {},
+				log: () => undefined,
+				toolRegistry: tools,
+			},
+		)
+
+		expect(result.success).toBe(true)
+		expect(result.output).toContain('Activated 5 tool(s)')
+		expect(result.output).toContain('NOT loaded')
+		expect(result.data).toMatchObject({
+			activated: ['invoice_a', 'invoice_b', 'invoice_c', 'invoice_d', 'invoice_e'],
+			count: 5,
+			nearMisses: ['invoice_f', 'invoice_g', 'invoice_h'],
+		})
+		for (const name of ['invoice_a', 'invoice_b', 'invoice_c', 'invoice_d', 'invoice_e']) {
+			expect(tools.getAvailability(name)).toBe('active')
+		}
+		for (const name of ['invoice_f', 'invoice_g', 'invoice_h']) {
+			expect(tools.getAvailability(name)).toBe('deferred')
+		}
 	})
 })

package/src/runtime/query/__tests__/long-document-flow.test.ts

@@ -0,0 +1,180 @@
+import { readFile, rm } from 'node:fs/promises'
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import { EditTool, WriteFileTool } from '../../../tools/builtins/index.js'
+import type { SessionId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { LLMProvider, StreamChunk } from '../../../types/provider/index.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { drainQuery } from '../index.js'
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+interface ToolStep {
+	readonly name: string
+	readonly input: Record<string, unknown>
+}
+
+class ScriptedLongDocumentProvider implements LLMProvider {
+	readonly id = 'scripted-long-document'
+	readonly name = 'Scripted Long Document Provider'
+	calls = 0
+
+	constructor(private readonly steps: readonly ToolStep[]) {}
+
+	async *chatStream(): AsyncIterable<StreamChunk> {
+		const step = this.steps[this.calls]
+		this.calls += 1
+
+		if (!step) {
+			yield {
+				id: 'msg_done',
+				delta: { content: 'Long document created and verified.' },
+				finishReason: 'stop',
+				usage: ZERO_USAGE,
+			}
+			return
+		}
+
+		yield {
+			id: `msg_${this.calls}`,
+			delta: {
+				toolCalls: [
+					{
+						index: 0,
+						id: `toolu_${this.calls}`,
+						type: 'function',
+						function: { name: step.name },
+					},
+				],
+			},
+		}
+		yield {
+			id: `msg_${this.calls}`,
+			delta: {
+				toolCalls: [
+					{
+						index: 0,
+						id: `toolu_${this.calls}`,
+						function: { arguments: JSON.stringify(step.input) },
+					},
+				],
+			},
+		}
+		yield {
+			id: `msg_${this.calls}`,
+			delta: {},
+			finishReason: 'tool_calls',
+			usage: ZERO_USAGE,
+		}
+	}
+}
+
+describe('query long-document tool flow', () => {
+	const workdirs: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
+		workdirs.length = 0
+	})
+
+	it('executes the canonical write skeleton plus bounded edit chunks flow end to end', async () => {
+		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-query-long-doc-'))
+		workdirs.push(workingDirectory)
+
+		const chunks = Array.from({ length: 4 }, (_, sectionIndex) => {
+			const lines = Array.from({ length: 40 }, (_, lineIndex) => {
+				return `Section ${sectionIndex + 1}.${lineIndex + 1}: this content is intentionally long enough to require repeated bounded edit calls.`
+			})
+			const chunk = [`## Section ${sectionIndex + 1}`, ...lines, ''].join('\n')
+			expect(chunk.length).toBeLessThan(12_000)
+			return chunk
+		})
+
+		const provider = new ScriptedLongDocumentProvider([
+			{
+				name: 'write',
+				input: {
+					path: 'outputs/long-document-flow.md',
+					content: '# Long document flow\n\n{{BODY}}\n',
+				},
+			},
+			{
+				name: 'edit',
+				input: {
+					path: 'outputs/long-document-flow.md',
+					oldStr: '{{BODY}}',
+					newStr: chunks[0],
+					replace_all: false,
+				},
+			},
+			...chunks.slice(1).map((chunk) => ({
+				name: 'edit',
+				input: {
+					path: 'outputs/long-document-flow.md',
+					insertLine: 'end',
+					newStr: chunk,
+					replace_all: false,
+				},
+			})),
+		])
+		const tools = new ToolRegistry()
+		tools.register(WriteFileTool)
+		tools.register(EditTool)
+		const events: RunEvent[] = []
+
+		const run = await drainQuery(
+			{
+				provider,
+				tools,
+				runConfig: {
+					model: 'mock-model',
+					timeoutMs: 5_000,
+					tokenBudget: 100_000,
+					maxIterations: 8,
+					maxResponseTokens: 256,
+				},
+				agentId: 'agent_long_doc',
+				agentName: 'Long Document Agent',
+				messages: [createUserMessage('create a long document')],
+				workingDirectory,
+				sessionId: 'ses_long_document_flow' as SessionId,
+				threadId: 'thd_long_document_flow' as ThreadId,
+				projectId: 'prj_long_document_flow' as ProjectId,
+				tenantId: 'tnt_long_document_flow' as TenantId,
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		const final = await readFile(join(workingDirectory, 'outputs/long-document-flow.md'), 'utf-8')
+		const executingTools = events
+			.filter(
+				(event): event is Extract<RunEvent, { type: 'tool_executing' }> =>
+					event.type === 'tool_executing',
+			)
+			.map((event) => event.toolName)
+
+		expect(run.status).toBe('completed')
+		expect(run.result).toBe('Long document created and verified.')
+		expect(provider.calls).toBe(6)
+		expect(executingTools).toEqual(['write', 'edit', 'edit', 'edit', 'edit'])
+		expect(final).not.toContain('{{BODY}}')
+		expect(final.split('\n').length).toBeGreaterThan(160)
+		expect(final).toContain('## Section 1')
+		expect(final).toContain('## Section 4')
+		expect(final).toContain('Section 4.40')
+	})
+})

package/src/runtime/query/__tests__/prompt.test.ts

@@ -43,18 +43,21 @@ describe('PromptBuilder runtime context', () => {
 			skills: [
 				{
 					metadata: {
-						name: 'project-documents',
-						description: 'Draft and edit project documents from grounded inputs.',
+						name: 'delivery-briefing',
+						description: 'Draft and edit delivery briefings from grounded inputs.',
 					},
-					dirPath: '/repo/.agents/skills/project-documents',
+					dirPath: '/repo/.agents/skills/delivery-briefing',
 				},
 			],
 		}).build('full', '/tmp/work')
 
 		expect(prompt).toContain('You are a project assistant.')
 		expect(prompt).toContain('## Available Skills')
-		expect(prompt).toContain('project-documents')
-		expect(prompt).toContain('Draft and edit project documents')
+		expect(prompt).toContain('<available_skills>')
+		expect(prompt).toContain('delivery-briefing')
+		expect(prompt).toContain('Draft and edit delivery briefings')
+		expect(prompt).toContain('<location>/repo/.agents/skills/delivery-briefing/SKILL.md</location>')
+		expect(prompt).toContain('The following block is a manifest')
 		expect(prompt).not.toContain('## Loaded Skills')
 	})
 
@@ -65,22 +68,23 @@ describe('PromptBuilder runtime context', () => {
 			skills: [
 				{
 					metadata: {
-						name: 'long-form-files',
-						description: 'Create long files with bounded edit chunks.',
+						name: 'structured-file-authoring',
+						description: 'Create structured files with bounded edit chunks.',
 						license: 'MIT',
 						compatibility: 'Requires file tools',
 						allowedTools: 'read write edit',
 					},
 					body: 'Use skeleton-first writes and bounded edit chunks.',
-					dirPath: '/repo/.agents/skills/long-form-files',
+					dirPath: '/repo/.agents/skills/structured-file-authoring',
 				},
 			],
 		}).build('full', '/tmp/work')
 
 		expect(prompt).toContain('## Available Skills')
-		expect(prompt).toContain('license: MIT')
-		expect(prompt).toContain('compatibility: Requires file tools')
-		expect(prompt).toContain('allowed-tools: read write edit')
+		expect(prompt).toContain('<license>MIT</license>')
+		expect(prompt).toContain('<compatibility>Requires file tools</compatibility>')
+		expect(prompt).toContain('<allowed_tools>read write edit</allowed_tools>')
+		expect(prompt).toContain('read the SKILL.md at its <location> before writing code')
 		expect(prompt).toContain('## Loaded Skills')
 		expect(prompt).toContain('Use skeleton-first writes')
 	})

package/src/runtime/query/index.ts

@@ -16,6 +16,7 @@ import { buildTaskTools } from '../../tools/task/index.js'
 import type { AdvisoryConfig } from '../../types/advisory/index.js'
 import type { AgentRuntimeContext, RuntimeToolOverrides } from '../../types/agent/base.js'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
+import type { WorkingMemoryProvider } from '../../types/agent/working-memory.js'
 import {
 	type CheckpointId,
 	type ResumeHandler,
@@ -42,6 +43,8 @@ import { RunContextFactory } from './context.js'
 import { EventTranslator } from './events.js'
 import { GuardCoordinator } from './guard.js'
 import { IterationOrchestrator } from './iteration/index.js'
+import { isCompactionMessage } from './iteration/phases/compaction.js'
+import { isWorkingMemoryMessage } from './iteration/phases/working-memory.js'
 import { applyLifecycleHookResults } from './plugin-hooks.js'
 import { PromptBuilder } from './prompt.js'
 import type { PromptSegments } from './prompt.js'
@@ -127,6 +130,15 @@ export interface QueryParams {
 
 	compactionConfig?: CompactionConfig
 
+	/**
+	 * Optional neutral working-memory seam. When set, the iteration loop
+	 * re-renders the provider's string into a single pinned leading system
+	 * message every turn (the primacy-edge, compaction-preserved slot).
+	 * Absent ⇒ `refreshWorkingMemory` early-returns and the run path is
+	 * byte-identical.
+	 */
+	workingMemoryProvider?: WorkingMemoryProvider
+
 	agentBus?: import('../../bus/index.js').AgentBus
 
 	verificationGate?: VerificationGateConfig
@@ -187,7 +199,15 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		})
 
 		if (decision.action === 'approve_plan') {
-			return { approved: true }
+			// Optional approve-with-edits channel: the host may attach
+			// feedback to an approval. `PlanApprovalResponse.feedback`
+			// already exists on the type; threading it through lets the
+			// coordinator's approve_plan tool surface the user's edits in
+			// the same tool_result that unblocks the park. Bare approvals
+			// stay byte-identical (`{ approved: true }`).
+			return decision.feedback
+				? { approved: true, feedback: decision.feedback }
+				: { approved: true }
 		}
 		if (decision.action === 'reject_plan') {
 			return { approved: false, feedback: decision.feedback }
@@ -322,6 +342,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			advisoryCtx,
 			compactionConfig: params.compactionConfig,
 			workingStateManager,
+			workingMemoryProvider: params.workingMemoryProvider,
 			agentBus: params.agentBus,
 			verificationGate: verificationGate,
 			pluginManager: params.pluginManager,
@@ -408,7 +429,18 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 
 				pushSystemMessages()
 				for (const msg of checkpoint.messages) {
-					if (msg.role === 'system') continue
+					if (msg.role === 'system') {
+						// Re-push the FRESH static/dynamic floor (done above) but PRESERVE
+						// the two system messages that carry irreplaceable run state: the
+						// `[COMPACTED CONTEXT]` summary is the only surviving record of the
+						// older history a compaction pass deleted, and the working-memory
+						// slot pins the produced-artifact ledger. Dropping every system
+						// message on restore silently lost both on resume.
+						if (isCompactionMessage(msg.content) || isWorkingMemoryMessage(msg.content)) {
+							ctx.runMgr.pushMessage(msg)
+						}
+						continue
+					}
 					ctx.runMgr.pushMessage(msg)
 				}
 			} else if (params.continuationMode) {