overlord-cli 0.2605120852.0 → 0.2605121205.0

package/README.md

@@ -13,7 +13,7 @@ Install it globally so the `ovld` and `overlord` commands are available on your
 ```bash
 npm install -g overlord-cli
 
-#After installing, run 
+#After installing, run
 ovld setup all #to configure every supported connector (`ovld setup` alone is interactive)
 
 #for individual connectors, run `ovld setup <connector>`.
@@ -27,6 +27,7 @@ ovld setup all
 # To update the CLI to the latest release, run:
 ovld update
 ```
+
 ## Usage
 
 ```bash
@@ -35,6 +36,7 @@ overlord help
 ```
 
 ### Auth
+
 ```bash
 # Repair shared credentials first when a session already exists
 ovld auth repair # mirror and chmod shared Desktop/CLI credentials when possible
@@ -47,6 +49,7 @@ ovld auth logout # remove stored credentials
 
 Desktop-installed wrappers default `OVERLORD_URL` to `https://www.ovld.ai` unless you override it explicitly.
 For local dev against the web app on port 3000, export the override before running auth or protocol commands:
+
 ```bash
 export OVERLORD_URL=http://localhost:3000
 ```
@@ -101,6 +104,7 @@ Top-level commands (see `ovld help`):
 - `version` - print the installed CLI version
 
 ## Commands for agents
+
 Agents can find docs here: https://www.ovld.ai/docs/for-agents
 
 `ovld protocol <subcommand>` is the surface agents and hooks use for ticket lifecycle work. Run `ovld protocol help` for flags, env fallbacks, and examples.
@@ -117,6 +121,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `record-change-rationales` - persist structured change rationales without a normal progress update
 - `ask` - post a blocking question and move the ticket to review
 - `permission-request` - notify Overlord that the agent is requesting tool permission
+- `hook-event` - record lifecycle hook events such as `UserPromptSubmit` / Cursor `beforeSubmitPrompt` without a session key
 - `read-context` - read shared persistent context for this ticket
 - `write-context` - write shared persistent context for future sessions
 - `deliver` - create a local JJ/Git checkpoint when available, send artifacts/rationales, and move the ticket to review

package/bin/_cli/protocol.mjs

@@ -279,6 +279,14 @@ function readTextFile(filePath, label) {
   }
 }
 
