@calltelemetry/openclaw-linear 0.9.15 → 0.9.17

package/README.md

@@ -23,20 +23,25 @@ Connect Linear to AI agents. Issues get triaged, implemented, and audited — au
 - [x] Linear OAuth app webhook (AgentSessionEvent created/prompted)
 - [x] Linear API integration (issues, comments, labels, state transitions)
 - [x] Agent routing (`@mentions`, natural language intent classifier)
+- [x] Intent gate + scope enforcement (all 4 webhook paths, 3-layer defense)
 - [x] Auto-triage (story points, labels, priority — read-only)
 - [x] Complexity-tier dispatch (small → Haiku, medium → Sonnet, high → Opus)
 - [x] Isolated git worktrees per dispatch
 - [x] Worker → Auditor pipeline (hard-enforced, not LLM-mediated)
 - [x] Audit rework loop (gaps fed back, automatic retry)
 - [x] Watchdog timeout + escalation
-- [x] Webhook deduplication (60s sliding window across session/comment/assignment)
-- [ ] Multi-repo worktree support
-- [ ] Project planner (interview → user stories → sub-issues → DAG dispatch)
-- [ ] Cross-model plan review (Claude ↔ Codex ↔ Gemini)
+- [x] Webhook deduplication (60s sliding window + `activeRuns` race guard on all paths)
+- [x] Webhook auto-provisioning (`webhooks setup` CLI, `doctor --fix`)
+- [x] Multi-repo worktree support
+- [x] Project planner (interview → user stories → sub-issues → DAG dispatch)
+- [x] Cross-model plan review (Claude ↔ Codex ↔ Gemini)
 - [x] Issue closure with summary report
-- [ ] Sub-issue decomposition (orchestrator-level only)
+- [x] Sub-issue decomposition (orchestrator-level only)
 - [x] `spawn_agent` / `ask_agent` sub-agent tools
-- [x] CI + coverage badges (1000+ tests, Codecov integration)
+- [x] CI + coverage badges (1170+ tests, Codecov integration)
+- [x] Setup wizard (`openclaw openclaw-linear setup`) + `doctor --fix` auto-repair
+- [x] Project context auto-detection (repo, framework, build/test commands → worker/audit prompts)
+- [x] Per-backend CLI tools (`cli_codex`, `cli_claude`, `cli_gemini`) with Linear session activity streaming
 - [ ] **Worktree → PR merge** — `createPullRequest()` exists but is not wired into the pipeline. After audit pass, commits sit on a `codex/{identifier}` branch. You create the PR manually.
 - [ ] **Sub-agent worktree sharing** — Sub-agents spawned via `spawn_agent`/`ask_agent` do not inherit the parent worktree. They run in their own session without code access.
 - [ ] **Parallel worktree conflict resolution** — DAG dispatch runs up to 3 issues concurrently in separate worktrees, but there's no merge conflict detection across them.
@@ -107,12 +112,13 @@ The end result: you work in Linear. You create issues, assign them, comment in p
 ### Multi-Agent & Routing
 
 - **Named agents** — Define agents with different roles and expertise. Route work by `@mention` or natural language ("hey kaylee look at this").
-- **Intent classification** — An LLM classifier (~300 tokens, ~2s) understands what you want from any comment. Regex fallback if the classifier fails.
+- **Intent classification** — An LLM classifier (~300 tokens, ~2s) runs on every user request across all webhook paths — not just comments. Classifies intent and gates work requests on untriaged issues. Regex fallback if the classifier fails.
+- **Scope enforcement** — Three-layer defense prevents agents from building code on issues that haven't been planned. Intent gate blocks `request_work` pre-dispatch; prompt-level constraints limit CLI tools to planning-only; a `before_tool_call` hook prepends hard constraints to worker prompts.
 - **One-time detour** — `@mention` a different agent in a session and it handles that single interaction. The session stays with the original agent.
 
 ### Multi-Backend & Multi-Repo
 
-- **Three coding backends** — Codex (OpenAI), Claude (Anthropic), Gemini (Google). Configurable globally or per-agent. The agent writes the prompt; the plugin handles backend selection.
+- **Three coding backends** — Codex (OpenAI), Claude (Anthropic), Gemini (Google). Configurable globally or per-agent. Each backend registers as a dedicated tool (`cli_codex`, `cli_claude`, `cli_gemini`) so agents and Linear session UI show exactly which backend is running. Per-agent overrides let you assign different backends to different team members.
 - **Multi-repo dispatch** — Tag an issue with `<!-- repos: api, frontend -->` and the worker gets isolated worktrees for each repo. One issue, multiple codebases, one agent session.
 
 ### Operations
