overlord-cli 0.2605121205.0 → 0.2605131312.0

package/README.md

@@ -130,6 +130,8 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `attachment-download-url` - get a signed download URL for an existing objective attachment
 - `attachment-upload-file` - prepare, upload, and finalize a local objective attachment in one command
 
+`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|->`.
+
 ## 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

@@ -1122,14 +1122,28 @@ async function protocolDeliver(args) {
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   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)');
+  if (flags['payload-file'] && flags['payload-json']) {
+    throw new Error('Use either --payload-file or --payload-json, not both');
+  }
   const deliverPayload = flags['payload-file']
     ? await readJsonFileOrStdin(String(flags['payload-file']), '--payload-file')
-    : null;
-  const summary =
-    deliverPayload?.summary ??
-    (flags['summary-file']
+    : flags['payload-json']
+      ? parseJsonFlag('--payload-json', flags['payload-json'])
+      : null;
+  if (deliverPayload && (flags.summary || flags['summary-file'])) {
+    throw new Error('Use either payload input or --summary/--summary-file, not both');
+  }
+  const summary = deliverPayload
+    ? (() => {
+        const value = deliverPayload.summary;
+        if (typeof value !== 'string' || !value.trim()) {
+          throw new Error('payload input must include a non-empty summary');
+        }
+        return value;
+      })()
+    : flags['summary-file']
       ? await readTextFileOrStdin(String(flags['summary-file']), '--summary-file')
-      : requireFlag(flags, 'summary', undefined));
+      : requireFlag(flags, 'summary', undefined);
 
   const { platformUrl, bearerToken, localSecret, organizationId } =
     await resolveProtocolAuthForFlags(flags, ticketId);
