akm-opencode 0.7.2 → 0.7.5

package/README.md

@@ -36,7 +36,7 @@ The plugin exposes **20 high-value tools**. Long-tail verbs (`add`, `save`, `imp
 | `akm_reflect` | Generate a reflection proposal via the configured agent CLI; output lands in the proposal queue only |
 | `akm_propose` | Generate a new-asset proposal via the configured agent CLI; the result is `quality:"proposed"` until accepted |
 | `akm_distill` | Distill an AKM ref (typically `memory:*` or `knowledge:*`) into a proposed `lesson` (gated by `llm.features.feedback_distillation`) |
-| `akm_setup` | Detect installed agent CLIs (`opencode`, `claude`, `codex`, `gemini`, `aider`) and persist `agent.default`. Required once per machine for `akm_reflect` / `akm_propose` |
+| `akm_init` | Initialize AKM's working stash directory and persist `stashDir` in config. This is the agent-safe initialization path; interactive `akm setup` is human-facing |
 | `akm_help` | Discover the right `akm` CLI invocation for non-first-class verbs. Returns a curated quick-reference table plus live `akm <subcommand> --help` output |
 
 ## Compound-engineering hooks
@@ -47,8 +47,8 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 
 | Event | What happens |
 | --- | --- |
-| **`session.created`** (event hook) | Warms the stash index in the background, caches `akm hints` plus active workflow status, and runs a scoped `akm curate --run <sessionID>` so fresh sessions see relevant stash context before the first user message. |
-| **`chat.message`** | Runs `akm curate "<prompt>" --run <sessionID>` on each user message (prompts shorter than `AKM_CURATE_MIN_CHARS` are skipped). The top matches are stored for injection. Memory intents (prompts mentioning "remember" / "memory") are tracked in the session buffer. |
+| **`session.created`** (event hook) | Sets `agent.default` to `opencode` when missing, warms the stash index in the background, caches `akm hints` plus active workflow status, and runs a scoped `akm curate --run <sessionID>` so fresh sessions start with relevant stash context. |
+| **`chat.message`** | Records user feedback/memory intent and appends a short reminder to use `akm_search` / `akm_curate` when more stash context is needed. It does not auto-run AKM CLI lookups on every message. |
 | **`experimental.chat.system.transform`** | Appends cached hints, active workflow state, pending proposal summaries, the last curator report, and the current prompt's curated context to the model's system prompt. Hints and workflow state are re-injected after transcript compaction. |
 | **`tool.execute.before`** (`akm_*` tools) | Blocks destructive or sensitive operations until `confirm:true` is provided. |
 | **`permission.ask`** / **`command.execute.before`** | Detects risky raw `akm` CLI commands executed through shell/commands and denies them until the user explicitly approves the exact operation. |
@@ -61,7 +61,7 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `AKM_AUTO_CURATE` | `1` | Set to `0` to disable automatic `akm curate` on user messages. |
+| `AKM_AUTO_CURATE` | `1` | Set to `0` to disable automatic `akm curate` on user messages. Session start no longer auto-curates. |
 | `AKM_AUTO_FEEDBACK` | `1` | Set to `0` to disable automatic `akm feedback` on tool success/failure. |
 | `AKM_AUTO_HINTS` | `1` | Set to `0` to skip injecting `akm hints` at session start. |
 | `AKM_AUTO_MEMORY` | `1` | Set to `0` to disable automatic session-summary memories. |

package/index.ts

@@ -3,6 +3,11 @@ import { execFileSync, execSync, spawn } from "node:child_process"
 import { readFileSync } from "node:fs"
 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"
 
 let resolvedAkmCommand = "akm"
 const autoInstallPackageRef = process.env.AKM_PACKAGE_REF ?? "akm-cli@latest"
@@ -26,6 +31,8 @@ const AKM_RETROSPECTIVE_NEGATIVE_RE = createRetrospectiveNegativeRegex()
 const AKM_EXPLICIT_CORRECTION_RE = createExplicitCorrectionRegex()
 const PLUGIN_VERSION = readPackageVersion()
 const PLUGIN_INSTALL_LOCATION = moduleDir
+const OPENCODE_EVENT_LOG = getEventLogPath("opencode")
+const OPENCODE_CANDIDATE_LOG = getCandidateLogPath("opencode")
 
 // Per-session state that drives the compound-engineering loop.
 // These maps are keyed by OpenCode sessionID.
@@ -37,6 +44,7 @@ const sessionContextEpoch = new Map<string, number>()
 const sessionContextInjectedEpoch = new Map<string, number>()
 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
@@ -71,7 +79,7 @@ const AKM_WORKFLOW_INSTRUCTION = [
   "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`.",
-  "6. Run `akm_setup` once on a fresh machine to detect installed agent CLIs and persist `agent.default`. Reflect/propose require it.",
+  "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.",
 ].join("\n")