@@ -698,24 +704,53 @@ flowchart LR
 | "hey kaylee can you look at this?" | Routes to Kaylee (no `@` needed) |
 | "@mal close this issue" | Routes to Mal (one-time detour) and closes the issue |
 | "what can I do here?" | Default agent responds (not silently dropped) |
-| "fix the search bug" | Default agent dispatches work |
+| "fix the search bug" | Default agent dispatches work (if issue is In Progress) |
+| "build me a stock trading app" (on Backlog issue) | Blocked — agent explains the issue needs scoping first |
 | "close this" / "mark as done" / "this is resolved" | Generates closure report, transitions issue to completed |
 
-`@mentions` still work as a fast path — if you write `@kaylee`, the classifier is skipped entirely for speed.
+Intent classification runs on **all webhook paths** — not just `Comment.create`. `AgentSessionEvent.created`, `AgentSessionEvent.prompted`, and `@mention` fast paths all classify intent and enforce scope.
 
 > **Tip:** Configure `classifierAgentId` to point to a small/fast model agent (like Haiku) for low-latency, low-cost intent classification. The classifier only needs ~300 tokens per call.
 
+### Scope Enforcement — Work Request Gate
+
+When a user's intent is classified as `request_work`, the plugin checks the issue's workflow state before dispatching. Issues that haven't reached **In Progress** get a polite rejection instead of an agent run:
+
+```
+This issue (ENG-123) is in Backlog — it needs planning and scoping before implementation.
+
+To move forward:
+1. Update the issue description with requirements and acceptance criteria
+2. Move the issue to In Progress
+3. Then ask me to implement it
+
+I can help you scope and plan — just ask questions or discuss the approach.
+```
+
+This prevents the most common failure mode: an agent receiving a casual comment like "build X" on an unscoped issue and immediately spinning up a CLI tool to build something that was never planned.
+
+**What's allowed on untriaged issues:**
+- Questions, discussion, scope refinement
+- Planning (`plan_start`, `plan_continue`, `plan_finalize`)
+- Agent routing (`@mention` or natural language)
+- Issue closure
+- `cli_codex`/`cli_claude`/`cli_gemini` in **planning mode only** — workers can explore code and write plan files but cannot create, modify, or delete source code
+
+**What's blocked on untriaged issues:**
+- `request_work` intent — the gate returns a rejection message before any agent runs
+- Full CLI tool implementation — even if the orchestrator LLM ignores prompt rules, a `before_tool_call` hook prepends hard planning-only constraints to the worker's prompt
+
 ### Agent Routing
 
 The plugin supports a multi-agent team where one agent is the default (`isDefault: true` in agent profiles) and others are routed to on demand. Routing works across all webhook paths:
 
-| Webhook Path | How agent is selected |
-|---|---|
-| `Comment.create` | `@mention` in comment text → specific agent. No mention → intent classifier may detect agent name ("hey kaylee") → `ask_agent` intent. Otherwise → default agent. |
-| `AgentSessionEvent.created` | Scans user's message for `@mention` aliases → routes to mentioned agent for that interaction. No mention → default agent. |
-| `AgentSessionEvent.prompted` | Same as `created` — scans follow-up message for `@mention` → one-time detour to mentioned agent. No mention → default agent. |
-| `Issue.update` (assignment) | Always dispatches to default agent. |
-| `Issue.create` (triage) | Always dispatches to default agent. |
+| Webhook Path | How agent is selected | Scope gate |
+|---|---|---|
+| `Comment.create` | `@mention` → specific agent (with intent gate). No mention → intent classifier may detect agent name ("hey kaylee") → `ask_agent` intent. Otherwise → default agent. | `request_work` blocked on untriaged |
+| `AgentSessionEvent.created` | Scans user's message for `@mention` aliases → routes to mentioned agent. No mention → default agent. | `request_work` blocked on untriaged |
+| `AgentSessionEvent.prompted` | Same as `created` — scans follow-up message for `@mention` → one-time detour. No mention → default agent. | `request_work` blocked on untriaged |
+| `Issue.update` (assignment) | Always dispatches to default agent. | Full dispatch pipeline |
+| `Issue.create` (triage) | Always dispatches to default agent. | Read-only triage |
 
 **One-time detour:** When you `@mention` an agent in a session that belongs to a different default agent, the mentioned agent handles that single interaction. The session itself stays owned by whoever created it — subsequent messages without `@mentions` go back to the default. This lets you ask a specific agent for help without permanently switching context.
 
