@gianfrancopiana/openclaw-autoresearch 1.0.5 → 1.0.7

package/README.md

@@ -16,7 +16,7 @@ Three tools drive the loop:
 | `run_experiment` | Executes a shell command, times it, captures stdout/stderr, parses `METRIC name=number` lines, and opens a pending experiment window that must be logged before another run can start. |
 | `log_experiment` | Records the pending run. The first logged run in a segment is tagged as the baseline automatically. `keep` auto-commits to git. `discard`/`crash` log without committing, and `discard` now requires an `idea` note that is appended to `autoresearch.ideas.md`. If the prior `run_experiment` captured the primary metric, `log_experiment` can infer `commit` and `metric` automatically. After 3+ runs in a segment, it also reports a confidence score for the best improvement versus noise. |
 
-Each tool also accepts an optional `cwd` so callers can target a nested repo explicitly instead of relying on the current session working directory.
+In OpenClaw sessions, the plugin uses the host-provided `workspaceDir` as the normal repo root. Each tool also accepts an optional `cwd` so callers can explicitly target a nested or non-session repo when needed.
 
 All state lives in six repo-root files:
 
@@ -33,7 +33,8 @@ The design is file-first: any agent can pick up the repo-root files and continue
 
 ## Install
 
-Requires OpenClaw `2026.3.13` or newer.
+Requires OpenClaw `2026.4.25` or newer.
+Needs bash, git, and a git repo.
 
 Use OpenClaw's plugin installer:
 
@@ -63,12 +64,15 @@ npm pack
 openclaw plugins install ./gianfrancopiana-openclaw-autoresearch-<version>.tgz
 ```
 
-The install command records the plugin, enables it, and exposes the plugin surfaces on restart. The installer reads `package.json#openclaw.extensions`, loads the root [`index.ts`](index.ts), and discovers the manifest in [`openclaw.plugin.json`](openclaw.plugin.json).
+The install command records the plugin, enables it, and makes it available
+after restart. OpenClaw reads the package metadata, loads the root
+[`index.ts`](index.ts), and finds the manifest in
+[`openclaw.plugin.json`](openclaw.plugin.json).
 
 Verify:
 
 - skill: `autoresearch-create`
-- tools: `init_experiment`, `run_experiment`, `log_experiment`
+- tools: `init_experiment`, `run_experiment`, `log_experiment`, `autoresearch_status`
 - command: `/autoresearch` (recommended)
 - direct skill fallback: `/skill autoresearch-create`
 
@@ -119,15 +123,17 @@ This port preserves upstream semantics, names, and file contracts while adapting
 
 ```bash
 npm install --include=dev
+npm run check:release-metadata
 npm run typecheck
 npm test
 npm run validate
 npm run release:verify
+npm run smoke:openclaw-host -- /absolute/path/to/openclaw
 ```
 
 Release instructions, including npm 2FA publishing, live in [`RELEASING.md`](RELEASING.md).
 
-The local test shim supports typechecking and tests without a full OpenClaw host checkout. Runtime behavior depends on a real OpenClaw host.
+The local test shim supports typechecking and tests without a full OpenClaw host checkout. Runtime behavior depends on a real OpenClaw host, so run the host smoke against a current checkout before release.
 
 ## License
 

package/RELEASING.md

@@ -7,7 +7,15 @@
 
 ## Release
 
-1. Update `package.json` and `openclaw.plugin.json` if you are changing the version.
+1. Update the package version in `package.json`, then sync generated metadata:
+
+   ```bash
+   npm run sync:release-metadata
+   ```
+
+   If you change the minimum supported OpenClaw version, keep
+   `openclaw.install`, `openclaw.compat`, and `openclaw.build` aligned too.
+
 2. Run the release checks:
 
    ```bash
@@ -15,7 +23,16 @@
    npm run release:verify
    ```
 
-3. Publish:
+   CI runs the same release verification, so metadata drift should fail before
+   publish.
+
+3. Smoke-test against a current local OpenClaw checkout:
+
+   ```bash
+   npm run smoke:openclaw-host -- /absolute/path/to/openclaw
+   ```
+
+4. Publish:
 
    ```bash
    npm publish --otp=123456
@@ -23,7 +40,7 @@
 
    Replace `123456` with the current code from your authenticator app.
 
-4. Verify install:
+5. Verify install:
 
    ```bash
    openclaw plugins install @gianfrancopiana/openclaw-autoresearch

