bmsdna-devtools 0.36.0__tar.gz → 0.37.0__tar.gz

{bmsdna_devtools-0.36.0 → bmsdna_devtools-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.36.0
+Version: 0.37.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.14
 Requires-Dist: pgdevkit[db]>=0.7.1
@@ -15,7 +15,7 @@ Description-Content-Type: text/markdown
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status and a
-one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue take`), issue/work item creation and comments, git worktrees (creation and
+one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue take`), issue/work item creation and comments, finding issues addressed to an agent (`bdt issue search --for-me`) and waiting for new comments (`bdt issue watch`), git worktrees (creation and
 merged-worktree/orphaned-test-DB cleanup), a commit-and-push helper with
 pre-flight checks, Azure log queries, and static checks (`bdt lint`) for
 postgres/psycopg (and arrowbricks) SQL rules, pydantic-model placement, hand-wired HTTP access in
@@ -179,7 +179,15 @@ a thin wrapper around `az repos pr create` (org/project/repo inferred by
 `az` itself from the git remote). On GitHub, `gh pr create --fill` (autofills
 title/body from commit info so it never blocks on an interactive prompt).
 Extra arguments pass through either way, e.g.
-`bdt pr create --target dev -- --title "..."`.
+`bdt pr create --target dev -- --reviewers "..."`.
+
+Pass the text with `--title "..."` and `--description "$(cat pr.md)"` rather than as passthrough
+args: it is kept in full. On GitHub the description goes to `gh` on stdin (`--body-file -`); on
+Azure DevOps it is set over the REST API right after `az` creates the PR, because
+`az repos pr create --description` has been seen cutting long text at ~450 characters (a `--title`/
+`--description` given after `--` is intercepted the same way). Azure DevOps itself allows at most
+4000 characters in a PR description: a longer one is rejected up front, and a description the
+server stored shorter than sent is reported as a warning (`bdt pr update` does the same check).
 
 PRs are created as **drafts by default**; a successful create always prints
 the PR's link plus `bdt pr publish` (which abstracts over the host) to mark
@@ -343,6 +351,58 @@ branch's PR closes (`Fixes #N`, or an issue/work-item URL in the PR body); it re
 that is none or several. If the issue's newest comment already is a "Taken by ..." claim (by anyone) it
 says so and posts nothing, so it's safe to run repeatedly -- including before `bdt issue do`.
 
