agex-cli 0.28.0__tar.gz → 0.29.0__tar.gz

{agex_cli-0.28.0 → agex_cli-0.29.0}/.github/workflows/test.yml

@@ -54,6 +54,12 @@ jobs:
       - run: uv venv
       - run: uv pip install -e ".[dev]"
       - run: uv run pytest --cov=src/devex --cov-report=xml --cov-report=term
+        env:
+          # Opt-in live-webhook dogfood (tests/core/test_webhook_live.py). Wired
+          # only into this single ubuntu/3.12 job — NOT the 3x4 `test` matrix —
+          # so a real Discord POST fires at most once per CI run. Empty when the
+          # secret is unset (forks / not configured) -> the test skips.
+          DEVEX_PR_WEBHOOK_TEST_URL: ${{ secrets.DEVEX_PR_WEBHOOK_TEST_URL }}
       # Pinned to v6 to match the sibling agentfront repo's working scan.
       # The v7+/v8 scanner engine 404s on `api.sonarcloud.io/analysis/analyses`
       # against SonarQube Cloud; v6 posts to sonarcloud.io directly.

{agex_cli-0.28.0 → agex_cli-0.29.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.29.0] - 2026-06-03
+
+### Added
+
+- `devex pr open` / `pr reply` / `pr review` post an opt-in, best-effort JSON webhook notification (`{event, repo, id, subject, content}`) to a configured webhook. Discord webhooks (auto-detected by host) get a `{content, embeds}` payload; any other URL gets the raw fields (`[pr.webhook].format = auto|discord|generic` overrides). New `core/webhook.py` (stdlib-`urllib`, the only non-`gh` egress) and `commands/pr/scripts/_webhook.py` orchestrator. New journal events `pr_webhook_posted` / `pr_webhook_failed`.
+- Webhook URL is read only from the environment (a secret): `DEVEX_PR_WEBHOOK_URL` (primary) or the var named by `[pr.webhook].url_env` — never stored in `.devex/config.toml`.
+
+### Changed
+
+- Design invariant #4: the `pr` namespace gains a single opt-in, env-gated, fail-open outbound webhook POST as its only non-`gh` network egress. Unset env = no network call (default behavior unchanged).
+- `core/webhook.py` is now a **generic** transport (`post(url, payload)` + URL classifiers) with no `pr`-namespace knowledge; the `DEVEX_PR_WEBHOOK_URL` env var, `[pr.webhook]` config, and PR payload/format shaping moved to `commands/pr/scripts/_webhook.py`, keeping `core/` command-agnostic (PR #74 review).
+
+### Fixed
+
+- Webhook POST no longer follows redirects (a 3xx is treated as failed), closing a redirect-based SSRF / scheme-guard bypass (PR #74 review).
+- `_webhook.notify()` is now genuinely fail-open: a malformed `.devex/config.toml`, a `gh` failure resolving the repo slug, or a journal-write error can no longer abort `pr open` / `pr reply` / `pr review` (PR #74 review).
+- A whitespace-only `DEVEX_PR_WEBHOOK_URL` now counts as unset (disabled) instead of triggering a `gh` call and a failed POST (PR #74 review).
+
 ## [0.28.0] - 2026-05-29
 
 ### Added

{agex_cli-0.28.0 → agex_cli-0.29.0}/CLAUDE.md

@@ -19,7 +19,7 @@ Read the spec before any non-trivial change — the design invariants below are
 1. **Zero LLM calls inside devex.** All output is deterministic markdown from Jinja templates + Python.
 2. **Markdown is the only output format.** No `--json` flag.
 3. **`--agent <backend>` is required** on backend-sensitive commands. The CLI never auto-detects.
-4. **Side effects only in** `gamify`, `gamify --uninstall`, `hook write`, `pr open`, `pr reply`, `pr review`, `pr read` (journal writes), `pr await` (journal + `--detach` marker writes under `.devex/data/pr/<pr>/` and the detached poller subprocess), `push` (see below), and first-run `.devex/` init. Everything else is read-only. The `devex pr` namespace allows scoped network I/O (via `gh`), bounded `--wait` sleep, and — for `pr await --detach` — a detached background process that pays that sleep outside the agent session; a deliberate carve-out from the no-network/no-sleep invariants. `devex push` performs a `git push` of the current branch (push-only — it never stages or commits); a deliberate carve-out from the no-mutation invariant, introducing `git push` as a new allowed side-effect class.
+4. **Side effects only in** `gamify`, `gamify --uninstall`, `hook write`, `pr open`, `pr reply`, `pr review`, `pr read` (journal writes), `pr await` (journal + `--detach` marker writes under `.devex/data/pr/<pr>/` and the detached poller subprocess), `push` (see below), and first-run `.devex/` init. Everything else is read-only. The `devex pr` namespace allows scoped network I/O (via `gh`), bounded `--wait` sleep, and — for `pr await --detach` — a detached background process that pays that sleep outside the agent session; a deliberate carve-out from the no-network/no-sleep invariants. `devex push` performs a `git push` of the current branch (push-only — it never stages or commits); a deliberate carve-out from the no-mutation invariant, introducing `git push` as a new allowed side-effect class. **`pr open` / `pr reply` / `pr review` also fire an opt-in, best-effort outbound webhook POST** (devex's only non-`gh` network egress, via `core/webhook.py`) carrying `{event, repo, id, subject, content}` to a Discord or generic webhook — but **only when `DEVEX_PR_WEBHOOK_URL` (or a config-named env var) is set**. Unconfigured = no network call (the default is unchanged); a failed POST never aborts the PR action (exit stays 0).
 5. **"Unsupported" is success** — exit 0 with a markdown notice that links to the issue tracker, not a non-zero exit.
 6. **Skills are authored by the agent, not shipped by devex.** `devex learn <topic>` teaches; `devex explain <topic>` describes; devex never writes a user skill file on the agent's behalf in v0.1.
 
@@ -47,9 +47,13 @@ Every non-silent command ends with a deterministic, per-backend **"Next step:"**
 
 ## `devex pr` namespace (v0.17.0+)
 
-`lint`, `open`, `read`, `reply`, `review`, `await`, `delta`. Each command ends with a deterministic "Next step:" footer. The `pr` namespace allows scoped network I/O (via `gh`) and bounded `--wait` sleep — a deliberate carve-out from the no-network/no-sleep invariants. `pr open` (non-draft, new PR) and `pr review` post the Qodo `/agentic_review` trigger comment; the legacy `/improve` is deprecated and never emitted. The trigger string lives in one place: `commands/pr/scripts/review.QODO_REVIEW_TRIGGER`. `pr await --detach` / `--check` (issue #64) move the bounded poll out of the agent session: `--detach` forks a detached worker (`commands/pr/scripts/_await_worker.py`) that writes the verdict to a marker (`commands/pr/scripts/_detach.py`, atomic `os.replace`), and `--check` reads it back without sleeping. Key modules:
+`lint`, `open`, `read`, `reply`, `review`, `await`, `delta`. Each command ends with a deterministic "Next step:" footer. The `pr` namespace allows scoped network I/O (via `gh`) and bounded `--wait` sleep — a deliberate carve-out from the no-network/no-sleep invariants. `pr open` (non-draft, new PR) and `pr review` post the Qodo `/agentic_review` trigger comment; the legacy `/improve` is deprecated and never emitted. The trigger string lives in one place: `commands/pr/scripts/review.QODO_REVIEW_TRIGGER`. `pr await --detach` / `--check` (issue #64) move the bounded poll out of the agent session: `--detach` forks a detached worker (`commands/pr/scripts/_await_worker.py`) that writes the verdict to a marker (`commands/pr/scripts/_detach.py`, atomic `os.replace`), and `--check` reads it back without sleeping.
+
+**Webhook notifications (opt-in, env-gated):** `pr open` (`pr_opened`), `pr reply` (`pr_replied`), and `pr review` (`pr_review_triggered`) each fire one best-effort JSON POST to a configured webhook with `{event, repo, id, subject, content}`. The secret URL comes only from the environment — `DEVEX_PR_WEBHOOK_URL` (primary) or the var named by `[pr.webhook].url_env` — never from the config file. Discord webhooks are auto-detected by host and get a `{content, embeds}` payload; everything else gets raw fields; `[pr.webhook].format = auto|discord|generic` overrides. Fail-open: a failed POST never aborts the verb. Unset env = no network call at all (so the no-network default and every existing test are unaffected). `pr await` is intentionally **not** wired. Key modules:
 
 - `core/github.py` — thin `gh` shellout wrapper; future zero-trust httpx swap touches only this file.
+- `core/webhook.py` — **generic** stdlib-`urllib` transport: `post(url, payload)` + `is_discord_url` / `is_http_url`. Knows HTTP and Discord-the-service, but **nothing** about the `pr` namespace (no env var, no config, no PR fields) — so `core/` stays command-agnostic. Refuses redirects (a 3xx → `FAILED`, blocking redirect-based SSRF); never raises. The only non-`gh` egress, and the second module the future zero-trust httpx swap touches.
+- `commands/pr/scripts/_webhook.py` — owns the devex-pr specifics: the `DEVEX_PR_WEBHOOK_URL` env var, `[pr.webhook]` config, the PR payload + discord/generic shaping. `notify()` is fully **fail-open** — resolve-then-gate (no `gh`/network when disabled), and every error (bad config, `gh` failure, journal write) is swallowed so a webhook problem can't abort the verb. Journals `pr_webhook_posted`/`pr_webhook_failed` (never the URL/payload).
 - `commands/pr/scripts/_detach.py` — await-marker read/write (atomic) + the detached-subprocess spawn helper.
 - `core/journal.py` — nested-stream JSONL append/load for `.devex/data/<dir>/<stream>.jsonl`.
 - `core/backend.resolve_backend()` — `--agent` resolution with `culture.yaml` fallback.
@@ -84,11 +88,16 @@ uv run devex explain explain
 
 # Coverage (matches the `sonarcloud` job in test.yml; SonarCloud reads coverage.xml)
 uv run pytest --cov=src/devex --cov-report=xml --cov-report=term
+
+# Live webhook dogfood (real POST). Skipped unless DEVEX_PR_WEBHOOK_TEST_URL is set —
+# a SEPARATE var from the production DEVEX_PR_WEBHOOK_URL, so the suite never fires a
+# real configured webhook. Set it to a throwaway Discord/test webhook to run it:
+DEVEX_PR_WEBHOOK_TEST_URL=<test-webhook-url> uv run pytest tests/core/test_webhook_live.py
 ```
 
 ## CI surface
 
-- `.github/workflows/test.yml` — matrix: 3 OS × 4 Python (3.10–3.13) running `uv run pytest`. Also runs (1) a `sonarcloud` job that generates `coverage.xml` (`pytest --cov`, repo-relative paths via `pyproject [tool.coverage.run]`) and runs the SHA-pinned `sonarqube-scan-action` (needs the `SONAR_TOKEN` repo secret); and (2) a `version-check` job on PRs that fails (with a sticky `<!-- version-check -->` comment) when `pyproject.toml`'s version on the PR matches the one on `main` and any code file under `src/` / `tests/` / `pyproject.toml` changed. Docs-only PRs skip the version check.
+- `.github/workflows/test.yml` — matrix: 3 OS × 4 Python (3.10–3.13) running `uv run pytest`. Also runs (1) a `sonarcloud` job that generates `coverage.xml` (`pytest --cov`, repo-relative paths via `pyproject [tool.coverage.run]`) and runs the SHA-pinned `sonarqube-scan-action` (needs the `SONAR_TOKEN` repo secret); and (2) a `version-check` job on PRs that fails (with a sticky `<!-- version-check -->` comment) when `pyproject.toml`'s version on the PR matches the one on `main` and any code file under `src/` / `tests/` / `pyproject.toml` changed. Docs-only PRs skip the version check. The `sonarcloud` job's `pytest` step also receives `DEVEX_PR_WEBHOOK_TEST_URL` from the same-named repo secret, so the opt-in live-webhook test (`tests/core/test_webhook_live.py`) runs **once** there (single ubuntu/3.12 job, not the matrix) when the secret is set, and skips otherwise — a real webhook POST fires at most once per CI run.
 - `.github/workflows/publish.yml` — builds sdist + wheel. PRs publish a per-PR dev version to TestPyPI (sticky install-command comment); pushes to `main` publish the stable version to TestPyPI (canary), then an `autotag` job pushes `v<version>` if missing, which gates the inline `publish-pypi` + `github-release` jobs. No manual tagging — bumping `pyproject.toml` is the release signal.
 - SonarCloud runs in **CI-based analysis** mode (Automatic Analysis is off — the two are mutually exclusive). The `sonarcloud` job in `test.yml` uploads coverage + triggers the scan via `sonarqube-scan-action`, reading `sonar-project.properties` and the `SONAR_TOKEN` secret. The quality gate decorates PRs and gates merges.
 - All third-party actions are **pinned to full commit SHAs** with trailing `# vN` comments (rule `githubactions:S7637`). Keep new actions pinned the same way.

{agex_cli-0.28.0 → agex_cli-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agex-cli
-Version: 0.28.0
+Version: 0.29.0
 Summary: Agent-operated developer-experience CLI — deterministic per-backend markdown briefings for autonomous agents.
 Project-URL: Homepage, https://culture.dev/devex/
 Project-URL: Repository, https://github.com/agentculture/devex
@@ -44,6 +44,14 @@ devex overview --agent claude-code
 devex learn --agent claude-code
 ```
 
+## PR webhooks (opt-in)
+
+Set `DEVEX_PR_WEBHOOK_URL` and `devex pr open` / `pr reply` / `pr review` will POST
+a best-effort JSON notification (`{event, repo, id, subject, content}`) to that
+webhook. Discord URLs are auto-detected and get a Discord-shaped payload; any other
+URL gets the raw fields. Unset = no network call; a failed POST never blocks the PR
+action. See `devex explain pr` for details.
+
 ## Docs
 
 [culture.dev/devex](https://culture.dev/devex/).

{agex_cli-0.28.0 → agex_cli-0.29.0}/README.md

@@ -18,6 +18,14 @@ devex overview --agent claude-code
 devex learn --agent claude-code
 ```
 
+## PR webhooks (opt-in)
+
+Set `DEVEX_PR_WEBHOOK_URL` and `devex pr open` / `pr reply` / `pr review` will POST
+a best-effort JSON notification (`{event, repo, id, subject, content}`) to that
+webhook. Discord URLs are auto-detected and get a Discord-shaped payload; any other
+URL gets the raw fields. Unset = no network call; a failed POST never blocks the PR
+action. See `devex explain pr` for details.
+
 ## Docs
 
 [culture.dev/devex](https://culture.dev/devex/).

{agex_cli-0.28.0 → agex_cli-0.29.0}/docs/superpowers/specs/2026-05-10-agex-pr-design.md

@@ -21,8 +21,8 @@ This spec is also the test bed for relaxing agex's "no network / no sleep" invar
 
 The original agex invariants stand, with two scoped relaxations:
 
-- **Invariant 3 carve-out:** "no retries, no sleeps, no network" is relaxed for the `agex pr` namespace only, and only for: GitHub API reads/writes (via `gh` shellout in v0.1), and `--wait`-gated bounded sleep in `agex pr read`. **No silent retries anywhere** — if the agent wants retry, it reruns the command.
-- **Invariant 6 extension:** the enumerated side-effecting commands gain `pr open`, `pr reply`, and `pr read` (journal writes only). Network reads in `pr read` are not "side effects" by this definition; journal writes are.
+- **Invariant 3 carve-out:** "no retries, no sleeps, no network" is relaxed for the `agex pr` namespace only, and only for: GitHub API reads/writes (via `gh` shellout in v0.1), `--wait`-gated bounded sleep in `agex pr read`, and — **added later (v0.29.0)** — a single opt-in outbound webhook POST on `pr open` / `pr reply` / `pr review`. This is the namespace's only **non-`gh`** egress (stdlib `urllib`, centralized in `core/webhook.py`); it is **off unless `DEVEX_PR_WEBHOOK_URL` (or a config-named env var) is set**, fail-open (a failed POST never aborts the verb), and bounded (5s timeout). **No silent retries anywhere** — if the agent wants retry, it reruns the command.
+- **Invariant 6 extension:** the enumerated side-effecting commands gain `pr open`, `pr reply`, and `pr read` (journal writes only). Network reads in `pr read` are not "side effects" by this definition; journal writes are. The webhook POST (above) and its `pr_webhook_posted` / `pr_webhook_failed` journal events are likewise side effects of `pr open` / `pr reply` / `pr review` when the webhook is configured.
 
 Unchanged invariants:
 
@@ -38,11 +38,13 @@ Unchanged invariants:
 | Verb | Replaces (bash) | Side effects |
 |---|---|---|
 | `agex pr lint` | `portability-lint.sh` | Read-only. |
-| `agex pr open --title T [--body-file F] [--draft] [--delayed-read]` | first half of `create-pr-and-wait.sh` | `gh pr create`; one journal append. With `--delayed-read`, chains to `read --wait 180`. |
+| `agex pr open --title T [--body-file F] [--draft] [--delayed-read]` | first half of `create-pr-and-wait.sh` | `gh pr create`; one journal append. With `--delayed-read`, chains to `read --wait 180`. + optional webhook POST (env-gated). |
 | `agex pr read [<PR>] [--wait SECS]` | `pr-status.sh` + `pr-comments.sh` + `poll-readiness.sh` | Read-only network; one journal append (or two with readiness). Bounded sleep when `--wait` given. |
-| `agex pr reply <PR>` | `pr-reply.sh` + `pr-batch.sh` | Posts comments, resolves threads; one journal append per reply, one per batch. |
+| `agex pr reply <PR>` | `pr-reply.sh` + `pr-batch.sh` | Posts comments, resolves threads; one journal append per reply, one per batch. + optional webhook POST (env-gated). |
 | `agex pr delta` | `delta` subcommand of `workflow.sh` | Read-only. |
 
+`agex pr review [<PR>]` (added after v0.1) posts the `/agentic_review` trigger comment + one journal append, plus the optional env-gated webhook POST.
+
 Every command ends with a deterministic **"Next step:"** footer derived from a small per-command rule table. Footers reference the next agex command in the typical chain (e.g. `pr lint` clean → "commit, push, then `agex pr open --title ...`"; `pr open` → "rerun `agex pr read <N> --wait 180` (recommended) or `agex pr read <N>` in ~3 min").
 
 Deliberately **not** in v0.1:
@@ -120,6 +122,21 @@ def resolve_nick(project_dir: Path) -> str: ...    # ports _resolve-nick.sh
 
 Every call shells `gh api ...` / `gh pr ...` and parses JSON. `RuntimeError` with the gh stderr first line on hard failure; soft failures (missing SonarCloud project) return `None` / `[]` so renders still succeed. When httpx replaces gh, only this file changes.
 
+### New: `core/webhook.py` (v0.29.0) — generic transport
+
+The single non-`gh` egress, centralized so the future zero-trust httpx swap touches `github.py` *and* this file only. **Generic** — it knows HTTP and Discord-*the-service*, but nothing about the `pr` namespace (no env var, no config keys, no PR payload fields), so `core/` stays command-agnostic. No `gh`, no journal, no filesystem writes:
+
+```python
+class PostResult(str, Enum): DISABLED | POSTED | FAILED
+def is_discord_url(url) -> bool          # host in Discord set AND /api/webhooks/ path
+def is_http_url(url) -> bool             # http(s) scheme guard
+def post(url: str | None, payload: dict) -> PostResult   # stdlib urllib, 5s, no redirects, never raises
+```
+
+`post()` returns `DISABLED` for a falsy URL (no network), validates the scheme is http(s) (SSRF/B310 guard), uses a **no-redirect opener** (a 3xx → `HTTPError` → `FAILED`, so a redirect can't bounce the POST past the validated URL), POSTs `json.dumps(...).encode("utf-8")` (non-ASCII-safe), treats only 2xx as `POSTED`, and swallows every failure (incl. a non-serialisable payload) to `FAILED`.
+
+The devex-pr specifics live in `commands/pr/scripts/_webhook.py` (keeping core agnostic): the `DEVEX_PR_WEBHOOK_URL` env var (a blank/whitespace value counts as unset), `[pr.webhook]` config (`url_env`, `format`), the `{event,repo,id,subject,content}` payload, and the discord/generic selection. Its `notify()` is fully **fail-open**: it resolves config first (returning early when disabled — no `gh` lookup or network), and wraps `config.load()`, `github._repo_slug()`, `webhook.post()`, and the journal append so *any* error degrades to best-effort rather than aborting `pr open`/`reply`/`review`. It journals `pr_webhook_posted` / `pr_webhook_failed` (type + pr + event only; never the URL or payload).
+
 ### New: `core/journal.py`
 
 `append_event(stream, payload)` — JSONL append using `portalocker.lock` / `portalocker.unlock` (matches the existing convention in `core/hook_io.py`). `pr` events go to `.agex/data/pr/events.jsonl`. `core/hook_io.py` stays unchanged in v0.1 (a future refactor can collapse them); the new `pr` namespace uses `core/journal.py` directly to avoid touching the existing hook surface.
@@ -263,7 +280,7 @@ Event schema:
  "type": "pr_opened", "pr": 42, "title": "feat: ..."}
 ```
 
-Event types in v0.1: `pr_opened`, `pr_read`, `readiness_arrived`, `pr_reply`, `pr_batch_replied`. Future types (`pr_merged`, `pr_closed`) just append. `agex hook read` extends to discover `pr/` alongside `data/*.json`.
+Event types in v0.1: `pr_opened`, `pr_read`, `readiness_arrived`, `pr_reply`, `pr_batch_replied`. Added in v0.29.0: `pr_webhook_posted`, `pr_webhook_failed` (each `{type, pr, event}` — no URL/payload). Future types (`pr_merged`, `pr_closed`) just append. `agex hook read` extends to discover `pr/` alongside `data/*.json`.
 
 ### `config.toml` additions
 
@@ -272,9 +289,15 @@ Event types in v0.1: `pr_opened`, `pr_read`, `readiness_arrived`, `pr_reply`, `p
 wait_default = 180
 required_reviewers = ["qodo"]
 gh_exec = "gh"
+
+# Optional outbound webhook (v0.29.0). The secret URL is NEVER stored here —
+# it is read only from the environment.
+[pr.webhook]
+url_env = "MY_DISCORD_WEBHOOK"   # names the env var holding the URL; DEVEX_PR_WEBHOOK_URL wins
+format  = "auto"                 # auto (default) | discord | generic
 ```
 
-All optional.
+All optional. With no `DEVEX_PR_WEBHOOK_URL` and no `[pr.webhook]`, the webhook is disabled and no network call is made.
 
 ## Error handling
 

{agex_cli-0.28.0 → agex_cli-0.29.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agex-cli"
-version = "0.28.0"
+version = "0.29.0"
 description = "Agent-operated developer-experience CLI — deterministic per-backend markdown briefings for autonomous agents."
 authors = [{name = "Ori Nachum"}]
 license = {text = "MIT"}

{agex_cli-0.28.0 → agex_cli-0.29.0}/src/devex/commands/pr/SKILL.md

@@ -87,6 +87,32 @@ no committed removal date), so devex never posts `/improve`.
 The command string lives in one place (`scripts/review.QODO_REVIEW_TRIGGER`), so
 a future Qodo rename is a one-line change for every consumer of `devex pr`.
 
+## Webhook notifications (opt-in)
+
+`pr open`, `pr reply`, and `pr review` can POST a one-shot JSON notification to an
+external webhook so something outside the repo learns the PR moved. It is **off by
+default** — devex makes the call only when a webhook URL is configured, and a
+failed POST never aborts the verb (the PR action has already succeeded).
+
+The URL is a secret (a Discord webhook URL embeds a token), so it is read **only
+from the environment**, never from `.devex/config.toml`:
+
+- `DEVEX_PR_WEBHOOK_URL` — set this and you're done (zero config).
+- or `[pr.webhook] url_env = "MY_VAR"` in `.devex/config.toml` to name a different
+  env var holding the secret. `DEVEX_PR_WEBHOOK_URL` always wins if both are set.
+
+Payload (the same inputs used to act on the PR):
+
+```json
+{"event": "pr_opened", "repo": "owner/repo", "id": 42,
+ "subject": "<PR title>", "content": "<PR body / summary>"}
+```
+
+`event` is `pr_opened` / `pr_replied` / `pr_review_triggered`. **Discord** webhooks
+are auto-detected by host and instead receive a `{content, embeds: [...]}` payload;
+set `[pr.webhook] format = auto|discord|generic` to force the shape. `pr open` fires
+only for a new, non-draft PR; `pr reply` only when at least one reply posted.
+
 ## SonarCloud project key
 
 `pr read` and `pr await` query the SonarCloud quality gate, new-code issues, and
@@ -119,9 +145,11 @@ Every command ends with a `**Next step:**` footer — chase the chain without gu
 
 Network: every command except `lint` and `delta` talks to GitHub via `gh`.
 `pr open` (non-draft, new PR) and `pr review` post the `/agentic_review` trigger
-comment.
+comment. When `DEVEX_PR_WEBHOOK_URL` (or a config-named env var) is set, `pr open` /
+`pr reply` / `pr review` also POST a best-effort notification to that webhook — the
+only non-`gh` network call, and the only one that is off unless explicitly configured.
 Disk: `pr open`, `pr read`, `pr reply`, and `pr review` append events to
-`.devex/data/pr/events.jsonl`.
+`.devex/data/pr/events.jsonl` (including `pr_webhook_posted` / `pr_webhook_failed`).
 
 ## Prerequisites
 

{agex_cli-0.28.0 → agex_cli-0.29.0}/src/devex/commands/pr/assets/templates/pr_open_result.md.j2

@@ -14,4 +14,9 @@ PR opened: **#{{ pr }}**{% if url %} ({{ url }}){% endif %}.
 {%- if review_failed %}
 > ⚠️ PR created, but posting `{{ review_command }}` failed (network/`gh`). The PR is open — run `{{ prog }} pr review {{ pr }}` to post the Qodo trigger once reachable.
 {% endif %}
+{%- if webhook_posted %}- Notified webhook of the new PR.
+{% endif %}
+{%- if webhook_failed %}
+> ⚠️ PR created, but the webhook notification failed (best-effort, skipped). The PR is open.
+{% endif %}
 {{ footer }}

{agex_cli-0.28.0 → agex_cli-0.29.0}/src/devex/commands/pr/assets/templates/pr_reply_result.md.j2

@@ -11,5 +11,9 @@
 | {{ f.line }} | {{ f.reason }} | `{{ f.entry }}` |
 {% endfor %}
 {%- endif %}
-
+{% if webhook_posted %}- Notified webhook of the replies.
+{% endif %}
+{%- if webhook_failed %}
+> ⚠️ Replies posted, but the webhook notification failed (best-effort, skipped).
+{% endif %}
 {{ footer }}

agex_cli-0.29.0/src/devex/commands/pr/assets/templates/pr_review_result.md.j2

@@ -0,0 +1,11 @@
+# `{{ prog }} pr review`
+
+Posted `{{ command }}` on PR **#{{ pr }}** to start a Qodo agentic review.
+{% if webhook_posted %}
+- Notified webhook of the review trigger.
+{%- endif %}
+{%- if webhook_failed %}
+> ⚠️ Trigger posted, but the webhook notification failed (best-effort, skipped).
+{%- endif %}
+
+{{ footer }}

agex_cli-0.29.0/src/devex/commands/pr/scripts/_webhook.py

@@ -0,0 +1,143 @@
+"""Best-effort PR-webhook policy for the `pr` namespace.
+
+Owns everything ``devex pr``-specific about the webhook — the
+``DEVEX_PR_WEBHOOK_URL`` env var, the ``[pr.webhook]`` config keys, the PR
+payload shape, and the Discord/generic format selection — and delegates the
+actual HTTP to the generic :mod:`devex.core.webhook` transport.  Keeping these
+specifics here (not in ``core/``) preserves core's command-agnostic rule.
+
+:func:`notify` is strictly **fail-open**: it resolves config first (so a
+disabled webhook does no network and no ``gh`` lookup) and swallows *every*
+error — malformed config, a ``gh`` failure resolving the repo slug, a journal
+write error — so a webhook problem can never abort ``pr open`` / ``reply`` /
+``review`` after their primary side effect already succeeded.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from devex.commands.pr.scripts import _journal
+from devex.core import config as config_mod
+from devex.core import github, webhook
+
+# The secret env var. Lives here (not in core) because it is `devex pr`-specific.
+ENV_WEBHOOK_URL = "DEVEX_PR_WEBHOOK_URL"
+
+# Discord's content field caps at 2000 chars and an embed description at 4096;
+# trim defensively below both so a large PR body never gets the POST rejected.
+_MAX_CONTENT_CHARS = 1900
+_MAX_TITLE_CHARS = 256
+
+_VALID_FORMATS = ("auto", "discord", "generic")
+
+
+def _resolve(config: Any) -> tuple[str | None, str]:
+    """Return ``(url, fmt)``; ``url`` is ``None`` when the webhook is disabled.
+
+    The secret URL is read **only** from the environment — ``DEVEX_PR_WEBHOOK_URL``
+    (wins), else the env var named by ``[pr.webhook].url_env``.  A blank or
+    whitespace-only value counts as unset (and a blank primary falls through to
+    ``url_env``).  ``fmt`` from ``[pr.webhook].format`` (``auto`` | ``discord`` |
+    ``generic``), defaulting to ``auto``.  Defensive over the open-ended ``pr``
+    dict so a malformed table degrades to disabled.
+    """
+    try:
+        webhook_cfg = dict(config.pr.get("webhook", {}) or {})
+    except (AttributeError, TypeError):
+        webhook_cfg = {}
+
+    url = (os.environ.get(ENV_WEBHOOK_URL) or "").strip() or None
+    if url is None:
+        url_env = webhook_cfg.get("url_env")
+        if url_env:
+            url = (os.environ.get(str(url_env)) or "").strip() or None
+
+    fmt = str(webhook_cfg.get("format", "auto")).lower()
+    if fmt not in _VALID_FORMATS:
+        fmt = "auto"
+    return url, fmt
+
+
+def _trim(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def _build_payload(
+    fmt: str,
+    url: str,
+    *,
+    event: str,
+    repo: str,
+    pr_id: int,
+    subject: str,
+    content: str,
+) -> dict:
+    """Shape the PR notification.
+
+    Discord (``fmt == "discord"`` or ``auto`` + a Discord URL) gets a
+    ``{content, embeds:[...]}`` envelope; everything else gets the raw fields.
+    """
+    use_discord = fmt == "discord" or (fmt == "auto" and webhook.is_discord_url(url))
+    if use_discord:
+        return {
+            "content": _trim(f"{event} on {repo}: #{pr_id} — {subject}", _MAX_TITLE_CHARS),
+            "embeds": [
+                {
+                    "title": _trim(subject, _MAX_TITLE_CHARS),
+                    "description": _trim(content, _MAX_CONTENT_CHARS),
+                    "fields": [
+                        {"name": "repo", "value": repo, "inline": True},
+                        {"name": "id", "value": str(pr_id), "inline": True},
+                        {"name": "event", "value": event, "inline": True},
+                    ],
+                }
+            ],
+        }
+    return {"event": event, "repo": repo, "id": pr_id, "subject": subject, "content": content}
+
+
+def _journal_result(pr: int, event: str, result: webhook.PostResult) -> tuple[bool, bool]:
+    posted = result is webhook.PostResult.POSTED
+    failed = result is webhook.PostResult.FAILED
+    try:
+        if posted:
+            _journal.append({"type": "pr_webhook_posted", "pr": pr, "event": event})
+        elif failed:
+            _journal.append({"type": "pr_webhook_failed", "pr": pr, "event": event})
+    except Exception:
+        pass  # nosec B110 - journal write must not break the fail-open contract
+    return posted, failed
+
+
+def notify(*, event: str, pr: int, subject: str, content: str) -> tuple[bool, bool]:
+    """Notify the configured webhook of a PR event.  Returns ``(posted, failed)``.
+
+    ``(False, False)`` means disabled — no network call and no ``gh`` repo-slug
+    lookup.  Otherwise exactly one of ``posted`` / ``failed`` is True and a
+    matching journal event (``pr_webhook_posted`` / ``pr_webhook_failed``) is
+    appended (recording only ``{type, pr, event}`` — never the URL or payload).
+    **Never raises** — any error is swallowed so a webhook problem can't abort
+    the PR verb.
+    """
+    try:
+        url, fmt = _resolve(config_mod.load())
+    except Exception:  # malformed config etc. -> disabled, never abort the verb
+        return False, False
+
+    if not url:
+        return False, False
+    if not webhook.is_http_url(url):
+        # Obviously-bad URL: surface as a failed attempt, but skip the gh round-trip.
+        return _journal_result(pr, event, webhook.PostResult.FAILED)
+
+    try:
+        repo = github._repo_slug()  # noqa: SLF001 - established accessor (cf. _sonar.py)
+        payload = _build_payload(
+            fmt, url, event=event, repo=repo, pr_id=pr, subject=subject, content=content
+        )
+        result = webhook.post(url, payload)
+    except Exception:  # gh failure / unexpected -> best-effort FAILED, never abort the verb
+        result = webhook.PostResult.FAILED
+    return _journal_result(pr, event, result)

{agex_cli-0.28.0 → agex_cli-0.29.0}/src/devex/commands/pr/scripts/open_.py

@@ -7,7 +7,7 @@ from importlib.resources import files
 from pathlib import Path
 
 from devex.commands.pr.assets.rules.next_step_rules import open_next_step
-from devex.commands.pr.scripts import _journal, review
+from devex.commands.pr.scripts import _journal, _webhook, review
 from devex.commands.pr.scripts._footer import render_footer
 from devex.core import github
 from devex.core.backend import resolve_backend
@@ -75,6 +75,17 @@ def run(
         except RuntimeError:
             review_failed = True
 
+    # Best-effort outbound webhook notify — same fail-open contract as the Qodo
+    # trigger above, gated identically (new, non-draft PR only).  When no webhook
+    # URL is configured (DEVEX_PR_WEBHOOK_URL / [pr.webhook].url_env), this makes
+    # no network call and leaves both flags False.  `body` is the signed body.
+    webhook_posted = False
+    webhook_failed = False
+    if not was_already_open and not draft:
+        webhook_posted, webhook_failed = _webhook.notify(
+            event="pr_opened", pr=pr, subject=title, content=body
+        )
+
     footer_key, footer_ctx = open_next_step(pr, was_already_open)
     footer = render_footer(footer_key, backend, footer_ctx)
 
@@ -91,6 +102,8 @@ def run(
             "review_posted": review_posted,
             "review_failed": review_failed,
             "review_command": review.QODO_REVIEW_TRIGGER,
+            "webhook_posted": webhook_posted,
+            "webhook_failed": webhook_failed,
             "footer": footer,
         },
     )

{agex_cli-0.28.0 → agex_cli-0.29.0}/src/devex/commands/pr/scripts/reply.py

@@ -9,7 +9,7 @@ from importlib.resources import files
 from pathlib import Path
 
 from devex.commands.pr.assets.rules.next_step_rules import reply_next_step
-from devex.commands.pr.scripts import _journal
+from devex.commands.pr.scripts import _journal, _webhook
 from devex.commands.pr.scripts._footer import render_footer
 from devex.core import github
 from devex.core.backend import resolve_backend
@@ -141,6 +141,19 @@ def run(
 
     _journal.append({"type": "pr_batch_replied", "pr": pr, "count": posted, "resolved": resolved})
 
+    # Best-effort webhook notify — only when at least one reply was posted (a
+    # no-op or all-failed batch shouldn't notify).  `content` is a concise batch
+    # summary rather than every reply body.  Disabled = no network call.
+    webhook_posted = False
+    webhook_failed = False
+    if posted:
+        webhook_posted, webhook_failed = _webhook.notify(
+            event="pr_replied",
+            pr=pr,
+            subject=f"Replied on PR #{pr}",
+            content=f"Posted {posted} comment(s); resolved {resolved} thread(s).",
+        )
+
     footer_key, footer_ctx = reply_next_step(pr=pr, failure_count=len(failures))
     footer = render_footer(footer_key, backend, footer_ctx)
 
@@ -152,6 +165,8 @@ def run(
             "count": posted,
             "resolved": resolved,
             "failures": [f.__dict__ for f in failures],
+            "webhook_posted": webhook_posted,
+            "webhook_failed": webhook_failed,
             "footer": footer,
         },
     )

{agex_cli-0.28.0 → agex_cli-0.29.0}/src/devex/commands/pr/scripts/review.py

@@ -14,7 +14,7 @@ from importlib.resources import files
 from pathlib import Path
 
 from devex.commands.pr.assets.rules.next_step_rules import review_next_step
-from devex.commands.pr.scripts import _journal
+from devex.commands.pr.scripts import _journal, _webhook
 from devex.commands.pr.scripts._footer import render_footer
 from devex.core import github
 from devex.core.backend import resolve_backend
@@ -44,6 +44,16 @@ def run(agent: str | None, project_dir: Path, pr: int | None) -> tuple[str, int,
 
     post_trigger(pr_number)
 
+    # Best-effort webhook notify for the explicit `pr review` verb.  Deliberately
+    # NOT inside post_trigger(): `pr open` calls post_trigger() for its auto-review
+    # and must emit only `pr_opened`, never a second `pr_review_triggered`.
+    webhook_posted, webhook_failed = _webhook.notify(
+        event="pr_review_triggered",
+        pr=pr_number,
+        subject=f"Review triggered on PR #{pr_number}",
+        content=QODO_REVIEW_TRIGGER,
+    )
+
     footer_key, footer_ctx = review_next_step(pr_number)
     footer = render_footer(footer_key, backend, footer_ctx)
 
@@ -53,6 +63,8 @@ def run(agent: str | None, project_dir: Path, pr: int | None) -> tuple[str, int,
         {
             "pr": pr_number,
             "command": QODO_REVIEW_TRIGGER,
+            "webhook_posted": webhook_posted,
+            "webhook_failed": webhook_failed,
             "footer": footer,
         },
     )