@@ -854,7 +889,7 @@ Add settings under the plugin entry in `openclaw.json`:
 | `notifications` | object | — | Notification targets (see [Notifications](#notifications)) |
 | `inactivitySec` | number | `120` | Kill agent if silent this long |
 | `maxTotalSec` | number | `7200` | Max total agent session time |
-| `toolTimeoutSec` | number | `600` | Max single `code_run` time |
+| `toolTimeoutSec` | number | `600` | Max single CLI tool time |
 | `enableGuidance` | boolean | `true` | Inject Linear workspace/team guidance into agent prompts |
 | `teamGuidanceOverrides` | object | — | Per-team guidance toggle. Key = team ID, value = boolean. Unset teams inherit `enableGuidance`. |
 | `claudeApiKey` | string | — | Anthropic API key for Claude CLI (passed as `ANTHROPIC_API_KEY` env var). Required if using Claude backend. |
@@ -921,7 +956,7 @@ Create `coding-tools.json` in the plugin root to configure which CLI backend age
 }
 ```
 
-The agent calls `code_run` without knowing which backend is active. Resolution order: explicit `backend` parameter > per-agent override > global default > `"codex"`.
+Each backend registers as a dedicated tool — `cli_codex`, `cli_claude`, or `cli_gemini` — so agents and Linear's session UI show exactly which backend is running. The agent's prompt references the correct tool name automatically. Resolution order for which tool is exposed: per-agent override (`agentCodingTools`) > global default (`codingTool`) > `"codex"`.
 
 #### Claude API Key
 
@@ -1095,7 +1130,7 @@ rework:
 | `{{reviewModel}}` | Name of cross-model reviewer (planner review) |
 | `{{crossModelFeedback}}` | Review recommendations (planner review) |
 | `{{guidance}}` | Linear workspace/team guidance (if available, empty string otherwise) |
-| `{{projectContext}}` | Project context from config (project name, repo paths). Framework/build/test info belongs in CLAUDE.md. |
+| `{{projectContext}}` | Auto-detected project context (repo paths, framework, build commands, test commands) injected into worker and audit prompts. |
 
 ### CLI
 
@@ -1256,7 +1291,7 @@ If an agent goes silent (LLM timeout, API hang, CLI lockup), the watchdog handle
 |---|---|---|
 | `inactivitySec` | 120s | Kill if no output for this long |
 | `maxTotalSec` | 7200s (2 hrs) | Hard ceiling on total session time |
-| `toolTimeoutSec` | 600s (10 min) | Max time for a single `code_run` call |
+| `toolTimeoutSec` | 600s (10 min) | Max time for a single CLI tool call |
 
 Configure per-agent in `agent-profiles.json` or globally in plugin config.
 
@@ -1266,9 +1301,9 @@ Configure per-agent in `agent-profiles.json` or globally in plugin config.
 
 Every agent session gets these registered tools. They're available as native tool calls — no CLI parsing, no shell execution, no flag guessing.
 
-### `code_run` — Coding backend dispatch
+### `cli_codex` / `cli_claude` / `cli_gemini` — Coding backend tools
 
-Sends a task to whichever coding CLI is configured (Codex, Claude Code, or Gemini). The agent writes the prompt; the plugin handles backend selection, worktree setup, and output capture.
+Three per-backend tools that send tasks to their respective coding CLIs. Each agent sees only the tool matching its configured backend (e.g., an agent configured for `codex` gets `cli_codex`). The tool name is visible in Linear's agent session UI, so you always know which backend is running. The agent writes the prompt; the plugin handles worktree setup, session activity streaming, and output capture.
 
 ### `linear_issues` — Native Linear API
 
@@ -1289,7 +1324,7 @@ Agents call `linear_issues` with typed JSON parameters. The tool wraps the Linea
 
 Delegate work to other crew agents. `spawn_agent` is fire-and-forget (parallel), `ask_agent` waits for a reply (synchronous). Disabled with `enableOrchestration: false`.
 
-Sub-agents run in their own context — they do **not** share the parent's worktree or get `code_run` access. They're useful for reasoning, research, and coordination (e.g., "ask Inara how to phrase this error message") but cannot directly modify code. To give a sub-agent code context, include the relevant snippets in the task message.
+Sub-agents run in their own context — they do **not** share the parent's worktree or get CLI tool access. They're useful for reasoning, research, and coordination (e.g., "ask Inara how to phrase this error message") but cannot directly modify code. To give a sub-agent code context, include the relevant snippets in the task message.
 
 ### `dispatch_history` — Recent dispatch context
 
@@ -1299,10 +1334,10 @@ Returns recent dispatch activity. Agents use this for situational awareness when
 
 Tool access varies by context. Orchestrators get the full toolset; workers and auditors are restricted:
 
-| Context | `linear_issues` | `code_run` | `spawn_agent` / `ask_agent` | Filesystem |
+| Context | `linear_issues` | `cli_*` | `spawn_agent` / `ask_agent` | Filesystem |
 |---|---|---|---|---|
-| Orchestrator (triaged issue) | Full (read, create, update, comment) | Yes | Yes | Read + write |
-| Orchestrator (untriaged issue) | Read only | Yes | Yes | Read + write |
+| Orchestrator (triaged issue) | Full (read, create, update, comment) | Yes (backend-specific tool) | Yes | Read + write |
+| Orchestrator (untriaged issue) | Read only | Planning only | Yes | Read + write |
 | Worker | None | None | None | Read + write |
 | Auditor | Prompt-constrained (has tool, instructed to verify only) | None | None | Read only (by prompt) |
 | Sub-agent (spawn/ask) | None | None | Yes (can chain) | Inherited from parent |
@@ -1311,7 +1346,7 @@ Tool access varies by context. Orchestrators get the full toolset; workers and a
 
 **Auditors** have access to `linear_issues` (the tool is registered) but are instructed via prompt to verify only — they return a JSON verdict, not code or issue mutations. Write access is not enforced at the tool level.
 
-**Sub-agents** spawned via `spawn_agent`/`ask_agent` run in their own session with no worktree access and no `code_run`. They're information workers — useful for reasoning and coordination, not code execution.
+**Sub-agents** spawned via `spawn_agent`/`ask_agent` run in their own session with no worktree access and no CLI tools. They're information workers — useful for reasoning and coordination, not code execution.
 
 ---
 
@@ -1372,9 +1407,9 @@ The handler dispatches by `type + action`:
 ```mermaid
 flowchart TD
     A["POST /linear/webhook"] --> B{"Event Type"}
-    B --> C["AgentSessionEvent.created<br/>→ dedup → scan @mentions → run agent"]
-    B --> D["AgentSessionEvent.prompted<br/>→ dedup → scan @mentions → resume agent"]
-    B --> E["Comment.create<br/>→ filter self → dedup → intent classify → route"]
+    B --> C["AgentSessionEvent.created<br/>→ dedup → scan @mentions → intent classify → scope gate → run agent"]
+    B --> D["AgentSessionEvent.prompted<br/>→ dedup → scan @mentions → intent classify → scope gate → resume agent"]
+    B --> E["Comment.create<br/>→ filter self → dedup → intent classify → scope gate → route"]
     B --> F["Issue.update<br/>→ check assignment → dispatch"]
     B --> G["Issue.create<br/>→ triage (estimate, labels, priority)"]
     B --> H["AppUserNotification<br/>→ discarded (duplicates workspace events)"]
@@ -1382,26 +1417,39 @@ flowchart TD
 
 ### Intent Classification
 
-When a `Comment.create` event arrives, the plugin classifies the user's intent using a two-tier system:
+Every user request — across all 4 webhook dispatch paths — is classified through a two-tier intent system before the agent runs:
 
-1. **LLM classifier** (~300 tokens, ~2-5s) — a small/fast model parses the comment and returns structured JSON with intent + reasoning
+1. **LLM classifier** (~300 tokens, ~2-5s) — a small/fast model parses the message and returns structured JSON with intent + reasoning
 2. **Regex fallback** — if the LLM call fails or times out, static patterns catch common cases
 
-| Intent | Trigger | Handler |
-|---|---|---|
-| `plan_start` | "let's plan the features" | Start planner interview session |
-| `plan_finalize` | "looks good, ship it" | Run plan audit + cross-model review |
-| `plan_abandon` | "cancel planning" | End planning session |
-| `plan_continue` | Any message during active planning | Continue planner conversation |
-| `ask_agent` | "@kaylee" or "hey kaylee" | Route to specific agent by name |
-| `request_work` | "fix the search bug" | Dispatch to default agent |
-| `question` | "what's the status?" | Agent answers without code changes |
-| `close_issue` | "close this" / "mark as done" | Generate closure report + transition state |
-| `general` | Noise, automated messages | Silently dropped |
+**Where it runs:**
+
+| Webhook Path | Classification Point |
+|---|---|
+| `Comment.create` (no @mention) | Before routing by intent |
+| `Comment.create` (@mention fast path) | After resolving agent, before dispatch |
+| `AgentSessionEvent.created` | After enriching issue, before building prompt |
+| `AgentSessionEvent.prompted` | After enriching issue, before building follow-up prompt |
+
+**Intents:**
+
+| Intent | Trigger | Handler | Blocked on untriaged? |
+|---|---|---|---|
+| `plan_start` | "let's plan the features" | Start planner interview session | No |
+| `plan_finalize` | "looks good, ship it" | Run plan audit + cross-model review | No |
+| `plan_abandon` | "cancel planning" | End planning session | No |
+| `plan_continue` | Any message during active planning | Continue planner conversation | No |
+| `ask_agent` | "@kaylee" or "hey kaylee" | Route to specific agent by name | No |
+| `request_work` | "fix the search bug" | Dispatch to default agent | **Yes** |
+| `question` | "what's the status?" | Agent answers without code changes | No |
+| `close_issue` | "close this" / "mark as done" | Generate closure report + transition state | No |
+| `general` | Noise, automated messages | Silently dropped | No |
+
+The `request_work` intent is the only one gated by issue state. When the issue is not in **In Progress** (i.e., `stateType !== "started"`), the gate returns a rejection message explaining what the user needs to do. All other intents are allowed regardless of issue state — you can always plan, ask questions, discuss scope, and close issues.
 
 ### Hook Lifecycle
 
-The plugin registers three lifecycle hooks via `api.on()` in `index.ts`:
+The plugin registers four lifecycle hooks via `api.on()` in `index.ts`:
 
 **`agent_end`** — Dispatch pipeline state machine. When a sub-agent (worker or auditor) finishes:
 - Looks up the session key in dispatch state to find the active dispatch
@@ -1413,6 +1461,13 @@ The plugin registers three lifecycle hooks via `api.on()` in `index.ts`:
 - Reads dispatch state and finds up to 3 active dispatches
 - Prepends a `<dispatch-history>` block so the agent has situational awareness of concurrent work
 
+**`before_tool_call`** — Planning-only enforcement for CLI tools (`cli_codex`, `cli_claude`, `cli_gemini`). When the active issue is not in "started" state:
+- Fetches the issue's current workflow state from the Linear API
+- If the issue is in Triage, Todo, Backlog, or any non-started state, prepends hard constraints to the worker's prompt:
+  - Workers may read/explore files and write plan files (PLAN.md, design docs)
+  - Workers must NOT create/modify/delete source code, run deployments, or make system changes
+- This is the deepest layer of scope enforcement — even if the orchestrator LLM ignores prompt-level scope rules and calls a CLI tool anyway, the worker receives constraints that prevent implementation
+
 **`message_sending`** — Narration guard. Catches short (~250 char) "Let me explore..." responses where the agent narrates intent without actually calling tools:
 - Appends a warning: "Agent acknowledged but may not have completed the task"
 - Prevents users from thinking the agent did something when it only said it would
@@ -1711,7 +1766,8 @@ openclaw openclaw-linear prompts show       # View the active prompts
 ## CLI Reference
 
 ```bash
-# Auth & status
+# Setup & auth
+openclaw openclaw-linear setup                     # Guided first-time setup (profiles, auth, webhook, doctor)
 openclaw openclaw-linear auth                      # Run OAuth flow
 openclaw openclaw-linear status                    # Check connection
 
@@ -1775,8 +1831,8 @@ journalctl --user -u openclaw-gateway -f         # Watch live logs
 |---|---|
 | Agent goes silent | Watchdog auto-kills after `inactivitySec` and retries. Check logs for `Watchdog KILL`. |
 | Dispatch stuck after watchdog | Both retries failed. Check `.claw/log.jsonl`. Re-assign issue to restart. |
-| `code_run` uses wrong backend | Check `coding-tools.json` — explicit backend > per-agent > global default. Run `code-run doctor` to see routing. |
-| `code_run` fails at runtime | Run `openclaw openclaw-linear code-run doctor` — checks binary, API key, and live callability for each backend. |
+| `cli_*` uses wrong backend | Check `coding-tools.json` — per-agent override > global default. Run `code-run doctor` to see routing. |
+| `cli_*` fails at runtime | Run `openclaw openclaw-linear code-run doctor` — checks binary, API key, and live callability for each backend. |
 | Webhook events not arriving | Run `openclaw openclaw-linear webhooks setup` to auto-provision. Both webhooks must point to `/linear/webhook`. Check tunnel is running. |
 | Tunnel down / webhooks silently failing | `systemctl status cloudflared` (or `systemctl --user status cloudflared`). Restart with `systemctl restart cloudflared`. Test: `curl -s -X POST https://your-domain.com/linear/webhook -H 'Content-Type: application/json' -d '{"type":"test"}'` — should return `"ok"`. |
 | OAuth token expired | Auto-refreshes. If stuck, re-run `openclaw openclaw-linear auth` and restart. |

package/index.ts

@@ -18,6 +18,7 @@ import { createPlannerTools } from "./src/tools/planner-tools.js";
 import { registerDispatchCommands } from "./src/infra/commands.js";
 import { createDispatchHistoryTool } from "./src/tools/dispatch-history-tool.js";
 import { readDispatchState as readStateForHook, listActiveDispatches as listActiveForHook } from "./src/pipeline/dispatch-state.js";
+import { startTokenRefreshTimer, stopTokenRefreshTimer } from "./src/infra/token-refresh-timer.js";
 
 export default function register(api: OpenClawPluginApi) {
   const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
@@ -337,4 +338,10 @@ export default function register(api: OpenClawPluginApi) {
   api.logger.info(
     `Linear agent extension registered (agent: ${agentId}, token: ${tokenInfo.source !== "none" ? `${tokenInfo.source}` : "missing"}, ${cliSummary}, orchestration: ${orchestration})`,
   );
+
+  // Start proactive token refresh timer (runs immediately, then every 6h)
+  startTokenRefreshTimer(api, pluginConfig);
+
+  // Clean up timer on process exit
+  process.on("beforeExit", () => stopTokenRefreshTimer());
 }

package/openclaw.plugin.json

@@ -17,7 +17,46 @@
       "codexBaseRepo": { "type": "string", "description": "Path to git repo for Codex worktrees", "default": "/home/claw/ai-workspace" },
       "enableOrchestration": { "type": "boolean", "description": "Allow agents to spawn sub-agents via spawn_agent/ask_agent tools", "default": true },
       "worktreeBaseDir": { "type": "string", "description": "Base directory for persistent git worktrees (default: ~/.openclaw/worktrees)" },
-      "repos": { "type": "object", "description": "Multi-repo map (name → path, e.g. {\"api\": \"/home/claw/api\", \"frontend\": \"/home/claw/frontend\"})", "additionalProperties": { "type": "string" } },
+      "repos": {
+        "type": "object",
+        "description": "Multi-repo map — each key is a repo name, value is a path string or object with path + GitHub identity",
+        "additionalProperties": {
+          "oneOf": [
+            { "type": "string", "description": "Filesystem path (backward compat)" },
+            {
+              "type": "object",
+              "required": ["path"],
+              "properties": {
+                "path": { "type": "string", "description": "Absolute filesystem path to git repo" },
+                "github": { "type": "string", "description": "GitHub owner/repo (e.g. 'calltelemetry/cisco-cdr')" },
+                "hostname": { "type": "string", "description": "Git host (default: 'github.com')", "default": "github.com" }
+              }
+            }
+          ]
+        }
+      },
+      "teamMappings": {
+        "type": "object",
+        "description": "Map Linear team keys to repos, agents, and team-specific context",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "repos": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Repo names (keys in 'repos' config) for this team"
+            },
+            "defaultAgent": {
+              "type": "string",
+              "description": "OpenClaw agent ID to handle issues from this team"
+            },
+            "context": {
+              "type": "string",
+              "description": "Extra context injected into worker/audit prompts for this team"
+            }
+          }
+        }
+      },
       "dispatchStatePath": { "type": "string", "description": "Path to dispatch state JSON file (default: ~/.openclaw/linear-dispatch-state.json)" },
       "planningStatePath": { "type": "string", "description": "Path to planning state JSON file (default: ~/.openclaw/linear-planning-state.json)" },
       "notifications": {
@@ -61,7 +100,10 @@
       "toolTimeoutSec": { "type": "number", "description": "Max runtime for a single code_run CLI invocation in seconds (default: 600)", "default": 600 },
       "claudeApiKey": { "type": "string", "description": "Anthropic API key for Claude CLI backend (passed as ANTHROPIC_API_KEY env var)", "sensitive": true },
       "enableGuidance": { "type": "boolean", "description": "Inject Linear workspace/team guidance into agent prompts (default: true)", "default": true },
-      "teamGuidanceOverrides": { "type": "object", "description": "Per-team guidance toggle. Key = Linear team ID, value = boolean. Unset teams inherit enableGuidance.", "additionalProperties": { "type": "boolean" } }
+      "teamGuidanceOverrides": { "type": "object", "description": "Per-team guidance toggle. Key = Linear team ID, value = boolean. Unset teams inherit enableGuidance.", "additionalProperties": { "type": "boolean" } },
+      "enableTmux": { "type": "boolean", "default": true, "description": "Enable tmux wrapping for code_run CLI backends (enables steering)" },
+      "enableRetro": { "type": "boolean", "default": true, "description": "Enable post-task retrospective analysis" },
+      "retroDir": { "type": "string", "description": "Override path for coding retrospective files (default: {stateDir}/shared/coding)" }
     }
   }
 }

