helloagents 3.1.5 → 3.1.9

package/scripts/cli-runtime-root.mjs

@@ -1,11 +1,22 @@
-import { copyFileSync, existsSync, mkdtempSync, realpathSync, renameSync } from 'node:fs'
+import {
+  copyFileSync,
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
 import { copyEntries, createLink, ensureDir, removeIfExists } from './cli-utils.mjs'
 
 export const RUNTIME_ROOT_ENTRIES = [
   '.claude-plugin',
+  '.cursor-plugin',
   '.codex-plugin',
+  '.grok-plugin',
   'assets',
   'bootstrap-lite.md',
   'bootstrap.md',
@@ -23,6 +34,17 @@ export const RUNTIME_ROOT_ENTRIES = [
   'templates',
 ]
 
+const CURSOR_PLUGIN_ENTRIES = [
+  '.cursor-plugin',
+  'hooks',
+  'LICENSE.md',
+  'README.md',
+]
+
+export const GROK_MARKETPLACE_NAME = 'helloagents-grok-marketplace'
+export const GROK_PLUGIN_NAME = 'helloagents'
+export const CURSOR_PLUGIN_NAME = 'helloagents'
+
 /** Return the stable per-user runtime copy used by host integrations. */
 export function getStableRuntimeRoot(home) {
   return join(home, '.helloagents', 'helloagents')
@@ -33,11 +55,26 @@ export function getClaudeMarketplaceRoot(home) {
   return join(home, '.helloagents', 'host-projections', 'claude-marketplace')
 }
 
+/** Return the Cursor local-plugin projection root derived from the shared runtime copy. */
+export function getCursorPluginRoot(home) {
+  return join(home, '.helloagents', 'host-projections', 'cursor-local-plugin', CURSOR_PLUGIN_NAME)
+}
+
+/** Return the Cursor managed local plugin install root. */
+export function getCursorInstallRoot(home) {
+  return join(home, '.cursor', 'plugins', 'local', CURSOR_PLUGIN_NAME)
+}
+
 /** Return the Gemini extension projection root derived from the shared runtime copy. */
 export function getGeminiExtensionRoot(home) {
   return join(home, '.helloagents', 'host-projections', 'gemini')
 }
 
+/** Return the Grok marketplace projection root derived from the shared runtime copy. */
+export function getGrokMarketplaceRoot(home) {
+  return join(home, '.helloagents', 'host-projections', GROK_MARKETPLACE_NAME)
+}
+
 function normalizePath(path) {
   const resolved = resolve(path)
   try {
@@ -73,6 +110,165 @@ function retryTransientFs(operation) {
   throw lastError
 }
 
+function safeJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'))
+  } catch {
+    return fallback
+  }
+}
+
+function safeText(filePath) {
+  try {
+    return readFileSync(filePath, 'utf-8')
+  } catch {
+    return ''
+  }
+}
+
+function normalizeSummaryText(text = '') {
+  return String(text || '')
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join(' ')
+}
+
+function extractSkillDescription(skillFile) {
+  const text = safeText(skillFile)
+  if (!text) return ''
+
+  const lines = text.replace(/\r\n/g, '\n').split('\n')
+  let inCodeFence = false
+  for (const rawLine of lines) {
+    const line = rawLine.trim()
+    if (line.startsWith('```')) {
+      inCodeFence = !inCodeFence
+      continue
+    }
+    if (inCodeFence || !line || line.startsWith('#')) continue
+    return normalizeSummaryText(line).slice(0, 280)
+  }
+  return ''
+}
+
+function listSkillComponents(sourceRoot) {
+  const skillsRoot = join(sourceRoot, 'skills')
+  if (!existsSync(skillsRoot)) return []
+
+  return readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const skillFile = join(skillsRoot, entry.name, 'SKILL.md')
+      if (!existsSync(skillFile)) return null
+      const description = extractSkillDescription(skillFile)
+      return description
+        ? { name: entry.name, description }
+        : { name: entry.name }
+    })
+    .filter(Boolean)
+}
+
+function listGrokHookComponents(sourceRoot) {
+  const hooksData = safeJson(join(sourceRoot, 'hooks', 'hooks-grok.json'), {})
+  return Object.keys(hooksData.hooks || {}).map((name) => (
+    name === 'SessionStart'
+      ? { name, description: 'startup|resume|clear|compact' }
+      : { name }
+  ))
+}
+
+function readPackageMetadata(sourceRoot) {
+  const pkg = safeJson(join(sourceRoot, 'package.json'), {}) || {}
+  const grokManifest = safeJson(join(sourceRoot, '.grok-plugin', 'plugin.json'), {}) || {}
+  const author = (
+    typeof grokManifest.author === 'object' && grokManifest.author
+      ? grokManifest.author
+      : (typeof pkg.author === 'object' && pkg.author ? pkg.author : {})
+  )
+
+  return {
+    name: grokManifest.name || GROK_PLUGIN_NAME,
+    version: grokManifest.version || pkg.version || '0.0.0',
+    description: grokManifest.description || pkg.description || '',
+    homepage: grokManifest.homepage || pkg.homepage || '',
+    repository: typeof grokManifest.repository === 'string'
+      ? grokManifest.repository
+      : (typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url || ''),
+    authorName: author.name || 'HelloWind',
+    authorEmail: author.email || '',
+    keywords: Array.isArray(grokManifest.keywords)
+      ? grokManifest.keywords
+      : (Array.isArray(pkg.keywords) ? pkg.keywords : []),
+  }
+}
+
+function buildGrokMarketplaceManifest(metadata) {
+  return {
+    name: GROK_MARKETPLACE_NAME,
+    description: 'Local development marketplace for the HelloAGENTS Grok Build plugin.',
+    owner: {
+      name: metadata.authorName,
+      ...(metadata.authorEmail ? { email: metadata.authorEmail } : {}),
+    },
+    plugins: [
+      {
+        name: metadata.name || GROK_PLUGIN_NAME,
+        description: metadata.description,
+        category: 'development',
+        version: metadata.version,
+        source: {
+          type: 'local',
+          path: `./plugins/${GROK_PLUGIN_NAME}`,
+        },
+        ...(metadata.homepage ? { homepage: metadata.homepage } : {}),
+        ...(metadata.keywords.length ? { keywords: metadata.keywords } : {}),
+      },
+    ],
+  }
+}
+
+function buildClaudeCompatibleMarketplaceManifest(metadata) {
+  return {
+    name: GROK_MARKETPLACE_NAME,
+    description: 'Local development marketplace for the HelloAGENTS Grok Build plugin.',
+    owner: {
+      name: metadata.authorName,
+      ...(metadata.authorEmail ? { email: metadata.authorEmail } : {}),
+    },
+    plugins: [
+      {
+        name: metadata.name || GROK_PLUGIN_NAME,
+        description: metadata.description,
+        source: `./plugins/${GROK_PLUGIN_NAME}`,
+        version: metadata.version,
+        category: 'development',
+        strict: false,
+      },
+    ],
+  }
+}
+
+function buildGrokPluginIndex(sourceRoot) {
+  return {
+    version: 1,
+    plugins: {
+      [GROK_PLUGIN_NAME]: {
+        components: {
+          hooks: listGrokHookComponents(sourceRoot),
+          skills: listSkillComponents(sourceRoot),
+        },
+      },
+    },
+  }
+}
+
+function writeJsonFile(filePath, value) {
+  ensureDir(dirname(filePath))
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8')
+}
+
 function syncRuntimeTree(sourceRoot, targetRoot, { materializeGeminiHooks = false } = {}) {
   const source = resolve(sourceRoot)
   const target = resolve(targetRoot)
@@ -129,6 +325,78 @@ export function syncGeminiExtensionRoot(sourceRoot, extensionRoot) {
   return syncRuntimeTree(sourceRoot, extensionRoot, { materializeGeminiHooks: true })
 }
 
+function syncCursorPluginTree(sourceRoot, targetRoot) {
+  const source = resolve(sourceRoot)
+  const target = resolve(targetRoot)
+  if (samePath(source, target)) {
+    return { synced: false, root: target }
+  }
+
+  const parent = dirname(target)
+  ensureDir(parent)
+  const staging = mkdtempSync(join(parent, '.helloagents-cursor-plugin-'))
+
+  try {
+    copyEntries(source, staging, CURSOR_PLUGIN_ENTRIES)
+    retryTransientFs(() => {
+      removeIfExists(target)
+      renameSync(staging, target)
+    })
+    return { synced: true, root: target }
+  } catch (error) {
+    removeIfExists(staging)
+    throw error
+  }
+}
+
+/** Sync a materialized Cursor local-plugin projection derived from the shared runtime copy. */
+export function syncCursorPluginRoot(sourceRoot, cursorPluginRoot) {
+  return syncCursorPluginTree(sourceRoot, cursorPluginRoot)
+}
+
+/** Sync the Cursor local-plugin install directory as a real plugin copy. */
+export function syncCursorInstallRoot(sourceRoot, installRoot) {
+  return syncCursorPluginTree(sourceRoot, installRoot)
+}
+
+/** Sync a materialized Grok marketplace projection derived from the shared runtime copy. */
+export function syncGrokMarketplaceRoot(sourceRoot, marketplaceRoot) {
+  const source = resolve(sourceRoot)
+  const target = resolve(marketplaceRoot)
+  if (samePath(source, target)) {
+    return { synced: false, root: target }
+  }
+
+  const parent = dirname(target)
+  ensureDir(parent)
+  const staging = mkdtempSync(join(parent, '.helloagents-grok-marketplace-'))
+
+  try {
+    const pluginRoot = join(staging, 'plugins', GROK_PLUGIN_NAME)
+    copyEntries(source, pluginRoot, RUNTIME_ROOT_ENTRIES)
+
+    const sourceHooks = join(pluginRoot, 'hooks', 'hooks-grok.json')
+    const targetHooks = join(pluginRoot, 'hooks', 'hooks.json')
+    if (existsSync(sourceHooks)) {
+      copyFileSync(sourceHooks, targetHooks)
+    }
+
+    const metadata = readPackageMetadata(source)
+    writeJsonFile(join(staging, '.grok-plugin', 'marketplace.json'), buildGrokMarketplaceManifest(metadata))
+    writeJsonFile(join(staging, '.grok-plugin', 'plugin-index.json'), buildGrokPluginIndex(source))
+    writeJsonFile(join(staging, '.claude-plugin', 'marketplace.json'), buildClaudeCompatibleMarketplaceManifest(metadata))
+
+    retryTransientFs(() => {
+      removeIfExists(target)
+      renameSync(staging, target)
+    })
+    return { synced: true, root: target }
+  } catch (error) {
+    removeIfExists(staging)
+    throw error
+  }
+}
+
 /** Remove the stable runtime copy while leaving user settings under ~/.helloagents intact. */
 export function removeRuntimeRoot(runtimeRoot) {
   removeIfExists(runtimeRoot)
@@ -139,7 +407,22 @@ export function removeClaudeMarketplaceRoot(home) {
   removeIfExists(getClaudeMarketplaceRoot(home))
 }
 
+/** Remove the Cursor local-plugin projection root. */
+export function removeCursorPluginRoot(home) {
+  removeIfExists(getCursorPluginRoot(home))
+}
+
+/** Remove the Cursor managed local plugin install root. */
+export function removeCursorInstallRoot(home) {
+  removeIfExists(getCursorInstallRoot(home))
+}
+
 /** Remove the Gemini extension projection root. */
 export function removeGeminiExtensionRoot(home) {
   removeIfExists(getGeminiExtensionRoot(home))
 }
+
+/** Remove the Grok marketplace projection root. */
+export function removeGrokMarketplaceRoot(home) {
+  removeIfExists(getGrokMarketplaceRoot(home))
+}

package/scripts/cli-utils.mjs

@@ -140,6 +140,42 @@ export function cleanSettingsHooks(settingsPath, cleanPermissions = false) {
   }
 }
 
+/** Merge helloagents hooks into a standalone hooks.json file, preserving non-managed entries. */
+export function mergeHooksConfig(hooksPath, hooksData) {
+  const config = safeJson(hooksPath) || {};
+  if (!config.version) config.version = 1;
+  if (!config.hooks || typeof config.hooks !== 'object' || Array.isArray(config.hooks)) {
+    config.hooks = {};
+  }
+
+  for (const [event, entries] of Object.entries(hooksData?.hooks || {})) {
+    if (!Array.isArray(config.hooks[event])) config.hooks[event] = [];
+    config.hooks[event] = config.hooks[event].filter((entry) => !JSON.stringify(entry).includes('helloagents'));
+    config.hooks[event].push(...entries);
+  }
+
+  safeWrite(hooksPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+/** Remove helloagents hooks from a standalone hooks.json file. */
+export function cleanHooksConfig(hooksPath) {
+  const config = safeJson(hooksPath);
+  if (!config || !config.hooks || typeof config.hooks !== 'object') return;
+
+  for (const [event, entries] of Object.entries(config.hooks)) {
+    if (!Array.isArray(entries)) continue;
+    config.hooks[event] = entries.filter((entry) => !JSON.stringify(entry).includes('helloagents'));
+    if (!config.hooks[event].length) delete config.hooks[event];
+  }
+
+  if (!Object.keys(config.hooks).length) delete config.hooks;
+  if (Object.keys(config).length) {
+    safeWrite(hooksPath, JSON.stringify(config, null, 2) + '\n');
+  } else {
+    removeIfExists(hooksPath);
+  }
+}
+
 function rewriteHookCommandToCli(command = '', pathVar = '') {
   const replacements = new Map([
     [`node "${pathVar}/scripts/notify.mjs"`, 'helloagents-js notify'],

package/scripts/cursor-hook.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { normalizeNotifyPayload } from './notify-payload.mjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const EVENT = String(process.argv[2] || '').trim().toLowerCase()
+
+const EVENT_CONFIG = {
+  'session-start': {
+    script: 'notify.mjs',
+    args: ['inject', '--cursor'],
+    hookEventName: 'sessionStart',
+  },
+  'pre-tool-use': {
+    script: 'guard.mjs',
+    args: ['--cursor'],
+    hookEventName: 'preToolUse',
+  },
+  'post-tool-use': {
+    script: 'guard.mjs',
+    args: ['post-write', '--cursor'],
+    hookEventName: 'postToolUse',
+  },
+  'pre-compact': {
+    script: 'notify.mjs',
+    args: ['pre-compact', '--cursor'],
+    hookEventName: 'preCompact',
+  },
+  'subagent-stop': {
+    script: 'ralph-loop.mjs',
+    args: ['subagent', '--cursor'],
+    hookEventName: 'subagentStop',
+  },
+  stop: {
+    script: 'notify.mjs',
+    args: ['stop', '--cursor'],
+    hookEventName: 'stop',
+  },
+}
+
+function readStdinJson() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function resolveWorkspaceRoot(payload = {}) {
+  if (typeof payload.cwd === 'string' && payload.cwd.trim()) return payload.cwd.trim()
+  if (Array.isArray(payload.workspace_roots)) {
+    const first = payload.workspace_roots.find((entry) => typeof entry === 'string' && entry.trim())
+    if (first) return first.trim()
+  }
+  const envRoot = String(process.env.CURSOR_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || '').trim()
+  return envRoot || process.cwd()
+}
+
+function normalizeCursorPayload(payload = {}, hookEventName = '') {
+  const normalized = normalizeNotifyPayload(payload)
+  normalized.cwd = resolveWorkspaceRoot(payload)
+  if (!normalized.hook_event_name && hookEventName) normalized.hook_event_name = hookEventName
+  if (!normalized.hookEventName && hookEventName) normalized.hookEventName = hookEventName
+
+  if (!normalized.tool_name) {
+    if (typeof payload.command === 'string' && payload.command.trim()) {
+      normalized.tool_name = 'Shell'
+      normalized.tool_input = {
+        ...(normalized.tool_input && typeof normalized.tool_input === 'object' ? normalized.tool_input : {}),
+        command: payload.command,
+      }
+    } else if (typeof payload.file_path === 'string' && payload.file_path.trim()) {
+      normalized.tool_name = hookEventName === 'postToolUse' ? 'Write' : 'Read'
+      normalized.tool_input = {
+        ...(normalized.tool_input && typeof normalized.tool_input === 'object' ? normalized.tool_input : {}),
+        file_path: payload.file_path,
+        content: payload.content,
+      }
+    }
+  }
+
+  if (
+    normalized.tool_output === undefined
+    && typeof payload.tool_output === 'string'
+  ) {
+    normalized.tool_output = payload.tool_output
+  }
+
+  return normalized
+}
+
+function runInternalScript(scriptName, args, payload, hookEventName) {
+  const result = spawnSync(process.execPath, [join(__dirname, scriptName), ...args], {
+    input: JSON.stringify(normalizeCursorPayload(payload, hookEventName)),
+    encoding: 'utf-8',
+    env: {
+      ...process.env,
+      HELLOAGENTS_HOOK_EVENT: hookEventName,
+    },
+    windowsHide: true,
+  })
+
+  if (result.error) {
+    throw result.error
+  }
+
+  if (result.status && result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || '').trim() || `${scriptName} exited with code ${result.status}`)
+  }
+
+  const stdout = String(result.stdout || '').trim()
+  if (!stdout) return {}
+  try {
+    return JSON.parse(stdout)
+  } catch {
+    throw new Error(`Invalid JSON from ${scriptName}: ${stdout}`)
+  }
+}
+
+function buildErrorResponse(event, error) {
+  const reason = `[HelloAGENTS Cursor Hook] ${error?.message || error}`
+  if (event === 'pre-tool-use') {
+    return {
+      permission: 'deny',
+      user_message: reason,
+      agent_message: reason,
+    }
+  }
+  if (event === 'session-start') {
+    return {
+      additional_context: reason,
+    }
+  }
+  return {}
+}
+
+function translatePermissionResponse(result = {}) {
+  const denialReason = result?.hookSpecificOutput?.permissionDecisionReason || result?.reason || ''
+  if (result?.hookSpecificOutput?.permissionDecision === 'deny' || result?.decision === 'block') {
+    return {
+      permission: 'deny',
+      user_message: denialReason || '[HelloAGENTS] Operation blocked.',
+      agent_message: denialReason || '[HelloAGENTS] Operation blocked.',
+    }
+  }
+  return {}
+}
+
+function translateCursorResponse(event, result = {}) {
+  if (event === 'session-start') {
+    const additionalContext = result?.hookSpecificOutput?.additionalContext
+    return additionalContext ? { additional_context: additionalContext } : {}
+  }
+  if (event === 'pre-tool-use') {
+    return translatePermissionResponse(result)
+  }
+  if (event === 'post-tool-use') {
+    const additionalContext = result?.hookSpecificOutput?.additionalContext
+    return additionalContext ? { additional_context: additionalContext } : {}
+  }
+  if (event === 'stop' || event === 'subagent-stop') {
+    if (result?.decision === 'block' && result?.reason) {
+      return {
+        followup_message: result.reason,
+      }
+    }
+    return {}
+  }
+  return {}
+}
+
+function main() {
+  const config = EVENT_CONFIG[EVENT]
+  if (!config) {
+    process.stderr.write(`cursor-hook.mjs: unknown event "${EVENT}"\n`)
+    process.exit(1)
+  }
+
+  const payload = readStdinJson()
+  try {
+    const result = runInternalScript(config.script, config.args, payload, config.hookEventName)
+    process.stdout.write(JSON.stringify(translateCursorResponse(EVENT, result)))
+  } catch (error) {
+    process.stdout.write(JSON.stringify(buildErrorResponse(EVENT, error)))
+  }
+}
+
+main()

package/scripts/guard.mjs

@@ -21,12 +21,14 @@ import {
 
 const CONFIG_FILE = join(homedir(), '.helloagents', 'helloagents.json')
 const IS_GEMINI = process.argv.includes('--gemini')
-const HOST = IS_GEMINI ? 'gemini' : 'claude'
+const IS_GROK = process.argv.includes('--grok')
+const IS_CURSOR = process.argv.includes('--cursor')
+const HOST = IS_GEMINI ? 'gemini' : (IS_GROK ? 'grok' : (IS_CURSOR ? 'cursor' : 'claude'))
 const HOOK_EVENT = process.env.HELLOAGENTS_HOOK_EVENT
   || (
     process.argv.includes('post-write')
-      ? (IS_GEMINI ? 'AfterModel' : 'PostToolUse')
-      : (IS_GEMINI ? 'BeforeTool' : 'PreToolUse')
+      ? (IS_GEMINI ? 'AfterModel' : (IS_CURSOR ? 'postToolUse' : 'PostToolUse'))
+      : (IS_GEMINI ? 'BeforeTool' : (IS_CURSOR ? 'preToolUse' : 'PreToolUse'))
   )
 
 function readSettings() {
@@ -176,4 +178,4 @@ main().catch((error) => {
   })
   process.stderr.write(`${reason}\n`)
   process.exitCode = 1
-})
+})

package/scripts/notify-context.mjs

@@ -12,6 +12,7 @@ const COMMAND_ALIASES = {
   do: 'build',
   design: 'plan',
   review: 'qa',
+  idea: 'ask',
 };
 
 function buildRuntimeRootBlock(pkgRoot) {
@@ -165,7 +166,7 @@ export function buildSemanticRouteInstruction(cwd, payload = {}) {
     '请根据用户请求的真实意图选路，不依赖关键词表。',
     buildDelegatedTaskHint(),
     '任务分层：T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆操作。',
-    '路由映射：~idea=只读探索与方向比较，不创建文件；~office=只读价值/范围评估，不创建文件；~build=明确实现；~qa=统一质量审查/验证/修复/收尾；~plan=结构化规划；~prd=重型规格；~auto=自动选择并继续执行后续阶段。',
+    '路由映射：~ask=一问一答交互澄清，不创建文件；~build=明确实现；~qa=统一质量审查/验证/修复/收尾；~plan=结构化规划；~prd=重型规格；~auto=自动选择并继续执行后续阶段。',
     '若判定为 T3，默认先走 ~plan / ~prd；纯质量审查、验真或收尾请求才优先 ~qa。',
     `涉及 UI 任务时，设计决策优先级：当前活跃 plan / PRD → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → 已读取的 hello-ui 规则；同时所有 UI 任务都必须满足 UI 质量基线。`,
     projectStorageHint,

package/scripts/notify-events.mjs

@@ -8,6 +8,8 @@ export function resolveNotifyHost(argv = []) {
   const args = Array.from(argv, (value) => String(value || ''));
   const command = args[2] || args[0] || '';
   if (args.includes('--gemini')) return 'gemini';
+  if (args.includes('--grok')) return 'grok';
+  if (args.includes('--cursor')) return 'cursor';
   if (args.includes('--codex') || command === 'codex-notify') return 'codex';
   return 'claude';
 }

package/scripts/notify-source.mjs

@@ -5,7 +5,9 @@ import { resolveSessionToken } from './session-token.mjs'
 const HOST_LABELS = {
   codex: 'Codex',
   claude: 'Claude Code',
+  cursor: 'Cursor',
   gemini: 'Gemini',
+  grok: 'Grok Build',
 }
 
 function normalizePath(filePath = '') {

package/scripts/notify.mjs

@@ -34,12 +34,13 @@ const CONFIG_FILE = join(homedir(), '.helloagents', 'helloagents.json');
 const cmd = process.argv[2] || '';
 const HOST = resolveNotifyHost(process.argv);
 const IS_GEMINI = HOST === 'gemini';
+const IS_CURSOR = HOST === 'cursor';
 const IS_CODEX = HOST === 'codex';
 const IS_SILENT = process.argv.includes('--silent');
 const EVENT_NAME = {
   SessionStart: 'SessionStart',
-  UserPromptSubmit: IS_GEMINI ? 'BeforeAgent' : 'UserPromptSubmit',
-  PreCompact: IS_GEMINI ? 'BeforeAgent' : 'PreCompact',
+  UserPromptSubmit: IS_GEMINI ? 'BeforeAgent' : (IS_CURSOR ? 'beforeSubmitPrompt' : 'UserPromptSubmit'),
+  PreCompact: IS_GEMINI ? 'BeforeAgent' : (IS_CURSOR ? 'preCompact' : 'PreCompact'),
 };
 const RALPH_LOOP_ROUTE_COMMANDS = new Set(['qa', 'loop']);
 const CODEX_HOOKS_FILE = join(homedir(), '.codex', 'hooks.json');

package/scripts/plan-contract.mjs

@@ -5,7 +5,7 @@ import { resolveProjectPlanDir } from './project-storage.mjs'
 
 export const PLAN_CONTRACT_FILE_NAME = 'contract.json'
 const VALID_QA_MODES = new Set(['standard', 'deep'])
-const VALID_ADVISOR_SOURCES = new Set(['claude', 'codex', 'gemini'])
+const VALID_ADVISOR_SOURCES = new Set(['claude', 'codex', 'cursor', 'gemini', 'grok'])
 
 function normalizeStringArray(values) {
   if (!Array.isArray(values)) return []

package/scripts/runtime-context.mjs

@@ -78,13 +78,13 @@ export function clearRouteContext(options = {}) {
 }
 
 export function writeRouteContext({ cwd, skillName, sourceSkillName = skillName, payload = {}, env, ppid }) {
-  const shouldEnsureProjectLocal = skillName !== 'idea' && skillName !== 'office' && skillName !== 'help'
+  const shouldEnsureProjectLocal = skillName !== 'ask' && skillName !== 'help'
   const scope = getRuntimeScope(cwd, { payload, env, ppid, ensureProjectLocal: shouldEnsureProjectLocal })
   const context = {
     cwd: normalizePath(cwd),
     skillName,
     sourceSkillName,
-    zeroSideEffect: skillName === 'idea' || skillName === 'office',
+    zeroSideEffect: skillName === 'ask',  // 写入会话胶囊供未来运行时消费；当前由 SKILL.md 铁律 + guard 设计共同保证边界
     identity: extractPayloadIdentity(payload),
     source: routeSource(payload),
     promptHash: hashPrompt(payload.prompt),

package/scripts/runtime-scope.mjs

@@ -174,7 +174,7 @@ export function getProjectRoot(cwd) {
 
 function getCarrierPathForRoot(root, host = '') {
   if (!root) return ''
-  if (host === 'codex') return join(root, 'AGENTS.md')
+  if (host === 'codex' || host === 'grok' || host === 'cursor') return join(root, 'AGENTS.md')
   if (host === 'gemini') return join(root, '.gemini', 'GEMINI.md')
   return join(root, 'CLAUDE.md')
 }