@@ -225,42 +233,17 @@ function needsAgentSetup(message: string): boolean {
 
 function addAgentSetupGuidance(message: string): string {
   if (!needsAgentSetup(message)) return message
-  if (/\bakm_setup\b|\bakm setup\b/i.test(message)) return message
-  return `${message}. Run akm_setup to detect an installed agent CLI and persist agent.default. If none is installed yet, install one of: opencode, claude, codex, gemini, aider.`
+  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.`
 }
 
-function toLogString(value: unknown): string | undefined {
-  if (typeof value === "string") return value
-  if (value instanceof Buffer) return value.toString("utf8")
-  return undefined
-}
-
-function getExecStatus(error: unknown): number | null {
-  if (!error || typeof error !== "object" || !("status" in error)) return null
-  const status = (error as { status?: unknown }).status
-  return typeof status === "number" ? status : null
-}
-
-async function writePluginLog(client: LogCapableClient, level: LogLevel, message: string, extra: Record<string, unknown>) {
-  try {
-    await client.app.log({
-      query: typeof extra.directory === "string" ? { directory: extra.directory } : undefined,
-      body: {
-        service: "akm-opencode",
-        level,
-        message,
-        extra,
-      },
-    })
-  } catch {
-    // Avoid breaking the TUI if logging itself fails.
-  }
-}
-
-async function runAgentSetup(client: LogCapableClient, meta: { directory?: string; sessionID?: string; trigger: string; force?: boolean }): Promise<boolean> {
+async function ensurePlatformAgentDefault(
+  client: LogCapableClient,
+  meta: { directory?: string; sessionID?: string; trigger: string; platform: string },
+): Promise<boolean> {
   const command = resolveAkmCommand()
   if (typeof command !== "string") {
-    await writePluginLog(client, "warn", "AKM agent setup skipped", {
+    await writePluginLog(client, "warn", "AKM agent default check skipped", {
       subsystem: "akm",
       trigger: meta.trigger,
       sessionID: meta.sessionID,
@@ -270,59 +253,56 @@ async function runAgentSetup(client: LogCapableClient, meta: { directory?: strin
     return false
   }
 
-  const args = ["setup"]
-  if (meta.force) args.push("--force")
-  args.push("--format", "json")
-
   try {
-    const stdout = execFileSync(command, args, {
+    const currentRaw = execFileSync(command, ["config", "get", "agent.default", "--format", "json"], {
       encoding: "utf8",
       timeout: 30_000,
     })
-    const parsed = safeJsonParse<{ ok?: boolean; error?: string }>(stdout)
-    if (parsed?.ok === false) {
-      await writePluginLog(client, "warn", "AKM agent setup reported an error", {
-        subsystem: "akm",
-        trigger: meta.trigger,
-        sessionID: meta.sessionID,
-        directory: meta.directory,
-        command,
-        args,
-        stdout,
-        error: parsed.error ?? "Unknown akm setup error",
-      })
-      return false
-    }
-    await writePluginLog(client, "info", "AKM agent setup completed", {
+    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()
+            : ""
+        : ""
+    if (current) return true
+
+    execFileSync(command, ["config", "set", "agent.default", meta.platform, "--format", "json"], {
+      encoding: "utf8",
+      timeout: 30_000,
+    })
+    await writePluginLog(client, "info", "AKM agent default initialized", {
       subsystem: "akm",
       trigger: meta.trigger,
       sessionID: meta.sessionID,
       directory: meta.directory,
-      command,
-      args,
-      stdout,
+      agentDefault: meta.platform,
     })
     return true
   } catch (error: unknown) {
-    const message = addAgentSetupGuidance(formatCliError(error))
-    await writePluginLog(client, "warn", "AKM agent setup failed", {
+    await writePluginLog(client, "warn", "AKM agent default initialization failed", {
       subsystem: "akm",
       trigger: meta.trigger,
       sessionID: meta.sessionID,
       directory: meta.directory,
-      command,
-      args,
-      error: message,
+      platform: meta.platform,
+      error: addAgentSetupGuidance(formatCliError(error)),
       stdout: toLogString((error as { stdout?: unknown }).stdout) ?? "",
-      stderr: toLogString((error as { stderr?: unknown }).stderr) ?? message,
+      stderr: toLogString((error as { stderr?: unknown }).stderr) ?? "",
     })
     return false
   }
 }
 
-async function ensureAgentSetup(client: LogCapableClient, meta: { directory?: string; sessionID?: string; trigger: string; force?: boolean }): Promise<boolean> {
+async function ensureAgentSetup(
+  client: LogCapableClient,
+  meta: { directory?: string; sessionID?: string; trigger: string; platform: string },
+): Promise<boolean> {
   if (agentSetupPromise) return agentSetupPromise
-  const promise = runAgentSetup(client, meta)
+  const promise = ensurePlatformAgentDefault(client, meta)
   const trackedPromise = promise.finally(() => {
     if (agentSetupPromise === trackedPromise) agentSetupPromise = null
   })
@@ -330,6 +310,74 @@ async function ensureAgentSetup(client: LogCapableClient, meta: { directory?: st
   return trackedPromise
 }
 
+function isNotIndexedFeedbackError(message: string): boolean {
+  return /not in the current index|run ["'`]?akm index["'`]? and try again/i.test(message)
+}
+
+function toLogString(value: unknown): string | undefined {
+  if (typeof value === "string") return value
+  if (value instanceof Buffer) return value.toString("utf8")
+  return undefined
+}
+
+function getExecStatus(error: unknown): number | null {
+  if (!error || typeof error !== "object" || !("status" in error)) return null
+  const status = (error as { status?: unknown }).status
+  return typeof status === "number" ? status : null
+}
+
+async function writePluginLog(client: LogCapableClient, level: LogLevel, message: string, extra: Record<string, unknown>) {
+  try {
+    const redacted = redactObject(extra)
+    await client.app.log({
+      query: typeof redacted.value.directory === "string" ? { directory: redacted.value.directory as string } : undefined,
+      body: {
+        service: "akm-opencode",
+        level,
+        message,
+        extra: redacted.value,
+      },
+    })
+  } catch {
+    // Avoid breaking the TUI if logging itself fails.
+  }
+}
+
+function buildEventScope(sessionID?: string, directory?: string, agent?: string) {
+  return {
+    user: process.env.AKM_USER_ID,
+    agent,
+    run: sessionID,
+    channel: process.env.AKM_CHANNEL,
+    project: directory,
+    repo: process.env.AKM_REPO,
+    branch: process.env.AKM_BRANCH,
+  }
+}
+
+function writeStructuredEvent(event: Omit<AkmMemoryEvent, "version" | "timestamp" | "harness">) {
+  return appendMemoryEvent(OPENCODE_EVENT_LOG, {
+    version: 1,
+    timestamp: nowIso(),
+    harness: "opencode",
+    ...event,
+  })
+}
+
+async function logHookFailure(
+  client: LogCapableClient,
+  hook: string,
+  error: unknown,
+  extra?: Record<string, unknown>,
+) {
+  await writePluginLog(client, "error", `AKM ${hook} hook failed`, {
+    subsystem: "hook",
+    hook,
+    error: formatCliError(error),
+    ...extra,
+  })
+}
+
 function nowIso(): string {
   return new Date().toISOString()
 }
@@ -431,9 +479,20 @@ function runCurate(args: string[]): string | null {
   return body || null
 }
 
-function runCurateForPrompt(text: string, sessionID?: string): string | null {
+async function runCurateLogged(
+  client: LogCapableClient,
+  args: string[],
+  meta: CliLogMeta & { operation: string },
+): Promise<string | null> {
+  return runCliSyncBestEffort(client, args, AKM_CURATE_TIMEOUT_MS, {
+    ...meta,
+    subsystem: "curation",
+  })
+}
+
+async function runCurateForPrompt(client: LogCapableClient, text: string, sessionID?: string): Promise<string | null> {
   if (!text || text.length < AKM_CURATE_MIN_CHARS) return null
-  return runCurate(
+  return runCurateLogged(client,
     appendRunScopeArgs(
       [
         "--detail",
@@ -448,11 +507,12 @@ function runCurateForPrompt(text: string, sessionID?: string): string | null {
       ],
       sessionID,
     ),
+    { toolName: "chat.message", sessionID, operation: "prompt-curate" },
   )
 }
 
-function runCurateForSession(sessionID: string): string | null {
-  return runCurate(
+async function runCurateForSession(client: LogCapableClient, sessionID: string): Promise<string | null> {
+  return runCurateLogged(client,
     appendRunScopeArgs(
       [
         "--detail",
@@ -466,14 +526,17 @@ function runCurateForSession(sessionID: string): string | null {
       ],
       sessionID,
     ),
+    { toolName: "session.start", sessionID, operation: "session-curate" },
   )
 }
 
-function runHintsForSession(): string | null {
-  const result = runCliSyncRaw(["--format", "text", "-q", "hints"], AKM_CURATE_TIMEOUT_MS)
-  if (!result.ok) return null
-  const body = result.stdout.trim()
-  return body || null
+async function runHintsForSession(client: LogCapableClient, sessionID?: string): Promise<string | null> {
+  return runCliSyncBestEffort(client, ["--format", "text", "-q", "hints"], AKM_CURATE_TIMEOUT_MS, {
+    toolName: "session.start",
+    sessionID,
+    subsystem: "hints",
+    operation: "session-hints",
+  })
 }
 
 function summarizeWorkflowList(value: unknown): string | null {
@@ -507,10 +570,15 @@ function summarizeWorkflowList(value: unknown): string | null {
   return null
 }
 
-function runWorkflowSummaryForSession(): string | null {
-  const result = runCliSyncRaw(["--format", "json", "-q", "workflow", "list", "--active"], AKM_CURATE_TIMEOUT_MS)
-  if (!result.ok) return null
-  const parsed = parseMaybeJson(result.stdout)
+async function runWorkflowSummaryForSession(client: LogCapableClient, sessionID?: string): Promise<string | null> {
+  const raw = await runCliSyncBestEffort(client, ["--format", "json", "-q", "workflow", "list", "--active"], AKM_CURATE_TIMEOUT_MS, {
+    toolName: "session.start",
+    sessionID,
+    subsystem: "workflow",
+    operation: "active-workflow-summary",
+  })
+  if (!raw) return null
+  const parsed = parseMaybeJson(raw)
   const summary = summarizeWorkflowList(
     Array.isArray(parsed)
       ? parsed
@@ -547,14 +615,20 @@ function summarizeCuratorReportForContext(report: string): string {
   return `${report.slice(0, AKM_CURATOR_CONTEXT_MAX_CHARS).trimEnd()}\n\n[truncated for context]`
 }
 
-function getAkmStashDir(): string | undefined {
+async function getAkmStashDir(client?: LogCapableClient): Promise<string | undefined> {
   if (cachedAkmStashDir !== undefined) return cachedAkmStashDir || undefined
-  const result = runCliSyncRaw(["--format", "json", "-q", "config", "get", "stashDir"], AKM_CURATE_TIMEOUT_MS)
-  if (!result.ok) {
+  const raw = client
+    ? await runCliSyncBestEffort(client, ["--format", "json", "-q", "config", "get", "stashDir"], AKM_CURATE_TIMEOUT_MS, {
+      toolName: "shell.env",
+      subsystem: "config",
+      operation: "get-stash-dir",
+    })
+    : runCurate(["--format", "json", "-q", "config", "get", "stashDir"])
+  if (!raw) {
     cachedAkmStashDir = ""
     return undefined
   }
-  const parsed = parseMaybeJson(result.stdout)
+  const parsed = parseMaybeJson(raw)
   if (typeof parsed === "string" && parsed.trim()) {
     cachedAkmStashDir = parsed.trim()
     return cachedAkmStashDir
@@ -568,7 +642,6 @@ function getAkmStashDir(): string | undefined {
       }
     }
   }
-  const raw = result.stdout.trim()
   cachedAkmStashDir = raw || ""
   return cachedAkmStashDir || undefined
 }
@@ -594,6 +667,19 @@ function safeJsonParse<T>(raw: string): T | undefined {
 }
 
 function emitWorkflowTelemetry(client: LogCapableClient, level: LogLevel, eventType: string, extra: Record<string, unknown>) {
+  const mappedEvent: AkmMemoryEvent["event"] = eventType.includes("workflow_")
+    ? eventType as AkmMemoryEvent["event"]
+    : eventType.includes("blocked")
+      ? "safety_blocked"
+      : "workflow_step"
+  void writeStructuredEvent({
+    event: mappedEvent,
+    sessionId: typeof extra.sessionID === "string" ? extra.sessionID : undefined,
+    workflowRunId: typeof extra.runId === "string" ? extra.runId : undefined,
+    scope: buildEventScope(typeof extra.sessionID === "string" ? extra.sessionID : undefined, typeof extra.directory === "string" ? extra.directory : undefined, typeof extra.toolName === "string" ? extra.toolName : undefined),
+    input: redactObject(extra).value as Record<string, unknown>,
+    outcome: { status: level === "error" ? "failed" : level === "warn" ? "blocked" : "ok", warnings: typeof extra.reason === "string" ? [extra.reason] : undefined },
+  })
   return writePluginLog(client, level, eventType, {
     subsystem: "workflow-compliance",
     eventType,
@@ -602,6 +688,29 @@ function emitWorkflowTelemetry(client: LogCapableClient, level: LogLevel, eventT
   })
 }
 
+async function runCliSyncBestEffort(
+  client: LogCapableClient,
+  args: string[],
+  timeoutMs: number,
+  meta: CliLogMeta & { subsystem: string; operation: string },
+): Promise<string | null> {
+  const result = runCliSyncRaw(args, timeoutMs)
+  if (!result.ok) {
+    await writePluginLog(client, "warn", "AKM synchronous helper failed", {
+      subsystem: meta.subsystem,
+      operation: meta.operation,
+      toolName: meta.toolName,
+      sessionID: meta.sessionID,
+      directory: meta.directory,
+      args,
+      error: result.error,
+    })
+    return null
+  }
+  const body = result.stdout.trim()
+  return body || null
+}
+
 function noteRecentRefs(sessionID: string | undefined, refs: string[]) {
   if (!sessionID || refs.length === 0) return
   const state = retrospectiveState.get(sessionID) ?? { recentRefs: [] }
@@ -659,7 +768,7 @@ async function recordRetrospectiveFeedback(client: LogCapableClient, sessionID:
     sessionID,
   })
   const parsed = safeJsonParse<{ ok?: boolean }>(raw)
-  if (parsed?.ok !== false) {
+  if (parsed?.ok === true) {
     await emitWorkflowTelemetry(client, "info", "akm.feedback.recorded", {
       sessionID,
       toolName: "akm_feedback",
@@ -811,7 +920,7 @@ function rememberTextAsMemory(name: string, body: string): string | null {
     execFileSync(command, ["--format", "json", "-q", "remember", "--name", name, "--force"], {
       encoding: "utf8",
       timeout: AKM_CURATE_TIMEOUT_MS * 2,
-      input: body,
+      input: redactSecrets(body).text,
     })
     return `memory:${name}`
   } catch {
@@ -837,6 +946,13 @@ function captureSessionMemory(
   }
 
   const lines: string[] = []
+  lines.push("---")
+  lines.push("akm_memory_kind: session_checkpoint")
+  lines.push("harness: opencode")
+  lines.push(`session_id: ${sessionID}`)
+  lines.push(`reason: ${reason}`)
+  lines.push("---")
+  lines.push("")
   lines.push(`# Session summary (${nowIso()})`)
   lines.push(`Reason: ${reason}`)
   lines.push(`Session: ${sessionID}`)
@@ -871,6 +987,26 @@ function captureSessionMemory(
   }
 
   if (isCheckpoint) {
+    void writeStructuredEvent({
+      event: "pre_compact_checkpoint",
+      sessionId: sessionID,
+      scope: buildEventScope(sessionID),
+      memory: { ref, reason, kind: "session_checkpoint" },
+      refs: [ref],
+      outcome: { status: "ok" },
+    })
+    const candidates = extractCandidatesFromText({ harness: "opencode", sessionId: sessionID, text: body, evidence: [ref, reason] })
+    if (candidates.length > 0) {
+      appendCandidates(OPENCODE_CANDIDATE_LOG, candidates)
+      void writeStructuredEvent({
+        event: "candidate_extracted",
+        sessionId: sessionID,
+        scope: buildEventScope(sessionID),
+        memory: { sourceRef: ref, count: candidates.length },
+        refs: [ref],
+        outcome: { status: "ok" },
+      })
+    }
     for (const entry of entries) {
       if (!entry.checkpointed) entry.checkpointed = true
     }
@@ -881,6 +1017,26 @@ function captureSessionMemory(
 
   sessionFinalMemoryCaptured.add(sessionID)
   sessionBuffer.delete(sessionID)
+  void writeStructuredEvent({
+    event: "session_ended",
+    sessionId: sessionID,
+    scope: buildEventScope(sessionID),
+    memory: { ref, reason, kind: "session_checkpoint" },
+    refs: [ref],
+    outcome: { status: "ok" },
+  })
+  const candidates = extractCandidatesFromText({ harness: "opencode", sessionId: sessionID, text: body, evidence: [ref, reason] })
+  if (candidates.length > 0) {
+    appendCandidates(OPENCODE_CANDIDATE_LOG, candidates)
+    void writeStructuredEvent({
+      event: "candidate_extracted",
+      sessionId: sessionID,
+      scope: buildEventScope(sessionID),
+      memory: { sourceRef: ref, count: candidates.length },
+      refs: [ref],
+      outcome: { status: "ok" },
+    })
+  }
   return ref
 }
 
@@ -1490,32 +1646,7 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
   } catch (error: unknown) {
     let message = formatCliError(error)
     if (["akm_reflect", "akm_propose"].includes(meta.toolName) && needsAgentSetup(message)) {
-      const setupOk = await ensureAgentSetup(client, {
-        directory: meta.directory,
-        sessionID: meta.sessionID,
-        trigger: `${meta.toolName}:retry`,
-        force: true,
-      })
-      if (setupOk) {
-        try {
-          const stdout = execFileSync(command, fullArgs, {
-            encoding: "utf8",
-            timeout: 60_000,
-          })
-          await writePluginLog(client, "info", "AKM command recovered after setup", {
-            subsystem: "akm",
-            toolName: meta.toolName,
-            sessionID: meta.sessionID,
-            directory: meta.directory,
-            command,
-            args: fullArgs,
-          })
-          return recordSuccess(stdout)
-        } catch (retryError: unknown) {
-          error = retryError
-          message = formatCliError(retryError)
-        }
-      }
+      message = addAgentSetupGuidance(message)
     }
     message = addAgentSetupGuidance(message)
     await writePluginLog(client, "error", "AKM command failed", {
@@ -2110,16 +2241,24 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         const sid = extractSessionIdFromEvent(event) ?? extractSessionIdFromEvent((event as { properties?: unknown }).properties)
         if (type === "session.created" || type === "session.updated") {
           if (!sid) return
+          writeStructuredEvent({
+            event: "session_started",
+            sessionId: sid,
+            scope: buildEventScope(sid, directory),
+            input: { type },
+            outcome: { status: "ok" },
+          })
           if (!sessionContextEpoch.has(sid)) sessionContextEpoch.set(sid, 0)
           if (type === "session.created") {
             await ensureAgentSetup(logClient, {
               directory,
               sessionID: sid,
               trigger: "session.created",
+              platform: "opencode",
             })
             warmIndexInBackground()
             if (AKM_AUTO_CURATE && !sessionCurated.has(sid)) {
-              const curated = runCurateForSession(sid)
+              const curated = await runCurateForSession(logClient, sid)
               if (curated) {
                 bumpCuratedVersion(sid)
                 sessionCurated.set(sid, curated)
@@ -2127,11 +2266,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             }
           }
           if (AKM_AUTO_HINTS && !sessionHints.has(sid)) {
-            const hints = runHintsForSession()
+            const hints = await runHintsForSession(logClient, sid)
             if (hints) sessionHints.set(sid, hints)
           }
           if (!sessionWorkflow.has(sid)) {
-            sessionWorkflow.set(sid, runWorkflowSummaryForSession() ?? "")
+            sessionWorkflow.set(sid, await runWorkflowSummaryForSession(logClient, sid) ?? "")
           }
           const proposalSummary = await getPendingProposalCount(logClient, sid)
           if (!proposalSummary.unsupported && proposalSummary.count > 0) {
@@ -2150,6 +2289,15 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             })
             await maybeIndexSessionMemory(logClient, sid, type, captured)
           }
+          if (type === "session.compacted") {
+            writeStructuredEvent({
+              event: "post_compact_summary",
+              sessionId: sid,
+              scope: buildEventScope(sid, directory),
+              memory: { ref: captured ?? null, reason: type },
+              outcome: { status: captured ? "ok" : "skipped" },
+            })
+          }
           // Drop per-session state so a re-created session does not inherit
           // stale hints/curation.
           if (type === "session.deleted") {
@@ -2166,8 +2314,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             sessionBuffer.delete(sid)
           }
         }
-      } catch {
-        // Lifecycle hooks must never throw into the TUI.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "event", error)
       }
     },
     // Stop is the closest analogue to Claude's Stop/SubagentStop — the user or
@@ -2188,8 +2336,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           })
           await maybeIndexSessionMemory(logClient, sid, "stop", captured)
         }
-      } catch {
-        // Best-effort only.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "stop", error)
       }
     },
     // experimental.chat.system.transform is how OpenCode exposes the
@@ -2228,8 +2376,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             sessionCuratedInjectedVersion.set(sid, curatedVersion)
           }
         }
-      } catch {
-        // Never break the turn because of a transform failure.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "experimental.chat.system.transform", error)
       }
     },
     "tool.execute.before": async (input, output) => {
@@ -2244,9 +2392,19 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           }
           return
         }
+        if (input.tool === "akm_memory" && ["promote", "reject"].includes(String(args.action ?? "")) && !confirm) {
+          output.args = {
+            ...args,
+            __akmBlocked: `akm_memory action='${String(args.action)}' requires confirm:true because it mutates candidate or memory state.`,
+          }
+          return
+        }
         output.args = args
-      } catch {
-        // Never break tool execution from the pre-hook.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "tool.execute.before", error, {
+          toolName: input?.tool,
+          sessionID: input?.sessionID,
+        })
       }
     },
     "permission.ask": async (input, output) => {
@@ -2274,8 +2432,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           command,
           category: assessment.category,
         })
-      } catch {
-        // Best-effort only.
+      } 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) => {
@@ -2292,18 +2453,21 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           command,
           category: assessment.category,
         })
-      } catch {
-        // Best-effort only.
+      } 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
         output.env.AKM_PLUGIN_VERSION = PLUGIN_VERSION