package/package.json

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

package/prompts.yaml

@@ -2,7 +2,7 @@
 #
 # Template variables: {{identifier}}, {{title}}, {{description}},
 #   {{worktreePath}}, {{gaps}}, {{tier}}, {{attempt}}, {{guidance}},
-#   {{projectContext}}
+#   {{projectContext}}, {{teamContext}}
 #
 # Edit these to customize worker/audit behavior without rebuilding the plugin.
 # Override path via `promptsPath` in plugin config.
@@ -27,6 +27,7 @@ worker:
 
     Worktree: {{worktreePath}}
     {{projectContext}}
+    {{teamContext}}
 
     Before writing any code, read these files in the worktree root (if they exist):
     - CLAUDE.md — project conventions, tech stack, build/test commands, architecture
@@ -70,6 +71,7 @@ audit:
 
     Worktree: {{worktreePath}}
     {{projectContext}}
+    {{teamContext}}
 
     Before auditing, read these files in the worktree root (if they exist):
     - CLAUDE.md — project conventions, tech stack, build/test commands

package/src/__test__/fixtures/recorded-sub-issue-flow.ts

@@ -2,7 +2,7 @@
  * Recorded API responses from sub-issue decomposition smoke test.
  * Auto-generated — do not edit manually.
  * Re-generate by running: npx vitest run src/__test__/smoke-linear-api.test.ts
