akm-opencode 0.8.0-rc1 → 0.8.0

package/index.ts

@@ -1,18 +1,50 @@
 import { type Plugin, tool } from "@opencode-ai/plugin"
 import { execFileSync, execSync, spawn } from "node:child_process"
-import { readFileSync } from "node:fs"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import os from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
-import { classifyFeedbackSignal, shouldSubmitAutomaticFeedback } from "../shared/feedback-signals"
-import { appendCandidates, extractCandidatesFromText, getCandidateLogPath, readCandidates, updateCandidateStatus } from "../shared/memory-candidates"
-import { appendMemoryEvent, getEventLogPath, readJsonl, type AkmMemoryEvent } from "../shared/memory-events"
-import { shouldRecall } from "../shared/recall-policy"
-import { redactObject, redactSecrets } from "../shared/redaction"
+import { classifyFeedbackSignal, shouldSubmitAutomaticFeedback } from "./shared/feedback-signals"
+import { appendCandidates, extractCandidatesFromText, getCandidateLogPath, readCandidates, updateCandidateStatus } from "./shared/memory-candidates"
+import { appendMemoryEvent, getEventLogPath, readJsonl, type AkmMemoryEvent } from "./shared/memory-events"
+import { shouldRecall } from "./shared/recall-policy"
+import { redactObject, redactSecrets } from "./shared/redaction"
+import { extractAkmRefsFromString } from "./shared/ref-extraction"
+
+// Quote-aware shell tokenizer. Splits on whitespace but respects single,
+// double, and backtick quotes. Used by renderCommandTemplate() to fill
+// `$1`/`$2` positional placeholders from raw `$ARGUMENTS` strings. Was
+// previously co-located with the risky-command assessor in
+// shared/risky-command.ts; inlined here when that gate was removed.
+function splitArguments(raw: string): string[] {
+  if (!raw.trim()) return []
+  const args: string[] = []
+  const re = /"([^"]*)"|'([^']*)'|`([^`]*)`|(\S+)/g
+  let match: RegExpExecArray | null
+  while ((match = re.exec(raw)) !== null) {
+    args.push(match[1] ?? match[2] ?? match[3] ?? match[4] ?? "")
+  }
+  return args
+}
 
 let resolvedAkmCommand = "akm"
-const autoInstallPackageRef = process.env.AKM_PACKAGE_REF ?? "akm-cli@latest"
+
+// Test-only: reset the module-level resolved-CLI cache so each test resolves
+// the akm command fresh under its own sandboxed env (HOME / AKM_OPENCODE_*).
+// Without this, the first test to resolve pins `resolvedAkmCommand` for the
+// rest of the process (resolveAkmCommand short-circuits on a still-valid
+// cached command), making later resolution tests order-dependent.
+export function __resetResolvedAkmForTests(): void {
+  resolvedAkmCommand = "akm"
+}
+
 const moduleDir = path.dirname(fileURLToPath(import.meta.url))
 const SEMVER_PATTERN = /\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\b/
+// Note: satisfiesAkmVersionRange() implements a custom matcher that accepts
+// any 0.8.x release including prereleases (0.8.0-rc.5, 0.8.0-beta.2, etc.).
+// Strict semver `^0.8.0` would NOT match prereleases, so the constant string
+// is widened to honestly reflect what the matcher accepts.
+const AKM_REQUIRED_VERSION_RANGE = "^0.8.0 || ^0.8.0-rc0"
 
 const AKM_AUTO_FEEDBACK = (process.env.AKM_AUTO_FEEDBACK ?? "1") !== "0"
 const AKM_AUTO_MEMORY = (process.env.AKM_AUTO_MEMORY ?? "1") !== "0"
@@ -42,10 +74,10 @@ const sessionWorkflow = new Map<string, string>()
 const sessionCuratorReport = new Map<string, string>()
 const sessionContextEpoch = new Map<string, number>()
 const sessionContextInjectedEpoch = new Map<string, number>()
+const sessionCuratedFile = new Map<string, string>()
 const sessionCuratedVersion = new Map<string, number>()
 const sessionCuratedInjectedVersion = new Map<string, number>()
 const sessionRecallAudit = new Map<string, { shouldRecall: boolean; reason: string; query: string; injectedRefs: string[]; injectedChars: number; warnings: string[] }>()
