{
  "name": "wait_for_text",
  "wireName": "wait_for_text",
  "source": {
    "repo": "tmux-python/libtmux-mcp",
    "revision": "4daddc0dfca96c43bf521d818bf91564e1434760",
    "extractedRevision": "4daddc0dfca96c43bf521d818bf91564e1434760",
    "file": "src/libtmux_mcp/tools/pane_tools/__init__.py",
    "line": 153
  },
  "description": "Wait for NEW output in a tmux pane, then return.\n\nPolls until one of ``patterns`` appears on a line written *after*\nthis call starts, one of ``stop`` appears (immediate failure exit),\nor the timeout expires. Pass ``patterns=null`` to wait for any new\noutput at all. Use this instead of polling ``capture_pane`` in a\nloop.\n\nPre-existing scrollback is never matched, and neither is paint left\nbelow the cursor at entry — only rows written after the call began\ncount. If a pattern was already on screen the result says so via\n``matched_at_entry``.\n\n**Last resort: reserve for output you did not author.** Commands\nyou send are AUTHORED — use ``run_command`` (returns exit status)\nor compose ``; tmux wait-for -S <channel>`` with ``wait_for_channel``\ninstead, both cheaper and exact. For unattributable recurring\nprompts or background log lines, bracket your own command with a\nunique sentinel (``cmd; echo __WAIT_$RANDOM__``) and wait for that.\n\n``stop`` is the cheap way to avoid burning the whole budget: pass\nthe failure markers you already know (``\"error:\"``, ``\"FAILED\"``,\n``\"Traceback\"``) and a failed run returns in milliseconds instead\nof at the ceiling.\n\nThe server caps ``timeout``. An over-large value is not an error —\nthe wait returns at the ceiling and reports ``effective_timeout``.",
  "schemaStatus": "runtime",
  "inputSchema": {
    "additionalProperties": false,
    "properties": {
      "interval": {
        "default": 0.05,
        "description": "Seconds between polls. Default 0.05 (50ms). Minimum 0.01.",
        "type": "number"
      },
      "match_case": {
        "default": false,
        "description": "Whether to match case. Default False (case-insensitive).",
        "type": "boolean"
      },
      "pane_id": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Pane ID (e.g. '%1')."
      },
      "patterns": {
        "anyOf": [
          {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Success patterns; the first one to match ends the wait.\nLiteral text unless ``regex=True``. Omit or pass ``null`` to\nwait for any new output."
      },
      "regex": {
        "default": false,
        "description": "Interpret ``patterns`` and ``stop`` as regular expressions.\nDefault False (literal text).",
        "type": "boolean"
      },
      "session_id": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Session ID (e.g. '$1') for pane resolution."
      },
      "session_name": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Session name for pane resolution."
      },
      "socket_name": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "tmux socket name."
      },
      "stop": {
        "anyOf": [
          {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Failure patterns. A hit ends the wait immediately with\n``outcome=\"stopped\"`` and ``found=false``; ``matched_index``\nsays which entry fired."
      },
      "timeout": {
        "default": 8,
        "description": "Requested seconds to wait. Default 8.0. Clamped by server\npolicy; see ``effective_timeout`` in the result.",
        "type": "number"
      },
      "window_id": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Window ID for pane resolution."
      }
    },
    "type": "object"
  },
  "outputSchema": {
    "description": "Result of a bounded wait for new pane output.\n\nDeliberately free of inference. Every field is something the tool\nobserved directly — a match, a clock reading, a tmux flag. There is\nno \"likely cause\", no \"next action\", no quiescence verdict: a\nconfidently-wrong diagnosis costs the agent more than an honest\n\"nothing appeared, here is what the pane shows\".\n\nField count is load-bearing. ``outputSchema`` is re-sent on every\nrequest of every session, so a field that no agent branches on is a\npermanent tax. ``outcome`` carries what three separate booleans\ncarried before it.",
    "properties": {
      "alternate_screen": {
        "default": false,
        "description": "True when the pane was on the terminal's alternate screen at any point during the wait.",
        "type": "boolean"
      },
      "effective_timeout": {
        "description": "Seconds actually enforced. Server policy caps the requested ``timeout``; compare against what you passed to see a clamp.",
        "type": "number"
      },
      "elapsed_seconds": {
        "description": "Time spent waiting in seconds",
        "type": "number"
      },
      "found": {
        "description": "True when a ``patterns`` entry matched new output, or, with ``patterns=null``, when any new output appeared.",
        "type": "boolean"
      },
      "matched_at_entry": {
        "default": false,
        "description": "True when ``patterns`` already matched on-screen text before the wait began and nothing new matched after. The wait holds out for a FRESH occurrence, so re-running a command whose output looks identical still works. Read it as: the text is there, but it predates your call.",
        "type": "boolean"
      },
      "matched_index": {
        "anyOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ],
        "default": null,
        "description": "Zero-based index into ``patterns``, or into ``stop`` when ``outcome`` is ``stopped``. Null otherwise."
      },
      "matched_lines": {
        "description": "Newly-written lines that matched (empty on timeout).",
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "outcome": {
        "description": "How the wait ended. ``matched``: a ``patterns`` entry hit. ``any_output``: ``patterns`` was omitted and something — possibly just a prompt repaint — was written; read it as 'the pane moved', never as 'the command finished'. ``stopped``: a ``stop`` failure marker hit. ``alternate_screen``: the pane was under a pager, editor, or full-screen TUI, which repaints the whole grid, so matching was suppressed — read the screen with snapshot_pane instead of retrying. ``timeout``: nothing matched in the budget.",
        "enum": [
          "matched",
          "any_output",
          "stopped",
          "alternate_screen",
          "timeout"
        ],
        "type": "string"
      },
      "pane_id": {
        "description": "Pane ID that was polled",
        "type": "string"
      },
      "saw_new_output": {
        "default": false,
        "description": "True when content was written on or below the entry cursor row. Read it with ``found=false``: true means output arrived and did not match — read ``tail`` and fix the pattern; false means the pane was quiet — suspect the command never ran, or check ``alternate_screen``.",
        "type": "boolean"
      },
      "tail": {
        "description": "Rows from the entry cursor row down at the final poll, tail-limited by lines and bytes. Includes stale rows excluded from matching, so it shows what the pane looks like, not what matched. On a timeout this usually already contains the answer — read it before retrying with a different pattern.",
        "items": {
          "type": "string"
        },
        "type": "array"
      }
    },
    "required": [
      "found",
      "outcome",
      "pane_id",
      "elapsed_seconds",
      "effective_timeout"
    ],
    "type": "object"
  },
  "annotations": {
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": true,
    "readOnlyHint": false
  },
  "meta": {
    "fastmcp": {
      "tags": [
        "inspect",
        "self-bounded"
      ]
    }
  }
}