-        const stashDir = getAkmStashDir()
+        const stashDir = await getAkmStashDir(logClient)
         if (stashDir) output.env.AKM_STASH_DIR = stashDir
-      } catch {
-        // Best-effort only.
+      } catch (error: unknown) {
+        await logHookFailure(logClient, "shell.env", error)
       }
     },
     "chat.message": async (input, output) => {
@@ -2319,13 +2483,53 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           text: truncateLogText(text),
         })
 
-        // Compound-engineering loop: on every user message, curate the stash and
-        // stash the result so experimental.chat.system.transform can inject it.
         if (AKM_AUTO_CURATE && input.sessionID) {
-          const curated = runCurateForPrompt(text, input.sessionID)
-          if (curated) {
-            sessionCurated.set(input.sessionID, curated)
-            bumpCuratedVersion(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, {
+              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" },
+            })
+            if (curated) {
+              sessionCurated.set(input.sessionID, curated)
+              bumpCuratedVersion(input.sessionID)
+            }
+          } else {
+            const hint = "Need more AKM context? Use `akm_search` or `akm_curate` before writing from scratch."
+            sessionRecallAudit.set(input.sessionID, {
+              shouldRecall: false,
+              reason: decision.reason,
+              query: decision.query,
+              injectedRefs: [],
+              injectedChars: 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 },
+              outcome: { status: "skipped" },
+            })
+            const current = sessionCurated.get(input.sessionID) ?? ""
+            if (!current.includes(hint)) {
+              sessionCurated.set(input.sessionID, current ? `${current}\n\n${hint}` : hint)
+              bumpCuratedVersion(input.sessionID)
+            }
           }
         }
 