-type ParsedSemver = { core: [number, number, number]; prerelease: Array<string | number> | null }
 type SessionBufferEntry = {
   timestamp: string
   kind: "memory-intent" | "tool-ref"
@@ -66,22 +98,22 @@ let agentSetupPromise: Promise<boolean> | null = null
 // Asset-ref grammar matching the stash skill: [origin//]type:name.
 // We validate normalized tokens individually instead of running a global regex
 // over arbitrary tool output to keep extraction predictable and ReDoS-safe.
-const AKM_REF_PATTERN = /^(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|script|workflow|vault|wiki|lesson):[A-Za-z0-9._/\-]+$/
+const AKM_REF_PATTERN = /^(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|script|workflow|task|env|secret|wiki|lesson):[A-Za-z0-9._/\-]+$/
 const PROPOSED_QUALITY_WARNING = "Do not treat proposed assets as curated until accepted."
 const AKM_WORKFLOW_INSTRUCTION = [
-  "# AKM workflow (v0.7.0)",
+  "# AKM workflow (v0.8.0)",
   "",
   "Use AKM as a reusable knowledge and workflow stash.",
   "",
   "Before writing from scratch:",
-  "1. Use `akm_search` or `akm_curate`.",
+  "1. Use `akm_curate` with a query that includes the current project name/domain (primary discovery). Fall back to `akm_search` only when you already know an asset exists and need its exact ref.",
   "2. Use `akm_show <ref>` before relying on an asset.",
   "3. Record `akm_feedback` after the result is known.",
-  "4. Use the dedicated v0.7.0 tools for the proposal flow: `akm_proposal` (list/show/diff/accept/reject), `akm_reflect`, `akm_propose`, and `akm_distill`. Fall back to `akm_help` for any verb without a dedicated tool.",
-  "5. Treat `lesson:*` as first-class durable learning assets — they are produced by `akm_distill <ref>` as proposals and accepted via `akm_proposal action=accept`.",
+  "4. Use the dedicated v0.8.0 tools for the proposal flow: `akm_proposal` (list/show/diff/accept/reject/drain), `akm_improve`, and `akm_propose`. Fall back to `akm_help` for any verb without a dedicated tool.",
+  "5. Treat `lesson:*` as first-class durable learning assets — they are produced through `akm_improve` and accepted via `akm_proposal action=accept`.",
   "6. Use `akm_init` when you need to create the working stash or persist `stashDir`. Do not use `akm setup` from an agent; it is interactive and human-facing.",
   `7. ${PROPOSED_QUALITY_WARNING}`,
-  "8. Never accept or reject proposals, push saves, remove sources, or access vault values without explicit user approval.",
+  "8. Never accept or reject proposals, push saves, remove sources, or access env values / secret material without explicit user approval.",
 ].join("\n")
 
 function readPackageVersion(): string {
@@ -127,14 +159,14 @@ Inputs you should inspect:
 Signals to act on:
 - Hot refs: assets repeatedly appearing in positive tool outcomes. Call akm_feedback <ref> positive --note "curator: consistently useful" to reinforce.
 - Cold refs: assets tied to failures or user complaints. Record akm_feedback <ref> negative --note "<excerpt>" and open the asset for review.
-- Lesson candidates: repeated memories or failures that should become a proposed lesson. Use akm_help topic="distill" before raw CLI distill commands.
+- Lesson candidates: repeated memories or failures that should become a proposed lesson. Use akm_improve or akm_help topic="improve" before raw CLI improvement commands.
 - Missing coverage: recurring user prompts with no matching asset. Draft a new skill, command, knowledge doc, wiki page, or workflow in the working stash and reindex via the akm CLI (see akm_help topic="reindex").
 - Pending proposals: list or diff them via akm_help topic="proposal" and recommend accept, reject, or revise. Never accept or reject without explicit user approval.
 - Duplicates / drift: near-identical descriptions or overlapping responsibilities. Propose a consolidation.
 - Stale memories: session summaries that never get recalled. Propose removal (see akm_help topic="remove") once distilled into a durable knowledge doc or wiki page.
 - Wiki hygiene: for each wiki returned by akm_wiki list, run akm_wiki lint <name> and report orphans, broken xrefs, uncited raws, and stale indexes as fix candidates.
 - Stuck workflows: run akm_workflow list --active and surface any runs in blocked or failed state with their step ids. Propose whether to resume or escalate.
-- Never touch vaults: do not call akm_vault show or load unless the user explicitly asks. Vault values must never appear in reports.
+- Never touch env or secret values: do not call akm_env run or akm_secret path unless the user explicitly asks. Env values and secret material must never appear in reports.
 
 Rules of engagement:
 - Never apply destructive changes without explicit user approval.
@@ -152,7 +184,7 @@ Output shape: end every run with a markdown report that has these sections:
 - <ref> — failure signal — proposed fix
 
 ## Lesson candidates
-- <theme> — evidence refs — distill or reflect command to run
+- <theme> — evidence refs — improve or propose command to run
 
 ## Coverage gaps
 - <theme> — proposed asset (type, name, one-line description)
@@ -210,6 +242,9 @@ type CliLogMeta = {
   toolName: string
   directory?: string
   sessionID?: string
+  agent?: string
+  userID?: string
+  channel?: string
 }
 
 type SessionPromptBody = {
@@ -220,6 +255,12 @@ type SessionPromptBody = {
   tools?: Record<string, boolean>
 }
 
+type DispatchTarget = {
+  agent: string
+  model?: { providerID: string; modelID: string }
+  requested: string
+}
+
 function formatCliError(error: unknown): string {
   if (error && typeof error === "object" && "code" in error && (error as { code?: unknown }).code === "ENOENT") {
     return "The 'akm' CLI was not found on PATH. Install it first from https://github.com/itlackey/akm."
@@ -234,7 +275,78 @@ function needsAgentSetup(message: string): boolean {
 function addAgentSetupGuidance(message: string): string {
   if (!needsAgentSetup(message)) return message
   if (/\bakm init\b|\bakm_init\b|\bakm setup\b/i.test(message)) return message
-  return `${message}. Agents should not run akm setup because it is interactive. The plugin should set agent.default to the current platform when it is missing; if interactive configuration is still needed, ask the user to run akm setup manually. Use akm_init for agent-safe stash initialization.`
+  return `${message}. Agents should not run akm setup because it is interactive. The plugin should set the AKM default agent to the current platform when it is missing; if interactive configuration is still needed, ask the user to run akm setup manually. Use akm_init for agent-safe stash initialization.`
+}
+
+function getAkmConfigPath(): string {
+  const configHome = process.env.XDG_CONFIG_HOME ?? path.join(process.env.HOME ?? ".", ".config")
+  return path.join(configHome, "akm", "config.json")
+}
+
+function readAkmConfig(): Record<string, unknown> {
+  try {
+    const raw = readFileSync(getAkmConfigPath(), "utf8")
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === "object" ? parsed as Record<string, unknown> : {}
+  } catch {
+    return {}
+  }
+}
+
+function readConfiguredAgentDefault(): string {
+  const config = readAkmConfig()
+  // 0.8.0 canonical shape: defaults.agent. Fall back to the legacy agent.default
+  // slot when running against a pre-0.8 config that has not been migrated yet.
+  const defaults = config.defaults
+  if (defaults && typeof defaults === "object") {
+    const value = (defaults as Record<string, unknown>).agent
+    if (typeof value === "string" && value.trim()) return value.trim()
+  }
+  const agent = config.agent
+  if (agent && typeof agent === "object") {
+    const value = (agent as Record<string, unknown>).default
+    if (typeof value === "string" && value.trim()) return value.trim()
+  }
+  return ""
+}
+
+function writeConfiguredAgentDefault(platform: string): boolean {
+  if (!platform.trim()) return false
+  // #463: route through `akm config set` so akm's schema-walker / validator
+  // is the single source of truth for the on-disk shape. Direct JSON writes
+  // here would bypass strict-mode validation and the 5-backup ring buffer,
+  // and historically clobbered nearby keys when the legacy `agent.default`
+  // slot triggered an auto-migration.
+  const command = resolveAkmCommand()
+  if (typeof command === "object" && "ok" in command) return false
+  try {
+    // #463: --silent --layer user (akm-cli 0.8.0+) pins writes to the user
+    // config layer regardless of merged-read scope and silences hook-driven
+    // CLI output. Without them, hook writes could race with a project-layer
+    // override or pollute the parent process stdout.
+    execFileSync(
+      command.command,
+      [
+        ...command.argsPrefix,
+        "config",
+        "set",
+        "--silent",
+        "--layer",
+        "user",
+        `profiles.agent.${platform}`,
+        JSON.stringify({ platform }),
+      ],
+      { stdio: "ignore" },
+    )
+    execFileSync(
+      command.command,
+      [...command.argsPrefix, "config", "set", "--silent", "--layer", "user", "defaults.agent", platform],
+      { stdio: "ignore" },
+    )
+    return true
+  } catch {
+    return false
+  }
 }
 
 async function ensurePlatformAgentDefault(
@@ -242,7 +354,7 @@ async function ensurePlatformAgentDefault(
   meta: { directory?: string; sessionID?: string; trigger: string; platform: string },
 ): Promise<boolean> {
   const command = resolveAkmCommand()
-  if (typeof command !== "string") {
+  if (typeof command === "object" && "ok" in command) {
     await writePluginLog(client, "warn", "AKM agent default check skipped", {
       subsystem: "akm",
       trigger: meta.trigger,
@@ -254,26 +366,12 @@ async function ensurePlatformAgentDefault(
   }
 
   try {
-    const currentRaw = execFileSync(command, ["config", "get", "agent.default", "--format", "json"], {
-      encoding: "utf8",
-      timeout: 30_000,
-    })
-    const parsed = safeJsonParse<unknown>(currentRaw)
-    const current = typeof parsed === "string"
-      ? parsed.trim()
-      : parsed && typeof parsed === "object"
-        ? typeof (parsed as Record<string, unknown>).value === "string"
-          ? ((parsed as Record<string, unknown>).value as string).trim()
-          : typeof (parsed as Record<string, unknown>)["agent.default"] === "string"
-            ? ((parsed as Record<string, unknown>)["agent.default"] as string).trim()
-            : ""
-        : ""
+    const current = readConfiguredAgentDefault()
     if (current) return true
 
-    execFileSync(command, ["config", "set", "agent.default", meta.platform, "--format", "json"], {
-      encoding: "utf8",
-      timeout: 30_000,
-    })
+    if (!writeConfiguredAgentDefault(meta.platform)) {
+      throw new Error(`Failed to write ${getAkmConfigPath()}`)
+    }
     await writePluginLog(client, "info", "AKM agent default initialized", {
       subsystem: "akm",
       trigger: meta.trigger,
@@ -364,6 +462,46 @@ function writeStructuredEvent(event: Omit<AkmMemoryEvent, "version" | "timestamp
   })
 }
 
+const CURATED_DIR = path.join(os.tmpdir(), "akm-opencode", "curated")
+mkdirSync(CURATED_DIR, { recursive: true })
+
+function gatherCwdContext(directory: string): string {
+  const parts: string[] = []
+  const indicators: Array<{ file: string; label: string }> = [
+    { file: "package.json", label: "Node" },
+    { file: "Cargo.toml", label: "Rust" },
+    { file: "pyproject.toml", label: "Python" },
+    { file: "go.mod", label: "Go" },
+    { file: "Gemfile", label: "Ruby" },
+    { file: "Makefile", label: "Make" },
+    { file: "Dockerfile", label: "Docker" },
+    { file: "docker-compose.yml", label: "Docker Compose" },
+    { file: ".github/workflows", label: "GitHub Actions" },
+    { file: "composer.json", label: "PHP" },
+  ]
+  for (const indicator of indicators) {
+    try {
+      if (existsSync(path.join(directory, indicator.file))) parts.push(indicator.label)
+    } catch {}
+  }
+  try {
+    const pkgPath = path.join(directory, "package.json")
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"))
+      if (pkg.name) parts.push(pkg.name)
+      if (pkg.description) parts.push(String(pkg.description).slice(0, 120))
+    }
+  } catch {}
+  try {
+    const readme = path.join(directory, "README.md")
+    if (existsSync(readme)) {
+      const firstContent = readFileSync(readme, "utf8").split("\n").find((l) => l.trim() && !l.startsWith("#"))
+      if (firstContent) parts.push(firstContent.trim().slice(0, 100))
+    }
+  } catch {}
+  return parts.join(", ")
+}
+
 async function logHookFailure(
   client: LogCapableClient,
   hook: string,
@@ -406,6 +544,17 @@ function bumpCuratedVersion(sessionID: string) {
   sessionCuratedVersion.set(sessionID, (sessionCuratedVersion.get(sessionID) ?? 0) + 1)
 }
 
+function writeCuratedFile(sessionID: string, content: string): string {
+  const sanitized = sessionID.replace(/[^A-Za-z0-9._-]/g, "_")
+  const filePath = path.join(CURATED_DIR, `${sanitized}.md`)
+  try {
+    writeFileSync(filePath, content)
+    sessionCuratedFile.set(sessionID, filePath)
+  } catch {}
+  return filePath
+}
+
+
 function isAkmRef(value: string): boolean {
   return AKM_REF_PATTERN.test(value)
 }
@@ -423,9 +572,9 @@ function parseMaybeJson(value: string): unknown {
 // stash never wedges the session loop.
 function runCliSyncRaw(args: string[], timeoutMs: number): { ok: true; stdout: string } | { ok: false; error: string } {
   const command = resolveAkmCommand()
-  if (typeof command !== "string") return { ok: false, error: command.error }
+  if (typeof command === "object" && "ok" in command) return { ok: false, error: command.error }
   try {
-    const stdout = execFileSync(command, args, {
+    const stdout = execResolvedAkm(command, args, {
       encoding: "utf8",
       timeout: timeoutMs,
       stdio: ["ignore", "pipe", "pipe"],
@@ -472,6 +621,125 @@ function buildScopedArgs(context: Record<string, unknown> | undefined): string[]
   return args
 }
 
+function getHarnessStatePaths(): { stateDir: string; eventLog: string; candidateLog: string; opencodeLogDir: string } {
+  const stateDir = path.dirname(OPENCODE_EVENT_LOG)
+  return {
+    stateDir,
+    eventLog: OPENCODE_EVENT_LOG,
+    candidateLog: OPENCODE_CANDIDATE_LOG,
+    opencodeLogDir: path.join(process.env.XDG_DATA_HOME ?? path.join(process.env.HOME ?? ".", ".local", "share"), "opencode", "log"),
+  }
+}
+
+function formatPathBullet(label: string, filePath: string): string {
+  return `- ${label}: ${filePath}`
+}
+
+function countByValue(values: string[]): Array<[string, number]> {
+  const counts = new Map<string, number>()
+  for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1)
+  return [...counts.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+}
+
+function uniqueRecent<T>(values: T[], key: (value: T) => string, limit: number): T[] {
+  const selected: T[] = []
+  const seen = new Set<string>()
+  for (let index = values.length - 1; index >= 0 && selected.length < limit; index -= 1) {
+    const value = values[index]
+    const id = key(value)
+    if (!id || seen.has(id)) continue
+    seen.add(id)
+    selected.push(value)
+  }
+  return selected.reverse()
+}
+
+function sessionHasPendingCheckpointEvidence(sessionID: string | undefined): boolean {
+  if (!sessionID) return false
+  return (sessionBuffer.get(sessionID) ?? []).some((entry) => !entry.checkpointed)
+}
+
+async function ensureFreshProposalCheckpoint(
+  client: LogCapableClient,
+  context: { sessionID?: string; directory?: string; agent?: string },
+  reason: string,
+): Promise<string | null> {
+  if (!context.sessionID || !sessionHasPendingCheckpointEvidence(context.sessionID)) return null
+  const ref = captureSessionMemory(context.sessionID, reason, { checkpoint: true })
+  if (!ref) return null
+  await writePluginLog(client, "info", "AKM proposal checkpoint captured", {
+    subsystem: "memory",
+    actor: "system",
+    sessionID: context.sessionID,
+    directory: context.directory,
+    agent: context.agent,
+    reason,
+    ref,
+  })
+  const indexResult = runCliSyncRaw(["index"], AKM_CURATE_TIMEOUT_MS)
+  if (!indexResult.ok) {
+    await writePluginLog(client, "warn", "AKM proposal checkpoint indexing failed", {
+      subsystem: "memory",
+      actor: "system",
+      sessionID: context.sessionID,
+      directory: context.directory,
+      agent: context.agent,
+      reason,
+      ref,
+      error: indexResult.error,
+    })
+  }
+  return ref
+}
+
+function truncateLine(value: string, maxChars = 220): string {
+  return value.length <= maxChars ? value : `${value.slice(0, maxChars - 1)}...`
+}
+
+function formatEvidenceSummary(events: AkmMemoryEvent[], candidates: ReturnType<typeof readCandidates>, entries: SessionBufferEntry[]): string[] {
+  const lines: string[] = []
+  const toolRefs = entries.filter((entry) => entry.kind === "tool-ref" && entry.ref)
+  const touchedRefs = countByValue(toolRefs.map((entry) => entry.ref!))
+  const toolNames = countByValue(toolRefs.map((entry) => entry.toolName ?? "tool"))
+  const statuses = countByValue(toolRefs.map((entry) => entry.status ?? "unknown"))
+  const eventTypes = countByValue(events.map((event) => event.event))
+  const candidateTypes = countByValue(candidates.map((candidate) => candidate.type))
+
+  lines.push("## Evidence aggregates")
+  lines.push(`- buffered observations: ${entries.length}`)
+  if (toolRefs.length > 0) lines.push(`- asset-touch observations: ${toolRefs.length}`)
+  if (touchedRefs.length > 0) lines.push(`- top refs: ${touchedRefs.slice(0, 5).map(([ref, count]) => `${ref} (${count})`).join(", ")}`)
+  if (toolNames.length > 0) lines.push(`- tools involved: ${toolNames.slice(0, 5).map(([name, count]) => `${name} (${count})`).join(", ")}`)
+  if (statuses.length > 0) lines.push(`- statuses: ${statuses.map(([status, count]) => `${status} (${count})`).join(", ")}`)
+  if (eventTypes.length > 0) lines.push(`- event types: ${eventTypes.slice(0, 6).map(([event, count]) => `${event} (${count})`).join(", ")}`)
+  if (candidateTypes.length > 0) lines.push(`- candidate types: ${candidateTypes.map(([type, count]) => `${type} (${count})`).join(", ")}`)
+  lines.push("")
+
+  const notableEvents = uniqueRecent(events, (event) => `${event.timestamp}:${event.event}:${(event.refs ?? []).join(",")}`, 5)
+  if (notableEvents.length > 0) {
+    lines.push("## Notable recent events")
+    for (const event of notableEvents) {
+      const status = event.outcome?.status ?? "unknown"
+      const refs = Array.isArray(event.refs) && event.refs.length > 0 ? ` refs=${event.refs.join(", ")}` : ""
+      const warning = event.outcome?.warnings?.[0] ? ` warning=${truncateLine(event.outcome.warnings[0], 120)}` : ""
+      lines.push(`- ${event.timestamp} ${event.event} (${status})${refs}${warning}`)
+    }
+    lines.push("")
+  }
+
+  const notableCandidates = uniqueRecent(candidates, (candidate) => candidate.id, 5)
+  if (notableCandidates.length > 0) {
+    lines.push("## Candidate highlights")
+    for (const candidate of notableCandidates) {
+      const target = candidate.targetRef ? ` target=${candidate.targetRef}` : ""
+      lines.push(`- [${candidate.status}] ${candidate.type}/${candidate.scope}${target} :: ${truncateLine(candidate.content, 180)}`)
+    }
+    lines.push("")
+  }
+
+  return lines
+}
+
 function runCurate(args: string[]): string | null {
   const result = runCliSyncRaw(args, AKM_CURATE_TIMEOUT_MS)
   if (!result.ok) return null
@@ -495,7 +763,7 @@ async function runCurateForPrompt(client: LogCapableClient, text: string, sessio
   return runCurateLogged(client,
     appendRunScopeArgs(
       [
-        "--detail",
+        "--shape",
         "agent",
         "--format",
         "text",
@@ -511,21 +779,19 @@ async function runCurateForPrompt(client: LogCapableClient, text: string, sessio
   )
 }
 
-async function runCurateForSession(client: LogCapableClient, sessionID: string): Promise<string | null> {
+async function runCurateForSession(client: LogCapableClient, sessionID: string, query?: string): Promise<string | null> {
+  const args = [
+    "--shape",
+    "agent",
+    "--format",
+    "text",
+    "-q",
+    "curate",
+  ]
+  if (query) args.push(query)
+  args.push("--limit", String(AKM_CURATE_LIMIT))
   return runCurateLogged(client,
-    appendRunScopeArgs(
-      [
-        "--detail",
-        "agent",
-        "--format",
-        "text",
-        "-q",
-        "curate",
-        "--limit",
-        String(AKM_CURATE_LIMIT),
-      ],
-      sessionID,
-    ),
+    appendRunScopeArgs(args, sessionID),
     { toolName: "session.start", sessionID, operation: "session-curate" },
   )
 }
@@ -648,11 +914,12 @@ async function getAkmStashDir(client?: LogCapableClient): Promise<string | undef
 
 function warmIndexInBackground(): void {
   const command = resolveAkmCommand()
-  if (typeof command !== "string") return
+  if (typeof command === "object" && "ok" in command) return
   try {
     // Fire and forget — execSync with a timeout would block, so spawn via the
     // shell and detach. Errors here are never surfaced to the session.
-    execSync(`${JSON.stringify(command)} index >/dev/null 2>&1 &`, { timeout: 2_000 })
+    const shellArgs = [command.command, ...command.argsPrefix, "index"].map((part) => JSON.stringify(part)).join(" ")
+    execSync(`${shellArgs} >/dev/null 2>&1 &`, { timeout: 2_000 })
   } catch {
     // Intentionally ignore — warming is best-effort.
   }
@@ -724,9 +991,10 @@ async function getPendingProposalCount(client: LogCapableClient, sessionID?: str
   if (cached && cached.expiresAt > Date.now()) return cached
 
   const command = resolveAkmCommand()
-  if (typeof command !== "string") return { count: 0, unsupported: true }
+  if (typeof command === "object" && "ok" in command) return { count: 0, unsupported: true }
   try {
-    const stdout = execFileSync(command, ["proposal", "list", "--status", "pending", "--format", "json"], {
+    // 0.8.0 canonical proposal-queue listing path: `akm proposal list`.
+    const stdout = execResolvedAkm(command, ["proposal", "list", "--status", "pending", "--format", "json"], {
       encoding: "utf8",
       timeout: AKM_PENDING_PROPOSAL_TIMEOUT_MS,
     })
@@ -763,7 +1031,7 @@ async function recordRetrospectiveFeedback(client: LogCapableClient, sessionID:
   }
 
   const targetRef = recentRefs[recentRefs.length - 1]
-  const raw = await runCli(client, ["feedback", targetRef, "--negative", "--note", text.slice(0, 280)], {
+  const raw = await runCli(client, ["feedback", targetRef, "--negative", "--note", text.slice(0, 280), ...buildScopedArgs({ sessionID })], {
     toolName: "akm_feedback",
     sessionID,
   })
@@ -780,53 +1048,6 @@ async function recordRetrospectiveFeedback(client: LogCapableClient, sessionID:
   retrospectiveState.set(sessionID, { recentRefs })
 }
 
-type RiskyCommandAssessment = {
-  category: string
-  reason: string
-  approval: string
-}
-
-function assessRiskyAkmCommand(command: string): RiskyCommandAssessment | undefined {
-  const args = splitArguments(command)
-  const akmIndex = args.findIndex((arg) => arg === "akm" || arg.endsWith("/akm") || arg.endsWith("\\akm.exe"))
-  if (akmIndex === -1) return undefined
-  const tokens = args.slice(akmIndex + 1)
-  if (tokens[0] === "proposal" && tokens[1] === "accept") {
-    return { category: "proposal-accept", reason: "Proposal acceptance changes curated AKM content.", approval: "Ask the user to approve `akm proposal accept <id>`." }
-  }
-  if (tokens[0] === "proposal" && tokens[1] === "reject") {
-    return { category: "proposal-reject", reason: "Proposal rejection is a durable curation decision.", approval: "Ask the user to approve `akm proposal reject <id> --reason \"...\"`." }
-  }
-  if (tokens[0] === "save" && tokens.includes("--push")) {
-    return { category: "save-push", reason: "Pushing stash changes must be explicitly approved.", approval: "Ask the user to approve `akm save --push`." }
-  }
-  if (tokens[0] === "remove") {
-    return { category: "remove", reason: "Removing AKM sources is destructive.", approval: "Ask the user to approve the exact `akm remove ...` command." }
-  }
-  if (tokens[0] === "vault" && ["show", "load", "set", "unset"].includes(tokens[1] ?? "")) {
-    return { category: `vault-${tokens[1]}`, reason: "Vault access or mutation is sensitive.", approval: `Ask the user to approve the exact \`akm vault ${tokens[1]} ...\` command.` }
-  }
-  if (tokens[0] === "config" && tokens[1] === "set" && (tokens[2]?.startsWith("llm.features.") ?? false)) {
-    return { category: "config-llm-features", reason: "Changing AKM LLM feature flags alters autonomous behavior.", approval: "Ask the user to approve the exact `akm config set llm.features.* ...` command." }
-  }
-  if (tokens[0] === "update" && tokens.includes("--all")) {
-    return { category: "update-all", reason: "Updating all AKM kits changes many assets at once.", approval: "Ask the user to approve `akm update --all`." }
-  }
-  if (tokens[0] === "upgrade") {
-    return { category: "upgrade", reason: "Upgrading the AKM CLI changes the toolchain.", approval: "Ask the user to approve the exact `akm upgrade` command." }
-  }
-  return undefined
-}
-
-function blockedCommandMessage(command: string, assessment: RiskyCommandAssessment): string {
-  return [
-    `Blocked risky AKM command: ${command}`,
-    assessment.reason,
-    assessment.approval,
-    "Retry only after explicit user approval in this conversation.",
-  ].join("\n")
-}
-
 function queueFeedback(
   client: LogCapableClient,
   ref: string,
@@ -840,7 +1061,7 @@ function queueFeedback(
   dedupe?.add(dedupeKey)
 
   const command = resolveAkmCommand()
-  if (typeof command !== "string") {
+  if (typeof command === "object" && "ok" in command) {
     void writePluginLog(client, "warn", "AKM auto-feedback skipped", {
       subsystem: "feedback",
       toolName: meta.toolName,
@@ -855,8 +1076,9 @@ function queueFeedback(
 
   try {
     const child = spawn(
-      command,
+      command.command,
       [
+        ...command.argsPrefix,
         "--format",
         "json",
         "-q",
@@ -865,6 +1087,13 @@ function queueFeedback(
         sentiment === "positive" ? "--positive" : "--negative",
         "--note",
         note,
+        ...buildScopedArgs({
+          sessionID: meta.sessionID,
+          directory: meta.directory,
+          agent: meta.agent,
+          userID: meta.userID,
+          channel: meta.channel,
+        }),
       ],
       {
         detached: true,
@@ -913,11 +1142,11 @@ function queueFeedback(
   }
 }
 
-function rememberTextAsMemory(name: string, body: string): string | null {
+function rememberTextAsMemory(name: string, body: string, context?: Record<string, unknown>): string | null {
   const command = resolveAkmCommand()
-  if (typeof command !== "string") return null
+  if (typeof command === "object" && "ok" in command) return null
   try {
-    execFileSync(command, ["--format", "json", "-q", "remember", "--name", name, "--force"], {
+    execResolvedAkm(command, ["--format", "json", "-q", "remember", "--name", name, "--force", ...buildScopedArgs(context)], {
       encoding: "utf8",
       timeout: AKM_CURATE_TIMEOUT_MS * 2,
       input: redactSecrets(body).text,
@@ -931,7 +1160,7 @@ function rememberTextAsMemory(name: string, body: string): string | null {
 function captureSessionMemory(
   sessionID: string,
   reason: string,
-  options?: { checkpoint?: boolean },
+  options?: { checkpoint?: boolean; directory?: string; agent?: string; channel?: string; userID?: string; user?: string },
 ): string | null {
   if (!AKM_AUTO_MEMORY) return null
   if (!sessionID) return null
@@ -945,6 +1174,14 @@ function captureSessionMemory(
     return null
   }
 
+  const relatedEvents = readJsonl<AkmMemoryEvent>(OPENCODE_EVENT_LOG)
+    .filter((event) => event.sessionId === sessionID)
+    .slice(-12)
+  const relatedCandidates = readCandidates(OPENCODE_CANDIDATE_LOG)
+    .filter((candidate) => candidate.sessionId === sessionID)
+    .slice(-8)
+  const harnessPaths = getHarnessStatePaths()
+
   const lines: string[] = []
   lines.push("---")
   lines.push("akm_memory_kind: session_checkpoint")
@@ -957,6 +1194,15 @@ function captureSessionMemory(
   lines.push(`Reason: ${reason}`)
   lines.push(`Session: ${sessionID}`)
   lines.push("")
+  lines.push("## Full-detail evidence files")
+  lines.push(formatPathBullet("OpenCode state dir", harnessPaths.stateDir))
+  lines.push(formatPathBullet("Structured event log", harnessPaths.eventLog))
+  lines.push(formatPathBullet("Memory candidate log", harnessPaths.candidateLog))
+  lines.push(formatPathBullet("OpenCode host log dir", harnessPaths.opencodeLogDir))
+  const harnessLog = process.env.AKM_EVAL_HARNESS_LOG?.trim()
+  if (harnessLog) lines.push(formatPathBullet("Harness log", harnessLog))
+  lines.push("")
+  lines.push(...formatEvidenceSummary(relatedEvents, relatedCandidates, pendingEntries))
   for (const entry of pendingEntries) {
     if (entry.kind === "memory-intent") {
       lines.push(`## ${entry.timestamp} — user memory intent`)
@@ -969,6 +1215,22 @@ function captureSessionMemory(
       lines.push("")
     }
   }
+  if (relatedEvents.length > 0) {
+    lines.push("## Plugin event summary")
+    for (const event of relatedEvents) {
+      const status = event.outcome?.status ?? "unknown"
+      const refs = Array.isArray(event.refs) && event.refs.length > 0 ? ` — refs: ${event.refs.join(", ")}` : ""
+      lines.push(`- ${event.timestamp} — ${event.event} (${status})${refs}`)
+    }
+    lines.push("")
+  }
+  if (relatedCandidates.length > 0) {
+    lines.push("## Memory candidates observed")
+    for (const candidate of relatedCandidates) {
+      lines.push(`- [${candidate.status}] ${candidate.type}/${candidate.scope}: ${candidate.content}`)
+    }
+    lines.push("")
+  }
   const body = lines.join("\n")
 
   const dateTag = buildDateTag({ includeTime: isCheckpoint })
@@ -977,7 +1239,15 @@ function captureSessionMemory(
     ? `opencode-checkpoint-${dateTag}-${shortSid}`
     : `opencode-session-${dateTag}-${shortSid}`
 
-  const ref = rememberTextAsMemory(name, body)
+  const ref = rememberTextAsMemory(name, body, {
+    sessionID,
+    run: sessionID,
+    directory: options?.directory,
+    agent: options?.agent,
+    channel: options?.channel,
+    userID: options?.userID,
+    user: options?.user,
+  })
   if (!ref) {
     if (!isCheckpoint) {
       sessionFinalMemoryCaptured.add(sessionID)
@@ -995,7 +1265,15 @@ function captureSessionMemory(
       refs: [ref],
       outcome: { status: "ok" },
     })
-    const candidates = extractCandidatesFromText({ harness: "opencode", sessionId: sessionID, text: body, evidence: [ref, reason] })
+    const targetRefHints = pendingEntries.flatMap((entry) => entry.ref ? [entry.ref] : [])
+    const candidates = extractCandidatesFromText({
+      harness: "opencode",
+      sessionId: sessionID,
+      text: body,
+      evidence: [ref, reason, ...targetRefHints],
+      sourcePaths: [harnessPaths.eventLog, harnessPaths.candidateLog],
+      targetRefHints,
+    })
     if (candidates.length > 0) {
       appendCandidates(OPENCODE_CANDIDATE_LOG, candidates)
       void writeStructuredEvent({
@@ -1025,7 +1303,15 @@ function captureSessionMemory(
     refs: [ref],
     outcome: { status: "ok" },
   })
-  const candidates = extractCandidatesFromText({ harness: "opencode", sessionId: sessionID, text: body, evidence: [ref, reason] })
+  const targetRefHints = entries.flatMap((entry) => entry.ref ? [entry.ref] : [])
+  const candidates = extractCandidatesFromText({
+    harness: "opencode",
+    sessionId: sessionID,
+    text: body,
+    evidence: [ref, reason, ...targetRefHints],
+    sourcePaths: [harnessPaths.eventLog, harnessPaths.candidateLog],
+    targetRefHints,
+  })
   if (candidates.length > 0) {
     appendCandidates(OPENCODE_CANDIDATE_LOG, candidates)
     void writeStructuredEvent({
@@ -1040,10 +1326,13 @@ function captureSessionMemory(
   return ref
 }
 
-function maybeCheckpointSessionMemory(sessionID: string): string | null {
+function maybeCheckpointSessionMemory(
+  sessionID: string,
+  options?: { directory?: string; agent?: string; channel?: string; userID?: string; user?: string },
+): string | null {
   const count = sessionSuccessfulAssetTouchCount.get(sessionID) ?? 0
   if (count < AKM_MEMORY_CHECKPOINT_EVERY) return null
-  const captured = captureSessionMemory(sessionID, "checkpoint", { checkpoint: true })
+  const captured = captureSessionMemory(sessionID, "checkpoint", { checkpoint: true, ...options })
   if (!captured) {
     sessionSuccessfulAssetTouchCount.set(sessionID, 0)
   }
@@ -1132,10 +1421,33 @@ function extractToolRefs(
   return { refs: [...refs], positiveOnlyRefs: [...positiveOnlyRefs] }
 }
 
+function extractAkmRefsFromAllArgs(args: Record<string, unknown>): string[] {
+  if (!args || typeof args !== "object") return []
+  const refs = new Set<string>()
+  for (const value of Object.values(args)) {
+    if (typeof value === "string") {
+      for (const ref of extractAkmRefsFromString(value)) refs.add(ref)
+    } else if (typeof value === "object" && value !== null) {
+      const serialized = JSON.stringify(value)
+      for (const ref of extractAkmRefsFromString(serialized)) refs.add(ref)
+    }
+  }
+  return [...refs]
+}
+
 const AKM_HINTS_PREFIX = [
   "# AKM is available in this session",
   "",
-  "You have an AKM stash on this machine. Before writing anything from scratch, call `akm_search` or `akm_curate` to see if the stash already covers it. Record `akm_feedback <ref> positive|negative` whenever an asset materially helps or misses, and use `akm_remember` to persist durable learnings so future sessions inherit them.",
+  "You have an AKM stash on this machine. Before writing anything from scratch, call `akm_curate` with a task description to find relevant assets with LLM-reranked relevance scores.",
+  "",
+  "**Choosing the right lookup command:**",
+  "",
+  "- **`akm_curate`** — use this when starting any new task, looking for patterns, docs, skills, or workflows. This is the PRIMARY lookup command. v0.8.0 automatically boosts assets that match the current project (cwd-anchored project-context ranking), so an explicit project name in the query is no longer required for ranking — but it still helps the reranker frame intent.",
+  '  - Good: `akm_curate("akm CLI improve command performance analysis")` (explicit framing, still ideal)',
+  '  - Bad: `akm_curate("improve performance analysis")` (too generic — the reranker has less to work with even with auto-boost)',
+  "- **`akm_search` (known name)** — use ONLY when you already know an asset exists (e.g. after `akm_show` returned \"not found\") and need to locate its exact ref. Do not use as a discovery tool.",
+  "",
+  "Record `akm_feedback <ref> positive|negative` whenever an asset materially helps or misses, and use `akm_remember` to persist durable learnings so future sessions inherit them.",
   "",
   AKM_WORKFLOW_INSTRUCTION,
 ].join("\n")
@@ -1196,15 +1508,22 @@ const AKM_HELP_QUICK_REFERENCE: readonly AkmHelpEntry[] = [
     keywords: ["proposal", "review proposals", "pending proposals", "accept proposal", "reject proposal"],
   },
   {
-    task: "Distill repeated evidence into a proposed lesson",
-    command: "akm distill <ref>",
-    notes: "Distill creates a proposal; proposed assets are not curated until accepted.",
-    keywords: ["distill", "lesson", "proposed lesson"],
+    task: "Bulk-triage the standing pending proposal backlog by policy",
+    command: "akm proposal drain --policy <personal-stash|conservative|manual> --dry-run",
+    notes: "Mutating: promotes/rejects in bulk and commits to git (no batch revert). Preview with --dry-run, then --promote --yes after explicit approval. Supersedes the old manual proposal-management agent session; also runs as the processes.triage improve pre-pass.",
+    keywords: ["proposal", "drain", "triage", "backlog", "bulk accept", "bulk reject"],
   },
   {
-    task: "Reflect on an existing asset after failure or drift",
-    command: "akm reflect <ref> --task \"...\"",
-    keywords: ["reflect", "drift", "failure"],
+    task: "Improve existing assets or distill repeated evidence into proposals",
+    command: "akm improve [<type>|<ref>] [--task \"...\"]",
+    notes: "Improve owns the former reflect/distill flow; proposed assets are not curated until accepted. Profiles add a processes.triage pre-pass and end-of-run sync.",
+    keywords: ["improve", "lesson", "reflect", "distill", "drift", "failure"],
+  },
+  {
+    task: "Manage scheduled task assets via the OS scheduler",
+    command: "akm tasks <add|list|show|remove|enable|disable|run|history|sync|doctor> ...",
+    notes: "Tasks are first-class in v0.8.0 but remain a long-tail CLI surface in this plugin.",
+    keywords: ["tasks", "scheduled task", "cron", "launchd", "schtasks"],
   },
   {
     task: "Create a proposed asset for a coverage gap",
@@ -1220,15 +1539,15 @@ const AKM_HELP_QUICK_REFERENCE: readonly AkmHelpEntry[] = [
   },
   {
     task: "Install a kit or register an external source (npm, GitHub, git, URL, local dir)",
-    command: "akm add <package-ref> [--name <n>] [--type wiki] [--writable] [--trust] [--provider <p>] [--max-pages N] [--max-depth N]",
-    notes: "Confirm with the user before passing --trust or registering a website crawler.",
+    command: "akm add <package-ref> [--name <n>] [--type wiki] [--writable] [--provider <p>] [--max-pages N] [--max-depth N] [--allow-insecure]",
+    notes: "Confirm with the user before registering a website crawler or passing --allow-insecure.",
     keywords: ["add", "install", "register", "kit", "source", "github", "npm"],
   },
   {
-    task: "Commit (and optionally push) pending stash changes",
-    command: "akm save [<source-name>] [-m <msg>] [--push]",
-    notes: "Add --push only when the stash is writable; review the diff first.",
-    keywords: ["save", "commit", "push", "publish", "git"],
+    task: "Commit and push pending stash changes",
+    command: "akm sync [<source-name>] [-m <msg>] [--no-push]",
+    notes: "For writable git-backed sources, sync commits and pushes by default (pass --no-push to skip); review the diff first.",
+    keywords: ["sync", "save", "commit", "push", "publish", "git"],
   },
   {
     task: "Import a file (or stdin) into the stash as a typed asset",
@@ -1270,6 +1589,12 @@ const AKM_HELP_QUICK_REFERENCE: readonly AkmHelpEntry[] = [
     notes: "Rarely needed — the index refreshes implicitly after writes.",
     keywords: ["index", "reindex", "rebuild"],
   },
+  {
+    task: "Manage whole-file secrets outside the chat-safe read surface",
+    command: "akm secret <set|run|remove> ...",
+    notes: "Use the first-class akm_secret tool for list/path. Secret values must never be pasted back into chat; `set` reads from stdin/--from-file/--from-env and `run` injects into a child process only.",
+    keywords: ["secret", "docker secret", "pem", "token", "_FILE"],
+  },
   {
     task: "View or update akm config (get/set/list/unset/path)",
     command: "akm config <action> [<key>] [<value>] [--all]",
@@ -1319,21 +1644,6 @@ function extractSessionIdFromEvent(payload: unknown): string | undefined {
   return undefined
 }
 
-function getCommandStatus(command: string): "ok" | "missing" | "error" {
-  try {
-    execFileSync(command, ["--version"], {
-      encoding: "utf8",
-      timeout: 10_000,
-    })
-    return "ok"
-  } catch (error: unknown) {
-    if (error && typeof error === "object" && "code" in error && (error as { code?: unknown }).code === "ENOENT") {
-      return "missing"
-    }
-    return "error"
-  }
-}
-
 function extractFirstSemverMatch(value: string): string | null {
   return value.match(SEMVER_PATTERN)?.[0] ?? null
 }
@@ -1350,208 +1660,268 @@ function getCommandVersion(command: string): string | null {
   }
 }
 
-function parseSemver(version: string): ParsedSemver | null {
-  const normalized = extractFirstSemverMatch(version)
-  if (!normalized) return null
+type ResolvedAkmCommand = {
+  command: string
+  argsPrefix: string[]
+  displayCommand: string
+}
 
-  const [withoutBuildMetadata] = normalized.split("+", 1)
-  const [release, prereleaseText] = withoutBuildMetadata.split("-", 2)
-  const parts = release.split(".").map((part) => Number(part))
-  if (parts.length !== 3 || parts.some((part) => !Number.isInteger(part) || part < 0)) {
-    return null
-  }
-  const core = [parts[0], parts[1], parts[2]] as [number, number, number]
+type CommandProbe = {
+  command: string
+  argsPrefix: string[]
+  displayCommand: string
+  exists: boolean
+  version: string | null
+  failureReason: string | null
+}
 
+// Like getCommandVersion, but distinguishes "binary not found on disk" from
+// "binary found but failed to produce a version" — the latter typically means
+// the binary is corrupt, wrong architecture, or has a runtime dependency missing.
+// Used by the diagnostic resolution trail so the consent banner can tell users
+// which failure mode they're hitting.
+function getLocalBuildAkmCommand(): ResolvedAkmCommand | null {
+  const cliPath = process.env.AKM_LOCAL_BUILD_CLI?.trim()
+  if (!cliPath) return null
   return {
-    core,
-    prerelease: prereleaseText
-      ? prereleaseText.split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : part))
-      : null,
+    command: process.env.BUN || "bun",
+    argsPrefix: [cliPath],
+    displayCommand: cliPath,
   }
 }
 
-function compareSemver(left: string, right: string): number {
-  const leftParsed = parseSemver(left)
-  const rightParsed = parseSemver(right)
-  if (!leftParsed || !rightParsed) return left.localeCompare(right)
+function execResolvedAkm(command: ResolvedAkmCommand, args: string[], options?: Parameters<typeof execFileSync>[2]) {
+  return execFileSync(command.command, [...command.argsPrefix, ...args], options)
+}
 
-  for (let index = 0; index < leftParsed.core.length; index += 1) {
-    const delta = leftParsed.core[index] - rightParsed.core[index]
-    if (delta !== 0) return delta
+function probeCommand(command: ResolvedAkmCommand): CommandProbe {
+  const displayIsAbsolute = path.isAbsolute(command.displayCommand)
+  const displayExists = displayIsAbsolute ? existsSync(command.displayCommand) : true
+  if (displayIsAbsolute && !displayExists) {
+    return { ...command, exists: false, version: null, failureReason: "not_on_disk" }
   }
-
-  if (!leftParsed.prerelease && !rightParsed.prerelease) return 0
-  if (!leftParsed.prerelease) return 1
-  if (!rightParsed.prerelease) return -1
-
-  const length = Math.max(leftParsed.prerelease.length, rightParsed.prerelease.length)
-  for (let index = 0; index < length; index += 1) {
-    const leftPart = leftParsed.prerelease[index]
-    const rightPart = rightParsed.prerelease[index]
-    if (leftPart === undefined) return -1
-    if (rightPart === undefined) return 1
-    if (leftPart === rightPart) continue
-    if (typeof leftPart === "number" && typeof rightPart === "number") return leftPart - rightPart
-    if (typeof leftPart === "number") return -1
-    if (typeof rightPart === "number") return 1
-    return leftPart.localeCompare(rightPart)
+  const commandIsAbsolute = path.isAbsolute(command.command)
+  const commandExists = commandIsAbsolute ? existsSync(command.command) : true
+  if (commandIsAbsolute && !commandExists) {
+    return { ...command, exists: false, version: null, failureReason: "command_not_on_disk" }
+  }
+  try {
+    const version = execResolvedAkm(command, ["--version"], {
+      encoding: "utf8",
+      timeout: 10_000,
+    })
+    const parsed = extractFirstSemverMatch(version)
+    if (!parsed) {
+      return { ...command, exists: true, version: null, failureReason: "no_semver_in_output" }
+    }
+    return { ...command, exists: true, version: parsed, failureReason: null }
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException)?.code
+    if (code === "ENOENT") {
+      return { ...command, exists: false, version: null, failureReason: "not_on_path" }
+    }
+    return { ...command, exists: true, version: null, failureReason: code ?? "version_check_failed" }
   }
+}
 
-  return 0
+function satisfiesAkmVersionRange(version: string | null): boolean {
+  if (typeof version !== "string") return false
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/)
+  if (!match) return false
+  return Number(match[1]) === 0 && Number(match[2]) === 8
 }
 
-function getBunGlobalAkmCommand(): string | null {
+function getBundledAkmCommand(): string | null {
+  const packagePath = path.join(moduleDir, "node_modules", "akm-cli", "package.json")
+  const fallback = path.join(moduleDir, "node_modules", ".bin", process.platform === "win32" ? "akm.cmd" : "akm")
   try {
-    const globalBin = execFileSync("bun", ["pm", "bin", "-g"], {
-      encoding: "utf8",
-      timeout: 10_000,
-    }).trim()
-    if (!globalBin || !path.isAbsolute(globalBin)) return null
-    return process.platform === "win32"
-      ? path.join(globalBin, "akm.exe")
-      : path.join(globalBin, "akm")
+    const raw = readFileSync(packagePath, "utf8")
+    const pkg = JSON.parse(raw) as { bin?: unknown }
+    const bin = pkg.bin
+    const relativeBin = typeof bin === "string"
+      ? bin
+      : bin && typeof bin === "object" && typeof (bin as Record<string, unknown>).akm === "string"
+        ? (bin as Record<string, string>).akm
+        : null
+    if (!relativeBin) return existsSync(fallback) ? fallback : null
+    const bundledCommand = path.join(moduleDir, "node_modules", "akm-cli", relativeBin)
+    return existsSync(bundledCommand) ? bundledCommand : existsSync(fallback) ? fallback : null
   } catch {
-    return null
+    return existsSync(fallback) ? fallback : null
   }
 }
 
-function getInstalledAkmDetails(): { command: string; version: string } | null {
-  const candidates = [resolvedAkmCommand, getBunGlobalAkmCommand(), "akm"]
-  const seen = new Set<string>()
-  for (const candidate of candidates) {
-    if (!candidate || seen.has(candidate)) continue
-    seen.add(candidate)
-    const version = getCommandVersion(candidate)
-    if (version) return { command: candidate, version }
+function getConfigNodeModulesAkmCommand(): string | null {
+  const homeDir = process.env.HOME || os.homedir()
+  const configDir = process.env.XDG_CONFIG_HOME || path.join(homeDir, ".config")
+  const configBin = path.join(configDir, "opencode", "node_modules", ".bin", process.platform === "win32" ? "akm.cmd" : "akm")
+  return existsSync(configBin) ? configBin : null
+}
+
+function getPathAkmCandidates(): string[] {
+  const candidates: string[] = []
+  const configNodeModules = getConfigNodeModulesAkmCommand()
+  if (configNodeModules) candidates.push(configNodeModules)
+  candidates.push("akm")
+  // Honor an explicit $HOME override (standard POSIX, and matches
+  // getConfigNodeModulesAkmCommand). os.homedir() snapshots HOME at process
+  // start and ignores later changes, which made this path non-sandboxable.
+  const home = process.env.HOME || os.homedir()
+  if (home) {
+    candidates.push(path.join(home, ".local", "bin", process.platform === "win32" ? "akm.cmd" : "akm"))
   }
-  return null
+  return candidates
 }
 
-async function getLatestNpmPackageVersion(packageName: string): Promise<string | null> {
-  if (typeof fetch !== "function") return null
+type AkmResolutionTrail = Array<{
+  command: string
+  source: "bundled" | "path" | "local_build"
+  version: string | null
+  outcome: "selected" | "version_out_of_range" | "missing" | "probe_failed"
+  failureReason: string | null
+}>
+
+let lastAkmResolutionTrail: AkmResolutionTrail = []
+
+function getResolvedAkmDetails(): { command: string; argsPrefix: string[]; displayCommand: string; version: string; source: "bundled" | "path" | "local_build" } | null {
+  const candidates: Array<{ command: string; argsPrefix: string[]; displayCommand: string; source: "bundled" | "path" | "local_build" }> = []
+  // Opt-out (default off): force the plugin to ignore its bundled akm-cli and
+  // fall through to AKM_LOCAL_BUILD_CLI / PATH. Used by the eval harness so a
+  // deterministic fake `akm` on PATH wins over the real bundled dependency;
+  // also a useful escape hatch when a bundled dep is broken.
+  const ignoreBundled = process.env.AKM_OPENCODE_IGNORE_BUNDLED_CLI === "1"
+  const bundled = ignoreBundled ? null : getBundledAkmCommand()
+  if (bundled) candidates.push({ command: bundled, argsPrefix: [], displayCommand: bundled, source: "bundled" })
+  const localBuild = getLocalBuildAkmCommand()
+  if (localBuild) candidates.push({ ...localBuild, source: "local_build" })
+  for (const command of getPathAkmCandidates()) {
+    candidates.push({ command, argsPrefix: [], displayCommand: command, source: "path" })
+  }
 
-  const controller = new AbortController()
-  const timeout = setTimeout(() => controller.abort(), 10_000)
-  try {
-    const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
-      headers: { accept: "application/json" },
-      signal: controller.signal,
-    })
-    if (!response.ok) return null
-    const body = await response.json()
-    if (!body || typeof body !== "object") return null
-    return typeof body.version === "string" ? extractFirstSemverMatch(body.version) : null
-  } catch {
-    return null
-  } finally {
-    clearTimeout(timeout)
+  const trail: AkmResolutionTrail = []
+  const seen = new Set<string>()
+  for (const candidate of candidates) {
+    const cacheKey = `${candidate.command}::${candidate.argsPrefix.join(" ")}`
+    if (!candidate.command || seen.has(cacheKey)) continue
+    seen.add(cacheKey)
+    const probe = probeCommand(candidate)
+    if (!probe.exists) {
+      trail.push({ command: candidate.displayCommand, source: candidate.source, version: null, outcome: "missing", failureReason: probe.failureReason })
+      continue
+    }
+    if (probe.failureReason || !probe.version) {
+      trail.push({ command: candidate.displayCommand, source: candidate.source, version: probe.version, outcome: "probe_failed", failureReason: probe.failureReason })
+      continue
+    }
+    if (!satisfiesAkmVersionRange(probe.version)) {
+      trail.push({ command: candidate.displayCommand, source: candidate.source, version: probe.version, outcome: "version_out_of_range", failureReason: null })
+      continue
+    }
+    trail.push({ command: candidate.displayCommand, source: candidate.source, version: probe.version, outcome: "selected", failureReason: null })
+    lastAkmResolutionTrail = trail
+    return { ...candidate, version: probe.version }
   }
+  lastAkmResolutionTrail = trail
+  return null
 }
 
-async function ensureLatestAkmInstalled(client: LogCapableClient): Promise<void> {
-  try {
-    execFileSync("bun", ["--version"], {
-      encoding: "utf8",
-      timeout: 10_000,
-    })
-  } catch (error: unknown) {
-    await writePluginLog(client, "warn", "AKM auto-install skipped", {
+// The OpenCode plugin has never silently auto-installed akm-cli — it relies on
+// the bundled binary that ships with the plugin, falling back to PATH. When
+// neither path produces a compatible akm we log a warn-level event to the host
+// AND write a stderr banner so the human running OpenCode actually sees the
+// problem. The banner mirrors the Claude plugin's wording: install must be
+// user-driven, never automatic. The recommended consent point is `akm setup`
+// (or the host-specific akm setup slash command if one exists).
+async function ensureSupportedAkmResolved(client: LogCapableClient): Promise<void> {
+  const installedAkm = getResolvedAkmDetails()
+  if (!installedAkm) {
+    await writePluginLog(client, "warn", "AKM CLI resolution failed", {
       subsystem: "akm",
-      installer: "bun",
-      error: `Bun is not available: ${formatCliError(error)}`,
+      requiredRange: AKM_REQUIRED_VERSION_RANGE,
+      bundledCommand: getBundledAkmCommand(),
+      pathCommand: "akm",
+      reason: "no_supported_command",
+      trail: lastAkmResolutionTrail,
+    })
+    writeAkmConsentBanner({
+      detected: getCommandVersion("akm") ?? undefined,
+      bundled: getBundledAkmCommand(),
+      trail: lastAkmResolutionTrail,
     })
     return
   }
 
-  const installedAkm = getInstalledAkmDetails()
-  const latestStable = await getLatestNpmPackageVersion("akm-cli")
-
-  if (installedAkm) {
-    if (!latestStable) {
-      resolvedAkmCommand = installedAkm.command
-      await writePluginLog(client, "info", "AKM auto-install skipped", {
-        subsystem: "akm",
-        installer: "bun",
-        package: autoInstallPackageRef,
-        command: resolvedAkmCommand,
-        installedVersion: installedAkm.version,
-        latestStable,
-        reason: "latest_version_unavailable",
-      })
-      return
-    }
+  resolvedAkmCommand = installedAkm.command
+  await writePluginLog(client, "info", "AKM CLI resolved", {
+    subsystem: "akm",
+    command: installedAkm.command,
+    source: installedAkm.source,
+    version: installedAkm.version,
+    requiredRange: AKM_REQUIRED_VERSION_RANGE,
+  })
+}
 
-    if (compareSemver(installedAkm.version, latestStable) >= 0) {
-      resolvedAkmCommand = installedAkm.command
-      await writePluginLog(client, "info", "AKM auto-install skipped", {
-        subsystem: "akm",
-        installer: "bun",
-        package: autoInstallPackageRef,
-        command: resolvedAkmCommand,
-        installedVersion: installedAkm.version,
-        latestStable,
-        reason: "installed_version_not_older",
-      })
-      return
+function writeAkmConsentBanner(info: { detected?: string; bundled?: string | null; trail?: AkmResolutionTrail }) {
+  const detectedLabel = info.detected ?? "(not found on PATH)"
+  const bundledLabel = info.bundled ?? "(none)"
+  const trailLines: string[] = []
+  if (info.trail && info.trail.length > 0) {
+    trailLines.push("", "  resolution trail (in order tried):")
+    for (const entry of info.trail) {
+      const versionLabel = entry.version ?? "no version"
+      const reason = entry.failureReason ? ` reason=${entry.failureReason}` : ""
+      trailLines.push(`    [${entry.source}] ${entry.command} → ${entry.outcome} (${versionLabel})${reason}`)
     }
   }
-
+  const banner = [
+    "─".repeat(60),
+    "akm-opencode plugin: akm CLI not installed or wrong version",
+    `  detected on PATH: ${detectedLabel}`,
+    `  bundled fallback: ${bundledLabel}`,
+    `  required:         ${AKM_REQUIRED_VERSION_RANGE}`,
+    ...trailLines,
+    "",
+    "Reinstall or update the akm-opencode plugin so OpenCode/Bun",
+    "installs the dependency, or install akm-cli manually:",
+    "  bun install -g akm-cli@^0.8.0",
+    "  npm install -g akm-cli@^0.8.0",
+    "Then run `akm setup` interactively to configure the stash.",
+    "─".repeat(60),
+  ].join("\n")
   try {
-    execFileSync("bun", ["install", "-g", autoInstallPackageRef], {
-      encoding: "utf8",
-      timeout: 120_000,
-      stdio: "pipe",
-    })
-
-    const bunGlobalAkm = getBunGlobalAkmCommand()
-    if (bunGlobalAkm && getCommandStatus(bunGlobalAkm) === "ok") {
-      resolvedAkmCommand = bunGlobalAkm
-    } else if (getCommandStatus("akm") === "ok") {
-      resolvedAkmCommand = "akm"
-    }
-
-      await writePluginLog(client, "info", "AKM CLI install check completed", {
-        subsystem: "akm",
-        installer: "bun",
-        package: autoInstallPackageRef,
-        command: resolvedAkmCommand,
-        installedVersion: installedAkm?.version ?? null,
-        latestStable,
-      })
-  } catch (error: unknown) {
-    await writePluginLog(client, "warn", "AKM auto-install failed", {
-      subsystem: "akm",
-      installer: "bun",
-      package: autoInstallPackageRef,
-      error: formatCliError(error),
-    })
+    process.stderr.write(banner + "\n")
+  } catch {
+    // best-effort; never crash the plugin over a banner
   }
 }
 
-function resolveAkmCommand(): string | CliError {
-  const currentStatus = getCommandStatus(resolvedAkmCommand)
-  if (currentStatus === "ok" || currentStatus === "error") return resolvedAkmCommand
+function resolveAkmCommand(): ResolvedAkmCommand | CliError {
+  const localBuild = getLocalBuildAkmCommand()
+  if (localBuild) {
+    const probe = probeCommand(localBuild)
+    if (probe.exists && satisfiesAkmVersionRange(probe.version)) return localBuild
+  }
 
-  const bunGlobalAkm = getBunGlobalAkmCommand()
-  if (bunGlobalAkm && getCommandStatus(bunGlobalAkm) === "ok") {
-    resolvedAkmCommand = bunGlobalAkm
-    return resolvedAkmCommand
+  const currentVersion = getCommandVersion(resolvedAkmCommand)
+  if (satisfiesAkmVersionRange(currentVersion)) {
+    return { command: resolvedAkmCommand, argsPrefix: [], displayCommand: resolvedAkmCommand }
   }
 
-  if (getCommandStatus("akm") === "ok") {
-    resolvedAkmCommand = "akm"
-    return resolvedAkmCommand
+  const installedAkm = getResolvedAkmDetails()
+  if (installedAkm) {
+    resolvedAkmCommand = installedAkm.command
+    return { command: installedAkm.command, argsPrefix: installedAkm.argsPrefix, displayCommand: installedAkm.displayCommand }
   }
 
   return {
     ok: false,
-    error: `The 'akm' CLI could not be resolved after attempting to install '${autoInstallPackageRef}' with Bun. Install akm from https://github.com/itlackey/akm.`,
+    error: `AKM CLI ${AKM_REQUIRED_VERSION_RANGE} is required, but no compatible bundled or PATH 'akm' executable was found. Reinstall or update the akm-opencode plugin so OpenCode/Bun installs the dependency.`,
   }
 }
 
 async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta): Promise<string> {
   const command = resolveAkmCommand()
-  if (typeof command !== "string") {
+  if (typeof command === "object" && "ok" in command) {
     await writePluginLog(client, "error", "AKM command resolution failed", {
       subsystem: "akm",
       toolName: meta.toolName,
@@ -1566,7 +1936,9 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
     return JSON.stringify(command)
   }
 
-  const fullArgs = args.includes("--format") ? [...args] : [...args, "--format", "json"]
+  // `akm improve` hard-rejects --format in 0.8.0 (cli.ts:4131-4137); never auto-inject it there.
+  const skipFormatInjection = args[0] === "improve"
+  const fullArgs = skipFormatInjection || args.includes("--format") ? [...args] : [...args, "--format", "json"]
   const proposalId = args[0] === "proposal" && typeof args[2] === "string" ? args[2] : null
 
   const recordSuccess = async (stdout: string): Promise<string> => {
@@ -1625,8 +1997,8 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
         directory: meta.directory,
       })
     }
-    if (args[0] === "proposal" && ["accept", "reject"].includes(args[1] ?? "")) {
-      await emitWorkflowTelemetry(client, "info", args[1] === "accept" ? "akm.proposal.accept.requested" : "akm.proposal.reject.requested", {
+    if (args[0] === "proposal" && ["accept", "reject", "drain"].includes(args[1] ?? "")) {
+      await emitWorkflowTelemetry(client, "info", args[1] === "accept" ? "akm.proposal.accept.requested" : args[1] === "drain" ? "akm.proposal.drain.requested" : "akm.proposal.reject.requested", {
         sessionID: meta.sessionID,
         toolName: meta.toolName,
         proposalId,
@@ -1638,14 +2010,14 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
   }
 
   try {
-    const stdout = execFileSync(command, fullArgs, {
-      encoding: "utf8",
-      timeout: 60_000,
-    })
+      const stdout = execResolvedAkm(command, fullArgs, {
+        encoding: "utf8",
+        timeout: 60_000,
+      })
     return recordSuccess(stdout)
   } catch (error: unknown) {
     let message = formatCliError(error)
-    if (["akm_reflect", "akm_propose"].includes(meta.toolName) && needsAgentSetup(message)) {
+    if (["akm_improve", "akm_propose"].includes(meta.toolName) && needsAgentSetup(message)) {
       message = addAgentSetupGuidance(message)
     }
     message = addAgentSetupGuidance(message)
@@ -1654,8 +2026,8 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
       toolName: meta.toolName,
       sessionID: meta.sessionID,
       directory: meta.directory,
-      command,
-      args: fullArgs,
+        command: command.displayCommand,
+        args: fullArgs,
       exitCode: getExecStatus(error),
       stdout: toLogString((error as { stdout?: unknown }).stdout) ?? "",
       stderr: toLogString((error as { stderr?: unknown }).stderr) ?? message,
@@ -1683,8 +2055,10 @@ type AssetType =
   | "memory"
   | "script"
   | "skill"
+  | "task"
   | "workflow"
-  | "vault"
+  | "env"
+  | "secret"
   | "wiki"
 
 const ASSET_TYPES = [
@@ -1695,8 +2069,10 @@ const ASSET_TYPES = [
   "memory",
   "script",
   "skill",
+  "task",
   "workflow",
-  "vault",
+  "env",
+  "secret",
   "wiki",
   "any",
 ] as const
@@ -1833,6 +2209,18 @@ function parseModelHint(modelHint: unknown): { providerID: string; modelID: stri
   return { providerID, modelID }
 }
 
+function resolveDispatchTarget(requested: string | undefined, fallbackAgent: string): DispatchTarget {
+  const trimmed = requested?.trim()
+  if (!trimmed) {
+    return { agent: fallbackAgent, requested: fallbackAgent }
+  }
+  const model = parseModelHint(trimmed)
+  if (model) {
+    return { agent: fallbackAgent, model, requested: trimmed }
+  }
+  return { agent: trimmed, requested: trimmed }
+}
+
 function parseToolPolicy(toolPolicy: unknown): Record<string, boolean> | undefined {
   const result: Record<string, boolean> = {}
 
@@ -2047,8 +2435,8 @@ async function promptTargetSession(input: {
   try {
     const promptResponse = await input.client.session.prompt({
       path: { id: input.targetSessionID },
-      body: input.promptBody,
-    })
+        body: input.promptBody,
+      })
 
     if (promptResponse.error || !promptResponse.data) {
       const reason = promptResponse.error ? JSON.stringify(promptResponse.error) : "empty response"
@@ -2059,6 +2447,7 @@ async function promptTargetSession(input: {
         directory: input.context.directory,
         targetSessionID: input.targetSessionID,
         dispatchAgent: input.promptBody.agent,
+        dispatchModel: input.promptBody.model ?? null,
         ref: input.ref,
         error: reason,
       })
@@ -2073,10 +2462,11 @@ async function promptTargetSession(input: {
       toolName: input.toolName,
       sessionID: input.context.sessionID,
       directory: input.context.directory,
-      targetSessionID: input.targetSessionID,
-      dispatchAgent: input.promptBody.agent,
-      ref: input.ref,
-    })
+       targetSessionID: input.targetSessionID,
+       dispatchAgent: input.promptBody.agent,
+       dispatchModel: input.promptBody.model ?? null,
+       ref: input.ref,
+     })
     return { ok: true, data: promptResponse.data }
   } catch (error: unknown) {
     const reason = error instanceof Error ? error.message : String(error)
@@ -2087,6 +2477,7 @@ async function promptTargetSession(input: {
       directory: input.context.directory,
       targetSessionID: input.targetSessionID,
       dispatchAgent: input.promptBody.agent,
+      dispatchModel: input.promptBody.model ?? null,
       ref: input.ref,
       error: reason,
     })
@@ -2156,17 +2547,6 @@ async function getParentSessionID(
   }
 }
 
-function splitArguments(raw: string): string[] {
-  if (!raw.trim()) return []
-  const args: string[] = []
-  const re = /"([^"]*)"|'([^']*)'|`([^`]*)`|(\S+)/g
-  let match: RegExpExecArray | null
-  while ((match = re.exec(raw)) !== null) {
-    args.push(match[1] ?? match[2] ?? match[3] ?? match[4] ?? "")
-  }
-  return args
-}
-
 function renderCommandTemplate(template: string, rawArguments: string): string {
   const args = splitArguments(rawArguments)
   return template
@@ -2225,7 +2605,7 @@ type PluginClient = {
 }
 
 export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
-  await ensureLatestAkmInstalled(client as unknown as LogCapableClient)
+  await ensureSupportedAkmResolved(client as unknown as LogCapableClient)
 
   const logClient = client as unknown as LogCapableClient
   const sdkClient = client as unknown as PluginClient
@@ -2258,10 +2638,12 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             })
             warmIndexInBackground()
             if (AKM_AUTO_CURATE && !sessionCurated.has(sid)) {
-              const curated = await runCurateForSession(logClient, sid)
+              const cwdContext = gatherCwdContext(directory)
+              const curated = await runCurateForSession(logClient, sid, cwdContext || undefined)
               if (curated) {
                 bumpCuratedVersion(sid)
                 sessionCurated.set(sid, curated)
+                writeCuratedFile(sid, curated)
               }
             }
           }
@@ -2278,7 +2660,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           }
         } else if (type === "session.compacted" || type === "session.idle" || type === "session.deleted") {
           if (!sid) return
-          const captured = captureSessionMemory(sid, type)
+          const captured = captureSessionMemory(sid, type, { directory })
           if (captured) {
             await writePluginLog(logClient, "info", "AKM session memory captured", {
               subsystem: "memory",
@@ -2288,6 +2670,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
               ref: captured,
             })
             await maybeIndexSessionMemory(logClient, sid, type, captured)
+            // Auto-signal so improve picks up this session memory on the next run.
+            runCliSyncRaw(["feedback", captured, "--positive", "--note", "session checkpoint: auto-signal for improve eligibility"], AKM_CURATE_TIMEOUT_MS)
           }
           if (type === "session.compacted") {
             writeStructuredEvent({
@@ -2303,6 +2687,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           if (type === "session.deleted") {
             sessionHints.delete(sid)
             sessionCurated.delete(sid)
+            sessionCuratedFile.delete(sid)
             sessionWorkflow.delete(sid)
             sessionCuratorReport.delete(sid)
             sessionContextEpoch.delete(sid)
@@ -2325,7 +2710,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
       try {
         const sid = extractSessionIdFromEvent(input)
         if (!sid) return
-        const captured = captureSessionMemory(sid, "stop")
+        const captured = captureSessionMemory(sid, "stop", { directory })
         if (captured) {
           await writePluginLog(logClient, "info", "AKM session memory captured", {
             subsystem: "memory",
@@ -2335,6 +2720,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             ref: captured,
           })
           await maybeIndexSessionMemory(logClient, sid, "stop", captured)
+          // Auto-signal so improve picks up this session memory on the next run.
+          runCliSyncRaw(["feedback", captured, "--positive", "--note", "session checkpoint: auto-signal for improve eligibility"], AKM_CURATE_TIMEOUT_MS)
         }
       } catch (error: unknown) {
         await logHookFailure(logClient, "stop", error)
@@ -2342,7 +2729,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
     },
     // experimental.chat.system.transform is how OpenCode exposes the
     // additionalContext channel. We append the cached hints (once per session)
-    // and the curated assets (once per turn) so the next LLM call sees them.
+    // and the curated file reference (once per turn) so the next LLM call
+    // sees instructions to read the curated file instead of raw content.
     "experimental.chat.system.transform": async (
       input: { sessionID?: string; session_id?: string } | undefined,
       output: { system?: string[] } | undefined,
@@ -2353,9 +2741,13 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         const epoch = sessionContextEpoch.get(sid) ?? 0
         const injectedEpoch = sessionContextInjectedEpoch.get(sid)
         if (sid && injectedEpoch !== epoch) {
+          const curatedFile = sessionCuratedFile.get(sid)
+          const curatedBlock = curatedFile
+            ? `AKM stash curation available at \`${curatedFile}\`. Read that file to discover assets relevant to this session. ${AKM_CURATED_TAIL}`
+            : ""
           const blocks = [
             sessionHints.get(sid) ? `${AKM_HINTS_PREFIX}\n\n${sessionHints.get(sid)}` : "",
-            sessionCurated.get(sid) ? `${AKM_CURATED_HEADER}\n${sessionCurated.get(sid)}${AKM_CURATED_TAIL}` : "",
+            curatedBlock,
             sessionWorkflow.get(sid) ? formatWorkflowContext(sessionWorkflow.get(sid)!) : "",
             (await getPendingProposalCount(logClient, sid)).count > 0 && !(await getPendingProposalCount(logClient, sid)).unsupported ? formatPendingProposalContext((await getPendingProposalCount(logClient, sid)).count) : "",
             sessionCuratorReport.get(sid) ? formatCuratorReportContext(sessionCuratorReport.get(sid)!) : "",
@@ -2363,8 +2755,6 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           output.system.push(...applyContextBudget(blocks))
           sessionContextInjectedEpoch.set(sid, epoch)
           if (sessionCurated.has(sid)) {
-            // Startup curation is already included in the epoch-scoped block,
-            // so mark that version as consumed to avoid a duplicate inject below.
             sessionCuratedInjectedVersion.set(sid, sessionCuratedVersion.get(sid) ?? 0)
           }
         }
@@ -2372,7 +2762,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         const curatedVersion = sessionCuratedVersion.get(sid) ?? 0
         if (curated) {
           if (sessionCuratedInjectedVersion.get(sid) !== curatedVersion) {
-            output.system.push(...applyContextBudget([`${AKM_CURATED_HEADER}\n${curated}${AKM_CURATED_TAIL}`]))
+            const curatedFile = writeCuratedFile(sid, curated)
+            output.system.push(...applyContextBudget([`AKM stash curation written to \`${curatedFile}\`. Read that file to discover assets relevant to the current task. ${AKM_CURATED_TAIL}`]))
             sessionCuratedInjectedVersion.set(sid, curatedVersion)
           }
         }
@@ -2385,10 +2776,17 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         if (!input.tool.startsWith("akm_")) return
         const args = output.args && typeof output.args === "object" ? output.args as Record<string, unknown> : {}
         const confirm = args.confirm === true
-        if (input.tool === "akm_vault" && (args.action === "show" || args.action === "unset") && !confirm) {
+        if (input.tool === "akm_env" && (args.action === "path" || args.action === "run") && !confirm) {
           output.args = {
             ...args,
-            __akmBlocked: `akm_vault action='${String(args.action)}' requires confirm:true to avoid accidental secret exposure or deletion.`,
+            __akmBlocked: `akm_env action='${String(args.action)}' requires confirm:true because env reads are sensitive.`,
+          }
+          return
+        }
+        if (input.tool === "akm_secret" && args.action === "path" && !confirm) {
+          output.args = {
+            ...args,
+            __akmBlocked: "akm_secret action='path' requires confirm:true because secret paths are sensitive.",
           }
           return
         }
@@ -2399,6 +2797,13 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           }
           return
         }
+        if (input.tool === "akm_proposal" && ["accept", "reject", "drain"].includes(String(args.action ?? "")) && !confirm) {
+          output.args = {
+            ...args,
+            __akmBlocked: `akm_proposal action='${String(args.action)}' requires confirm:true because it mutates the proposal queue.`,
+          }
+          return
+        }
         output.args = args
       } catch (error: unknown) {
         await logHookFailure(logClient, "tool.execute.before", error, {
@@ -2407,59 +2812,6 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         })
       }
     },
-    "permission.ask": async (input, output) => {
-      try {
-        const command = typeof input?.metadata?.command === "string"
-          ? input.metadata.command
-          : Array.isArray(input?.patterns)
-            ? input.patterns.join(" && ")
-            : ""
-        if (!command.includes("akm")) return
-        await emitWorkflowTelemetry(logClient, "info", "akm.raw_cli.invoked", {
-          sessionID: input.sessionID,
-          toolName: "bash",
-          outcome: "requested",
-          command,
-        })
-        const assessment = assessRiskyAkmCommand(command)
-        if (!assessment) return
-        output.status = "deny"
-        await emitWorkflowTelemetry(logClient, "warn", "akm.raw_cli.blocked", {
-          sessionID: input.sessionID,
-          toolName: "bash",
-          outcome: "blocked",
-          reason: assessment.reason,
-          command,
-          category: assessment.category,
-        })
-      } catch (error: unknown) {
-        await logHookFailure(logClient, "permission.ask", error, {
-          sessionID: input?.sessionID,
-          command: typeof input?.metadata?.command === "string" ? input.metadata.command : undefined,
-        })
-      }
-    },
-    "command.execute.before": async (input, output) => {
-      try {
-        const command = `${input.command ?? ""} ${input.arguments ?? ""}`.trim()
-        const assessment = assessRiskyAkmCommand(command)
-        if (!assessment) return
-        output.parts = [{ type: "text", text: blockedCommandMessage(command, assessment) }]
-        await emitWorkflowTelemetry(logClient, "warn", "akm.raw_cli.blocked", {
-          sessionID: input.sessionID,
-          toolName: String(input.command ?? "bash"),
-          outcome: "blocked",
-          reason: assessment.reason,
-          command,
-          category: assessment.category,
-        })
-      } catch (error: unknown) {
-        await logHookFailure(logClient, "command.execute.before", error, {
-          sessionID: input?.sessionID,
-          command: input?.command,
-        })
-      }
-    },
     "shell.env": async (_input, output) => {
       try {
         output.env.AKM_PROJECT = worktree
@@ -2486,28 +2838,63 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         if (AKM_AUTO_CURATE && input.sessionID) {
           const decision = shouldRecall(text, { activeWorkflow: !!sessionWorkflow.get(input.sessionID), recentAssetFailure: retrospectiveState.get(input.sessionID)?.lastNegativeSignalAt != null })
           if (decision.shouldRecall) {
-            const curated = await runCurateForPrompt(logClient, decision.query, input.sessionID)
-            const refs = [...new Set((curated ?? "").match(/(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|lesson|script|workflow|vault|wiki):[A-Za-z0-9._/-]+/g) ?? [])]
-            sessionRecallAudit.set(input.sessionID, {
+            // Do NOT block the model on `akm curate` — previously this awaited
+            // an 8s-timeout sync curate on every user message, adding up to 8s
+            // to the time-to-first-token of every turn. Fire-and-forget the
+            // curate; when it completes, store the result in `sessionCurated`
+            // which gets picked up by `experimental.chat.system.transform` on
+            // the NEXT message. The current message proceeds with whatever
+            // curated context (if any) was cached from previous turns.
+            const sessionID = input.sessionID
+            const directorySnapshot = directory
+            const agentSnapshot = input.agent
+            const previewText = text
+            // Record the audit row immediately so callers (akm_memory audit)
+            // see the decision; the `injectedRefs` field is populated lazily
+            // when the background curate resolves.
+            sessionRecallAudit.set(sessionID, {
               shouldRecall: true,
               reason: decision.reason,
               query: decision.query,
-              injectedRefs: refs,
-              injectedChars: curated?.length ?? 0,
-              warnings: [],
-            })
-            writeStructuredEvent({
-              event: "prompt_recall",
-              sessionId: input.sessionID,
-              scope: buildEventScope(input.sessionID, directory, input.agent),
-              input: { promptPreview: text.slice(0, 280), query: decision.query, reason: decision.reason },
-              refs,
-              outcome: { status: curated ? "ok" : "skipped" },
+              injectedRefs: [],
+              injectedChars: 0,
+              warnings: ["curate dispatched asynchronously; result injected on next message"],
             })
-            if (curated) {
-              sessionCurated.set(input.sessionID, curated)
-              bumpCuratedVersion(input.sessionID)
-            }
+            void (async () => {
+              try {
+                const curated = await runCurateForPrompt(logClient, decision.query, sessionID)
+                const refs = [...new Set((curated ?? "").match(/(?:[A-Za-z0-9@._+/-]+\/\/)?(?:skill|command|agent|knowledge|memory|lesson|script|workflow|task|env|secret|wiki):[A-Za-z0-9._/-]+/g) ?? [])]
+                const prior = sessionRecallAudit.get(sessionID)
+                if (prior) {
+                  sessionRecallAudit.set(sessionID, {
+                    ...prior,
+                    injectedRefs: refs,
+                    injectedChars: curated?.length ?? 0,
+                    warnings: prior.warnings.filter((warning) => !warning.startsWith("curate dispatched asynchronously")),
+                  })
+                }
+                writeStructuredEvent({
+                  event: "prompt_recall",
+                  sessionId: sessionID,
+                  scope: buildEventScope(sessionID, directorySnapshot, agentSnapshot),
+                  input: { promptPreview: previewText.slice(0, 280), query: decision.query, reason: decision.reason },
+                  refs,
+                  outcome: { status: curated ? "ok" : "skipped" },
+                })
+                if (curated) {
+                  sessionCurated.set(sessionID, curated)
+                  writeCuratedFile(sessionID, curated)
+                  bumpCuratedVersion(sessionID)
+                }
+              } catch (error: unknown) {
+                await writePluginLog(logClient, "warn", "AKM background curate failed", {
+                  subsystem: "curation",
+                  sessionID,
+                  directory: directorySnapshot,
+                  error: formatCliError(error),
+                })
+              }
+            })()
           } else {
             const hint = "Need more AKM context? Use `akm_search` or `akm_curate` before writing from scratch."
             sessionRecallAudit.set(input.sessionID, {
@@ -2527,7 +2914,9 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             })
             const current = sessionCurated.get(input.sessionID) ?? ""
             if (!current.includes(hint)) {
-              sessionCurated.set(input.sessionID, current ? `${current}\n\n${hint}` : hint)
+              const updated = current ? `${current}\n\n${hint}` : hint
+              sessionCurated.set(input.sessionID, updated)
+              writeCuratedFile(input.sessionID, updated)
               bumpCuratedVersion(input.sessionID)
             }
           }
@@ -2542,17 +2931,42 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           })
         }
 
-        if (input.sessionID && AKM_AUTO_FEEDBACK && AKM_RETROSPECTIVE_FEEDBACK_RE.test(text)) {
+        // Retrospective positive feedback: the loose "thanks|perfect|worked"
+        // matcher previously fired on `thanks, but it didn't work` because it
+        // only checked for a positive token without considering negation in
+        // the same message. Gate the path with the same negative/correction
+        // matchers used by `recordRetrospectiveFeedback` so a mixed-signal
+        // message is treated as ambiguous (skip rather than misattribute).
+        // Refs still flow through the shared confidence gate so Claude and
+        // OpenCode produce parallel auto-feedback verdicts for the same
+        // signal (README "Confidence-scored auto-feedback" parity claim).
+        if (
+          input.sessionID
+          && AKM_AUTO_FEEDBACK
+          && AKM_RETROSPECTIVE_FEEDBACK_RE.test(text)
+          && !AKM_RETROSPECTIVE_NEGATIVE_RE.test(text)
+          && !AKM_EXPLICIT_CORRECTION_RE.test(text)
+        ) {
           const recentRefs = (sessionBuffer.get(input.sessionID) ?? [])
             .filter((entry) => entry.kind === "tool-ref" && !!entry.ref)
             .map((entry) => entry.ref!)
-            .filter((ref, index, refs) => !ref.startsWith("memory:") && !ref.startsWith("vault:") && refs.indexOf(ref) === index)
+            .filter((ref, index, refs) => !ref.startsWith("memory:") && !ref.startsWith("env:") && !ref.startsWith("secret:") && refs.indexOf(ref) === index)
             .slice(-3)
           const dedupe = new Set<string>()
           for (const ref of recentRefs) {
-            queueFeedback(logClient, ref, "positive", "opencode retrospective: user confirmed it worked", {
+            const signal = classifyFeedbackSignal({
+              ref,
+              polarity: "positive",
+              harness: "opencode",
+              sessionId: input.sessionID,
+              retrospective: true,
+              note: "opencode retrospective: user confirmed it worked",
+            })
+            if (!shouldSubmitAutomaticFeedback(signal)) continue
+            queueFeedback(logClient, ref, "positive", signal.note, {
               toolName: "chat.message",
               sessionID: input.sessionID,
+              agent: input.agent,
             }, dedupe)
           }
         }
@@ -2570,7 +2984,38 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
     },
     "tool.execute.after": async (input, output) => {
       try {
-        if (!input.tool.startsWith("akm_")) return
+        const isAkmTool = input.tool.startsWith("akm_")
+        // The SDK type for `tool.execute.after` input does not expose `directory`,
+        // but the OpenCode runtime does provide it for tool-scoped hooks. Read
+        // it via a structural cast so we get the value when present without
+        // accepting `any` everywhere it's used.
+        const inputDirectory = (input as { directory?: unknown }).directory
+        const directory = typeof inputDirectory === "string" ? inputDirectory : undefined
+
+        const allArgRefs = extractAkmRefsFromAllArgs(input.args as Record<string, unknown>)
+        const allOutputRefs = extractAkmRefsFromString(output.output)
+        const allRefs = [...new Set([...allArgRefs, ...allOutputRefs])]
+
+        if (allRefs.length > 0) {
+          writeStructuredEvent({
+            event: "tool_ref_observed",
+            sessionId: input.sessionID,
+            scope: buildEventScope(input.sessionID, directory, input.tool),
+            input: { tool: input.tool, callID: input.callID },
+            refs: allRefs,
+            outcome: { status: "ok" },
+          })
+          for (const ref of allRefs) {
+            addBufferEntry(input.sessionID, {
+              kind: "tool-ref",
+              toolName: input.tool,
+              ref,
+              status: "unknown",
+            })
+          }
+        }
+
+        if (!isAkmTool) return
 
         const parsed = parseToolOutput(output.output)
         if (!parsed) return
@@ -2600,15 +3045,12 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           })
         }
 
-        // Auto-feedback + session buffering: record every asset ref the tool
-        // touched so the stash ranking improves over time and so Stop/Compact
-        // has material to flush into a session summary memory.
         const refResult = extractToolRefs(input.tool, input.args as Record<string, unknown>, parsed)
         noteRecentRefs(input.sessionID, refResult.refs)
         writeStructuredEvent({
           event: "tool_observation",
           sessionId: input.sessionID,
-          scope: buildEventScope(input.sessionID, input.directory, input.tool),
+          scope: buildEventScope(input.sessionID, directory, input.tool),
           input: { tool: input.tool, callID: input.callID, args: input.args as Record<string, unknown>, output: parsed as Record<string, unknown> },
           refs: refResult.refs,
           outcome: { status: feedback === "negative" ? "failed" : "ok" },
@@ -2627,7 +3069,10 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
               input.sessionID,
               (sessionSuccessfulAssetTouchCount.get(input.sessionID) ?? 0) + 1,
             )
-            const checkpointRef = maybeCheckpointSessionMemory(input.sessionID)
+            const checkpointRef = maybeCheckpointSessionMemory(input.sessionID, {
+              directory,
+              agent: input.tool,
+            })
             if (checkpointRef) {
               await writePluginLog(logClient, "info", "AKM checkpoint memory captured", {
                 subsystem: "memory",
@@ -2654,10 +3099,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             ? `opencode auto: ${input.tool} succeeded`
             : `opencode auto: ${input.tool} failed`
           for (const ref of feedbackRefs) {
-            // Memories and vault refs are not first-class feedback targets —
-            // memories do not accept feedback, and vault values never surface in
-            // JSON so automatic usage signals would be misleading.
-            if (ref.startsWith("memory:") || ref.startsWith("vault:")) continue
+            // Skip refs that should never receive auto-feedback. Matches the
+            // claude-side hook: memory/env/secret/lesson are excluded, including
+            // origin-qualified forms like `local//lesson:foo`. Lessons take
+            // feedback through the proposal queue, not via direct akm feedback.
+            if (/^(?:.*\/\/)?(?:memory|env|secret|lesson):/.test(ref)) continue
             const directInput = Object.values(input.args as Record<string, unknown>).some((value) => typeof value === "string" && value.includes(ref))
             const signal = classifyFeedbackSignal({
               ref,
@@ -2671,7 +3117,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
               writeStructuredEvent({
                 event: "feedback_recorded",
                 sessionId: input.sessionID,
-                scope: buildEventScope(input.sessionID, input.directory, input.tool),
+                scope: buildEventScope(input.sessionID, directory, input.tool),
                 refs: [ref],
                 input: { source: signal.source, confidence: signal.confidence, note: signal.note },
                 outcome: { status: "skipped", warnings: ["confidence below automatic submission threshold"] },
@@ -2681,12 +3127,14 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             const ok = queueFeedback(logClient, ref, feedback, signal.note, {
               toolName: input.tool,
               sessionID: input.sessionID,
+              directory,
+              agent: input.tool,
             }, dedupe)
             if (ok) {
               writeStructuredEvent({
                 event: "feedback_recorded",
                 sessionId: input.sessionID,
-                scope: buildEventScope(input.sessionID, input.directory, input.tool),
+                scope: buildEventScope(input.sessionID, directory, input.tool),
                 refs: [ref],
                 input: { source: signal.source, confidence: signal.confidence, note: signal.note },
                 outcome: { status: "ok" },
@@ -2716,7 +3164,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
       },
     }),
     akm_search: tool({
-      description: "Search your stash or the akm registry for scripts, skills, commands, agents, knowledge, memories, workflows, vaults, and wikis. Use source='registry' for installable community kits.",
+      description: "Search your stash or the akm registry for scripts, skills, commands, agents, knowledge, memories, lessons, tasks, workflows, env configs, secrets, and wikis. Use source='registry' for installable community kits.",
       args: {
         query: tool.schema.string().describe("Case-insensitive substring search."),
         type: tool.schema
@@ -2872,7 +3320,14 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           return JSON.stringify({ ok: true, candidates })
         }
         if (input.action === "checkpoint") {
-          const ref = captureSessionMemory(context.sessionID, "manual-checkpoint", { checkpoint: true })
+          const ref = captureSessionMemory(context.sessionID, "manual-checkpoint", {
+            checkpoint: true,
+            directory: context.directory,
+            agent: context.agent,
+            channel: (context as Record<string, unknown>).channel as string | undefined,
+            userID: (context as Record<string, unknown>).userID as string | undefined,
+            user: (context as Record<string, unknown>).user as string | undefined,
+          })
           return JSON.stringify({ ok: true, ref })
         }
         if (input.action === "sync") {
@@ -2900,7 +3355,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           } else if (candidate.recommendedAction === "feedback" && candidate.targetRef) {
             rawResult = await runCli(client as unknown as LogCapableClient, ["feedback", candidate.targetRef, "--positive", "--note", candidate.content, ...buildScopedArgs(context as unknown as Record<string, unknown>)], { toolName: "akm_memory", sessionID: context.sessionID, directory: context.directory })
           } else if (candidate.recommendedAction === "distill" && candidate.targetRef) {
-            rawResult = await runCli(client as unknown as LogCapableClient, ["distill", candidate.targetRef], { toolName: "akm_memory", sessionID: context.sessionID, directory: context.directory })
+            rawResult = await runCli(client as unknown as LogCapableClient, ["improve", candidate.targetRef], { toolName: "akm_memory", sessionID: context.sessionID, directory: context.directory })
           } else if (candidate.recommendedAction === "propose") {
             rawResult = await runCli(client as unknown as LogCapableClient, ["propose", "knowledge", `candidate-${candidate.id}`, "--task", candidate.content], { toolName: "akm_memory", sessionID: context.sessionID, directory: context.directory })
           } else {
@@ -2955,6 +3410,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         as_subtask: tool.schema.boolean().optional().describe("Run in a child session with parent context. Defaults to true."),
       },
       async execute({ focus, dispatch_agent, as_subtask }, context) {
+        await ensureFreshProposalCheckpoint(logClient, {
+          sessionID: context.sessionID,
+          directory: context.directory,
+          agent: context.agent,
+        }, "pre-evolve")
         const useSubtask = as_subtask ?? true
         const requestedAgent = dispatch_agent ?? "akm-curator"
         const targetAgent = await resolveDispatchAgent(sdkClient, requestedAgent, context.directory)
@@ -2993,7 +3453,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         const dateTag = buildDateTag()
         const shortSid = context.sessionID.replace(/[^A-Za-z0-9._-]/g, "").slice(0, 8) || "session"
         const curatorMemoryRef = fullText
-          ? rememberTextAsMemory(`akm-curator-${dateTag}-${shortSid}`, fullText)
+          ? rememberTextAsMemory(`akm-curator-${dateTag}-${shortSid}`, fullText, context as unknown as Record<string, unknown>)
           : null
 
         return JSON.stringify({
@@ -3077,7 +3537,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         ref: tool.schema.string().optional().describe("Agent ref from akm_search (e.g. agent:my-agent.md)."),
         query: tool.schema.string().optional().describe("If ref is omitted, resolve best matching stash agent for this query."),
         task_prompt: tool.schema.string().describe("Task prompt sent to the dispatched OpenCode agent."),
-        dispatch_agent: tool.schema.string().optional().describe("OpenCode agent to run the task with. Defaults to 'general'."),
+        dispatch_agent: tool.schema.string().optional().describe("OpenCode agent to run the task with, or a provider/model override like 'openai/gpt-5.3-codex'. Defaults to 'general'."),
         as_subtask: tool.schema.boolean().optional().describe("Run in child session with parent context. Defaults to true."),
       },
       async execute({ ref, query, task_prompt, dispatch_agent, as_subtask }, context) {
@@ -3110,10 +3570,10 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         }
 
         const useSubtask = as_subtask ?? true
-        const targetAgent = dispatch_agent ?? "general"
-        const model = parseModelHint(shown.modelHint)
+        const dispatchTarget = resolveDispatchTarget(dispatch_agent, "general")
+        const hintedModel = parseModelHint(shown.modelHint)
+        const model = dispatchTarget.model ?? hintedModel
         const tools = parseToolPolicy(shown.toolPolicy)
-
         writeStructuredEvent({
           event: "subagent_started",
           sessionId: context.sessionID,
@@ -3121,7 +3581,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           input: {
             ref: resolved.ref,
             stashAgent: shown.name,
-            dispatchAgent: targetAgent,
+            dispatchAgent: dispatchTarget.agent,
+            requestedDispatchTarget: dispatchTarget.requested,
             taskPrompt: task_prompt,
             advisoryToolPolicy: shown.toolPolicy ?? null,
             appliedToolPolicy: tools ?? null,
@@ -3143,7 +3604,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         if (!targetSession.ok) return JSON.stringify(targetSession)
 
         const promptBody: SessionPromptBody = {
-          agent: targetAgent,
+          agent: dispatchTarget.agent,
           system: shown.prompt,
           parts: [{ type: "text", text: task_prompt }],
         }
@@ -3163,13 +3624,26 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         if (!promptResponse.ok) return JSON.stringify(promptResponse)
 
         const childText = extractText(promptResponse.data.parts)
-        const candidates = extractCandidatesFromText({ harness: "opencode", sessionId: targetSession.sessionID, text: childText, evidence: [resolved.ref, task_prompt] })
+        const candidates = extractCandidatesFromText({
+          harness: "opencode",
+          sessionId: targetSession.sessionID,
+          text: childText,
+          evidence: [resolved.ref, task_prompt],
+          sourcePaths: [OPENCODE_EVENT_LOG, OPENCODE_CANDIDATE_LOG],
+          targetRefHints: [resolved.ref],
+        })
         if (candidates.length > 0) appendCandidates(OPENCODE_CANDIDATE_LOG, candidates)
         writeStructuredEvent({
           event: "subagent_completed",
           sessionId: context.sessionID,
           scope: buildEventScope(context.sessionID, context.directory, context.agent),
-          input: { childSessionID: targetSession.sessionID, stashAgent: shown.name, dispatchAgent: targetAgent },
+          input: {
+            childSessionID: targetSession.sessionID,
+            stashAgent: shown.name,
+            dispatchAgent: dispatchTarget.agent,
+            requestedDispatchTarget: dispatchTarget.requested,
+            dispatchModel: model ?? null,
+          },
           memory: { parentSessionID: context.sessionID, childSessionID: targetSession.sessionID, candidatesCreated: candidates.length },
           refs: [resolved.ref],
           outcome: { status: "ok" },
@@ -3179,7 +3653,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           ok: true,
           ref: resolved.ref,
           stashAgent: shown.name,
-          dispatchAgent: targetAgent,
+          dispatchAgent: dispatchTarget.agent,
+          requestedDispatchTarget: dispatchTarget.requested,
           usedSubtask: useSubtask,
           sessionID: targetSession.sessionID,
           model,
@@ -3194,7 +3669,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         ref: tool.schema.string().optional().describe("Command ref from akm_search (e.g. command:review.md)."),
         query: tool.schema.string().optional().describe("If ref is omitted, resolve best matching stash command for this query."),
         arguments: tool.schema.string().optional().describe("Command arguments used for $ARGUMENTS and positional placeholders ($1, $2, ...)."),
-        dispatch_agent: tool.schema.string().optional().describe("OpenCode agent to run the rendered command. Defaults to current agent."),
+        dispatch_agent: tool.schema.string().optional().describe("OpenCode agent to run the rendered command, or a provider/model override like 'openai/gpt-5.3-codex'. Defaults to current agent."),
         as_subtask: tool.schema.boolean().optional().describe("Run in child session with parent context. Defaults to false."),
       },
       async execute({ ref, query, arguments: commandArguments, dispatch_agent, as_subtask }, context) {
@@ -3221,7 +3696,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         const argsText = commandArguments ?? ""
         const rendered = renderCommandTemplate(template, argsText)
         const useSubtask = as_subtask ?? false
-        const targetAgent = dispatch_agent ?? context.agent
+        const fallbackAgent = typeof context.agent === "string" && context.agent.trim() ? context.agent : "general"
+        const dispatchTarget = resolveDispatchTarget(dispatch_agent, fallbackAgent)
 
         const targetSession = await ensureTargetSessionID({
           useSubtask,
@@ -3242,7 +3718,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           failureMessage: `Failed to execute command ${resolved.ref}`,
           ref: resolved.ref,
           promptBody: {
-            agent: targetAgent,
+            agent: dispatchTarget.agent,
+            model: dispatchTarget.model,
             parts: [{ type: "text", text: rendered }],
           },
         })
@@ -3252,75 +3729,84 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           ok: true,
           ref: resolved.ref,
           stashCommand: shown.name,
-          dispatchAgent: targetAgent,
+          dispatchAgent: dispatchTarget.agent,
+          requestedDispatchTarget: dispatchTarget.requested,
           usedSubtask: useSubtask,
           sessionID: targetSession.sessionID,
+          model: dispatchTarget.model,
           arguments: argsText,
           renderedTemplate: rendered,
           text: extractText(promptResponse.data.parts),
         })
       },
     }),
-    akm_vault: tool({
-      description: "Manage encrypted-at-rest vaults of KEY=VALUE pairs. Values never surface in any output channel — 'show'/'list' return key names only, 'set'/'unset' never echo the value. Use 'load' to get a shell-eval snippet that loads values into the process. action='show' and action='unset' require confirm:true.",
+    akm_env: tool({
+      description: "Access AKM env assets (.env files) without surfacing values. 'list' returns env refs. 'path' returns the on-disk file path. 'run' injects the env into a child command without values reaching stdout — the preferred agent-safe path. action='path' and action='run' require confirm:true.",
       args: {
-        action: tool.schema.enum(["list", "show", "create", "set", "unset", "load"]).describe("Vault subcommand. 'load' wraps `akm vault load` — treat its output as opaque shell text meant for eval."),
-        ref: tool.schema.string().optional().describe("Vault ref such as vault:prod or vault:team/prod. Required for show/set/unset/load; optional for list."),
-        name: tool.schema.string().optional().describe("Vault name when action is 'create' (e.g. 'prod' → vaults/prod.env)."),
-        key: tool.schema.string().optional().describe("Variable name for set/unset. May include '=' to pass KEY=VALUE in one field when value is omitted."),
-        value: tool.schema.string().optional().describe("Value to store. Never echoed back."),
-        comment: tool.schema.string().optional().describe("Optional inline '# comment' written above the key for 'set'."),
-        confirm: tool.schema.boolean().optional().describe("Must be true for sensitive actions like show and unset."),
+        action: tool.schema.enum(["list", "path", "run"]).describe("Env subcommand. 'list' returns refs; 'path' returns the file path; 'run' injects env into a child command."),
+        ref: tool.schema.string().optional().describe("Env ref such as env:prod or env:myapp. Required for path/run."),
+        cmd: tool.schema.string().optional().describe("Command to run with env injected. Required for action='run'. Example: 'npm start'."),
+        confirm: tool.schema.boolean().optional().describe("Must be true for path and run actions."),
       },
       async execute(input) {
         const blocked = blockedToolResponse(input as Record<string, unknown>)
         if (blocked) return blocked
-        const { action, ref, name, key, value, comment } = input
-        const logMeta = { toolName: "akm_vault" }
+        const { action, ref, cmd, confirm } = input
+        const logMeta = { toolName: "akm_env" }
         switch (action) {
           case "list": {
-            const args = ["vault", "list"]
-            if (ref) args.push(ref)
-            return runCli(client as unknown as LogCapableClient, args, logMeta)
-          }
-          case "show": {
-            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='show'." })
-            return runCli(client as unknown as LogCapableClient, ["vault", "show", ref], logMeta)
-          }
-          case "create": {
-            if (!name) return JSON.stringify({ ok: false, error: "'name' is required for action='create'." })
-            return runCli(client as unknown as LogCapableClient, ["vault", "create", name], logMeta)
+            return runCli(client as unknown as LogCapableClient, ["env", "list"], logMeta)
           }
-          case "set": {
-            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='set'." })
-            if (!key) return JSON.stringify({ ok: false, error: "'key' is required for action='set'." })
-            const args = ["vault", "set", ref, key]
-            if (value != null) args.push(value)
-            if (comment) args.push("--comment", comment)
-            return runCli(client as unknown as LogCapableClient, args, logMeta)
+          case "path": {
+            if (confirm !== true) return JSON.stringify({ ok: false, error: "akm_env action='path' requires confirm:true." })
+            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='path'." })
+            return runCli(client as unknown as LogCapableClient, ["env", "path", ref], logMeta)
           }
-          case "unset": {
-            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='unset'." })
-            if (!key) return JSON.stringify({ ok: false, error: "'key' is required for action='unset'." })
-            return runCli(client as unknown as LogCapableClient, ["vault", "unset", ref, key], logMeta)
+          case "run": {
+            if (confirm !== true) return JSON.stringify({ ok: false, error: "akm_env action='run' requires confirm:true." })
+            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='run'." })
+            if (!cmd) return JSON.stringify({ ok: false, error: "'cmd' is required for action='run'." })
+            return runCli(client as unknown as LogCapableClient, ["env", "run", ref, "--", ...cmd.split(/\s+/)], logMeta)
           }
-          case "load": {
-            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='load'." })
-            // `vault load` emits raw shell — not JSON. Return the snippet verbatim
-            // so the caller can hand it to a shell via eval. Never parse values.
+        }
+      },
+    }),
+    akm_secret: tool({
+      description: "Inspect whole-file AKM secrets without surfacing contents. 'list' returns secret refs only. 'path' returns the on-disk file path for `_FILE`-style consumers. action='path' requires confirm:true.",
+      args: {
+        action: tool.schema.enum(["list", "path"]).describe("Secret subcommand. 'path' returns the absolute file path without reading or echoing the secret bytes."),
+        ref: tool.schema.string().optional().describe("Secret ref such as secret:deploy-key. Required for action='path'."),
+        confirm: tool.schema.boolean().optional().describe("Must be true for sensitive actions like path."),
+      },
+      async execute(input) {
+        const blocked = blockedToolResponse(input as Record<string, unknown>)
+        if (blocked) return blocked
+        const { action, ref, confirm } = input
+        const logMeta = { toolName: "akm_secret" }
+        switch (action) {
+          case "list":
+            return runCli(client as unknown as LogCapableClient, ["secret", "list"], logMeta)
+          case "path": {
+            if (confirm !== true) return JSON.stringify({ ok: false, error: "akm_secret action='path' requires confirm:true because secret paths are sensitive." })
+            if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='path'." })
             const command = resolveAkmCommand()
-            if (typeof command !== "string") return JSON.stringify(command)
+            if (typeof command === "object" && "ok" in command) return JSON.stringify(command)
             try {
-              const stdout = execFileSync(command, ["vault", "load", ref], {
+              const filePath = execResolvedAkm(command, ["secret", "path", ref], {
                 encoding: "utf8",
                 timeout: 30_000,
+              }).toString().trim()
+              return JSON.stringify({
+                ok: true,
+                ref,
+                filePath,
+                usage: "Pass this file path to trusted `_FILE`-style consumers or shells. The plugin did not read or surface the secret contents.",
               })
-              return JSON.stringify({ ok: true, ref, shell: stdout.trim() })
             } catch (error: unknown) {
-              await writePluginLog(logClient, "error", "AKM vault load failed", {
-                subsystem: "vault",
-                toolName: "akm_vault",
-                action: "load",
+              await writePluginLog(logClient, "error", "AKM secret path failed", {
+                subsystem: "secret",
+                toolName: "akm_secret",
+                action: "path",
                 ref,
                 error: formatCliError(error),
               })
@@ -3347,8 +3833,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         ]).describe("Wiki subcommand."),
         name: tool.schema.string().optional().describe("Wiki name (required for every action except 'list')."),
         source_ref: tool.schema.string().optional().describe("Source ref to register (required for action='register'). Accepts directory paths, git URLs, github owner/repo, or https:// website roots."),
-        writable: tool.schema.boolean().optional().describe("When registering a git-backed source, mark it as push-writable (used by `akm save`; see akm_help topic='save')."),
-        trust: tool.schema.boolean().optional().describe("Bypass install-audit blocking for this registration only."),
+        writable: tool.schema.boolean().optional().describe("When registering a git-backed source, mark it as push-writable (used by `akm sync`; see akm_help topic='sync')."),
         max_pages: tool.schema.number().optional().describe("Crawler page cap when registering a website (default 50)."),
         max_depth: tool.schema.number().optional().describe("Crawler depth cap when registering a website (default 3)."),
         query: tool.schema.string().optional().describe("Query string for action='search'."),
@@ -3359,7 +3844,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         force: tool.schema.boolean().optional().describe("Required for action='remove'."),
         with_sources: tool.schema.boolean().optional().describe("When removing, also delete the raw/ sources (default false)."),
       },
-      async execute({ action, name, source_ref, writable, trust, max_pages, max_depth, query, limit, source, as_slug, content, force, with_sources }) {
+      async execute({ action, name, source_ref, writable, max_pages, max_depth, query, limit, source, as_slug, content, force, with_sources }) {
         const logMeta = { toolName: "akm_wiki" }
         const requireName = () => {
           if (!name) return JSON.stringify({ ok: false, error: `'name' is required for action='${action}'.` })
@@ -3396,7 +3881,6 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             if (!source_ref) return JSON.stringify({ ok: false, error: "'source_ref' is required for action='register'." })
             const args = ["wiki", "register", name!, source_ref]
             if (writable) args.push("--writable")
-            if (trust) args.push("--trust")
             if (max_pages != null) args.push("--max-pages", String(max_pages))
             if (max_depth != null) args.push("--max-depth", String(max_depth))
             return runCli(client as unknown as LogCapableClient, args, logMeta)
@@ -3422,9 +3906,9 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             if (as_slug) args.push("--as", as_slug)
             if (source === "-" && content) {
               const command = resolveAkmCommand()
-              if (typeof command !== "string") return JSON.stringify(command)
+              if (typeof command === "object" && "ok" in command) return JSON.stringify(command)
               try {
-                const stdout = execFileSync(command, [...args, "--format", "json"], {
+                const stdout = execResolvedAkm(command, [...args, "--format", "json"], {
                   encoding: "utf8",
                   timeout: 60_000,
                   input: content,
@@ -3552,9 +4036,9 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           case "template": {
             // The workflow template is emitted as raw markdown, not JSON.
             const command = resolveAkmCommand()
-            if (typeof command !== "string") return JSON.stringify(command)
+            if (typeof command === "object" && "ok" in command) return JSON.stringify(command)
             try {
-              const stdout = execFileSync(command, ["workflow", "template"], {
+              const stdout = execResolvedAkm(command, ["workflow", "template"], {
                 encoding: "utf8",
                 timeout: 30_000,
               })
@@ -3579,14 +4063,26 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
       },
     }),
     akm_proposal: tool({
-      description: "Operate the AKM v0.7.0 proposal queue — list/show/diff/accept/reject pending drafts. All proposal-producing commands (reflect, propose, distill, plus plugin-emitted proposals) write through this queue. Acceptance runs full validation before promoting; rejection archives the draft. Always confirm with the user before action='accept' or 'reject'.",
+      description: "Operate the AKM v0.8.0 proposal queue — list/show/diff/accept/reject pending drafts, or action='drain' for deterministic BULK triage of the whole backlog. All proposal-producing commands (improve, propose, plus plugin-emitted proposals) write through this queue. Acceptance runs full validation before promoting; rejection archives the draft. Always confirm with the user before action='accept', 'reject', or 'drain'. action='drain' clears the standing pending backlog by a deterministic policy (default queue/stage mode; pass promote:true to actually accept) — mutating, commits to git, no batch revert; always preview with dry_run:true first. This and the automatic improve `processes.triage` pre-pass supersede manual one-by-one queue management.",
       args: {
-        action: tool.schema.enum(["list", "show", "diff", "accept", "reject"]).describe("Proposal subcommand."),
+        action: tool.schema.enum(["list", "show", "diff", "accept", "reject", "drain"]).describe("Proposal subcommand."),
         id: tool.schema.string().optional().describe("Proposal id. Required for show/diff/accept/reject."),
         status: tool.schema.enum(["pending", "accepted", "rejected"]).optional().describe("Filter for action='list'."),
         reason: tool.schema.string().optional().describe("Required for action='reject'. Recorded with the archived proposal."),
+        confirm: tool.schema.boolean().optional().describe("Must be true for action='accept', 'reject', and 'drain'."),
+        policy: tool.schema.string().optional().describe("action='drain' only: built-in preset (personal-stash|conservative|manual) or path to a policy file."),
+        promote: tool.schema.boolean().optional().describe("action='drain' only: promote (accept) matching proposals. Default is queue/stage mode (no writes to assets)."),
+        dry_run: tool.schema.boolean().optional().describe("action='drain' only: list the planned accept/reject/defer set without writing. Always preview first."),
+        max_accepts: tool.schema.number().optional().describe("action='drain' only: hard per-run accept ceiling."),
+        max_diff_lines: tool.schema.number().optional().describe("action='drain' only: defer accepts whose proposed content exceeds this many lines."),
+        older_than: tool.schema.number().optional().describe("action='drain' only: only consider proposals created more than this many days ago."),
+        judgment: tool.schema.boolean().optional().describe("action='drain' only: opt into the judgment tier for deferred items."),
+        profile: tool.schema.string().optional().describe("action='drain' only: read the triage block (policy, applyMode, ceilings, judgment) from this improve profile."),
       },
-      async execute({ action, id, status, reason }) {
+      async execute(input) {
+        const blocked = blockedToolResponse(input as Record<string, unknown>)
+        if (blocked) return blocked
+        const { action, id, status, reason, confirm, policy, promote, dry_run, max_accepts, max_diff_lines, older_than, judgment, profile } = input
         const logMeta = { toolName: "akm_proposal" }
         switch (action) {
           case "list": {
@@ -3603,51 +4099,89 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             return runCli(client as unknown as LogCapableClient, ["proposal", "diff", id], logMeta)
           }
           case "accept": {
+            if (confirm !== true) return JSON.stringify({ ok: false, error: "akm_proposal action='accept' requires confirm:true because it mutates the proposal queue." })
             if (!id) return JSON.stringify({ ok: false, error: "'id' is required for action='accept'. Confirm with the user before accepting." })
-            return runCli(client as unknown as LogCapableClient, ["proposal", "accept", id], logMeta)
+            const acceptResult = await runCli(client as unknown as LogCapableClient, ["proposal", "accept", id, "--yes"], logMeta)
+            // Invalidate the proposal-count cache so the next getPendingProposalCount() call
+            // reflects the updated queue immediately (WS-7a: no stale 60s TTL after mutations).
+            pendingProposalSummaryCache.clear()
+            return acceptResult
           }
           case "reject": {
+            if (confirm !== true) return JSON.stringify({ ok: false, error: "akm_proposal action='reject' requires confirm:true because it mutates the proposal queue." })
             if (!id) return JSON.stringify({ ok: false, error: "'id' is required for action='reject'. Confirm with the user before rejecting." })
             if (!reason || !reason.trim()) return JSON.stringify({ ok: false, error: "'reason' is required for action='reject'. Ask the user why the proposal is being rejected." })
-            return runCli(client as unknown as LogCapableClient, ["proposal", "reject", id, "--reason", reason], logMeta)
+            const rejectResult = await runCli(client as unknown as LogCapableClient, ["proposal", "reject", id, "--reason", reason, "--yes"], logMeta)
+            // Invalidate the proposal-count cache (WS-7a).
+            pendingProposalSummaryCache.clear()
+            return rejectResult
+          }
+          case "drain": {
+            if (confirm !== true) return JSON.stringify({ ok: false, error: "akm_proposal action='drain' requires confirm:true because it bulk-mutates the proposal queue and commits to git." })
+            const args = ["proposal", "drain"]
+            if (policy) args.push("--policy", policy)
+            if (promote) args.push("--promote")
+            if (dry_run) args.push("--dry-run")
+            else args.push("--yes")
+            if (typeof max_accepts === "number") args.push("--max-accepts", String(max_accepts))
+            if (typeof max_diff_lines === "number") args.push("--max-diff-lines", String(max_diff_lines))
+            if (typeof older_than === "number") args.push("--older-than", String(older_than))
+            if (judgment) args.push("--judgment")
+            if (profile) args.push("--profile", profile)
+            const drainResult = await runCli(client as unknown as LogCapableClient, args, logMeta)
+            // A real drain (not a dry run) mutates the queue; invalidate the count cache (WS-7a).
+            if (!dry_run) pendingProposalSummaryCache.clear()
+            return drainResult
           }
         }
       },
     }),
-    akm_reflect: tool({
-      description: "Generate a reflection proposal for an AKM ref via the configured agent CLI. Output lands in the proposal queue only — never mutates live stash content. Requires `agent.default` to be set (run akm_setup first if missing).",
+    akm_improve: tool({
+      description: "Generate AKM improvement proposals for an existing ref, an asset type, or the broader stash. This is the v0.8.0 replacement for the old reflect/distill flow. Output lands in the proposal queue only — never mutates live stash content. Requires `defaults.agent` (with a matching `profiles.agent.<name>` entry) to be set for agent-backed proposal generation; the legacy `agent.default` shape is auto-migrated on load.",
       args: {
-        ref: tool.schema.string().optional().describe("[origin//]type:name ref to reflect on. Optional — when omitted the agent reflects on overall session signal."),
-        task: tool.schema.string().optional().describe("Free-form task description guiding the reflection."),
+        scope: tool.schema.string().optional().describe("Optional asset type or [origin//]type:name ref to improve. When omitted, improves the current stash scope."),
+        task: tool.schema.string().optional().describe("Optional extra guidance for this improvement pass."),
+        dry_run: tool.schema.boolean().optional().describe("Show planned actions without generating proposals."),
       },
-      async execute({ ref, task }) {
-        const args = ["reflect"]
-        if (ref) args.push(ref)
+      async execute({ scope, task, dry_run }, context) {
+        if (!dry_run) {
+          await ensureFreshProposalCheckpoint(logClient, {
+            sessionID: context.sessionID,
+            directory: context.directory,
+            agent: context.agent,
+          }, "pre-improve")
+        }
+        const args = ["improve"]
+        if (scope) args.push(scope)
         if (task) args.push("--task", task)
-        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_reflect" })
+        if (dry_run) args.push("--dry-run")
+        const improveResult = await runCli(client as unknown as LogCapableClient, args, { toolName: "akm_improve", sessionID: context.sessionID, directory: context.directory, agent: context.agent })
+        // Invalidate the proposal-count cache after improve (may have added proposals) (WS-7a).
+        if (!dry_run) pendingProposalSummaryCache.clear()
+        return improveResult
       },
     }),
     akm_propose: tool({
-      description: "Generate a new-asset proposal via the configured agent CLI. The asset is drafted as `quality:\"proposed\"` and lands in the proposal queue — never directly into curated content. Requires `agent.default` (run akm_setup first if missing).",
+      description: "Generate a new-asset proposal via the configured agent CLI. The asset is drafted as `quality:\"proposed\"` and lands in the proposal queue — never directly into curated content. Requires `defaults.agent` (with a matching `profiles.agent.<name>` entry; run akm_setup first if missing). The legacy `agent.default` shape is auto-migrated on load.",
       args: {
         type: tool.schema.enum(["skill", "command", "agent", "knowledge", "lesson", "script", "workflow", "wiki"]).describe("Asset type for the new proposal."),
         name: tool.schema.string().describe("Slug for the new asset (matches the standard ref grammar)."),
-        task: tool.schema.string().describe("Required. Describes what the asset should do."),
-      },
-      async execute({ type, name, task }) {
-        if (!task || !task.trim()) return JSON.stringify({ ok: false, error: "'task' is required for akm_propose." })
-        const args = ["propose", type, name, "--task", task]
-        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_propose" })
+        task: tool.schema.string().optional().describe("Optional inline task text describing what the asset should do."),
+        file: tool.schema.string().optional().describe("Optional UTF-8 file path to read the task text from. Exactly one of task/file is required."),
       },
-    }),
-    akm_distill: tool({
-      description: "Distill an AKM ref into a proposed `lesson` using the bounded in-tree LLM. Gated by `llm.features.feedback_distillation` (default false); when the gate is off the call returns a fallback warning instead of a proposal. Lessons require `description` and `when_to_use` frontmatter and are stored under `lessons/<name>.md` after acceptance.",
-      args: {
-        ref: tool.schema.string().describe("[origin//]type:name ref to distill — most often memory:<name> or knowledge:<name>."),
-      },
-      async execute({ ref }) {
-        if (!ref || !ref.trim()) return JSON.stringify({ ok: false, error: "'ref' is required for akm_distill." })
-        return runCli(client as unknown as LogCapableClient, ["distill", ref], { toolName: "akm_distill" })
+      async execute({ type, name, task, file }, context) {
+        const hasTask = !!task?.trim()
+        const hasFile = !!file?.trim()
+        if (hasTask === hasFile) return JSON.stringify({ ok: false, error: "Exactly one of 'task' or 'file' is required for akm_propose." })
+        await ensureFreshProposalCheckpoint(logClient, {
+          sessionID: context.sessionID,
+          directory: context.directory,
+          agent: context.agent,
+        }, "pre-propose")
+        const args = ["propose", type, name]
+        if (hasTask) args.push("--task", task!.trim())
+        if (hasFile) args.push("--file", file!.trim())
+        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_propose", sessionID: context.sessionID, directory: context.directory, agent: context.agent })
       },
     }),
     akm_init: tool({
@@ -3665,13 +4199,13 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
       },
       async execute({ topic, command }) {
         const cliCommand = resolveAkmCommand()
-        if (typeof cliCommand !== "string") return JSON.stringify(cliCommand)
+        if (typeof cliCommand === "object" && "ok" in cliCommand) return JSON.stringify(cliCommand)
         const helpArgs = command && command.trim()
           ? [command.trim(), "--help"]
           : ["--help"]
         let helpText = ""
         try {
-          helpText = execFileSync(cliCommand, helpArgs, {
+          helpText = execResolvedAkm(cliCommand, helpArgs, {
             encoding: "utf8",
             timeout: 30_000,
           }).toString().trim()
@@ -3694,13 +4228,14 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           help: helpText,
           workflowTopics: [
             "proposal",
-            "distill",
-            "reflect",
+            "improve",
             "propose",
             "lesson",
+            "tasks",
+            "secret-safety",
             "include-proposed",
             "llm-features",
-            "vault-safety",
+            "env-safety",
           ],
         })
       },
@@ -3708,6 +4243,6 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
     },
   }
 }
-
+ 
 export const server = AkmPlugin
-export default { server }
+export default { server, id: "akm-opencode" }