package/extensions/openclaw-autoresearch/index.ts

@@ -1,9 +1,12 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  definePluginEntry,
+  type OpenClawPluginApi,
+  type OpenClawPluginToolContext,
+} from "openclaw/plugin-sdk/core";
 import {
   AUTORESEARCH_PLUGIN_DESCRIPTION,
   AUTORESEARCH_PLUGIN_ID,
   AUTORESEARCH_PLUGIN_NAME,
-  autoresearchPluginConfigSchema,
 } from "./src/config.js";
 import { createInitExperimentTool } from "./src/tools/init-experiment.js";
 import { createRunExperimentTool } from "./src/tools/run-experiment.js";
@@ -12,19 +15,43 @@ import { createAutoresearchStatusTool } from "./src/tools/autoresearch-status.js
 import { registerAutoresearchHooks } from "./src/hooks.js";
 import { registerAutoresearchCommand } from "./src/commands/autoresearch.js";
 
-const plugin = {
+function createToolFactory<TTool>(
+  createTool: (
+    api: OpenClawPluginApi,
+    toolContext?: Pick<OpenClawPluginToolContext, "sessionKey" | "sessionId" | "workspaceDir">,
+  ) => TTool,
+  api: OpenClawPluginApi,
+) {
+  return (toolContext: OpenClawPluginToolContext) => createTool(api, toolContext);
+}
+
+function registerRequiredTool<TTool>(
+  api: OpenClawPluginApi,
+  name: string,
+  createTool: (
+    api: OpenClawPluginApi,
+    toolContext?: Pick<OpenClawPluginToolContext, "sessionKey" | "sessionId" | "workspaceDir">,
+  ) => TTool,
+) {
+  api.registerTool(
+    createToolFactory(createTool, api) as Parameters<OpenClawPluginApi["registerTool"]>[0],
+    {
+      name,
+      optional: false,
+    },
+  );
+}
+
+export default definePluginEntry({
   id: AUTORESEARCH_PLUGIN_ID,
   name: AUTORESEARCH_PLUGIN_NAME,
   description: AUTORESEARCH_PLUGIN_DESCRIPTION,
-  configSchema: autoresearchPluginConfigSchema,
   register(api: OpenClawPluginApi) {
     registerAutoresearchHooks(api);
     registerAutoresearchCommand(api);
-    api.registerTool(createInitExperimentTool(api));
-    api.registerTool(createRunExperimentTool(api));
-    api.registerTool(createLogExperimentTool(api));
-    api.registerTool(createAutoresearchStatusTool(api));
+    registerRequiredTool(api, "init_experiment", createInitExperimentTool);
+    registerRequiredTool(api, "run_experiment", createRunExperimentTool);
+    registerRequiredTool(api, "log_experiment", createLogExperimentTool);
+    registerRequiredTool(api, "autoresearch_status", createAutoresearchStatusTool);
   },
-};
-
-export default plugin;
+});

package/extensions/openclaw-autoresearch/src/commands/autoresearch.ts