+/** Like readTextFile but accepts "-" to read from stdin. */
+async function readTextFileOrStdin(filePath, label) {
+  if (filePath === '-') {
+    return readTextFromStdin(label);
+  }
+  return readTextFile(filePath, label);
+}
+
 function readJsonFile(filePath, label) {
   try {
     return JSON.parse(readTextFile(filePath, label));
@@ -823,7 +831,7 @@ async function protocolUpdate(args) {
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
   if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const summary = flags['summary-file']
-    ? readTextFile(String(flags['summary-file']), '--summary-file')
+    ? await readTextFileOrStdin(String(flags['summary-file']), '--summary-file')
     : requireFlag(flags, 'summary', undefined);
 
   const { platformUrl, bearerToken, localSecret, organizationId } =
@@ -894,7 +902,7 @@ async function protocolRecordChangeRationales(args) {
     ticketId,
     changeRationales,
     ...(flags['summary-file']
-      ? { summary: readTextFile(String(flags['summary-file']), '--summary-file') }
+      ? { summary: await readTextFileOrStdin(String(flags['summary-file']), '--summary-file') }
       : flags.summary
         ? { summary: String(flags.summary) }
         : {}),
@@ -924,7 +932,7 @@ async function protocolAsk(args) {
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
   if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const question = flags['question-file']
-    ? readTextFile(String(flags['question-file']), '--question-file')
+    ? await readTextFileOrStdin(String(flags['question-file']), '--question-file')
     : requireFlag(flags, 'question', undefined);
 
   const { platformUrl, bearerToken, localSecret, organizationId } =
@@ -980,6 +988,46 @@ async function protocolPermissionRequest(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// ---------------------------------------------------------------------------
+// hook-event
+// ---------------------------------------------------------------------------
+
+async function protocolHookEvent(args) {
+  const flags = parseFlags(args);
+  const ticketId = requireFlag(flags, 'ticket-id', 'TICKET_ID');
+  const hookType = requireFlag(flags, 'hook-type', undefined);
+
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
+  const timeoutMs = resolveTimeout(flags);
+
+  const body = {
+    hookType,
+    ticketId,
+    ...(flags.prompt !== undefined ? { prompt: String(flags.prompt) } : {}),
+    ...(flags['turn-index'] !== undefined
+      ? { turnIndex: parseInt(String(flags['turn-index']), 10) }
+      : {})
+  };
+
+  try {
+    const data = await apiPost(
+      platformUrl,
+      bearerToken,
+      localSecret,
+      organizationId,
+      '/api/protocol/hook-event',
+      body,
+      timeoutMs
+    );
+    console.log(JSON.stringify(data, null, 2));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[protocol] hook-event skipped: ${message}\n`);
+    console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+  }
+}
+
 // ---------------------------------------------------------------------------
 // read-context
 // ---------------------------------------------------------------------------
@@ -1080,7 +1128,7 @@ async function protocolDeliver(args) {
   const summary =
     deliverPayload?.summary ??
     (flags['summary-file']
-      ? readTextFile(String(flags['summary-file']), '--summary-file')
+      ? await readTextFileOrStdin(String(flags['summary-file']), '--summary-file')
       : requireFlag(flags, 'summary', undefined));
 
   const { platformUrl, bearerToken, localSecret, organizationId } =
@@ -1705,6 +1753,7 @@ Subcommands:
   record-change-rationales  Persist structured change rationales without a progress update
   ask                       Post a blocking question and move the ticket to review
   permission-request        Notify Overlord that the agent is requesting tool permission
+  hook-event                Record a lifecycle hook event without a session key
   read-context              Read shared persistent context for this ticket
   write-context             Write shared persistent context for future sessions
   deliver                     Finish work, send artifacts, and move the ticket to review
@@ -1808,7 +1857,7 @@ update:
   Required:
     --session-key <key>
     --ticket-id <ticket_id>
-    --summary <text> or --summary-file <path>
+    --summary <text> or --summary-file <path|->
   Optional:
     --phase <status>          draft | execute | review | deliver | complete | blocked | cancelled
     --event-type <type>       update | user_follow_up | alert
@@ -1819,6 +1868,8 @@ update:
     --change-rationales-file <path>
   Notes:
     Use phase=execute while actively working. user_follow_up is for verbatim human follow-up messages.
+    Pass --summary-file - to read the summary from stdin — avoids shell interpretation of backticks,
+    quotes, or other special characters in the summary text.
 
 record-change-rationales:
   Purpose:
@@ -1828,7 +1879,7 @@ record-change-rationales:
     --ticket-id <ticket_id>
     --change-rationales-json <json> or --change-rationales-file <path>
   Optional:
-    --summary <text> or --summary-file <path>
+    --summary <text> or --summary-file <path|->
     --phase <status>
 
 ask:
@@ -1837,7 +1888,7 @@ ask:
   Required:
     --session-key <key>
     --ticket-id <ticket_id>
-    --question <text> or --question-file <path>
+    --question <text> or --question-file <path|->
   Optional:
     --phase <status>
     --payload-json <json>
@@ -1853,6 +1904,17 @@ permission-request:
   Optional:
     --payload-file <path|->   Hook JSON payload, or stdin when "-"
 
+hook-event:
+  Purpose:
+    Record a lifecycle hook event for a ticket without requiring a session key.
+    This is primarily used by installed UserPromptSubmit hooks. Stop is reserved for future lifecycle hooks.
+  Required:
+    --hook-type <UserPromptSubmit|Stop>
+    --ticket-id <ticket_id>
+  Optional:
+    --prompt <text>
+    --turn-index <n>
+
 read-context:
   Purpose:
     Read persistent shared context written by earlier sessions
@@ -1880,7 +1942,7 @@ deliver:
   Required:
     --session-key <key>
     --ticket-id <ticket_id>
-    --summary <text> or --summary-file <path>
+    --summary <text> or --summary-file <path|->
     or: --payload-file <path|-> containing { summary, artifacts, changeRationales }
   Optional:
     --artifacts-json <json>
@@ -1890,6 +1952,7 @@ deliver:
     --skip-file-change-check  Bypass local git vs changeRationales validation
   Notes:
     Use --payload-file - to read the full delivery JSON from stdin without creating a scratch file.
+    Use --summary-file - to pipe just the summary text via stdin (avoids shell special-char issues).
     Do not combine --payload-file with --artifacts-json/--artifacts-file or change-rationale flags.
     In a git workspace, deliver validates that changed files are represented by changeRationales unless skipped.
 
@@ -2017,6 +2080,7 @@ Examples:
   ovld protocol update --session-key <key> --ticket-id <ticket_id> --summary-file ./update.txt --event-type user_follow_up
   ovld protocol record-change-rationales --session-key <key> --ticket-id <ticket_id> --change-rationales-json '[{"label":"...","file_path":"...","summary":"...","why":"...","impact":"...","hunks":[{"header":"@@ ... @@"}]}]'
   ovld protocol ask --session-key <key> --ticket-id <ticket_id> --question-file ./question.txt
+  ovld protocol hook-event --hook-type UserPromptSubmit --ticket-id <ticket_id> --prompt "User follow-up" --turn-index 1
   ovld protocol read-context --session-key <key> --ticket-id <ticket_id> --query arch --limit 5
   ovld protocol write-context --session-key <key> --ticket-id <ticket_id> --key "arch" --value '"monorepo"' --tags repo,agent
   ovld protocol attachment-list --session-key <key> --ticket-id <ticket_id>
@@ -2101,6 +2165,10 @@ Examples:
     await protocolPermissionRequest(args);
     return;
   }
+  if (subcommand === 'hook-event') {
+    await protocolHookEvent(args);
+    return;
+  }
   if (subcommand === 'read-context') {
     await protocolReadContext(args);
     return;

package/bin/_cli/setup.mjs

@@ -809,10 +809,57 @@ function cursorPaths() {
       'plugin.json'
     ),
     rulesFile: path.join(base, 'rules', 'overlord-local.mdc'),
-    settingsFile: path.join(base, 'settings.json')
+    settingsFile: path.join(base, 'settings.json'),
+    hooksFile: path.join(base, 'hooks.json')
   };
 }
 
+const CURSOR_USER_PROMPT_HOOK_RELATIVE = 'plugins/local/overlord/hooks/overlord-user-prompt-submit.sh';
+
+function isOverlordCursorBeforeSubmitHook(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  const cmd = typeof entry.command === 'string' ? entry.command : '';
+  return cmd.includes('overlord-user-prompt-submit');
+}
+
+function mergeCursorBeforeSubmitHook(paths) {
+  const hooksFile = paths.hooksFile;
+  const base = fs.existsSync(hooksFile)
+    ? readJsonFile(hooksFile)
+    : { version: 1, hooks: {} };
+  const hooks = base.hooks && typeof base.hooks === 'object' && !Array.isArray(base.hooks) ? base.hooks : {};
+  const existing = Array.isArray(hooks.beforeSubmitPrompt) ? hooks.beforeSubmitPrompt : [];
+  hooks.beforeSubmitPrompt = [
+    ...existing.filter(entry => !isOverlordCursorBeforeSubmitHook(entry)),
+    { command: CURSOR_USER_PROMPT_HOOK_RELATIVE }
+  ];
+  writeJsonFile(hooksFile, {
+    ...base,
+    version: typeof base.version === 'number' ? base.version : 1,
+    hooks
+  });
+}
+
+function removeCursorBeforeSubmitHook(paths) {
+  const hooksFile = paths.hooksFile;
+  if (!fs.existsSync(hooksFile)) return;
+  const base = readJsonFile(hooksFile);
+  const hooks = base.hooks && typeof base.hooks === 'object' && !Array.isArray(base.hooks) ? base.hooks : {};
+  if (!Array.isArray(hooks.beforeSubmitPrompt)) return;
+  hooks.beforeSubmitPrompt = hooks.beforeSubmitPrompt.filter(
+    entry => !isOverlordCursorBeforeSubmitHook(entry)
+  );
+  if (hooks.beforeSubmitPrompt.length === 0) {
+    delete hooks.beforeSubmitPrompt;
+  }
+  if (Object.keys(hooks).length === 0) {
+    delete base.hooks;
+  } else {
+    base.hooks = hooks;
+  }
+  writeJsonFile(hooksFile, base);
+}
+
 function geminiPaths() {
   const base = path.join(os.homedir(), '.gemini');
   return {
@@ -945,6 +992,7 @@ function installCodex() {
 
 function installCursor() {
   const paths = cursorPaths();
+  const backups = [];
   const sourceDir = cursorSourcePluginDir();
   fs.mkdirSync(path.dirname(paths.pluginDir), { recursive: true });
   fs.rmSync(paths.pluginDir, { recursive: true, force: true });
@@ -961,6 +1009,14 @@ function installCursor() {
     for (const filePath of removedLegacySlash.removedFiles) console.log(`      ${filePath}`);
   }
 
+  const hooksBackup = backupFile(paths.hooksFile);
+  if (hooksBackup) {
+    backups.push(hooksBackup);
+    console.log(`  ✓ Backed up: ${paths.hooksFile} → ${path.basename(hooksBackup)}`);
+  }
+  mergeCursorBeforeSubmitHook(paths);
+  console.log(`  ✓ Registered Cursor beforeSubmitPrompt hook: ${paths.hooksFile}`);
+
   const existingSettings = readJsonFile(paths.settingsFile);
   const permissions =
     existingSettings.permissions && typeof existingSettings.permissions === 'object'
@@ -983,11 +1039,11 @@ function installCursor() {
     version: pluginVersion(paths.pluginManifest) ?? '0.0.0',
     contentHash: currentContentHashForAgent('cursor'),
     installedAt: new Date().toISOString(),
-    files: [...listFilesRecursive(paths.pluginDir), paths.settingsFile]
+    files: [...listFilesRecursive(paths.pluginDir), paths.settingsFile, paths.hooksFile]
   };
   writeManifest(manifest);
 
-  return { ok: true };
+  return { ok: true, backups };
 }
 
 function installGemini() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605120852.0",
+  "version": "0.2605121205.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "overlord",
-  "version": "0.1.0",
-  "description": "Overlord ticket protocol workflow for Claude Code — attach/update/ask/deliver, slash commands, and a PermissionRequest notifier.",
+  "version": "0.2.0",
+  "description": "Overlord ticket protocol workflow for Claude Code — attach/update/ask/deliver, slash commands, and hook-driven activity capture.",
   "author": {
     "name": "Cooperativ",
     "url": "https://github.com/cooperativ"
@@ -9,14 +9,8 @@
   "homepage": "https://www.ovld.ai",
   "repository": "https://github.com/cooperativ/overlord",
   "license": "UNLICENSED",
-  "keywords": [
-    "overlord",
-    "tickets",
-    "agents",
-    "workflow",
-    "protocol",
-    "claude-code"
-  ],
+  "keywords": ["overlord", "tickets", "agents", "workflow", "protocol", "claude-code"],
+  "hooks": "./hooks/hooks.json",
   "userConfig": {
     "overlord_url": {
       "type": "string",

package/plugins/claude/hooks/hooks.json

@@ -10,6 +10,17 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/user-prompt-submit-hook.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/plugins/claude/scripts/user-prompt-submit-hook.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Overlord UserPromptSubmit hook — fires before Claude processes each user turn.
+
+BODY=$(cat -)
+OVERLORD_BASE_URL="${CLAUDE_PLUGIN_OPTION_OVERLORD_URL:-$OVERLORD_URL}"
+OVERLORD_TOKEN="${CLAUDE_PLUGIN_OPTION_AGENT_TOKEN:-${CLAUDE_PLUGIN_OPTION_OVERLORD_ACCESS_TOKEN:-$OVERLORD_ACCESS_TOKEN}}"
+OVERLORD_LOCAL_SECRET="${OVERLORD_LOCAL_SECRET:-}"
+
+TURN=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('turn_number', 0))" 2>/dev/null || echo "0")
+if [ "$TURN" = "0" ]; then
+  exit 0
+fi
+
+if [ -n "$OVERLORD_BASE_URL" ] && [ -n "$OVERLORD_TOKEN" ] && [ -n "$TICKET_ID" ]; then
+  PAYLOAD=$(printf '%s' "$BODY" | python3 -c "import json,sys; body=json.load(sys.stdin); print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': __import__('os').environ['TICKET_ID'], 'prompt': body.get('prompt', ''), 'turnIndex': body.get('turn_number', 0)}))" 2>/dev/null || echo '')
+  if [ -n "$PAYLOAD" ]; then
+    curl -sf -m 5 \
+      -X POST "$OVERLORD_BASE_URL/api/protocol/hook-event" \
+      -H "Authorization: Bearer $OVERLORD_TOKEN" \
+      -H "X-Overlord-Local-Secret: $OVERLORD_LOCAL_SECRET" \
+      -H "Content-Type: application/json" \
+      -d "$PAYLOAD" \
+      >/dev/null 2>&1 &
+    disown
+  fi
+fi
+
+exit 0

package/plugins/claude/skills/overlord-ticket/SKILL.md

@@ -15,7 +15,7 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 2. Keep the returned `session.sessionKey` for all follow-up calls.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working with `ovld protocol update --phase execute`.
-5. If the user sends a follow-up message after the initial ticket, publish it immediately with `--event-type user_follow_up`.
+5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask` and stop.
 7. Deliver last with `ovld protocol deliver`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -33,7 +33,16 @@ Update:
 ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
 ```
 
+When the summary contains backticks, quotes, or other special shell characters, pipe it via stdin to prevent shell interpretation:
+
+```bash
+ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary-file - --phase execute <<'EOF'
+What you did and why — including `backticks`, "quotes", and $variables are all safe here.
+EOF
+```
+
 Supported `--phase` values:
+
 - `draft`
 - `execute`
 - `review`
@@ -45,8 +54,9 @@ Supported `--phase` values:
 These are hardcoded CLI-supported values for the `--phase` flag. They are not user-defined phase types.
 
 Event types:
+
 - `update` for standard progress updates
-- `user_follow_up` for human follow-up messages after the initial ticket
+- `user_follow_up` for human follow-up messages after the initial ticket when the automatic hook is unavailable
 - `alert` for warnings or non-blocking issues
 
 Ask when blocked:
@@ -65,7 +75,7 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
 
 ## Mode 2: Asked From Chat To Use Overlord
 
@@ -108,6 +118,7 @@ Record only meaningful behavioral changes. Skip formatting-only noise.
 ## Project Discovery And Ticket Creation
 
 When creating tickets from within a repository:
+
 - Prefer `create` by default for draft ticket creation.
 - Use `prompt` only when the user explicitly asks to start execution immediately.
 - Both commands can resolve the project from the current working directory; use `--working-directory` to override.
@@ -135,7 +146,7 @@ Pass `--execution-target agent` or `--execution-target human` (default: `human`)
 - **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
 - **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
 
-When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+When in doubt, ask yourself: _can this be done entirely inside a terminal or browser by an AI without human intervention?_ If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
 
 ## Context And Artifacts
 
@@ -164,10 +175,11 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - Use `ovld protocol` commands and the plugin's slash commands instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
+- When a summary or question contains backticks, `$vars`, or other shell-special characters, always use `--summary-file -` (or `--question-file -`) with a single-quoted heredoc (`<<'EOF'`). Never retry by stripping or escaping content — pipe stdin instead.
 - Use `write-context` for facts a future agent session should know.
 - If a protocol or MCP call fails with auth/session errors, run `ovld auth repair` yourself before asking the user to log in again or proceed without Overlord updates.
 - If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
 - Do not add or commit changes unless the user explicitly asks you to commit.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.4.7 -->
+<!-- version: 0.4.8 -->

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local Overlord workflow plugin for Cursor terminal agents.",
   "author": {
     "name": "Cooperativ",

package/plugins/cursor/hooks/overlord-user-prompt-submit.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Overlord Cursor beforeSubmitPrompt hook — posts user composer prompts to the ticket activity feed.
+# Cursor does not expose Claude's turn_number; we send a monotonic turnIndex per conversation (always >= 1)
+# so POST /api/protocol/hook-event records the event (the API skips only turnIndex === 0).
+
+BODY=$(cat -)
+
+OVERLORD_BASE_URL="${OVERLORD_URL:-${OVERLORD_CONNECTOR_URL:-}}"
+OVERLORD_TOKEN="${OVERLORD_ACCESS_TOKEN:-}"
+TICKET_ID="${TICKET_ID:-}"
+OVERLORD_LOCAL_SECRET="${OVERLORD_LOCAL_SECRET:-}"
+
+if [ -n "$OVERLORD_BASE_URL" ] && [ -n "$OVERLORD_TOKEN" ] && [ -n "$TICKET_ID" ]; then
+  PAYLOAD=$(
+    printf '%s' "$BODY" | python3 -c "
+import hashlib
+import json
+import os
+import sys
+
+try:
+    body = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+
+text = (body.get('prompt') or body.get('message') or '').strip()
+if not text:
+    sys.exit(0)
+
+cid = body.get('conversation_id') or 'unknown'
+state_dir = os.path.join(os.path.expanduser('~'), '.ovld', 'cursor-user-prompt-hook')
+os.makedirs(state_dir, exist_ok=True)
+path = os.path.join(state_dir, hashlib.sha256(cid.encode()).hexdigest())
+try:
+    with open(path, encoding='utf-8') as handle:
+        n = int((handle.read() or '0').strip() or '0')
+except Exception:
+    n = 0
+n += 1
+with open(path, 'w', encoding='utf-8') as handle:
+    handle.write(str(n))
+
+tid = os.environ.get('TICKET_ID', '')
+print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': n}))
+" 2>/dev/null
+  )
+  if [ -n "$PAYLOAD" ]; then
+    curl -sf -m 5 \
+      -X POST "$OVERLORD_BASE_URL/api/protocol/hook-event" \
+      -H "Authorization: Bearer $OVERLORD_TOKEN" \
+      -H "X-Overlord-Local-Secret: $OVERLORD_LOCAL_SECRET" \
+      -H "Content-Type: application/json" \
+      -d "$PAYLOAD" \
+      >/dev/null 2>&1 &
+    disown
+  fi
+fi
+
+printf '%s\n' '{"continue":true}'
+exit 0

package/plugins/cursor/skills/overlord-ticket/SKILL.md

@@ -13,7 +13,7 @@ Use this skill whenever Cursor needs to work with Overlord, whether the session
 2. Keep the returned `session.sessionKey` for all follow-up calls.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working with `ovld protocol update --phase execute`.
-5. If the user sends a follow-up message after the initial ticket, publish it immediately with `--event-type user_follow_up`.
+5. Follow-up messages after the initial ticket are captured automatically by the installed Cursor `beforeSubmitPrompt` hook (see `~/.cursor/hooks.json`). Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask` and stop.
 7. Deliver last with `ovld protocol deliver`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -42,7 +42,7 @@ Supported `--phase` values:
 
 Event types:
 - `update` for standard progress updates
-- `user_follow_up` for human follow-up messages after the initial ticket
+- `user_follow_up` — only when the Cursor `beforeSubmitPrompt` hook is unavailable; the hook normally posts follow-ups to the activity feed
 - `alert` for warnings or non-blocking issues
 
 Ask when blocked:
@@ -152,4 +152,4 @@ Objective attachment uploads also expose two-step variants — `attachment-prepa
 - If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.4.7 -->
+<!-- version: 0.4.8 -->

package/plugins/overlord/.codex-plugin/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEX_PLUGIN_ROOT}/scripts/user-prompt-submit-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/overlord/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "overlord",
-  "version": "0.2.1",
-  "description": "Chat-driven access to Overlord ticket protocol workflows.",
+  "version": "0.2.2",
+  "description": "Chat-driven access to Overlord ticket protocol workflows with hook-driven activity capture.",
   "author": {
     "name": "Cooperativ",
     "url": "https://github.com/cooperativ"
@@ -11,6 +11,7 @@
   "license": "UNLICENSED",
   "keywords": ["overlord", "tickets", "agents", "workflow", "protocol", "mcp", "codex-plugin"],
   "skills": "./skills/",
+  "hooks": "./.codex-plugin/hooks.json",
   "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "Overlord",

package/plugins/overlord/scripts/overlord-mcp.mjs

@@ -35,7 +35,10 @@ const tools = [
     inputSchema: {
       type: 'object',
       properties: {
-        working_directory: { type: 'string', description: 'Directory to match. Defaults to the current workspace.' }
+        working_directory: {
+          type: 'string',
+          description: 'Directory to match. Defaults to the current workspace.'
+        }
       }
     },
     toCliFlags: args => ({
@@ -45,17 +48,22 @@ const tools = [
   },
   {
     name: 'attach',
-    description: 'Attach an agent session to an existing Overlord ticket and return the working context.',
+    description:
+      'Attach an agent session to an existing Overlord ticket and return the working context.',
     inputSchema: {
       type: 'object',
       properties: {
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         agent: { type: 'string' },
         method: { type: 'string' },
         external_session_id: { type: ['string', 'null'] },
         metadata: {
           type: 'object',
-          description: 'Optional extra metadata merged into the attach request (same as --metadata-json on the CLI).'
+          description:
+            'Optional extra metadata merged into the attach request (same as --metadata-json on the CLI).'
         }
       },
       required: ['ticket_id']
@@ -77,12 +85,16 @@ const tools = [
     inputSchema: {
       type: 'object',
       properties: {
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         agent: { type: 'string' },
         method: { type: 'string' },
         metadata: {
           type: 'object',
-          description: 'Optional extra metadata merged into the connect request (same as --metadata-json on the CLI).'
+          description:
+            'Optional extra metadata merged into the connect request (same as --metadata-json on the CLI).'
         }
       },
       required: ['ticket_id']
@@ -104,7 +116,10 @@ const tools = [
     inputSchema: {
       type: 'object',
       properties: {
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' }
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        }
       },
       required: ['ticket_id']
     },
@@ -124,7 +139,10 @@ const tools = [
         priority: { type: 'string', enum: ['low', 'medium', 'high', 'urgent'] },
         project_id: { type: 'string' },
         working_directory: { type: 'string' },
-        personal: { type: 'boolean', description: 'Create without assigning a project (private ticket).' },
+        personal: {
+          type: 'boolean',
+          description: 'Create without assigning a project (private ticket).'
+        },
         acceptance_criteria: { type: 'string' },
         available_tools: { type: 'string' },
         execution_target: { type: 'string', enum: ['agent', 'human'] },
@@ -161,9 +179,15 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         summary: { type: 'string' },
-        phase: { type: 'string', enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled'] },
+        phase: {
+          type: 'string',
+          enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled']
+        },
         event_type: { type: 'string', enum: ['update', 'user_follow_up', 'alert'] },
         external_url: { type: ['string', 'null'] },
         external_session_id: { type: ['string', 'null'] },
@@ -192,9 +216,15 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         summary: { type: 'string' },
-        phase: { type: 'string', enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled'] },
+        phase: {
+          type: 'string',
+          enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled']
+        },
         change_rationales: { type: 'array' }
       },
       required: ['session_key', 'ticket_id', 'change_rationales']
@@ -208,6 +238,31 @@ const tools = [
     }),
     subcommand: 'record-change-rationales'
   },
+  {
+    name: 'record_hook_event',
+    description:
+      'Record a hook lifecycle event for a ticket without requiring a session key. Stop is reserved for future lifecycle hooks.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        hook_type: { type: 'string', enum: ['UserPromptSubmit', 'Stop'] },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
+        prompt: { type: 'string' },
+        turn_index: { type: 'number' }
+      },
+      required: ['hook_type', 'ticket_id']
+    },
+    toCliFlags: args => ({
+      'hook-type': args.hook_type,
+      'ticket-id': args.ticket_id,
+      prompt: args.prompt,
+      'turn-index': args.turn_index
+    }),
+    subcommand: 'hook-event'
+  },
   {
     name: 'ask',
     description: 'Send a blocking question to the human reviewer or PM.',
@@ -215,9 +270,15 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         question: { type: 'string' },
-        phase: { type: 'string', enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled'] },
+        phase: {
+          type: 'string',
+          enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled']
+        },
         payload: { type: 'object' }
       },
       required: ['session_key', 'ticket_id', 'question']
@@ -238,7 +299,10 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         query: { type: 'string' },
         limit: { type: 'number' }
       },
@@ -259,7 +323,10 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         key: { type: 'string' },
         value: {},
         tags: { type: 'array', items: { type: 'string' } }
@@ -283,7 +350,10 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         summary: { type: 'string' },
         artifacts: { type: 'array' },
         change_rationales: { type: 'array' },
@@ -313,9 +383,13 @@ const tools = [
       JSON.stringify({
         summary: args.summary,
         ...(Array.isArray(args.artifacts) ? { artifacts: args.artifacts } : {}),
-        ...(Array.isArray(args.change_rationales) ? { changeRationales: args.change_rationales } : {}),
+        ...(Array.isArray(args.change_rationales)
+          ? { changeRationales: args.change_rationales }
+          : {}),
         ...(args.snapshot && typeof args.snapshot === 'object' ? { snapshot: args.snapshot } : {}),
-        ...(args.checkpoint && typeof args.checkpoint === 'object' ? { checkpoint: args.checkpoint } : {})
+        ...(args.checkpoint && typeof args.checkpoint === 'object'
+          ? { checkpoint: args.checkpoint }
+          : {})
       }),
     subcommand: 'deliver'
   },
@@ -327,7 +401,10 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         objective_id: { type: 'string' }
       },
       required: ['session_key', 'ticket_id']
@@ -346,7 +423,10 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         objective_id: { type: 'string' },
         file_name: { type: 'string' },
         label: { type: 'string' },
@@ -370,12 +450,16 @@ const tools = [
   },
   {
     name: 'finalize_attachment_upload',
-    description: 'Finalize an objective attachment after uploading bytes to the signed storage URL.',
+    description:
+      'Finalize an objective attachment after uploading bytes to the signed storage URL.',
     inputSchema: {
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         objective_id: { type: 'string' },
         storage_path: { type: 'string' },
         label: { type: 'string' },
@@ -404,7 +488,10 @@ const tools = [
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         objective_id: { type: 'string' },
         attachment_id: { type: 'string' },
         storage_path: { type: 'string' },
@@ -424,12 +511,16 @@ const tools = [
   },
   {
     name: 'upload_attachment_file',
-    description: 'Prepare, upload, and finalize a local file as an objective attachment in one step.',
+    description:
+      'Prepare, upload, and finalize a local file as an objective attachment in one step.',
     inputSchema: {
       type: 'object',
       properties: {
         session_key: { type: 'string' },
-        ticket_id: { type: 'string', description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
         objective_id: { type: 'string' },
         file: { type: 'string' },
         file_name: { type: 'string' },
@@ -516,12 +607,13 @@ function parseMessages(chunk) {
 
     const headerText = buffer.subarray(0, headerEnd).toString('utf8');
     const headers = Object.fromEntries(
-      headerText
-        .split('\r\n')
-        .map(line => {
-          const separatorIndex = line.indexOf(':');
-          return [line.slice(0, separatorIndex).trim().toLowerCase(), line.slice(separatorIndex + 1).trim()];
-        })
+      headerText.split('\r\n').map(line => {
+        const separatorIndex = line.indexOf(':');
+        return [
+          line.slice(0, separatorIndex).trim().toLowerCase(),
+          line.slice(separatorIndex + 1).trim()
+        ];
+      })
     );
 
     const contentLength = Number(headers['content-length']);
@@ -560,7 +652,9 @@ function cliArgsFromFlags(flags) {
     }
 
     const serialized =
-      typeof value === 'string' || typeof value === 'number' ? String(value) : JSON.stringify(value);
+      typeof value === 'string' || typeof value === 'number'
+        ? String(value)
+        : JSON.stringify(value);
     args.push(`--${key}`, serialized);
   }
 

package/plugins/overlord/scripts/user-prompt-submit-hook.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Overlord UserPromptSubmit hook — fires before Codex processes each user turn.
+
+BODY=$(cat -)
+OVERLORD_BASE_URL="${OVERLORD_URL:-}"
+OVERLORD_TOKEN="${OVERLORD_ACCESS_TOKEN:-}"
+OVERLORD_LOCAL_SECRET="${OVERLORD_LOCAL_SECRET:-}"
+
+TURN=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('turn_number', 0))" 2>/dev/null || echo "0")
+if [ "$TURN" = "0" ]; then
+  exit 0
+fi
+
+if [ -n "$OVERLORD_BASE_URL" ] && [ -n "$OVERLORD_TOKEN" ] && [ -n "$TICKET_ID" ]; then
+  PAYLOAD=$(printf '%s' "$BODY" | python3 -c "import json,sys; body=json.load(sys.stdin); print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': __import__('os').environ['TICKET_ID'], 'prompt': body.get('prompt', ''), 'turnIndex': body.get('turn_number', 0)}))" 2>/dev/null || echo '')
+  if [ -n "$PAYLOAD" ]; then
+    curl -sf -m 5 \
+      -X POST "$OVERLORD_BASE_URL/api/protocol/hook-event" \
+      -H "Authorization: Bearer $OVERLORD_TOKEN" \
+      -H "X-Overlord-Local-Secret: $OVERLORD_LOCAL_SECRET" \
+      -H "Content-Type: application/json" \
+      -d "$PAYLOAD" \
+      >/dev/null 2>&1 &
+    disown
+  fi
+fi
+
+exit 0

package/plugins/overlord/skills/overlord-ticket/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when Codex needs to work with Overlord, whether the session was l
 2. Store the returned `SESSION_KEY` or `session.sessionKey`.
 3. Treat the Overlord ticket prompt as authoritative for the specific objective and ticket-level constraints.
 4. While working, publish meaningful progress with `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --phase execute --summary "..."`.
-5. If a later user message arrives during the ticket session, publish it immediately with `--event-type user_follow_up` before doing anything else.
+5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked on a human-only action, ask a precise blocking question with `ovld protocol ask` and stop.
 7. Deliver last with `ovld protocol deliver`, including meaningful `changeRationales` for every behavioral git-tracked change.
 
@@ -32,6 +32,7 @@ ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary
 ```
 
 Supported `--phase` values:
+
 - `draft`
 - `execute`
 - `review`
@@ -43,8 +44,9 @@ Supported `--phase` values:
 These are hardcoded CLI-supported values for the `--phase` flag. They are not user-defined phase types.
 
 Event types:
+
 - `update` for standard progress updates
-- `user_follow_up` for human follow-up messages after the initial ticket
+- `user_follow_up` for human follow-up messages after the initial ticket when the automatic hook is unavailable
 - `alert` for warnings or non-blocking issues
 
 Ask when blocked:
@@ -81,6 +83,7 @@ ovld protocol deliver --session-key <sessionKey> \
 ## Project Discovery And Ticket Creation
 
 When creating tickets from within a repository:
+
 - Prefer `create` by default for draft ticket creation.
 - Use `prompt` only when the user explicitly asks to start execution immediately.
 - Both commands can resolve the project from the current working directory; use `--working-directory` to override.
@@ -100,7 +103,7 @@ Pass `--execution-target agent` or `--execution-target human` (default: `human`)
 - **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
 - **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
 
-When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+When in doubt, ask yourself: _can this be done entirely inside a terminal or browser by an AI without human intervention?_ If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
 
 ## Change Rationales
 
@@ -155,4 +158,4 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - If a protocol or MCP call fails with auth/session errors, run `ovld auth repair` yourself before asking the user to log in again or proceed without Overlord updates.
 - If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
 
-<!-- version: 0.4.7 -->
+<!-- version: 0.4.8 -->