overlord-cli 0.2605240843.0 → 0.2605241101.0

package/README.md

@@ -127,7 +127,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `create` - create a draft ticket without attaching (standalone or follow-up)
 - `prompt` - create a ticket and attach to it immediately (`spawn` is a backward-compatible alias)
 - `record-work` - record already-completed chat work as a ticket in review with a completed objective and trigger feed-post generation
-- `update` - post progress, activity events, and optional change rationales
+- `update` - post progress, discussion/decision events, optional change rationales, and explicit `--begin-follow-up-work` transitions
 - `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
@@ -151,6 +151,8 @@ Use `create` for future work you want to track, `prompt` for work that should st
 
 `ovld protocol deliver` accepts either discrete flags like `--summary` / `--artifacts-json`, an inline full payload with `--payload-json '{"summary":"...","artifacts":[...],"changeRationales":[...]}'`, or a file/stdin payload with `--payload-file <path|->`.
 
+After delivery, follow-up messages are recorded as discussion by default. To start implementation again on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving back to `--phase execute`. Use `--event-type discussion_summary` or `--event-type decision` for important non-file outcomes. Once follow-up execution records a real work signal, such as an execution update, git snapshot, change rationales, deliverables, or explicit `pending_delivery` intent, Overlord marks the objective `pending_delivery` so redelivery is only required for actual post-delivery work.
+
 ## License
 
 Permission is granted to use this software for any purpose, free of charge. You may not modify, distribute, sublicense, or sell copies of the software without explicit permission from the author.

package/bin/_cli/protocol.mjs

@@ -1023,6 +1023,8 @@ async function protocolUpdate(args) {
       : {}),
     ...(flags.phase ? { phase: String(flags.phase) } : {}),
     ...(flags['event-type'] ? { eventType: String(flags['event-type']) } : {}),
+    ...(flags['begin-follow-up-work'] !== undefined ? { beginFollowUpWork: true } : {}),
+    ...(flags['follow-up-intent'] ? { followUpIntent: String(flags['follow-up-intent']) } : {}),
     ...(flags['payload-json']
       ? { payload: parseJsonFlag('--payload-json', flags['payload-json']) }
       : {}),
@@ -1204,13 +1206,17 @@ async function protocolHookEvent(args) {
     await resolveProtocolAuthForFlags(flags, ticketId);
   const timeoutMs = resolveTimeout(flags);
 
+  const sessionKey = String(flags['session-key'] ?? process.env.SESSION_KEY ?? '');
+
   const body = {
     hookType,
     ticketId,
     ...(flags.prompt !== undefined ? { prompt: String(flags.prompt) } : {}),
     ...(flags['turn-index'] !== undefined
       ? { turnIndex: parseInt(String(flags['turn-index']), 10) }
-      : {})
+      : {}),
+    ...(flags['follow-up-intent'] ? { followUpIntent: String(flags['follow-up-intent']) } : {}),
+    ...(sessionKey ? { sessionKey } : {})
   };
 
   try {
@@ -2696,14 +2702,22 @@ update:
     --summary <text> or --summary-file <path|->
   Optional:
     --phase <status>          draft | execute | review | deliver | complete | blocked | cancelled
-    --event-type <type>       update | user_follow_up | alert
+    --event-type <type>       update | user_follow_up | alert | discussion_summary | decision
+    --begin-follow-up-work    Explicitly reopen a delivered/review ticket for execution
+    --follow-up-intent <mode> discussion | execution | pending_delivery
     --payload-json <json>     Additional structured payload, for example notifications
     --external-url <url|null> Store or clear a deep link to the live agent session
     --external-session-id <id|null>
     --change-rationales-json <json>
     --change-rationales-file <path>
   Notes:
-    Use phase=execute while actively working. user_follow_up is for verbatim human follow-up messages.
+    Use phase=execute while actively working. For delivered/review tickets, pass
+    --begin-follow-up-work before moving back to execute. user_follow_up is for
+    verbatim human follow-up messages; discussion_summary and decision record
+    important non-file follow-up outcomes. After a prior delivery, execution
+    updates, git snapshots, change rationales, or explicit pending_delivery
+    intent mark the objective as pending_delivery so redelivery is required
+    only when follow-up execution produced work.
     Pass --summary-file - to read the summary from stdin — avoids shell interpretation of backticks,
     quotes, or other special characters in the summary text.
 
@@ -2750,6 +2764,7 @@ hook-event:
   Optional:
     --prompt <text>
     --turn-index <n>
+    --follow-up-intent <mode> discussion | execution | pending_delivery
 
 read-context:
   Purpose:

package/bin/_cli/setup.mjs

@@ -1670,6 +1670,19 @@ function getPlatformUrl() {
   return process.env.OVERLORD_URL || 'http://localhost:3000';
 }
 
+function printAgentPermissionsDescription() {
+  console.log('Agent permissions pre-approve the `ovld protocol` commands your coding');
+  console.log('agent runs to drive Overlord tickets (attach, update, deliver, etc.) so');
+  console.log('you aren\'t prompted to approve each call mid-task. Without this, the');
+  console.log('agent stalls on permission prompts for every protocol step.');
+  console.log('');
+  console.log('Where each agent\'s permission is written:');
+  console.log('  • Claude Code — ./.claude/settings.local.json (this directory only)');
+  console.log('  • OpenCode    — ~/.config/opencode/opencode.json (global)');
+  console.log('  • Codex       — prints a one-time command to run inside Codex');
+  console.log('Each entry is plain JSON you can review or remove at any time.\n');
+}
+
 function installAgentPermissions(agents, platformUrl) {
   console.log(`\nInstalling agent permissions for: ${agents.join(', ')}`);
   console.log(`Platform URL: ${platformUrl}\n`);
@@ -1878,6 +1891,7 @@ export async function runSetupCommand(args) {
     if (agentsThatNeedPermissions.length > 0) {
       console.log('Agent plugins/connectors prepared successfully!\n');
 
+      printAgentPermissionsDescription();
       const shouldInstallPermissions = await askYesNo(
         'Would you like to configure agent permissions for Overlord protocol access?',
         true
@@ -1923,8 +1937,10 @@ export async function runSetupCommand(args) {
     );
 
     if (agentsThatNeedPermissions.length > 0) {
+      console.log();
+      printAgentPermissionsDescription();
       const shouldInstallPermissions = await askYesNo(
-        '\nWould you like to configure agent permissions for Overlord protocol access?',
+        'Would you like to configure agent permissions for Overlord protocol access?',
         true
       );
 
@@ -1956,8 +1972,10 @@ export async function runSetupCommand(args) {
 
     // Offer permissions setup for single agent install too
     if (['claude', 'codex', 'opencode'].includes(agent)) {
+      console.log();
+      printAgentPermissionsDescription();
       const shouldInstallPermissions = await askYesNo(
-        '\nWould you like to configure agent permissions for Overlord protocol access?',
+        'Would you like to configure agent permissions for Overlord protocol access?',
         true
       );
 

package/package.json

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

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

@@ -327,7 +327,8 @@ const tools = [
   },
   {
     name: 'update',
-    description: 'Post an Overlord progress update or activity event.',
+    description:
+      'Post an Overlord progress update or activity event. Use begin_follow_up_work to explicitly reopen delivered/review tickets for follow-up execution.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -341,7 +342,15 @@ const tools = [
           type: 'string',
           enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled']
         },
-        event_type: { type: 'string', enum: ['update', 'user_follow_up', 'alert'] },
+        event_type: {
+          type: 'string',
+          enum: ['update', 'user_follow_up', 'alert', 'discussion_summary', 'decision']
+        },
+        begin_follow_up_work: { type: 'boolean' },
+        follow_up_intent: {
+          type: 'string',
+          enum: ['discussion', 'execution', 'pending_delivery']
+        },
         external_url: { type: ['string', 'null'] },
         external_session_id: { type: ['string', 'null'] },
         payload: { type: 'object' },
@@ -355,6 +364,8 @@ const tools = [
       summary: args.summary,
       phase: args.phase,
       'event-type': args.event_type,
+      ...(args.begin_follow_up_work ? { 'begin-follow-up-work': true } : {}),
+      'follow-up-intent': args.follow_up_intent,
       'external-url': args.external_url,
       'external-session-id': args.external_session_id,
       'payload-json': args.payload,
@@ -394,7 +405,7 @@ const tools = [
   {
     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.',
+      "Record a hook lifecycle event for a ticket. Use hookType='Stop' with a session_key to check whether delivery is needed after a turn ends.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -404,7 +415,16 @@ const tools = [
           description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
         },
         prompt: { type: 'string' },
-        turn_index: { type: 'number' }
+        turn_index: { type: 'number' },
+        follow_up_intent: {
+          type: 'string',
+          enum: ['discussion', 'execution', 'pending_delivery']
+        },
+        session_key: {
+          type: 'string',
+          description:
+            'Optional session key for Stop hooks. When provided, the response includes deliveryStatus indicating whether delivery is needed.'
+        }
       },
       required: ['hook_type', 'ticket_id']
     },
@@ -412,7 +432,9 @@ const tools = [
       'hook-type': args.hook_type,
       'ticket-id': args.ticket_id,
       prompt: args.prompt,
-      'turn-index': args.turn_index
+      'turn-index': args.turn_index,
+      'follow-up-intent': args.follow_up_intent,
+      'session-key': args.session_key
     }),
     subcommand: 'hook-event'
   },
@@ -760,6 +782,10 @@ const tools = [
         device_platform: {
           type: 'string',
           description: 'e.g. darwin, linux, win32.'
+        },
+        device_port: {
+          type: 'integer',
+          description: 'SSH port for placeholder reconciliation when multiple targets share the same host.'
         }
       },
       required: ['device_fingerprint']
@@ -771,7 +797,8 @@ const tools = [
         : {}),
       ...(typeof args.device_platform === 'string' && args.device_platform.trim().length > 0
         ? { 'device-platform': args.device_platform }
-        : {})
+        : {}),
+      ...(typeof args.device_port === 'number' ? { 'device-port': args.device_port } : {})
     }),
     subcommand: 'get-device'
   },
@@ -833,7 +860,11 @@ const tools = [
         label: { type: 'string' },
         is_primary: { type: 'boolean' },
         device_hostname: { type: 'string' },
-        device_platform: { type: 'string' }
+        device_platform: { type: 'string' },
+        device_port: {
+          type: 'integer',
+          description: 'SSH port for placeholder reconciliation when multiple targets share the same host.'
+        }
       },
       required: ['project_id', 'device_fingerprint']
     },
@@ -850,7 +881,8 @@ const tools = [
         : {}),
       ...(typeof args.device_platform === 'string' && args.device_platform.trim().length > 0
         ? { 'device-platform': args.device_platform }
-        : {})
+        : {}),
+      ...(typeof args.device_port === 'number' ? { 'device-port': args.device_port } : {})
     }),
     subcommand: 'add-project-resource'
   },
@@ -885,6 +917,40 @@ const tools = [
     }),
     subcommand: 'update-project-resource'
   },
+  {
+    name: 'request_approval_gate',
+    description:
+      'Flip the next queued future objective on this ticket to require manual human approval before it runs. Use sparingly — only when your current work surfaced a question, risk, or decision a human must make before the next objective auto-launches.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_key: { type: 'string' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
+        reason: {
+          type: 'string',
+          description:
+            'Why a human must approve before the next objective runs. Rendered in the awaiting-approval banner verbatim.'
+        },
+        objective_id: {
+          type: 'string',
+          description: 'Optional UUID of a specific future objective to gate. Defaults to the next.'
+        }
+      },
+      required: ['session_key', 'ticket_id', 'reason']
+    },
+    toCliFlags: args => ({
+      'session-key': args.session_key,
+      'ticket-id': args.ticket_id,
+      reason: args.reason,
+      ...(typeof args.objective_id === 'string' && args.objective_id.trim().length > 0
+        ? { 'objective-id': args.objective_id }
+        : {})
+    }),
+    subcommand: 'request-approval-gate'
+  },
   {
     name: 'request_execution',
     description:
@@ -1190,7 +1256,7 @@ async function handleRequest(message) {
       },
       serverInfo: {
         name: 'overlord',
-        version: '0.1.0'
+        version: '0.1.1'
       },
       instructions:
         'Use these tools to drive Overlord ticket workflows through the installed ovld CLI. Names mirror hosted MCP tools (attach, update, deliver, get_device, list_project_resources, …). Session tools need attach/connect. Devices are scoped to organization + user + fingerprint — call get_device before add_project_resource.'

package/plugins/antigravity/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. 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.
+5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook and stay in discussion intent while the ticket is in review. 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.
 
@@ -60,6 +60,14 @@ Event types:
 - `update` for standard progress updates
 - `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
