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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.35.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,10 +15,10 @@ 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 SQL rules, pydantic-model placement, hand-wired HTTP access in
+postgres/psycopg (and arrowbricks) SQL rules, pydantic-model placement, hand-wired HTTP access in
 TypeScript and baseline tooling, plus `bdt dead-code` for `.sql` files nothing loads and
 backend routes nothing calls.
 `bdt pr *` and `bdt issue *` auto-detect whether the current repo's `origin`
@@ -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
@@ -637,6 +697,21 @@ unresolvable argument, e.g. a plain function parameter, is silently skipped --
 this can't false-positive on non-psycopg `.execute()` calls, or on dynamic SQL
 it can't see through).
 
+**arrowbricks** (the Databricks SQL client): `Cursor.execute`/`execute_streamed`, `DatabricksClient.query_agent`/`stream_query_json`
+and the free `arrowbricks.stream_query_json(client, sql)` are checked as well. `execute_streamed`/`query_agent`/`stream_query_json`
+are matched by name (the free function's SQL is its *second* argument; the method's is the first; `sql=` as keyword works too).
+Only the injection rules apply there -- an f-string/concatenation/`%`/`.format()` is flagged and the fix suggests an
+arrowbricks t-string (`{value}` binds a named parameter, `{name:i}` quotes an identifier) or literal SQL with
+`parameters=[...]` (`params=[...]` on `query_agent`/`stream_query_json`) for `:name` markers. The postgres house style (`sql-inline-too-complex`, `sql-positional-param`, `sql-forbidden-join`) is not applied to
+them, since Databricks SQL isn't postgres. The SQL is also parsed as Databricks SQL (backticks, `QUALIFY`, ...), so such
+statements are no longer missed; a plain `.execute()` (incl. `execute(sql=...)`) gets that extra dialect only in a file that
+imports `arrowbricks`, and keeps the postgres rules there (it may be a psycopg cursor too). The free function is recognised
+under `from arrowbricks import stream_query_json as x` and `arrowbricks[._streaming].stream_query_json(...)`.
+Like pgdevkit's helpers the three names match by name wherever they are called (a client injected from another module is the
+common case), so an unrelated `agent.query_agent(f"select ...")` whose text parses as SQL is flagged too.
+arrowbricks' `unsafe_sql(x)` -- its typing-only escape hatch -- is treated like `cast(LiteralString, x)` (in any file):
+only as safe as `x`.
+
 pgdevkit's helpers are matched by name (`fetch_all(...)`, `db.fetch_all(...)`, `pgdevkit.db.execute(...)`). The one
 exception is a *bare* `execute(...)`, a far too generic name: it is only checked in a file that imports it from
 `pgdevkit`/`pgdevkit.db` (`from pgdevkit.db import execute`, also aliased: `... import execute as run`; the import is
@@ -846,8 +921,8 @@ Findings have two severities: **error** (a definite unsafe pattern, exit code 1)
 (depends on where a value comes from; listed with an instruction for an AI/human to verify, exit
 code 0 unless `--strict`).
 
-- **SQL** (Python `.execute()` / `fetch_all()` / `fetch_one()` / `fetch_scalar()` / `execute()` from pgdevkit / `PostgresJsonResponse()`): f-string / `%` / concatenation / `.format()` SQL is an error.
-  SQL from `load_sql()`, `sql.SQL`, sqlglot (`expr.sql()`, `sqlglot.*`), `cast(LiteralString, <sqlglot expr>)` (the cast is only as safe as its argument) or
+- **SQL** (Python `.execute()` / `fetch_all()` / `fetch_one()` / `fetch_scalar()` / `execute()` from pgdevkit / `PostgresJsonResponse()` / arrowbricks `execute_streamed()` / `query_agent()` / `stream_query_json()`): f-string / `%` / concatenation / `.format()` SQL is an error.
+  SQL from `load_sql()`, `sql.SQL`, sqlglot (`expr.sql()`, `sqlglot.*`), `cast(LiteralString, <sqlglot expr>)`/`unsafe_sql(...)` (the cast is only as safe as its argument) or
   a function in the same file annotated `-> LiteralString` is trusted; SQL from any other function
   call is a `sql-unverified-call` review item. (`bdt lint` accepts the same trusted forms but never
   reports unverified calls.)

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

@@ -1,10 +1,10 @@
 # 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 SQL rules, pydantic-model placement, hand-wired HTTP access in
+postgres/psycopg (and arrowbricks) SQL rules, pydantic-model placement, hand-wired HTTP access in
 TypeScript and baseline tooling, plus `bdt dead-code` for `.sql` files nothing loads and
 backend routes nothing calls.
 `bdt pr *` and `bdt issue *` auto-detect whether the current repo's `origin`
@@ -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
@@ -623,6 +683,21 @@ unresolvable argument, e.g. a plain function parameter, is silently skipped --
 this can't false-positive on non-psycopg `.execute()` calls, or on dynamic SQL
 it can't see through).
 
+**arrowbricks** (the Databricks SQL client): `Cursor.execute`/`execute_streamed`, `DatabricksClient.query_agent`/`stream_query_json`
+and the free `arrowbricks.stream_query_json(client, sql)` are checked as well. `execute_streamed`/`query_agent`/`stream_query_json`
+are matched by name (the free function's SQL is its *second* argument; the method's is the first; `sql=` as keyword works too).
+Only the injection rules apply there -- an f-string/concatenation/`%`/`.format()` is flagged and the fix suggests an
+arrowbricks t-string (`{value}` binds a named parameter, `{name:i}` quotes an identifier) or literal SQL with
+`parameters=[...]` (`params=[...]` on `query_agent`/`stream_query_json`) for `:name` markers. The postgres house style (`sql-inline-too-complex`, `sql-positional-param`, `sql-forbidden-join`) is not applied to
+them, since Databricks SQL isn't postgres. The SQL is also parsed as Databricks SQL (backticks, `QUALIFY`, ...), so such
+statements are no longer missed; a plain `.execute()` (incl. `execute(sql=...)`) gets that extra dialect only in a file that
+imports `arrowbricks`, and keeps the postgres rules there (it may be a psycopg cursor too). The free function is recognised
+under `from arrowbricks import stream_query_json as x` and `arrowbricks[._streaming].stream_query_json(...)`.
+Like pgdevkit's helpers the three names match by name wherever they are called (a client injected from another module is the
+common case), so an unrelated `agent.query_agent(f"select ...")` whose text parses as SQL is flagged too.
+arrowbricks' `unsafe_sql(x)` -- its typing-only escape hatch -- is treated like `cast(LiteralString, x)` (in any file):
+only as safe as `x`.
+
 pgdevkit's helpers are matched by name (`fetch_all(...)`, `db.fetch_all(...)`, `pgdevkit.db.execute(...)`). The one
 exception is a *bare* `execute(...)`, a far too generic name: it is only checked in a file that imports it from
 `pgdevkit`/`pgdevkit.db` (`from pgdevkit.db import execute`, also aliased: `... import execute as run`; the import is
@@ -832,8 +907,8 @@ Findings have two severities: **error** (a definite unsafe pattern, exit code 1)
 (depends on where a value comes from; listed with an instruction for an AI/human to verify, exit
 code 0 unless `--strict`).
 
-- **SQL** (Python `.execute()` / `fetch_all()` / `fetch_one()` / `fetch_scalar()` / `execute()` from pgdevkit / `PostgresJsonResponse()`): f-string / `%` / concatenation / `.format()` SQL is an error.
-  SQL from `load_sql()`, `sql.SQL`, sqlglot (`expr.sql()`, `sqlglot.*`), `cast(LiteralString, <sqlglot expr>)` (the cast is only as safe as its argument) or
+- **SQL** (Python `.execute()` / `fetch_all()` / `fetch_one()` / `fetch_scalar()` / `execute()` from pgdevkit / `PostgresJsonResponse()` / arrowbricks `execute_streamed()` / `query_agent()` / `stream_query_json()`): f-string / `%` / concatenation / `.format()` SQL is an error.
+  SQL from `load_sql()`, `sql.SQL`, sqlglot (`expr.sql()`, `sqlglot.*`), `cast(LiteralString, <sqlglot expr>)`/`unsafe_sql(...)` (the cast is only as safe as its argument) or
   a function in the same file annotated `-> LiteralString` is trusted; SQL from any other function
   call is a `sql-unverified-call` review item. (`bdt lint` accepts the same trusted forms but never
   reports unverified calls.)

{bmsdna_devtools-0.35.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)