@adhdev/daemon-core 0.9.82-rc.46 → 0.9.82-rc.460

package/src/providers/sdk/v1/schemas/primitives/acp-session-protocol-v1.json

@@ -0,0 +1,131 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:acp/session-protocol@1",
+  "title": "acp/session-protocol — v1",
+  "description": "Describes how to detect ACP stdio session status from line-oriented process output. Supports json-rpc, plain-text, and mcp prompt styles. The daemon compiles the regex patterns at builder time and uses them at runtime to classify each incoming line as idle, generating, or an error verdict.",
+  "type": "object",
+  "required": ["$schema"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "const": "adhdev:acp/session-protocol@1"
+    },
+    "idlePattern": {
+      "type": "object",
+      "description": "Regex pattern that matches a line emitted when the agent finishes a turn and is waiting for the next user message.",
+      "required": ["regex"],
+      "additionalProperties": false,
+      "properties": {
+        "regex": {
+          "type": "string",
+          "description": "ECMAScript regex source. Daemon compiles with the flags below."
+        },
+        "flags": {
+          "type": "string",
+          "pattern": "^[gimsuy]*$",
+          "default": "i",
+          "description": "Optional ECMAScript regex flags (default: 'i')."
+        },
+        "description": {
+          "type": "string",
+          "description": "Author-facing note explaining when this pattern fires."
+        }
+      }
+    },
+    "generatingPattern": {
+      "type": "object",
+      "description": "Regex pattern that matches a line emitted while the agent is actively working (streaming tokens, calling tools, etc.).",
+      "required": ["regex"],
+      "additionalProperties": false,
+      "properties": {
+        "regex": {
+          "type": "string",
+          "description": "ECMAScript regex source."
+        },
+        "flags": {
+          "type": "string",
+          "pattern": "^[gimsuy]*$",
+          "default": "i"
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    "errorPatterns": {
+      "type": "array",
+      "description": "List of error-signal patterns. Each entry provides a regex and the status verdict to return on match. Checked in order; first match wins.",
+      "items": {
+        "type": "object",
+        "required": ["regex", "verdict"],
+        "additionalProperties": false,
+        "properties": {
+          "regex": {
+            "type": "string",
+            "description": "ECMAScript regex source."
+          },
+          "flags": {
+            "type": "string",
+            "pattern": "^[gimsuy]*$",
+            "default": "i"
+          },
+          "verdict": {
+            "type": "string",
+            "enum": ["idle", "generating", "waiting_approval"],
+            "description": "Status verdict to return when this error pattern fires."
+          },
+          "description": {
+            "type": "string",
+            "description": "Author-facing note explaining what condition this pattern represents."
+          }
+        }
+      }
+    },
+    "promptStyle": {
+      "description": "Wire format used by the agent on stdio. Affects how lines are parsed (e.g. json-rpc messages are newline-delimited JSON objects; plain-text is freeform; mcp is the Model Context Protocol framing).",
+      "default": "plain-text",
+      "oneOf": [
+        {
+          "const": "json-rpc",
+          "title": "JSON-RPC",
+          "description": "Each line is a newline-delimited JSON-RPC 2.0 object."
+        },
+        {
+          "const": "plain-text",
+          "title": "Plain text",
+          "description": "Freeform text output — patterns are matched against each line directly."
+        },
+        {
+          "const": "mcp",
+          "title": "MCP",
+          "description": "Model Context Protocol stdio framing (Content-Length + JSON body)."
+        }
+      ]
+    },
+    "messageDelimiter": {
+      "type": "string",
+      "default": "\n",
+      "description": "String used to delimit messages in the stdio stream. Defaults to newline ('\\n'). For MCP framing this is effectively the Content-Length header separator, but the builder uses this field to split incoming bytes into logical lines for regex matching."
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:acp/session-protocol@1",
+      "promptStyle": "plain-text",
+      "idlePattern": { "regex": "^\\$\\s*$", "flags": "m", "description": "Shell prompt — agent returned to idle" },
+      "generatingPattern": { "regex": "thinking|processing|calling tool", "flags": "i" },
+      "errorPatterns": [
+        { "regex": "error:|exception:", "flags": "i", "verdict": "idle", "description": "Unrecoverable error — treat as idle so user can retry" }
+      ]
+    },
+    {
+      "$schema": "adhdev:acp/session-protocol@1",
+      "promptStyle": "json-rpc",
+      "idlePattern": { "regex": "\"method\"\\s*:\\s*\"agent/ready\"" },
+      "generatingPattern": { "regex": "\"method\"\\s*:\\s*\"agent/(?:thinking|toolCall)\"" },
+      "errorPatterns": [
+        { "regex": "\"method\"\\s*:\\s*\"agent/approvalRequired\"", "verdict": "waiting_approval" }
+      ]
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/native-history-codex-rollout-v1.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:native-history/codex-rollout@1",
+  "title": "native-history/codex-rollout — v1",
+  "description": "Declares that the provider's chat history is canonically owned by Codex's rollout JSONL files at `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`. The daemon's chat-history layer routes readChat through the configured `scripts.readSession` adapter, which is expected to honour the format contract documented at:\n\n  - One JSONL line per record. First line is `session_meta`; subsequent lines are `response_item` payloads.\n  - Workspace scoping by matching `session_meta.payload.cwd` to the live session's working directory (with symlink expansion via `fs.realpathSync.native`).\n  - spawnAt grace window (default 3000ms): reject workspace-only candidates older than `spawnAt - graceMs`.\n  - excludeInProgressTurn: strip trailing in-flight assistant/tool records when set.\n  - Silent-skip malformed JSONL lines (mirrors codex's concurrent-write tolerance).\n\nThis primitive is currently script-delegated. A daemon-side built-in adapter may replace `_shared/native_history.js` in a later phase; the schema is forward-compatible.",
+  "type": "object",
+  "required": ["$schema", "format", "watchPath", "mode"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "adhdev:native-history/codex-rollout@1" },
+    "format": {
+      "const": "codex-rollout",
+      "description": "Identifies the rollout-jsonl contract version. Sync with `payload.cli_version` interpretation in adapter code."
+    },
+    "watchPath": {
+      "type": "string",
+      "default": "~/.codex/sessions",
+      "description": "Filesystem root the daemon watches for new rollout files. Defaults to the canonical Codex path; override only when the user has a custom CODEX_HOME."
+    },
+    "mode": {
+      "const": "native-source",
+      "description": "Codex JSONL is authoritative for sealed turns; PTY parsing fills the in-flight tail."
+    },
+    "contractVersion": {
+      "type": "string",
+      "default": "1.0",
+      "description": "Adapter contract version; bump in lockstep with breaking changes to Codex's rollout-record schema."
+    },
+    "spawnGraceMs": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 60000,
+      "default": 3000,
+      "description": "Workspace-only candidates with mtime older than `spawnAt - spawnGraceMs` are rejected as stale. Codex's default is 3000ms; only override if you observe a different race window."
+    },
+    "excludeInProgressTurn": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true, trailing assistant/tool records produced mid-turn are stripped so paused approvals don't show as completed."
+    },
+    "scripts": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Pointers to the JS adapter functions (until a daemon-side built-in replaces them).",
+      "properties": {
+        "readSession": { "type": "string", "default": "readCodexNativeHistory" },
+        "listSessions": { "type": "string", "default": "listCodexNativeHistory" }
+      }
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:native-history/codex-rollout@1",
+      "format": "codex-rollout",
+      "watchPath": "~/.codex/sessions",
+      "mode": "native-source",
+      "contractVersion": "1.0",
+      "spawnGraceMs": 3000,
+      "excludeInProgressTurn": true,
+      "scripts": {
+        "readSession": "readCodexNativeHistory",
+        "listSessions": "listCodexNativeHistory"
+      }
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/tui-approval-squash-v1.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/approval-squash@1",
+  "title": "tui/approval-squash — v1",
+  "description": "Recognises approval modals whose buttons + cues have been collapsed by the terminal renderer into a single squashed lowercase-alnum string (e.g. `1yescontinue2noquit`, `doyoutrustthecontentsofthisdirectory`). Codex is the canonical example: when the terminal re-flows the modal across narrow widths, the rendered text loses whitespace/punctuation but the byte order is preserved. The builder applies the manifest's `cues` to detect the modal, then the `buttonRules` to reconstruct labels.\n\nThe normalisation function is fixed: `String(value).toLowerCase().replace(/[^a-z0-9]+/g, '')`. Authors only declare which compact substrings count as cues and how to map known compact button runs back into labels.",
+  "type": "object",
+  "required": ["$schema", "cues", "buttonRules"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "adhdev:tui/approval-squash@1" },
+    "cues": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Compact substrings or regexes that, if found in the compacted text, identify this as an approval modal. Mix freely — daemon tries every cue.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["compact"],
+        "properties": {
+          "compact": { "type": "string", "description": "Compacted (lowercase-alnum) substring." },
+          "kind": { "enum": ["substring", "regex"], "default": "substring" },
+          "label": { "type": "string", "description": "Optional category label, e.g. 'trust-folder'." },
+          "messageWhenMatched": { "type": "string", "description": "Human-readable message the modal builder returns when this cue matches. Use this to recover the original prose from the compacted form." }
+        }
+      }
+    },
+    "footers": {
+      "type": "array",
+      "description": "Optional compact substrings that must also be present in the compacted text to count as a real modal (e.g. 'pressentertocontinue'). Default: at least one cue is sufficient.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["compact"],
+        "properties": {
+          "compact": { "type": "string" },
+          "kind": { "enum": ["substring", "regex"], "default": "substring" }
+        }
+      },
+      "default": []
+    },
+    "buttonRules": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Rules that map a recognised compact substring to the original labels. Tried in order; first match wins. Use this for the cases where the terminal collapsed both buttons into one rendering blob.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["compact", "labels"],
+        "properties": {
+          "compact": { "type": "string", "description": "Compact substring (e.g. '1yescontinue2noquit') OR regex source when kind=regex." },
+          "kind": { "enum": ["substring", "regex"], "default": "substring" },
+          "labels": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" },
+            "description": "Original human-readable labels in display order."
+          }
+        }
+      }
+    },
+    "scope": {
+      "default": "tail-window",
+      "enum": ["tail-window", "whole-screen"]
+    },
+    "tailWindowLines": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 64,
+      "default": 24
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/approval-squash@1",
+      "cues": [
+        { "compact": "doyoutrustthecontentsofthisdirectory", "label": "trust-folder", "messageWhenMatched": "Do you trust the contents of this directory?" },
+        { "compact": "workingwithuntrustedcontents",          "label": "untrusted-content", "messageWhenMatched": "Working with untrusted contents" },
+        { "compact": "switchtogpt",                            "kind": "regex", "label": "rate-limit" }
+      ],
+      "footers": [
+        { "compact": "pressentertocontinue" },
+        { "compact": "esctocancel" }
+      ],
+      "buttonRules": [
+        { "compact": "1yescontinue2noquit",       "labels": ["Yes, continue", "No, quit"] },
+        { "compact": "1approveandrun2deny",       "labels": ["Approve and run", "Deny"] },
+        { "compact": "1alwaysapprove2approve3deny", "labels": ["Always approve", "Approve", "Deny"] }
+      ]
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/tui-assistant-block-v1.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/assistant-block@1",
+  "title": "tui/assistant-block — v1",
+  "description": "Declares how to extract assistant turns from the rendered transcript. The block starts at a marker (e.g. Claude `⏺`, Codex `Codex` heading) and ends at either the next user prompt or the next block marker. Each captured block becomes one assistant chat message.",
+  "type": "object",
+  "required": ["$schema", "startMarker"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "adhdev:tui/assistant-block@1" },
+    "startMarker": {
+      "description": "Where an assistant block begins. Can be a plain substring or a regex.",
+      "oneOf": [
+        { "type": "string", "description": "Plain substring." },
+        {
+          "type": "object",
+          "required": ["regex"],
+          "additionalProperties": false,
+          "properties": {
+            "regex": { "type": "string" },
+            "flags": { "type": "string", "pattern": "^[gimsuy]*$", "default": "m" }
+          }
+        }
+      ]
+    },
+    "endMarker": {
+      "description": "Where the block ends. Common: next prompt marker or another startMarker. Defaults to \"next-user-prompt\".",
+      "default": "next-user-prompt",
+      "oneOf": [
+        { "const": "next-user-prompt", "title": "Stop at the next prompt marker line" },
+        { "const": "next-start-marker", "title": "Stop at the next startMarker" },
+        { "type": "string", "title": "Plain substring marker" },
+        {
+          "type": "object",
+          "required": ["regex"],
+          "additionalProperties": false,
+          "properties": {
+            "regex": { "type": "string" },
+            "flags": { "type": "string", "pattern": "^[gimsuy]*$", "default": "m" }
+          }
+        }
+      ]
+    },
+    "skipKinds": {
+      "type": "array",
+      "description": "Which sub-blocks to skip when classifying assistant turns. Tool calls and thinking blocks are usually classified separately via tui/tool-block and tui/thinking-block.",
+      "items": { "enum": ["tool", "thinking", "system"] },
+      "default": ["tool"]
+    },
+    "headerLines": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Number of header lines after the startMarker to skip when extracting content (e.g. Codex's `Codex\\n<timestamp>` header)."
+    },
+    "trimEmptyLeading": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether to strip leading whitespace-only lines from the captured content."
+    },
+    "trimEmptyTrailing": {
+      "type": "boolean",
+      "default": true
+    },
+    "kind": {
+      "type": "string",
+      "default": "standard",
+      "description": "The CliChatMessage.kind value to stamp on captured blocks."
+    },
+    "minLength": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1,
+      "description": "Discard blocks whose captured content is shorter than this. Set higher if you have noisy short blocks (e.g. single-character paints)."
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/assistant-block@1",
+      "startMarker": "⏺",
+      "endMarker": "next-user-prompt",
+      "skipKinds": ["tool", "thinking"]
+    },
+    {
+      "$schema": "adhdev:tui/assistant-block@1",
+      "startMarker": { "regex": "^Codex\\s*$" },
+      "endMarker": "next-start-marker",
+      "headerLines": 1
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/tui-cue-ordering-v1.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/cue-ordering@1",
+  "title": "TUI cue ordering",
+  "description": "Declares the relative spatial order cues must occur in to be considered evidence of a state. Addresses the canonical 'idle-while-Working-still-visible' regression: spinner cue near bottom + settled prompt cue ABOVE spinner → still generating; spinner ABOVE settled prompt → stale.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["rules"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/cue-ordering@1" },
+    "rules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "cues", "verdict"],
+        "properties": {
+          "name": { "type": "string" },
+          "cues": {
+            "type": "array",
+            "minItems": 2,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["primitive", "position"],
+              "properties": {
+                "primitive": {
+                  "type": "string",
+                  "description": "Reference to another primitive $id (e.g. adhdev:tui/spinner@1)."
+                },
+                "position": {
+                  "enum": ["above", "below", "same-line", "any"],
+                  "description": "Spatial relation to the NEXT cue in this array."
+                }
+              }
+            }
+          },
+          "verdict": {
+            "enum": ["generating", "idle", "approval", "ignore"],
+            "description": "What to return when this ordering matches."
+          }
+        }
+      }
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-dispatch-order-v1.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/dispatch-order@1",
+  "title": "TUI dispatch order",
+  "description": "Declares the order in which detectStatus consults its primitive groups. Default order — spinner → modal → settled-prompt — is what fixed the sprint-2026-06 'idle while Working visible' regression and must be expressible in declarative manifests.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["order"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/dispatch-order@1" },
+    "order": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "Ordered list of primitive group identifiers. Daemon evaluates them in this order; first matching group decides the verdict.",
+      "items": {
+        "enum": [
+          "spinner",
+          "modal",
+          "settled-prompt",
+          "cue-ordering",
+          "error-detection",
+          "approval-stitching"
+        ]
+      }
+    },
+    "onNoMatch": {
+      "enum": ["idle", "unknown", "preserve-last"],
+      "default": "idle"
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-footer-chrome-v1.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/footer-chrome@1",
+  "title": "TUI footer chrome",
+  "description": "Declares the lines/regions that constitute the persistent CLI footer (input hint, model badge, token counter, etc.). Used to mask the footer out before running prompt-marker / spinner / settled-prompt matchers, so chrome text never gets misclassified as agent state.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["regions"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/footer-chrome@1" },
+    "regions": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Ordered list of regions; the first match wins. Each region is identified by a sentinel + bounded line span.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["sentinel"],
+        "properties": {
+          "name": { "type": "string" },
+          "sentinel": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["pattern"],
+            "properties": {
+              "pattern": { "type": "string", "description": "Regex source." },
+              "flags": { "type": "string" }
+            }
+          },
+          "spanLinesBefore": { "type": "integer", "minimum": 0, "default": 0 },
+          "spanLinesAfter": { "type": "integer", "minimum": 0, "default": 0 },
+          "anchor": {
+            "enum": ["bottom", "any"],
+            "default": "bottom",
+            "description": "When 'bottom', region must be within the last N lines of the screen."
+          },
+          "bottomLookbackLines": { "type": "integer", "minimum": 1, "default": 12 }
+        }
+      }
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-index-finder-v1.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/index-finder@1",
+  "title": "TUI index finder",
+  "description": "Locates the most-recent occurrence of a cue inside a rendered screen by line index — exposed as a helper primitive used by cue-ordering, settled-prompt, and visible-region. Authors don't reference this primitive directly in manifests; the runtime uses it internally when evaluating spatial relations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["strategy"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/index-finder@1" },
+    "strategy": {
+      "enum": ["last-match", "first-match", "tail-window-only"],
+      "default": "last-match"
+    },
+    "tailWindowLines": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 12,
+      "description": "Used when strategy=tail-window-only."
+    },
+    "ignoreInsideRegions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Primitive $ids whose matched regions should be ignored (e.g. mask out footer-chrome lines before finding the cue)."
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-modal-v1.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/modal@1",
+  "title": "tui/modal — v1",
+  "description": "Declares how to extract an approval modal from the screen. Codex `Do you want to proceed?` + numbered list, Claude approval frame with explicit separators, Antigravity `agy wants to run:` are all expressible. The builder returns null when no modal is visible; daemon then keeps status non-waiting.",
+  "type": "object",
+  "required": ["$schema", "questionPattern", "buttonPattern"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "adhdev:tui/modal@1" },
+    "questionPattern": {
+      "type": "string",
+      "description": "Regex source matching the question line that introduces the modal. Examples: `Do you want to proceed\\?`, `Do you trust the contents of this directory\\?`, `agy wants to run:`."
+    },
+    "questionFlags": {
+      "type": "string",
+      "pattern": "^[gimsuy]*$",
+      "default": "i"
+    },
+    "questionVariants": {
+      "type": "array",
+      "description": "Additional regex sources that count as the same approval kind. Each is tried in order; the first match wins.",
+      "items": {
+        "type": "object",
+        "required": ["regex"],
+        "additionalProperties": false,
+        "properties": {
+          "regex": { "type": "string" },
+          "flags": { "type": "string", "pattern": "^[gimsuy]*$", "default": "i" },
+          "label": { "type": "string", "description": "Optional category label, e.g. \"trust-folder\", \"tool-approval\"." }
+        }
+      },
+      "default": []
+    },
+    "buttonPattern": {
+      "type": "string",
+      "description": "Regex source matching a single button line. Capture group 1 is the button label. Example: `^[\\s❯>]*\\d+\\.\\s+(.+)$`."
+    },
+    "buttonLabelGroup": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1,
+      "description": "Capture group number to use as the button label when `buttonPattern` contains non-label groups such as selected-row markers."
+    },
+    "buttonFlags": {
+      "type": "string",
+      "pattern": "^[gimsuy]*$",
+      "default": "m"
+    },
+    "inlineButtonPattern": {
+      "type": "string",
+      "description": "Fallback regex for terminals that render all options on a single line (e.g. Antigravity's `[0] skip [1] yes [2] no [3] still using` survey). Used only when per-line extraction collects fewer than `minButtons`. The `g` flag is forced on by the builder; capture group 1 is the label."
+    },
+    "inlineButtonFlags": {
+      "type": "string",
+      "pattern": "^[gimsuy]*$",
+      "default": "gi"
+    },
+    "scope": {
+      "default": "between-last-two-separators",
+      "description": "Where on the screen the question + buttons must appear together.",
+      "oneOf": [
+        {
+          "const": "between-last-two-separators",
+          "title": "Between last two separators",
+          "description": "Most robust for Claude/Antigravity-style framed modals."
+        },
+        {
+          "const": "window-around-question",
+          "title": "Window around the question line",
+          "description": "Matches when the modal is announced by an explicit question line; collects buttons in the N lines below."
+        },
+        {
+          "const": "whole-screen",
+          "title": "Whole screen",
+          "description": "Use sparingly; tends to false-positive on numbered lists in assistant prose."
+        }
+      ]
+    },
+    "scopeWindowLines": {
+      "type": "integer",
+      "minimum": 2,
+      "maximum": 64,
+      "default": 16,
+      "description": "Lines of context around the question when scope is `window-around-question`."
+    },
+    "contextHeader": {
+      "type": "object",
+      "description": "Optional header line that should be included in the modal message text. Captures the tool name / command being approved.",
+      "additionalProperties": false,
+      "properties": {
+        "regex": { "type": "string" },
+        "flags": { "type": "string", "pattern": "^[gimsuy]*$", "default": "i" }
+      }
+    },
+    "continuationLines": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, indented lines immediately following a button line are concatenated to the previous label (handles wrapped long options like Antigravity's \"Yes, and always allow ...\")."
+    },
+    "minButtons": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 2,
+      "description": "Minimum buttons required for the modal to be considered valid. Daemon's auto-approve gate also enforces buttons.length > 0."
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/modal@1",
+      "questionPattern": "Do you want to (?:proceed|allow|run)",
+      "buttonPattern": "^[\\s❯>]*\\d+\\.\\s+(.+)$",
+      "scope": "between-last-two-separators",
+      "minButtons": 2
+    },
+    {
+      "$schema": "adhdev:tui/modal@1",
+      "questionPattern": "agy wants to run:",
+      "buttonPattern": "^\\s*\\d+\\.\\s+(.+)$",
+      "scope": "window-around-question",
+      "continuationLines": true,
+      "contextHeader": { "regex": "agy wants to run:\\s*\\n?(.+)" }
+    }
+  ]
+}