@calltelemetry/openclaw-linear 0.9.14 → 0.9.15

package/index.ts

@@ -229,6 +229,56 @@ export default function register(api: OpenClawPluginApi) {
     }
   });
 
+  // Hard gate: prepend planning-only constraints to code_run when issue is not "started".
+  // Even if the orchestrator LLM ignores scope rules, the coding agent receives hard constraints.
+  api.on("before_tool_call", async (event: any, _ctx: any) => {
+    if (event.toolName !== "code_run") return;
+
+    const { getCurrentSession } = await import("./src/pipeline/active-session.js");
+    const session = getCurrentSession();
+    if (!session?.issueId) return; // Non-Linear context, allow
+
+    // Check issue state
+    const hookTokenInfo = resolveLinearToken(pluginConfig);
+    if (!hookTokenInfo.accessToken) return;
+    const hookLinearApi = new LinearAgentApi(hookTokenInfo.accessToken, {
+      refreshToken: hookTokenInfo.refreshToken,
+      expiresAt: hookTokenInfo.expiresAt,
+    });
+
+    try {
+      const issue = await hookLinearApi.getIssueDetails(session.issueId);
+      const stateType = issue?.state?.type ?? "";
+      const isStarted = stateType === "started";
+
+      if (!isStarted) {
+        const constraint = [
+          "CRITICAL CONSTRAINT — PLANNING MODE ONLY:",
+          `This issue (${session.issueIdentifier}) is in "${issue?.state?.name ?? stateType}" state — NOT In Progress.`,
+          "You may ONLY:",
+          "- Read and explore files to understand the codebase",
+          "- Write plan files (PLAN.md, notes, design outlines)",
+          "- Search code to inform planning",
+          "You MUST NOT:",
+          "- Create, modify, or delete source code, config, or infrastructure files",
+          "- Run system commands that change state (deploys, installs, migrations)",
+          "- Make external API requests that modify data",
+          "- Build, implement, or scaffold any application code",
+          "Plan and explore ONLY. Do not implement anything.",
+          "---",
+        ].join("\n");
+
+        const originalPrompt = event.params?.prompt ?? "";
+        return {
+          params: { ...event.params, prompt: `${constraint}\n${originalPrompt}` },
+        };
+      }
+    } catch (err) {
+      api.logger.warn(`before_tool_call: issue state check failed: ${err}`);
+      // Don't block on failure — fall through to allow
+    }
+  });
+
   // Narration Guard: catch short "Let me explore..." responses that narrate intent
   // without actually calling tools, and append a warning for the user.
   const NARRATION_PATTERNS = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.9.14",
+  "version": "0.9.15",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",

package/src/pipeline/webhook.test.ts

@@ -1261,7 +1261,7 @@ describe("Comment.create intent routing", () => {
       identifier: "ENG-RW",
       title: "Request Work",
       description: "desc",
-      state: { name: "Backlog", type: "backlog" },
+      state: { name: "In Progress", type: "started" },
       team: { id: "team-rw" },
       comments: { nodes: [] },
     });
@@ -2219,7 +2219,7 @@ describe("dispatchCommentToAgent via Comment.create intents", () => {
       identifier: "ENG-DE",
       title: "Dispatch Error",
       description: "desc",
-      state: { name: "Backlog", type: "backlog" },
+      state: { name: "In Progress", type: "started" },
       team: { id: "team-de" },
       comments: { nodes: [] },
     });
@@ -2709,7 +2709,7 @@ describe("postAgentComment edge cases", () => {
       identifier: "ENG-IF",
       title: "Identity Fail",
       description: "desc",
-      state: { name: "Backlog", type: "backlog" },
+      state: { name: "In Progress", type: "started" },
       team: { id: "team-if" },
       comments: { nodes: [] },
     });
@@ -3405,7 +3405,7 @@ describe("Comment.create .catch callbacks on fire-and-forget dispatches", () =>
       identifier: "ENG-RWC",
       title: "Request Work Catch",
       description: "desc",
-      state: { name: "Backlog", type: "backlog" },
+      state: { name: "In Progress", type: "started" },
       team: { id: "team-rwc" },
       comments: { nodes: [] },
     });
@@ -3599,7 +3599,7 @@ describe("dispatchCommentToAgent internal .catch callbacks", () => {
       identifier: "ENG-DCE",
       title: "DCA Error",
       description: "desc",
-      state: { name: "Backlog", type: "backlog" },
+      state: { name: "In Progress", type: "started" },
       team: { id: "team-dce" },
       comments: { nodes: [] },
     });