+- `discussion_summary` for important discussion outcomes that should remain visible on the ticket
+- `decision` for explicit non-file decisions made during follow-up discussion
+
+Post-delivery follow-up modes:
+
+- User follow-up messages default to `discussion` intent while the ticket is in review.
+- Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.
+- Use `--follow-up-intent pending_delivery` when implementation is complete but final delivery is still being prepared.
 
 Ask when blocked:
 
@@ -256,12 +264,16 @@ This keeps the ticket feed readable while preserving the full document in versio
 - Always attach first and always deliver last once you are on a ticket.
 - 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.
+- After delivery, answer ordinary questions and clarifications in discussion mode; only begin follow-up execution when the user explicitly asks for file or code changes.
+- When explicit follow-up implementation starts on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before code changes or `--phase execute`.
+- During follow-up execution, post progress updates and record change rationales for each file modified, the same as during initial execution.
+- Record important non-file decisions with `--event-type decision` or `--event-type discussion_summary`.
 - 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`, `--organization-id <id>` is optional — use it only when you want to set a different default organization than the CLI would choose automatically.
 - 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.
+- Delivery is the concluding step. After delivering, stop implementation work unless the user explicitly asks for follow-up execution; once follow-up execution is complete, deliver again.
 
-<!-- version: 0.1.2 -->
+<!-- version: 0.1.4 -->

package/plugins/claude/hooks/hooks.json

@@ -21,6 +21,17 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/stop-hook.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/plugins/claude/scripts/stop-hook.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# Overlord Stop hook — fires when the agent's turn ends.
+# Checks whether the session has pending delivery work and outputs
+# guidance if delivery is needed. Does not force delivery.
+
+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:-}"
+LOG_DIR="${HOME:-}/.ovld/logs"
+LOG_FILE="${LOG_DIR}/stop-hook.log"
+
+log_hook() {
+  mkdir -p "$LOG_DIR" 2>/dev/null || return 0
+  printf '%s [stop] %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$1" >>"$LOG_FILE" 2>/dev/null || true
+}
+
+if [ -z "$OVERLORD_BASE_URL" ] || [ -z "$OVERLORD_TOKEN" ] || [ -z "${TICKET_ID:-}" ]; then
+  log_hook "missing required env, skipping"
+  exit 0
+fi
+
+SESSION_KEY=$(python3 -c "
+import base64, json, os, tempfile
+cwd = os.getcwd().encode()
+encoded = base64.urlsafe_b64encode(cwd).decode().rstrip('=')
+session_file = os.path.join(tempfile.gettempdir(), f'.overlord-session-{encoded}')
+try:
+    with open(session_file) as f:
+        data = json.load(f)
+        print(data.get('sessionKey', ''))
+except Exception:
+    print('')
+" 2>/dev/null)
+
+if [ -z "$SESSION_KEY" ]; then
+  log_hook "no persisted session key, skipping delivery check"
+  exit 0
+fi
+
+PAYLOAD="{\"hookType\":\"Stop\",\"ticketId\":\"$TICKET_ID\",\"sessionKey\":\"$SESSION_KEY\"}"
+
+log_hook "checking delivery status session_key=${SESSION_KEY:0:8}..."
+
+RESPONSE_FILE=$(mktemp "${TMPDIR:-/tmp}/overlord-stop-hook.XXXXXX")
+HTTP_CODE=$(curl -sS -m 5 -o "$RESPONSE_FILE" -w "%{http_code}" \
+  -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")
+CURL_EXIT=$?
+
+if [ "$CURL_EXIT" -eq 0 ] && [ -f "$RESPONSE_FILE" ]; then
+  GUIDANCE=$(python3 -c "
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        data = json.load(f)
+    status = data.get('deliveryStatus')
+    if status and status.get('needed'):
+        print(status.get('reason', 'Pending delivery work detected.'))
+except Exception:
+    pass
+" "$RESPONSE_FILE" 2>/dev/null)
+
+  if [ -n "$GUIDANCE" ]; then
+    log_hook "delivery needed, outputting guidance"
+    echo "[Overlord] $GUIDANCE"
+  else
+    log_hook "no delivery needed"
+  fi
+else
+  log_hook "hook-event POST failed exit=$CURL_EXIT http_status=${HTTP_CODE:-none}"
+fi
+
+rm -f "$RESPONSE_FILE"
+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. The attach response prints JSON to stdout containing `session.sessionKey`. The CLI also persists this key automatically so subsequent `ovld protocol` commands in the same working directory resolve it without `--session-key`. If auto-resolution fails, pass `--session-key <sessionKey>` explicitly on every subsequent call.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working: `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --summary "..." --phase execute`.
-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.
+5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask --session-key <sessionKey> --ticket-id <ticket_id> --question "..."` and stop.
 7. Deliver last with `ovld protocol deliver --session-key <sessionKey> --ticket-id <ticket_id> --summary "..."`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -93,13 +93,17 @@ For the `record-change-rationales` command and full payload shape with optional
 - 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.
 - Include at least one progress update before delivering.