@@ -1137,10 +1151,10 @@ async function protocolDeliver(args) {
 
   let artifacts = deliverPayload?.artifacts ?? [];
   if (deliverPayload && flags['artifacts-file']) {
-    throw new Error('Use either --payload-file or --artifacts-file, not both');
+    throw new Error('Use either payload input or --artifacts-file, not both');
   }
   if (deliverPayload && flags['artifacts-json']) {
-    throw new Error('Use either --payload-file or --artifacts-json, not both');
+    throw new Error('Use either payload input or --artifacts-json, not both');
   }
   if (flags['artifacts-file']) {
     artifacts = await readJsonFileOrStdin(String(flags['artifacts-file']), '--artifacts-file');
@@ -1149,7 +1163,7 @@ async function protocolDeliver(args) {
   }
 
   if (deliverPayload && (flags['change-rationales-file'] || flags['change-rationales-json'])) {
-    throw new Error('Use either --payload-file or change-rationale flags, not both');
+    throw new Error('Use either payload input or change-rationale flags, not both');
   }
 
   const changeRationales =
@@ -1556,6 +1570,34 @@ async function protocolPrompt(args) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// discuss-objective (mark a draft objective as submitted)
+// ---------------------------------------------------------------------------
+
+async function protocolDiscussObjective(args) {
+  const flags = parseFlags(args);
+  const ticketId = requireFlag(flags, 'ticket-id', process.env.TICKET_ID);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
+  const timeoutMs = resolveTimeout(flags);
+
+  const body = {
+    ticketId,
+    ...(flags['objective-id'] ? { objectiveId: String(flags['objective-id']) } : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/discuss-objective',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
 // ---------------------------------------------------------------------------
 // create (create follow-up ticket draft only)
 // ---------------------------------------------------------------------------
@@ -1747,6 +1789,7 @@ Subcommands:
   connect                   Start a lightweight session without full context
   load-context              Read ticket context without creating a session
   search-tickets            Find tickets by keyword, status, project, creator, or update date
+  discuss-objective          Mark a draft objective as submitted (ready for review/execution)
   create                    Create a draft ticket without attaching (follow-up or standalone)
   prompt                    Create a ticket and attach to it immediately
   update                    Post progress, activity events, and optional change rationales
@@ -1943,6 +1986,7 @@ deliver:
     --session-key <key>
     --ticket-id <ticket_id>
     --summary <text> or --summary-file <path|->
+    or: --payload-json <json>
     or: --payload-file <path|-> containing { summary, artifacts, changeRationales }
   Optional:
     --artifacts-json <json>
@@ -1951,9 +1995,10 @@ deliver:
     --change-rationales-file <path|->
     --skip-file-change-check  Bypass local git vs changeRationales validation
   Notes:
+    Use --payload-json when the full delivery JSON fits comfortably inline.
     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.
+    Do not combine --payload-json/--payload-file with --summary/--summary-file, --artifacts-json/--artifacts-file, or change-rationale flags.
     In a git workspace, deliver validates that changed files are represented by changeRationales unless skipped.
 
 prompt:
@@ -1982,6 +2027,16 @@ prompt:
   Returns:
     New ticket/session JSON plus SESSION_KEY and TICKET_ID on stderr when available
 
+discuss-objective:
+  Purpose:
+    Mark the latest draft objective on a ticket as "submitted", indicating the objective
+    has been discussed and is ready for review or execution. Does NOT start execution —
+    use \`attach\` to begin execution.
+  Required:
+    --ticket-id <ticket_id>
+  Optional:
+    --objective-id <id>       Target a specific draft objective by UUID
+
 create:
   Purpose:
     Create a draft ticket without attaching to it.
@@ -2073,6 +2128,8 @@ Examples:
   ovld protocol connect --ticket-id 1:899
   ovld protocol load-context --ticket-id 1:899
   ovld protocol search-tickets --query "auth refactor" --status next-up,execute --limit 10
+  ovld protocol discuss-objective --ticket-id 1:899
+  ovld protocol discuss-objective --ticket-id 1:899 --objective-id <objective-uuid>
   ovld protocol create --agent codex --objective "Capture follow-up work from this repo"
   ovld protocol create --agent codex --session-key <key> --ticket-id <ticket_id> --objective "Capture follow-up work"
   ovld protocol prompt --agent codex --objective "Implement user auth" --priority high
@@ -2089,6 +2146,7 @@ Examples:
   ovld protocol attachment-download-url --session-key <key> --ticket-id <ticket_id> --attachment-id <attachment-id>
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done"
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --artifacts-file ./artifacts.json
+  ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-json '{"summary":"Done","artifacts":[{"type":"note","label":"Delivery","content":"..."}]}'
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-file ./deliver.json
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-file -
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --skip-file-change-check
@@ -2121,6 +2179,10 @@ Examples:
     await protocolSearchTickets(args);
     return;
   }
+  if (subcommand === 'discuss-objective') {
+    await protocolDiscussObjective(args);
+    return;
+  }
   if (subcommand === 'create' || subcommand === 'create-ticket') {
     await protocolCreateTicket(args);
     return;

package/bin/_cli/setup.mjs

@@ -88,7 +88,7 @@ If you receive a prompt with a specified ticket ID, adhere to the following. If
      --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 @@"}]}]'
    \`\`\`
 
-   For larger or quote-sensitive deliveries, prefer a single JSON payload on stdin:
+   Use \`--payload-json\` when the full delivery object fits comfortably inline. For larger or quote-sensitive deliveries, prefer a single JSON payload on stdin:
    \`\`\`bash
    ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --payload-file -
    \`\`\`
@@ -261,7 +261,7 @@ When done, deliver with artifacts and change rationales:
 \`\`\`bash
 ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --summary "Narrative: what you did, next steps." --artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' --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 @@"}]}]'
 \`\`\`
-For larger delivery JSON, prefer \`--payload-file -\` with stdin so no scratch file needs to be created or removed. If you use a JSON file for delivery transport, keep it ephemeral scratch data outside the repository and remove it after the protocol call.
+Use \`--payload-json\` for compact inline delivery objects. For larger delivery JSON, prefer \`--payload-file -\` with stdin so no scratch file needs to be created or removed. If you use a JSON file for delivery transport, keep it ephemeral scratch data outside the repository and remove it after the protocol call.
 
 Rules:
 - Always attach first and deliver last.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605121205.0",
+  "version": "0.2605131312.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,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Overlord ticket protocol workflow for Claude Code — attach/update/ask/deliver, slash commands, and hook-driven activity capture.",
   "author": {
     "name": "Cooperativ",

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

@@ -1,28 +1,95 @@
 #!/bin/bash
 # Overlord UserPromptSubmit hook — fires before Claude processes each user turn.
+# Claude Code does not expose turn_number in the hook body; we persist the last
+# posted turnIndex per session_id and send (last + 1). The first submit is
+# turnIndex 0 (initial injected ticket/objective prompt), which
+# POST /api/protocol/hook-event skips — same contract as the Cursor hook.
 
 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:-}"
+HOOK_NAME="claude"
+LOG_DIR="${HOME:-}/.ovld/logs"
+LOG_FILE="${LOG_DIR}/user-prompt-submit-hook.log"
 
-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
+log_hook() {
+  mkdir -p "$LOG_DIR" 2>/dev/null || return 0
+  printf '%s [%s] %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$HOOK_NAME" "$1" >>"$LOG_FILE" 2>/dev/null || true
+}
+
+PROMPT_LEN=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(len((json.load(sys.stdin).get('prompt') or '').strip()))" 2>/dev/null || echo "0")
+SESSION_ID=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('session_id') or 'unknown')" 2>/dev/null || echo "unknown")
+log_hook "received submit session_id=$SESSION_ID prompt_len=$PROMPT_LEN ticket_present=$([ -n "${TICKET_ID:-}" ] && echo yes || echo no)"
+
+if [ -z "$OVERLORD_BASE_URL" ] || [ -z "$OVERLORD_TOKEN" ] || [ -z "${TICKET_ID:-}" ]; then
+  log_hook "missing required env base_url=$([ -n "$OVERLORD_BASE_URL" ] && echo yes || echo no) token=$([ -n "$OVERLORD_TOKEN" ] && echo yes || echo no) ticket=$([ -n "${TICKET_ID:-}" ] && echo yes || echo no)"
   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 \
+  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 '').strip()
+if not text:
+    sys.exit(0)
+
+sid = body.get('session_id') or 'unknown'
+state_dir = os.path.join(os.path.expanduser('~'), '.ovld', 'claude-user-prompt-hook')
+os.makedirs(state_dir, exist_ok=True)
+path = os.path.join(state_dir, hashlib.sha256(sid.encode()).hexdigest())
+last_posted = -1
+try:
+    with open(path, encoding='utf-8') as handle:
+        raw = (handle.read() or '').strip()
+        if raw != '':
+            last_posted = int(raw)
+except Exception:
+    last_posted = -1
+
+turn_index = last_posted + 1
+with open(path, 'w', encoding='utf-8') as handle:
+    handle.write(str(turn_index))
+
+tid = os.environ.get('TICKET_ID', '')
+print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': turn_index}))
+" 2>/dev/null
+  )
+  if [ -z "$PAYLOAD" ]; then
+    log_hook "failed to build hook-event payload from submit body"
+    exit 0
+  fi
+
+  PAYLOAD_TURN=$(printf '%s' "$PAYLOAD" | python3 -c "import json,sys; print(json.load(sys.stdin).get('turnIndex', 'unknown'))" 2>/dev/null || echo "unknown")
+  log_hook "built payload turn=$PAYLOAD_TURN posting hook-event"
+  (
+    RESPONSE_FILE=$(mktemp "${TMPDIR:-/tmp}/overlord-hook-event.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" \
-      >/dev/null 2>&1 &
+      -d "$PAYLOAD")
+    CURL_EXIT=$?
+    RESPONSE_PREVIEW=$(python3 -c "from pathlib import Path; import sys; p=Path(sys.argv[1]); text=p.read_text(encoding='utf-8', errors='replace') if p.exists() else ''; text=' '.join(text.split()); print(text[:200])" "$RESPONSE_FILE" 2>/dev/null || echo '')
+    rm -f "$RESPONSE_FILE"
+    if [ "$CURL_EXIT" -eq 0 ]; then
+      log_hook "hook-event POST finished exit=0 http_status=$HTTP_CODE response_preview=$RESPONSE_PREVIEW"
+    else
+      log_hook "hook-event POST failed exit=$CURL_EXIT http_status=${HTTP_CODE:-none} response_preview=$RESPONSE_PREVIEW"
+    fi
+  ) >/dev/null 2>&1 &
     disown
-  fi
 fi
 
 exit 0

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

@@ -75,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 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.
+`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. Use `--payload-json` when the full delivery object fits comfortably inline. 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
 
@@ -99,7 +99,7 @@ Always include `changeRationales` when delivering. Optionally include them on up
 
 Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact.
 
-These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. For larger full delivery payloads, prefer `--payload-file -` so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
+These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. Use `--payload-json` for compact full delivery payloads, or `--payload-file -` when the JSON is larger or quote-sensitive so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
 
 ```bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
@@ -182,4 +182,4 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - 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.8 -->
+<!-- version: 0.4.9 -->

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

@@ -1,7 +1,8 @@
 #!/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).
+# Cursor does not expose Claude's turn_number; we persist the last posted turnIndex per conversation_id
+# and send (last + 1). The first submit is turnIndex 0 (initial injected ticket/objective prompt), which
+# POST /api/protocol/hook-event skips — same contract as Claude's turn_number 0.
 
 BODY=$(cat -)
 
@@ -31,17 +32,21 @@ 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())
+last_posted = -1
 try:
     with open(path, encoding='utf-8') as handle:
-        n = int((handle.read() or '0').strip() or '0')
+        raw = (handle.read() or '').strip()
+        if raw != '':
+            last_posted = int(raw)
 except Exception:
-    n = 0
-n += 1
+    last_posted = -1
+
+turn_index = last_posted + 1
 with open(path, 'w', encoding='utf-8') as handle:
-    handle.write(str(n))
+    handle.write(str(turn_index))
 
 tid = os.environ.get('TICKET_ID', '')
-print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': n}))
+print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': turn_index}))
 " 2>/dev/null
   )
   if [ -n "$PAYLOAD" ]; then

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

@@ -61,7 +61,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.
+`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. Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed.
 
 ## Mode 2: Asked From Chat To Use Overlord
 
@@ -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.8 -->
+<!-- version: 0.4.9 -->

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

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Chat-driven access to Overlord ticket protocol workflows with hook-driven activity capture.",
   "author": {
     "name": "Cooperativ",

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

@@ -5,24 +5,55 @@ BODY=$(cat -)
 OVERLORD_BASE_URL="${OVERLORD_URL:-}"
 OVERLORD_TOKEN="${OVERLORD_ACCESS_TOKEN:-}"
 OVERLORD_LOCAL_SECRET="${OVERLORD_LOCAL_SECRET:-}"
+HOOK_NAME="codex"
+LOG_DIR="${HOME:-}/.ovld/logs"
+LOG_FILE="${LOG_DIR}/user-prompt-submit-hook.log"
+
+log_hook() {
+  mkdir -p "$LOG_DIR" 2>/dev/null || return 0
+  printf '%s [%s] %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$HOOK_NAME" "$1" >>"$LOG_FILE" 2>/dev/null || true
+}
 
 TURN=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('turn_number', 0))" 2>/dev/null || echo "0")
+PROMPT_LEN=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(len((json.load(sys.stdin).get('prompt') or '').strip()))" 2>/dev/null || echo "0")
+log_hook "received submit turn=$TURN prompt_len=$PROMPT_LEN ticket_present=$([ -n "${TICKET_ID:-}" ] && echo yes || echo no)"
 if [ "$TURN" = "0" ]; then
+  log_hook "skipping initial submit turn=0"
+  exit 0
+fi
+
+if [ -z "$OVERLORD_BASE_URL" ] || [ -z "$OVERLORD_TOKEN" ] || [ -z "${TICKET_ID:-}" ]; then
+  log_hook "missing required env base_url=$([ -n "$OVERLORD_BASE_URL" ] && echo yes || echo no) token=$([ -n "$OVERLORD_TOKEN" ] && echo yes || echo no) ticket=$([ -n "${TICKET_ID:-}" ] && echo yes || echo no)"
   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 \
+  if [ -z "$PAYLOAD" ]; then
+    log_hook "failed to build hook-event payload from submit body"
+    exit 0
+  fi
+
+  PAYLOAD_TURN=$(printf '%s' "$PAYLOAD" | python3 -c "import json,sys; print(json.load(sys.stdin).get('turnIndex', 'unknown'))" 2>/dev/null || echo "unknown")
+  log_hook "built payload turn=$PAYLOAD_TURN posting hook-event"
+  (
+    RESPONSE_FILE=$(mktemp "${TMPDIR:-/tmp}/overlord-hook-event.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" \
-      >/dev/null 2>&1 &
+      -d "$PAYLOAD")
+    CURL_EXIT=$?
+    RESPONSE_PREVIEW=$(python3 -c "from pathlib import Path; import sys; p=Path(sys.argv[1]); text=p.read_text(encoding='utf-8', errors='replace') if p.exists() else ''; text=' '.join(text.split()); print(text[:200])" "$RESPONSE_FILE" 2>/dev/null || echo '')
+    rm -f "$RESPONSE_FILE"
+    if [ "$CURL_EXIT" -eq 0 ]; then
+      log_hook "hook-event POST finished exit=0 http_status=$HTTP_CODE response_preview=$RESPONSE_PREVIEW"
+    else
+      log_hook "hook-event POST failed exit=$CURL_EXIT http_status=${HTTP_CODE:-none} response_preview=$RESPONSE_PREVIEW"
+    fi
+  ) >/dev/null 2>&1 &
     disown
-  fi
 fi
 
 exit 0

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

@@ -65,7 +65,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. Use `--payload-json` when the full delivery object fits comfortably inline. 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.
 
 ## Mode 2: Asked From Chat To Use Overlord
 
@@ -111,7 +111,7 @@ Always include `changeRationales` when delivering. Optionally include them on up
 
 Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact.
 
-These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. For larger full delivery payloads, prefer `--payload-file -` so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
+These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. Use `--payload-json` for compact full delivery payloads, or `--payload-file -` when the JSON is larger or quote-sensitive so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
 
 ```bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
@@ -158,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.8 -->
+<!-- version: 0.4.9 -->