+## `bdt issue search --for-me` / `bdt issue watch`
+
+Issues are how people and coding agents talk to each other: someone comments `@Claude, can you look
+at this?` on an issue, and the agent finds it; the agent asks a question in an issue and waits for the answer.
+
+```bash
+bdt issue search --for-me [--agent claude] [--state all] [--limit 10]
+bdt issue watch 84 [--timeout 900] [--interval 20] [--since-comment ID] [--for-me] [--skip-own] [--json]
+```
+
+**`issue search --for-me`** only keeps issues (GitHub) / work items (Azure DevOps) whose **last comment**
+addresses the calling agent. It combines with every other `search` filter (keywords, `--label`, `--board`,
+`--org-wide`, ...). A comment addresses the agent when it contains `@Claude`, `@Codex`, `@Goose`, ... for
+the agent that is running `bdt`, or `@Agent`, which addresses every agent. Matching is case-insensitive and
+on whole words: `@claude`, `@CLAUDE,` and `@Claude.` match, `@Claudette`, `@claude-bot` and `me@claude.ai` do not.
+Only the newest comment counts, so once someone (including the agent, e.g. with a reply) comments after the
+mention, the issue drops out of the list. The newest comment isn't part of the list output of `gh`/Azure DevOps,
+so this costs one extra request per candidate; candidates are scanned in recently-updated order (up to 10x
+`--limit` on GitHub, 200 on Azure DevOps) until `--limit` have matched.
+
+Which agent is calling is detected from the environment, first match wins: `--agent NAME` (or the `BDT_AGENT`
+environment variable, to pin it), `CLAUDECODE=1` (Claude), the agent-agnostic `AI_AGENT` convention (first
+token of its value, `claude-code_2-1_agent` is Claude; `gh` reads it too), then marker variables of
+`CLAUDE_CODE_*` (Claude), `CODEX_SANDBOX*` / `CODEX_THREAD_*` / `CODEX_CI` (Codex), `GOOSE_TERMINAL` /
+`GOOSE_SESSION` (Goose), `OPENCODE` (OpenCode) and `GEMINI_CLI=1` (Gemini). These variables are not a
+documented contract of those tools, so use `--agent`/`BDT_AGENT` for any other agent (any name works:
+`--agent myagent` looks for `@myagent`). With no agent detected (a human at a terminal), `--for-me` notes
+that on stderr and matches `@Agent` only.
+
+**`issue watch NUMBER`** (also available as `bdt watch-issue NUMBER`) blocks until a new comment arrives on the
+issue / work item, polling every `--interval` seconds (default 20), then prints the new comment(s) and exits 0. It
+exits **4** if nothing arrived within `--timeout` seconds (default 900; `0` waits forever), so an agent can
+tell "no answer yet" from a failure (exit 1) and run it again. Comments that were already there when the
+watch started are ignored -- use `--since-comment ID` (the id `issue comment add` printed) to also receive anything
+posted after that comment, which avoids missing a reply that came in before the watch started. So an agent asks
+and waits like this:
+
+```bash
+bdt issue comment add 84 --message "@aersam Should this also cover Azure DevOps?"   # prints (comment #123)
+bdt issue watch 84 --since-comment 123 --skip-own --json --timeout 1800
+```
+
+- `--for-me` only reports new comments that address the calling agent (same matching and `--agent` as `search`).
+- `--skip-own` ignores comments this agent wrote itself: those carrying its session note (bdt appends
+  `<Agent> Session: <id>` to every comment it posts under an agent) or, outside an agent, those authored by the
+  authenticated user. Comments of a human who shares the agent's account are still reported under an agent.
+- `--json` prints each new comment as one JSON object per line (`id`, `author`, `created_at`, `url`, `body`; Azure
+  DevOps's HTML is converted to plain text); without it a short readable block per comment. Status messages go to
+  stderr, so stdout holds only the comments.
+- A single failed poll (network blip, API error) is retried; three in a row abort with the error.
+- On Azure DevOps only the newest 100 comments of a work item are looked at per poll.
+
 ## `bdt env get-keys`
 
 Lists the variable **names** (never the values) defined in `.env`, `*.env` and `.env.*` files under the

{bmsdna_devtools-0.36.0 → bmsdna_devtools-0.37.0}/README.md

@@ -1,7 +1,7 @@
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status and a
-one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue take`), issue/work item creation and comments, git worktrees (creation and
+one-shot PR summary (`bdt pr info`), PR creation, claiming an issue (`bdt issue take`), issue/work item creation and comments, finding issues addressed to an agent (`bdt issue search --for-me`) and waiting for new comments (`bdt issue watch`), git worktrees (creation and
 merged-worktree/orphaned-test-DB cleanup), a commit-and-push helper with
 pre-flight checks, Azure log queries, and static checks (`bdt lint`) for
 postgres/psycopg (and arrowbricks) SQL rules, pydantic-model placement, hand-wired HTTP access in
@@ -165,7 +165,15 @@ a thin wrapper around `az repos pr create` (org/project/repo inferred by
 `az` itself from the git remote). On GitHub, `gh pr create --fill` (autofills
 title/body from commit info so it never blocks on an interactive prompt).
 Extra arguments pass through either way, e.g.
-`bdt pr create --target dev -- --title "..."`.
+`bdt pr create --target dev -- --reviewers "..."`.
+
+Pass the text with `--title "..."` and `--description "$(cat pr.md)"` rather than as passthrough
+args: it is kept in full. On GitHub the description goes to `gh` on stdin (`--body-file -`); on
+Azure DevOps it is set over the REST API right after `az` creates the PR, because
+`az repos pr create --description` has been seen cutting long text at ~450 characters (a `--title`/
+`--description` given after `--` is intercepted the same way). Azure DevOps itself allows at most
+4000 characters in a PR description: a longer one is rejected up front, and a description the
+server stored shorter than sent is reported as a warning (`bdt pr update` does the same check).
 
 PRs are created as **drafts by default**; a successful create always prints
 the PR's link plus `bdt pr publish` (which abstracts over the host) to mark
@@ -329,6 +337,58 @@ branch's PR closes (`Fixes #N`, or an issue/work-item URL in the PR body); it re
 that is none or several. If the issue's newest comment already is a "Taken by ..." claim (by anyone) it
 says so and posts nothing, so it's safe to run repeatedly -- including before `bdt issue do`.
 
+## `bdt issue search --for-me` / `bdt issue watch`
+
+Issues are how people and coding agents talk to each other: someone comments `@Claude, can you look
+at this?` on an issue, and the agent finds it; the agent asks a question in an issue and waits for the answer.
+
+```bash
+bdt issue search --for-me [--agent claude] [--state all] [--limit 10]
+bdt issue watch 84 [--timeout 900] [--interval 20] [--since-comment ID] [--for-me] [--skip-own] [--json]
+```
+
+**`issue search --for-me`** only keeps issues (GitHub) / work items (Azure DevOps) whose **last comment**
+addresses the calling agent. It combines with every other `search` filter (keywords, `--label`, `--board`,
+`--org-wide`, ...). A comment addresses the agent when it contains `@Claude`, `@Codex`, `@Goose`, ... for
+the agent that is running `bdt`, or `@Agent`, which addresses every agent. Matching is case-insensitive and
+on whole words: `@claude`, `@CLAUDE,` and `@Claude.` match, `@Claudette`, `@claude-bot` and `me@claude.ai` do not.
+Only the newest comment counts, so once someone (including the agent, e.g. with a reply) comments after the
+mention, the issue drops out of the list. The newest comment isn't part of the list output of `gh`/Azure DevOps,
+so this costs one extra request per candidate; candidates are scanned in recently-updated order (up to 10x
+`--limit` on GitHub, 200 on Azure DevOps) until `--limit` have matched.
+
+Which agent is calling is detected from the environment, first match wins: `--agent NAME` (or the `BDT_AGENT`
+environment variable, to pin it), `CLAUDECODE=1` (Claude), the agent-agnostic `AI_AGENT` convention (first
+token of its value, `claude-code_2-1_agent` is Claude; `gh` reads it too), then marker variables of
+`CLAUDE_CODE_*` (Claude), `CODEX_SANDBOX*` / `CODEX_THREAD_*` / `CODEX_CI` (Codex), `GOOSE_TERMINAL` /
+`GOOSE_SESSION` (Goose), `OPENCODE` (OpenCode) and `GEMINI_CLI=1` (Gemini). These variables are not a
+documented contract of those tools, so use `--agent`/`BDT_AGENT` for any other agent (any name works:
+`--agent myagent` looks for `@myagent`). With no agent detected (a human at a terminal), `--for-me` notes
+that on stderr and matches `@Agent` only.
+
+**`issue watch NUMBER`** (also available as `bdt watch-issue NUMBER`) blocks until a new comment arrives on the
+issue / work item, polling every `--interval` seconds (default 20), then prints the new comment(s) and exits 0. It
+exits **4** if nothing arrived within `--timeout` seconds (default 900; `0` waits forever), so an agent can
+tell "no answer yet" from a failure (exit 1) and run it again. Comments that were already there when the
+watch started are ignored -- use `--since-comment ID` (the id `issue comment add` printed) to also receive anything
+posted after that comment, which avoids missing a reply that came in before the watch started. So an agent asks
+and waits like this:
+
+```bash
+bdt issue comment add 84 --message "@aersam Should this also cover Azure DevOps?"   # prints (comment #123)
+bdt issue watch 84 --since-comment 123 --skip-own --json --timeout 1800
+```
+
+- `--for-me` only reports new comments that address the calling agent (same matching and `--agent` as `search`).
+- `--skip-own` ignores comments this agent wrote itself: those carrying its session note (bdt appends
+  `<Agent> Session: <id>` to every comment it posts under an agent) or, outside an agent, those authored by the
+  authenticated user. Comments of a human who shares the agent's account are still reported under an agent.
+- `--json` prints each new comment as one JSON object per line (`id`, `author`, `created_at`, `url`, `body`; Azure
+  DevOps's HTML is converted to plain text); without it a short readable block per comment. Status messages go to
+  stderr, so stdout holds only the comments.
+- A single failed poll (network blip, API error) is retried; three in a row abort with the error.
+- On Azure DevOps only the newest 100 comments of a work item are looked at per poll.
+
 ## `bdt env get-keys`
 
 Lists the variable **names** (never the values) defined in `.env`, `*.env` and `.env.*` files under the

{bmsdna_devtools-0.36.0 → bmsdna_devtools-0.37.0}/bmsdna/devtools/ado_issue.py

@@ -41,6 +41,8 @@ a field is saved as Markdown it can't be switched back to HTML via the API.
 from __future__ import annotations
 
 import sys
+from collections.abc import Callable
+from dataclasses import replace
 from pathlib import Path
 from urllib.parse import quote
 
@@ -325,6 +327,32 @@ def last_comment(session: requests.Session, remote: AdoRemote, work_item_id: int
     return comments[0].get("text") if comments else None
 
 
+# Newest comments to fetch per poll of a work item (see `list_comments`) -- a watcher only ever needs
+# what arrived since its last poll, so this is far more than enough while keeping one request per poll.
+_LIST_COMMENTS_TOP = 100
+
+
+def list_comments(session: requests.Session, remote: AdoRemote, work_item_id: int) -> list[dict]:
+    """The work item's newest comments (at most `_LIST_COMMENTS_TOP`), oldest first, as
+    `{id, author, created_at, url, body}` -- `body` is the comment's HTML, as stored."""
+    r = session.get(
+        f"{_base_url(remote)}/_apis/wit/workItems/{work_item_id}/comments",
+        params={"api-version": COMMENTS_API_VERSION, "$top": _LIST_COMMENTS_TOP, "order": "desc"},
+    )
+    r.raise_for_status()
+    url = edit_url(remote, work_item_id)
+    return [
+        {
+            "id": c["id"],
+            "author": (c.get("createdBy") or {}).get("displayName") or "unknown",
+            "created_at": c.get("createdDate") or "",
+            "url": url,
+            "body": c.get("text") or "",
+        }
+        for c in reversed(r.json().get("comments") or [])
+    ]
+
+
 def update_comment(session: requests.Session, remote: AdoRemote, work_item_id: int, comment_id: int, text: str) -> dict:
     r = session.patch(
         f"{_base_url(remote)}/_apis/wit/workItems/{work_item_id}/comments/{comment_id}",
@@ -524,6 +552,27 @@ def get_work_items(session: requests.Session, remote: AdoRemote, ids: list[int],
     return [by_id[i] for i in ids if i in by_id]
 
 
+# Max candidates a comment-filtered `search()` looks at -- also the most work item ids the batch
+# `get_work_items` endpoint accepts per request.
+_COMMENT_FILTER_POOL = 200
+
+
+def _filter_by_last_comment(
+    session: requests.Session, remote: AdoRemote, items: list[dict], top: int, comment_filter: Callable[[str | None], bool]
+) -> list[dict]:
+    """The first `top` of `items` (in order) whose newest comment `comment_filter` accepts. An
+    item from another project (org-wide search) is looked up in its own project."""
+    matched: list[dict] = []
+    for item in items:
+        if len(matched) >= top:
+            break
+        project = item["fields"].get("System.TeamProject")
+        item_remote = replace(remote, project=project) if project else remote
+        if comment_filter(last_comment(session, item_remote, item["id"])):
+            matched.append(item)
+    return matched
+
+
 def search(
     session: requests.Session,
     remote: AdoRemote,
@@ -534,6 +583,7 @@ def search(
     state: str = "open",
     org_wide: bool = False,
     tags: list[str] | None = None,
+    comment_filter: Callable[[str | None], bool] | None = None,
 ) -> list[dict]:
     """Search (or, with no keywords, just list) work items by keywords (ANDed, matched against
     Title or Description) and state, most recently changed first. `board` is an Azure Boards team
@@ -544,13 +594,19 @@ def search(
     `org_wide` searches every project in `remote.org` instead of just `remote.project` --
     mutually exclusive with `board`, since a team's Area Path only means something within a
     single project.
+
+    `comment_filter` keeps only work items whose newest comment (None if it has none) it accepts --
+    e.g. `bdt issue search --for-me`. WIQL can't query comments, so up to `_COMMENT_FILTER_POOL`
+    candidates are fetched and checked one by one, stopping once `top` have matched.
     """
     if org_wide and board:
         sys.exit("--board can't be combined with --org-wide (a board's Area Path is scoped to a single project).")
     area_path = get_team_area_path(session, remote, board) if board else None
     wiql = build_search_wiql(keywords, since, area_path, state, org_wide=org_wide, tags=tags)
-    ids = run_wiql(session, remote, wiql, top, org_wide=org_wide)
+    ids = run_wiql(session, remote, wiql, min(top * 10, _COMMENT_FILTER_POOL) if comment_filter else top, org_wide=org_wide)
     items = get_work_items(session, remote, ids, org_wide=org_wide)
+    if comment_filter:
+        items = _filter_by_last_comment(session, remote, items, top, comment_filter)
     for item in items:
         fields = item["fields"]
         project = fields.get("System.TeamProject")

bmsdna_devtools-0.37.0/bmsdna/devtools/agent_mentions.py

@@ -0,0 +1,82 @@
+"""Which coding agent is calling `bdt`, and does a comment address it?
+
+Backs `bdt issue search --for-me` and `bdt issue watch`: people (or other agents) address an agent
+in an issue comment with `@Claude`, `@Codex`, `@Goose`, ... and `@Agent` addresses all of them.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Callable, Mapping
+
+# A mention addressed to every agent, whatever the caller is.
+ANY_AGENT = "agent"
+
+# Env var that overrides detection (the `--agent` option of `issue search`/`issue watch` reads it too).
+AGENT_ENV_VAR = "BDT_AGENT"
+
+# Mention handles of the agents we know how to detect, with the environment each one leaves in the
+# processes it spawns. Best-effort, like `cli_tools.detect_agent_session`: none of these is a
+# documented, stable contract, which is why an explicit override always wins.
+_ENV_EXACT: tuple[tuple[str, str, str], ...] = (("CLAUDECODE", "1", "claude"), ("GEMINI_CLI", "1", "gemini"))
+_ENV_PREFIXES: tuple[tuple[str, str], ...] = (
+    ("CLAUDE_CODE_", "claude"),
+    ("CODEX_SANDBOX", "codex"),
+    ("CODEX_THREAD_", "codex"),
+    ("CODEX_CI", "codex"),
+    ("GOOSE_TERMINAL", "goose"),
+    ("GOOSE_SESSION", "goose"),
+    ("OPENCODE", "opencode"),
+)
+
+
+def normalize_agent(name: str) -> str:
+    """The mention handle for an agent name or tag: 'Claude' / 'claude-code_2-1_agent' -> 'claude',
+    'Codex CLI' -> 'codex', '@Goose' -> 'goose'."""
+    tag = re.split(r"[\s_-]+", name.strip().lstrip("@").lower(), maxsplit=1)[0]
+    return tag
+
+
+def detect_agent(env: Mapping[str, str] | None = None, override: str | None = None) -> str | None:
+    """The calling agent's mention handle (lowercase, e.g. 'claude'), or None when not run by one.
+
+    Order: an explicit `override` (the `--agent` option), then `BDT_AGENT`, then `CLAUDECODE=1`,
+    then the agent-agnostic `AI_AGENT` convention (the first token of its value; `gh` reads the same
+    variable), then each agent's own marker variables (`CLAUDE_CODE_*`, `CODEX_*`, `GOOSE_*`, ...).
+    """
+    env = os.environ if env is None else env
+    for explicit in (override, env.get(AGENT_ENV_VAR)):
+        if explicit and explicit.strip():
+            return normalize_agent(explicit)
+    for var, value, handle in _ENV_EXACT:
+        if env.get(var) == value:
+            return handle
+    ai_agent = env.get("AI_AGENT", "").strip()
+    if ai_agent:
+        return normalize_agent(ai_agent)
+    for prefix, handle in _ENV_PREFIXES:
+        if any(key.startswith(prefix) and env[key] for key in env):
+            return handle
+    return None
+
+
+def mentions_agent(text: str | None, agent: str | None) -> bool:
+    """Does `text` contain an `@<agent>` or `@Agent` mention?
+
+    Case-insensitive, and the handle must be a whole word: `@Claude` and `@claude,` match but
+    `@Claudette`, `@claude-bot` and `name@claude.com` do not. With `agent=None` (no agent detected)
+    only `@Agent` matches.
+    """
+    if not text:
+        return False
+    handles = {ANY_AGENT}
+    if agent:
+        handles.add(normalize_agent(agent))
+    pattern = r"(?<![\w@])@(?:" + "|".join(re.escape(h) for h in sorted(handles)) + r")(?![\w@]|-\w)"
+    return re.search(pattern, text, re.IGNORECASE) is not None
+
+
+def last_comment_filter(agent: str | None) -> Callable[[str | None], bool]:
+    """A predicate over an issue's newest comment (None = no comments): does it address `agent`?"""
+    return lambda text: mentions_agent(text, agent)

{bmsdna_devtools-0.36.0 → bmsdna_devtools-0.37.0}/bmsdna/devtools/cli.py

@@ -15,11 +15,12 @@ import requests
 import typer
 from pgdevkit.testdb import constants as pgdevkit_constants
 
-from . import ado_issue, api_usage as api_usage_mod, app_service_logs, commit as commit_mod, dead_code as dead_code_mod
+from . import ado_issue, agent_mentions, api_usage as api_usage_mod, app_service_logs, commit as commit_mod, dead_code as dead_code_mod
 from . import env_config
 from . import env_files as env_files_mod
 from . import find_repo as find_repo_mod
 from . import issue_do as issue_do_mod
+from . import issue_watch as issue_watch_mod
 from . import gh_issue, gh_pr
 from . import find_injection as find_injection_mod
 from . import lint as lint_mod
@@ -258,6 +259,13 @@ def pr_create(
         "named group before the PR is created. [tool.bdt.pr.scope_labels] can auto-add a label based "
         "on the HEAD commit's conventional-commit scope (e.g. `feat(customers): ...` -> a configured label).",
     ),
+    title: str | None = typer.Option(None, "--title", help="PR title (default: from the commits)"),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        help="PR description, kept in full (default: from the commits). On Azure DevOps it is set over the "
+        "REST API after the PR is created, since `az repos pr create --description` can cut long text.",
+    ),
     screenshot: list[str] = typer.Option(
         [], "--screenshot", help="Path to an image to attach to the PR description (repeatable)"
     ),
@@ -315,7 +323,7 @@ def pr_create(
     pr_url: str | None = None
     if isinstance(remote, GitHubRemote):
         gh = require_gh()
-        returncode, pr_url = gh_pr.create(gh, target, args or [], draft=draft, labels=label)
+        returncode, pr_url = gh_pr.create(gh, target, args or [], draft=draft, labels=label, title=title, description=description)
         build_policy = gh_pr.has_build_policy(gh, target)
         if returncode == 0 and (screenshot or file):
             _after_create(lambda: gh_pr.add_attachments(gh, remote.owner, remote.repo, source_branch, screenshot, file), "attaching screenshots/files")
@@ -323,6 +331,17 @@ def pr_create(
             _after_create(lambda: _link_and_label_github(gh, remote, issue_numbers), "linking issue(s) / setting 'pr-available' label")
     else:
         az = require_az()
+        # `--title`/`--description` (also when passed through to `az`) are applied over REST
+        # below rather than trusting `az` with long text.
+        az_args, pass_title, pass_description = pr_build.split_az_text_args(args or [])
+        title = title if title is not None else pass_title
+        description = description if description is not None else pass_description
+        if description is not None and len(description) > pr_build.ADO_PR_DESCRIPTION_MAX:
+            raise typer.BadParameter(
+                f"{len(description)} characters; Azure DevOps allows at most {pr_build.ADO_PR_DESCRIPTION_MAX}. "
+                "Shorten it, or attach the detail with --file.",
+                param_hint="--description",
+            )
         cmd = [
             az, "repos", "pr", "create",
             "--organization", f"https://dev.azure.com/{remote.org}",
@@ -334,7 +353,8 @@ def pr_create(
             "--output", "json",
             *(["--draft", "true"] if draft else []),
             *(["--labels", *label] if label else []),
-            *(args or []),
+            *(["--title", title] if title is not None else []),
+            *az_args,
         ]
         r = subprocess.run(cmd, capture_output=True, encoding="utf-8")
         returncode = r.returncode
@@ -361,14 +381,16 @@ def pr_create(
         session = requests.Session()
         session.headers.update(auth_header(pat))
         build_policy = pr_build.has_build_policy(session, remote, target)
-        if returncode == 0 and (detect_agent_session() is not None or screenshot or file):
+        if returncode == 0 and (detect_agent_session() is not None or screenshot or file or description is not None):
             def _finish() -> None:
                 pr = pr_build.get_pr(session, remote, source_branch, target)
+                if description is not None:
+                    pr = pr_build.set_description(session, remote, pr, description)
                 if screenshot or file:
                     pr = pr_build.add_attachments(session, remote, pr, screenshot, file)
                 pr_build.ensure_session_note(session, remote, pr)
 
-            _after_create(_finish, "attaching screenshots/files and/or noting the agent session")
+            _after_create(_finish, "setting the description, attaching screenshots/files and/or noting the agent session (retry with `bdt pr update`)")
         if returncode == 0:
             # Fetches the PR fresh via `pr_build.get_pr` rather than trusting `pr_json` -- `az`
             # can exit 0 with stdout that isn't clean JSON (e.g. a deprecation banner ahead of
@@ -694,6 +716,20 @@ def issue_search(
         envvar=["AZURE_DEVOPS_EXT_PAT", "AZURE_DEVOPS_PAT"],
         help="Azure DevOps PAT (else falls back to `az` login)",
     ),
+    for_me: bool = typer.Option(
+        False,
+        "--for-me",
+        help="Only issues/work items whose LAST comment addresses the calling coding agent: contains "
+        "@Claude / @Codex / @Goose / ... (case-insensitive, whole word; which one is detected from the "
+        "environment, see --agent) or @Agent (addresses every agent).",
+    ),
+    agent: str | None = typer.Option(
+        None,
+        "--agent",
+        envvar=agent_mentions.AGENT_ENV_VAR,
+        help="With --for-me: the agent to look for mentions of, e.g. claude, codex, goose. Default: detected "
+        "from the environment (CLAUDECODE, AI_AGENT, CODEX_*, GOOSE_*, ...); without any, only @Agent matches.",
+    ),
 ) -> None:
     """Search (or, with no keywords, just list) issues / work items, defaulting to open issues
     from the last 30 days (Azure DevOps or GitHub, auto-detected).
@@ -702,6 +738,8 @@ def issue_search(
         raise typer.BadParameter("Must be one of: open, closed, all", param_hint="--state")
     since = (datetime.now(timezone.utc) - timedelta(days=since_days)).strftime("%Y-%m-%d") if since_days > 0 else None
     tags_or_labels = _merge_tags_and_labels(tag, label) or []
+    # only passed on with --for-me, so a plain search calls the backends exactly as before
+    search_extra = {"comment_filter": agent_mentions.last_comment_filter(_resolve_agent(agent))} if for_me else {}
 
     # --org/--github-org are only ever consulted as a *fallback*, when `current_remote()` itself
     # fails (no git repo, no origin remote, or a remote that's neither GitHub nor Azure DevOps) --
@@ -729,17 +767,26 @@ def issue_search(
     if isinstance(remote, GitHubRemote):
         resolved_board = gh_issue.resolve_board(board)
         gh_issue.search(
-            require_gh(), remote.owner, remote.repo, keywords or [], since, limit, state, board=resolved_board, org_wide=org_wide, labels=tags_or_labels
+            require_gh(), remote.owner, remote.repo, keywords or [], since, limit, state, board=resolved_board, org_wide=org_wide, labels=tags_or_labels, **search_extra
         )
     else:
         session = requests.Session()
         session.headers.update(auth_header(pat))
         resolved_board = ado_issue.resolve_board(board)
         ado_issue.search(
-            session, remote, keywords or [], since=since, board=resolved_board, top=limit, state=state, org_wide=org_wide, tags=tags_or_labels
+            session, remote, keywords or [], since=since, board=resolved_board, top=limit, state=state, org_wide=org_wide, tags=tags_or_labels, **search_extra
         )
 
 
+def _resolve_agent(agent: str | None) -> str | None:
+    """The agent to match `@mentions` of: `--agent`/`BDT_AGENT`, else detected from the environment.
+    None (with a note on stderr) when neither -- then only `@Agent` mentions can match."""
+    resolved = agent_mentions.detect_agent(override=agent)
+    if resolved is None:
+        typer.echo("No calling agent detected (pass --agent or set BDT_AGENT) -- only @Agent mentions match", err=True)
+    return resolved
+
+
 @issue_app.command("do", context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
 def issue_do(
     ctx: typer.Context,
@@ -868,6 +915,74 @@ def _capture(cmd: list[str]) -> subprocess.CompletedProcess | None:
         return None
 
 
+def issue_watch(
+    number: int = typer.Argument(..., help="Issue number (GitHub) or work item ID (Azure DevOps)"),
+    interval: float = typer.Option(20.0, "--interval", help="Seconds between polls"),
+    timeout: float = typer.Option(900.0, "--timeout", help="Give up after this many seconds (0 = wait forever); exits 4 on timeout"),
+    since_comment: int | None = typer.Option(
+        None,
+        "--since-comment",
+        help="Report comments newer than this comment ID (as printed by `issue comment add`), even ones already "
+        "posted before the watch started. Default: only comments arriving after the watch started.",
+    ),
+    for_me: bool = typer.Option(
+        False, "--for-me", help="Only report comments that mention the calling agent (@Claude / @Codex / ...) or @Agent -- see `issue search --for-me`"
+    ),
+    agent: str | None = typer.Option(
+        None, "--agent", envvar=agent_mentions.AGENT_ENV_VAR, help="With --for-me: the agent to look for mentions of (default: detected from the environment)"
+    ),
+    skip_own: bool = typer.Option(
+        False,
+        "--skip-own",
+        help="Ignore comments this agent wrote itself: those carrying its session note (appended by bdt to every comment "
+        "it posts), or, outside an agent, those authored by the current user",
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Print each new comment as one JSON line (id, author, created_at, url, body)"),
+    pat: str | None = typer.Option(None, "--pat", envvar=["AZURE_DEVOPS_EXT_PAT", "AZURE_DEVOPS_PAT"], help="Azure DevOps PAT (else falls back to `az` login)"),
+) -> None:
+    """Wait for new comments on an issue / work item -- so an agent can ask a question in the issue and
+    block until someone answers. Prints the new comment(s) and exits 0; exits 4 if none arrived within
+    --timeout. Progress notes go to stderr, so stdout holds only the comments (JSON lines with --json).
+    """
+    if interval <= 0:
+        raise typer.BadParameter("Must be greater than 0", param_hint="--interval")
+    if timeout < 0:
+        raise typer.BadParameter("Must be 0 (wait forever) or greater", param_hint="--timeout")
+    remote = current_remote()
+    if isinstance(remote, GitHubRemote):
+        gh = require_gh()
+
+        def fetch() -> list[issue_watch_mod.Comment]:
+            return issue_watch_mod.to_comments(gh_issue.list_comments(gh, remote.owner, remote.repo, number))
+    else:
+        ado_session = requests.Session()
+        ado_session.headers.update(auth_header(pat))
+
+        def fetch() -> list[issue_watch_mod.Comment]:
+            return issue_watch_mod.to_comments(ado_issue.list_comments(ado_session, remote, number), is_html=True)
+
+    own_session = detect_agent_session() if skip_own else None
+    accept = issue_watch_mod.build_accept(
+        agent=_resolve_agent(agent) if for_me else None,
+        for_me=for_me,
+        own_session_id=own_session.session_id if own_session else None,
+        own_author=_current_user(remote) if skip_own and own_session is None else None,
+    )
+    typer.echo(f"Watching #{number} for new comments (every {interval:g}s, {f'up to {timeout:g}s' if timeout else 'no timeout'})", err=True)
+    new = issue_watch_mod.watch(fetch, since_id=since_comment, accept=accept, interval=interval, timeout=timeout or None)
+    if new is None:
+        typer.echo(f"No new comment on #{number} within {timeout:g}s", err=True)
+        raise typer.Exit(issue_watch_mod.EXIT_TIMEOUT)
+    for comment in new:
+        typer.echo(issue_watch_mod.format_comment(comment, as_json=as_json))
+        if not as_json:
+            typer.echo("")
+
+
+issue_app.command("watch")(issue_watch)
+app.command("watch-issue", help="Alias for `bdt issue watch`")(issue_watch)
+
+
 @issue_app.command("update")
 def issue_update(
     number: int = typer.Argument(..., help="Issue number (GitHub) or work item ID (Azure DevOps)"),