+- After delivery, answer ordinary questions and clarifications in discussion mode; only begin follow-up execution when the user explicitly asks for file or code changes.
+- When explicit follow-up implementation starts on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before code changes or `--phase execute`.
+- During follow-up execution, post progress updates and record change rationales for each file modified, the same as during initial execution.
+- Record important non-file decisions with `--event-type decision` or `--event-type discussion_summary`.
 - 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. See [reference/shell-escaping.md](reference/shell-escaping.md).
 - 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`, `--organization-id <id>` is optional — use it only when you want to set a different default organization than the CLI would choose automatically.
 - 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.
+- Delivery is the concluding step. After delivering, stop implementation work unless the user explicitly asks for follow-up execution; once follow-up execution is complete, deliver again.
 
 ## Reference
 
@@ -109,5 +113,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.6 -->
+<!-- version: 0.5.8 -->
 

package/plugins/claude/skills/overlord-ticket/reference/cli.md

@@ -31,6 +31,14 @@ Event types:
 - `update` for standard progress updates
 - `user_follow_up` — only when the `UserPromptSubmit` hook is unavailable; the hook normally posts follow-ups to the activity feed
 - `alert` for warnings or non-blocking issues
+- `discussion_summary` for important discussion outcomes that should remain visible on the ticket
+- `decision` for explicit non-file decisions made during follow-up discussion
+
+Post-delivery follow-up modes:
+
+- User follow-up messages default to `discussion` intent while the ticket is in review.
+- Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.
+- Use `--follow-up-intent pending_delivery` when implementation is complete but final delivery is still being prepared.
 
 ## Ask
 

package/plugins/cursor/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. The attach response prints JSON to stdout containing `session.sessionKey`. The CLI also persists this key automatically so subsequent `ovld protocol` commands in the same working directory resolve it without `--session-key`. If auto-resolution fails, pass `--session-key <sessionKey>` explicitly on every subsequent call.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working: `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --summary "..." --phase execute`.
-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.
+5. Follow-up messages after the initial ticket are captured automatically by the installed Cursor `beforeSubmitPrompt` hook (see `~/.cursor/hooks.json`) and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask --session-key <sessionKey> --ticket-id <ticket_id> --question "..."` and stop.
 7. Deliver last with `ovld protocol deliver --session-key <sessionKey> --ticket-id <ticket_id> --summary "..."`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -93,13 +93,17 @@ For the `record-change-rationales` command and full payload shape with optional
 - Use `ovld protocol` commands, the plugin commands, and the MCP tool instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
 - Include at least one progress update before delivering.