@@ -2401,6 +2605,14 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         // 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),
+          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" },
+        })
         if (refResult.refs.length > 0 && input.sessionID) {
           for (const ref of refResult.refs) {
             addBufferEntry(input.sessionID, {
@@ -2446,10 +2658,40 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             // 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
-            const ok = queueFeedback(logClient, ref, feedback, note, {
+            const directInput = Object.values(input.args as Record<string, unknown>).some((value) => typeof value === "string" && value.includes(ref))
+            const signal = classifyFeedbackSignal({
+              ref,
+              polarity: feedback,
+              harness: "opencode",
+              sessionId: input.sessionID,
+              directInput,
+              note: `${note}; confidence=${directInput ? "0.65" : "0.25"}; source=${feedback === "positive" ? "tool_success" : "tool_failure"}`,
+            })
+            if (!shouldSubmitAutomaticFeedback(signal)) {
+              writeStructuredEvent({
+                event: "feedback_recorded",
+                sessionId: input.sessionID,
+                scope: buildEventScope(input.sessionID, input.directory, input.tool),
+                refs: [ref],
+                input: { source: signal.source, confidence: signal.confidence, note: signal.note },
+                outcome: { status: "skipped", warnings: ["confidence below automatic submission threshold"] },
+              })
+              continue
+            }
+            const ok = queueFeedback(logClient, ref, feedback, signal.note, {
               toolName: input.tool,
               sessionID: input.sessionID,
             }, dedupe)
+            if (ok) {
+              writeStructuredEvent({
+                event: "feedback_recorded",
+                sessionId: input.sessionID,
+                scope: buildEventScope(input.sessionID, input.directory, input.tool),
+                refs: [ref],
+                input: { source: signal.source, confidence: signal.confidence, note: signal.note },
+                outcome: { status: "ok" },
+              })
+            }
             if (!ok) break
           }
         }
@@ -2552,6 +2794,32 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         if (note) args.push("--note", note)
         args.push(...buildScopedArgs(context as unknown as Record<string, unknown>))
         const raw = await runCli(client as unknown as LogCapableClient, args, { toolName: "akm_feedback", sessionID: context.sessionID, directory: context.directory })
+        const parsed = safeJsonParse<{ ok?: boolean; error?: string }>(raw)
+        if (parsed?.ok === false) {
+          const error = parsed.error ?? "Unknown akm feedback error"
+          if (isNotIndexedFeedbackError(error)) {
+            await writePluginLog(logClient, "warn", "AKM feedback skipped", {
+              subsystem: "feedback",
+              toolName: "akm_feedback",
+              sessionID: context.sessionID,
+              directory: context.directory,
+              ref,
+              sentiment,
+              reason: "ref_not_indexed",
+              error,
+            })
+            await emitWorkflowTelemetry(logClient, "warn", "akm.feedback.skipped", {
+              sessionID: context.sessionID,
+              toolName: "akm_feedback",
+              assetRef: ref,
+              outcome: "skipped",
+              reason: "ref not indexed",
+              directory: context.directory,
+            })
+            return JSON.stringify({ ok: true, skipped: true, reason: "ref_not_indexed", ref, sentiment })
+          }
+          return raw
+        }
         await emitWorkflowTelemetry(logClient, "info", "akm.feedback.recorded", {
           sessionID: context.sessionID,
           toolName: "akm_feedback",
@@ -2563,6 +2831,108 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         return raw
       },
     }),
+    akm_memory: tool({
+      description: "Audit AKM memory behavior, inspect pending candidates, and promote or reject candidates. Mutating actions require confirm:true.",
+      args: {
+        action: tool.schema.enum(["audit", "candidates", "promote", "reject", "checkpoint", "sync"]).describe("Memory action."),
+        candidate_id: tool.schema.string().optional().describe("Candidate id for promote/reject."),
+        reason: tool.schema.string().optional().describe("Reason for rejection."),
+        scope: tool.schema.enum(["last-prompt", "session", "refs", "safety"]).optional().describe("Audit scope."),
+        status: tool.schema.enum(["pending", "promoted", "rejected"]).optional().describe("Candidate status filter."),
+        confirm: tool.schema.boolean().optional().describe("Must be true for mutate actions."),
+      },
+      async execute(input, context) {
+        const blocked = blockedToolResponse(input as Record<string, unknown>)
+        if (blocked) return blocked
+        if (input.action === "audit") {
+          const events = readJsonl<AkmMemoryEvent>(OPENCODE_EVENT_LOG)
+          const sessionEvents = context.sessionID ? events.filter((event) => event.sessionId === context.sessionID) : events
+          const recall = sessionRecallAudit.get(context.sessionID)
+          const recentWrites = sessionEvents.filter((event) => ["durable_memory_written", "pre_compact_checkpoint", "session_ended"].includes(event.event)).slice(-5)
+          const recentSafetyBlocks = sessionEvents.filter((event) => event.event === "safety_blocked").slice(-5)
+          const refs = [...new Set(sessionEvents.flatMap((event) => event.refs ?? []))]
+          const audit = input.scope === "last-prompt"
+            ? { lastRecall: recall ?? null }
+            : input.scope === "refs"
+              ? { refs }
+              : input.scope === "safety"
+                ? { recentSafetyBlocks }
+                : input.scope === "session"
+                  ? { lastRecall: recall ?? null, recentWrites, recentSafetyBlocks, refs }
+                  : { lastRecall: recall ?? null, recentWrites, recentSafetyBlocks, refs }
+          return JSON.stringify({
+            ok: true,
+            audit,
+          })
+        }
+        if (input.action === "candidates") {
+          const candidates = readCandidates(OPENCODE_CANDIDATE_LOG)
+            .filter((candidate) => !input.status || candidate.status === input.status)
+            .filter((candidate) => !context.sessionID || candidate.sessionId === context.sessionID)
+          return JSON.stringify({ ok: true, candidates })
+        }
+        if (input.action === "checkpoint") {
+          const ref = captureSessionMemory(context.sessionID, "manual-checkpoint", { checkpoint: true })
+          return JSON.stringify({ ok: true, ref })
+        }
+        if (input.action === "sync") {
+          return JSON.stringify({ ok: true, synced: true, events: readJsonl<AkmMemoryEvent>(OPENCODE_EVENT_LOG).length, candidates: readCandidates(OPENCODE_CANDIDATE_LOG).length })
+        }
+        if (!input.candidate_id) return JSON.stringify({ ok: false, error: "'candidate_id' is required for promote/reject." })
+        const candidates = readCandidates(OPENCODE_CANDIDATE_LOG)
+        const candidate = candidates.find((entry) => entry.id === input.candidate_id)
+        if (!candidate) return JSON.stringify({ ok: false, error: `Unknown candidate '${input.candidate_id}'.` })
+        if (input.action === "reject") {
+          const updated = updateCandidateStatus(OPENCODE_CANDIDATE_LOG, candidate.id, "rejected", input.reason)
+          writeStructuredEvent({
+            event: "candidate_rejected",
+            sessionId: context.sessionID,
+            scope: buildEventScope(context.sessionID, context.directory, context.agent),
+            memory: { candidateId: candidate.id, reason: input.reason ?? null },
+            outcome: { status: updated ? "ok" : "failed" },
+          })
+          return JSON.stringify({ ok: !!updated, candidate: updated ?? null })
+        }
+        if (input.action === "promote") {
+          let rawResult: string | null = null
+          if (candidate.recommendedAction === "remember") {
+            rawResult = await runCli(client as unknown as LogCapableClient, ["remember", candidate.content, "--name", `candidate-${candidate.id}`, "--force", ...buildScopedArgs(context as unknown as Record<string, unknown>)], { toolName: "akm_memory", sessionID: context.sessionID, directory: context.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 })
+          } 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 {
+            return JSON.stringify({ ok: false, error: "Candidate recommendedAction is 'ignore'; reject it instead." })
+          }
+          const parsedResult = rawResult ? parseMaybeJson(rawResult) : null
+          const resultOk = typeof parsedResult === "object" && parsedResult !== null && "ok" in parsedResult
+            ? parsedResult.ok !== false
+            : !!rawResult
+          if (!resultOk) {
+            writeStructuredEvent({
+              event: "candidate_promoted",
+              sessionId: context.sessionID,
+              scope: buildEventScope(context.sessionID, context.directory, context.agent),
+              memory: { candidateId: candidate.id, recommendedAction: candidate.recommendedAction },
+              outcome: { status: "failed", warnings: ["candidate promotion command did not succeed"] },
+            })
+            return JSON.stringify({ ok: false, candidate, result: parsedResult ?? rawResult })
+          }
+          const updated = updateCandidateStatus(OPENCODE_CANDIDATE_LOG, candidate.id, "promoted")
+          writeStructuredEvent({
+            event: "candidate_promoted",
+            sessionId: context.sessionID,
+            scope: buildEventScope(context.sessionID, context.directory, context.agent),
+            memory: { candidateId: candidate.id, recommendedAction: candidate.recommendedAction },
+            outcome: { status: updated ? "ok" : "failed" },
+          })
+          return JSON.stringify({ ok: !!updated, candidate: updated ?? null, result: parsedResult ?? rawResult })
+        }
+        return JSON.stringify({ ok: false, error: `Unsupported action '${String(input.action)}'.` })
+      },
+    }),
     akm_curate: tool({
       description: "Curate stash assets for a task or topic. Returns the top matches as a ranked list so the agent can inspect and use them.",
       args: {
@@ -2744,6 +3114,24 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         const model = parseModelHint(shown.modelHint)
         const tools = parseToolPolicy(shown.toolPolicy)
 
+        writeStructuredEvent({
+          event: "subagent_started",
+          sessionId: context.sessionID,
+          scope: buildEventScope(context.sessionID, context.directory, context.agent),
+          input: {
+            ref: resolved.ref,
+            stashAgent: shown.name,
+            dispatchAgent: targetAgent,
+            taskPrompt: task_prompt,
+            advisoryToolPolicy: shown.toolPolicy ?? null,
+            appliedToolPolicy: tools ?? null,
+            modelHint: shown.modelHint ?? null,
+            appliedModel: model ?? null,
+          },
+          refs: [resolved.ref],
+          outcome: { status: "ok" },
+        })
+
         const targetSession = await ensureTargetSessionID({
           useSubtask,
           context: { sessionID: context.sessionID, directory: context.directory },
@@ -2774,6 +3162,19 @@ 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] })
+        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 },
+          memory: { parentSessionID: context.sessionID, childSessionID: targetSession.sessionID, candidatesCreated: candidates.length },
+          refs: [resolved.ref],
+          outcome: { status: "ok" },
+        })
+
         return JSON.stringify({
           ok: true,
           ref: resolved.ref,
@@ -2783,7 +3184,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           sessionID: targetSession.sessionID,
           model,
           tools,
-          text: extractText(promptResponse.data.parts),
+          text: childText,
         })
       },
     }),
