akm-opencode 0.7.1 → 0.7.3

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

@@ -53,6 +53,7 @@ const sessionSuccessfulAssetTouchCount = new Map<string, number>()
 const pendingProposalSummaryCache = new Map<string, { count: number; expiresAt: number; unsupported?: boolean }>()
 const retrospectiveState = new Map<string, { recentRefs: string[]; lastNegativeSignalAt?: number }>()
 let cachedAkmStashDir: string | undefined
+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
@@ -70,7 +71,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")
@@ -218,6 +219,93 @@ function formatCliError(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+function needsAgentSetup(message: string): boolean {
+  return /(agent commands are disabled|agent not configured|no [`'"]?agent[`'"]? block in config\.json)/i.test(message)
+}
+
+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.`
+}
+
+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 default check skipped", {
+      subsystem: "akm",
+      trigger: meta.trigger,
+      sessionID: meta.sessionID,
+      directory: meta.directory,
+      error: command.error,
+    })
+    return false
+  }
+
+  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()
+            : ""
+        : ""
+    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,
+      agentDefault: meta.platform,
+    })
+    return true
+  } catch (error: unknown) {
+    await writePluginLog(client, "warn", "AKM agent default initialization failed", {
+      subsystem: "akm",
+      trigger: meta.trigger,
+      sessionID: meta.sessionID,
+      directory: meta.directory,
+      platform: meta.platform,
+      error: addAgentSetupGuidance(formatCliError(error)),
+      stdout: toLogString((error as { stdout?: unknown }).stdout) ?? "",
+      stderr: toLogString((error as { stderr?: unknown }).stderr) ?? "",
+    })
+    return false
+  }
+}
+
+async function ensureAgentSetup(
+  client: LogCapableClient,
+  meta: { directory?: string; sessionID?: string; trigger: string; platform: string },
+): Promise<boolean> {
+  if (agentSetupPromise) return agentSetupPromise
+  const promise = ensurePlatformAgentDefault(client, meta)
+  const trackedPromise = promise.finally(() => {
+    if (agentSetupPromise === trackedPromise) agentSetupPromise = null
+  })
+  agentSetupPromise = trackedPromise
+  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")
@@ -246,6 +334,20 @@ async function writePluginLog(client: LogCapableClient, level: LogLevel, message
   }
 }
 
+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()
 }
@@ -347,9 +449,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",
@@ -364,11 +477,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",
@@ -382,14 +496,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 {
@@ -423,10 +540,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
@@ -463,14 +585,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
@@ -484,7 +612,6 @@ function getAkmStashDir(): string | undefined {
       }
     }
   }
-  const raw = result.stdout.trim()
   cachedAkmStashDir = raw || ""
   return cachedAkmStashDir || undefined
 }
@@ -518,6 +645,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: [] }
@@ -575,7 +725,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",
@@ -678,6 +828,21 @@ function queueFeedback(
         stdio: "ignore",
       },
     )
+    child.on("exit", (code, signal) => {
+      if ((typeof code === "number" && code !== 0) || signal) {
+        void writePluginLog(client, "warn", "AKM auto-feedback failed", {
+          subsystem: "feedback",
+          toolName: meta.toolName,
+          sessionID: meta.sessionID,
+          directory: meta.directory,
+          ref,
+          sentiment,
+          error: signal
+            ? `akm feedback exited via signal ${signal}`
+            : `akm feedback exited with code ${code}`,
+        })
+      }
+    })
     child.on("error", (error) => {
       void writePluginLog(client, "warn", "AKM auto-feedback failed", {
         subsystem: "feedback",
@@ -1314,11 +1479,7 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
   const fullArgs = args.includes("--format") ? [...args] : [...args, "--format", "json"]
   const proposalId = args[0] === "proposal" && typeof args[2] === "string" ? args[2] : null
 
-  try {
-    const stdout = execFileSync(command, fullArgs, {
-      encoding: "utf8",
-      timeout: 60_000,
-    })
+  const recordSuccess = async (stdout: string): Promise<string> => {
     await writePluginLog(client, "info", "AKM command completed", {
       subsystem: "akm",
       toolName: meta.toolName,
@@ -1384,8 +1545,20 @@ async function runCli(client: LogCapableClient, args: string[], meta: CliLogMeta
       })
     }
     return stdout
+  }
+
+  try {
+    const stdout = execFileSync(command, fullArgs, {
+      encoding: "utf8",
+      timeout: 60_000,
+    })
+    return recordSuccess(stdout)
   } catch (error: unknown) {
-    const message = formatCliError(error)
+    let message = formatCliError(error)
+    if (["akm_reflect", "akm_propose"].includes(meta.toolName) && needsAgentSetup(message)) {
+      message = addAgentSetupGuidance(message)
+    }
+    message = addAgentSetupGuidance(message)
     await writePluginLog(client, "error", "AKM command failed", {
       subsystem: "akm",
       toolName: meta.toolName,
@@ -1980,9 +2153,15 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           if (!sid) return
           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)
@@ -1990,11 +2169,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) {
@@ -2029,8 +2208,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
@@ -2051,8 +2230,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
@@ -2091,8 +2270,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) => {
@@ -2108,8 +2287,11 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
           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) => {
@@ -2137,8 +2319,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) => {
@@ -2155,154 +2340,180 @@ 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) => {
-      const text = extractText(output.parts).trim()
-      if (!text) return
-      await writePluginLog(logClient, "info", "AKM user feedback recorded", {
-        subsystem: "feedback",
-        actor: "user",
-        sessionID: input.sessionID,
-        messageID: input.messageID,
-        agent: input.agent,
-        text: truncateLogText(text),
-      })
+      try {
+        const text = extractText(output.parts).trim()
+        if (!text) return
+        await writePluginLog(logClient, "info", "AKM user feedback recorded", {
+          subsystem: "feedback",
+          actor: "user",
+          sessionID: input.sessionID,
+          messageID: input.messageID,
+          agent: input.agent,
+          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)
+        // Session-start curation already seeded context. On later user messages,
+        // inject only a small reminder instead of firing more automatic AKM CLI calls.
+        if (AKM_AUTO_CURATE && input.sessionID) {
+          const hint = "Need more AKM context? Use `akm_search` or `akm_curate` before writing from scratch."
+          const current = sessionCurated.get(input.sessionID) ?? ""
+          if (!current.includes(hint)) {
+            sessionCurated.set(input.sessionID, current ? `${current}\n\n${hint}` : hint)
+            bumpCuratedVersion(input.sessionID)
+          }
         }
-      }
 
-      // Track explicit memory intents so capture-memory has something durable
-      // to flush when the session ends.
-      if (/\b(remember|memory|memories)\b/i.test(text)) {
-        addBufferEntry(input.sessionID, {
-          kind: "memory-intent",
-          note: truncateLogText(text, 500),
-        })
-      }
+        // Track explicit memory intents so capture-memory has something durable
+        // to flush when the session ends.
+        if (/\b(remember|memory|memories)\b/i.test(text)) {
+          addBufferEntry(input.sessionID, {
+            kind: "memory-intent",
+            note: truncateLogText(text, 500),
+          })
+        }
 
-      if (input.sessionID && AKM_AUTO_FEEDBACK && AKM_RETROSPECTIVE_FEEDBACK_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)
-          .slice(-3)
-        const dedupe = new Set<string>()
-        for (const ref of recentRefs) {
-          queueFeedback(logClient, ref, "positive", "opencode retrospective: user confirmed it worked", {
-            toolName: "chat.message",
-            sessionID: input.sessionID,
-          }, dedupe)
+        if (input.sessionID && AKM_AUTO_FEEDBACK && AKM_RETROSPECTIVE_FEEDBACK_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)
+            .slice(-3)
+          const dedupe = new Set<string>()
+          for (const ref of recentRefs) {
+            queueFeedback(logClient, ref, "positive", "opencode retrospective: user confirmed it worked", {
+              toolName: "chat.message",
+              sessionID: input.sessionID,
+            }, dedupe)
+          }
         }
+        await recordRetrospectiveFeedback(logClient, input.sessionID, text)
+      } catch (error: unknown) {
+        await writePluginLog(logClient, "error", "AKM chat.message hook failed", {
+          subsystem: "hook",
+          hook: "chat.message",
+          sessionID: input?.sessionID,
+          messageID: input?.messageID,
+          agent: input?.agent,
+          error: formatCliError(error),
+        })
       }
-      await recordRetrospectiveFeedback(logClient, input.sessionID, text)
     },
     "tool.execute.after": async (input, output) => {
-      if (!input.tool.startsWith("akm_")) return
+      try {
+        if (!input.tool.startsWith("akm_")) return
 
-      const parsed = parseToolOutput(output.output)
-      if (!parsed) return
+        const parsed = parseToolOutput(output.output)
+        if (!parsed) return
 
-      const feedback = classifyToolFeedback(parsed)
-      if (feedback) {
-        await writePluginLog(logClient, feedback === "negative" ? "warn" : "info", "AKM system feedback recorded", {
-          subsystem: "feedback",
-          actor: "system",
-          feedback,
-          toolName: input.tool,
-          sessionID: input.sessionID,
-          callID: input.callID,
-          title: output.title,
-          error: typeof (parsed as { error?: unknown }).error === "string" ? (parsed as { error?: string }).error : undefined,
-        })
-      }
+        const feedback = classifyToolFeedback(parsed)
+        if (feedback) {
+          await writePluginLog(logClient, feedback === "negative" ? "warn" : "info", "AKM system feedback recorded", {
+            subsystem: "feedback",
+            actor: "system",
+            feedback,
+            toolName: input.tool,
+            sessionID: input.sessionID,
+            callID: input.callID,
+            title: output.title,
+            error: typeof (parsed as { error?: unknown }).error === "string" ? (parsed as { error?: string }).error : undefined,
+          })
+        }
 
-      const memoryRefs = extractMemoryRefs(input.tool, input.args as Record<string, unknown>, parsed)
-      if (memoryRefs.length > 0) {
-        await writePluginLog(logClient, "info", "AKM memory usage recorded", {
-          subsystem: "memory",
-          toolName: input.tool,
-          sessionID: input.sessionID,
-          callID: input.callID,
-          refs: memoryRefs,
-        })
-      }
+        const memoryRefs = extractMemoryRefs(input.tool, input.args as Record<string, unknown>, parsed)
+        if (memoryRefs.length > 0) {
+          await writePluginLog(logClient, "info", "AKM memory usage recorded", {
+            subsystem: "memory",
+            toolName: input.tool,
+            sessionID: input.sessionID,
+            callID: input.callID,
+            refs: memoryRefs,
+          })
+        }
 
-      // 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.
+        // 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)
         if (refResult.refs.length > 0 && input.sessionID) {
-        for (const ref of refResult.refs) {
-          addBufferEntry(input.sessionID, {
-            kind: "tool-ref",
-            toolName: input.tool,
-            ref,
-            status: feedback ?? "unknown",
-          })
-        }
-        if (feedback === "positive") {
-          sessionSuccessfulAssetTouchCount.set(
-            input.sessionID,
-            (sessionSuccessfulAssetTouchCount.get(input.sessionID) ?? 0) + 1,
-          )
-          const checkpointRef = maybeCheckpointSessionMemory(input.sessionID)
-          if (checkpointRef) {
-            await writePluginLog(logClient, "info", "AKM checkpoint memory captured", {
-              subsystem: "memory",
-              actor: "system",
-              sessionID: input.sessionID,
-              reason: "checkpoint",
-              ref: checkpointRef,
+          for (const ref of refResult.refs) {
+            addBufferEntry(input.sessionID, {
+              kind: "tool-ref",
+              toolName: input.tool,
+              ref,
+              status: feedback ?? "unknown",
             })
           }
+          if (feedback === "positive") {
+            sessionSuccessfulAssetTouchCount.set(
+              input.sessionID,
+              (sessionSuccessfulAssetTouchCount.get(input.sessionID) ?? 0) + 1,
+            )
+            const checkpointRef = maybeCheckpointSessionMemory(input.sessionID)
+            if (checkpointRef) {
+              await writePluginLog(logClient, "info", "AKM checkpoint memory captured", {
+                subsystem: "memory",
+                actor: "system",
+                sessionID: input.sessionID,
+                reason: "checkpoint",
+                ref: checkpointRef,
+              })
+            }
+          }
         }
-      }
 
-      if (
-        AKM_AUTO_FEEDBACK
-        && feedback
-        && input.tool !== "akm_feedback"
-        && refResult.refs.length > 0
-      ) {
-        const dedupe = new Set<string>()
-        const feedbackRefs = feedback === "positive"
-          ? refResult.refs
-          : refResult.refs.filter((ref) => !refResult.positiveOnlyRefs.includes(ref))
-        const note = feedback === "positive"
-          ? `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
-          const ok = queueFeedback(logClient, ref, feedback, note, {
-            toolName: input.tool,
-            sessionID: input.sessionID,
-          }, dedupe)
-          if (!ok) break
+        if (
+          AKM_AUTO_FEEDBACK
+          && feedback
+          && input.tool !== "akm_feedback"
+          && refResult.refs.length > 0
+        ) {
+          const dedupe = new Set<string>()
+          const feedbackRefs = feedback === "positive"
+            ? refResult.refs
+            : refResult.refs.filter((ref) => !refResult.positiveOnlyRefs.includes(ref))
+          const note = feedback === "positive"
+            ? `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
+            const ok = queueFeedback(logClient, ref, feedback, note, {
+              toolName: input.tool,
+              sessionID: input.sessionID,
+            }, dedupe)
+            if (!ok) break
+          }
         }
+      } catch (error: unknown) {
+        await writePluginLog(logClient, "error", "AKM tool.execute.after hook failed", {
+          subsystem: "hook",
+          hook: "tool.execute.after",
+          toolName: input?.tool,
+          sessionID: input?.sessionID,
+          callID: input?.callID,
+          error: formatCliError(error),
+        })
       }
     },
     tool: {
@@ -2393,6 +2604,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",
@@ -2482,16 +2719,27 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
       description: "Read compact text summaries of the parent session's messages so a dispatched AKM subagent can inherit upstream context.",
       args: {},
       async execute(_input, context) {
-        const parent = await getParentSessionID(sdkClient, context.sessionID, context.directory)
-        if (!parent.ok) return JSON.stringify(parent)
-        const messages = await sdkClient.session.messages({
-          path: { id: parent.parentID },
-          query: { directory: context.directory },
-        })
-        if (messages.error || !messages.data) {
+        try {
+          const parent = await getParentSessionID(sdkClient, context.sessionID, context.directory)
+          if (!parent.ok) return JSON.stringify(parent)
+          const messages = await sdkClient.session.messages({
+            path: { id: parent.parentID },
+            query: { directory: context.directory },
+          })
+          if (messages.error || !messages.data) {
+            return JSON.stringify({ ok: false, error: "Failed to read parent session messages." })
+          }
+          return JSON.stringify(summarizeSessionMessages(parent.parentID, messages.data))
+        } catch (error: unknown) {
+          await writePluginLog(logClient, "error", "AKM parent session read failed", {
+            subsystem: "session",
+            toolName: "akm_parent_messages",
+            sessionID: context.sessionID,
+            directory: context.directory,
+            error: formatCliError(error),
+          })
           return JSON.stringify({ ok: false, error: "Failed to read parent session messages." })
         }
-        return JSON.stringify(summarizeSessionMessages(parent.parentID, messages.data))
       },
     }),
     akm_session_messages: tool({
@@ -2500,23 +2748,35 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         session_id: tool.schema.string().describe("OpenCode session ID to inspect."),
       },
       async execute({ session_id }, context) {
-        const parent = await getParentSessionID(sdkClient, context.sessionID, context.directory)
-        const allowedSessionIDs = new Set<string>([context.sessionID])
-        if (parent.ok) allowedSessionIDs.add(parent.parentID)
-        if (context.agent !== "akm-curator" && !allowedSessionIDs.has(session_id)) {
-          return JSON.stringify({
-            ok: false,
-            error: "akm_session_messages only allows arbitrary session IDs for the akm-curator agent. Use akm_parent_messages for parent context.",
+        try {
+          const parent = await getParentSessionID(sdkClient, context.sessionID, context.directory)
+          const allowedSessionIDs = new Set<string>([context.sessionID])
+          if (parent.ok) allowedSessionIDs.add(parent.parentID)
+          if (context.agent !== "akm-curator" && !allowedSessionIDs.has(session_id)) {
+            return JSON.stringify({
+              ok: false,
+              error: "akm_session_messages only allows arbitrary session IDs for the akm-curator agent. Use akm_parent_messages for parent context.",
+            })
+          }
+          const messages = await sdkClient.session.messages({
+            path: { id: session_id },
+            query: { directory: context.directory },
+          })
+          if (messages.error || !messages.data) {
+            return JSON.stringify({ ok: false, error: `Failed to read messages for session '${session_id}'.` })
+          }
+          return JSON.stringify(summarizeSessionMessages(session_id, messages.data))
+        } catch (error: unknown) {
+          await writePluginLog(logClient, "error", "AKM session messages read failed", {
+            subsystem: "session",
+            toolName: "akm_session_messages",
+            sessionID: context.sessionID,
+            directory: context.directory,
+            targetSessionID: session_id,
+            error: formatCliError(error),
           })
-        }
-        const messages = await sdkClient.session.messages({
-          path: { id: session_id },
-          query: { directory: context.directory },
-        })
-        if (messages.error || !messages.data) {
           return JSON.stringify({ ok: false, error: `Failed to read messages for session '${session_id}'.` })
         }
-        return JSON.stringify(summarizeSessionMessages(session_id, messages.data))
       },
     }),
     akm_agent: tool({
@@ -2734,6 +2994,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) })
             }
           }
@@ -2841,6 +3108,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) })
               }
             }
@@ -2948,6 +3224,12 @@ 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) })
             }
           }
@@ -3030,15 +3312,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({
@@ -3060,6 +3338,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.1",
+  "version": "0.7.3",
   "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": [