+- After delivery, answer ordinary questions and clarifications in discussion mode; only begin follow-up execution when the user explicitly asks for file or code changes.
+- When explicit follow-up implementation starts on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before code changes or `--phase execute`.
+- During follow-up execution, post progress updates and record change rationales for each file modified, the same as during initial execution.
+- Record important non-file decisions with `--event-type decision` or `--event-type discussion_summary`.
 - 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. See [reference/shell-escaping.md](reference/shell-escaping.md).
 - 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`, `--organization-id <id>` is optional — use it only when you want to set a different default organization than the CLI would choose automatically.
 - 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.
+- Delivery is the concluding step. After delivering, stop implementation work unless the user explicitly asks for follow-up execution; once follow-up execution is complete, deliver again.
 
 ## Reference
 
@@ -109,5 +113,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.6 -->
+<!-- version: 0.5.8 -->
 

package/plugins/cursor/skills/overlord-ticket/reference/cli.md

@@ -31,6 +31,14 @@ Event types:
 - `update` for standard progress updates
 - `user_follow_up` — only when the Cursor `beforeSubmitPrompt` hook (see `~/.cursor/hooks.json`) is unavailable; the hook normally posts follow-ups to the activity feed
 - `alert` for warnings or non-blocking issues
+- `discussion_summary` for important discussion outcomes that should remain visible on the ticket
+- `decision` for explicit non-file decisions made during follow-up discussion
+
+Post-delivery follow-up modes:
+
+- User follow-up messages default to `discussion` intent while the ticket is in review.
+- Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.
+- Use `--follow-up-intent pending_delivery` when implementation is complete but final delivery is still being prepared.
 
 ## Ask
 

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

@@ -327,7 +327,8 @@ const tools = [
   },
   {
     name: 'update',
-    description: 'Post an Overlord progress update or activity event.',
+    description:
+      'Post an Overlord progress update or activity event. Use begin_follow_up_work to explicitly reopen delivered/review tickets for follow-up execution.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -341,7 +342,15 @@ const tools = [
           type: 'string',
           enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled']
         },
-        event_type: { type: 'string', enum: ['update', 'user_follow_up', 'alert'] },
+        event_type: {
+          type: 'string',
+          enum: ['update', 'user_follow_up', 'alert', 'discussion_summary', 'decision']
+        },
+        begin_follow_up_work: { type: 'boolean' },
+        follow_up_intent: {
+          type: 'string',
+          enum: ['discussion', 'execution', 'pending_delivery']
+        },
         external_url: { type: ['string', 'null'] },
         external_session_id: { type: ['string', 'null'] },
         payload: { type: 'object' },
@@ -355,6 +364,8 @@ const tools = [
       summary: args.summary,
       phase: args.phase,
       'event-type': args.event_type,
+      ...(args.begin_follow_up_work ? { 'begin-follow-up-work': true } : {}),
+      'follow-up-intent': args.follow_up_intent,
       'external-url': args.external_url,
       'external-session-id': args.external_session_id,
       'payload-json': args.payload,
@@ -394,7 +405,7 @@ const tools = [
   {
     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.',
+      "Record a hook lifecycle event for a ticket. Use hookType='Stop' with a session_key to check whether delivery is needed after a turn ends.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -404,7 +415,16 @@ const tools = [
           description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
         },
         prompt: { type: 'string' },
-        turn_index: { type: 'number' }
+        turn_index: { type: 'number' },
+        follow_up_intent: {
+          type: 'string',
+          enum: ['discussion', 'execution', 'pending_delivery']
+        },
+        session_key: {
+          type: 'string',
+          description:
+            'Optional session key for Stop hooks. When provided, the response includes deliveryStatus indicating whether delivery is needed.'
+        }
       },
       required: ['hook_type', 'ticket_id']
     },
@@ -412,7 +432,9 @@ const tools = [
       'hook-type': args.hook_type,
       'ticket-id': args.ticket_id,
       prompt: args.prompt,
-      'turn-index': args.turn_index
+      'turn-index': args.turn_index,
+      'follow-up-intent': args.follow_up_intent,
+      'session-key': args.session_key
     }),
     subcommand: 'hook-event'
   },
@@ -1197,7 +1219,7 @@ async function handleRequest(message) {
       },
       serverInfo: {
         name: 'overlord',
-        version: '0.1.5'
+        version: '0.1.6'
       },
       instructions:
         'Use these tools to drive Overlord ticket workflows through the installed ovld CLI. Names mirror hosted MCP tools (attach, update, deliver, get_device, list_project_resources, …). Session tools need attach/connect. Devices are scoped to organization + user + fingerprint — call get_device before add_project_resource.'

package/plugins/overlord/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. The attach response prints JSON to stdout containing `session.sessionKey`. The CLI also persists this key automatically so subsequent `ovld protocol` commands in the same working directory resolve it without `--session-key`. If auto-resolution fails, pass `--session-key <sessionKey>` explicitly on every subsequent call.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working: `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --summary "..." --phase execute`.
-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.
+5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask --session-key <sessionKey> --ticket-id <ticket_id> --question "..."` and stop.
 7. Deliver last with `ovld protocol deliver --session-key <sessionKey> --ticket-id <ticket_id> --summary "..."`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -93,6 +93,10 @@ For the `record-change-rationales` command and full payload shape with optional
 - Use `ovld protocol` commands and the plugin's MCP tools instead of ad hoc scripts.
 - Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
 - Include at least one progress update before delivering.