@@ -4865,7 +4865,7 @@ describe("session affinity routing", () => {
       identifier: "ENG-AFF-RW",
       title: "Affinity Request Work",
       description: "desc",
-      state: { name: "Backlog", type: "backlog" },
+      state: { name: "In Progress", type: "started" },
       team: { id: "team-aff" },
       comments: { nodes: [] },
     });
@@ -4899,7 +4899,7 @@ describe("session affinity routing", () => {
       identifier: "ENG-NO-AFF",
       title: "No Affinity",
       description: "desc",
-      state: { name: "Backlog", type: "backlog" },
+      state: { name: "In Progress", type: "started" },
       team: { id: "team-noaff" },
       comments: { nodes: [] },
     });

package/src/pipeline/webhook.ts

@@ -15,7 +15,7 @@ import { readPlanningState, isInPlanningMode, getPlanningSession, endPlanningSes
 import { initiatePlanningSession, handlePlannerTurn, runPlanAudit } from "./planner.js";
 import { startProjectDispatch } from "./dag-dispatch.js";
 import { emitDiagnostic } from "../infra/observability.js";
-import { classifyIntent } from "./intent-classify.js";
+import { classifyIntent, type Intent } from "./intent-classify.js";
 import { extractGuidance, formatGuidanceAppendix, cacheGuidanceForTeam, getCachedGuidanceForTeam, isGuidanceEnabled, _resetGuidanceCacheForTesting } from "./guidance.js";
 import { loadAgentProfiles, buildMentionPattern, resolveAgentFromAlias, validateProfiles, _resetProfilesCacheForTesting, type AgentProfile } from "../infra/shared-profiles.js";
 
@@ -35,6 +35,28 @@ export function sanitizePromptInput(text: string, maxLength = 4000): string {
   return sanitized;
 }
 
+/**
+ * Check if a work request should be blocked based on issue state.
+ * Returns a rejection message if blocked, null if allowed.
+ */
+function shouldBlockWorkRequest(
+  intent: Intent,
+  stateType: string,
+  stateName: string,
+  issueRef: string,
+): string | null {
+  if (intent !== "request_work") return null;
+  if (stateType === "started") return null; // In Progress — allow
+  return (
+    `This issue (${issueRef}) is in **${stateName}** — it needs planning and scoping before implementation.\n\n` +
+    `**To move forward:**\n` +
+    `1. Update the issue description with requirements and acceptance criteria\n` +
+    `2. Move the issue to **In Progress**\n` +
+    `3. Then ask me to implement it\n\n` +
+    `I can help you scope and plan — just ask questions or discuss the approach.`
+  );
+}
+
 // Track issues with active agent runs to prevent concurrent duplicate runs.
 const activeRuns = new Set<string>();
 
@@ -448,7 +470,7 @@ export async function handleLinearWebhook(
       : [
         `**Tool access:**`,
         `- \`linear_issues\` tool: READ ONLY. Use action="read" with issueId="${issueRef}" to get details, action="list_states"/"list_labels" for metadata. Do NOT use action="update", action="create", or action="comment".`,
-        `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linear_issues.`,
+        `- \`code_run\`: **Planning mode only.** Workers may explore code and write plan files (PLAN.md, design docs). Workers MUST NOT create, modify, or delete source code, run deployments, or make system changes. Use for codebase exploration and planning only.`,
         `- \`spawn_agent\`/\`ask_agent\`: Delegate to other crew agents.`,
         `- Standard tools: exec, read, edit, write, web_search, etc.`,
       ];
@@ -461,6 +483,35 @@ export async function handleLinearWebhook(
       api.logger.info(`Guidance injected (${guidanceCtx.source}): ${guidanceCtx.guidance?.slice(0, 120)}...`);
     }
 
+    // ── Intent gate: classify user request and block work requests on untriaged issues ──
+    const classifyText = userMessage || promptContext || enrichedIssue?.title || "";
+    const projectId = enrichedIssue?.project?.id;
+    let isPlanning = false;
+    if (projectId) {
+      try {
+        const planState = await readPlanningState(pluginConfig?.planningStatePath as string | undefined);
+        isPlanning = isInPlanningMode(planState, projectId);
+      } catch { /* proceed without planning context */ }
+    }
+
+    const intentResult = await classifyIntent(api, {
+      commentBody: classifyText,
+      issueTitle: enrichedIssue?.title ?? "(untitled)",
+      issueStatus: enrichedIssue?.state?.name,
+      isPlanning,
+      agentNames: Object.keys(profiles),
+      hasProject: !!projectId,
+    }, pluginConfig as Record<string, unknown> | undefined);
+
+    api.logger.info(`AgentSession.created intent: ${intentResult.intent}${intentResult.agentId ? ` (agent: ${intentResult.agentId})` : ""} — ${intentResult.reasoning}`);
+
+    const blockMsg = shouldBlockWorkRequest(intentResult.intent, stateType, enrichedIssue?.state?.name ?? "Unknown", issueRef);
+    if (blockMsg) {
+      api.logger.info(`AgentSession.created: blocking work request on untriaged issue ${issueRef}`);
+      await linearApi.emitActivity(session.id, { type: "response", body: blockMsg }).catch(() => {});
+      return true;
+    }
+
     const message = [
       `You are an orchestrator responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
       ``,
@@ -698,7 +749,7 @@ export async function handleLinearWebhook(
         : [
           `**Tool access:**`,
           `- \`linear_issues\` tool: READ ONLY. Use action="read" with issueId="${followUpIssueRef}" to get details, action="list_states"/"list_labels" for metadata. Do NOT use action="update", action="create", or action="comment".`,
-          `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linear_issues.`,
+          `- \`code_run\`: **Planning mode only.** Workers may explore code and write plan files (PLAN.md, design docs). Workers MUST NOT create, modify, or delete source code, run deployments, or make system changes. Use for codebase exploration and planning only.`,
           `- \`spawn_agent\`/\`ask_agent\`: Delegate to other crew agents.`,
           `- Standard tools: exec, read, edit, write, web_search, etc.`,
         ];
@@ -711,6 +762,37 @@ export async function handleLinearWebhook(
         api.logger.info(`Follow-up guidance injected: ${(guidanceCtxPrompted.guidance ?? "cached").slice(0, 120)}...`);
       }
 
+      // ── Intent gate: classify follow-up and block work requests on untriaged issues ──
+      const followUpProjectId = enrichedIssue?.project?.id;
+      let followUpIsPlanning = false;
+      if (followUpProjectId) {
+        try {
+          const planState = await readPlanningState(pluginConfig?.planningStatePath as string | undefined);
+          followUpIsPlanning = isInPlanningMode(planState, followUpProjectId);
+        } catch { /* proceed without planning context */ }
+      }
+
+      const followUpIntentResult = await classifyIntent(api, {
+        commentBody: userMessage,
+        issueTitle: enrichedIssue?.title ?? "(untitled)",
+        issueStatus: enrichedIssue?.state?.name,
+        isPlanning: followUpIsPlanning,
+        agentNames: Object.keys(profiles),
+        hasProject: !!followUpProjectId,
+      }, pluginConfig as Record<string, unknown> | undefined);
+
+      api.logger.info(`AgentSession.prompted intent: ${followUpIntentResult.intent}${followUpIntentResult.agentId ? ` (agent: ${followUpIntentResult.agentId})` : ""} — ${followUpIntentResult.reasoning}`);
+
+      const followUpBlockMsg = shouldBlockWorkRequest(
+        followUpIntentResult.intent, followUpStateType, enrichedIssue?.state?.name ?? "Unknown", followUpIssueRef,
+      );
+      if (followUpBlockMsg) {
+        api.logger.info(`AgentSession.prompted: blocking work request on untriaged issue ${followUpIssueRef}`);
+        await linearApi.emitActivity(session.id, { type: "response", body: followUpBlockMsg }).catch(() => {});
+        activeRuns.delete(issue.id);
+        return;
+      }
+
       const message = [
         `You are an orchestrator responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
         ``,
@@ -856,7 +938,7 @@ export async function handleLinearWebhook(
     const profiles = loadAgentProfiles();
     const agentNames = Object.keys(profiles);
 
-    // ── @mention fast path — skip classifier ────────────────────
+    // ── @mention fast path — with intent gate ────────────────────
     const mentionPattern = buildMentionPattern(profiles);
     const mentionMatches = mentionPattern ? commentBody.match(mentionPattern) : null;
     if (mentionMatches && mentionMatches.length > 0) {
@@ -864,6 +946,42 @@ export async function handleLinearWebhook(
       const resolved = resolveAgentFromAlias(alias, profiles);
       if (resolved) {
         api.logger.info(`Comment @mention fast path: @${resolved.agentId} on ${issue.identifier ?? issue.id}`);
+
+        // Classify intent even on @mention path to gate work requests
+        let enrichedForGate: any = issue;
+        try { enrichedForGate = await linearApi.getIssueDetails(issue.id); } catch {}
+        const mentionStateType = enrichedForGate?.state?.type ?? "";
+        const mentionProjectId = enrichedForGate?.project?.id;
+        let mentionIsPlanning = false;
+        if (mentionProjectId) {
+          try {
+            const planState = await readPlanningState(pluginConfig?.planningStatePath as string | undefined);
+            mentionIsPlanning = isInPlanningMode(planState, mentionProjectId);
+          } catch {}
+        }
+
+        const mentionIntentResult = await classifyIntent(api, {
+          commentBody,
+          issueTitle: enrichedForGate?.title ?? "(untitled)",
+          issueStatus: enrichedForGate?.state?.name,
+          isPlanning: mentionIsPlanning,
+          agentNames,
+          hasProject: !!mentionProjectId,
+        }, pluginConfig);
+
+        api.logger.info(`Comment @mention intent: ${mentionIntentResult.intent} — ${mentionIntentResult.reasoning}`);
+
+        const mentionBlockMsg = shouldBlockWorkRequest(
+          mentionIntentResult.intent, mentionStateType,
+          enrichedForGate?.state?.name ?? "Unknown",
+          enrichedForGate?.identifier ?? issue.identifier ?? issue.id,
+        );
+        if (mentionBlockMsg) {
+          api.logger.info(`Comment @mention: blocking work request on untriaged issue ${enrichedForGate?.identifier ?? issue.identifier ?? issue.id}`);
+          try { await createCommentWithDedup(linearApi, issue.id, mentionBlockMsg); } catch {}
+          return true;
+        }
+
         void dispatchCommentToAgent(api, linearApi, profiles, resolved.agentId, issue, comment, commentBody, commentor, pluginConfig)
           .catch((err) => api.logger.error(`Comment dispatch error: ${err}`));
         return true;
@@ -906,6 +1024,19 @@ export async function handleLinearWebhook(
 
     api.logger.info(`Comment intent: ${intentResult.intent}${intentResult.agentId ? ` (agent: ${intentResult.agentId})` : ""} — ${intentResult.reasoning} (fallback: ${intentResult.fromFallback})`);
 
+    // ── Gate work requests on untriaged issues ────────────────────
+    const commentStateType = enrichedIssue?.state?.type ?? "";
+    const commentBlockMsg = shouldBlockWorkRequest(
+      intentResult.intent, commentStateType,
+      enrichedIssue?.state?.name ?? "Unknown",
+      enrichedIssue?.identifier ?? issue.identifier ?? issue.id,
+    );
+    if (commentBlockMsg) {
+      api.logger.info(`Comment: blocking work request on untriaged issue ${enrichedIssue?.identifier ?? issue.identifier ?? issue.id}`);
+      try { await createCommentWithDedup(linearApi, issue.id, commentBlockMsg); } catch {}
+      return true;
+    }
+
     // ── Route by intent ────────────────────────────────────────────
 
     switch (intentResult.intent) {
@@ -1461,7 +1592,7 @@ async function dispatchCommentToAgent(
     : [
       `**Tool access:**`,
       `- \`linear_issues\` tool: READ ONLY. Use action="read" with issueId="${issueRef}" to get details, action="list_states"/"list_labels" for metadata. Do NOT use action="update", action="create", or action="comment".`,
-      `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linear_issues.`,
+      `- \`code_run\`: **Planning mode only.** Workers may explore code and write plan files (PLAN.md, design docs). Workers MUST NOT create, modify, or delete source code, run deployments, or make system changes. Use for codebase exploration and planning only.`,
       `- Standard tools: exec, read, edit, write, web_search, etc.`,
     ];
 
@@ -1487,7 +1618,14 @@ async function dispatchCommentToAgent(
     ``,
     `IMPORTANT: Only reference real users from the issue data above. Do NOT fabricate or guess user names, emails, or identities.`,
     ``,
-    `Respond concisely. For work requests, dispatch via \`code_run\` and summarize the result.`,
+    `## Scope Rules`,
+    `1. **Read the issue first.** The issue title + description define your scope. Everything you do must serve the issue as written.`,
+    `2. **\`code_run\` is ONLY for issue-body work.** Only dispatch \`code_run\` when the issue description contains implementation requirements. A greeting, question, or conversational issue gets a conversational response — NOT code_run.`,
+    `3. **Comments explore, issue body builds.** The comment above may explore scope or ask questions but NEVER trigger \`code_run\` from a comment alone. If the comment requests new implementation, suggest updating the issue description or creating a new issue.`,
+    `4. **Plan before building.** For non-trivial work, respond with a plan first. Only dispatch \`code_run\` after the plan is clear and grounded in the issue body.`,
+    `5. **Match response to request.** Greeting → greet. Question → answer. No implementation requirements in the issue body → no code_run.`,
+    ``,
+    `Respond within the scope defined above. Be concise and action-oriented.`,
     commentGuidanceAppendix,
   ].filter(Boolean).join("\n");