- * Last recorded: 2026-02-22T03:40:54.418Z
+ * Last recorded: 2026-02-24T05:15:32.100Z
  */
 
 export const RECORDED = {
@@ -44,20 +44,20 @@ export const RECORDED = {
     }
   ],
   "createParent": {
-    "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-    "identifier": "UAT-438"
+    "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+    "identifier": "UAT-638"
   },
   "createSubIssue1": {
-    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
-    "identifier": "UAT-439"
+    "id": "a1702cad-3206-4a2b-bb0c-c6ad47df8983",
+    "identifier": "UAT-639"
   },
   "createSubIssue2": {
-    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
-    "identifier": "UAT-440"
+    "id": "d988eb3a-7d45-4d9b-8ee2-4d7580dd183e",
+    "identifier": "UAT-640"
   },
   "subIssue1Details": {
-    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
-    "identifier": "UAT-439",
+    "id": "a1702cad-3206-4a2b-bb0c-c6ad47df8983",
+    "identifier": "UAT-639",
     "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
     "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
     "estimate": 2,
@@ -75,6 +75,7 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
@@ -83,16 +84,16 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-      "identifier": "UAT-438"
+      "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+      "identifier": "UAT-638"
     },
     "relations": {
       "nodes": []
     }
   },
   "subIssue2Details": {
-    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
-    "identifier": "UAT-440",
+    "id": "d988eb3a-7d45-4d9b-8ee2-4d7580dd183e",
+    "identifier": "UAT-640",
     "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
     "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
     "estimate": 3,
@@ -110,6 +111,7 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
@@ -118,18 +120,18 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-      "identifier": "UAT-438"
+      "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+      "identifier": "UAT-638"
     },
     "relations": {
       "nodes": []
     }
   },
   "parentDetails": {
-    "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-    "identifier": "UAT-438",
+    "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+    "identifier": "UAT-638",
     "title": "[SMOKE TEST] Sub-Issue Parent: Search Feature",
-    "description": "Auto-generated by smoke test to verify sub-issue decomposition.\n\nThis parent issue should have two sub-issues created under it.\n\nCreated: 2026-02-22T03:40:52.229Z",
+    "description": "Auto-generated by smoke test to verify sub-issue decomposition.\n\nThis parent issue should have two sub-issues created under it.\n\nCreated: 2026-02-24T05:15:30.285Z",
     "estimate": null,
     "state": {
       "name": "Backlog",
@@ -145,17 +147,12 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": [
-        {
-          "body": "This thread is for an agent session with ctclaw.",
-          "user": null,
-          "createdAt": "2026-02-22T03:40:53.165Z"
-        }
-      ]
+      "nodes": []
     },
     "project": null,
     "parent": null,