+- After delivery, answer ordinary questions and clarifications in discussion mode; only begin follow-up execution when the user explicitly asks for file or code changes.
+- When explicit follow-up implementation starts on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before code changes or `--phase execute`.
+- During follow-up execution, post progress updates and record change rationales for each file modified, the same as during initial execution.
+- Record important non-file decisions with `--event-type decision` or `--event-type discussion_summary`.
 - 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. See [reference/shell-escaping.md](reference/shell-escaping.md).
 - Use `write-context` for facts a future agent session should know.
@@ -100,7 +104,7 @@ For the `record-change-rationales` command and full payload shape with optional
 - If you must run `ovld auth login`, `--organization-id <id>` is optional — use it only when you want to set a different default organization than the CLI would choose automatically.
 - Do not add or commit changes unless the user explicitly asks you to commit.
 - Do not create or rely on a local Codex `AGENTS.md` bundle for Overlord.
-- Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
+- Delivery is the concluding step. After delivering, stop implementation work unless the user explicitly asks for follow-up execution; once follow-up execution is complete, deliver again.
 
 ## Reference
 
@@ -110,5 +114,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.6 -->
+<!-- version: 0.5.8 -->
 

package/plugins/overlord/skills/overlord-ticket/reference/cli.md

@@ -31,6 +31,14 @@ Event types:
 - `update` for standard progress updates
 - `user_follow_up` — only when the `UserPromptSubmit` hook is unavailable; the hook normally posts follow-ups to the activity feed
 - `alert` for warnings or non-blocking issues
+- `discussion_summary` for important discussion outcomes that should remain visible on the ticket
+- `decision` for explicit non-file decisions made during follow-up discussion
+
+Post-delivery follow-up modes:
+
+- User follow-up messages default to `discussion` intent while the ticket is in review.
+- Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.
+- Use `--follow-up-intent pending_delivery` when implementation is complete but final delivery is still being prepared.
 
 ## Ask