@@ -1,5 +1,5 @@
 import * as fs from "node:fs";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import {
   AUTORESEARCH_ROOT_FILES,
   getAutoresearchRootFilePath,
@@ -8,10 +8,9 @@ import {
 import { reconstructStateFromJsonl } from "../state.js";
 import { formatAutoresearchStatusText } from "../tools/autoresearch-status.js";
 import {
-  clearAutoresearchSteers,
+  clearAutoresearchRuntimeState,
   getAutoresearchRuntimeState,
   setAutoresearchPendingCommand,
-  setAutoresearchRunInFlight,
   setAutoresearchRuntimeMode,
 } from "../runtime-state.js";
 import {
@@ -19,11 +18,16 @@ import {
   getAutoresearchSessionLockStatus,
   removeAutoresearchSessionLock,
 } from "../session-lock.js";
+import { type AutoresearchScopeRef, resolveAutoresearchScope } from "../scope.js";
 
 type CommandContext = {
   args?: string;
   channel?: string;
   senderId?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  workspaceDir?: string;
+  runId?: string;
   cwd?: string;
 };
 
@@ -45,7 +49,7 @@ export function registerAutoresearchCommand(api: OpenClawPluginApi): void {
     description: "Enable, disable, or inspect repo-root autoresearch mode.",
     acceptsArgs: true,
     handler: (ctx: CommandContext) => {
-      const cwd = resolveCommandCwd(api, ctx);
+      const scope = resolveCommandScope(ctx);
       const rawArgs = (ctx.args ?? "").trim();
       const [verb, ...rest] = rawArgs.split(/\s+/).filter(Boolean);
       const action = (verb ?? "").toLowerCase();
@@ -53,18 +57,19 @@ export function registerAutoresearchCommand(api: OpenClawPluginApi): void {
 
       if (!rawArgs || action === "resume" || action === "on") {
         return {
-          text: enableAutoresearchMode(cwd, rawArgs && action !== "resume" && action !== "on" ? rawArgs : remainder),
+          text: enableAutoresearchMode(
+            scope,
+            rawArgs && action !== "resume" && action !== "on" ? rawArgs : remainder,
+          ),
         };
       }
       if (action === "setup") {
-        return { text: primeAutoresearchSetup(cwd, remainder) };
+        return { text: primeAutoresearchSetup(scope, remainder) };
       }
       if (action === "off") {
-        setAutoresearchRuntimeMode(cwd, "off");
-        setAutoresearchPendingCommand(cwd, null);
-        clearAutoresearchSteers(cwd);
-        setAutoresearchRunInFlight(cwd, false);
-        removeAutoresearchSessionLock(cwd);
+        clearAutoresearchRuntimeState(scope);
+        setAutoresearchRuntimeMode(scope, "off");
+        removeAutoresearchSessionLock(scope);
         return {
           text: [
             "Autoresearch mode OFF.",
@@ -73,30 +78,35 @@ export function registerAutoresearchCommand(api: OpenClawPluginApi): void {
         };
       }
       if (action === "status") {
-        return { text: buildAutoresearchCommandText(cwd, "status") };
+        return { text: buildAutoresearchCommandText(scope, "status") };
       }
       if (action === "help") {
-        return { text: `${COMMAND_USAGE}\n\n${buildAutoresearchCommandText(cwd, "default")}` };
+        return { text: `${COMMAND_USAGE}\n\n${buildAutoresearchCommandText(scope, "default")}` };
       }
 
       return {
-        text: enableAutoresearchMode(cwd, rawArgs),
+        text: enableAutoresearchMode(scope, rawArgs),
       };
     },
   });
 }
 
 export function buildAutoresearchCommandText(
-  cwd: string,
+  scopeRef: AutoresearchScopeRef,
   mode: "default" | "status",
 ): string {
-  const runtimeState = getAutoresearchRuntimeState(cwd);
-  const presentFiles = getPresentCanonicalFiles(cwd);
+  const scope = resolveAutoresearchScope(scopeRef);
+  const runtimeState = getAutoresearchRuntimeState(scopeRef);
+  if (!scope.repoDir) {
+    return buildWorkspacePendingCommandText(runtimeState);
+  }
+
+  const presentFiles = getPresentCanonicalFiles(scope.repoDir);
   const presentSessionFiles = presentFiles.filter(
     (file) => file !== AUTORESEARCH_ROOT_FILES.sessionLock,
   );
   const hasSession = presentSessionFiles.length > 0;
-  const lockStatus = getAutoresearchSessionLockStatus(cwd);
+  const lockStatus = getAutoresearchSessionLockStatus(scope);
 
   if (!hasSession) {
     return [
@@ -109,14 +119,18 @@ export function buildAutoresearchCommandText(
     ].join("\n");
   }
 
-  const state = reconstructStateFromJsonl(cwd);
+  const state = reconstructStateFromJsonl(scope.repoDir);
   const lines = [
     `Autoresearch session detected at repo root: ${presentFiles.join(", ")}`,
     `Read \`${AUTORESEARCH_ROOT_FILES.sessionDoc}\` before resuming or changing the loop.`,
   ];
 
   if (mode === "status") {
-    lines.push("", formatAutoresearchStatusText(state, runtimeState), `Session lock: ${formatLockStatus(lockStatus)}`);
+    lines.push(
+      "",
+      formatAutoresearchStatusText(state, runtimeState),
+      `Session lock: ${formatLockStatus(lockStatus)}`,
+    );
   } else if (state.mode === "active" || state.hasSessionDoc) {
     lines.push(
       "Use `/autoresearch` or `/autoresearch on` to enable mode for the next agent turn, then continue the upstream loop with `init_experiment`, `run_experiment`, and `log_experiment` as needed.",
@@ -130,25 +144,47 @@ export function buildAutoresearchCommandText(
   return lines.join("\n");
 }
 
-function enableAutoresearchMode(cwd: string, args: string | null): string {
-  const lockStatus = acquireAutoresearchSessionLock(cwd);
-  if (lockStatus.state === "active" && !lockStatus.ownedByCurrentProcess) {
-    return [
-      "Autoresearch mode NOT enabled.",
-      `Another live autoresearch loop holds autoresearch.lock (PID ${lockStatus.pid}, started ${new Date(lockStatus.timestamp ?? 0).toISOString()}).`,
-      "Resume that loop instead of creating a parallel session.",
-    ].join("\n");
+function buildWorkspacePendingCommandText(
+  runtimeState: ReturnType<typeof getAutoresearchRuntimeState>,
+): string {
+  return [
+    "OpenClaw has not exposed a workspace root for this session yet.",
+    "Send a normal message from the target workspace, or invoke an autoresearch tool there, so the plugin can bind `workspaceDir` and inspect the repo-root files.",
+    `Runtime mode: ${runtimeState.mode}`,
+    `Pending run: ${runtimeState.pendingRun ? "yes" : "no"}`,
+  ].join("\n");
+}
+
+function enableAutoresearchMode(scopeRef: AutoresearchScopeRef, args: string | null): string {
+  const scope = resolveAutoresearchScope(scopeRef);
+  if (scope.repoDir) {
+    const lockStatus = acquireAutoresearchSessionLock(scope);
+    if (lockStatus.state === "active" && !lockStatus.ownedByCurrentSession) {
+      return [
+        "Autoresearch mode NOT enabled.",
+        `Another live autoresearch loop holds autoresearch.lock (PID ${lockStatus.pid}, started ${new Date(lockStatus.timestamp ?? 0).toISOString()}).`,
+        "Resume that loop instead of creating a parallel session.",
+      ].join("\n");
+    }
   }
 
-  setAutoresearchRuntimeMode(cwd, "on");
-  const presentFiles = getPresentCanonicalFiles(cwd);
+  setAutoresearchRuntimeMode(scopeRef, "on");
+  const presentFiles = scope.repoDir ? getPresentCanonicalFiles(scope.repoDir) : [];
   const hasSession = presentFiles.some((file) => file !== AUTORESEARCH_ROOT_FILES.sessionLock);
+  setAutoresearchPendingCommand(scopeRef, {
+    kind: hasSession ? "resume" : "setup",
+    args,
+  });
+
+  if (!scope.repoDir) {
+    return [
+      "Autoresearch mode ON.",
+      "Workspace root is not bound yet, so the next agent or tool turn for this session will resolve it from OpenClaw `workspaceDir` before continuing.",
+      args ? `Captured instruction: ${args}` : "Send a normal message to continue once the workspace is available.",
+    ].join("\n");
+  }
 
   if (!hasSession) {
-    setAutoresearchPendingCommand(cwd, {
-      kind: "setup",
-      args,
-    });
     return [
       "Autoresearch mode ON.",
       "No repo-root session was detected, so the next agent turn will be primed for setup.",
@@ -158,10 +194,6 @@ function enableAutoresearchMode(cwd: string, args: string | null): string {
     ].join("\n");
   }
 
-  setAutoresearchPendingCommand(cwd, {
-    kind: "resume",
-    args,
-  });
   return [
     "Autoresearch mode ON.",
     `Next agent turn will be primed from \`${AUTORESEARCH_ROOT_FILES.sessionDoc}\` and the canonical repo-root files.`,
@@ -169,35 +201,43 @@ function enableAutoresearchMode(cwd: string, args: string | null): string {
   ].join("\n");
 }
 
-function primeAutoresearchSetup(cwd: string, args: string | null): string {
-  const lockStatus = acquireAutoresearchSessionLock(cwd);
-  if (lockStatus.state === "active" && !lockStatus.ownedByCurrentProcess) {
-    return [
-      "Autoresearch setup NOT primed.",
-      `Another live autoresearch loop holds autoresearch.lock (PID ${lockStatus.pid}, started ${new Date(lockStatus.timestamp ?? 0).toISOString()}).`,
-      "Resume that loop instead of starting a parallel setup flow.",
-    ].join("\n");
+function primeAutoresearchSetup(scopeRef: AutoresearchScopeRef, args: string | null): string {
+  const scope = resolveAutoresearchScope(scopeRef);
+  if (scope.repoDir) {
+    const lockStatus = acquireAutoresearchSessionLock(scope);
+    if (lockStatus.state === "active" && !lockStatus.ownedByCurrentSession) {
+      return [
+        "Autoresearch setup NOT primed.",
+        `Another live autoresearch loop holds autoresearch.lock (PID ${lockStatus.pid}, started ${new Date(lockStatus.timestamp ?? 0).toISOString()}).`,
+        "Resume that loop instead of starting a parallel setup flow.",
+      ].join("\n");
+    }
   }
 
-  setAutoresearchRuntimeMode(cwd, "on");
-  setAutoresearchPendingCommand(cwd, {
+  setAutoresearchRuntimeMode(scopeRef, "on");
+  setAutoresearchPendingCommand(scopeRef, {
     kind: "setup",
     args,
   });
 
   return [
     "Autoresearch setup primed.",
-    "The next agent turn will be told to create the canonical repo-root files and start the loop.",
+    scope.repoDir
+      ? "The next agent turn will be told to create the canonical repo-root files and start the loop."
+      : "The next agent turn will wait for OpenClaw to provide a workspace root, then create the canonical repo-root files and start the loop.",
     "Continue with a normal message on the next turn, or invoke the skill directly with `/skill autoresearch-create`.",
     args ? `Captured setup instruction: ${args}` : "Add an argument to `/autoresearch setup` if you want a specific goal or constraint carried forward.",
   ].join("\n");
 }
 
-function resolveCommandCwd(api: OpenClawPluginApi, ctx: CommandContext): string {
-  if (typeof ctx.cwd === "string" && ctx.cwd.trim().length > 0) {
-    return ctx.cwd;
-  }
-  return api.resolvePath(".");
+function resolveCommandScope(ctx: CommandContext): AutoresearchScopeRef {
+  return {
+    sessionKey: ctx.sessionKey,
+    sessionId: ctx.sessionId,
+    workspaceDir: ctx.workspaceDir,
+    runId: ctx.runId,
+    legacyCwd: ctx.cwd,
+  };
 }
 
 function getPresentCanonicalFiles(cwd: string): string[] {

package/extensions/openclaw-autoresearch/src/execute.ts

@@ -1,4 +1,4 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 
 const OUTPUT_TAIL_LINES = 80;
 const DEFAULT_TIMEOUT_SECONDS = 600;

package/extensions/openclaw-autoresearch/src/git.ts

@@ -1,4 +1,4 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 
 const GIT_TIMEOUT_MS = 30_000;
 

package/extensions/openclaw-autoresearch/src/hooks.ts

@@ -1,4 +1,4 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import { AUTORESEARCH_ROOT_FILES } from "./files.js";
 import { reconstructStateFromJsonl } from "./state.js";
 import { readAutoresearchCheckpoint } from "./checkpoint.js";
@@ -12,6 +12,11 @@ import {
   setAutoresearchContinuationReminder,
 } from "./runtime-state.js";
 import { removeAutoresearchSessionLock } from "./session-lock.js";
+import {
+  forgetAutoresearchScope,
+  type AutoresearchScopeRef,
+  resolveAutoresearchScope,
+} from "./scope.js";
 
 type BeforeAgentStartEvent = {
   systemPrompt?: string;
@@ -19,9 +24,13 @@ type BeforeAgentStartEvent = {
 
 type HookContext = {
   cwd?: string;
+  workspaceDir?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  runId?: string;
 };
 
-type HookCapablePluginApi = OpenClawPluginApi & {
+type HookCapablePluginApi = {
   on?: (hookName: string, handler: (event: unknown, ctx: HookContext) => unknown) => void;
   registerHook?: (
     hookName: string,
@@ -30,15 +39,10 @@ type HookCapablePluginApi = OpenClawPluginApi & {
 };
 
 export function registerAutoresearchHooks(api: OpenClawPluginApi): void {
-  const hookApi = api as HookCapablePluginApi;
+  const hookApi = api as unknown as HookCapablePluginApi;
   if (typeof hookApi.on === "function") {
     hookApi.on("before_prompt_build", (_event, ctx) => {
-      const cwd = resolveHookCwd(api, ctx);
-      if (cwd === null) {
-        return;
-      }
-
-      const addition = buildBeforePromptBuildContext(cwd);
+      const addition = buildBeforePromptBuildContext(resolveHookScope(ctx));
       if (addition === null) {
         return;
       }
@@ -49,12 +53,8 @@ export function registerAutoresearchHooks(api: OpenClawPluginApi): void {
     });
 
     hookApi.on("message_received", (event, ctx) => {
-      const cwd = resolveHookCwd(api, ctx);
-      if (cwd === null) {
-        return;
-      }
-
-      const state = getAutoresearchRuntimeState(cwd);
+      const scope = resolveHookScope(ctx);
+      const state = getAutoresearchRuntimeState(scope);
       if (!state.runInFlight) {
         return;
       }
@@ -64,12 +64,12 @@ export function registerAutoresearchHooks(api: OpenClawPluginApi): void {
         return;
       }
 
-      queueAutoresearchSteer(cwd, messageText);
+      queueAutoresearchSteer(scope, messageText);
     });
 
     hookApi.on("before_tool_call", (event, ctx) => {
-      const cwd = resolveHookCwd(api, ctx);
-      if (cwd === null || !shouldEnforceAutoresearchMode(cwd)) {
+      const scope = resolveHookScope(ctx);
+      if (!shouldEnforceAutoresearchMode(scope)) {
         return;
       }
 
@@ -92,25 +92,22 @@ export function registerAutoresearchHooks(api: OpenClawPluginApi): void {
     });
 
     hookApi.on("agent_end", (_event, ctx) => {
-      const cwd = resolveHookCwd(api, ctx);
-      if (cwd === null) {
+      const scope = resolveAutoresearchScope(resolveHookScope(ctx));
+      if (!scope.repoDir) {
         return;
       }
 
-      const state = reconstructStateFromJsonl(cwd);
+      const state = reconstructStateFromJsonl(scope.repoDir);
       if (state.mode === "active" && state.ideas.hasBacklog) {
-        setAutoresearchContinuationReminder(cwd, true);
+        setAutoresearchContinuationReminder(resolveHookScope(ctx), true);
       }
     });
 
     hookApi.on("session_end", (_event, ctx) => {
-      const cwd = resolveHookCwd(api, ctx);
-      if (cwd === null) {
-        return;
-      }
-
-      removeAutoresearchSessionLock(cwd);
-      clearAutoresearchRuntimeState(cwd);
+      const scope = resolveHookScope(ctx);
+      removeAutoresearchSessionLock(scope);
+      clearAutoresearchRuntimeState(scope);
+      forgetAutoresearchScope(scope);
     });
     return;
   }
@@ -119,13 +116,8 @@ export function registerAutoresearchHooks(api: OpenClawPluginApi): void {
     return;
   }
 
-  hookApi.registerHook("before_agent_start", (event, ctx) => {
-    const cwd = resolveHookCwd(api, ctx);
-    if (cwd === null) {
-      return;
-    }
-
-    const addition = buildBeforePromptBuildContext(cwd);
+  hookApi.registerHook("before_agent_start", (event: BeforeAgentStartEvent, ctx: HookContext) => {
+    const addition = buildBeforePromptBuildContext(resolveHookScope(ctx));
     if (addition === null) {
       return;
     }
@@ -137,11 +129,16 @@ export function registerAutoresearchHooks(api: OpenClawPluginApi): void {
   });
 }
 
-export function buildBeforePromptBuildContext(cwd: string): string | null {
-  const state = reconstructStateFromJsonl(cwd);
-  const runtimeState = getAutoresearchRuntimeState(cwd);
-  const checkpoint = readAutoresearchCheckpoint(cwd);
-  if (!shouldEnforceAutoresearchMode(cwd, state, runtimeState)) {
+export function buildBeforePromptBuildContext(scopeRef: AutoresearchScopeRef): string | null {
+  const scope = resolveAutoresearchScope(scopeRef);
+  if (!scope.repoDir) {
+    return null;
+  }
+
+  const state = reconstructStateFromJsonl(scope.repoDir);
+  const runtimeState = getAutoresearchRuntimeState(scopeRef);
+  const checkpoint = readAutoresearchCheckpoint(scope.repoDir);
+  if (!shouldEnforceAutoresearchMode(scopeRef, state, runtimeState)) {
     return null;
   }
 
@@ -150,8 +147,8 @@ export function buildBeforePromptBuildContext(cwd: string): string | null {
     AUTORESEARCH_ROOT_FILES.runnerScript,
     AUTORESEARCH_ROOT_FILES.resultsLog,
   ];
-  const pendingCommand = consumeAutoresearchPendingCommand(cwd);
-  const needsContinuationReminder = consumeAutoresearchContinuationReminder(cwd);
+  const pendingCommand = consumeAutoresearchPendingCommand(scopeRef);
+  const needsContinuationReminder = consumeAutoresearchContinuationReminder(scopeRef);
 
   const lines = ["", "", "## Autoresearch Mode (ACTIVE)"];
 
@@ -195,7 +192,7 @@ export function buildBeforePromptBuildContext(cwd: string): string | null {
   }
 
   lines.push(
-    `For discard or crash results, log_experiment records the outcome but does not revert your tree for you. Run \`git checkout -- .\` yourself after logging when you want to discard tracked changes.`,
+    "For discard or crash results, log_experiment records the outcome but does not revert your tree for you. Run `git checkout -- .` yourself after logging when you want to discard tracked changes.",
   );
 
   if (state.ideas.hasBacklog) {
@@ -219,17 +216,14 @@ export function buildBeforePromptBuildContext(cwd: string): string | null {
   return lines.join("\n");
 }
 
-function resolveHookCwd(api: OpenClawPluginApi, ctx: HookContext | undefined): string | null {
-  if (ctx && typeof ctx.cwd === "string" && ctx.cwd.trim().length > 0) {
-    return ctx.cwd;
-  }
-
-  try {
-    const resolved = api.resolvePath(".");
-    return resolved.trim().length > 0 ? resolved : null;
-  } catch {
-    return null;
-  }
+function resolveHookScope(ctx: HookContext | undefined): Exclude<AutoresearchScopeRef, string> {
+  return {
+    sessionKey: ctx?.sessionKey,
+    sessionId: ctx?.sessionId,
+    workspaceDir: ctx?.workspaceDir,
+    runId: ctx?.runId,
+    legacyCwd: ctx?.cwd,
+  };
 }
 
 function extractMessageText(event: unknown): string | null {
@@ -278,15 +272,18 @@ function isCommandLikeMessage(text: string): boolean {
 }
 
 function shouldEnforceAutoresearchMode(
-  cwd: string,
-  state = reconstructStateFromJsonl(cwd),
-  runtimeState = getAutoresearchRuntimeState(cwd),
+  scopeRef: AutoresearchScopeRef,
+  state = (() => {
+    const scope = resolveAutoresearchScope(scopeRef);
+    return scope.repoDir ? reconstructStateFromJsonl(scope.repoDir) : null;
+  })(),
+  runtimeState = getAutoresearchRuntimeState(scopeRef),
 ): boolean {
   return (
     runtimeState.mode === "on" ||
     runtimeState.runInFlight ||
     runtimeState.pendingRun !== null ||
-    (runtimeState.mode !== "off" && (state.mode === "active" || state.hasSessionDoc))
+    (runtimeState.mode !== "off" && Boolean(state && (state.mode === "active" || state.hasSessionDoc)))
   );
 }