@@ -2916,6 +3317,13 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
               })
               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",
+                ref,
+                error: formatCliError(error),
+              })
               return JSON.stringify({ ok: false, error: formatCliError(error) })
             }
           }
@@ -3023,6 +3431,15 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
                 })
                 return stdout
               } catch (error: unknown) {
+                await writePluginLog(logClient, "error", "AKM wiki stash failed", {
+                  subsystem: "wiki",
+                  toolName: "akm_wiki",
+                  action: "stash",
+                  name,
+                  source,
+                  as_slug,
+                  error: formatCliError(error),
+                })
                 return JSON.stringify({ ok: false, error: formatCliError(error) })
               }
             }
@@ -3082,14 +3499,18 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             if (!ref) return JSON.stringify({ ok: false, error: "'ref' is required for action='start'." })
             const args = ["workflow", "start", ref]
             if (params) args.push("--params", params)
-            return runCli(client as unknown as LogCapableClient, args, logMeta)
+            const raw = await runCli(client as unknown as LogCapableClient, args, logMeta)
+            void emitWorkflowTelemetry(logClient, "info", "workflow_started", { toolName: "akm_workflow", ref, params: params ?? null })
+            return raw
           }
           case "next": {
             const picked = target ?? run_id ?? ref
             if (!picked) return JSON.stringify({ ok: false, error: "'target', 'run_id', or 'ref' is required for action='next'." })
             const args = ["workflow", "next", picked]
             if (params) args.push("--params", params)
-            return runCli(client as unknown as LogCapableClient, args, logMeta)
+            const raw = await runCli(client as unknown as LogCapableClient, args, logMeta)
+            void emitWorkflowTelemetry(logClient, "info", "workflow_next_loaded", { toolName: "akm_workflow", target: picked, params: params ?? null })
+            return raw
           }
           case "complete": {
             if (!run_id) return JSON.stringify({ ok: false, error: "'run_id' is required for action='complete'." })
@@ -3098,7 +3519,16 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             if (state) args.push("--state", state)
             if (notes) args.push("--notes", notes)
             if (evidence) args.push("--evidence", evidence)
-            return runCli(client as unknown as LogCapableClient, args, logMeta)
+            const raw = await runCli(client as unknown as LogCapableClient, args, logMeta)
+            const eventType = state === "blocked"
+              ? "workflow_step_blocked"
+              : state === "failed"
+                ? "workflow_step_failed"
+                : state === "skipped"
+                  ? "workflow_step_skipped"
+                  : "workflow_step_completed"
+            void emitWorkflowTelemetry(logClient, "info", eventType, { toolName: "akm_workflow", runId: run_id, step, notes: notes ?? null, evidence: evidence ?? null })
+            return raw
           }
           case "status": {
             const picked = target ?? run_id ?? ref
@@ -3130,12 +3560,20 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
               })
               return JSON.stringify({ ok: true, template: stdout })
             } catch (error: unknown) {
+              await writePluginLog(logClient, "error", "AKM workflow template failed", {
+                subsystem: "workflow",
+                toolName: "akm_workflow",
+                action: "template",
+                error: formatCliError(error),
+              })
               return JSON.stringify({ ok: false, error: formatCliError(error) })
             }
           }
           case "resume": {
             if (!run_id) return JSON.stringify({ ok: false, error: "'run_id' is required for action='resume'." })
-            return runCli(client as unknown as LogCapableClient, ["workflow", "resume", run_id], logMeta)
+            const raw = await runCli(client as unknown as LogCapableClient, ["workflow", "resume", run_id], logMeta)
+            void emitWorkflowTelemetry(logClient, "info", "workflow_resumed", { toolName: "akm_workflow", runId: run_id })
+            return raw
           }
         }
       },