@@ -164,11 +161,11 @@ export const RECORDED = {
     }
   },
   "createRelation": {
-    "id": "185dfd6c-362e-48a4-b717-e900407ced84"
+    "id": "139541b2-b088-4290-9ded-5b0167a42741"
   },
   "subIssue1WithRelation": {
-    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
-    "identifier": "UAT-439",
+    "id": "a1702cad-3206-4a2b-bb0c-c6ad47df8983",
+    "identifier": "UAT-639",
     "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
     "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
     "estimate": 2,
@@ -186,30 +183,25 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": [
-        {
-          "body": "This thread is for an agent session with ctclaw.",
-          "user": null,
-          "createdAt": "2026-02-22T03:40:53.603Z"
-        }
-      ]
+      "nodes": []
     },
     "project": null,
     "parent": {
-      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-      "identifier": "UAT-438"
+      "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+      "identifier": "UAT-638"
     },
     "relations": {
       "nodes": [
         {
           "type": "blocks",
           "relatedIssue": {
-            "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
-            "identifier": "UAT-440",
+            "id": "d988eb3a-7d45-4d9b-8ee2-4d7580dd183e",
+            "identifier": "UAT-640",
             "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI"
           }
         }
@@ -217,8 +209,8 @@ export const RECORDED = {
     }
   },
   "subIssue2WithRelation": {
-    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
-    "identifier": "UAT-440",
+    "id": "d988eb3a-7d45-4d9b-8ee2-4d7580dd183e",
+    "identifier": "UAT-640",
     "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
     "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
     "estimate": 3,
@@ -236,22 +228,17 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": [
-        {
-          "body": "This thread is for an agent session with ctclaw.",
-          "user": null,
-          "createdAt": "2026-02-22T03:40:53.840Z"
-        }
-      ]
+      "nodes": []
     },
     "project": null,
     "parent": {
-      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-      "identifier": "UAT-438"
+      "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+      "identifier": "UAT-638"
     },
     "relations": {
       "nodes": []

package/src/agent/agent.test.ts

@@ -228,7 +228,7 @@ describe("runAgent subprocess", () => {
     const noisyOutput = [
       "[plugins] Dispatch gateway methods registered",
       "[plugins] Linear agent extension registered (agent: zoe)",
-      '[plugins] code_run: default backend=codex, aliases={"claude":"claude"}',
+      '[plugins] cli tools registered: cli_codex, cli_claude, cli_gemini (agent default: cli_codex)',
       JSON.stringify({ payloads: [{ text: "clean response" }], meta: {} }),
     ].join("\n");
     (api.runtime.system as any).runCommandWithTimeout = vi.fn().mockResolvedValue({