@@ -3212,15 +3650,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         return runCli(client as unknown as LogCapableClient, ["distill", ref], { toolName: "akm_distill" })
       },
     }),
-    akm_setup: tool({
-      description: "Detect installed agent CLIs (opencode, claude, codex, gemini, aider) and persist `agent.default`. Required once per machine before akm_reflect / akm_propose can shell out. Idempotent — pass force=true to re-run detection even when agent.default is already set.",
-      args: {
-        force: tool.schema.boolean().optional().describe("Re-run detection even when agent.default is already configured."),
-      },
-      async execute({ force }) {
-        const args = ["setup"]
-        if (force) args.push("--force")
-        return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_setup" })
+    akm_init: tool({
+      description: "Initialize AKM's working stash directory and persist `stashDir` in config. This is the agent-safe initialization path; do not use interactive `akm setup` from tools.",
+      args: {},
+      async execute() {
+        return runCli(client as unknown as LogCapableClient, ["init"], { toolName: "akm_init" })
       },
     }),
     akm_help: tool({
@@ -3242,6 +3676,13 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             timeout: 30_000,
           }).toString().trim()
         } catch (error: unknown) {
+          await writePluginLog(logClient, "error", "AKM help command failed", {
+            subsystem: "help",
+            toolName: "akm_help",
+            command: cliCommand,
+            args: helpArgs,
+            error: formatCliError(error),
+          })
           return JSON.stringify({ ok: false, error: formatCliError(error) })
         }
         return JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-opencode",
-  "version": "0.7.2",
+  "version": "0.7.5",
   "type": "module",
   "description": "OpenCode plugin for AKM v0.7.0 - search, show, and manage extension assets via the akm CLI, including vaults, wikis, workflows, the proposal queue, lesson assets, and reflect/propose/distill commands, with agentic hooks that auto-load relevant stash assets, record feedback, and harvest session memories so the stash improves every session.",
   "keywords": [