From a73ed933a24904d7efeee93b5173fc484c34e803 Mon Sep 17 00:00:00 2001
From: Dmitry Teryaev <doudmitry@gmail.com>
Date: Fri, 10 Jul 2026 11:18:52 +0300
Subject: [PATCH] feat: add gRPC transport (agctl grpc)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First-class in-tree gRPC transport — a fifth transport alongside
http/kafka/db/logs. Every command emits one JSON envelope with
deterministic exit codes; gRPC status is a result (ok:true, exit 0)
unless an assertion fails, mirroring HTTP 4xx.

- grpc: config section (targets/descriptors/templates) + pydantic models
  (GrpcTls/GrpcTarget/GrpcDescriptorSource/GrpcTemplate/GrpcConfig) and
  cross-reference validation.
- GrpcClient: reflection-first/descriptor-fallback proto resolution
  (file_containing_symbol), JSON<->protobuf (json_format/message_factory,
  no generated _pb2), all four call types, healthcheck (grpc.health.v1),
  mTLS, lazy imports + DI seams.
- gRPC assertions: validate_grpc_assertion_args + evaluate_grpc_assertions
  reusing the jq/subset/equals primitives + a hardcoded status map.
- grpc call: template + free-form; unary/client-stream return one envelope;
  server-stream/bidi stream NDJSON out + consume NDJSON in (stdin), with
  signal-driven stop + a terminal-status summary.
- grpc healthcheck; grpc-services/grpc-methods discover categories.
- grpc extra (grpcio/grpcio-tools/grpcio-health-checking/grpcio-reflection/
  protobuf/jq) + integration aggregate + CI install line.
- Docs: DESIGN (struck from future-work; added throughout), ARCHITECTURE,
  sample config, consumer skill, README.

Design via brainstorming -> spec -> plan -> 14 TDD tasks (each per-task
reviewed) + an independent 4-reviewer fan-out code review; all Critical
and Important findings fixed. Full suite + live in-process grpcio
integration tests green.

Spec: docs/superpowers/specs/active/2026-07-09-grpc-support-design.md
Plan: docs/superpowers/plans/active/2026-07-09-grpc-support.md

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/workflows/test.yml                    |    2 +-
 .gitignore                                    |    6 +
 .superpowers/sdd/task-10-report.md            |  113 --
 README.md                                     |   40 +-
 agctl/assertions.py                           |  215 +++
 agctl/cli.py                                  |   11 +
 agctl/clients/grpc_client.py                  |  909 +++++++++++++
 agctl/commands/discover_commands.py           |  101 +-
 agctl/commands/grpc_commands.py               |  822 +++++++++++
 agctl/config/models.py                        |   46 +
 agctl/config/validator.py                     |   35 +
 agctl/data/sample-config.yaml                 |   33 +
 docs/ARCHITECTURE.md                          |  103 +-
 docs/DESIGN.md                                |  241 +++-
 .../plans/active/2026-07-09-grpc-support.md   |  764 +++++++++++
 .../active/2026-07-09-grpc-support-design.md  |  615 +++++++++
 pyproject.toml                                |    3 +-
 skills/agctl/SKILL.md                         |   48 +
 tests/fixtures/agctl.yaml                     |   16 +
 tests/fixtures/echo.proto                     |   19 +
 tests/fixtures/echo_descriptor.pb             |   14 +
 tests/fixtures/echo_pb2.py                    |   40 +
 tests/fixtures/echo_pb2_grpc.py               |  226 +++
 tests/integration/test_grpc_commands.py       |  512 +++++++
 tests/unit/test_config_validator.py           |  169 +++
 tests/unit/test_discover_command.py           |  213 +++
 tests/unit/test_grpc_assertions.py            |  169 +++
 tests/unit/test_grpc_client.py                | 1212 +++++++++++++++++
 tests/unit/test_grpc_commands.py              | 1134 +++++++++++++++
 tests/unit/test_models.py                     |   86 ++
 30 files changed, 7792 insertions(+), 125 deletions(-)
 delete mode 100644 .superpowers/sdd/task-10-report.md
 create mode 100644 agctl/clients/grpc_client.py
 create mode 100644 agctl/commands/grpc_commands.py
 create mode 100644 docs/superpowers/plans/active/2026-07-09-grpc-support.md
 create mode 100644 docs/superpowers/specs/active/2026-07-09-grpc-support-design.md
 create mode 100644 tests/fixtures/echo.proto
 create mode 100644 tests/fixtures/echo_descriptor.pb
 create mode 100644 tests/fixtures/echo_pb2.py
 create mode 100644 tests/fixtures/echo_pb2_grpc.py
 create mode 100644 tests/integration/test_grpc_commands.py
 create mode 100644 tests/unit/test_config_validator.py
 create mode 100644 tests/unit/test_grpc_assertions.py
 create mode 100644 tests/unit/test_grpc_client.py
 create mode 100644 tests/unit/test_grpc_commands.py

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 64b7245..1bcda83 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -32,7 +32,7 @@ jobs:
       - name: Install agctl with all client extras and test deps
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev,http,jq,kafka,db,logs]"
+          pip install -e ".[dev,http,jq,kafka,db,logs,grpc]"
 
       - name: Run tests
         run: pytest
diff --git a/.gitignore b/.gitignore
index ec0252d..0fa3b18 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,3 +29,9 @@ uv.lock
 
 # agctl test-runbook results (ephemeral per-run reports)
 *.results.md
+
+# agctl mock daemon runtime state (pidfiles + logs; default state-dir ./.agctl/)
+.agctl/
+
+# superpowers SDD scratch (task briefs/reports, review packages, progress ledger)
+.superpowers/
diff --git a/.superpowers/sdd/task-10-report.md b/.superpowers/sdd/task-10-report.md
deleted file mode 100644
index 53ffe0e..0000000
--- a/.superpowers/sdd/task-10-report.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# Task 10 Report: Config Overlay + Runbook Sidecar Documentation Sync
-
-## Summary
-
-Config overlay and runbook sidecar feature documentation synced across DESIGN.md, ARCHITECTURE.md, and skills/agctl/SKILL.md. All changes reflect the as-built implementation on branch `config-overlay-sidecar`.
-
-## Files Changed
-
-### `/Users/dmitry/Desktop/CursorProjects/agenttest/docs/DESIGN.md`
-
-**§3 (CLI Command Design) — Global flags table:**
-- Added `--overlay <path>` row: "Overlay config fragment (repeatable; later wins); layered on base config"
-
-**§2.4 (Configuration Schema) — New section:**
-- Added complete overlay documentation covering:
-  - Overlay syntax (partial config with optional version)
-  - Usage via `--overlay <path>` (repeatable)
-  - Runbook sidecar convention (`<runbook-base>.agctl.yaml`)
-  - Merge behavior (sidecar-wins: recursive dict merge, scalar/list replace, type clash → error)
-  - Override tracking in `config validate --overlay`
-  - Precedence: base < overlays < AGCTL_* env vars
-  - Schema version note (not a version bump)
-
-**§5 (Configuration Resolution Order):**
-- Updated precedence chain from 5 to 6 steps
-- Inserted overlays as step 5: `--overlay <path>` flags after interpolation, before env overrides
-- Clarified that overlays are applied in flag order (later wins)
-
-**§3.6 (`agctl config` — Config Introspection):**
-- Updated `config validate` command: added `--overlay <path>` flag documentation
-- Updated `config show` command: added `--overlay <path>` flag documentation
-- Documented output shape changes: `config show --overlay` emits `{"config": ..., "overrides": [...]}`; back-compat form without overlays
-
-**§3.7 (`agctl discover` — Lazy Scoped Discovery):**
-- Added section intro note: "All `discover` commands accept `--overlay <path>`"
-- Updated all four discover invocation forms:
-  - Level 0 (summary): `agctl discover [--overlay <path>]`
-  - Level 1 (category): `agctl discover --category <name> [--overlay <path>]`
-  - Level 2 (item): `agctl discover --category <name> --name <item-name> [--overlay <path>]`
-  - Search: `agctl discover --search <term> [--overlay <path>]`
-
-**§3.5 (`agctl mock` — Mock Server):**
-- Updated `mock run` command: added `--overlay <path>` flag
-- Updated `mock start` command: added `--overlay <path>` flag with note "forwarded to the daemon"
-
-**§4.2 (Result Shapes by Command Group):**
-- Updated `config.validate` output: documented `warnings` array with override records
-- Updated `config.show` output: documented branch result shape with `{"config": ..., "overrides": [...]}`
-
-### `/Users/dmitry/Desktop/CursorProjects/agenttest/docs/ARCHITECTURE.md`
-
-**§5 (Configuration Pipeline):**
-- Extended as-built pipeline diagram with overlay loop:
-  - After base interpolation and `_check_version`
-  - For each overlay: discover (explicit only) → interpolate → `PartialConfig.model_validate` → version-major-match check → `deep_merge`
-  - Then `apply_env_overrides` on MERGED dict (AGCTL_* wins over overlays)
-  - Finally `Config.model_validate` (final)
-
-- Added "Overlay types" subsection:
-  - Documented `PartialConfig` (Config with optional version)
-  - Documented `ComposedConfig` NamedTuple (config + overrides list)
-  - Documented override record shape: `{"path": "<dotted>", "overlay": "<file>"}`
-
-- Added "Deep merge" subsection:
-  - Documented `deep_merge(base, overlay, overlay_name, overrides)` algorithm
-  - Specified merge contract: sidecar-wins, recursive dict merge, scalar/list replace, override recording at leaves
-
-### `/Users/dmitry/Desktop/CursorProjects/agenttest/skills/agctl/SKILL.md`
-
-**Command forms section:**
-- Updated global flags line from "Only `--config <path>` is global" to "`--config <path>` and `--overlay <path>` (repeatable) are global"
-
-**Rationale:** The skill documents operational command surfaces. The global `--overlay` flag is part of that surface and agents need to know it exists when composing commands (especially when following runbook preconditions that require overlays).
-
-## Altitude Preserved
-
-All updates respect document altitude:
-- **DESIGN.md** captures user-facing contract (WHAT/WHY): overlay syntax, precedence, CLI surface, output shapes
-- **ARCHITECTURE.md** captures as-built implementation (HOW): pipeline stages, types, merge algorithm
-- **skills/agctl/SKILL.md** captures operational surface: global flags an agent must know
-
-No implementation details leaked into DESIGN.md, no user-facing contract leaked into ARCHITECTURE.md, and no design rationale leaked into skills/.
-
-## Cross-References Verified
-
-- DESIGN §2.4 overlays → DESIGN §3 global flags table → DESIGN §5 precedence order
-- DESIGN §3.6 config commands → DESIGN §4.2 output shapes
-- DESIGN §3.7 discover → references overlay support
-- DESIGN §3.5 mock commands → overlay forwarding to daemon
-- ARCHITECTURE §5 pipeline → references `compose_config`, `PartialConfig`, `ComposedConfig`, `deep_merge`
-- skills/agctl → references global `--overlay` flag
-
-## Code Review Verification
-
-All documentation changes were verified against the as-built code:
-- CLI flag registration in `agctl/cli.py`
-- `PartialConfig` model in `agctl/config/models.py`
-- `compose_config` pipeline in `agctl/config/loader.py`
-- `deep_merge` algorithm in `agctl/config/loader.py`
-- Command threading in `agctl/commands/*_commands.py`
-- Output shape changes in `agctl/commands/config_commands.py`
-
-## No Changes Intentionally Omitted
-
-Assessed and found not requiring changes:
-- `agctl/data/sample-config.yaml` — frozen by drift-guard test; out of scope for docs-watcher
-- `.env.example` — not part of this feature
-- Test files — out of scope for docs-watcher
-- Archived specs — frozen history
-
-## Conclusion
-
-All three document families (DESIGN, ARCHITECTURE, skills/agctl) have been updated to reflect the config overlay and runbook sidecar feature at their respective altitudes. Documentation now matches the as-built implementation on branch `config-overlay-sidecar` (tip 4337f63).
diff --git a/README.md b/README.md
index 80fc04c..8135dfb 100644
--- a/README.md
+++ b/README.md
@@ -66,9 +66,10 @@ pip install -e ".[http]"            # http call / request / ping / check ready
 pip install -e ".[jq]"             # jq flags: http --match/--jq-path, mock match.jq
 pip install -e ".[kafka]"           # kafka produce / consume / assert
 pip install -e ".[db]"              # db query / assert
+pip install -e ".[grpc]"            # grpc call / healthcheck (includes grpcio, protobuf, jq)
 pip install -e ".[logs]"            # logs query / assert / tail (includes jq)
-pip install -e ".[http,kafka,db]"   # everything except logs (typical — bundles jq)
-pip install -e ".[http,kafka,db,logs]"   # everything
+pip install -e ".[http,kafka,db]"   # everything except logs/grpc (typical — bundles jq)
+pip install -e ".[http,kafka,db,grpc,logs]"   # everything
 ```
 
 Verify the install — both binary names work:
@@ -111,6 +112,8 @@ auto-discovered from the current directory upward).
 | | `assert` | Fail (exit 1) unless a matching message arrives within `--timeout`. Modes: `--contains`, `--match <jq>`, `--pattern <name>` (combinable) |
 | **`db`** | `query` | Run `--template` or free-form `--sql`; return all rows |
 | | `assert` | Assert `--expect-rows N`, or `--expect-value --path <jq> --equals <v>` on the first row |
+| **`grpc`** | `call <template>` | Execute a named gRPC template (unary, client-stream, server-stream, bidi) |
+| | `healthcheck` | gRPC health check via grpc.health.v1.Health |
 | **`logs`** | `query` | Scan log sources; filter by `--since`, `--match` (jq), `--level` |
 | | `assert` | Assert logs match/nmatch a condition within `--timeout` (one-shot or poll) |
 | | `tail` | Stream log entries as NDJSON (with `--duration` or `--until-stopped`) |
@@ -345,6 +348,39 @@ defaults:
   timeout_seconds: 10
   database_connection: main-db
 
+# --- grpc: gRPC service targets and templates -------------------------------
+grpc:
+  # targets: named gRPC server addresses
+  targets:
+    order-service:
+      address: "localhost:50051"
+      use_tls: false               # optional; defaults to false (plaintext)
+      reflection: auto             # auto (default) | on | off
+      # tls:                       # optional TLS settings (when use_tls: true)
+      #   override_authority: ""  # optional; override the TLS server name
+
+  # descriptors: fallback proto descriptor sets when reflection is unavailable.
+  # Each entry sets exactly one of `descriptor_set` (a compiled FileDescriptorSet
+  # .pb file) or `proto` (a .proto glob compiled at load via protoc; pair with
+  # `include_paths`).
+  descriptors:
+    - descriptor_set: "protos/order-service.desc"
+    # - proto: "protos/orders/v1/*.proto"
+    #   include_paths: ["protos"]
+
+  # templates: named gRPC request templates
+  templates:
+    create-order:
+      description: "Create a new order via gRPC"
+      target: order-service
+      service: "orders.OrderService"
+      method: "CreateOrder"
+      message:
+        customer_id: "{customer_id}"
+        items:
+          - sku: "{sku}"
+            quantity: 1
+
 # --- logs: log file sources for tailing and searching ------------------------
 logs:
   sources:
diff --git a/agctl/assertions.py b/agctl/assertions.py
index 812da13..bf9a243 100644
--- a/agctl/assertions.py
+++ b/agctl/assertions.py
@@ -12,6 +12,29 @@
 
 from .errors import AssertionFailure, ConfigError
 
+# gRPC status code mappings. Mirrors grpc.StatusCode; hardcoded to keep this module grpc-free.
+_GRPC_STATUS_BY_NAME: dict[str, int] = {
+    "OK": 0,
+    "CANCELLED": 1,
+    "UNKNOWN": 2,
+    "INVALID_ARGUMENT": 3,
+    "DEADLINE_EXCEEDED": 4,
+    "NOT_FOUND": 5,
+    "ALREADY_EXISTS": 6,
+    "PERMISSION_DENIED": 7,
+    "RESOURCE_EXHAUSTED": 8,
+    "FAILED_PRECONDITION": 9,
+    "ABORTED": 10,
+    "OUT_OF_RANGE": 11,
+    "UNIMPLEMENTED": 12,
+    "INTERNAL": 13,
+    "UNAVAILABLE": 14,
+    "DATA_LOSS": 15,
+    "UNAUTHENTICATED": 16,
+}
+
+_GRPC_STATUS_BY_CODE: dict[int, str] = {v: k for k, v in _GRPC_STATUS_BY_NAME.items()}
+
 # A dotted jq path whose final segment contains a hyphen, e.g.
 # ``.headers.x-request-id`` or ``.body.event-type``. jq parses such segments
 # as subtraction, producing a baffling compile error; this lets ``compile_jq``
@@ -405,3 +428,195 @@ def evaluate_http_assertions(
             f"HTTP response failed {len(failures)} assertion(s)",
             {"response": result, "failures": failures},
         )
+
+
+def validate_grpc_assertion_args(
+    *,
+    status: str | int | None = None,
+    contains: str | None = None,
+    match: str | None = None,
+    jq_path: str | None = None,
+    equals: str | None = None,
+) -> None:
+    """Pre-request gate for gRPC assertions (mirrors HTTP validation).
+
+    Pure arg validation only -- never touches the network, so misuse fails
+    BEFORE the request side-effect is triggered.
+
+    Raises :class:`ConfigError` (exit 2) on:
+      - **pairing**: exactly one of ``jq_path``/``equals`` set ->
+        ``--jq-path and --equals must be used together``.
+      - ``--contains`` present but not valid JSON ->
+        ``--contains must be valid JSON``.
+      - ``--status`` present but not a valid gRPC code name or number 0-16 ->
+        ``--status must be a gRPC code name or number 0-16, got {status!r}```.
+
+    Returns ``None`` (no-op) when args are sound -- including the all-None case.
+    """
+    # pairing: jq_path and equals must be used together (XOR on None-ness)
+    if (jq_path is None) != (equals is None):
+        raise ConfigError("--jq-path and --equals must be used together", {})
+    # --contains must parse as JSON when present
+    if contains is not None:
+        try:
+            json.loads(contains)
+        except (json.JSONDecodeError, ValueError):
+            raise ConfigError("--contains must be valid JSON", {})
+    # --status must be a valid gRPC code name or number 0-16
+    if status is not None:
+        # Coerce a numeric string (e.g. "5" arriving from the Click CLI, which
+        # declares --status as type=str) to int BEFORE the lookup — otherwise the
+        # int branch below is unreachable from the CLI and --status 5 is rejected.
+        # gRPC codes are 0-16 (non-negative); ``isdigit`` suffices.
+        if isinstance(status, str) and status.isdigit():
+            status = int(status)
+        # If it's a string, must be in _GRPC_STATUS_BY_NAME
+        if isinstance(status, str):
+            if status not in _GRPC_STATUS_BY_NAME:
+                raise ConfigError(
+                    f"--status must be a gRPC code name or number 0-16, got {status!r}",
+                    {},
+                )
+        # If it's an int, must be in _GRPC_STATUS_BY_CODE
+        elif isinstance(status, int):
+            if status not in _GRPC_STATUS_BY_CODE:
+                raise ConfigError(
+                    f"--status must be a gRPC code name or number 0-16, got {status!r}",
+                    {},
+                )
+        else:
+            # Wrong type (neither str nor int)
+            raise ConfigError(
+                f"--status must be a gRPC code name or number 0-16, got {status!r}",
+                {},
+            )
+    return None
+
+
+def evaluate_grpc_assertions(
+    result: dict,
+    *,
+    status: str | int | None = None,
+    contains: str | None = None,
+    match: str | None = None,
+    jq_path: str | None = None,
+    equals: str | None = None,
+) -> None:
+    """Post-request evaluation of a gRPC response against active assertion modes.
+
+    Assumes :func:`validate_grpc_assertion_args` has already run on the same
+    args (so pairing is satisfied, ``--contains`` is valid JSON, and ``--status``
+    is a valid code name or number).
+
+    Evaluates each active mode, collecting a failure entry per failing mode
+    (NO short-circuit -- all modes run, all failures are reported). If any
+    failures were collected, raises :class:`AssertionFailure` whose
+    ``detail`` carries BOTH the full ``response`` dict and the ``failures``
+    list.
+
+    For ``--match`` / ``--jq-path``, a missing ``jq`` library surfaces from
+    ``_jq()`` as a :class:`ConfigError` whose message names only db/kafka;
+    it is re-raised here pointing at ``pip install 'agctl[grpc]'``.
+
+    Per-mode failure entry shapes (pinned, parsed by downstream agents):
+      - ``status``:   ``{"mode":"status","expected":<arg>,"actual":<status name>}``
+      - ``contains``: ``{"mode":"contains","needle":<parsed>,"matched":False,
+                        "root":"response message","body":<message snapshot>}``
+      - ``match``:    ``{"mode":"match","expr":<match>,"result":False,
+                        "root":"response envelope","body":<message snapshot>}``
+      - ``jq-path``:  ``{"mode":"jq-path","path":<jq_path>,
+                        "expected":<parse_equals(equals)>,"actual":<jq_value or None>,
+                        "root":"response message","body":<message snapshot>}``
+
+    The ``root`` label differs per mode because the modes root differently:
+    ``--match`` at the response envelope (whole result dict), ``--contains``/``--jq-path``
+    at the response message (``result['message']``).
+    """
+    if all(arg is None for arg in (status, contains, match, jq_path, equals)):
+        return None
+
+    failures = []
+
+    # Status assertion: normalize arg to code, compare to result['status']['code']
+    if status is not None:
+        # Normalize status arg to a code (coerce numeric string from CLI — see
+        # validate_grpc_assertion_args; both must agree on the coercion).
+        if isinstance(status, str) and status.isdigit():
+            status = int(status)
+        if isinstance(status, str):
+            expected_code = _GRPC_STATUS_BY_NAME[status]
+        else:  # int
+            expected_code = status
+        actual_code = result["status"]["code"]
+        if expected_code != actual_code:
+            failures.append(
+                {
+                    "mode": "status",
+                    "expected": status,
+                    "actual": result["status"]["name"],
+                }
+            )
+
+    # Contains assertion: check result['message'] subset match
+    if contains is not None:
+        needle = json.loads(contains)  # validated safe by validate_grpc_assertion_args
+        if not json_subset(needle, result.get("message")):
+            failures.append(
+                {
+                    "mode": "contains",
+                    "needle": needle,
+                    "matched": False,
+                    "root": "response message",
+                    "body": _response_body_snapshot(result.get("message")),
+                }
+            )
+
+    # Match assertion: evaluate jq against the whole result dict (envelope-rooted)
+    if match is not None:
+        try:
+            ok = jq_bool(result, match)
+        except ConfigError:
+            # Re-raise with grpc-specific install hint
+            raise ConfigError(
+                "jq is required for match assertions: pip install 'agctl[grpc]'",
+                {"expr": match},
+            ) from None
+        if not ok:
+            failures.append(
+                {
+                    "mode": "match",
+                    "expr": match,
+                    "result": False,
+                    "root": "response envelope",
+                    "body": _response_body_snapshot(result.get("message")),
+                }
+            )
+
+    # jq-path assertion: evaluate against result['message']
+    if jq_path is not None:  # equals is non-None too (validated pairing)
+        expected = parse_equals(equals)
+        try:
+            actual = jq_value(result.get("message"), jq_path)
+        except ConfigError:
+            # Re-raise with grpc-specific install hint
+            raise ConfigError(
+                "jq is required for jq-path assertions: pip install 'agctl[grpc]'",
+                {"path": jq_path},
+            ) from None
+        if not type_aware_equal(actual, expected):
+            failures.append(
+                {
+                    "mode": "jq-path",
+                    "path": jq_path,
+                    "expected": expected,
+                    "actual": actual,
+                    "root": "response message",
+                    "body": _response_body_snapshot(result.get("message")),
+                }
+            )
+
+    if failures:
+        raise AssertionFailure(
+            f"gRPC response failed {len(failures)} assertion(s)",
+            {"response": result, "failures": failures},
+        )
diff --git a/agctl/cli.py b/agctl/cli.py
index 8a24bda..4c5761e 100644
--- a/agctl/cli.py
+++ b/agctl/cli.py
@@ -24,6 +24,7 @@
 )
 from .commands.db_commands import db_assert, db_execute, db_query, db_schema
 from .commands.discover_commands import discover
+from .commands.grpc_commands import grpc_call, grpc_healthcheck
 from .commands.http_commands import http_call, http_ping, http_request
 from .commands.kafka_commands import kafka_assert, kafka_consume, kafka_produce
 from .commands.logs_commands import logs_assert, logs_query, logs_tail
@@ -145,6 +146,11 @@ def logs_group() -> None:
     """Log query/assert/tail commands."""
 
 
+@cli.group(name="grpc")
+def grpc_group() -> None:
+    """gRPC call/healthcheck commands."""
+
+
 @cli.group(name="check")
 def check_group() -> None:
     """Health/readiness checks."""
@@ -186,6 +192,11 @@ def mock_group() -> None:
 logs_group.add_command(logs_tail)
 
 
+# Register subcommands on the grpc group.
+grpc_group.add_command(grpc_call)
+grpc_group.add_command(grpc_healthcheck)
+
+
 # Register subcommands on the check group.
 check_group.add_command(check_ready)
 
diff --git a/agctl/clients/grpc_client.py b/agctl/clients/grpc_client.py
new file mode 100644
index 0000000..d09a05b
--- /dev/null
+++ b/agctl/clients/grpc_client.py
@@ -0,0 +1,909 @@
+"""gRPC client DTOs and skeleton with lazy grpcio import."""
+
+from __future__ import annotations
+
+import pathlib
+from dataclasses import dataclass
+
+from agctl.config.models import GrpcTarget
+from agctl.errors import ConfigError
+
+
+@dataclass
+class GrpcStatus:
+    """gRPC status code and metadata."""
+
+    code: int
+    name: str
+    message: str = ""
+
+
+@dataclass
+class GrpcUnaryResult:
+    """Result of a unary or client-streaming gRPC call."""
+
+    target: str
+    service: str
+    method: str
+    call_type: str
+    status: GrpcStatus
+    message: dict | None
+    initial_metadata: dict
+    trailers: dict
+
+
+@dataclass
+class GrpcStreamMessage:
+    """A single message from a server-streaming or bidirectional stream."""
+
+    message: dict
+    trailers: dict | None
+
+
+@dataclass
+class GrpcHealthResult:
+    """Result of a gRPC health check."""
+
+    target: str
+    address: str
+    status: str
+    note: str | None = None
+
+
+def _add_file_protos_order_tolerant(pool, file_protos) -> None:
+    """Add FileDescriptorProtos to the pool regardless of dependency order.
+
+    protoc's FileDescriptorSet.file order is NOT guaranteed dependency-first,
+    and the descriptor pool validates dependencies eagerly (raising TypeError
+    for a file whose import is not yet loaded — even via AddSerializedFile).
+    Make repeated passes, deferring any file whose dependency is not yet loaded,
+    until all are added. If no file can be added in a pass, surface the genuine
+    error by re-adding the first remaining file. See review finding I5.
+    """
+    remaining = list(file_protos)
+    while remaining:
+        progress = False
+        deferred = []
+        for fd in remaining:
+            try:
+                pool.AddSerializedFile(fd.SerializeToString())
+                progress = True
+            except TypeError:
+                deferred.append(fd)
+        if not progress:
+            # No file could be added -> genuine error (missing import, etc.).
+            # Re-raise so the real cause surfaces.
+            pool.AddSerializedFile(remaining[0].SerializeToString())
+        remaining = deferred
+
+
+class GrpcClient:
+    """gRPC client with lazy grpcio import and DI support."""
+
+    def __init__(
+        self,
+        target: GrpcTarget,
+        *,
+        channel=None,
+        descriptor_pool=None,
+        descriptors=None,
+        timeout_seconds: float | None = None,
+    ):
+        """Initialize gRPC client.
+
+        Args:
+            target: gRPC target configuration.
+            channel: Optional injected gRPC channel (bypasses grpcio import).
+            descriptor_pool: Optional injected descriptor pool.
+            descriptors: Optional list of GrpcDescriptorSource for fallback resolution.
+            timeout_seconds: Optional timeout for calls in seconds.
+        """
+        self._target = target
+        self._channel = channel
+        self._pool = descriptor_pool
+        self._descriptors = descriptors
+        self._timeout = timeout_seconds
+        self.terminal_status: GrpcStatus = GrpcStatus(0, "OK", "")
+
+        # Lazy import grpcio only when no channel is injected
+        if channel is None:
+            try:
+                import grpc
+            except ImportError as exc:
+                raise ConfigError(
+                    "gRPC support requires the 'grpc' extra: pip install 'agctl[grpc]'",
+                    {},
+                ) from exc
+            self._grpc = grpc
+
+            # Build channel from target
+            if not target.use_tls:
+                # Plaintext h2c channel
+                self._channel = grpc.insecure_channel(target.address)
+            else:
+                # TLS channel with credentials (mTLS support)
+                # Read file bytes for each TLS field (empty-string-counts-as-unset convention)
+                ca_bytes = None
+                cert_bytes = None
+                key_bytes = None
+
+                if target.tls.ca_location:
+                    try:
+                        ca_bytes = pathlib.Path(target.tls.ca_location).read_bytes()
+                    except Exception as exc:
+                        raise ConfigError(
+                            f"gRPC tls.ca_location file not readable: {target.tls.ca_location}: {exc}",
+                            {"path": target.tls.ca_location},
+                        ) from exc
+
+                if target.tls.certificate_location:
+                    try:
+                        cert_bytes = pathlib.Path(target.tls.certificate_location).read_bytes()
+                    except Exception as exc:
+                        raise ConfigError(
+                            f"gRPC tls.certificate_location file not readable: {target.tls.certificate_location}: {exc}",
+                            {"path": target.tls.certificate_location},
+                        ) from exc
+
+                if target.tls.key_location:
+                    try:
+                        key_bytes = pathlib.Path(target.tls.key_location).read_bytes()
+                    except Exception as exc:
+                        raise ConfigError(
+                            f"gRPC tls.key_location file not readable: {target.tls.key_location}: {exc}",
+                            {"path": target.tls.key_location},
+                        ) from exc
+
+                # Build credentials with the provided file bytes
+                credentials = grpc.ssl_channel_credentials(
+                    root_certificates=ca_bytes,
+                    certificate_chain=cert_bytes,
+                    private_key=key_bytes,
+                )
+
+                # Apply override_authority if set
+                if target.tls.override_authority:
+                    self._channel = grpc.secure_channel(
+                        target.address,
+                        credentials,
+                        options=(
+                            ("grpc.ssl_target_name_override", target.tls.override_authority),
+                            ("grpc.authority", target.tls.override_authority),
+                        ),
+                    )
+                else:
+                    self._channel = grpc.secure_channel(target.address, credentials)
+
+    def resolve_descriptors(self):
+        """Resolve service/method descriptors from proto files.
+
+        Resolution order:
+        1. Injected pool (self._pool is not None) → return it directly
+        2. Reflection (if reflection in ("auto", "on")) → query server
+        3. Descriptor fallback (from self._descriptors) → load from files
+
+        Returns:
+            DescriptorPool: A pool containing all resolved descriptors.
+
+        Raises:
+            ConfigError: If reflection is requested but unavailable and no descriptors.
+        """
+        # Path 1: Injected pool (test seam / pre-resolved)
+        if self._pool is not None:
+            return self._pool
+
+        # Path 2: Reflection
+        if self._target.reflection in ("auto", "on"):
+            # Local import: on the channel-injected DI path self._grpc is None,
+            # so referencing self._grpc here would AttributeError before the
+            # UNIMPLEMENTED handling (see review finding M2).
+            import grpc
+
+            try:
+                return self._resolve_via_reflection()
+            except grpc.RpcError as exc:
+                # Check if this is an UNIMPLEMENTED error via status code
+                if exc.code() == grpc.StatusCode.UNIMPLEMENTED:
+                    if self._target.reflection == "on":
+                        # Reflection explicitly requested but not available
+                        raise ConfigError(
+                            "reflection requested but the server does not implement it; "
+                            "set grpc.targets.<name>.reflection: off and supply grpc.descriptors",
+                            {"target": self._target.address},
+                        ) from exc
+                    # If reflection == "auto", fall through to descriptor path
+                    pass
+                else:
+                    # Other reflection errors should propagate
+                    raise
+
+        # Path 3: Descriptor fallback
+        return self._resolve_via_descriptors()
+
+    def _resolve_via_reflection(self):
+        """Resolve descriptors via server reflection service.
+
+        Returns:
+            DescriptorPool: Pool built from reflection responses.
+
+        Raises:
+            Exception: If reflection query fails (including UNIMPLEMENTED).
+        """
+        from grpc_reflection.v1alpha import reflection_pb2
+        from grpc_reflection.v1alpha import reflection_pb2_grpc
+
+        # Create reflection stub
+        reflection_stub = reflection_pb2_grpc.ServerReflectionStub(
+            self._channel
+        )
+
+        # List all services via reflection
+        request = reflection_pb2.ServerReflectionRequest(
+            list_services=""
+        )
+        response = reflection_stub.ServerReflectionInfo(iter([request]))
+
+        # Collect all file descriptor protos
+        from google.protobuf import descriptor_pool
+
+        pool = descriptor_pool.DescriptorPool()
+        seen_files = set()  # Track files we've already collected
+        all_file_protos = []
+
+        # Collect service names from list_services_response
+        service_names = []
+        for response_msg in response:
+            if response_msg.HasField("list_services_response"):
+                for service in response_msg.list_services_response.service:
+                    # Skip reflection and health services
+                    if service.name not in ("grpc.reflection.v1alpha.ServerReflection", "grpc.health.v1.Health"):
+                        service_names.append(service.name)
+
+        # Request file descriptor for each service by symbol name
+        for service_name in service_names:
+            # Request file descriptor containing this service symbol
+            symbol_request = reflection_pb2.ServerReflectionRequest(
+                file_containing_symbol=service_name
+            )
+            symbol_response = reflection_stub.ServerReflectionInfo(
+                iter([symbol_request])
+            )
+
+            for response_msg in symbol_response:
+                if response_msg.HasField("file_descriptor_response"):
+                    from google.protobuf import descriptor_pb2
+                    for fd_bytes in response_msg.file_descriptor_response.file_descriptor_proto:
+                        # Deserialize the bytes into a FileDescriptorProto
+                        fd_proto = descriptor_pb2.FileDescriptorProto()
+                        fd_proto.ParseFromString(fd_bytes)
+                        # Collect each unique file descriptor; added to the pool
+                        # in dependency order below (reflection responses are
+                        # not guaranteed dependency-first).
+                        fd_name = fd_proto.name
+                        if fd_name not in seen_files:
+                            all_file_protos.append(fd_proto)
+                            seen_files.add(fd_name)
+
+        # Add collected files in a dependency-order-tolerant pass.
+        _add_file_protos_order_tolerant(pool, all_file_protos)
+        return pool
+
+    def _resolve_via_descriptors(self):
+        """Resolve descriptors from configured descriptor sources.
+
+        Returns:
+            DescriptorPool: Pool built from all descriptor sources.
+
+        Raises:
+            ConfigError: If no descriptors configured and reflection unavailable.
+        """
+        from google.protobuf import descriptor_pool, descriptor_pb2
+        import pathlib
+
+        if not self._descriptors:
+            raise ConfigError(
+                "no gRPC descriptors available and server reflection is unavailable; "
+                "configure grpc.descriptors",
+                {"target": self._target.address},
+            )
+
+        pool = descriptor_pool.DescriptorPool()
+
+        # Merge all descriptor sources into one pool
+        for descriptor_source in self._descriptors:
+            if descriptor_source.descriptor_set:
+                # Load from binary descriptor set
+                descriptor_path = pathlib.Path(descriptor_source.descriptor_set)
+                descriptor_bytes = descriptor_path.read_bytes()
+
+                # Parse the FileDescriptorSet
+                file_descriptor_set = descriptor_pb2.FileDescriptorSet()
+                file_descriptor_set.ParseFromString(descriptor_bytes)
+
+                # Add each file descriptor to the pool in a dependency-order-
+                # tolerant pass (protoc's FileDescriptorSet.file order is NOT
+                # guaranteed dependency-first, and the pool validates deps
+                # eagerly). See review finding I5.
+                _add_file_protos_order_tolerant(pool, file_descriptor_set.file)
+
+            elif descriptor_source.proto:
+                # Compile from proto file
+                from grpc_tools import protoc
+
+                proto_path = pathlib.Path(descriptor_source.proto)
+
+                # Compile to in-memory FileDescriptorSet
+                # Use protoc.main with a custom temp output
+                import tempfile
+                import os
+
+                with tempfile.TemporaryDirectory() as tmpdir:
+                    descriptor_set_path = os.path.join(tmpdir, "descriptor_set.pb")
+
+                    # Build proto search paths: the proto's own directory first,
+                    # then any configured include_paths.
+                    proto_paths = ["--proto_path", str(proto_path.parent)]
+                    for include_path in descriptor_source.include_paths:
+                        proto_paths.extend(["--proto_path", str(include_path)])
+
+                    # Call protoc to compile. protoc.main returns a nonzero int
+                    # on failure (it does NOT raise); surface as ConfigError
+                    # pointing at the proto. See review findings I4.
+                    rc = protoc.main(
+                        [
+                            "protoc",
+                            "--include_imports",
+                            *proto_paths,
+                            "--descriptor_set_out",
+                            descriptor_set_path,
+                            str(proto_path),
+                        ]
+                    )
+                    if rc != 0:
+                        raise ConfigError(
+                            f"protoc failed to compile {proto_path}: rc={rc}",
+                            {"proto": str(proto_path)},
+                        )
+
+                    # Load the generated descriptor set
+                    descriptor_bytes = pathlib.Path(descriptor_set_path).read_bytes()
+                    file_descriptor_set = descriptor_pb2.FileDescriptorSet()
+                    file_descriptor_set.ParseFromString(descriptor_bytes)
+
+                    _add_file_protos_order_tolerant(pool, file_descriptor_set.file)
+
+        return pool
+
+    def find_method(self, service: str, method: str):
+        """Find a method descriptor by service and method name.
+
+        Args:
+            service: Fully-qualified service name (e.g., "echo.Echo").
+            method: Method name within the service (e.g., "Unary").
+
+        Returns:
+            MethodDescriptor: The method descriptor.
+
+        Raises:
+            TemplateNotFound: If service or method not found.
+        """
+        from agctl.errors import TemplateNotFound
+
+        pool = self.resolve_descriptors()
+
+        # Find service by name
+        try:
+            service_desc = pool.FindServiceByName(service)
+        except KeyError:
+            raise TemplateNotFound(
+                f"Unknown gRPC service: {service}",
+                {"service": service},
+            )
+
+        # Find method by name
+        method_desc = service_desc.methods_by_name.get(method)
+        if method_desc is None:
+            raise TemplateNotFound(
+                f"Unknown gRPC method: {method} on {service}",
+                {"service": service, "method": method},
+            )
+
+        return method_desc
+
+    @staticmethod
+    def call_type_of(method_desc):
+        """Determine the call type from a method descriptor.
+
+        Args:
+            method_desc: A protobuf MethodDescriptor.
+
+        Returns:
+            str: One of "unary", "server_stream", "client_stream", "bidi".
+        """
+        is_client_streaming = method_desc.client_streaming
+        is_server_streaming = method_desc.server_streaming
+
+        if is_client_streaming and is_server_streaming:
+            return "bidi"
+        elif is_server_streaming:
+            return "server_stream"
+        elif is_client_streaming:
+            return "client_stream"
+        else:
+            return "unary"
+
+    def _msg_class(self, message_desc):
+        """Build a protobuf message class from a descriptor."""
+        from google.protobuf import message_factory
+
+        return message_factory.GetMessageClass(message_desc)
+
+    def _serialize(self, message_desc):
+        """Build a serializer callable: dict -> bytes."""
+
+        def serializer(d: dict | bytes) -> bytes:
+            # If already serialized (bytes), pass through
+            if isinstance(d, bytes):
+                return d
+
+            from google.protobuf import json_format
+
+            cls = self._msg_class(message_desc)
+            msg = cls()
+            # ParseDict raises on unknown fields - call methods convert to ConfigError
+            json_format.ParseDict(d, msg, ignore_unknown_fields=False)
+            return msg.SerializeToString()
+
+        return serializer
+
+    def _deserialize(self, message_desc):
+        """Build a deserializer callable: bytes -> dict."""
+
+        def deserializer(b: bytes) -> dict:
+            from google.protobuf import json_format
+
+            cls = self._msg_class(message_desc)
+            msg = cls.FromString(b)
+            return json_format.MessageToDict(msg)
+
+        return deserializer
+
+    def _metadata_to_items(self, metadata: dict | None) -> list | None:
+        """Convert metadata dict to list of (key, value) tuples or None."""
+        if metadata is None:
+            return None
+        return list(metadata.items())
+
+    def _metadata_to_dict(self, metadata_tuple) -> dict:
+        """Convert gRPC metadata tuple to dict with lowercased keys."""
+        if not metadata_tuple:
+            return {}
+        return {k.lower(): v for k, v in metadata_tuple}
+
+    def call_unary(
+        self,
+        service: str,
+        method: str,
+        message: dict,
+        *,
+        metadata: dict | None = None,
+        timeout: float | None = None,
+    ) -> GrpcUnaryResult:
+        """Make a unary gRPC call."""
+        from agctl.errors import ConnectionFailure, OperationTimeout
+        import grpc
+
+        md = self.find_method(service, method)
+
+        # Build serializers
+        ser = self._serialize(md.input_type)
+        deser = self._deserialize(md.output_type)
+
+        # Build invoker
+        fn = self._channel.unary_unary(
+            f"/{service}/{method}",
+            request_serializer=ser,
+            response_deserializer=deser,
+        )
+
+        try:
+            req_bytes = ser(message)
+        except Exception as e:
+            from agctl.errors import ConfigError
+
+            raise ConfigError(
+                f"Failed to serialize request message: {e}", {"service": service, "method": method}
+            ) from e
+
+        try:
+            resp, call = fn.with_call(
+                req_bytes,
+                metadata=self._metadata_to_items(metadata),
+                timeout=timeout or self._timeout,
+            )
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
+                raise OperationTimeout(message=str(e), detail={}) from e
+            else:
+                # Non-OK status is returned as result, not raised
+                code_enum = e.code()
+                status = GrpcStatus(
+                    code=code_enum.value[0],
+                    name=code_enum.name,
+                    message=e.details() or "",
+                )
+                return GrpcUnaryResult(
+                    target=self._target.address,
+                    service=service,
+                    method=method,
+                    call_type="unary",
+                    status=status,
+                    message=None,
+                    initial_metadata={},
+                    trailers={},
+                )
+        except Exception as e:
+            raise ConnectionFailure(message=str(e)) from e
+
+        # Success path
+        return GrpcUnaryResult(
+            target=self._target.address,
+            service=service,
+            method=method,
+            call_type="unary",
+            status=GrpcStatus(code=0, name="OK"),
+            message=resp,
+            initial_metadata=self._metadata_to_dict(call.initial_metadata()),
+            trailers=self._metadata_to_dict(call.trailing_metadata()),
+        )
+
+    def call_server_stream(
+        self,
+        service: str,
+        method: str,
+        message: dict,
+        *,
+        metadata: dict | None = None,
+        timeout: float | None = None,
+    ):
+        """Make a server-streaming gRPC call."""
+        from agctl.errors import OperationTimeout
+        import grpc
+
+        md = self.find_method(service, method)
+
+        # Build serializers
+        ser = self._serialize(md.input_type)
+        deser = self._deserialize(md.output_type)
+
+        # Build invoker
+        fn = self._channel.unary_stream(
+            f"/{service}/{method}",
+            request_serializer=ser,
+            response_deserializer=deser,
+        )
+
+        # Initialize/reset terminal status to OK
+        self.terminal_status = GrpcStatus(0, "OK", "")
+
+        try:
+            req_bytes = ser(message)
+        except Exception as e:
+            from agctl.errors import ConfigError
+
+            raise ConfigError(
+                f"Failed to serialize request message: {e}", {"service": service, "method": method}
+            ) from e
+
+        try:
+            response_iter = fn(
+                req_bytes,
+                metadata=self._metadata_to_items(metadata),
+                timeout=timeout or self._timeout,
+            )
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
+                raise OperationTimeout(message=str(e), detail={}) from e
+            else:
+                # Capture the terminal status from the RPC error
+                code_enum = e.code()
+                self.terminal_status = GrpcStatus(
+                    code=code_enum.value[0],
+                    name=code_enum.name,
+                    message=e.details() or "",
+                )
+                return
+        except Exception:
+            # Non-RpcError - stream ends
+            return
+
+        # Collect messages and yield them, attaching trailers to final message
+        messages = []
+        try:
+            for resp in response_iter:
+                messages.append(resp)
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
+                raise OperationTimeout(message=str(e), detail={}) from e
+            else:
+                # Capture the terminal status from the RPC error
+                code_enum = e.code()
+                self.terminal_status = GrpcStatus(
+                    code=code_enum.value[0],
+                    name=code_enum.name,
+                    message=e.details() or "",
+                )
+                # Stop iteration - terminal_status carries the error
+        except Exception:
+            # Non-RpcError - stream ends
+            pass
+
+        # Capture trailers after stream ends. On real grpcio the stream
+        # iterable is a _MultiThreadedRendezvous that inherits
+        # trailing_metadata() from Call directly; the old _call indirection
+        # targeted a cython IntegratedCall that does NOT expose it, so trailers
+        # were always None in production. Read off the iterable itself.
+        # See review finding I2.
+        trailers = None
+        try:
+            if hasattr(response_iter, "trailing_metadata"):
+                trailers = self._metadata_to_dict(response_iter.trailing_metadata())
+        except Exception:
+            # Ignore trailer metadata errors
+            pass
+
+        # Yield all messages with trailers=None except the final one
+        for i, msg in enumerate(messages):
+            if i == len(messages) - 1 and trailers:
+                # Final message gets trailers
+                yield GrpcStreamMessage(message=msg, trailers=trailers)
+            else:
+                yield GrpcStreamMessage(message=msg, trailers=None)
+
+    def call_client_stream(
+        self,
+        service: str,
+        method: str,
+        request_json_iter,
+        *,
+        metadata: dict | None = None,
+        timeout: float | None = None,
+    ) -> GrpcUnaryResult:
+        """Make a client-streaming gRPC call."""
+        from agctl.errors import ConnectionFailure, OperationTimeout
+        import grpc
+
+        md = self.find_method(service, method)
+
+        # Build serializers
+        ser = self._serialize(md.input_type)
+        deser = self._deserialize(md.output_type)
+
+        # Build invoker
+        fn = self._channel.stream_unary(
+            f"/{service}/{method}",
+            request_serializer=ser,
+            response_deserializer=deser,
+        )
+
+        try:
+            # Eagerly serialize all requests into a list so a malformed request
+            # raises ConfigError BEFORE the call. A generator expression would
+            # defer ser(req) past this try/except (serialization then happens
+            # inside grpcio, surfacing as a false-green INTERNAL result). The
+            # list is then wrapped in iter() because grpcio's request consumer
+            # calls next() on it (a raw list is not an iterator). See C1.
+            req_iter = iter([ser(req) for req in request_json_iter])
+        except Exception as e:
+            from agctl.errors import ConfigError
+
+            raise ConfigError(
+                f"Failed to serialize request message: {e}", {"service": service, "method": method}
+            ) from e
+
+        try:
+            resp = fn(
+                req_iter,
+                metadata=self._metadata_to_items(metadata),
+                timeout=timeout or self._timeout,
+            )
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
+                raise OperationTimeout(message=str(e), detail={}) from e
+            else:
+                # Non-OK status is returned as result, not raised
+                code_enum = e.code()
+                status = GrpcStatus(
+                    code=code_enum.value[0],
+                    name=code_enum.name,
+                    message=e.details() or "",
+                )
+                return GrpcUnaryResult(
+                    target=self._target.address,
+                    service=service,
+                    method=method,
+                    call_type="client_stream",
+                    status=status,
+                    message=None,
+                    initial_metadata={},
+                    trailers={},
+                )
+        except Exception as e:
+            raise ConnectionFailure(message=str(e)) from e
+
+        # Success path - stream_unary doesn't expose metadata
+        return GrpcUnaryResult(
+            target=self._target.address,
+            service=service,
+            method=method,
+            call_type="client_stream",
+            status=GrpcStatus(code=0, name="OK"),
+            message=resp,
+            initial_metadata={},
+            trailers={},
+        )
+
+    def call_bidi(
+        self,
+        service: str,
+        method: str,
+        request_json_iter,
+        *,
+        metadata: dict | None = None,
+        timeout: float | None = None,
+    ):
+        """Make a bidirectional-streaming gRPC call."""
+        from agctl.errors import OperationTimeout
+        import grpc
+
+        md = self.find_method(service, method)
+
+        # Build serializers
+        ser = self._serialize(md.input_type)
+        deser = self._deserialize(md.output_type)
+
+        # Build invoker
+        fn = self._channel.stream_stream(
+            f"/{service}/{method}",
+            request_serializer=ser,
+            response_deserializer=deser,
+        )
+
+        # Initialize/reset terminal status to OK
+        self.terminal_status = GrpcStatus(0, "OK", "")
+
+        try:
+            # Eagerly serialize all requests into a list so a malformed request
+            # raises ConfigError BEFORE the call. A generator expression would
+            # defer ser(req) past this try/except (serialization then happens
+            # inside grpcio, surfacing as a false-green INTERNAL result). The
+            # list is then wrapped in iter() because grpcio's request consumer
+            # calls next() on it (a raw list is not an iterator). See C1.
+            req_iter = iter([ser(req) for req in request_json_iter])
+        except Exception as e:
+            from agctl.errors import ConfigError
+
+            raise ConfigError(
+                f"Failed to serialize request message: {e}", {"service": service, "method": method}
+            ) from e
+
+        try:
+            response_iter = fn(
+                req_iter,
+                metadata=self._metadata_to_items(metadata),
+                timeout=timeout or self._timeout,
+            )
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
+                raise OperationTimeout(message=str(e), detail={}) from e
+            else:
+                # Capture the terminal status from the RPC error
+                code_enum = e.code()
+                self.terminal_status = GrpcStatus(
+                    code=code_enum.value[0],
+                    name=code_enum.name,
+                    message=e.details() or "",
+                )
+                return
+        except Exception:
+            # Non-RpcError - stream ends
+            return
+
+        # Collect messages and yield them, attaching trailers to final message
+        messages = []
+        try:
+            for resp in response_iter:
+                messages.append(resp)
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
+                raise OperationTimeout(message=str(e), detail={}) from e
+            else:
+                # Capture the terminal status from the RPC error
+                code_enum = e.code()
+                self.terminal_status = GrpcStatus(
+                    code=code_enum.value[0],
+                    name=code_enum.name,
+                    message=e.details() or "",
+                )
+                # Stop iteration - terminal_status carries the error
+        except Exception:
+            # Non-RpcError - stream ends
+            pass
+
+        # Capture trailers after stream ends. On real grpcio the stream
+        # iterable is a _MultiThreadedRendezvous that inherits
+        # trailing_metadata() from Call directly; the old _call indirection
+        # targeted a cython IntegratedCall that does NOT expose it, so trailers
+        # were always None in production. Read off the iterable itself.
+        # See review finding I2.
+        trailers = None
+        try:
+            if hasattr(response_iter, "trailing_metadata"):
+                trailers = self._metadata_to_dict(response_iter.trailing_metadata())
+        except Exception:
+            # Ignore trailer metadata errors
+            pass
+
+        # Yield all messages with trailers=None except the final one
+        for i, msg in enumerate(messages):
+            if i == len(messages) - 1 and trailers:
+                # Final message gets trailers
+                yield GrpcStreamMessage(message=msg, trailers=trailers)
+            else:
+                yield GrpcStreamMessage(message=msg, trailers=None)
+
+    def healthcheck(self, service_name: str = "") -> GrpcHealthResult:
+        """Perform a gRPC health check.
+
+        Args:
+            service_name: Optional service name to check. Empty string checks overall
+                server health.
+
+        Returns:
+            GrpcHealthResult: Health check result with status and optional note.
+
+        Raises:
+            OperationTimeout: If the health check request times out.
+            ConnectionFailure: If the connection fails or other RPC error occurs.
+        """
+        from agctl.errors import ConnectionFailure, OperationTimeout
+
+        # Lazy import grpc_health.v1
+        from grpc_health.v1 import health_pb2
+        from grpc_health.v1.health_pb2_grpc import HealthStub
+        import grpc
+
+        # Build HealthStub
+        health_stub = HealthStub(self._channel)
+
+        # Call health check
+        try:
+            response = health_stub.Check(
+                health_pb2.HealthCheckRequest(service=service_name),
+                timeout=self._timeout,
+            )
+            # Success: map status enum name to string
+            status_name = health_pb2.HealthCheckResponse.ServingStatus.Name(response.status)
+            return GrpcHealthResult(
+                target=self._target.address,
+                address=self._target.address,
+                status=status_name,
+                note=None,
+            )
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.UNIMPLEMENTED:
+                # Health service not implemented - return UNKNOWN (not an error)
+                return GrpcHealthResult(
+                    target=self._target.address,
+                    address=self._target.address,
+                    status="UNKNOWN",
+                    note="health service UNIMPLEMENTED",
+                )
+            elif e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
+                raise OperationTimeout(message=str(e)) from e
+            else:
+                # Other RPC errors are connection failures
+                raise ConnectionFailure(message=str(e)) from e
+        except Exception as exc:
+            # Non-RPC errors are connection failures
+            raise ConnectionFailure(message=str(exc)) from exc
diff --git a/agctl/commands/discover_commands.py b/agctl/commands/discover_commands.py
index cdcaf64..7298c00 100644
--- a/agctl/commands/discover_commands.py
+++ b/agctl/commands/discover_commands.py
@@ -46,12 +46,14 @@
     "mock-http-stubs",
     "mock-kafka-reactors",
     "log-sources",
+    "grpc-services",
+    "grpc-methods",
 )
 
 _SUMMARY_HINT = (
     "Run 'agctl discover --category <name>' to list items. "
     "Categories: services, http-templates, kafka-patterns, db-templates, "
-    "mock-http-stubs, mock-kafka-reactors, log-sources"
+    "mock-http-stubs, mock-kafka-reactors, log-sources, grpc-services, grpc-methods"
 )
 _CATEGORY_HINT = "Run 'agctl discover --category <c> --name <name>' for full detail"
 _SEARCH_HINT = (
@@ -202,6 +204,8 @@ def _summary_core(config_path: str | None, overlay_paths: list[str] | None = Non
         "mock_http_stubs": len(_mock_http_stubs(cfg)),
         "mock_kafka_reactors": len(_mock_kafka_reactors(cfg)),
         "log_sources": len(cfg.logs.sources),
+        "grpc_targets": len(cfg.grpc.targets),
+        "grpc_methods": len(cfg.grpc.templates),
         "hint": _SUMMARY_HINT,
     }
 
@@ -255,6 +259,22 @@ def _category_core(config_path: str | None, category: str, overlay_paths: list[s
                     "description": f"{src.type} logs for {name} ({src.path or '?'})",
                 }
             )
+    elif category == "grpc-services":
+        for name, tgt in cfg.grpc.targets.items():
+            items.append(
+                {
+                    "name": name,
+                    "description": f"gRPC target {name} at {tgt.address} (tls={tgt.use_tls})",
+                }
+            )
+    elif category == "grpc-methods":
+        for name, tpl in cfg.grpc.templates.items():
+            items.append(
+                {
+                    "name": name,
+                    "description": tpl.description or f"{tpl.service}/{tpl.method}",
+                }
+            )
 
     return {
         "category": category,
@@ -426,6 +446,65 @@ def _item_core(config_path: str | None, category: str, name: str, overlay_paths:
             "example": f"agctl logs query --source {name} --level ERROR --since 5m",
         }
 
+    if category == "grpc-services":
+        if name not in cfg.grpc.targets:
+            raise TemplateNotFound(
+                f"Unknown gRPC target: {name}",
+                {"path": f"grpc.targets.{name}"},
+            )
+        tgt = cfg.grpc.targets[name]
+        return {
+            "category": "grpc-services",
+            "name": name,
+            "description": f"gRPC target {name} at {tgt.address} (tls={tgt.use_tls})",
+            "address": tgt.address,
+            "use_tls": tgt.use_tls,
+            "reflection": tgt.reflection,
+            "example": f"agctl grpc call --target {name} --service <fq> --method <m>",
+        }
+
+    if category == "grpc-methods":
+        if name not in cfg.grpc.templates:
+            raise TemplateNotFound(
+                f"Unknown gRPC method template: {name}",
+                {"path": f"grpc.templates.{name}"},
+            )
+        tpl = cfg.grpc.templates[name]
+        # Local import to avoid module-load cycle (grpc_commands imports this file)
+        from ..commands.grpc_commands import new_grpc_client
+        from google.protobuf.descriptor import FieldDescriptor
+
+        try:
+            client = new_grpc_client(cfg.grpc.targets[tpl.target], descriptors=cfg.grpc.descriptors)
+            md = client.find_method(tpl.service, tpl.method)
+            # Map field type int to type name
+            type_map = {v: k for k, v in vars(FieldDescriptor).items() if k.startswith('TYPE_') and isinstance(v, int)}
+            request_fields = [
+                {"name": f.name, "type": type_map.get(f.type, f"UNKNOWN_{f.type}"), "repeated": f.is_repeated}
+                for f in md.input_type.fields
+            ]
+            call_type = client.call_type_of(md)
+            return {
+                "category": "grpc-methods",
+                "name": name,
+                "description": tpl.description,
+                "target": tpl.target,
+                "service": tpl.service,
+                "method": tpl.method,
+                "call_type": call_type,
+                "request_fields": request_fields,
+                "example": f"agctl grpc call {name}",
+            }
+        except ConfigError as err:
+            # Target unreachable or reflection unavailable - return unavailable marker
+            # instead of failing the whole discover call
+            return {
+                "category": "grpc-methods",
+                "name": name,
+                "unavailable": True,
+                "error": str(err),
+            }
+
     # category == "db-templates"
     if name not in cfg.database.templates:
         raise TemplateNotFound(
@@ -534,6 +613,26 @@ def _matches(haystack: str | None) -> bool:
                 }
             )
 
+    for name, tgt in cfg.grpc.targets.items():
+        if needle in name.lower() or needle in tgt.address.lower():
+            matches.append(
+                {
+                    "category": "grpc-services",
+                    "name": name,
+                    "description": f"gRPC target {name} at {tgt.address} (tls={tgt.use_tls})",
+                }
+            )
+
+    for name, tpl in cfg.grpc.templates.items():
+        if needle in name.lower() or _matches(tpl.description):
+            matches.append(
+                {
+                    "category": "grpc-methods",
+                    "name": name,
+                    "description": tpl.description or f"{tpl.service}/{tpl.method}",
+                }
+            )
+
     return {
         "query": term,
         "matches": matches,
diff --git a/agctl/commands/grpc_commands.py b/agctl/commands/grpc_commands.py
new file mode 100644
index 0000000..5bc9aee
--- /dev/null
+++ b/agctl/commands/grpc_commands.py
@@ -0,0 +1,822 @@
+"""`grpc call` command (DESIGN §3.3, D6).
+
+- ``grpc call <template>`` resolves a named gRPC template from config, fills
+  ``{name}`` placeholders, and dispatches a unary or client-streaming call.
+- ``grpc call --target <name>`` / ``--address host:port`` is the free-form variant.
+
+Both unary and client-streaming return a single result (the ``grpc.call`` envelope).
+Server-streaming and bidirectional streaming emit NDJSON (D9 streaming exception).
+
+A non-OK gRPC status is a *successful* call and yields ``ok: true`` — status is a
+result field, not an assertion failure (D6). Assertions (``--status``, ``--match``,
+etc.) are evaluated separately and raise ``AssertionFailure`` on mismatch.
+"""
+
+from __future__ import annotations
+
+import json
+import signal
+import sys
+import threading
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable
+
+import click
+
+from ..assertions import compile_jq, evaluate_grpc_assertions, jq_bool, validate_grpc_assertion_args
+from ..clients.grpc_client import GrpcStatus
+from ..command import envelope, load_config_or_raise
+from ..errors import AgctlError, AssertionFailure, ConfigError, TemplateNotFound
+from ..output import emit
+from ..params import parse_params
+from ..resolution import deep_merge, fill_placeholders
+
+if TYPE_CHECKING:
+    from ..config.models import GrpcConfig, GrpcTarget, GrpcTemplate
+
+__all__ = [
+    "grpc_call",
+    "grpc_healthcheck",
+    "new_grpc_client",
+]
+
+
+def new_grpc_client(target, *, descriptors=None):
+    """Build a real :class:`GrpcClient` from a :class:`GrpcTarget`.
+
+    Test seam: tests monkeypatch this attribute
+    (``monkeypatch.setattr(grpc_commands, "new_grpc_client", factory)``) to
+    return a fake GrpcClient, avoiding any real gRPC connection.
+    """
+    from ..clients.grpc_client import GrpcClient
+
+    return GrpcClient(target, descriptors=descriptors)
+
+
+def _resolve_target(cfg, name: str | None, address: str | None) -> tuple["GrpcTarget", str]:
+    """Resolve a gRPC target from either a named target or an address.
+
+    Args:
+        cfg: Loaded config object.
+        name: Target name from ``--target``.
+        address: Raw address string from ``--address`` (``host:port`` format).
+
+    Returns:
+        Tuple of ``(GrpcTarget, resolved_name)`` where ``resolved_name`` is the
+        address string if ``--address`` was used, otherwise the target name.
+
+    Raises:
+        ConfigError: If both ``--address`` and ``--target`` are given, if
+            address format is invalid, if the target is unknown, or if neither
+            is provided.
+    """
+    if address is not None:
+        if name is not None:
+            raise ConfigError("--address is mutually exclusive with --target", {})
+        # Validate host:port format (single colon, non-empty host and port)
+        if address.count(":") != 1:
+            raise ConfigError(f"--address must be host:port: {address!r}", {"address": address})
+        host, port = address.split(":", 1)
+        if not host or not port:
+            raise ConfigError(f"--address must be host:port: {address!r}", {"address": address})
+        from ..config.models import GrpcTarget
+
+        return GrpcTarget(address=address), address
+    elif name is not None:
+        grpc_cfg: "GrpcConfig" = cfg.grpc
+        if name not in grpc_cfg.targets:
+            raise ConfigError(f"Unknown gRPC target: {name}", {"target": name})
+        return grpc_cfg.targets[name], name
+    else:
+        raise ConfigError("grpc call requires --target <name> or --address host:port", {})
+
+
+def _parse_metadata(metadata: tuple[str, ...]) -> dict[str, str]:
+    """Turn ``--metadata k=v`` tuples into a dict (same rule as ``--param``)."""
+    return parse_params(metadata)
+
+
+def _stdin_request_iter(params: dict[str, str]) -> Callable[[], dict]:
+    """NDJSON iterator over stdin, filling placeholders per line.
+
+    Yields:
+        Parsed JSON dicts with placeholders filled from ``params``.
+
+    Raises:
+        ConfigError: If a line is not valid JSON.
+    """
+
+    def _iter():
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue  # Skip empty lines
+            try:
+                msg_dict = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise ConfigError(
+                    f"Invalid NDJSON on stdin: {exc.msg}",
+                    {"line": line, "lineno": getattr(exc, "lineno", None)},
+                ) from exc
+            yield fill_placeholders(msg_dict, params)
+
+    return _iter()
+
+
+def _emit_stdout_line(line: dict) -> None:
+    """Write one NDJSON line directly to stdout (NOT via emit)."""
+    sys.stdout.write(json.dumps(line, ensure_ascii=False))
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+
+
+@dataclass
+class _ResolvedGrpcCall:
+    """Fully resolved gRPC call context (produced exactly once per invocation).
+
+    ``grpc_call`` resolves the target/template/client/method/call-type a single
+    time and hands this context to BOTH the unary/client-stream path
+    (``_grpc_call_core``) and the streaming path — neither re-resolves (no second
+    ``load_config``/``new_grpc_client``/``find_method``), which matters for
+    ``reflection: auto`` targets where each ``find_method`` is a reflection
+    round-trip and each client build constructs a channel.
+    """
+
+    call_type: str
+    client: Any  # GrpcClient (or a test double)
+    service: str | None
+    method: str | None
+    message: str | None  # resolved JSON request string (None for stdin-input call types)
+    metadata: tuple[str, ...]
+    params: dict[str, str]
+
+
+def _resolve_grpc_call(
+    cfg,
+    *,
+    target_name: str | None,
+    address: str | None,
+    service: str | None,
+    method: str | None,
+    template_name: str | None = None,
+    caller_message: str | None = None,
+    caller_metadata: tuple[str, ...] = (),
+    param: tuple[str, ...] = (),
+) -> _ResolvedGrpcCall:
+    """Resolve a gRPC call EXACTLY ONCE: template/free-form, target, client,
+    method descriptor, and call type.
+
+    Returns a :class:`_ResolvedGrpcCall` carrying the client + resolved
+    service/method/message/metadata/params. Raises :class:`ConfigError` /
+    :class:`TemplateNotFound` for config errors.
+    """
+    resolved_target: str | None = target_name
+    resolved_address: str | None = address
+    resolved_service: str | None = service
+    resolved_method: str | None = method
+    resolved_message: str | None = caller_message
+    resolved_metadata: tuple[str, ...] = caller_metadata
+
+    # Mode resolution: template vs free-form
+    if template_name is not None:
+        # Template mode: --target/--address/--service/--method are mutually exclusive
+        if target_name is not None or address is not None or service is not None or method is not None:
+            raise ConfigError(
+                "grpc call <template> is mutually exclusive with --target/--address/--service/--method",
+                {},
+            )
+
+        if template_name not in cfg.grpc.templates:
+            raise TemplateNotFound(
+                f"Unknown gRPC template: {template_name}",
+                {"name": template_name},
+            )
+        tpl: "GrpcTemplate" = cfg.grpc.templates[template_name]
+
+        # Resolve template target
+        tpl_target_name = tpl.target
+        if tpl_target_name not in cfg.grpc.targets:
+            raise ConfigError(
+                f"Template '{template_name}' references unknown target '{tpl_target_name}'",
+                {"target": tpl_target_name},
+            )
+
+        # Use template's service/method
+        resolved_service = tpl.service
+        resolved_method = tpl.method
+
+        # Fill placeholders in template message
+        params = parse_params(param)
+        tpl_message = tpl.message or {}
+        filled_message = fill_placeholders(tpl_message, params)
+
+        # Merge caller --message if provided (caller wins, deep merge)
+        if caller_message is not None:
+            try:
+                caller_msg_dict = json.loads(caller_message)
+            except json.JSONDecodeError as exc:
+                raise ConfigError(
+                    f"Invalid JSON in --message: {exc.msg}",
+                    {"message": caller_message},
+                ) from exc
+            resolved_message_dict = deep_merge(filled_message, caller_msg_dict)
+        else:
+            resolved_message_dict = filled_message
+
+        # Fill metadata placeholders
+        tpl_metadata = tpl.metadata or {}
+        filled_metadata = fill_placeholders(dict(tpl_metadata), params)
+
+        # Overlay caller --metadata (caller wins)
+        caller_metadata_dict = _parse_metadata(caller_metadata)
+        resolved_metadata_dict = {**filled_metadata, **caller_metadata_dict}
+
+        # Serialize message back to JSON string
+        resolved_message = json.dumps(resolved_message_dict) if resolved_message_dict else None
+
+        # Convert metadata back to tuples
+        resolved_metadata = tuple(f"{k}={v}" for k, v in resolved_metadata_dict.items())
+
+        # Set target name for resolution
+        resolved_target = tpl_target_name
+        resolved_address = None
+    else:
+        # Free-form mode: service/method are required
+        if service is None or method is None:
+            raise ConfigError(
+                "grpc call requires --service and --method (or a template name)",
+                {},
+            )
+        params = parse_params(param)
+
+    # Resolve target, build the client ONCE, find method + call type ONCE
+    final_target, _ = _resolve_target(cfg, resolved_target, resolved_address)
+    client = new_grpc_client(final_target, descriptors=cfg.grpc.descriptors)
+    md = client.find_method(resolved_service, resolved_method)
+    call_type = client.call_type_of(md)
+
+    return _ResolvedGrpcCall(
+        call_type=call_type,
+        client=client,
+        service=resolved_service,
+        method=resolved_method,
+        message=resolved_message,
+        metadata=resolved_metadata,
+        params=params,
+    )
+
+
+def _grpc_stream_run(
+    client,
+    *,
+    service: str,
+    method: str,
+    call_type: str,
+    request_input: dict | Callable[[], dict],
+    metadata: dict | None,
+    timeout: float | None,
+    match: str | None,
+    params: dict[str, str],
+    stop_event: threading.Event,
+    emit_line: Callable[[dict], None],
+    stats: dict[str, int],
+) -> dict:
+    """Drive a streaming gRPC call (server-streaming or bidi).
+
+    Args:
+        client: GrpcClient instance.
+        service: Service name.
+        method: Method name.
+        call_type: "server_stream" or "bidi".
+        request_input: For server_stream, a single dict message; for bidi, an
+            iterator (from ``_stdin_request_iter``) of request dicts.
+        metadata: Metadata dict.
+        timeout: Timeout in seconds.
+        match: Compiled jq expression for filtering messages (optional).
+        params: Placeholder values for filling match expression.
+        stop_event: Threading event to stop streaming.
+        emit_line: Function to emit NDJSON lines.
+        stats: Mutable ``{"messages": int, "matched": int}`` updated as messages
+            stream, so a mid-run error can report the PARTIAL counts emitted so
+            far rather than dropping them to 0.
+
+    Returns:
+        Summary dict with keys: summary (True), messages (int), matched (int), status (dict), duration_ms (int).
+    """
+    start = time.monotonic()
+
+    # Build the match filter if provided
+    match_filter = None
+    if match is not None:
+        filled_match = fill_placeholders(match, params)
+
+        def match_filter(msg_dict: dict) -> bool:
+            return jq_bool(msg_dict, filled_match)
+
+    # Drive the appropriate call type.
+    # request_input is always a dict (server_stream) or a generator (bidi,
+    # from _stdin_request_iter) — never a callable, so no call() branch.
+    if call_type == "server_stream":
+        stream_iter = client.call_server_stream(service, method, request_input, metadata=metadata, timeout=timeout)
+    elif call_type == "bidi":
+        stream_iter = client.call_bidi(service, method, request_input, metadata=metadata, timeout=timeout)
+    else:
+        raise ConfigError(f"Unknown call type for streaming: {call_type}", {"call_type": call_type})
+
+    # Stream messages
+    for stream_msg in stream_iter:
+        if stop_event.is_set():
+            break
+
+        stats["messages"] += 1
+        msg_dict = stream_msg.message
+
+        # Apply match filter if provided
+        if match_filter is not None:
+            try:
+                if match_filter(msg_dict):
+                    stats["matched"] += 1
+                    emit_line({"event": "message", "message": msg_dict, "trailers": stream_msg.trailers})
+            except Exception:
+                # If match evaluation fails, count as not matched
+                pass
+        else:
+            # No filter: all messages match
+            stats["matched"] += 1
+            emit_line({"event": "message", "message": msg_dict, "trailers": stream_msg.trailers})
+
+    duration_ms = int((time.monotonic() - start) * 1000)
+
+    # Read the terminal status from the client
+    terminal = getattr(client, "terminal_status", None) or GrpcStatus(0, "OK", "")
+
+    # Return summary with the terminal status
+    return {
+        "summary": True,
+        "messages": stats["messages"],
+        "matched": stats["matched"],
+        "status": {"code": terminal.code, "name": terminal.name, "message": terminal.message},
+        "duration_ms": duration_ms,
+    }
+
+
+def _grpc_healthcheck_core(
+    config_path: str | None,
+    target: str | None,
+    service: str | None,
+    all_: bool,
+    overlay_paths: list[str] | None = None,
+) -> dict:
+    """Core gRPC healthcheck logic.
+
+    Args:
+        config_path: Path to config file.
+        target: Named gRPC target from config.
+        service: Optional service name to check.
+        all_: If True, check all targets.
+        overlay_paths: Optional config overlay paths.
+
+    Returns:
+        Dict with keys: targets (dict of target results), all_serving (bool).
+
+    Raises:
+        ConfigError: If target is unknown.
+    """
+    cfg = load_config_or_raise(config_path, overlay_paths=overlay_paths)
+
+    # Select targets: if all_ OR neither target given → all targets; else [target]
+    if all_ or target is None:
+        selected_targets = list(cfg.grpc.targets.keys())
+    else:
+        selected_targets = [target]
+
+    # Validate targets exist
+    for target_name in selected_targets:
+        if target_name not in cfg.grpc.targets:
+            raise ConfigError(f"Unknown gRPC target: {target_name}", {"target": target_name})
+
+    # Check health for each target
+    targets_result = {}
+    for target_name in selected_targets:
+        target_obj = cfg.grpc.targets[target_name]
+        client = new_grpc_client(target_obj, descriptors=cfg.grpc.descriptors)
+        res = client.healthcheck(service or "")
+
+        # Build result dict for this target
+        target_dict = {
+            "address": res.address,
+            "status": res.status,
+        }
+        if res.note is not None:
+            target_dict["note"] = res.note
+        targets_result[target_name] = target_dict
+
+    # Compute all_serving: True only if all statuses are SERVING
+    all_serving = all(result["status"] == "SERVING" for result in targets_result.values())
+
+    return {
+        "targets": targets_result,
+        "all_serving": all_serving,
+    }
+
+
+_grpc_healthcheck_envelope = envelope("grpc.healthcheck")(_grpc_healthcheck_core)
+
+
+@click.command("healthcheck")
+@click.option("--target", "target", default=None, help="Named gRPC target from config")
+@click.option("--service", "service", default=None, help="Service name to check (empty string checks overall health)")
+@click.option("--all", "all_", is_flag=True, help="Check all configured gRPC targets")
+@click.pass_context
+def grpc_healthcheck(
+    ctx: click.Context,
+    target: str | None,
+    service: str | None,
+    all_: bool,
+) -> None:
+    """Check health of gRPC services.
+
+    Without --target or --all, checks all configured targets.
+    With --target, checks only the specified target.
+    With --all, checks all configured targets explicitly.
+
+    Examples:
+        agctl grpc healthcheck                    # Check all targets
+        agctl grpc healthcheck --all              # Check all targets (explicit)
+        agctl grpc healthcheck --target echo       # Check specific target
+        agctl grpc healthcheck --target echo --service echo.Echo  # Check specific service
+    """
+    config_path = ctx.obj.get("config_path") if ctx.obj else None
+    ovs = ctx.obj.get("overlay_paths") if ctx.obj else None
+
+    _grpc_healthcheck_envelope(
+        config_path,
+        target,
+        service,
+        all_,
+        overlay_paths=list(ovs) if ovs else None,
+    )
+
+
+def _grpc_call_core(
+    resolved: _ResolvedGrpcCall,
+    *,
+    timeout: float | None,
+    status: str | None,
+    contains: str | None,
+    match: str | None,
+    jq_path: str | None,
+    equals: str | None,
+) -> dict:
+    """Core gRPC call logic for unary + client-streaming (single-result) paths.
+
+    Receives an ALREADY-RESOLVED context (``resolved``) produced once by
+    :func:`_resolve_grpc_call` — this function does NOT reload config, rebuild
+    the client, or re-run ``find_method``/``call_type_of``. The Click command
+    routes server-streaming/bidi to the streaming branch before this is called,
+    so only unary/client_stream reach here.
+
+    Raises:
+        ConfigError: For invalid JSON in ``--message`` or a streaming-input call
+            type given ``--message``.
+        AssertionFailure: When assertions fail (via ``evaluate_grpc_assertions``).
+    """
+    call_type = resolved.call_type
+    client = resolved.client
+
+    # Build message_json based on call type
+    if call_type == "unary":
+        if resolved.message is not None:
+            try:
+                message_json = json.loads(resolved.message)
+            except json.JSONDecodeError as exc:
+                raise ConfigError(
+                    f"Invalid JSON in --message: {exc.msg}",
+                    {"message": resolved.message},
+                ) from exc
+            message_json = fill_placeholders(message_json, resolved.params)
+        else:
+            message_json = {}
+    elif call_type == "client_stream":
+        # Client-streaming reads from stdin; --message is invalid
+        if resolved.message is not None:
+            raise ConfigError(
+                "--message is invalid for streaming-input call types; pipe request messages on stdin",
+                {"call_type": call_type},
+            )
+        message_json = None
+    else:
+        # Defensive: the Click command routes server_stream/bidi to the streaming
+        # branch, so this is unreachable in normal flow.
+        raise ConfigError(f"Unsupported call type for single-result path: {call_type}", {"call_type": call_type})
+
+    # Pre-call assertion validation (fail fast before the call)
+    validate_grpc_assertion_args(status=status, contains=contains, match=match, jq_path=jq_path, equals=equals)
+
+    metadata_dict = _parse_metadata(resolved.metadata) if resolved.metadata else None
+
+    # Dispatch on call type
+    if call_type == "unary":
+        result = client.call_unary(resolved.service, resolved.method, message_json, metadata=metadata_dict, timeout=timeout)
+    else:  # client_stream
+        result = client.call_client_stream(
+            resolved.service, resolved.method, _stdin_request_iter(resolved.params), metadata=metadata_dict, timeout=timeout
+        )
+
+    # Build the grpc.call result dict
+    result_dict = {
+        "target": result.target,
+        "service": result.service,
+        "method": result.method,
+        "call_type": result.call_type,
+        "status": {
+            "code": result.status.code,
+            "name": result.status.name,
+            "message": result.status.message,
+        },
+        "message": result.message,
+        "initial_metadata": result.initial_metadata,
+        "trailers": result.trailers,
+    }
+
+    # Post-call assertions (only when any assertion kwarg is set)
+    if any(arg is not None for arg in (status, contains, match, jq_path, equals)):
+        evaluate_grpc_assertions(result_dict, status=status, contains=contains, match=match, jq_path=jq_path, equals=equals)
+
+    return result_dict
+
+
+_grpc_call_envelope = envelope("grpc.call")(_grpc_call_core)
+
+
+@click.command("call")
+@click.argument("template_name", required=False)
+@click.option("--target", "target", default=None, help="Named gRPC target from config")
+@click.option("--address", "address", default=None, help="Raw gRPC address (host:port)")
+@click.option("--service", "service", default=None, help="Fully-qualified service name (e.g. echo.Echo)")
+@click.option("--method", "method", default=None, help="Method name within the service")
+@click.option("--message", "message", default=None, help="JSON request message body")
+@click.option("--metadata", "metadata", multiple=True, help="k=v metadata header")
+@click.option("--param", "param", multiple=True, help="k=v placeholder")
+@click.option("--timeout", "timeout", type=float, default=None, help="Request timeout (seconds)")
+@click.option("--status", "status", type=str, default=None, help="Expected gRPC status code (name or number)")
+@click.option("--contains", "contains", default=None, help="JSON needle that must be present in the response (subset match)")
+@click.option("--match", "match", default=None, help="jq predicate against the result envelope")
+@click.option("--jq-path", "jq_path", default=None, help="jq path expression (used with --equals)")
+@click.option("--equals", "equals", default=None, help="Expected value for --jq-path")
+@click.option("--expect-count", "expect_count", type=int, default=None, help="Expected number of matching messages (for streaming calls)")
+@click.pass_context
+def grpc_call(
+    ctx: click.Context,
+    template_name: str | None,
+    target: str | None,
+    address: str | None,
+    service: str | None,
+    method: str | None,
+    message: str | None,
+    metadata: tuple[str, ...],
+    param: tuple[str, ...],
+    timeout: float | None,
+    status: str | None,
+    contains: str | None,
+    match: str | None,
+    jq_path: str | None,
+    equals: str | None,
+    expect_count: int | None,
+) -> None:
+    """Make a gRPC call (unary, client-streaming, server-streaming, or bidirectional).
+
+    Either invoke a template:
+
+        agctl grpc call <template> --param name=value
+
+    Or provide free-form arguments:
+
+        agctl grpc call --target <name> --service <Service> --method <Method> --message '{"msg":"hello"}'
+        agctl grpc call --address host:port --service <Service> --method <Method> --message '{"msg":"hello"}'
+
+    Client-streaming and bidirectional calls read NDJSON from stdin (one JSON object per line).
+    Server-streaming and bidirectional calls emit NDJSON to stdout (one message per line).
+    """
+    config_path = ctx.obj.get("config_path") if ctx.obj else None
+    ovs = ctx.obj.get("overlay_paths") if ctx.obj else None
+    start = time.monotonic()
+
+    # Step 1: Resolve EXACTLY ONCE — config load, target/template resolution,
+    # client build, find_method, and call-type detection all happen here. The
+    # resulting context is handed to both the single-result path
+    # (``_grpc_call_core``) and the streaming path; neither re-resolves.
+    try:
+        cfg = load_config_or_raise(config_path, overlay_paths=list(ovs) if ovs else None)
+        resolved = _resolve_grpc_call(
+            cfg,
+            target_name=target,
+            address=address,
+            service=service,
+            method=method,
+            template_name=template_name,
+            caller_message=message,
+            caller_metadata=metadata,
+            param=param,
+        )
+    except AgctlError as err:
+        # Startup config errors -> structured envelope + exit code
+        emit(
+            ok=False,
+            command="grpc.call",
+            error=err.to_dict(),
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+        raise SystemExit(err.exit_code)
+    except Exception as exc:
+        # Non-agctl startup errors -> InternalError envelope + exit 2
+        emit(
+            ok=False,
+            command="grpc.call",
+            error={"type": "InternalError", "message": str(exc), "detail": {}},
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+        raise SystemExit(2)
+
+    call_type = resolved.call_type
+
+    # Step 2: Route based on call type
+    if call_type in ("unary", "client_stream"):
+        # Unary and client-streaming use the envelope path (single JSON result)
+        _grpc_call_envelope(
+            resolved,
+            timeout=timeout,
+            status=status,
+            contains=contains,
+            match=match,
+            jq_path=jq_path,
+            equals=equals,
+        )
+    elif call_type in ("server_stream", "bidi"):
+        # Server-streaming and bidi use the streaming path (NDJSON output),
+        # reusing the already-built client (no second new_grpc_client).
+        # Input validation
+        if call_type == "server_stream":
+            # Server-streaming requires a single request message
+            if resolved.message is None:
+                emit(
+                    ok=False,
+                    command="grpc.call",
+                    error={"type": "ConfigError", "message": "Server-streaming requires --message", "detail": {}},
+                    duration_ms=int((time.monotonic() - start) * 1000),
+                )
+                raise SystemExit(2)
+        else:  # bidi
+            # Bidi reads from stdin; --message is invalid
+            if resolved.message is not None:
+                emit(
+                    ok=False,
+                    command="grpc.call",
+                    error={"type": "ConfigError", "message": "--message is invalid for bidi; pipe request messages on stdin", "detail": {}},
+                    duration_ms=int((time.monotonic() - start) * 1000),
+                )
+                raise SystemExit(2)
+
+        # Reject unary assertion flags on streaming calls
+        if any(arg is not None for arg in (status, contains, jq_path, equals)):
+            emit(
+                ok=False,
+                command="grpc.call",
+                error={
+                    "type": "ConfigError",
+                    "message": "Unary assertion flags (--status, --contains, --jq-path, --equals) are not allowed on streaming calls",
+                    "detail": {},
+                },
+                duration_ms=int((time.monotonic() - start) * 1000),
+            )
+            raise SystemExit(2)
+
+        # Validate and compile --match if provided
+        compiled_match = None
+        if match is not None:
+            filled_match = fill_placeholders(match, resolved.params)
+            try:
+                compile_jq(filled_match, label="grpc --match")
+                compiled_match = filled_match
+            except ConfigError as exc:
+                emit(
+                    ok=False,
+                    command="grpc.call",
+                    error=exc.to_dict(),
+                    duration_ms=int((time.monotonic() - start) * 1000),
+                )
+                raise SystemExit(exc.exit_code)
+
+        # Build request input
+        if call_type == "server_stream":
+            # Parse the single message
+            try:
+                request_input = json.loads(resolved.message) if resolved.message else {}
+                request_input = fill_placeholders(request_input, resolved.params)
+            except json.JSONDecodeError as exc:
+                emit(
+                    ok=False,
+                    command="grpc.call",
+                    error={"type": "ConfigError", "message": f"Invalid JSON in --message: {exc.msg}", "detail": {"message": resolved.message}},
+                    duration_ms=int((time.monotonic() - start) * 1000),
+                )
+                raise SystemExit(2)
+        else:  # bidi
+            # Bidi uses stdin iterator
+            request_input = _stdin_request_iter(resolved.params)
+
+        # Build metadata dict
+        metadata_dict = _parse_metadata(resolved.metadata) if resolved.metadata else None
+
+        # Install signal handlers for graceful shutdown
+        stop_event = threading.Event()
+        prev_term = None
+        prev_int = None
+
+        def _handler(signum, frame):
+            stop_event.set()
+
+        try:
+            prev_term = signal.getsignal(signal.SIGTERM)
+            prev_int = signal.getsignal(signal.SIGINT)
+            signal.signal(signal.SIGTERM, _handler)
+            signal.signal(signal.SIGINT, _handler)
+        except (ValueError, OSError):
+            pass
+
+        # Partial counters shared with _grpc_stream_run so a mid-run error can
+        # report the counts actually emitted so far (M1: no dropped counts).
+        stats = {"messages": 0, "matched": 0}
+
+        try:
+            # Run the streaming call on the already-built client
+            summary = _grpc_stream_run(
+                resolved.client,
+                service=resolved.service,
+                method=resolved.method,
+                call_type=call_type,
+                request_input=request_input,
+                metadata=metadata_dict,
+                timeout=timeout,
+                match=compiled_match,
+                params=resolved.params,
+                stop_event=stop_event,
+                emit_line=_emit_stdout_line,
+                stats=stats,
+            )
+
+            # Emit summary
+            _emit_stdout_line(summary)
+
+            # Exit based on expect_count
+            if expect_count is not None and summary["matched"] < expect_count:
+                raise SystemExit(1)
+            else:
+                raise SystemExit(0)
+        except AgctlError as err:
+            # Emit final error summary line with PARTIAL counts (M1) and a valid
+            # gRPC status code (no invented -1).
+            _emit_stdout_line({
+                "error": err.to_dict(),
+                "summary": True,
+                "messages": stats["messages"],
+                "matched": stats["matched"],
+                "status": {"code": 2, "name": "UNKNOWN", "message": err.message},
+                "duration_ms": int((time.monotonic() - start) * 1000),
+            })
+            raise SystemExit(err.exit_code)
+        except Exception as exc:
+            # Internal error - emit structured error with PARTIAL counts (M1)
+            # and a valid gRPC status code.
+            _emit_stdout_line({
+                "error": {
+                    "type": "InternalError",
+                    "message": str(exc),
+                    "detail": {},
+                },
+                "summary": True,
+                "messages": stats["messages"],
+                "matched": stats["matched"],
+                "status": {"code": 2, "name": "UNKNOWN", "message": str(exc)},
+                "duration_ms": int((time.monotonic() - start) * 1000),
+            })
+            raise SystemExit(2)
+        finally:
+            # Restore previous signal handlers
+            try:
+                if prev_term is not None:
+                    signal.signal(signal.SIGTERM, prev_term)
+                if prev_int is not None:
+                    signal.signal(signal.SIGINT, prev_int)
+            except (ValueError, OSError):
+                pass
+    else:
+        # Unknown call type (shouldn't happen)
+        emit(
+            ok=False,
+            command="grpc.call",
+            error={"type": "ConfigError", "message": f"Unknown call type: {call_type}", "detail": {"call_type": call_type}},
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+        raise SystemExit(2)
diff --git a/agctl/config/models.py b/agctl/config/models.py
index 55fcd53..b5528ac 100644
--- a/agctl/config/models.py
+++ b/agctl/config/models.py
@@ -329,6 +329,51 @@ class LogsConfig(BaseModel):
     defaults: LogsDefaults = Field(default_factory=LogsDefaults)
 
 
+class GrpcTls(BaseModel):
+    """TLS/mTLS settings for a gRPC connection."""
+
+    ca_location: str | None = None
+    certificate_location: str | None = None
+    key_location: str | None = None
+    override_authority: str | None = None
+
+
+class GrpcTarget(BaseModel):
+    """gRPC target configuration: address, TLS, and server reflection settings."""
+
+    address: str
+    use_tls: bool = False
+    tls: GrpcTls | None = None
+    reflection: Literal["auto", "on", "off"] = "auto"
+
+
+class GrpcDescriptorSource(BaseModel):
+    """Protobuf descriptor source: either proto file or descriptor set."""
+
+    proto: str | None = None
+    include_paths: list[str] = Field(default_factory=list)
+    descriptor_set: str | None = None
+
+
+class GrpcTemplate(BaseModel):
+    """gRPC call template: target service, method, metadata, and message."""
+
+    description: str | None = None
+    target: str
+    service: str
+    method: str
+    metadata: dict[str, str] = Field(default_factory=dict)
+    message: dict | None = None
+
+
+class GrpcConfig(BaseModel):
+    """gRPC configuration: targets, descriptors, and templates."""
+
+    targets: dict[str, GrpcTarget] = Field(default_factory=dict)
+    descriptors: list[GrpcDescriptorSource] = Field(default_factory=list)
+    templates: dict[str, GrpcTemplate] = Field(default_factory=dict)
+
+
 class Config(BaseModel):
     version: str
     services: dict[str, ServiceConfig] = Field(default_factory=dict)
@@ -338,6 +383,7 @@ class Config(BaseModel):
     defaults: Defaults = Field(default_factory=Defaults)
     mocks: MocksConfig | None = None
     logs: LogsConfig = Field(default_factory=LogsConfig)
+    grpc: GrpcConfig = Field(default_factory=GrpcConfig)
 
 
 class PartialConfig(Config):
diff --git a/agctl/config/validator.py b/agctl/config/validator.py
index 4aad701..f4c5e29 100644
--- a/agctl/config/validator.py
+++ b/agctl/config/validator.py
@@ -253,6 +253,41 @@ def validate_config(cfg: Config) -> tuple[list[dict], list[dict]]:
                 {"path": f"logs.sources.{name}", "message": str(err)}
             )
 
+    # --- gRPC validation --------------------------------------------------------
+
+    # §3.5.4 — gRPC template -> target dangling refs.
+    grpc_targets = set(cfg.grpc.targets.keys())
+    for name, tpl in cfg.grpc.templates.items():
+        if tpl.target not in grpc_targets:
+            errors.append(
+                {
+                    "path": f"grpc.templates.{name}.target",
+                    "message": f"gRPC template references unknown target '{tpl.target}'",
+                }
+            )
+
+    # §3.5.5 — gRPC descriptor source exactly-one rule.
+    for i, src in enumerate(cfg.grpc.descriptors):
+        has_proto = src.proto is not None
+        has_ds = src.descriptor_set is not None
+        if has_proto == has_ds:  # Both or neither
+            errors.append(
+                {
+                    "path": f"grpc.descriptors[{i}]",
+                    "message": "each grpc.descriptors entry must set exactly one of 'proto' or 'descriptor_set'",
+                }
+            )
+
+    # §3.6 — gRPC template missing-description warnings.
+    for name, tpl in cfg.grpc.templates.items():
+        if _missing_description(tpl.description):
+            warnings.append(
+                {
+                    "path": f"grpc.templates.{name}",
+                    "message": "missing description (discovery degrades without it)",
+                }
+            )
+
     return errors, warnings
 
 
diff --git a/agctl/data/sample-config.yaml b/agctl/data/sample-config.yaml
index bc89543..8bd5286 100644
--- a/agctl/data/sample-config.yaml
+++ b/agctl/data/sample-config.yaml
@@ -141,6 +141,39 @@ defaults:
   timeout_seconds: 10
   database_connection: main-db
 
+# --- grpc: gRPC service targets and templates -------------------------------
+grpc:
+  # targets: named gRPC server addresses
+  targets:
+    order-service:
+      address: "localhost:50051"
+      use_tls: false               # optional; defaults to false (plaintext)
+      reflection: auto             # auto (default) | on | off
+      # tls:                       # optional TLS settings (when use_tls: true)
+      #   override_authority: ""  # optional; override the TLS server name
+
+  # descriptors: fallback proto descriptor sets when reflection is unavailable.
+  # Each entry sets exactly one of `descriptor_set` (a compiled FileDescriptorSet
+  # .pb file) or `proto` (a .proto glob compiled at load via protoc; pair with
+  # `include_paths`).
+  descriptors:
+    - descriptor_set: "protos/order-service.desc"
+    # - proto: "protos/orders/v1/*.proto"
+    #   include_paths: ["protos"]
+
+  # templates: named gRPC request templates
+  templates:
+    create-order:
+      description: "Create a new order via gRPC"
+      target: order-service
+      service: "orders.OrderService"
+      method: "CreateOrder"
+      message:
+        customer_id: "{customer_id}"
+        items:
+          - sku: "{sku}"
+            quantity: 1
+
 # --- logs: log file sources for tailing and searching ------------------------
 logs:
   sources:
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 1dbabdc..48a566e 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,7 +1,7 @@
 # `agctl` — Architecture Document
 
 **Status:** Source-of-truth (as-built).
-**Last updated:** 2026-07-06
+**Last updated:** 2026-07-10
 
 > `ARCHITECTURE.md` is the **source of truth for how the system works today** —
 > the as-built runtime, module boundaries, data flows, and extension model. Its
@@ -120,6 +120,7 @@ agctl/
 │   ├── check_commands.py       # check ready
 │   ├── config_commands.py      # config validate / show / init / migrate
 │   ├── discover_commands.py    # discover summary / category / item / search
+│   ├── grpc_commands.py        # grpc call / healthcheck
 │   └── mock_commands.py        # mock run / start / stop / status (HTTP mock + Kafka reactors)
 ├── mock/                       # mock server implementation (HTTP + Kafka)
 │   ├── routing.py              # path-template matching (pure functions)
@@ -138,6 +139,7 @@ agctl/
     ├── db_client.py            # driver dispatch via agctl.db_drivers entry points
     ├── db_driver_protocol.py   # DBDriver Protocol
     ├── db_drivers/postgresql.py  # built-in psycopg driver (lazy import)
+    ├── grpc_client.py          # grpcio wrapper (lazy import)
     ├── log_client.py           # log backend dispatch via agctl.logs_backends entry points
     ├── log_backend_protocol.py # LogBackend Protocol + CanonicalEntry DTOs
     └── log_backends/ndjson_file.py  # built-in NDJSON file backend (lazy import)
@@ -189,6 +191,34 @@ Trace of `agctl db query --template find-order --param orderId=42`:
 6. **Return** — `{"rows": [...], "row_count": N, "connection": name}`.
 7. **Emit + exit** — `@envelope`'s `else` branch emits `ok:true` and exits 0.
 
+Trace of `agctl grpc call --target echo-server --service echo.EchoService --method Unary --message '{"msg":"hello"}'`:
+
+1. **Click parses** argv; the root group stored `--config` in
+   `ctx.obj["config_path"]`. Click invokes `grpc_call`, which routes based on
+   call type detection.
+2. **Call type detection** — `_detect_call_type` loads config, resolves the target
+   (`echo-server`), constructs `GrpcClient`, and calls `find_method` to get the
+   method descriptor and determine call type (`unary` for this example).
+3. **Unary routing** — for `unary`/`client_stream`, delegates to the wrapped
+   `_grpc_call_envelope` (which wraps `_grpc_call_core`).
+4. **`@envelope`** starts a monotonic timer and calls `_grpc_call_core` in a `try`.
+5. **Config load** — already loaded; `load_config_or_raise` re-validates.
+6. **Message serialization** — JSON request is parsed, placeholders are filled,
+   and `json_format.ParseDict` serializes to protobuf bytes.
+7. **gRPC call** — `GrpcClient.call_unary` invokes the channel's `unary_unary`
+   method with request/response serializers. Success → JSON response deserialized
+   via `json_format.MessageToDict`; RpcError (non-OK status) → caught and
+   returned as `GrpcUnaryResult` with status field.
+8. **Post-call assertions** — if assertion flags were set, `evaluate_grpc_assertions`
+   runs (reusing jq/subset/equals primitives); failure → `AssertionFailure`.
+9. **Return** — `{"target": "localhost:50051", "service": "echo.EchoService",
+   "method": "Unary", "call_type": "unary", "status": {"code": 0, "name": "OK",
+   "message": ""}, "message": {...}, "initial_metadata": {...}, "trailers": {...}}`.
+10. **Emit + exit** — `@envelope`'s `else` branch emits `ok:true` and exits 0.
+
+**Server-streaming/bidi routing** — for `server_stream`/`bidi` call types, the
+command bypasses `@envelope` and emits NDJSON directly (§6, streaming exceptions).
+
 **Failure paths** all funnel through `@envelope`:
 
 | `_core` behavior | Envelope reaction | Exit |
@@ -359,6 +389,14 @@ results as they happen, so it violates "one object per invocation":
 - Supports `--duration` (daemon timer) and `--until-stopped` (signal-only) modes, mutually exclusive.
 - Startup errors emit a single structured envelope **before** any entry line.
 
+**The fourth and fifth streaming exceptions — `grpc call` (server-streaming and bidi).** Like `http ping`, server-streaming and bidirectional gRPC calls emit NDJSON:
+
+- Not wrapped by `@envelope`.
+- Emits one JSON object **per response message** (NDJSON) directly as the stream runs.
+- Each line includes `event: "message"`, the `message` dict, and optional `trailers`.
+- Installs `SIGTERM`/`SIGINT` handlers that set a stop event; the loop emits a final `{summary:true, messages, matched, status, duration_ms}` and exits `0` (or `1` if `--expect-count` is not met).
+- Startup errors emit a single structured envelope **before** any message line.
+
 **The managed daemon commands — `mock start`/`stop`/`status`** are NOT streaming exceptions. Each is a normal `@envelope`-wrapped command that emits exactly one JSON object and exits 0/1/2:
 
 - `mock start` blocks until the daemon's `started` line appears in the log (or a startup error or timeout), then returns the `mock.start` envelope (`ok:true` with pid/listen/log_path/stubs/reactors/started_at).
@@ -584,6 +622,58 @@ leaves the transaction ambiguous.
 
 ---
 
+### GrpcClient (`clients/grpc_client.py`)
+
+grpcio wrapper with descriptor resolution (reflection + descriptor fallback),
+JSON↔protobuf translation, and four call types. Lazy-import pattern: importing
+`agctl.clients.grpc_client` never requires `grpcio`; the constructor imports
+on-demand and raises `ConfigError` pointing at `pip install 'agctl[grpc]'`.
+
+**Descriptor resolution** (reflection-first, descriptor fallback):
+
+- **Path 1: Injected pool** — test seam; return directly.
+- **Path 2: Reflection** — query `grpc.reflection.v1alpha.ServerReflection` for
+  `list_services` → `file_containing_symbol` responses, deserialize
+  `FileDescriptorProto` messages into a `DescriptorPool`. Reflection mode is
+  controlled per-target: `"auto"` (try reflection, fall back to descriptors),
+  `"on"` (require reflection, error if UNIMPLEMENTED), `"off"` (skip reflection).
+- **Path 3: Descriptor fallback** — load proto files (compile via `grpc_tools.protoc`)
+  or precompiled `.pb` descriptor sets into a `DescriptorPool`.
+
+**JSON↔protobuf translation** — `MessageToJson` / `ParseFromJson` via
+`json_format.ParseDict` and `json_format.MessageToDict`. Request serialization
+fails with `ConfigError` on unknown fields (`ignore_unknown_fields=False`);
+response deserialization skips unknown fields.
+
+**Call types** — `call_type_of(method_desc)` returns one of four strings:
+
+- `"unary"` — `unary_unary` → single request, single response.
+- `"client_stream"` — `stream_unary` → request iterator, single response.
+- `"server_stream"` — `unary_stream` → single request, response iterator.
+- `"bidi"` — `stream_stream` → request iterator, response iterator.
+
+**Status-as-result semantics** — gRPC status is a result field, not an assertion.
+Non-OK `RpcError` (e.g. `NOT_FOUND`, `PERMISSION_DENIED`) is caught and
+returned as `GrpcUnaryResult` with `status` (code/name/message) and `message=None`;
+the envelope remains `ok:true`. Assertion flags (`--status`, `--contains`,
+`--match`, `--jq-path`, `--equals`) are evaluated separately via
+`evaluate_grpc_assertions` (reusing `jq_bool`/`json_subset`/`jq_value`/`parse_equals`
+primitives) and raise `AssertionFailure` on mismatch.
+
+**Exception mapping:** `RpcError.DEADLINE_EXCEEDED` → `OperationTimeout`;
+other `RpcError` → status-in-result (connection succeeded, call failed); bare
+`Exception` → `ConnectionFailure`.
+
+**Healthcheck** — calls `grpc.health.v1.Health/Check` via `HealthStub`.
+Returns `GrpcHealthResult` with `status` enum name (`SERVING`/`NOT_SERVING`/`UNKNOWN`)
+and optional `note`. `UNIMPLEMENTED` status returns `UNKNOWN` (not an error).
+
+**Lazy-grpcio rule** — grpcio, grpcio-tools, grpcio-health-checking,
+grpcio-reflection, and protobuf are imported only when `GrpcClient` is constructed;
+missing library surfaces as `ConfigError` (exit 2) pointing at the `grpc` extra.
+
+---
+
 ## 9. Assertion Engine
 
 Primitives in `assertions.py`, composed by the command layer. Five families:
@@ -751,6 +841,14 @@ and **skipped** — it never bricks the CLI, the registry, or driver discovery.
 - **Assertion modes** — loaded lazily on first `get_default_registry()` and
   cached. See §9.
 
+> **In-tree gRPC support:** The `grpc` command group is implemented in-tree
+> (`commands/grpc_commands.py` and `clients/grpc_client.py`) and does **not**
+> use the `agctl.plugins` entry point. Unlike protocol plugins (which add new
+> top-level groups via entry points), gRPC is a core transport and lives
+> alongside HTTP/Kafka/DB in the main module tree. The `grpc` extra
+> (`grpcio`, `grpcio-tools`, `grpcio-health-checking`, `grpcio-reflection`,
+> `protobuf`, `jq`) follows the same lazy-import pattern.
+
 ---
 
 ## 11. Dependency & Packaging Model
@@ -767,8 +865,9 @@ extras, so a user installs only what they need and the package imports fast:
 | `kafka` | `confluent-kafka`, `jq` | `kafka *` |
 | `db` | `psycopg[binary]`, `jq` | `db *` |
 | `logs` | `jq` | `logs *` (`--match` on logs query/assert/tail) |
+| `grpc` | `grpcio`, `grpcio-tools`, `grpcio-health-checking`, `grpcio-reflection`, `protobuf`, `jq` | `grpc *` |
 | `dev` | `pytest` | unit tests |
-| `integration` | `testcontainers`, `agctl[db,kafka,http]`, `pytest` | live integration tests |
+| `integration` | `testcontainers`, `agctl[db,kafka,http,grpc]`, `pytest` | live integration tests |
 
 `jq` is bundled under `kafka`/`db`/`logs` (which always needed it) **and** exposed as a
 dedicated `jq` extra for HTTP-only users (response assertions) and HTTP-only-mock
diff --git a/docs/DESIGN.md b/docs/DESIGN.md
index de8f7b3..a30bc92 100644
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
@@ -11,7 +11,7 @@
 
 1. [Goals & Non-Goals](#1-goals--non-goals)
 2. [Configuration Schema](#2-configuration-schema)
-3. [CLI Command Design](#3-cli-command-design) *(includes `agctl discover` §3.6)*
+3. [CLI Command Design](#3-cli-command-design) *(includes `agctl discover` §3.9)*
 4. [Output Schema](#4-output-schema)
 5. [Configuration Resolution Order](#5-configuration-resolution-order)
 6. [AGENTS.md Template](#6-agentsmd-template)
@@ -315,6 +315,61 @@ logs:
     timeout_seconds: 10
     poll_interval_ms: 100
 
+# ---------------------------------------------------------------------------
+# grpc — gRPC targets, descriptors, and call templates.
+#   targets.<name>: gRPC endpoint configuration
+#     address: host:port of the gRPC server
+#     use_tls: enable TLS (default false)
+#     tls: optional TLS/mTLS settings
+#       ca_location: path to CA certificate (PEM)
+#       certificate_location: path to client certificate (mTLS)
+#       key_location: path to client private key (mTLS)
+#       override_authority: override TLS authority name for self-signed certs
+#     reflection: server reflection mode ("auto" tries reflection, falls back to descriptors; "on" requires reflection; "off" disables it)
+#   descriptors: fallback proto descriptor sources (used when reflection is unavailable/off)
+#     proto: path to .proto file to compile on-the-fly
+#     include_paths: proto import paths (optional, for proto files)
+#     descriptor_set: path to precompiled .pb descriptor set file
+#   templates.<name>: gRPC call templates
+#     description: human-readable description
+#     target: name of target from targets
+#     service: fully-qualified service name (e.g. echo.EchoService)
+#     method: method name within the service
+#     metadata: optional metadata dict (supports {placeholder})
+#     message: request message JSON (supports {placeholder})
+# ---------------------------------------------------------------------------
+grpc:
+  targets:
+    echo-server:
+      address: "localhost:50051"
+      use_tls: false
+      reflection: auto
+
+    secure-server:
+      address: "prod.example.com:443"
+      use_tls: true
+      tls:
+        ca_location: "/etc/ssl/certs/ca.pem"
+        certificate_location: "/etc/ssl/certs/client.pem"
+        key_location: "/etc/ssl/private/client.key"
+      reflection: auto
+
+  descriptors:
+    - proto: "/path/to/echo.proto"          # compile on-the-fly
+      include_paths: ["/path/to/protos"]
+    - descriptor_set: "/path/to/descriptor.pb"  # precompiled
+
+  templates:
+    echo-unary:
+      description: "Call the Echo unary method"
+      target: echo-server
+      service: "echo.EchoService"
+      method: "Unary"
+      message:
+        message: "{msg}"
+      metadata:
+        x-trace-id: "{trace_id}"
+
 # ---------------------------------------------------------------------------
 # templates — named HTTP request templates.
 # method:   HTTP verb (GET, POST, PUT, PATCH, DELETE)
@@ -1432,7 +1487,110 @@ Then bumps `version` to `"3"`. `capture.*.from` and `match.body` are **not** vis
 
 ---
 
-### 3.8 `agctl discover` — Lazy Scoped Discovery
+### 3.8 `agctl grpc` — gRPC Operations
+
+The `agctl grpc` command group provides gRPC client operations: unary calls, streaming calls, and health checks. All commands support server reflection for descriptor resolution and fall back to configured proto descriptor files.
+
+#### `agctl grpc call`
+
+Make a gRPC call (unary, client-streaming, server-streaming, or bidirectional). Either invoke a template or provide free-form arguments.
+
+```
+# Template mode
+agctl grpc call <template>
+    [--param key=value]           # fill {placeholder} in template message/metadata
+
+# Free-form mode (mutually exclusive with template)
+agctl grpc call
+    [--target <name>]            # named gRPC target from config
+    [--address host:port]        # raw gRPC address (host:port format)
+    --service <Service>          # fully-qualified service name (e.g. echo.EchoService)
+    --method <Method>            # method name within the service
+    [--message 'JSON']           # request message body (JSON)
+    [--metadata k=v]             # repeatable metadata headers
+    [--timeout <seconds>]
+
+# Assertion flags (all require ≥1 to enter assertion mode)
+    [--status <code>]            # expected gRPC status code (name or number)
+    [--contains 'JSON']          # JSON needle in response message (subset match)
+    [--match <jq>]               # jq predicate against result envelope
+    [--jq-path <jq>]             # jq path (used with --equals)
+    [--equals <value>]           # expected value for --jq-path
+```
+
+**Call types and I/O model:**
+
+| Call type | Input | Output | Example |
+|---|---|---|---|
+| **unary** | Single `--message` JSON object | Single JSON response (envelope) | RPC-like request/response |
+| **client-stream** | NDJSON on stdin (one JSON per line) | Single JSON response (envelope) | Upload streaming |
+| **server-stream** | Single `--message` JSON object | NDJSON on stdout (one per line) | Download streaming |
+| **bidi** | NDJSON on stdin | NDJSON on stdout | Bidirectional chat |
+
+**Streaming calls (server-streaming, bidi):** Unlike unary/client-streaming which return a single JSON envelope, server-streaming and bidi emit one NDJSON line per response message. The command installs `SIGTERM`/`SIGINT` handlers and emits a final `summary` line with `messages`, `matched`, `status`, and `duration_ms`. Exit code is `0` on clean shutdown, or `1` if `--expect-count` is not met.
+
+**Template mode example:**
+
+```bash
+agctl grpc call echo-unary --param msg="hello world"
+```
+
+**Free-form example:**
+
+```bash
+agctl grpc call --target echo-server --service echo.EchoService --method Unary --message '{"msg":"hello"}'
+agctl grpc call --address localhost:50051 --service echo.EchoService --method Unary --message '{"msg":"hello"}'
+```
+
+**Client-streaming example (pipe NDJSON on stdin):**
+
+```bash
+echo '{"id":1}' '{"id":2}' '{"id":3}' | agctl grpc call --target echo-server --service upload.Uploader --method Upload
+```
+
+**Server-streaming example (NDJSON on stdout):**
+
+```bash
+agctl grpc call --target echo-server --service stream.Streamer --method Stream --message '{"count":10}'
+# Emits one JSON line per message, then final summary line
+```
+
+**Bidirectional streaming (NDJSON in, NDJSON out):**
+
+```bash
+echo '{"request":"a"}' '{"request":"b"}' | agctl grpc call --target echo-server --service chat.Chat --method ChatStream
+# Each stdin request generates one stdout response line
+```
+
+**Response assertions:** When any assertion flag (`--status`, `--contains`, `--match`, `--jq-path`, `--equals`) is set, the command evaluates all assertions post-call (AND logic). A failed assertion raises `AssertionError` (exit 1) with `error.detail` containing the full result and failure list. A non-OK gRPC status is **not** an assertion failure by default — status is a result field. Use `--status OK` (or `0`) to assert success.
+
+**Status-as-result semantics:** gRPC status is surfaced in the result envelope under `status` (with `code`, `name`, `message`). Even non-OK statuses (e.g. `NOT_FOUND`, `PERMISSION_DENIED`) return `ok:true` with the status in `result.status` — only assertion flags flip this to `ok:false`. This mirrors HTTP: a 4xx/5xx response is `ok:true` by default, assertions are opt-in.
+
+#### `agctl grpc healthcheck`
+
+Check health of gRPC services via the standard gRPC health protocol (grpc.health.v1.Health).
+
+```
+agctl grpc healthcheck
+    [--target <name>]            # check specific target
+    [--service <name>]           # optional service name (empty = overall health)
+    [--all]                      # check all targets (default when neither flag given)
+```
+
+Returns `ok:true` with `result.targets` (dict keyed by target name) and `result.all_serving` (bool). Each target entry contains `address`, `status` (`SERVING`/`NOT_SERVING`/`UNKNOWN`), and optional `note`.
+
+**Examples:**
+
+```bash
+agctl grpc healthcheck                     # Check all targets
+agctl grpc healthcheck --all              # Same
+agctl grpc healthcheck --target echo       # Check specific target
+agctl grpc healthcheck --target echo --service echo.EchoService  # Check specific service
+```
+
+---
+
+### 3.9 `agctl discover` — Lazy Scoped Discovery
 
 The discovery subsystem lets an agent understand what is available in the system **without loading everything into context at once**. It is structured as three progressive levels: a summary, a category listing, and a single-item detail. The agent fetches only what the current task requires.
 
@@ -1459,7 +1617,9 @@ agctl discover
     "kafka_patterns": 5,
     "db_templates": 8,
     "log_sources": 2,
-    "hint": "Run 'agctl discover --category <name>' to list items. Categories: services, http-templates, kafka-patterns, db-templates, mock-http-stubs, mock-kafka-reactors, log-sources"
+    "grpc_targets": 2,
+    "grpc_templates": 3,
+    "hint": "Run 'agctl discover --category <name>' to list items. Categories: services, http-templates, kafka-patterns, db-templates, mock-http-stubs, mock-kafka-reactors, log-sources, grpc-services, grpc-methods"
   },
   "duration_ms": 1
 }
@@ -1471,7 +1631,7 @@ Returns names and one-line descriptions for all items in a category. No params,
 
 ```bash
 agctl discover --category <name> [--overlay <path>]
-# <name>: services | http-templates | kafka-patterns | db-templates | mock-http-stubs | mock-kafka-reactors | log-sources
+# <name>: services | http-templates | kafka-patterns | db-templates | mock-http-stubs | mock-kafka-reactors | log-sources | grpc-services | grpc-methods
 ```
 
 **Example — `agctl discover --category http-templates`:**
@@ -1560,6 +1720,26 @@ agctl discover --category <name> --name <item-name> [--overlay <path>]
 }
 ```
 
+**Example — `agctl discover --category grpc-methods --name echo-unary`:**
+
+```json
+{
+  "ok": true,
+  "command": "discover.item",
+  "result": {
+    "category": "grpc-methods",
+    "name": "echo-unary",
+    "description": "Call the Echo unary method",
+    "target": "echo-server",
+    "service": "echo.EchoService",
+    "method": "Unary",
+    "params": ["msg"],
+    "example": "agctl grpc call echo-unary --param msg=X"
+  },
+  "duration_ms": 1
+}
+```
+
 #### `--search` — Cross-category keyword search
 
 When the agent does not know which category to look in, it searches across all categories by name and description. Returns a flat list of matching items at the name+description level only (no detail). The agent follows up with a Level 2 call for the item it wants to use.
@@ -1953,6 +2133,58 @@ Shape varies by category. All items share `name`, `description`, `params[]`, and
 }
 ```
 
+#### `grpc.call` (unary / client-stream)
+
+```json
+{
+  "target": "localhost:50051",
+  "service": "echo.EchoService",
+  "method": "Unary",
+  "call_type": "unary",
+  "status": {
+    "code": 0,
+    "name": "OK",
+    "message": ""
+  },
+  "message": {
+    "message": "hello world"
+  },
+  "initial_metadata": {
+    "content-type": "application/grpc+proto"
+  },
+  "trailers": {}
+}
+```
+
+#### `grpc.healthcheck`
+
+```json
+{
+  "targets": {
+    "echo-server": {
+      "address": "localhost:50051",
+      "status": "SERVING"
+    },
+    "secure-server": {
+      "address": "prod.example.com:443",
+      "status": "SERVING"
+    }
+  },
+  "all_serving": true
+}
+```
+
+#### `grpc.call` (server-stream / bidi) — NDJSON stream
+
+Server-streaming and bidirectional calls emit one JSON object per response message (NDJSON), followed by a final `summary` line:
+
+```json
+{"event":"message","message":{"id":1,"result":"first"},"trailers":null}
+{"event":"message","message":{"id":2,"result":"second"},"trailers":null}
+{"event":"message","message":{"id":3,"result":"third"},"trailers":{"grpc-status":"0","grpc-message":"OK"}}
+{"summary":true,"messages":3,"matched":3,"status":{"code":0,"name":"OK","message":""},"duration_ms":45}
+```
+
 #### `config.validate`
 
 ```json
@@ -2605,7 +2837,6 @@ These items are intentionally deferred. Do not implement them until the core des
 | **MCP server wrapper** | Expose `agctl` as an MCP (Model Context Protocol) tool server so agents that support MCP can call it without shell access. The JSON output schema maps cleanly to MCP tool results. |
 | **Retry / polling DSL** | `agctl db assert --retry-until-pass --max-attempts 5 --interval-ms 500` for assertions against eventually-consistent state. Currently, callers must implement polling themselves. |
 | **Template variable validation** | Warn (or error) at call time if a template defines `{placeholder}` variables that are not supplied via `--param`. Currently, unsupplied placeholders are left as literal strings. |
-| **gRPC support** | First-class `agctl grpc call` command via a plugin. The plugin protocol is designed; implementation is deferred. |
 | **Secret backends** | Pull secrets from Vault or AWS Secrets Manager instead of environment variables. Would be implemented as a resolver plugin hooked into the config resolution pipeline (§5). |
 | **Parallel command execution** | `agctl run --parallel step1.sh step2.sh` for agents that want to fire multiple requests concurrently and assert on all results. |
 | **OpenTelemetry trace propagation** | Inject `traceparent` headers automatically when a trace context is available, enabling distributed traces that span `agctl` invocations. |
diff --git a/docs/superpowers/plans/active/2026-07-09-grpc-support.md b/docs/superpowers/plans/active/2026-07-09-grpc-support.md
new file mode 100644
index 0000000..3bf6254
--- /dev/null
+++ b/docs/superpowers/plans/active/2026-07-09-grpc-support.md
@@ -0,0 +1,764 @@
+# `agctl grpc` Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a first-class in-tree `agctl grpc` transport (`grpc call` + `grpc healthcheck`) under a new `grpc` extra — reflection-first/descriptor-fallback proto resolution, JSON↔protobuf serialization, all four call types (stdin/stdout NDJSON for stream input/output), unary assertion reuse, and gRPC-status-as-result semantics — plus `grpc-services`/`grpc-methods` discovery.
+
+**Architecture:** A fifth transport structurally identical to http/kafka/db/logs. `GrpcClient` (`agctl/clients/grpc_client.py`) lazy-imports `grpcio`/`grpcio-tools`/`google.protobuf`, resolves proto definitions **reflection-first with a config-descriptor fallback** into one `descriptor_pool`, builds message classes dynamically (no generated `_pb2`), and exposes the four call types. `agctl/commands/grpc_commands.py` holds the `grpc call` / `grpc healthcheck` Click commands + the `new_grpc_client` test seam. Unary + client-streaming use the standard `@envelope` core split; server-streaming + bidi are **streaming exceptions** (NDJSON out) that also read **NDJSON in on stdin** for request streams. gRPC status is a *result* (`ok:true`, exit 0) unless an assertion fails — mirroring HTTP 4xx. A gRPC-specific assertion evaluator reuses the jq/subset/equals primitives. `grpc:` config section + pydantic models; `grpc-services`/`grpc-methods` discover categories.
+
+**Tech Stack:** Python ≥3.11, Click, Pydantic v2, PyYAML, `grpcio`/`grpcio-tools`/`grpcio-health-checking`/`protobuf` (new `grpc` extra, lazy-imported), `jq` (bundled in the extra, lazy), pytest + `click.testing.CliRunner`.
+
+**Spec:** [`docs/superpowers/specs/active/2026-07-09-grpc-support-design.md`](../specs/active/2026-07-09-grpc-support-design.md)
+
+## Global Constraints
+
+These apply to every task; each task's requirements implicitly include them. They are the spec's D1–D13 plus three plan-level refinements surfaced by reading the current code (flagged).
+
+- **Additive only (D1).** No existing flag, field, exit code, output shape, command, or entry-point changes. New `grpc` group, new `grpc:` config section, two new discover categories, new `grpc` extra. No `version` bump (additive under major `2`).
+- **In-tree, not a plugin (D1/D13).** Ships in the core package under the `grpc` extra. `GrpcClient` is a **plain DI-constructed class** — no `BUILTIN_DRIVERS`, no entry-point group, no `Protocol` (gRPC is one wire protocol, not a backend family). *(Refinement: the spec's §8/§10 framing leaned on the db/log client-dispatch pattern; the plan drops that — GrpcClient has no `type` dispatch. The §9.3 `Plugin` Protocol remains the seam for genuinely different future protocols.)*
+- **Reflection-first, descriptor-fallback (D2).** `reflection: auto` (default) or `on` → query the server reflection service; `off`, or reflection `UNIMPLEMENTED` under `auto` → load config descriptors (`proto` glob compiled via `grpc_tools.protoc`, or a pre-compiled `descriptor_set` blob). Reflection miss + no descriptors → `ConfigError` (exit 2).
+- **JSON in / JSON out (D3).** Request authored as JSON (`--message` / template `message`); `json_format.ParseDict(json, msg, ignore_unknown_fields=False)` serializes. Response decoded via `json_format.MessageToDict`. Message classes from `message_factory.GetMessageClass(message_desc)` over the resolved `descriptor_pool` — **no generated `_pb2` modules**. `ParseDict` unknown-field/type-mismatch → `ConfigError` (exit 2) pre-call.
+- **All four call types; call-type auto-detected from the descriptor (D4).** `MethodDescriptor.client_streaming`/`server_streaming` → `unary` (neither) / `server_stream` / `client_stream` / `bidi`. The emitted `call_type` token is one of `"unary" | "server_stream" | "client_stream" | "bidi"`.
+- **Bidirectional NDJSON symmetry (D4).** Server-stream/bidi emit one JSON object per response message (NDJSON) + a `summary` line (streaming exceptions, mirror `logs tail`). Client-stream/bidi **consume NDJSON on stdin** (one request message per line, EOF ends). `--message`/template `message` is valid only for unary/server-stream; stdin is valid only for client-stream/bidi; mismatch → `ConfigError` (exit 2). Unary/client-stream return one envelope (the single result).
+- **gRPC status is a result, not an error (D6).** A non-OK status → `ok:true`, exit `0`, status captured in `result.status = {code, name, message}` — unless an assertion flag fails. Only `--status`/`--contains`/`--match`/`--jq-path`/`--equals` mismatch → `AssertionFailure` (exit 1).
+- **Error mapping.** `grpc.RpcError` with `code() == DEADLINE_EXCEEDED` → `OperationTimeout` (exit 1, the `--timeout` budget). Any other `grpc.RpcError` → captured into `result.status` (ok path, D6). A non-`RpcError` exception during a call → `ConnectionFailure` (exit 2). Missing `grpc` extra → `ConfigError` pointing at `pip install 'agctl[grpc]'`. Unknown service/method → `TemplateNotFound` (exit 2).
+- **Unary assertions reuse primitives via a NEW gRPC evaluator (D7).** *(Refinement: the spec's Affects line said `assertions.py (reuse only)`; that is inaccurate — `evaluate_http_assertions` is HTTP-shaped, reading `result["status_code"]` (int) / `result["body"]` and comparing `--status` as an int.)* The plan ADDS to `agctl/assertions.py`: `validate_grpc_assertion_args(*, status, contains, match, jq_path, equals)`, `evaluate_grpc_assertions(result, *, status, contains, match, jq_path, equals)`, and a gRPC status name↔code map. They reuse `compile_jq`/`jq_bool`/`jq_value`/`json_subset`/`parse_equals`/`type_aware_equal`/`_response_body_snapshot` unchanged. `--match` is rooted at the **whole gRPC result envelope**; `--contains`/`--jq-path` at `result["message"]`; `--status` compares against `result["status"]` (name or 0–16 number).
+- **gRPC metadata (D8).** `--metadata key=value` (repeatable, caller wins) + template `metadata`; initial metadata sent, **trailers** captured in the result. Metadata keys are lowercased on the wire (gRPC rule).
+- **TLS/plaintext (D9).** `use_tls` (default `false` → plaintext h2c) + optional `tls` block (`ca_location`/`certificate_location`/`key_location`/`override_authority`), mirroring `kafka.ssl` including empty-string-counts-as-unset.
+- **No `@model_validator` anywhere in the codebase.** *(Refinement of spec §7.2.)* The `GrpcDescriptorSource` "exactly one of `proto`/`descriptor_set`" rule is a **structural check in `validator.py`** (Task 2), not a pydantic cross-field validator. Per-field rules (e.g. `reflection` literal, `use_tls` bool) use `@field_validator` (house style) or `Literal` types.
+- **Factory seam location.** *(Refinement of spec §8.3.)* `new_grpc_client(target)` is defined in **`agctl/commands/grpc_commands.py`** (mirrors `new_logs_client`/`new_db_client`), NOT in the client module. Tests monkeypatch `grpc_commands.new_grpc_client`. The factory takes the resolved `GrpcTarget` config object and lazy-imports `GrpcClient`.
+- **Exit codes unchanged:** `0` ok / `1` assertion / `2` config-or-env.
+- **Reuse, do not re-implement:** `envelope`/`load_config_or_raise` from `agctl/command.py`; `emit` from `agctl/output.py`; `fill_placeholders`/`deep_merge` from `agctl/resolution.py`; `parse_params` from `agctl/params.py`; the jq/subset/equals primitives from `agctl/assertions.py`; the `http ping`/`logs tail` signal + NDJSON + manual-startup-envelope streaming pattern.
+- **Unit tests run without optional extras** (ARCHITECTURE §12). The `grpc_client` module imports cleanly without `grpcio`/`protobuf` (lazy import). Command-layer tests inject a fake client via `new_grpc_client` (no grpcio/protobuf). Tests that genuinely exercise protobuf/grpcio use `pytest.importorskip("google.protobuf")` / `("grpc")` so they skip when the extra is absent and run in CI (Task 3 adds the extra to CI).
+- **Branch / harness:** worktree `.claude/worktrees/feat+grpc`, branch `worktree-feat+grpc`. Run tests via the shared venv (resolves worktree `agctl`): `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest`. For protobuf/grpcio-dependent tasks, first `pip install -e ".[grpc]"` in that venv. Commit after every task. End commit messages with `Co-Authored-By: Claude <noreply@anthropic.com>`.
+
+---
+
+## File Structure
+
+**Created:**
+- `agctl/clients/grpc_client.py` — `GrpcClient` (lazy-import grpcio/protobuf; descriptor resolution; JSON↔protobuf; 4 call types; healthcheck) + DTO dataclasses (`GrpcStatus`, `GrpcUnaryResult`, `GrpcStreamMessage`, `GrpcHealthResult`).
+- `agctl/commands/grpc_commands.py` — `grpc_call` / `grpc_healthcheck` Click commands + cores/envelopes + `new_grpc_client` factory + helpers (`_resolve_target`, `_parse_metadata`, call-type dispatch, stdin/stdout NDJSON).
+- `tests/fixtures/echo.proto` — a tiny service with unary/server-stream/client-stream/bidi methods (the descriptor test fixture).
+- `tests/fixtures/echo_descriptor.pb` — pre-compiled `FileDescriptorSet` for `echo.proto` (generated once in Task 5; committed; no protoc at test time).
+- `tests/unit/test_grpc_client.py` — DTO, descriptor-resolution, JSON↔protobuf, call-type, and healthcheck client tests.
+- `tests/unit/test_grpc_assertions.py` — `validate_grpc_assertion_args` + `evaluate_grpc_assertions` tests.
+- `tests/unit/test_grpc_commands.py` — `grpc call` / `grpc healthcheck` command tests (fake-client injection).
+- `tests/integration/test_grpc_commands.py` — in-process grpcio server E2E (self-skipping).
+
+**Modified:**
+- `agctl/config/models.py` — add `GrpcTls`/`GrpcTarget`/`GrpcDescriptorSource`/`GrpcTemplate`/`GrpcConfig`; add `grpc` field to `Config`.
+- `agctl/config/validator.py` — add a `grpc` validation pass (template→target refs, descriptor-source exactly-one, missing-description warnings).
+- `agctl/assertions.py` — add `validate_grpc_assertion_args`, `evaluate_grpc_assertions`, gRPC status name↔code map.
+- `agctl/commands/discover_commands.py` — add `grpc-services` / `grpc-methods` categories.
+- `agctl/cli.py` — register the `grpc` group + subcommands.
+- `agctl/data/sample-config.yaml` + `tests/fixtures/agctl.yaml` — add a `grpc:` section.
+- `pyproject.toml` — add `grpc` extra; add `grpc` to the `integration` aggregate.
+- `.github/workflows/test.yml` — add `grpc` to the CI install line.
+- `tests/unit/test_models.py` — add grpc-model tests.
+- `tests/unit/test_config_validator.py` (or wherever validator tests live) — add grpc validation tests.
+- `tests/unit/test_discover_command.py` — add grpc category tests.
+- `docs/DESIGN.md`, `docs/ARCHITECTURE.md`, `skills/agctl*`, `README.md` — docs sync (final task, via `docs-watcher` + targeted edits).
+
+---
+
+### Task 1: Config models — `GrpcTls` / `GrpcTarget` / `GrpcDescriptorSource` / `GrpcTemplate` / `GrpcConfig`
+
+Foundation: the pydantic models every later task reads. `${ENV}` interpolation and `AGCTL_GRPC__*` env overrides apply automatically via the existing loader; no loader change.
+
+**Files:**
+- Modify: `agctl/config/models.py` (add five models after `LogsConfig`, before `Config`; add one field to `Config`)
+- Test: `tests/unit/test_models.py`
+
+**Interfaces:**
+- Consumes: `BaseModel`, `Field`, `field_validator` from pydantic; `Literal` from `typing` (all already imported in `models.py`).
+- Produces (exact field names + types + defaults):
+  - `GrpcTls(BaseModel)`: `ca_location: str | None = None`; `certificate_location: str | None = None`; `key_location: str | None = None`; `override_authority: str | None = None`.
+  - `GrpcTarget(BaseModel)`: `address: str`; `use_tls: bool = False`; `tls: GrpcTls | None = None`; `reflection: Literal["auto", "on", "off"] = "auto"`.
+  - `GrpcDescriptorSource(BaseModel)`: `proto: str | None = None`; `include_paths: list[str] = Field(default_factory=list)`; `descriptor_set: str | None = None`. (The "exactly one of `proto`/`descriptor_set`" rule is enforced structurally in Task 2, NOT here — no `@model_validator` exists in the codebase.)
+  - `GrpcTemplate(BaseModel)`: `description: str | None = None`; `target: str`; `service: str`; `method: str`; `metadata: dict[str, str] = Field(default_factory=dict)`; `message: dict | None = None`.
+  - `GrpcConfig(BaseModel)`: `targets: dict[str, GrpcTarget] = Field(default_factory=dict)`; `descriptors: list[GrpcDescriptorSource] = Field(default_factory=list)`; `templates: dict[str, GrpcTemplate] = Field(default_factory=dict)`.
+  - `Config` gains: `grpc: GrpcConfig = Field(default_factory=GrpcConfig)` (placed after `logs`).
+
+- [ ] **Step 1: Write the failing model tests**
+
+Add to `tests/unit/test_models.py`:
+1. `test_grpc_tls_defaults`: `GrpcTls()` has all four fields `None`.
+2. `test_grpc_target_defaults`: `GrpcTarget(address="localhost:50051")` has `use_tls is False`, `tls is None`, `reflection == "auto"`. `GrpcTarget(address="x", use_tls=True, reflection="off")` keeps those values.
+3. `test_grpc_target_rejects_bad_reflection`: `GrpcTarget(address="x", reflection="maybe")` raises `ValidationError`.
+4. `test_grpc_descriptor_source_all_none`: `GrpcDescriptorSource()` has `proto is None`, `descriptor_set is None`, `include_paths == []`. (Both-set and both-None are NOT rejected here — that is Task 2's structural rule.)
+5. `test_grpc_template_defaults`: `GrpcTemplate(target="t", service="s.v1.S", method="M")` has `description is None`, `metadata == {}`, `message is None`.
+6. `test_grpc_config_empty_default`: `GrpcConfig()` has `targets == {}`, `descriptors == []`, `templates == {}`.
+7. `test_config_has_grpc_field`: `Config(version="2")` has `.grpc` a `GrpcConfig` (empty). `Config(version="2")` built via `model_validate` with `{"version":"2","grpc":{"targets":{"svc":{"address":"h:1"}}}}` yields `cfg.grpc.targets["svc"].address == "h:1"` and `cfg.grpc.targets["svc"].reflection == "auto"` (default applied).
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_models.py -q`
+Expected: FAIL — `GrpcTls`/`GrpcConfig` undefined (ImportError/AttributeError).
+
+- [ ] **Step 3: Add the five models + the Config field**
+
+In `agctl/config/models.py`: define `GrpcTls`, `GrpcTarget`, `GrpcDescriptorSource`, `GrpcTemplate`, `GrpcConfig` (after `LogsConfig`, before `Config`), and add `grpc: GrpcConfig = Field(default_factory=GrpcConfig)` to `Config` (after `logs`). Use `Literal["auto","on","off"]` for `reflection`; no cross-field validator.
+
+- [ ] **Step 4: Run the model tests + full unit suite (regression)**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_models.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS — adding an optional config field with a default is backward-compatible.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add agctl/config/models.py tests/unit/test_models.py && git commit -m "feat(config): add grpc targets/descriptors/templates models"`
+
+---
+
+### Task 2: Config validation — `validate_config` grpc pass
+
+Pure structural checks (no client needed): template→target dangling refs, descriptor-source "exactly one" rule, missing-description warnings.
+
+**Files:**
+- Modify: `agctl/config/validator.py`
+- Test: `tests/unit/test_config_validator.py` (create if absent; otherwise extend)
+
+**Interfaces:**
+- Consumes: `Config`, `GrpcDescriptorSource` from `agctl/config/models.py`; the existing `validate_config(cfg) -> tuple[list[dict], list[dict]]` (returns `(errors, warnings)`, each `{"path": str, "message": str}`); the existing `_missing_description(value) -> bool` helper.
+- Produces — append to `validate_config(cfg)` (after the existing checks), mirroring the DB template→connection pattern verbatim:
+  - **template→target (error):** for each `(name, tpl)` in `cfg.grpc.templates.items()`: if `tpl.target not in cfg.grpc.targets` → `errors.append({"path": f"grpc.templates.{name}.target", "message": f"gRPC template references unknown target '{tpl.target}'"})`.
+  - **descriptor-source exactly-one (error):** for each `(i, src)` in `enumerate(cfg.grpc.descriptors)`: let `has_proto = src.proto is not None`, `has_ds = src.descriptor_set is not None`. If `has_proto == has_ds` (both or neither) → `errors.append({"path": f"grpc.descriptors[{i}]", "message": "each grpc.descriptors entry must set exactly one of 'proto' or 'descriptor_set'"})`.
+  - **missing-description (warning):** for each `(name, tpl)` in `cfg.grpc.templates.items()`: if `_missing_description(tpl.description)` → `warnings.append({"path": f"grpc.templates.{name}", "message": "missing description (discovery degrades without it)"})`. (Mirror the existing templates/logs warning text.)
+
+- [ ] **Step 1: Write the failing validator tests**
+
+In `tests/unit/test_config_validator.py` (create if missing — mirror an existing validator test's `Config(...)` construction):
+1. `test_grpc_template_unknown_target_is_error`: a `Config` with `grpc.templates.t1.target="missing"` and no matching target → `validate_config` errors include `{"path":"grpc.templates.t1.target", ...}`; a matching target contributes no such error.
+2. `test_grpc_descriptor_both_set_is_error`: `grpc.descriptors=[{proto:"a.proto", descriptor_set:"b.pb"}]` → error at `grpc.descriptors[0]`.
+3. `test_grpc_descriptor_neither_set_is_error`: `grpc.descriptors=[{}]` → error at `grpc.descriptors[0]`.
+4. `test_grpc_descriptor_exactly_one_ok`: `grpc.descriptors=[{proto:"a.proto", include_paths:["."]}` and `[{descriptor_set:"b.pb"}]` each contribute no error.
+5. `test_grpc_template_missing_description_warns`: a template with `description=None` → warning at `grpc.templates.<name>`; with a description → no warning.
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_config_validator.py -k grpc -q`
+Expected: FAIL — no grpc checks present (errors/warnings empty).
+
+- [ ] **Step 3: Add the grpc validation pass to `validate_config`**
+
+Edit `agctl/config/validator.py` per the Produces contract (mirror the existing DB template→connection block style).
+
+- [ ] **Step 4: Run validator tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_config_validator.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS (existing fixtures have no `grpc:` section → empty `grpc` → no new errors).
+
+- [ ] **Step 5: Commit**
+
+Run: `git add agctl/config/validator.py tests/unit/test_config_validator.py && git commit -m "feat(config): validate grpc.templates target refs + descriptor source shape"`
+
+---
+
+### Task 3: Packaging — `grpc` extra + CI
+
+Tiny but load-bearing: makes `pip install -e ".[grpc]"` work so later protobuf/grpcio tasks can run.
+
+**Files:**
+- Modify: `pyproject.toml`
+- Modify: `.github/workflows/test.yml`
+
+**Interfaces:**
+- Produces:
+  - `pyproject.toml` `[project.optional-dependencies]` gains: `grpc = ["grpcio>=1.62", "grpcio-tools>=1.62", "grpcio-health-checking>=1.62", "protobuf>=4.25", "jq>=1.6"]`.
+  - The `integration` aggregate changes from `"agctl[db,kafka,http]"` to `"agctl[db,kafka,http,grpc]"`.
+  - `.github/workflows/test.yml` install line changes from `pip install -e ".[dev,http,jq,kafka,db,logs]"` to `pip install -e ".[dev,http,jq,kafka,db,logs,grpc]"`.
+  - **No new `[project.entry-points]` group** (D13).
+
+- [ ] **Step 1: Edit pyproject + CI per the Produces contract**
+
+Apply the three edits above.
+
+- [ ] **Step 2: Install the extra in the worktree venv and verify resolution**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pip install -e ".[grpc]"` (from the worktree root)
+Expected: succeeds; then `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -c "import grpc, grpc_tools, grpc_health, google.protobuf; print('grpc ok')"` prints `grpc ok`.
+
+- [ ] **Step 3: Run the unit suite (regression)**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS (no behavior change).
+
+- [ ] **Step 4: Commit**
+
+Run: `git add pyproject.toml .github/workflows/test.yml && git commit -m "build: add grpc extra (grpcio/grpcio-tools/grpcio-health-checking/protobuf/jq)"`
+
+---
+
+### Task 4: `GrpcClient` DTOs + skeleton (lazy import + DI seams)
+
+The DTOs every layer uses + a constructable client whose heavy libs are lazy-imported. Pure-logic unit tests run without `grpcio`/`protobuf` by injecting `channel` + `descriptor_pool`.
+
+**Files:**
+- Create: `agctl/clients/grpc_client.py`
+- Test: `tests/unit/test_grpc_client.py`
+
+**Interfaces:**
+- Consumes: `ConfigError` from `agctl/errors.py`; `GrpcTarget` from `agctl/config/models.py`.
+- Produces (exact):
+  - Dataclasses (`@dataclass`, `from __future__ import annotations`):
+    - `GrpcStatus`: `code: int`, `name: str`, `message: str = ""`.
+    - `GrpcUnaryResult`: `target: str`, `service: str`, `method: str`, `call_type: str`, `status: GrpcStatus`, `message: dict | None`, `initial_metadata: dict`, `trailers: dict`.
+    - `GrpcStreamMessage`: `message: dict`, `trailers: dict | None`.
+    - `GrpcHealthResult`: `target: str`, `address: str`, `status: str`, `note: str | None = None`.
+  - `class GrpcClient`:
+    - `__init__(self, target: GrpcTarget, *, channel=None, descriptor_pool=None, timeout_seconds: float | None = None)`: store `self._target = target`, `self._channel = channel`, `self._pool = descriptor_pool`, `self._timeout = timeout_seconds`. **Lazy grpcio import only when `channel is None`**: if `channel is None`, `try: import grpc except ImportError: raise ConfigError("gRPC support requires the 'grpc' extra: pip install 'agctl[grpc]'", {}) from exc`; build the channel from `target.address` + TLS/plaintext (plaintext h2c when `not target.use_tls`; TLS channel credentials from `target.tls` when `use_tls`, applying `override_authority`). Store `self._grpc = grpc`. If `channel` was injected, do NOT import grpcio (keeps DI unit tests dep-free).
+    - `resolve_descriptors`, `find_method`, `call_unary`, `call_server_stream`, `call_client_stream`, `call_bidi`, `healthcheck`: raise `NotImplementedError` for now (Tasks 5/6/7 fill them).
+  - The module imports cleanly with neither `grpcio` nor `protobuf` installed (all heavy imports are inside methods/`__init__`'s `channel is None` branch).
+
+- [ ] **Step 1: Write the failing DTO + skeleton tests**
+
+Create `tests/unit/test_grpc_client.py` (no grpcio/protobuf required for these):
+1. `test_status_and_result_dataclasses`: construct `GrpcStatus(code=0, name="OK")`, `GrpcUnaryResult(target="t", service="s", method="m", call_type="unary", status=GrpcStatus(0,"OK"), message={"a":1}, initial_metadata={}, trailers={})`, `GrpcStreamMessage(message={"a":1}, trailers=None)`, `GrpcHealthResult(target="t", address="h:1", status="SERVING")`; assert every field round-trips and defaults apply (`status.message==""`, `result.message` may be `None`, `health.note is None`).
+2. `test_client_uses_injected_channel_and_skips_grpcio_import`: `GrpcClient(GrpcTarget(address="h:1"), channel=object(), descriptor_pool=object())` constructs without importing grpcio (assert `getattr(client, "_grpc", None) is None` — the grpcio module attr is not set when a channel is injected) and `client._channel is the injected object` and `client._pool is the injected object`.
+3. `test_client_missing_extra_when_no_channel`: monkeypatch `builtins.__import__` (or `sys.modules`) so `import grpc` raises `ImportError`; `GrpcClient(GrpcTarget(address="h:1"))` (no injected channel) → raises `ConfigError` whose message contains `agctl[grpc]`.
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_client.py -q`
+Expected: FAIL — module/symbols undefined (ImportError).
+
+- [ ] **Step 3: Implement DTOs + skeleton `GrpcClient`**
+
+Create `agctl/clients/grpc_client.py` with the four dataclasses and `GrpcClient.__init__` per the Produces contract. Method bodies raise `NotImplementedError`. Keep the module import-free of grpcio/protobuf.
+
+- [ ] **Step 4: Run the tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_client.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add agctl/clients/grpc_client.py tests/unit/test_grpc_client.py && git commit -m "feat(grpc): GrpcClient skeleton + DTOs (lazy import, DI seams)"`
+
+---
+
+### Task 5: Descriptor resolution + `find_method` + call-type detection
+
+The gRPC-specific core: learn proto definitions (reflection-first, descriptor-fallback) and locate a method. Uses the bundled `echo_descriptor.pb`. Protobuf-dependent tests use `pytest.importorskip("google.protobuf")`.
+
+**Files:**
+- Modify: `agctl/clients/grpc_client.py` (`resolve_descriptors`, `find_method`)
+- Create: `tests/fixtures/echo.proto`, `tests/fixtures/echo_descriptor.pb`
+- Test: `tests/unit/test_grpc_client.py`
+
+**Interfaces:**
+- Consumes: Task 4 (`GrpcClient.__init__`, `self._channel`, `self._pool`, `self._grpc`, `self._target`); `ConfigError`/`TemplateNotFound` from `agctl/errors.py`; `grpc_tools.protoc` (only for the one-time fixture generation below), `google.protobuf.descriptor_pool`, `google.protobuf.message_factory`, grpc reflection stubs (all lazy/importorskip).
+- Produces:
+  - `resolve_descriptors(self) -> "DescriptorPool"`:
+    - If `self._pool is not None` (injected) → return it (test seam / pre-resolved).
+    - Else if `self._target.reflection in ("auto","on")`: query the server reflection service over `self._channel` for the list of services, then each file descriptor proto; build a `descriptor_pool.DescriptorPool` and add each file descriptor set. On reflection `UNIMPLEMENTED` (an RpcError with that code): if `reflection == "on"` → `ConfigError("reflection requested but the server does not implement it; set grpc.targets.<name>.reflection: off and supply grpc.descriptors", {"target": self._target.address})`; if `reflection == "auto"` → fall through to the descriptor path.
+    - Descriptor fallback (when `reflection == "off"`, or auto-fell-through): requires the command to have passed config descriptors (see Task 9 wiring) — accept a `descriptors: list[GrpcDescriptorSource]` via an additional `__init__` kwarg `descriptors: list | None = None` (store `self._descriptors`). For each source: if `descriptor_set` set → read the binary blob and `pool.add(serialized_pb=<bytes>)` (merge into one pool); if `proto` set → compile via `grpc_tools.protoc` to a `FileDescriptorSet` in memory and add it. If reflection fell through and `self._descriptors` is empty → `ConfigError("no gRPC descriptors available and server reflection is unavailable; configure grpc.descriptors", {"target": self._target.address})`.
+  - `find_method(self, service: str, method: str) -> "MethodDescriptor"`: `pool = self.resolve_descriptors()`; look up `service_desc = pool.FindMessageTypeByName` is NOT the path — use `pool.FindServiceByName(service)` (a `ServiceDescriptor`); if `NotFound` → `TemplateNotFound(f"Unknown gRPC service: {service}", {"service": service})`; `method_desc = service_desc.methods_by_name.get(method)`; if `None` → `TemplateNotFound(f"Unknown gRPC method: {method} on {service}", {"service": service, "method": method})`; return `method_desc`.
+  - **Call-type detection (free helper or staticmethod) `call_type_of(method_desc) -> str`:** `"bidi"` if `method_desc.client_streaming and method_desc.server_streaming`; `"server_stream"` if `method_desc.server_streaming and not method_desc.client_streaming`; `"client_stream"` if `method_desc.client_streaming and not method_desc.server_streaming`; else `"unary"`. (Token set pinned by Global Constraints.)
+  - `GrpcClient.__init__` gains `descriptors: list | None = None` kwarg (default `None`, stored as `self._descriptors`).
+- Produces (fixture): `tests/fixtures/echo.proto` declares `package echo; service Echo { rpc Unary(Request) returns (Response); rpc ServerStream(Request) returns (stream Response); rpc ClientStream(stream Request) returns (Response); rpc Bidi(stream Request) returns (stream Response); }` with simple `Request { string msg = 1; }` and `Response { string msg = 1; int32 n = 2; }` messages. `tests/fixtures/echo_descriptor.pb` is the compiled `FileDescriptorSet` (generated once — see Step 1).
+
+- [ ] **Step 1: Author `echo.proto` + generate `echo_descriptor.pb`**
+
+Write `tests/fixtures/echo.proto` per the Produces contract. Then generate the descriptor set ONCE (requires the Task-3 extra):
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m grpc_tools.protoc --include_imports --proto_path=tests/fixtures --descriptor_set_out=tests/fixtures/echo_descriptor.pb tests/fixtures/echo.proto`
+Expected: `tests/fixtures/echo_descriptor.pb` exists (binary). Commit it.
+
+- [ ] **Step 2: Write the failing descriptor/find_method tests**
+
+Add to `tests/unit/test_grpc_client.py`, each guarded with `pytest.importorskip("google.protobuf")` at the top of the test:
+1. `test_resolve_descriptors_uses_injected_pool`: `GrpcClient(GrpcTarget(address="h:1"), channel=object(), descriptor_pool=SENTINEL)` → `resolve_descriptors() is SENTINEL` (no reflection call).
+2. `test_find_method_from_echo_descriptor`: build a `descriptor_pool.DescriptorPool`, add `tests/fixtures/echo_descriptor.pb` bytes, construct `GrpcClient(GrpcTarget(address="h:1", reflection="off"), channel=object(), descriptor_pool=that_pool)`; `find_method("echo.Echo", "ServerStream")` returns a method descriptor; `call_type_of(it) == "server_stream"`; `find_method("echo.Echo","Unary")` → `"unary"`; `"ClientStream"` → `"client_stream"`; `"Bidi"` → `"bidi"`.
+3. `test_find_method_unknown_service_and_method`: with the echo pool, `find_method("echo.Missing","Unary")` → `TemplateNotFound` (detail `service`); `find_method("echo.Echo","Nope")` → `TemplateNotFound` (detail `method`).
+4. `test_resolve_reflection_unimplemented_off_path_no_descriptors_is_configerror`: with `reflection="off"`, an injected fake reflection-less channel, and no `descriptors` → `resolve_descriptors()` raises `ConfigError` mentioning `grpc.descriptors`. (Inject `descriptor_pool=None` and `descriptors=None`; do not call a real server.)
+- NOTE: a true reflection-success test lives in integration (Task 13). Unit tests cover the injected-pool + fallback + miss paths.
+
+- [ ] **Step 3: Run to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_client.py -k "resolve_descriptors or find_method or call_type" -q`
+Expected: FAIL — `resolve_descriptors`/`find_method` raise `NotImplementedError` (or skip if protobuf absent; after Task 3 they run).
+
+- [ ] **Step 4: Implement `resolve_descriptors`, `find_method`, `call_type_of`**
+
+Implement per the Produces contract. Add the `descriptors` kwarg to `__init__`. Use `pool.FindServiceByName`/`service_desc.methods_by_name`. Keep grpcio/protobuf imports inside the methods (lazy).
+
+- [ ] **Step 5: Run the client tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_client.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+Run: `git add agctl/clients/grpc_client.py tests/fixtures/echo.proto tests/fixtures/echo_descriptor.pb tests/unit/test_grpc_client.py && git commit -m "feat(grpc): descriptor resolution (reflection+fallback) + find_method + call-type detection"`
+
+---
+
+### Task 6: JSON↔protobuf + the four call types + error mapping
+
+The transport calls. Dynamic stubs via `channel.unary_unary`/`unary_stream`/`stream_unary`/`stream_stream` with serializer/deserializer built from message classes; JSON in/out via `json_format`; `grpc.RpcError` mapped per Global Constraints.
+
+**Files:**
+- Modify: `agctl/clients/grpc_client.py` (`call_unary`, `call_server_stream`, `call_client_stream`, `call_bidi`)
+- Test: `tests/unit/test_grpc_client.py`
+
+**Interfaces:**
+- Consumes: Task 5 (`resolve_descriptors`, `find_method`, `call_type_of`); `ConfigError`/`OperationTimeout`/`ConnectionFailure` from `agctl/errors.py`; lazy `google.protobuf.json_format` (`ParseDict`/`MessageToDict`) + `message_factory.GetMessageClass` + `grpc` (`StatusCode`, `RpcError`).
+- Produces — private serializer/deserializer builders (signatures only):
+  - `_msg_class(self, message_desc)` → `message_factory.GetMessageClass(message_desc)` (lazy import).
+  - `_serialize(message_desc)`: returns a callable `dict -> bytes` = `json_format.ParseDict(d, cls(), ignore_unknown_fields=False).SerializeToString()`. (Unknown field/type mismatch inside `ParseDict` raises — the call methods convert that to `ConfigError`.)
+  - `_deserialize(message_desc)`: returns `bytes -> dict` = `json_format.MessageToDict(cls.FromString(b))`.
+  - `call_unary(self, service, method, message_json: dict, *, metadata: dict | None = None, timeout: float | None = None) -> GrpcUnaryResult`:
+    - `md = self.find_method(service, method)`; assert `call_type_of(md) == "unary"` (mismatch → `ConfigError`, but the command layer guards this; client trusts its caller).
+    - Build request via `_serialize(md.input_type)`; the invoker `fn = self._channel.unary_unary(f"/{service}/{method}", request_serializer=ser, response_deserializer=_deserialize(md.output_type))`.
+    - `try: resp = fn(request_bytes, metadata=<(metadata items) or None>, timeout=timeout or self._timeout) except grpc.RpcError as e: <map per below>`.
+    - RpcError mapping: if `e.code() == grpc.StatusCode.DEADLINE_EXCEEDED` → `raise OperationTimeout(message=str(e), detail={})` from e; else build `status = GrpcStatus(code=<numeric>, name=<code name>, message=e.details() or "")`, `msg=None`, and return `GrpcUnaryResult(... status=status, message=None, initial_metadata={}, trailers={})` (non-OK status = result, D6). On any non-RpcError Exception → `raise ConnectionFailure(message=str(exc)) from exc`.
+    - Success (no exception): `resp` is the deserialized dict; return `GrpcUnaryResult(target=self._target... , service, method, call_type="unary", status=GrpcStatus(0,"OK"), message=resp, initial_metadata=<captured>, trailers=<captured>)`. (Capturing initial metadata/trailers from a unary call may require the call to also return trailing metadata — use grpcio's trailing-metadata accessors; if a plain unary unary returns only the message, wrap so the invoker also returns `(message, call)` — acceptable implementation detail. The result MUST populate `initial_metadata` and `trailers` dicts, even if empty.)
+  - `call_server_stream(self, service, method, message_json, *, metadata=None, timeout=None) -> Iterator[GrpcStreamMessage]`: `fn = channel.unary_stream(...)`; iterate `fn(request_bytes, metadata=..., timeout=...)`; for each response dict `yield GrpcStreamMessage(message=resp, trailers=None)`; the FINAL message (or post-loop) carries `trailers=<captured>`. A `DEADLINE_EXCEEDED` RpcError mid-stream → `OperationTimeout`; any other RpcError → end the stream (yield nothing more; the command's `summary` carries the status) — specifically: catch RpcError, set a local `status`, stop iterating. (The command converts the status into the summary line.)
+  - `call_client_stream(self, request_json_iter, *, service, method, metadata=None, timeout=None) -> GrpcUnaryResult`: `fn = channel.stream_unary(...)`; `resp = fn((self._serialize(md.input_type)(d) for d in request_json_iter), metadata=..., timeout=...)`; same RpcError mapping as unary; return `GrpcUnaryResult(... call_type="client_stream", ...)`.
+  - `call_bidi(self, request_json_iter, *, service, method, metadata=None, timeout=None) -> Iterator[GrpcStreamMessage]`: `fn = channel.stream_stream(...)`; iterate over `fn((ser(d) for d in request_json_iter), ...)` yielding `GrpcStreamMessage` per response (trailers on the final); RpcError mapping as server-stream.
+- Produces (numeric code + name): use `grpc.StatusCode` members (each has `.value[0]` = numeric code) to build `GrpcStatus.code`/`name`; OK = `(0, "OK")`.
+
+- [ ] **Step 1: Write the failing call-type tests (protobuf-guarded, fake channel)**
+
+Add to `tests/unit/test_grpc_client.py`, each starting with `pytest.importorskip("google.protobuf")` and using the echo descriptor pool (Task 5) + a **fake channel** whose `unary_unary/unary_stream/stream_unary/stream_stream` return canned invokers:
+1. `test_call_unary_success`: fake `channel.unary_unary("/echo.Echo/Unary", ...)` returns an invoker that returns the deserialized `{"msg":"hi","n":3}`; `call_unary("echo.Echo","Unary",{"msg":"hi"})` returns a `GrpcUnaryResult` with `status.name=="OK"`, `status.code==0`, `message=={"msg":"hi","n":3}`, `call_type=="unary"`.
+2. `test_call_unary_nonok_status_is_result`: invoker raises a fake `RpcError` with `.code()==grpc.StatusCode.NOT_FOUND` and `.details()=="nope"`; `call_unary(...)` returns a result with `status.name=="NOT_FOUND"`, `message is None`, and raises NOTHING (ok path).
+3. `test_call_unary_deadline_is_operation_timeout`: invoker raises `RpcError` `.code()==DEADLINE_EXCEEDED` → `OperationTimeout` is raised.
+4. `test_call_unary_bad_request_json_is_configerror`: the serializer's `ParseDict` raises on an unknown field — `call_unary("echo.Echo","Unary",{"unknown_field":1})` → `ConfigError` (pre-call; the fake channel is never invoked).
+5. `test_call_server_stream_yields_messages`: fake `channel.unary_stream(...)` invoker returns an iterator of 2 deserialized dicts; `list(call_server_stream("echo.Echo","ServerStream",{"msg":"x"}))` == 2 `GrpcStreamMessage` with the expected `message` dicts.
+6. `test_call_client_stream_returns_single_result`: fake `channel.stream_unary(...)` invoker returns `{"msg":"done"}`; `call_client_stream(iter([{"msg":"a"},{"msg":"b"}]), service="echo.Echo", method="ClientStream")` returns one `GrpcUnaryResult` with `call_type=="client_stream"`, `message=={"msg":"done"}`.
+7. `test_call_bidi_yields_messages`: fake `channel.stream_stream(...)` returns an iterator of 2 dicts; `list(call_bidi(iter([{"msg":"a"}]), service="echo.Echo", method="Bidi"))` == 2 `GrpcStreamMessage`.
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_client.py -k "call_" -q`
+Expected: FAIL — methods raise `NotImplementedError`.
+
+- [ ] **Step 3: Implement the serializer/deserializer builders + four call methods**
+
+Implement per the Produces contract. Reuse `find_method`/`call_type_of` from Task 5. Map `grpc.RpcError` exactly as specified (DEADLINE_EXCEEDED→OperationTimeout; other→status result; non-RpcError→ConnectionFailure). Keep all protobuf/grpcio imports lazy.
+
+- [ ] **Step 4: Run the client tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_client.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add agctl/clients/grpc_client.py tests/unit/test_grpc_client.py && git commit -m "feat(grpc): JSON<->protobuf + four call types + RpcError/status mapping"`
+
+---
+
+### Task 7: `healthcheck` client method + `grpc_health`
+
+Readiness via `grpc.health.v1.Health/Check`. `grpcio-health-checking` (added in Task 3) provides `HealthStub` + the status enum.
+
+**Files:**
+- Modify: `agctl/clients/grpc_client.py` (`healthcheck`)
+- Test: `tests/unit/test_grpc_client.py`
+
+**Interfaces:**
+- Consumes: Task 4 (`GrpcClient`, `self._channel`); lazy `grpc_health.v1` (`HealthStub`, `health_pb2.HealthCheckRequest`, `HealthCheckResponse.ServingStatus`). `ConfigError`/`ConnectionFailure` from `agctl/errors.py`.
+- Produces:
+  - `healthcheck(self, service_name: str = "") -> GrpcHealthResult`:
+    - Build a `HealthStub(self._channel)`; call `Check(HealthCheckRequest(service=service_name), timeout=self._timeout)`.
+    - Map the response status enum to a string: `SERVING`/`NOT_SERVING`/`UNKNOWN` (use the enum `.name`).
+    - On `grpc.RpcError` with code `UNIMPLEMENTED` → return `GrpcHealthResult(target=self._target..., address=self._target.address, status="UNKNOWN", note="health service UNIMPLEMENTED")` (NOT an error — mirror `check ready` on a missing health path).
+    - On `grpc.RpcError` `DEADLINE_EXCEEDED` → `OperationTimeout`; other RpcError → `ConnectionFailure(message=str(e))`; non-RpcError → `ConnectionFailure`.
+
+- [ ] **Step 1: Write the failing healthcheck test (protobuf/grpc-guarded)**
+
+Add to `tests/unit/test_grpc_client.py`, guarded with `pytest.importorskip("grpc_health")`:
+1. `test_healthcheck_serving`: a fake channel whose unary_unary returns the serialized bytes of a `HealthCheckResponse(HealthCheckResponse.SERVING)`; `healthcheck()` returns `GrpcHealthResult` with `status=="SERVING"`, `note is None`.
+2. `test_healthcheck_unimplemented_is_unknown`: the fake invoker raises `RpcError(code=UNIMPLEMENTED)`; `healthcheck()` returns `status=="UNKNOWN"`, `note` mentions `UNIMPLEMENTED` (no exception).
+3. `test_healthcheck_deadline_is_timeout`: `RpcError(DEADLINE_EXCEEDED)` → `OperationTimeout`.
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_client.py -k healthcheck -q`
+Expected: FAIL — `NotImplementedError`.
+
+- [ ] **Step 3: Implement `healthcheck`**
+
+Implement per the Produces contract; lazy-import `grpc_health.v1`.
+
+- [ ] **Step 4: Run the client tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_client.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add agctl/clients/grpc_client.py tests/unit/test_grpc_client.py && git commit -m "feat(grpc): healthcheck client method (grpc.health.v1)"`
+
+---
+
+### Task 8: gRPC assertions — `validate_grpc_assertion_args` + `evaluate_grpc_assertions`
+
+The unary assertion suite, gRPC-shaped. Reuses jq/subset/equals primitives; lives in `agctl/assertions.py` alongside the HTTP evaluator.
+
+**Files:**
+- Modify: `agctl/assertions.py`
+- Test: `tests/unit/test_grpc_assertions.py` (new file)
+
+**Interfaces:**
+- Consumes: `compile_jq`, `jq_bool`, `jq_value`, `json_subset`, `parse_equals`, `type_aware_equal`, `_response_body_snapshot` (all existing in `assertions.py`); `AssertionFailure`/`ConfigError` from `agctl/errors.py`; `json` (stdlib).
+- Produces:
+  - `_GRPC_STATUS_BY_NAME: dict[str,int]` and `_GRPC_STATUS_BY_CODE: dict[int,str]` built from `grpc.StatusCode` (lazy import inside a helper, OR a hardcoded `{OK:0, CANCELLED:1, UNKNOWN:2, ...}` map — prefer lazy `grpc.StatusCode` iteration so names/codes stay authoritative). The map covers codes 0–16.
+  - `validate_grpc_assertion_args(*, status, contains, match, jq_path, equals) -> None` — all-keyword; raises `ConfigError` (exit 2) on:
+    - `jq_path`/`equals` XOR (exactly one set) → `ConfigError("--jq-path and --equals must be used together", {})`.
+    - `contains is not None` and `json.loads(contains)` fails → `ConfigError("--contains must be valid JSON", {})`.
+    - `status is not None` and not a valid gRPC code (not an int 0–16 in `_GRPC_STATUS_BY_CODE`, and not a name in `_GRPC_STATUS_BY_NAME`) → `ConfigError(f"--status must be a gRPC code name or number 0-16, got {status!r}", {})`.
+    - Returns `None` otherwise (including all-None).
+  - `evaluate_grpc_assertions(result: dict, *, status, contains, match, jq_path, equals) -> None` — `result` is the `grpc.call` result dict (`{target, service, method, call_type, status: {code,name,message}, message, initial_metadata, trailers}`). Early-return if all kwargs None. Collect failures (no short-circuit). On failures raise `AssertionFailure(f"gRPC response failed {len(failures)} assertion(s)", {"response": result, "failures": failures})`. Failure-entry shapes (pinned):
+    - status: normalize the `status` arg to a code (name→code via map; int as-is); compare to `result["status"]["code"]`; on mismatch `{"mode":"status","expected":<arg>,"actual":<result status name>}`.
+    - contains: `needle = json.loads(contains)`; `matched = json_subset(needle, result.get("message"))`; on miss `{"mode":"contains","needle":needle,"matched":False,"root":"response message","body":<_response_body_snapshot(result.get("message"))>}`.
+    - match: `passed = jq_bool(result, match)` (envelope-rooted — the WHOLE result dict); on miss `{"mode":"match","expr":match,"result":False,"root":"response envelope","body":<_response_body_snapshot(result.get("message"))>}`. (A missing jq library surfaces as `ConfigError` via `jq_bool`/`_jq` — re-raise with a grpc-kind hint `pip install 'agctl[grpc]'`.)
+    - jq-path: `actual = jq_value(result.get("message"), jq_path)`; `expected = parse_equals(equals)`; on `not type_aware_equal(expected, actual)` → `{"mode":"jq-path","path":jq_path,"expected":expected,"actual":actual,"root":"response message","body":<_response_body_snapshot(result.get("message"))>}`.
+
+- [ ] **Step 1: Write the failing assertion tests**
+
+Create `tests/unit/test_grpc_assertions.py`:
+1. `test_validate_pairing`: `validate_grpc_assertion_args(status=None, contains=None, match=None, jq_path=".x", equals=None)` → `ConfigError` (--jq-path/--equals together).
+2. `test_validate_contains_json`: `validate_grpc_assertion_args(..., contains="{bad", ...)` → `ConfigError`.
+3. `test_validate_status_name_and_number`: `validate_grpc_assertion_args(status="NOT_FOUND", ...)` and `validate_grpc_assertion_args(status=5, ...)` both OK; `validate_grpc_assertion_args(status="NOPE", ...)` and `status=99` → `ConfigError`.
+4. `test_validate_all_none_ok`: all-None → returns `None`.
+5. `test_eval_status_pass_and_fail`: a result with `status.code==0`; `evaluate_grpc_assertions(result, status="OK", contains=None, match=None, jq_path=None, equals=None)` → None; `status="NOT_FOUND"` → raises `AssertionFailure`, `error.detail.failures[0]["mode"]=="status"`.
+6. `test_eval_contains`: result `message={"a":1,"b":{"c":2}}`; `contains='{"b":{"c":2}}'` passes; `contains='{"z":1}'` fails with a `contains` failure entry carrying `root=="response message"`.
+7. `test_eval_match_envelope_rooted`: `match='.status.name == "OK"'` passes; `match='.message.a == 1'` passes (envelope root reaches `.message`); `match='.status.name == "NOPE"'` fails (entry `root=="response envelope"`).
+8. `test_eval_jq_path_equals`: `jq_path=".a"`, `equals="1"` passes (type-aware); `equals='"1"'` fails (number≠string).
+9. `test_eval_multiple_failures_no_shortcircuit`: status + contains both wrong → `failures` length 2.
+10. `test_eval_missing_jq_is_configerror`: monkeypatch the jq import to fail; `evaluate_grpc_assertions(result, match=".x", ...)` → `ConfigError` whose message contains `agctl[grpc]`.
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_assertions.py -q`
+Expected: FAIL — symbols undefined.
+
+- [ ] **Step 3: Implement the validator + evaluator + status maps**
+
+Add to `agctl/assertions.py` per the Produces contract. Reuse the named primitives; do NOT duplicate jq/subset/equals logic.
+
+- [ ] **Step 4: Run the assertion tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_assertions.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add agctl/assertions.py tests/unit/test_grpc_assertions.py && git commit -m "feat(grpc): validate_grpc_assertion_args + evaluate_grpc_assertions (reuse jq/subset/equals)"`
+
+---
+
+### Task 9: `grpc call` unary + client-streaming (command + CLI group + fixture)
+
+The one-result command path + the `grpc` CLI group wiring + the `new_grpc_client` seam. Command tests inject a fake client (no grpcio/protobuf).
+
+**Files:**
+- Create: `agctl/commands/grpc_commands.py`
+- Modify: `agctl/cli.py` (import grpc commands; add `@cli.group(name="grpc")`; `grpc_group.add_command(grpc_call)`)
+- Modify: `tests/fixtures/agctl.yaml` (add a `grpc:` section)
+- Test: `tests/unit/test_grpc_commands.py` (new file)
+
+**Interfaces:**
+- Consumes: `envelope`, `load_config_or_raise` from `agctl/command.py`; `validate_grpc_assertion_args`, `evaluate_grpc_assertions` from `agctl/assertions.py` (Task 8); `fill_placeholders`, `deep_merge` from `agctl/resolution.py`; `parse_params` from `agctl/params.py`; `ConfigError`, `AssertionFailure`, `TemplateNotFound` from `agctl/errors.py`; `GrpcClient` + DTOs from `agctl/clients/grpc_client.py`; `GrpcTarget`/`GrpcTemplate` from `agctl/config/models.py`.
+- Produces:
+  - `new_grpc_client(target: GrpcTarget, *, descriptors=None) -> GrpcClient` — test seam (tests monkeypatch `grpc_commands.new_grpc_client`); body: `from ..clients.grpc_client import GrpcClient; return GrpcClient(target, descriptors=descriptors)`. Takes the resolved `GrpcTarget` object (not a name).
+  - `_resolve_target(cfg, name: str | None, address: str | None) -> tuple[GrpcTarget, str]`: if `address is not None`: reject if `name is not None` → `ConfigError("--address is mutually exclusive with --target", {})`; validate `address` is `host:port` (single colon, non-empty host/port) else `ConfigError(f"--address must be host:port: {address!r}", {"address": address})`; return `(GrpcTarget(address=address), address)`. Else if `name is not None`: if `name not in cfg.grpc.targets` → `ConfigError(f"Unknown gRPC target: {name}", {"target": name})`; return `(cfg.grpc.targets[name], name)`. Else → `ConfigError("grpc call requires --target <name> or --address host:port", {})`.
+  - `_parse_metadata(metadata: tuple[str,...]) -> dict[str,str]`: reuse `parse_params` (split on first `=`); values may contain `=`.
+  - `_grpc_call_core(config_path, target_name, address, service, method, message, metadata, param, timeout, status, contains, match, jq_path, equals, overlay_paths) -> dict` (the unary/client-stream envelope core):
+    - `cfg = load_config_or_raise(config_path, overlay_paths)`; `target, resolved_name = _resolve_target(cfg, target_name, address)`.
+    - Template mode is handled by the Click command (it looks up `cfg.grpc.templates[name]` and passes `target_name=tpl.target`, `service=tpl.service`, `method=tpl.method`, plus merged `metadata`/`message`); free-form mode passes them directly. (Decide: the Click command resolves template-vs-freeform and ALWAYS calls the core with concrete target/service/method/message/metadata — the core is mode-agnostic.)
+    - `params = parse_params(param)`; `client = new_grpc_client(target, descriptors=cfg.grpc.descriptors)`.
+    - `md = client.find_method(service, method)`; `call_type = client.call_type_of(md)`.
+    - Input-mode guard vs call_type: build `message_json` for unary/server-stream by `fill_placeholders(deep_merge(tpl_message_or_empty, parse(--message) if given), params)`; for client-stream/bidi, `--message` is rejected (`ConfigError("--message is invalid for streaming-input call types; pipe request messages on stdin", {"call_type": call_type})`). (Streaming input is Task 10; here unary/client-stream only — but the guard must reject stdin usage too. The core accepts a `stdin_lines` arg defaulting to `None`; for unary/client-stream it must be `None`.)
+    - Pre-call: `validate_grpc_assertion_args(status=status, contains=contains, match=match, jq_path=jq_path, equals=equals)`.
+    - Dispatch on call_type: `unary` → `result = client.call_unary(service, method, message_json, metadata=metadata_dict, timeout=timeout)`; `client_stream` → `result = client.call_client_stream(_stdin_request_iter, service=service, method=method, metadata=metadata_dict, timeout=timeout)` where `_stdin_request_iter` reads `sys.stdin` NDJSON lines (only when `call_type=="client_stream"`; here client-stream IS one-result so the core handles it).
+    - Build the `grpc.call` result dict from `result` (the `GrpcUnaryResult` → `{target, service, method, call_type, status:{code,name,message}, message, initial_metadata, trailers}`).
+    - Post-call assertions (only when any assertion kwarg is set — the evaluator early-returns otherwise): `evaluate_grpc_assertions(result_dict, status=status, contains=contains, match=match, jq_path=jq_path, equals=equals)`.
+    - Return `result_dict`.
+  - `_grpc_call_envelope = envelope("grpc.call")(_grpc_call_core)`.
+  - `grpc_call` — `@click.command("call")` accepting EITHER a positional `<template_name>` OR the free-form flags; flags: `--target`, `--address`, `--service`, `--method`, `--message`, `--metadata`(multiple), `--param`(multiple), `--timeout`(float), `--status`, `--contains`, `--match`, `--jq-path`, `--equals`, `--config`(global, via `ctx.obj`), `--overlay`(global). `@click.pass_context`. Behavior:
+    - Read `config_path = ctx.obj.get("config_path") if ctx.obj else None`; `ovs = ctx.obj.get("overlay_paths") if ctx.obj else None`.
+    - Mode resolution: if `template_name` is given → reject any of `--target/--address/--service/--method` → `ConfigError("grpc call <template> is mutually exclusive with --target/--address/--service/--method", {})`; load `cfg` only if needed to resolve the template (or defer into the core). Resolve template fields and pass concrete args to the core.
+    - **Important for Task 10:** this same `grpc_call` command handles streaming call types too, but the streaming emission logic is added in Task 10. In THIS task, the command supports unary + client-stream only; a server-stream/bidi call_type from the core currently flows through the envelope (Task 10 replaces that with NDJSON streaming). Keep the command signature complete; gate the streaming branch on `call_type in {"server_stream","bidi"}` and `raise NotImplementedError` there until Task 10.
+  - `grpc_group` is created in `cli.py` (see below).
+
+- [ ] **Step 1: Add the `grpc:` section to the test fixture**
+
+Append to `tests/fixtures/agctl.yaml` (after `logs:`): a `grpc:` section with `targets.echo` (`address: "${TEST_GRPC_ADDR:-localhost:50051}"`, `use_tls: false`, `reflection: auto`), `descriptors: []`, and `templates.echo-unary` (`description`, `target: echo`, `service: echo.Echo`, `method: Unary`, `message: {msg: "{m}"}`).
+
+- [ ] **Step 2: Write the failing unary/client-stream command tests**
+
+Create `tests/unit/test_grpc_commands.py` mirroring `test_kafka_commands.py` / `test_logs_commands.py`: `from agctl.cli import cli`, `FIXTURE = .../fixtures/agctl.yaml`, an `ENV` dict, `CliRunner`. Define a `_FakeGrpcClient` (methods `find_method`/`call_type_of`/`call_unary`/`call_client_stream`/.../`healthcheck`) returning canned `GrpcUnaryResult`/etc., and an `install_fake(monkeypatch)` that does `monkeypatch.setattr(grpc_commands, "new_grpc_client", lambda target, descriptors=None: fake)`. The fake's `find_method`/`call_type_of` return a stub method descriptor + `"unary"` (or `"client_stream"`).
+1. `test_grpc_call_template_unary`: fake `call_unary` returns `GrpcUnaryResult(..., message={"msg":"hi"}, status=GrpcStatus(0,"OK"), ...)`; `cli` invoke `["grpc","call","echo-unary","--param","m=hi","--config",FIXTURE]` env `ENV` → exit 0, `command=="grpc.call"`, `result.message=={"msg":"hi"}`, `result.status.name=="OK"`, `result.call_type=="unary"`.
+2. `test_grpc_call_freeform_address`: `["grpc","call","--address","localhost:50051","--service","echo.Echo","--method","Unary","--message",'{"msg":"x"}']` → exit 0; the fake saw `service=="echo.Echo"`, `method=="Unary"`.
+3. `test_grpc_call_target_unknown`: `--target nope` → exit 2 `ConfigError`.
+4. `test_grpc_call_address_target_mutex`: `--target echo --address h:1` → exit 2 `ConfigError`.
+5. `test_grpc_call_template_mutex`: `grpc call echo-unary --service x` → exit 2 `ConfigError`.
+6. `test_grpc_call_nonok_status_is_result`: fake returns `status=GrpcStatus(5,"NOT_FOUND")`, no assertion flags → exit 0, `result.status.name=="NOT_FOUND"` (D6).
+7. `test_grpc_call_assertion_status_fail`: fake returns OK; `--status NOT_FOUND` → exit 1 `AssertionError`, `error.detail.failures[0].mode=="status"`.
+8. `test_grpc_call_assertion_match_pass`: `--match '.status.name == "OK"'` → exit 0.
+9. `test_grpc_call_client_stream_envelope`: fake `call_type_of`→`"client_stream"` and `call_client_stream` returns one `GrpcUnaryResult`; invoke `["grpc","call","--target","echo","--service","echo.Echo","--method","ClientStream"]` with `input='{"msg":"a"}\n{"msg":"b"}\n'` (CliRunner `input=`) → exit 0, `result.call_type=="client_stream"`, the fake's `call_client_stream` request-iter saw 2 messages.
+10. `test_grpc_call_bad_request_json_is_configerror`: `--message '{"unknown_field":1}'` → exit 2 `ConfigError` (the fake's `call_unary` is never reached; the serializer/ParseDict guard fires — drive this by having the fake's `call_unary` raise `ConfigError` on unknown fields, OR validate before — pick one and assert exit 2).
+
+- [ ] **Step 3: Run to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_commands.py -q`
+Expected: FAIL — `grpc_commands`/`grpc` group undefined.
+
+- [ ] **Step 4: Implement `grpc_commands.py` + wire the `grpc` group**
+
+Implement `new_grpc_client`, `_resolve_target`, `_parse_metadata`, `_grpc_call_core`, `_grpc_call_envelope`, and `grpc_call` per the Produces contract. Match the kafka/http command style (`@click.option`, `@click.pass_context`, config_path/overlay resolution, envelope call). In `agctl/cli.py`: `from .commands.grpc_commands import grpc_call` (and later `grpc_healthcheck`); add `@cli.group(name="grpc") def grpc_group() -> None: """gRPC call/healthcheck commands."""`; add `grpc_group.add_command(grpc_call)`.
+
+- [ ] **Step 5: Run command tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_commands.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+Run: `git add agctl/commands/grpc_commands.py agctl/cli.py tests/fixtures/agctl.yaml tests/unit/test_grpc_commands.py && git commit -m "feat(grpc): grpc call unary + client-streaming command + grpc CLI group"`
+
+---
+
+### Task 10: `grpc call` server-streaming + bidi (NDJSON streaming + stdin input)
+
+The streaming exceptions: NDJSON out per response message + `summary`; NDJSON in on stdin for request streams. Manual startup-error envelopes (mirror `logs tail`).
+
+**Files:**
+- Modify: `agctl/commands/grpc_commands.py` (streaming branch in `grpc_call` + a `_grpc_stream_run` helper + `_emit_stdout_line`)
+- Test: `tests/unit/test_grpc_commands.py`
+
+**Interfaces:**
+- Consumes: Task 9 (`grpc_call` command, `_resolve_target`, `_parse_metadata`, `new_grpc_client`); `emit` from `agctl/output.py`; `signal`, `threading`, `time`, `json`, `sys`; the `logs tail`/`http ping` signal-install + restore + manual-envelope + summary discipline (read `agctl/commands/logs_commands.py` `logs_tail` and mirror it).
+- Produces:
+  - `_emit_stdout_line(line: dict) -> None` — write one NDJSON line to stdout (mirror `logs_commands._emit_stdout_line` / `http_commands._emit_stdout_line`).
+  - `_grpc_stream_run(client, *, service, method, call_type, request_input, metadata, timeout, match, expect_count, stop_event, emit_line) -> dict`: drive `client.call_server_stream(...)` (for `server_stream`, request = the single `--message`/template message) or `client.call_bidi(request_json_iter=<stdin lines>, ...)` (for `bidi`); for each yielded `GrpcStreamMessage`, apply the per-message `--match` filter (`jq_bool(message_dict, filled_match)` — message-rooted; a missing jq lib → `ConfigError` surfaced as a startup error BEFORE streaming) and emit one `{"event":"message","message":<dict>,"trailers":<trailers or null>}` line via `emit_line`; count `messages` and `matched`. Honor `expect_count`. Return a `summary` dict `{"summary": True, "messages": <n>, "matched": <m>, "status": <final status or {"code":0,"name":"OK","message":""}>, "duration_ms": <elapsed>}`. If `expect_count` is set and `matched < expect_count`, the returned summary carries the shortfall and the caller exits 1.
+  - `grpc_call` streaming branch (replaces the Task-9 `NotImplementedError` for `call_type in {"server_stream","bidi"}`): NOT `@envelope`-wrapped for these call types — emit NDJSON. Behavior:
+    - Resolve config + target + method + call_type (same as unary); on `AgctlError` during setup → `emit(ok=False, command="grpc.call", error=err.to_dict(), duration_ms=...)` + `raise SystemExit(err.exit_code)`; on other Exception → `InternalError` envelope + `raise SystemExit(2)`.
+    - Input guard: `server_stream` requires `--message`/template message (no stdin); `bidi` requires stdin request messages (reject `--message` for bidi). Unary assertion flags (`--status`/`--contains`/`--jq-path`/`--equals`) rejected on streams → `ConfigError`; only `--match`/`--expect-count` allowed.
+    - If `--match` given: `filled = fill_placeholders(match, params)`; `compile_jq(filled, label="grpc --match")` up front (loud `ConfigError` on bad expr / missing jq).
+    - Install `stop_event = threading.Event()` + SIGTERM/SIGINT handlers that `stop_event.set()` (guard non-main-thread); restore in `finally`.
+    - `summary = _grpc_stream_run(...)`; emit the summary via `_emit_stdout_line`; `raise SystemExit(0)` (or `1` if `expect_count` not met).
+  - For `bidi`, stdin-EOF closes the request half; the call drains remaining responses. For `server_stream`, the single request is sent and responses streamed.
+
+- [ ] **Step 1: Write the failing streaming tests**
+
+Add to `tests/unit/test_grpc_commands.py` (fake client's `call_server_stream`/`call_bidi` yield canned `GrpcStreamMessage` lists; drive via `CliRunner` `input=` for bidi):
+1. `test_grpc_call_server_stream_emits_ndjson_and_summary`: fake `call_type_of`→`"server_stream"`, `call_server_stream` yields 2 `GrpcStreamMessage(message={"msg":"a"})`/`{"msg":"b"}`; invoke `["grpc","call","--target","echo","--service","echo.Echo","--method","ServerStream","--message",'{"msg":"x"}']` → exit 0; stdout has 2 `event:"message"` lines + 1 `summary` line (`json.loads` each: messages lack `summary`; summary has `summary==True`, `messages==2`, `matched==2`).
+2. `test_grpc_call_bidi_reads_stdin_and_streams`: fake `call_type_of`→`"bidi"`, `call_bidi` echoes back one response per request; invoke with `input='{"msg":"a"}\n{"msg":"b"}\n'` → exit 0; stdout has 2 message lines + summary; the fake's `call_bidi` request-iter saw 2 messages.
+3. `test_grpc_call_stream_match_filters_and_expect_count`: fake `call_server_stream` yields 3 messages (2 matching `--match '.message.msg == "x"'`); `--expect-count 2` → exit 0, `summary.matched==2`. `--expect-count 3` → exit 1, `error`/summary reflects the shortfall.
+4. `test_grpc_call_stream_rejects_unary_assertion_flags`: `--status OK` on a server-stream → exit 2 `ConfigError`.
+5. `test_grpc_call_stream_bad_match_startup_error`: `--match '.msg =='` (malformed) → exit 2, one `ConfigError` envelope line, no message lines streamed.
+6. `test_grpc_call_stream_unknown_target_startup_error`: `--target nope` → exit 2 `ConfigError` envelope (single line, no streaming).
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_commands.py -k "server_stream or bidi or stream" -q`
+Expected: FAIL — streaming branch raises `NotImplementedError`.
+
+- [ ] **Step 3: Implement the streaming branch + `_grpc_stream_run` + `_emit_stdout_line`**
+
+Implement per the Produces contract. Read `agctl/commands/logs_commands.py` (`logs_tail`) and mirror its signal-install/restore + manual-envelope + summary + `SystemExit` discipline and its `_emit_stdout_line`.
+
+- [ ] **Step 4: Run command tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_commands.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add agctl/commands/grpc_commands.py tests/unit/test_grpc_commands.py && git commit -m "feat(grpc): grpc call server-streaming + bidi (NDJSON out, stdin NDJSON in)"`
+
+---
+
+### Task 11: `grpc healthcheck` command
+
+The readiness command (grpc analog of `check ready`). Wires `grpc_healthcheck` onto the `grpc` group.
+
+**Files:**
+- Modify: `agctl/commands/grpc_commands.py` (`grpc_healthcheck` command + core)
+- Modify: `agctl/cli.py` (`grpc_group.add_command(grpc_healthcheck)`)
+- Test: `tests/unit/test_grpc_commands.py`
+
+**Interfaces:**
+- Consumes: `envelope`, `load_config_or_raise`; `new_grpc_client`; `ConfigError`.
+- Produces:
+  - `_grpc_healthcheck_core(config_path, target, service, all_, overlay_paths) -> dict`:
+    - `cfg = load_config_or_raise(config_path, overlay_paths)`. Select targets: if `all_` or neither `target` given → all `cfg.grpc.targets`; else `[target]`. Unknown `target` → `ConfigError`.
+    - For each selected target name: `client = new_grpc_client(cfg.grpc.targets[name])`; `res = client.healthcheck(service or "")`; collect `{name: {"address": res.address, "status": res.status, ("note": res.note)}}`.
+    - Return `{"targets": {…}, "all_serving": <all statuses == "SERVING">}`.
+  - `_grpc_healthcheck_envelope = envelope("grpc.healthcheck")(_grpc_healthcheck_core)`.
+  - `grpc_healthcheck` — `@click.command("healthcheck")` with `--target`, `--service`, `--all`, `--config`, `--overlay`; `@click.pass_context`; resolves config_path/overlays and calls the envelope.
+
+- [ ] **Step 1: Write the failing healthcheck command tests**
+
+Add to `tests/unit/test_grpc_commands.py` (fake `healthcheck` returns canned `GrpcHealthResult`):
+1. `test_grpc_healthcheck_single_target`: `--target echo --service ""` → exit 0, `command=="grpc.healthcheck"`, `result.targets.echo.status=="SERVING"`, `result.all_serving==True`.
+2. `test_grpc_healthcheck_all`: `--all` → one entry per fixture target; `all_serving` reflects them.
+3. `test_grpc_healthcheck_unknown_is_unknown_not_error`: fake returns `status=="UNKNOWN", note="health service UNIMPLEMENTED"` → exit 0, `all_serving==False`, `targets.echo.note` present.
+4. `test_grpc_healthcheck_unknown_target`: `--target nope` → exit 2 `ConfigError`.
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_commands.py -k healthcheck -q`
+Expected: FAIL — `grpc_healthcheck` undefined.
+
+- [ ] **Step 3: Implement `grpc_healthcheck` + core; register on the group**
+
+Implement per the Produces contract. In `cli.py`: add `grpc_healthcheck` to the import and `grpc_group.add_command(grpc_healthcheck)`.
+
+- [ ] **Step 4: Run command tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_grpc_commands.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add agctl/commands/grpc_commands.py agctl/cli.py tests/unit/test_grpc_commands.py && git commit -m "feat(grpc): grpc healthcheck command"`
+
+---
+
+### Task 12: `discover` — `grpc-services` / `grpc-methods` categories
+
+Add the two categories across the four discover modes. `grpc-methods` item detail enumerates the request message field schema via `GrpcClient`. Tests inject a fake client (protobuf-free).
+
+**Files:**
+- Modify: `agctl/commands/discover_commands.py`
+- Test: `tests/unit/test_discover_command.py`
+
+**Interfaces:**
+- Consumes: `GrpcClient` from `agctl/clients/grpc_client.py` (local import inside cores to avoid a module-load cycle); existing discover helpers; `ConfigError`/`TemplateNotFound`.
+- Produces:
+  - `_VALID_CATEGORIES`: append `"grpc-services"` and `"grpc-methods"`.
+  - `_SUMMARY_HINT`: extend the category list in the hint string with `, grpc-services, grpc-methods`.
+  - `_summary_core`: add `"grpc_targets": len(cfg.grpc.targets)` and `"grpc_methods": <total methods across targets>` (counting may require resolving descriptors — to keep summary cheap and offline-safe, count `grpc_methods` as the number of `grpc.templates` plus a best-effort 0 when reflection is needed; simplest: `grpc_methods = len(cfg.grpc.templates)` in summary, with the per-service detail in `_item_core`). **Decision: summary `grpc_methods = len(cfg.grpc.templates)`** (templates are the named-call surface; full live method enumeration is the category listing).
+  - `_category_core`:
+    - `elif category == "grpc-services":` for `name, tgt in cfg.grpc.targets.items()`: `items.append({"name": name, "description": f"gRPC target {name} at {tgt.address} (tls={tgt.use_tls})"})`.
+    - `elif category == "grpc-methods":` for `name, tpl in cfg.grpc.templates.items()`: `items.append({"name": name, "description": (tpl.description or f"{tpl.service}/{tpl.method}")})`.
+  - `_item_core`:
+    - `if category == "grpc-services":` if `name not in cfg.grpc.targets` → `TemplateNotFound(f"Unknown gRPC target: {name}", {"path": f"grpc.targets.{name}"})`; `tgt = cfg.grpc.targets[name]`; return `{"category":"grpc-services","name":name,"description":...,"address":tgt.address,"use_tls":tgt.use_tls,"reflection":tgt.reflection,"example":f"agctl grpc call --target {name} --service <fq> --method <m>"}`.
+    - `if category == "grpc-methods":` if `name not in cfg.grpc.templates` → `TemplateNotFound(f"Unknown gRPC method template: {name}", {"path": f"grpc.templates.{name}"})`; `tpl = cfg.grpc.templates[name]`; resolve the request message schema: build a `GrpcClient(cfg.grpc.targets[tpl.target], descriptors=cfg.grpc.descriptors)`, `md = client.find_method(tpl.service, tpl.method)`, enumerate `md.input_type.fields` → `params = [{"name": f.name, "type": f.type.name, "repeated": f.label == repeated}` ...]; `call_type = client.call_type_of(md)`; return `{"category":"grpc-methods","name":name,"description":tpl.description,"target":tpl.target,"service":tpl.service,"method":tpl.method,"call_type":call_type,"request_fields":params,"example":f"agctl grpc call {name} --param ..."}`. (A target whose reflection is unreachable is reported as `unavailable` in the listing — `_item_core` catches `ConfigError` from `find_method`/`resolve_descriptors` and returns a detail dict with `"unavailable": True, "error": str(err)` rather than failing the whole discover call.)
+  - `_search_core`: loop `cfg.grpc.targets` and `cfg.grpc.templates` matching name/description (lowercased substring); append `{"category":"grpc-services"/"grpc-methods","name":name,"description":...}`.
+- Produces (test seam): `_item_core` constructs `GrpcClient` directly; tests that need protobuf-free behavior monkeypatch `grpc_commands.new_grpc_client` is NOT reachable from discover — so add a module-level seam `new_grpc_client_for_discover = GrpcClient` indirection OR have discover import `from ..commands.grpc_commands import new_grpc_client`. **Decision: discover reuses `grpc_commands.new_grpc_client`** (local import inside `_item_core`); tests monkeypatch `grpc_commands.new_grpc_client` to return a fake whose `find_method`/`call_type_of` return canned descriptors.
+
+- [ ] **Step 1: Write the failing discover tests**
+
+Add to `tests/unit/test_discover_command.py`:
+1. `test_discover_summary_includes_grpc`: `agctl discover --config FIXTURE` → `result.grpc_targets == <count>`, `result.grpc_methods == <template count>`, hint contains `grpc-services` and `grpc-methods`.
+2. `test_discover_category_grpc_services`: `--category grpc-services` → items include `echo` with a description naming the address; `count` matches.
+3. `test_discover_category_grpc_methods`: `--category grpc-methods` → items include `echo-unary`.
+4. `test_discover_item_grpc_methods_schema`: monkeypatch `grpc_commands.new_grpc_client` to a fake whose `find_method` returns a fake method descriptor (input_type with fields `msg`/string and `n`/int) and `call_type_of`→`"unary"`; `discover --category grpc-methods --name echo-unary --config FIXTURE` → `request_fields` lists `msg`/`n` with types, `call_type=="unary"`, `example` starts with `agctl grpc call echo-unary`.
+5. `test_discover_item_grpc_methods_unavailable_isolated`: fake `find_method` raises `ConfigError` (reflection unreachable, no descriptors); `--category grpc-methods --name echo-unary` → exit 0, detail has `"unavailable": True` (discover does not hard-fail).
+6. `test_discover_search_grpc`: `--search echo` → matches include `grpc-services`/`grpc-methods` entries.
+7. `test_discover_unknown_grpc_target_item`: `--category grpc-services --name nope` → exit 2 (`TemplateNotFound` handling).
+
+- [ ] **Step 2: Run to verify they fail**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_discover_command.py -k grpc -q`
+Expected: FAIL — `grpc-services`/`grpc-methods` not valid categories.
+
+- [ ] **Step 3: Add the two categories across the four cores**
+
+Edit `discover_commands.py` per the Produces contract. Local-import `new_grpc_client` inside `_item_core`'s grpc-methods branch.
+
+- [ ] **Step 4: Run discover tests + full unit suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit/test_discover_command.py -q && /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add agctl/commands/discover_commands.py tests/unit/test_discover_command.py && git commit -m "feat(discover): add grpc-services and grpc-methods categories"`
+
+---
+
+### Task 13: Integration tests (in-process grpcio server, self-skipping)
+
+End-to-end confidence against a real grpcio server implementing `echo.proto` + reflection + health. Self-skipping when `grpcio`/server unavailable (mirror the existing `AGCTL_TEST_LIVE` / `AGCTL_TEST_GRPC_ADDR` gating).
+
+**Files:**
+- Create: `tests/integration/test_grpc_commands.py`
+
+**Interfaces:**
+- Consumes: Tasks 4–12 (real client, real commands, real discover). `grpc`, `grpc_reflection`, `grpc_health`, the `echo.proto` service implemented in-process.
+- Produces: an in-process `grpcio` server fixture (start `Echo` servicer + reflection + health under `AGCTL_TEST_LIVE=1`, or point at `AGCTL_TEST_GRPC_ADDR`); E2E through the real `cli`. No fakes.
+
+- [ ] **Step 1: Write the integration tests**
+
+Create `tests/integration/test_grpc_commands.py`. Guard with `pytest.importorskip("grpc")` and a `require_grpc_server` fixture (skip unless `AGCTL_TEST_LIVE=1` or `AGCTL_TEST_GRPC_ADDR` set; mirror `tests/integration/conftest.py`'s `require_*` fixtures). Implement a tiny `Echo` servicer (unary echoes `msg`; server-stream emits N; client-stream concatenates; bidi echoes each) + reflection + health. Each test writes a temp `agctl.yaml` whose `grpc.targets.echo.address` is the server address + `grpc.descriptors` pointing at `tests/fixtures/echo_descriptor.pb` (or relies on reflection):
+1. `test_grpc_unary_call_and_assert`: `grpc call --target echo --service echo.Echo --method Unary --message '{"msg":"hi"}'` → exit 0, `result.message.msg=="hi"`; `--status OK` passes; `--status NOT_FOUND` → exit 1.
+2. `test_grpc_server_stream`: `grpc call --method ServerStream --message '{"msg":"x"}'` → NDJSON with N message lines + summary, exit 0.
+3. `test_grpc_client_stream`: pipe `{"msg":"a"}\n{"msg":"b"}\n` to stdin; `--method ClientStream` → one envelope result.
+4. `test_grpc_bidi`: pipe 2 requests; `--method Bidi` → 2 message lines + summary.
+5. `test_grpc_nonok_status_result`: a servicer method that returns `NOT_FOUND`; call with no assertion flags → exit 0, `result.status.name=="NOT_FOUND"`.
+6. `test_grpc_healthcheck`: `grpc healthcheck --target echo` → `SERVING`.
+7. `test_grpc_discover_methods`: `discover --category grpc-methods --name echo-unary` → `request_fields` populated from the live descriptor.
+8. `test_grpc_reflection_then_descriptor_fallback`: with `reflection: off` + `grpc.descriptors` set to the `.pb`, unary call still works (fallback path).
+
+- [ ] **Step 2: Run the integration tests (live)**
+
+Run: `AGCTL_TEST_LIVE=1 /Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/integration/test_grpc_commands.py -q`
+Expected: PASS (server starts in-process). Without the flag → SKIP.
+
+- [ ] **Step 3: Run the entire suite**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest -q`
+Expected: PASS (integration grpc tests skip without the flag; everything else passes).
+
+- [ ] **Step 4: Commit**
+
+Run: `git add tests/integration/test_grpc_commands.py && git commit -m "test(grpc): in-process grpcio integration tests (unary/stream/health/discover)"`
+
+---
+
+### Task 14: Documentation sync
+
+Sync DESIGN.md, ARCHITECTURE.md, the consumer skill, the sample config, and README to the as-built feature. Per CLAUDE.md, invoke the `docs-watcher` subagent for DESIGN/ARCHITECTURE altitude; make targeted concrete edits (sample config, skill reference, README) directly.
+
+**Files:**
+- Modify: `agctl/data/sample-config.yaml` (add a `grpc:` section mirroring the fixture)
+- Modify: `docs/DESIGN.md`, `docs/ARCHITECTURE.md` (via `docs-watcher` + targeted edits)
+- Modify: `skills/agctl*` (add a `grpc` authoring reference)
+- Modify: `README.md` (surface the `grpc` group + `pip install 'agctl[grpc]'`)
+
+**Interfaces:**
+- Consumes: Tasks 1–13 (as-built behavior).
+- Produces: docs matching as-built.
+
+- [ ] **Step 1: Add a `grpc:` section to the packaged sample config**
+
+In `agctl/data/sample-config.yaml`: add a commented `grpc:` section (one plaintext target with `reflection: auto`, a `descriptors` example, and one template), mirroring the test fixture. This is the `agctl config init` starter.
+
+- [ ] **Step 2: Invoke `docs-watcher` for DESIGN/ARCHITECTURE altitude**
+
+Dispatch the `docs-watcher` subagent (CLAUDE.md "Docs Sync") to reconcile:
+- DESIGN.md: **strike the gRPC row from §10**; add a `grpc` subsection to §3 (`grpc call` template/free-form, the call-type table, `grpc healthcheck`, the stdin/stdout NDJSON model, status-as-result); add `grpc:` to §2.1 (`targets`/`descriptors`/`templates`) and the `grpc` extra to §7/§11; add `grpc.call` / `grpc.healthcheck` shapes to §4.2; add `grpc-services`/`grpc-methods` to the discover categories (§3.8, §4.2).
+- ARCHITECTURE.md: add `grpc_client.py` / `grpc_commands.py` to §3; a grpc request-lifecycle trace to §4; a grpc subsection to §8 (descriptor resolution, JSON↔protobuf, four call types, status-as-result, RpcError mapping); note server-stream/bidi as streaming exceptions in §6 (the 4th/5th after http ping/mock run/logs tail); §10 — note grpc is in-tree with **no new entry-point**; §15 — strike the gRPC deferred note.
+
+- [ ] **Step 3: Update the consumer skill + README**
+
+In the relevant `skills/agctl*` reference: add a `grpc` authoring reference (`grpc:` config section, reflection-first/descriptor-fallback, JSON message authoring, the four call types and the stdin/stdout NDJSON model, status-as-result semantics, the `grpc` extra). In `README.md`: surface the `grpc` group and `pip install 'agctl[grpc]'`.
+
+- [ ] **Step 4: Verify the suite still passes + commit**
+
+Run: `/Users/dmitry/Desktop/CursorProjects/agenttest/.venv/bin/python -m pytest tests/unit -q`
+Expected: PASS (drift-guards, if any, satisfied by the Step-1 sample-config edit).
+
+Run: `git add -A && git commit -m "docs: sync grpc feature — DESIGN/ARCHITECTURE, sample config, skill, README"`
+
+---
+
+## Self-Review (completed)
+
+**1. Code scan:** No method bodies, algorithms, or test code appear. Each step states behavior, exact expected results, signatures, and data shapes (e.g. the `GrpcUnaryResult`/`GrpcStreamMessage` fields, the `RpcError` mapping rules, the `evaluate_grpc_assertions` failure-entry shapes). Dict-literal snippets are data contracts, not implementation.
+
+**2. Self-containment:** Every task lists exact files, Consumes/Produces contracts (signatures, fields, defaults, error cases), and per-test scenarios with expected results. A zero-context implementer can do any task alone — e.g. Task 6's call-method contracts fully define behavior using only Task 5's named `find_method`/`call_type_of` + the DTOs from Task 4.
+
+**3. Spec coverage:** D1 (in-tree) → all tasks (no plugin/entry-point); D2 (reflection+fallback) → Task 5; D3 (JSON↔protobuf) → Task 6; D4 (four call types + NDJSON symmetry) → Tasks 6/9/10; D5 (addressing + `--address`) → Task 9 (`_resolve_target`); D6 (status-as-result) → Tasks 6/8/9; D7 (assertions) → Task 8 (refined: grpc-specific evaluator); D8 (metadata/trailers) → Tasks 6/9; D9 (TLS/plaintext) → Task 4 (`__init__`); D10 (descriptor-driven dynamic stubs) → Tasks 5/6; D11 (packaging) → Task 3; D12 (healthcheck) → Tasks 7/11; D13 (no new entry-point) → Task 3. Spec §6 commands → Tasks 9/10/11; §7 config → Task 1 + §12 validation → Task 2; §8 client contract → Tasks 4–7; §9 descriptor strategy → Task 5; §10 output → Tasks 6/9/10/11; §11 error model → Tasks 4/5/6/7/8/9/10; §13 discovery → Task 12; §14 packaging → Task 3 (+CI); §15 testing → Tasks 4–13; §16/17 docs → Task 14.
+
+**4. Placeholder scan:** No TBD/TODO/"add error handling"/"similar to Task N". Each test step names scenario + expected result; each impl step names behavior. Named cross-task reuse (e.g. Task 10 reuses Task 9's `new_grpc_client`/`_resolve_target`/`_parse_metadata`) restates the relevant contract, not a bare pointer.
+
+**5. Type consistency:** DTO field names (`GrpcStatus.code/name/message`, `GrpcUnaryResult.{target,service,method,call_type,status,message,initial_metadata,trailers}`, `GrpcStreamMessage.{message,trailers}`, `GrpcHealthResult.{target,address,status,note}`) identical across Tasks 4 (definition), 6/7 (client), 9/10/11 (command), 13 (integration). `call_type` token set `"unary"|"server_stream"|"client_stream"|"bidi"` consistent across Tasks 5 (`call_type_of`), 6 (`call_type=` in results), 9/10 (dispatch). `new_grpc_client(target, *, descriptors=None)` consistent across Tasks 9 (definition), 12 (discover reuse + monkeypatch target), 13. `validate_grpc_assertion_args`/`evaluate_grpc_assertions` kwargs (`status, contains, match, jq_path, equals`) consistent across Task 8 (definition) and Task 9 (call). `_resolve_target`/`_parse_metadata` consistent across Tasks 9 (definition) and 10/11 (reuse).
diff --git a/docs/superpowers/specs/active/2026-07-09-grpc-support-design.md b/docs/superpowers/specs/active/2026-07-09-grpc-support-design.md
new file mode 100644
index 0000000..eeb75eb
--- /dev/null
+++ b/docs/superpowers/specs/active/2026-07-09-grpc-support-design.md
@@ -0,0 +1,615 @@
+# Design: `agctl grpc` — gRPC Support as a First-Class Transport
+
+**Status:** Draft v1 — design approved in brainstorming session; pending spec review
+**Date:** 2026-07-09
+**Author:** brainstorming session
+**Affects:** new `agctl/clients/grpc_client.py`, new `agctl/commands/grpc_commands.py`, `agctl/config/models.py` (new `GrpcConfig` / `GrpcTarget` / `GrpcDescriptorSource` / `GrpcTls` / `GrpcTemplate`), `agctl/commands/discover_commands.py` (new `grpc-services` / `grpc-methods` categories), `agctl/cli.py` (new `grpc` group), `agctl/assertions.py` (reuse only), `pyproject.toml` (new `grpc` extra; `grpc` added to the `integration` extra), `skills/agctl*`, DESIGN.md, ARCHITECTURE.md
+**Relation to docs:** Additive — no existing flag, field, exit code, or output shape changes. On implementation, DESIGN.md gains a `grpc` command group + `grpc:` config section + `grpc` extra, the gRPC row is **struck from §10 future work**, and ARCHITECTURE.md gains the `grpc` client/command module, descriptor-resolution + JSON↔protobuf flow, and the streaming-input exception. Synced via `docs-watcher`. No `version` bump (additive under major `2`).
+
+---
+
+## 1. Background & Problem
+
+`agctl` drives four transports today — HTTP, Kafka, DB, Logs — each a thin client behind a
+one-JSON-envelope command group, with heavy libraries as optional extras. gRPC is the
+conspicuous gap: it is listed explicitly in **DESIGN §10** (*"First-class `agctl grpc call`
+command via a plugin. The plugin protocol is designed; implementation is deferred."*), and
+**§9.3's `Plugin` Protocol** names gRPC/GraphQL/WebSocket as its targets.
+
+gRPC differs from the existing transports in three load-bearing ways, each of which shapes
+this design:
+
+1. **It needs a schema to serialize.** Protobuf is binary; an agent speaks JSON. `agctl`
+   must learn the service/message/method definitions — from **server reflection** (zero
+   config, dynamic) or from **supplied descriptors** (`.proto` / compiled
+   `FileDescriptorSet`) — and convert JSON↔protobuf on every call.
+2. **It has four call types**, not one: unary, server-streaming, client-streaming,
+   bidi-streaming. The one-envelope-per-invocation model has only three streaming
+   exceptions today (`http ping`, `mock run`, `logs tail`) — all *output* streams.
+   Client-streaming/bidi additionally need a **request-stream input**, which a stateless
+   CLI can only take from stdin.
+3. **Its status model is not HTTP's.** gRPC has its own status codes (0–16) and
+   metadata/trailers. A non-OK status must be a *result* (`ok:true`, exit 0) unless an
+   assertion says otherwise — the exact principle already established for HTTP 4xx/5xx.
+
+The design delivers gRPC as a **fifth in-tree transport**, structurally identical to
+http/kafka/db/logs: a lazy-imported client under a new `grpc` extra, a `grpc:` config
+section, a `grpc` command group, assertion reuse, and discovery integration. gRPC is
+**not** delivered as a third-party plugin package (D1) — the `Plugin` Protocol of §9.3
+remains the seam for *future* protocols; gRPC ships in-tree because every existing
+transport does and the feature branch lives in this repository.
+
+> **Scope honesty (load-bearing).** v1 covers **all four call types** and
+> **reflection-first with descriptor fallback** (both chosen in brainstorming). The
+> descriptor strategy (§9) is the gRPC-specific core: it is the only thing that makes
+> "an agent writes JSON, protobuf goes on the wire" possible without per-service codegen.
+
+## 2. Goals
+
+- Let an agent **call any gRPC method** (template or free-form) and assert on the response
+  with the same exit-code discipline as `http call` / `db assert`, including non-OK status
+  as a result, not an error.
+- Support **all four call types**, using **NDJSON on stdout** for server-streaming/bidi
+  output (the established streaming-exception model) and **NDJSON on stdin** for
+  client-streaming/bidi request input — closing a bidirectional symmetry.
+- Resolve proto definitions **reflection-first, descriptor-fallback** so a dev server with
+  reflection needs zero config, while a locked-down server with reflection disabled works
+  from supplied `.proto` files or a compiled descriptor set.
+- Serialize **JSON↔protobuf** transparently: the agent writes/reads JSON; `agctl` builds
+  message classes from descriptors (no generated `_pb2` modules required).
+- **Reuse** the existing jq assertion engine (`jq_bool` / `compile_jq` / `json_subset` /
+  `parse_equals` / `type_aware_equal`), the `@envelope` discipline, and the streaming
+  precedents. Add no new assertion engine and no new error types.
+- **Fail loud on authoring bugs, soft on data variance** — a malformed `--match` is a
+  `ConfigError` (exit 2) via up-front `compile_jq`; a reflection miss with no fallback
+  descriptors is a `ConfigError`; a data-dependent jq eval error is a soft non-match.
+- Preserve every existing behavior: no command, flag, field, exit code, or output shape
+  changes elsewhere.
+
+## 3. Scope & Design Constraints
+
+- **Additive only.** A new `grpc` command group, a new `grpc:` config section, two new
+  discover categories, and a new extra. Nothing existing changes.
+- **In-tree transport, not a plugin.** Ships in the core package under the `grpc` extra,
+  like http/kafka/db/logs. No new entry-point group and no new `Protocol` (D1, D13).
+- **Reflection-first.** When `reflection: auto` (default) or `on`, `GrpcClient` queries the
+  server's reflection service for services + file descriptor protos and builds a
+  `descriptor_pool`. When `off`, or when reflection is unavailable (`UNIMPLEMENTED`), it
+  falls back to config-supplied descriptors. A reflection failure with **no** fallback
+  configured is a `ConfigError` (exit 2).
+- **JSON in, JSON out for messages.** Request messages are authored as JSON (`--message`
+  or template `message`); `ParseDict` serializes them to protobuf via the resolved
+  descriptor. Responses are decoded via `MessageToDict`. The agent never touches bytes.
+- **Call type is auto-detected from the descriptor.** `MethodDescriptor` carries
+  `client_streaming` / `server_streaming` flags; unary = neither, server-stream =
+  server-streaming, client-stream = client-streaming, bidi = both. No `--streaming` flag.
+- **Streaming mirrors the established exceptions.** Server-streaming/bidi emit one JSON
+  object per response message (NDJSON) + a final `summary`; signal-driven stop via a
+  `threading.Event`; manual startup-error envelopes for pre-stream failures. Client-stream
+  is the one-result case (a single trailing response → a normal envelope).
+- **Request-stream input is stdin NDJSON** for client-streaming/bidi (D4): one JSON object
+  per line, EOF ends the stream. `--message`/template `message` is only valid for the
+  single-request types (unary, server-stream); providing the wrong input for a call type is
+  a `ConfigError` (exit 2).
+- **Reuse the lazy jq import.** jq is loaded only when `--match` / `--jq-path` is used; a
+  missing library surfaces as `ConfigError` (exit 2) with an install hint. The `grpc` extra
+  bundles `jq` (like `db` / `kafka`).
+- **`@envelope` discipline preserved** for `grpc call` unary + client-stream + `grpc
+  healthcheck`. Server-streaming/bidi are the streaming exceptions.
+
+## 4. Non-Goals
+
+- **A gRPC mock server** (a `mocks.grpc` analog to `mocks.http`/`mocks.kafka`). The mock
+  engine is HTTP+Kafka today; a gRPC mock is a separate, larger effort and is deferred
+  (§15).
+- **A third-party plugin package (`agctl-grpc`).** gRPC ships in-tree (D1). The `Plugin`
+  Protocol (§9.3) is the seam if a *different* protocol later wants out-of-tree delivery.
+- **Schema Registry / Protobuf-on-Kafka decoding.** Unrelated to the gRPC transport; that
+  is the separate Kafka §10 item.
+- **Cross-message ordering assertions** on streams ("messages arrive in this order") in v1.
+  Per-message `--match` + `--expect-count` cover v1; ordering is deferred.
+- **gRPC compression, retry policy / service-config, interceptors, OpenTelemetry
+  propagation, OAuth call-credentials beyond static metadata.** Deferred (§15).
+- **Reflection protocol v1 vs v1alpha selection as a config knob.** v1 prefers the modern
+  reflection API and falls back as needed; the selection is not user-facing in v1.
+- **Named gRPC "patterns"** (a `grpc.patterns` analog to `kafka.patterns`). Templates
+  (`grpc.templates`) cover the named-call case; a patterns layer is YAGNI.
+- **`--capture` response extraction.** Agents still hand-roll `jq -r` for the next
+  command; deferred (same call as the http-jq / logs specs).
+- **`--match-all` / regex status matching.** Deferred.
+
+## 5. Decisions (recorded with rationale)
+
+| # | Decision | Rationale |
+|---|---|---|
+| D1 | **In-tree first-class `grpc` group under a new `grpc` extra**, mirroring http/kafka/db/logs. Not a plugin package. | The feature branch lives in this repo and every sibling transport is in-tree. DESIGN §10's "via a plugin" describes the *extension mechanism* (§9.3 `Plugin` Protocol), not a delivery mandate; that Protocol remains the seam for *future* protocols. In-tree keeps gCTL's transport symmetry and lets discovery/config/assertions integrate like the others. |
+| D2 | **Reflection-first descriptor resolution with descriptor fallback** (`reflection: auto` default). | Zero config for dev servers that enable reflection (the common case); descriptors cover locked-down prod servers that disable it. User-chosen in brainstorming. A reflection miss with no fallback → loud `ConfigError`, never a silent failure. |
+| D3 | **JSON in / JSON out for messages; `agctl` serializes via descriptors.** Request = `ParseDict`, response = `MessageToDict`, message classes from `message_factory.GetMessageClass` over the resolved pool. | The agent speaks JSON; protobuf is binary. Forcing the agent to emit bytes is a non-starter. Descriptors are sufficient — no generated `_pb2` modules required, so any service in the descriptors is callable without codegen. |
+| D4 | **All four call types; client-stream/bidi consume NDJSON on stdin, server-stream/bidi emit NDJSON on stdout.** Call type is auto-detected from the method descriptor. | User-chosen scope. The established streaming exceptions are all *output* NDJSON; stdin NDJSON closes the symmetry and is the only unbounded, quote-free way for a stateless CLI to supply a request stream. Client-stream is the one-result case (single trailing response → normal envelope). |
+| D5 | **Method addressing is `package.Service/Method`** (the `grpcurl` convention), with template mode (`grpc call <name>`) and free-form mode (`--target/--service/--method`), plus `--address host:port` for no-config calls (the gRPC analog of `http request --url`). | Mirrors the `http call`/`http request` split exactly. `--address` removes the need to register a target for one-off endpoints (external APIs, ephemeral ports). |
+| D6 | **A non-OK gRPC status is a result, not an error.** `ok:true`, exit `0`, status captured in `result.status` (`{code, name, message}`) + trailers — unless an assertion flag is active. | Direct mirror of the HTTP principle "4xx/5xx is a result, not an assertion" (ARCHITECTURE §8). gRPC status is an outcome the agent asserts on, not a tool failure. Only `--status`/`--contains`/`--match`/`--jq-path` mismatch → `AssertionFailure` (exit 1). |
+| D7 | **Unary assertions reuse the existing suite unchanged.** `--status <gRPC code name or number>`, `--contains` (`json_subset`, message-rooted), `--match` (jq over the **response envelope** `{status, message, initial_metadata, trailers}`, dialect-"2"-style), `--jq-path`+`--equals` (message-rooted, `parse_equals`+`type_aware_equal`). Streaming uses `--match` (per-message, message-rooted) + `--expect-count`, like `kafka consume`. | No new assertion engine. `--match` envelope-rooted matches HTTP's dialect-"2" root choice, so `.message.x` / `.status.name` read naturally. Up-front `compile_jq` makes a typo a loud `ConfigError` (the http-jq D5 / logs D7 precedent). |
+| D8 | **gRPC metadata via `--metadata key=value` (repeatable, caller wins) and template `metadata`; initial metadata sent, **trailers** captured in the result.** | The gRPC analog of `--header`. Per-call merge mirrors `http` header merge (case rules are gRPC's: metadata keys are lowercase on the wire). |
+| D9 | **TLS/plaintext per target: `use_tls` (default `false` → plaintext h2c) + optional `tls` block** (`ca_location`/`certificate_location`/`key_location`/`override_authority`) mirroring `kafka.ssl` semantics, including the empty-string-counts-as-unset rule. | Plaintext is the dev norm for gRPC; TLS must be opt-in and explicit (never a silent downgrade). Mirroring `kafka.ssl` reuses a reviewed, unit-tested contract. |
+| D10 | **Descriptor-driven dynamic stubs; no generated `_pb2`.** Reflection stubs ship with `grpcio`; `.proto` fallback compiles via `grpc_tools.protoc` into a `FileDescriptorSet`; a pre-compiled `descriptor_set` blob is also accepted. All feed one `descriptor_pool`. | One code path for reflection and descriptors. Codegen coupling (generated modules on the import path) is rejected (§16) — it pins `agctl` to a specific `protoc` run and breaks the "any service in the descriptors" property. |
+| D11 | **New `grpc` extra bundles `grpcio`, `grpcio-tools`, `protobuf`, `jq`.** `grpcio`/`grpc_tools`/`google.protobuf` lazy-imported inside `GrpcClient`; missing → `ConfigError` pointing at `pip install 'agctl[grpc]'`. jq lazy-imported only for `--match`/`--jq-path` (like db/kafka). | Mirrors the optional-extras model (ARCHITECTURE §11). `grpcio-tools` is needed only for the `.proto` fallback compile, but bundling it keeps the extra self-contained; the lazy import means a reflection-only call still loads fast. |
+| D12 | **Optional `grpc healthcheck` via `grpc.health.v1`.** `--target`/`--service`/`--all`; the gRPC analog of `check ready`. | Standard gRPC health-checking is ubiquitous and gives agents a readiness primitive for gRPC services that `check ready` (HTTP-based) cannot reach. Small, additive, easy to cut. |
+| D13 | **No new entry-point group and no new `Protocol`.** gRPC is a single transport, not a backend family. | Unlike `db_drivers`/`logs_backends` (which select among backends by `type`), gRPC has one wire protocol. A `grpc_backends` seam would be speculative; if a *different* protocol wants out-of-tree delivery later, §9.3 `Plugin` is the seam, not a new group. (See §16.) |
+
+## 6. Command Contract — `grpc call` / `grpc healthcheck`
+
+A new `grpc` Click group is wired in `cli.py` (group + `add_command` per the existing
+two-step registration). Subcommands follow the core/envelope split
+(`_x_core` → `_x_envelope = envelope("grpc.x")(...)`) except server-streaming/bidi
+`call`, which are streaming exceptions. Commands obtain their client via the
+`new_grpc_client(target)` factory (the test seam).
+
+### 6.1 `agctl grpc call` — template and free-form
+
+Two mutually-exclusive invocation modes, mirroring `http call` / `http request`:
+
+```
+agctl grpc call <template-name>            # template mode
+    [--param key=value]      # repeatable; fills {placeholders} in message + metadata
+    [--message '{...}']      # deep-merged into the template message (analog of http --body)
+    [--metadata key=value]   # repeatable; merged with template metadata, caller wins
+    [--timeout <seconds>]
+
+agctl grpc call                            # free-form mode
+    --target <name>         # a grpc.targets key; OR --address for no-config
+    [--address host:port]   # full target; no registration needed (analog of http --url)
+    --service <fq-service>  # e.g. order.v1.OrderService
+    --method <method>       # e.g. CreateOrder
+    [--message '{...}']     # required for single-request types unless the method has an empty request
+    [--metadata key=value]  # repeatable
+    [--timeout <seconds>]
+
+# unary response assertions (single-request types only; ≥1 flag ⇒ assertion mode; AND together):
+    [--status <code>]       # gRPC status: name (OK|NOT_FOUND|PERMISSION_DENIED|...) or number (0..16)
+    [--contains '{...}']    # JSON subset of the response message
+    [--match <jq>]          # jq predicate over the response ENVELOPE
+                             #   {status:{code,name,message}, message, initial_metadata, trailers}
+                             #   → .message.x, .status.name, .trailers.x
+    [--jq-path <jq>]        # jq path into the response message (paired with --equals)
+    [--equals <value>]      # expected value (JSON-parsed when valid; strict, type-aware compare)
+
+# streaming (server-stream / bidi) per-message controls:
+    [--match <jq>]           # per-message jq predicate over the response MESSAGE (message-rooted)
+    [--expect-count <n>]     # exit 1 (AssertionFailure) if fewer than n messages in the stream
+```
+
+**Mode/exclusivity rules (all `ConfigError`, exit 2, pre-call):**
+
+- `<template-name>` is mutually exclusive with `--target`/`--address`/`--service`/`--method`.
+- `--target` and `--address` are mutually exclusive; exactly one target source is required
+  in free-form mode.
+- `--service` and `--method` are required in free-form mode (inferred from the template in
+  template mode).
+- Unary assertion flags (`--status`/`--contains`/`--jq-path`/`--equals`) are rejected on
+  streaming call types (server-stream/bidi) — those use `--match`/`--expect-count`. `--match`
+  is valid on both, but its root differs (envelope on unary, message on stream).
+
+### 6.2 Call-type behavior (auto-detected from the descriptor)
+
+| Call type | Request input | Output | Command tag |
+|---|---|---|---|
+| **unary** | `--message` / template `message` | one envelope (`grpc.call`) | `grpc.call` |
+| **server-streaming** | `--message` / template `message` | NDJSON: one `event:"message"` per response + `summary` | `grpc.call` (streaming) |
+| **client-streaming** | **stdin NDJSON** (one request message per line; EOF ends) | one envelope carrying the single trailing response | `grpc.call` |
+| **bidi-streaming** | **stdin NDJSON** | NDJSON: one `event:"message"` per response + `summary` | `grpc.call` (streaming) |
+
+- `--message`/template `message` is **invalid** for client-streaming/bidi (requests come
+  from stdin); stdin NDJSON is **invalid** for unary/server-streaming (single request from
+  `--message`). Mismatch → `ConfigError` (exit 2).
+- For bidi, stdin-EOF closes the request half; the call drains remaining responses, then
+  emits the `summary` and exits.
+- `--timeout` sets the gRPC call **deadline** (covers the whole call, including stream
+  drain). Deadline exceeded → `OperationTimeout` (exit 1).
+
+### 6.3 `agctl grpc healthcheck` — readiness via `grpc.health.v1`
+
+```
+agctl grpc healthcheck
+    [--target <name>]        # a grpc.targets key (omit with --all)
+    [--service <fq-service>] # health is per-service in v1; omit → overall ("" service)
+    [--all]                  # check every configured target (default when neither --target nor --all)
+    [--timeout <seconds>]
+```
+
+Result (`grpc.healthcheck`): per-target `{target, address, status}` where `status` is one of
+`SERVING` / `NOT_SERVING` / `UNKNOWN` (the health-v1 enum), plus `all_serving: bool`. A
+target whose health service is `UNIMPLEMENTED` reports `status: "UNKNOWN"` and a note, not a
+hard error (mirrors `check ready` not-erroring on a missing health path).
+
+## 7. Config Schema — `grpc`
+
+New pydantic models in `agctl/config/models.py`; a new `grpc` field on `Config`. `${ENV}`
+interpolation, overlays, and `AGCTL_GRPC__*` env overrides apply automatically via the
+existing pipeline (no new loader code). The resolver denylist (§5 of DESIGN) is unaffected.
+
+### 7.1 Config contract (YAML)
+
+```yaml
+grpc:
+  targets:                            # named gRPC endpoints (analog of `services`)
+    order-service:
+      address: "${ORDER_GRPC_ADDR}"   # host:port, e.g. localhost:50051
+      use_tls: false                  # plaintext h2c (default); true → TLS
+      tls:                            # optional; mirrors kafka.ssl (empty string = unset)
+        ca_location: "${GRPC_CA:-}"
+        certificate_location: "${GRPC_CERT:-}"
+        key_location: "${GRPC_KEY:-}"
+        override_authority: "${GRPC_AUTHORITY:-}"
+      reflection: auto                # auto (default) | on | off
+    payment-service:
+      address: "${PAYMENT_GRPC_ADDR}"
+      use_tls: true
+      reflection: auto
+
+  descriptors:                        # FALLBACK when reflection is off / unavailable
+    - proto: "protos/order/v1/*.proto"        # glob; compiled at load via grpc_tools.protoc
+      include_paths: ["protos"]
+    # OR a pre-compiled descriptor set (no protoc at load):
+    # - descriptor_set: "protos/compiled/order.pb"
+
+  templates:                          # named gRPC calls (analog of `templates`)
+    create-order:
+      description: "Create an order via gRPC"
+      target: order-service           # must match a grpc.targets key
+      service: order.v1.OrderService  # fully-qualified proto service
+      method: CreateOrder
+      metadata:                       # initial metadata (analog of `headers`)
+        authorization: "Bearer ${ORDER_TOKEN}"
+      message:                        # request message as JSON (proto-typed via descriptor)
+        customer_id: "{customer_id}"
+        items:
+          - sku: "{sku}"
+            quantity: 1
+```
+
+### 7.2 Pydantic model shape
+
+| Model | Fields |
+|---|---|
+| `GrpcTls` | `ca_location: str \| None = None`, `certificate_location: str \| None = None`, `key_location: str \| None = None`, `override_authority: str \| None = None` |
+| `GrpcTarget` | `address: str`, `use_tls: bool = False`, `tls: GrpcTls \| None = None`, `reflection: Literal["auto","on","off"] = "auto"` |
+| `GrpcDescriptorSource` | exactly one of `proto: str \| None` (+ `include_paths: list[str] = []`) **or** `descriptor_set: str \| None` |
+| `GrpcTemplate` | `description: str \| None`, `target: str`, `service: str`, `method: str`, `metadata: dict[str,str] = {}`, `message: dict \| None = None` |
+| `GrpcConfig` | `targets: dict[str, GrpcTarget] = {}`, `descriptors: list[GrpcDescriptorSource] = []`, `templates: dict[str, GrpcTemplate] = {}` |
+| `Config` | gains `grpc: GrpcConfig = Field(default_factory=GrpcConfig)` |
+
+`GrpcDescriptorSource` uses a pydantic **model_validator** to enforce "exactly one of
+`proto` / `descriptor_set`" (a structurally-bad source is a `ConfigError` at load).
+
+## 8. Client Contract — `GrpcClient`
+
+The client owns descriptor resolution + JSON↔protobuf + the four call types. Method
+**signatures and DTOs only** here — no bodies (implementation is the plan's job).
+
+### 8.1 `GrpcClient` (`agctl/clients/grpc_client.py`)
+
+| Method / member | Purpose |
+|---|---|
+| `__init__(self, target: GrpcTarget, *, channel=None, descriptor_pool=None)` | lazy-imports `grpcio`; constructs a channel (or accepts an injected `channel` test seam). Holds the resolved `descriptor_pool`. |
+| `resolve_descriptors(self) -> DescriptorPool` | reflection (if enabled/available) → pool; else config descriptors → pool. Reflection `UNIMPLEMENTED` + no descriptors → `ConfigError`. (D2, D10) |
+| `find_method(self, service: str, method: str) -> MethodDescriptor` | locate the method; unknown service/method → `TemplateNotFound`. Exposes `client_streaming`/`server_streaming` for call-type detection. |
+| `call_unary(self, service, method, message_json, *, metadata, timeout) -> GrpcUnaryResult` | single request → single response; status/trailers captured. (D3, D6) |
+| `call_server_stream(self, service, method, message_json, *, metadata, timeout) -> Iterator[GrpcStreamMessage]` | single request → stream of responses. |
+| `call_client_stream(self, request_json_iter, *, service, method, metadata, timeout) -> GrpcUnaryResult` | stream of requests (from stdin) → single trailing response. |
+| `call_bidi(self, request_json_iter, *, service, method, metadata, timeout) -> Iterator[GrpcStreamMessage]` | stream of requests → stream of responses. |
+| `healthcheck(self, service_name: str = "") -> GrpcHealthResult` | `grpc.health.v1.Health/Check`. (D12) |
+
+The heavy libraries (`grpc`, `grpc_tools`, `google.protobuf`) are imported inside
+`__init__`/methods — importing the module never requires the `grpc` extra (the lazy-import
+convention, ARCHITECTURE §8).
+
+### 8.2 DTOs (contracts)
+
+**`GrpcStatus`** — `{code: int, name: str, message: str}`. `name` is the canonical gRPC
+status string (`OK`, `NOT_FOUND`, …); `code` is the numeric status. Populated for **every**
+call outcome, OK or not (D6).
+
+**`GrpcUnaryResult`** — `{target, service, method, call_type, status: GrpcStatus,
+message: dict | null, initial_metadata: dict, trailers: dict}`. `message` is the decoded
+response (`null` for an empty response). Backs the `grpc.call` envelope result (§10.1) and
+the client-streaming single response. `call_type` is a stable token — one of
+`"unary" | "server_stream" | "client_stream" | "bidi"` (derived from the method
+descriptor's `client_streaming`/`server_streaming` flags) — used consistently in the
+envelope result, the streaming `summary`, and discovery (§13).
+
+**`GrpcStreamMessage`** — `{message: dict, trailers: dict | null}`. One per streamed
+response; `trailers` is present only on the final message of a stream (gRPC delivers
+trailers at stream end). Backs each NDJSON `event:"message"` line.
+
+**`GrpcHealthResult`** — `{target, address, status: str}` (`SERVING`/`NOT_SERVING`/`UNKNOWN`).
+
+### 8.3 Request serialization
+
+For single-request types, the resolved `message_json` (`--message` deep-merged into the
+template `message`, `{placeholder}`-filled from `--param`) is passed to
+`ParseDict(json, message_instance, ignore_unknown_fields=False)` over the method's input
+message class. **Unknown fields / type mismatches raise `ConfigError` (exit 2)** pre-call —
+an agent-authored request that does not match the proto schema fails loudly, never produces
+a malformed message on the wire. For client-stream/bidi, each stdin NDJSON line is parsed
+the same way.
+
+## 9. Descriptor Strategy & JSON↔protobuf (the gRPC-specific core)
+
+1. **Reflection** (`reflection: auto`/`on`): open the channel, call the server reflection
+   service, enumerate services, fetch file descriptor protos, build a
+   `descriptor_pool.DescriptorPool`. Reflection stubs ship with `grpcio`.
+2. **Descriptor fallback** (`reflection: off`, or reflection returns `UNIMPLEMENTED` with
+   `reflection: auto`): load from config — either compile `proto` globs via
+   `grpc_tools.protoc` into a `FileDescriptorSet`, or load a pre-compiled `descriptor_set`
+   blob. Either way the result feeds the same `descriptor_pool`.
+3. **Message classes** from the pool via `message_factory.GetMessageClass(message_desc)`
+   — no generated `_pb2` modules. **Stubs are built dynamically** from the channel + the
+   resolved service/method descriptors, so any service/method in the pool is callable.
+4. **JSON→protobuf** via `google.protobuf.json_format.ParseDict`; **protobuf→JSON** via
+   `MessageToDict` (preserving field names as authored in the proto, camelCase-default per
+   `json_format`, configurable).
+
+Descriptor resolution is **per-invocation and stateless** (like config load) — no on-disk
+cache, no shared pool across invocations. Reflection/descriptor load failure surfaces as the
+error model in §11.
+
+## 10. Output Contract
+
+### 10.1 `grpc.call` — one-result cases (unary + client-streaming)
+
+```json
+{
+  "ok": true,
+  "command": "grpc.call",
+  "result": {
+    "target": "order-service",
+    "service": "order.v1.OrderService",
+    "method": "CreateOrder",
+    "call_type": "unary",
+    "status": { "code": 0, "name": "OK", "message": "" },
+    "message": { "order_id": "ord-789", "status": "PENDING" },
+    "initial_metadata": { "content-type": "application/grpc" },
+    "trailers": {}
+  },
+  "duration_ms": 87
+}
+```
+
+A non-OK status still yields `ok:true` / exit `0` (D6); an assertion mismatch yields
+`ok:false` with `error.detail = {response, failures}` (the `http call` shape — full response
+in `detail.response`, each failing mode listed with a `root` label + payload snapshot).
+
+### 10.2 `grpc.call` — streaming cases (server-stream / bidi): NDJSON
+
+One JSON object per response message:
+
+```json
+{"event":"message","message":{"orderId":"ord-789"},"trailers":null}
+{"event":"message","message":{"orderId":"ord-790"},"trailers":null}
+{"summary":true,"messages":2,"matched":2,"status":{"code":0,"name":"OK","message":""},"duration_ms":1204}
+```
+
+- The `summary` line carries `messages` (total), `matched` (after `--match`), and the final
+  `status`. `--expect-count` failure (exit 1) is reflected in a `summary` with `matched <
+  expect_count` plus an `AssertionFailure` exit code (the streaming-exception pattern: the
+  verdict rides on the summary + exit code).
+- Pre-stream startup failures (unknown target/service/method, reflection miss + no
+  descriptors, bad `--match`, mutex violations, wrong input for call type, missing extra)
+  emit a single structured error envelope **before** any message line (the `http ping` /
+  `logs tail` precedent), then exit `2`.
+
+### 10.3 `grpc.healthcheck`
+
+```json
+{
+  "ok": true,
+  "command": "grpc.healthcheck",
+  "result": {
+    "targets": {
+      "order-service": { "address": "localhost:50051", "status": "SERVING" },
+      "payment-service": { "address": "localhost:50052", "status": "UNKNOWN",
+                           "note": "health service UNIMPLEMENTED" }
+    },
+    "all_serving": false
+  },
+  "duration_ms": 41
+}
+```
+
+## 11. Error & Exit-Code Model
+
+No new error types; the existing `AgctlError` hierarchy covers every path.
+
+| Failure | Type | Exit | When |
+|---|---|---|---|
+| Missing `grpc` extra (`grpcio`/`grpc_tools`/`protobuf`) | `ConfigError` | 2 | `GrpcClient` construction → `pip install 'agctl[grpc]'` |
+| Unknown `--target` (no key under `grpc.targets`) in free-form mode | `ConfigError` | 2 | command entry |
+| Unknown `--service` / `--method` after descriptor resolution | `TemplateNotFound` | 2 | `find_method` |
+| Reflection miss (`UNIMPLEMENTED`/`off`) with no `grpc.descriptors` | `ConfigError` | 2 | `resolve_descriptors` (points at `grpc.descriptors`) |
+| Bad/missing `.proto` or `descriptor_set` path; protoc compile error | `ConfigError` | 2 | descriptor load |
+| Structurally-bad `grpc.descriptors` entry (neither/both of `proto`/`descriptor_set`) | `ConfigError` | 2 | pydantic `model_validator` at config load |
+| Request JSON fails `ParseDict` (unknown field / type mismatch) | `ConfigError` | 2 | pre-call serialization |
+| Wrong input for call type (`--message` on client-stream/bidi; stdin on unary/server-stream) | `ConfigError` | 2 | command entry |
+| Mode/exclusivity violation (template + free-form flags; `--target`+`--address`; unary-assertion flags on a stream) | `ConfigError` | 2 | command entry |
+| Malformed `--match` (compile error, post-placeholder-fill) | `ConfigError` | 2 | up-front `compile_jq` |
+| `--match` / `--jq-path` used and `jq` extra missing | `ConfigError` | 2 | lazy `_jq` → `pip install 'agctl[grpc]'` (jq bundled in the extra) |
+| `--jq-path` without `--equals` (or vice versa) | `ConfigError` | 2 | pre-call arg check |
+| Channel connect failure / transport error | `ConnectionFailure` | 2 | call |
+| Deadline exceeded (`--timeout`) | `OperationTimeout` | 1 | call |
+| Unary assertion mismatch (`--status`/`--contains`/`--match`/`--jq-path`/`--equals`) | `AssertionFailure` | 1 | post-call |
+| Stream `--expect-count` not met | `AssertionFailure` | 1 | stream end (summary + exit 1) |
+| `--match` jq eval error at runtime | (soft non-match) | — | `jq_bool` swallows to `False` |
+| Non-OK gRPC status with **no** assertion flags | *(not an error)* | 0 | `ok:true`, status in `result.status` (D6) |
+
+Exit-code contract unchanged: `0` ok / `1` assertion / `2` config-or-env.
+
+## 12. Validation Rules (`agctl/config/validator.py`)
+
+Additive cross-reference checks during `agctl config validate` (mirroring how `mocks` and
+`database` refs are validated today):
+
+- A `grpc.templates.<name>.target` that is not a key under `grpc.targets` → **error**.
+- A `grpc.descriptors` entry that is structurally invalid (neither/both of
+  `proto`/`descriptor_set`) → **error** (also enforced by the pydantic validator at load).
+- A `grpc.templates.<name>` / `grpc.targets.<name>` missing `description` → **warning**
+  (discovery degrades; the existing missing-description rule).
+- `grpc.descriptors[].proto` / `descriptor_set` paths are **not** existence-checked at
+  config-validate time (a config may be validated in CI without the proto tree present) —
+  a missing path surfaces as `ConfigError` at descriptor load (command time), consistent
+  with how `logs.sources.<name>.path` is handled.
+
+Service/method existence and `ParseDict`-ability are **not** validated at config time
+(they require the live server / descriptor resolution); they surface at command time per §11.
+
+## 13. Discovery Changes — `grpc-services` / `grpc-methods` categories
+
+Additive, following the existing three-level + `--search` protocol. Categories are populated
+from the **resolved descriptors** (reflection or config), so discovery may require a live
+reflection call for a `reflection: auto/on` target (a target with `reflection: off` and no
+descriptors contributes nothing and is skipped with a warning).
+
+- Add `"grpc-services"` and `"grpc-methods"` to `_VALID_CATEGORIES`; update `_SUMMARY_HINT`;
+  add `grpc_targets` / `grpc_services` / `grpc_methods` counts to `_summary_core`.
+- **Level 1 `--category grpc-services`** → `{name, target, address, methods_count}`.
+- **Level 1 `--category grpc-methods`** → `{service, method, call_type}` (`unary` /
+  `server_stream` / `client_stream` / `bidi`).
+- **Level 2 `--category grpc-methods --name "<service>/<method>"`** → request message field
+  schema (`{name, type, repeated}`, derived from the input message descriptor), `call_type`,
+  required params, and an `example` command (`agctl grpc call --target <t> --service <s>
+  --method <m> --message '{...}'`).
+- `--search` covers gRPC service/method names + template descriptions.
+
+Discovery failure isolation: a single target whose reflection is unreachable does not fail
+the whole `discover` call — it is reported as `unavailable` in the listing (the
+self-skipping ethos of the integration suite, applied to discovery).
+
+## 14. Packaging
+
+- **New `grpc` extra** in `pyproject.toml`:
+  `grpc = ["grpcio>=1.62", "grpcio-tools>=1.62", "protobuf>=4.25", "jq>=1.6"]` under
+  `[project.optional-dependencies]`. (jq bundled because `--match`/`--jq-path` need it; the
+  db/kafka precedent.)
+- **`integration` extra** gains `grpc`: `integration = ["testcontainers",
+  "agctl[db,kafka,http,grpc]", "pytest>=8.0"]`.
+- **No new entry-point group** (D13). No new console script.
+- **New `grpc` command group** wired in `cli.py`. No `version` bump (additive under major
+  `2`).
+
+## 15. Testing Strategy
+
+Mirrors the existing test architecture and seams (CliRunner + `new_grpc_client`
+monkeypatch / injected `channel` / `descriptor_pool`; integration tests self-skip). A
+bundled tiny `.proto` (e.g. an `Echo` service with unary/server-stream/client-stream/bidi
+methods) ships under `tests/fixtures/` and is compiled into a descriptor set at collection
+time for unit tests — no live server needed for the descriptor/serialization/streaming logic.
+
+**Unit (no network, no `grpcio` required due to lazy import):**
+
+- `GrpcClient` descriptor resolution: reflection path against an injected fake reflection
+  stub; descriptor fallback against the bundled descriptor set; reflection `UNIMPLEMENTED`
+  + no descriptors → `ConfigError`.
+- JSON↔protobuf: `ParseDict` happy path; unknown field / type mismatch → `ConfigError`;
+  `MessageToDict` round-trip; call-type auto-detection from a method descriptor.
+- `grpc call` unary: template + free-form modes; mode/exclusivity violations → `ConfigError`;
+  wrong-input-for-call-type → `ConfigError`; assertion suite (`--status` name+number,
+  `--contains`, envelope-rooted `--match`, `--jq-path`+`--equals`) pass/fail; non-OK status
+  as result (exit 0) vs assertion mismatch (exit 1); missing extra / missing jq →
+  `ConfigError`.
+- `grpc call` streaming: server-stream NDJSON shape + `summary`; bidi NDJSON in (stdin)
+  → out; client-stream stdin → single envelope; `--match` per-message + `--expect-count`
+  pass/fail; call-type mismatch → `ConfigError`; startup-error envelope before any message.
+- `grpc healthcheck`: per-target `SERVING`/`NOT_SERVING`/`UNKNOWN`; `--all`; `UNIMPLEMENTED`
+  → `UNKNOWN` (not an error).
+- `discover`: `grpc-services`/`grpc-methods` in summary + hint; category listing; method
+  detail with field schema + `example`; search hit; unavailable-target isolation.
+- `config/validator`: template→target ref errors; missing-description warnings.
+
+**Integration (self-skipping, gated like the others):** an in-process `grpcio` server
+fixture implementing the bundled `Echo` service + reflection + health, started under
+`AGCTL_TEST_LIVE=1` or pointed at via `AGCTL_TEST_GRPC_ADDR`. Exercises all four call types,
+TLS (self-signed), healthcheck, and discovery end-to-end through the Click CLI (no
+monkeypatch).
+
+New files: `tests/fixtures/echo.proto` (+ compiled descriptor), `tests/unit/test_grpc_client.py`,
+`tests/unit/test_grpc_commands.py`, `tests/unit/test_grpc_discover.py`, and
+`tests/integration/test_grpc_commands.py`.
+
+## 16. Rejected Alternatives (ADR-style)
+
+- **Separate plugin package (`agctl-grpc`) via §9.3 `Plugin`** (the letter of DESIGN §10).
+  Rejected (D1): the branch is in-tree and every sibling transport is in-tree; in-tree
+  preserves transport symmetry and integrates discovery/config/assertions natively. The
+  `Plugin` Protocol remains the seam for genuinely *different* future protocols.
+- **Reflection-only** (require the SUT to expose reflection). Rejected (D2): hardened prod
+  servers commonly disable reflection; descriptor fallback is a small, principled addition
+  that removes a hard blocker.
+- **Descriptors-only / pre-compiled stubs only.** Rejected (D2/D10): reflection gives
+  zero-config dev ergonomics; generated `_pb2` stubs couple `agctl` to a specific `protoc`
+  run and break "any service in the descriptors."
+- **Request-stream input via `--messages '[...]'` array or `--messages-file`.** Rejected
+  (D4): bounded / quoting-hell / temp-file lifecycle. stdin NDJSON is unbounded, mirrors
+  the output NDJSON convention, and is trivial for an agent to produce.
+- **Unary-only / defer client-stream+bidi.** Rejected (D4): user chose all four call types;
+  the stdin-NDJSON model makes the two input-stream types tractable without a new contract.
+- **A `grpc_backends` entry-point + `Protocol`** (analog of `db_drivers`/`logs_backends`).
+  Rejected (D13): gRPC is one wire protocol, not a backend family; the seam would be
+  speculative. §9.3 `Plugin` is the correct out-of-tree seam if a *different* protocol
+  arrives.
+- **Mapping gRPC status codes to HTTP status / reusing `--status <http-code>`.** Rejected
+  (D6/D7): gRPC has its own status model; `--status` takes a gRPC code (name or number).
+  Translating to HTTP would lose information and surprise gRPC users.
+- **`--streaming` flag to select call type.** Rejected (D4): the descriptor already declares
+  the call type; auto-detection removes a foot-gun (a `--streaming` flag that disagrees with
+  the proto is a silent bug).
+- **Cross-message ordering assertions in v1.** Rejected (Non-Goals): per-message
+  `--match` + `--expect-count` cover v1; ordering adds offset/sequence tracking that is
+  deferred.
+- **gRPC mock server in v1.** Rejected (Non-Goals): the mock engine is HTTP+Kafka; a gRPC
+  mock (stub server + the trigger→reaction model over gRPC) is a separate effort.
+
+## 17. Deferred & Not-Covered
+
+- **gRPC mock server** (`mocks.grpc`) — separate effort.
+- **Cross-message ordering assertions** on streams.
+- **Compression, retry/service-config, interceptors, OpenTelemetry propagation.**
+- **OAuth / call-credentials beyond static `metadata`** (e.g. per-call token acquisition).
+- **Reflection v1 vs v1alpha as a user-facing knob.**
+- **Named gRPC patterns** (`grpc.patterns`) — templates cover the named-call case.
+- **Response extraction (`--capture`)** — deferred (same call as http-jq / logs).
+- **`--match-all` / regex status matching.**
+
+### Known-limitations note (honest)
+
+- **Zero-config discovery requires reflection.** A `reflection: off` target with no
+  descriptors contributes nothing to `grpc-*` discovery (skipped + warning); the operator
+  must supply descriptors for offline/locked-down servers. Documented, not hidden.
+- **Client-stream / bidi require an NDJSON-producing agent.** The two input-stream call
+  types are only usable when the caller can write request messages to stdin (a shell pipe
+  or agent subprocess). Unary/server-stream — the common cases — are unaffected.
+- **`.proto` fallback compile needs `grpcio-tools` at load.** The `grpc` extra bundles it,
+  but a reflection-only install that later adds a `.proto` descriptor must have the extra
+  (it does — the extra is monolithic). The lazy import keeps reflection-only loads fast.
+- **Server-streaming assertions are per-message.** v1 asserts on each message (`--match`)
+  and the count (`--expect-count`); there is no cross-message predicate. Documented; see
+  Deferred.
+
+## 18. Docs & Skill Impact
+
+- **DESIGN.md** — strike the gRPC row from §10; add a `grpc` subsection to §3 (command
+  contract: `grpc call` template/free-form, call-type table, `grpc healthcheck`, the
+  stdin/stdout NDJSON model); add `grpc:` to §2.1 (`targets`/`descriptors`/`templates`) and
+  the `grpc` extra to §7/§11; add `grpc.call` / `grpc.healthcheck` shapes to §4.2; add
+  `grpc-services`/`grpc-methods` to the `discover` categories (§3.8, §4.2).
+- **ARCHITECTURE.md** — add `grpc_client.py` / `grpc_commands.py` to §3 module map; add a
+  `grpc` request-lifecycle trace to §4; add a gRPC subsection to §8 (transport layer:
+  descriptor resolution, JSON↔protobuf, four call types, status-as-result); note server-stream
+  / bidi as a streaming exception in §6; §10 — note gRPC is in-tree with **no new
+  entry-point**; §15 — strike the gRPC deferred note.
+- **`skills/agctl*`** — add a `grpc` authoring reference: the `grpc:` config section
+  (`targets`/`descriptors`/`templates`), the reflection-first/descriptor-fallback rule,
+  JSON message authoring, the four call types and the stdin/stdout NDJSON model, the
+  status-as-result semantics, and the `grpc` extra.
+- **`README.md`** — surface the `grpc` group and `pip install 'agctl[grpc]'`.
+
+Doc sync is performed via the `docs-watcher` subagent after implementation
+(CLAUDE.md "Docs Sync").
diff --git a/pyproject.toml b/pyproject.toml
index 804d7e5..7284ad7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,10 +36,11 @@ jq = ["jq>=1.6"]
 kafka = ["confluent-kafka>=2.4", "jq>=1.6"]
 db = ["psycopg[binary]>=3.1", "jq>=1.6"]
 logs = ["jq>=1.6"]
+grpc = ["grpcio>=1.62", "grpcio-tools>=1.62", "grpcio-health-checking>=1.62", "grpcio-reflection>=1.62", "protobuf>=4.25", "jq>=1.6"]
 dev = ["pytest>=8.0"]
 integration = [
     "testcontainers",
-    "agctl[db,kafka,http]",
+    "agctl[db,kafka,http,grpc]",
     "pytest>=8.0",
 ]
 
diff --git a/skills/agctl/SKILL.md b/skills/agctl/SKILL.md
index 31ade3b..802123e 100644
--- a/skills/agctl/SKILL.md
+++ b/skills/agctl/SKILL.md
@@ -47,6 +47,7 @@ flags: see `--help`.)
 | See what was published | `kafka consume --topic T [--match …]` |
 | Publish a message | `kafka produce --topic T --message '{…}'` |
 | DB write / rows / value / inspect / schema | `db execute --write` / `db assert --expect-rows N` / `db assert --expect-value --path .x --equals v` / `db query` / `db schema` |
+| Call gRPC services / healthcheck | `grpc call <tpl> [--param…]` / `grpc call --target T --address host:port` / `grpc healthcheck` |
 | Impersonate a dependency | `mock run` (foreground) / `mock start\|stop\|status` (daemon) |
 | Are services up? / validate config / migrate v1/v2→v3 | `check ready --all` / `config validate` / `config migrate` |
 
@@ -246,4 +247,51 @@ agctl http ping heartbeat --interval 5 --until-stopped &
 PID=$!; … run the scenario …; kill "$PID"
 ```
 
+## `agctl grpc` — gRPC service calls
+
+gRPC support requires the `grpc` extra: `pip install 'agctl[grpc]'` (includes grpcio, grpcio-tools, grpcio-health-checking, grpcio-reflection, protobuf, jq).
+
+**Two invocation modes:**
+- **Template mode** `grpc call <template>` — resolves `grpc.templates[<name>]` (service, method, request body with `{placeholder}` support)
+- **Free-form mode** `grpc call --target <name>` or `--address host:port` — ad-hoc calls without config templates
+
+**Four call types** (auto-detected from method descriptor):
+- **Unary** — single request, single response (returns `grpc.call` envelope with `call_type: "unary"`)
+- **Client-stream** — NDJSON stdin requests → single response (same envelope shape)
+- **Server-stream** — single request → NDJSON stdout responses (streaming exception; one JSON object per response + final `summary`)
+- **Bidi** — NDJSON stdin requests ↔ NDJSON stdout responses (streaming exception; bidirectional stream)
+
+**stdin/stdout NDJSON model:** For client-stream and bidi calls, pipe NDJSON request objects via stdin. Each line is a complete JSON request object (placeholders filled per line). Server-stream and bidi emit one NDJSON line per response message plus a final `{"summary": true, ...}`.
+
+**Status-as-result semantics:** gRPC status codes are result fields, not assertion failures. A non-OK status (e.g. `StatusCode.NOT_FOUND`) still returns `ok: true` with `result.status.code`/`name`/`message`. Assertions (`--status`, `--match`, etc.) evaluate separately and raise `AssertionFailure` (exit 1) on mismatch.
+
+**Config structure:**
+```yaml
+grpc:
+  targets:
+    my-service:
+      address: "host:port"
+      use_tls: false
+      # tls: { override_authority: "" }  # optional for TLS
+  descriptors:                    # fallback when reflection is off / unavailable
+    - proto: "protos/my-service/v1/*.proto"   # compile .proto globs at load
+      include_paths: ["protos"]
+    # OR a pre-compiled descriptor set:
+    # - descriptor_set: "protos/compiled/my-service.pb"
+  templates:
+    my-method:
+      target: my-service
+      service: "ServiceName"
+      method: "MethodName"
+      request: { field: "{value}" }
+```
+
+**Discovery:** `agctl discover --category grpc-services` / `--category grpc-methods` lists discoverable services and methods (reflection-based or from descriptors).
+
+**Gotchas:**
+- **`--address` format** must be `host:port` (single colon, both non-empty). Mutually exclusive with `--target`.
+- **Reflection-first fallback:** Agctl tries server reflection first; if unavailable, falls back to `descriptors[]` proto files. Provide descriptors for air-gapped environments.
+- **Plaintext by default:** Set `use_tls: true` (and optionally `tls.override_authority`) for TLS services. Plaintext h2c is the default.
+- **Streaming exceptions:** Server-stream and bidi are the 4th and 5th streaming exceptions (after `http ping`, `mock run`, `logs tail`). Background with `&`, capture PID, kill when done.
+
 Prefer **templates** over free-form. Explore with **`discover`**, never `config show`.
diff --git a/tests/fixtures/agctl.yaml b/tests/fixtures/agctl.yaml
index e3a4882..26dd8ec 100644
--- a/tests/fixtures/agctl.yaml
+++ b/tests/fixtures/agctl.yaml
@@ -199,3 +199,19 @@ mocks:
           topic: audit.events
           value:
             kind: payment_failed
+
+grpc:
+  targets:
+    echo:
+      address: "${TEST_GRPC_ADDR:-localhost:50051}"
+      use_tls: false
+      reflection: auto
+  descriptors: []
+  templates:
+    echo-unary:
+      description: "Unary echo call"
+      target: echo
+      service: echo.Echo
+      method: Unary
+      message:
+        msg: "{m}"
diff --git a/tests/fixtures/echo.proto b/tests/fixtures/echo.proto
new file mode 100644
index 0000000..bfe6f0b
--- /dev/null
+++ b/tests/fixtures/echo.proto
@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+package echo;
+
+service Echo {
+  rpc Unary(Request) returns (Response);
+  rpc ServerStream(Request) returns (stream Response);
+  rpc ClientStream(stream Request) returns (Response);
+  rpc Bidi(stream Request) returns (stream Response);
+}
+
+message Request {
+  string msg = 1;
+}
+
+message Response {
+  string msg = 1;
+  int32 n = 2;
+}
diff --git a/tests/fixtures/echo_descriptor.pb b/tests/fixtures/echo_descriptor.pb
new file mode 100644
index 0000000..b620e59
--- /dev/null
+++ b/tests/fixtures/echo_descriptor.pb
@@ -0,0 +1,14 @@
+
+¡
+
+echo.protoecho"
+Request
+msg
 
(	Rmsg"*
+Response
+msg
 
(	Rmsg
+
n 
(R
n2»

+Echo&
+Unary
.echo.Request.echo.Response/
+ServerStream
.echo.Request.echo.Response0
/
+ClientStream
.echo.Request.echo.Response(
)
+Bidi
.echo.Request.echo.Response(
0
bproto3
\ No newline at end of file
diff --git a/tests/fixtures/echo_pb2.py b/tests/fixtures/echo_pb2.py
new file mode 100644
index 0000000..9ef634a
--- /dev/null
+++ b/tests/fixtures/echo_pb2.py
@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: echo.proto
+# Protobuf Python Version: 7.35.0
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    7,
+    35,
+    0,
+    '',
+    'echo.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\necho.proto\x12\x04\x65\x63ho\"\x16\n\x07Request\x12\x0b\n\x03msg\x18\x01 \x01(\t\"\"\n\x08Response\x12\x0b\n\x03msg\x18\x01 \x01(\t\x12\t\n\x01n\x18\x02 \x01(\x05\x32\xbb\x01\n\x04\x45\x63ho\x12&\n\x05Unary\x12\r.echo.Request\x1a\x0e.echo.Response\x12/\n\x0cServerStream\x12\r.echo.Request\x1a\x0e.echo.Response0\x01\x12/\n\x0c\x43lientStream\x12\r.echo.Request\x1a\x0e.echo.Response(\x01\x12)\n\x04\x42idi\x12\r.echo.Request\x1a\x0e.echo.Response(\x01\x30\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'echo_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_REQUEST']._serialized_start=20
+  _globals['_REQUEST']._serialized_end=42
+  _globals['_RESPONSE']._serialized_start=44
+  _globals['_RESPONSE']._serialized_end=78
+  _globals['_ECHO']._serialized_start=81
+  _globals['_ECHO']._serialized_end=268
+# @@protoc_insertion_point(module_scope)
diff --git a/tests/fixtures/echo_pb2_grpc.py b/tests/fixtures/echo_pb2_grpc.py
new file mode 100644
index 0000000..2ebd47f
--- /dev/null
+++ b/tests/fixtures/echo_pb2_grpc.py
@@ -0,0 +1,226 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+import echo_pb2 as echo__pb2
+
+GRPC_GENERATED_VERSION = '1.82.1'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in echo_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class EchoStub:
+    """Missing associated documentation comment in .proto file."""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Unary = channel.unary_unary(
+                '/echo.Echo/Unary',
+                request_serializer=echo__pb2.Request.SerializeToString,
+                response_deserializer=echo__pb2.Response.FromString,
+                _registered_method=True)
+        self.ServerStream = channel.unary_stream(
+                '/echo.Echo/ServerStream',
+                request_serializer=echo__pb2.Request.SerializeToString,
+                response_deserializer=echo__pb2.Response.FromString,
+                _registered_method=True)
+        self.ClientStream = channel.stream_unary(
+                '/echo.Echo/ClientStream',
+                request_serializer=echo__pb2.Request.SerializeToString,
+                response_deserializer=echo__pb2.Response.FromString,
+                _registered_method=True)
+        self.Bidi = channel.stream_stream(
+                '/echo.Echo/Bidi',
+                request_serializer=echo__pb2.Request.SerializeToString,
+                response_deserializer=echo__pb2.Response.FromString,
+                _registered_method=True)
+
+
+class EchoServicer:
+    """Missing associated documentation comment in .proto file."""
+
+    def Unary(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def ServerStream(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def ClientStream(self, request_iterator, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def Bidi(self, request_iterator, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_EchoServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Unary': grpc.unary_unary_rpc_method_handler(
+                    servicer.Unary,
+                    request_deserializer=echo__pb2.Request.FromString,
+                    response_serializer=echo__pb2.Response.SerializeToString,
+            ),
+            'ServerStream': grpc.unary_stream_rpc_method_handler(
+                    servicer.ServerStream,
+                    request_deserializer=echo__pb2.Request.FromString,
+                    response_serializer=echo__pb2.Response.SerializeToString,
+            ),
+            'ClientStream': grpc.stream_unary_rpc_method_handler(
+                    servicer.ClientStream,
+                    request_deserializer=echo__pb2.Request.FromString,
+                    response_serializer=echo__pb2.Response.SerializeToString,
+            ),
+            'Bidi': grpc.stream_stream_rpc_method_handler(
+                    servicer.Bidi,
+                    request_deserializer=echo__pb2.Request.FromString,
+                    response_serializer=echo__pb2.Response.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'echo.Echo', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('echo.Echo', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class Echo:
+    """Missing associated documentation comment in .proto file."""
+
+    @staticmethod
+    def Unary(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/echo.Echo/Unary',
+            echo__pb2.Request.SerializeToString,
+            echo__pb2.Response.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def ServerStream(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(
+            request,
+            target,
+            '/echo.Echo/ServerStream',
+            echo__pb2.Request.SerializeToString,
+            echo__pb2.Response.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def ClientStream(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_unary(
+            request_iterator,
+            target,
+            '/echo.Echo/ClientStream',
+            echo__pb2.Request.SerializeToString,
+            echo__pb2.Response.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def Bidi(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(
+            request_iterator,
+            target,
+            '/echo.Echo/Bidi',
+            echo__pb2.Request.SerializeToString,
+            echo__pb2.Response.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
diff --git a/tests/integration/test_grpc_commands.py b/tests/integration/test_grpc_commands.py
new file mode 100644
index 0000000..89ccef2
--- /dev/null
+++ b/tests/integration/test_grpc_commands.py
@@ -0,0 +1,512 @@
+"""Live integration test: ``grpc call`` and ``grpc healthcheck`` against a real grpcio server.
+
+Requires env:
+- ``AGCTL_TEST_LIVE=1`` — spins up an in-process grpcio Echo server with reflection + health.
+- ``AGCTL_TEST_GRPC_ADDR`` — ``host:port`` of an already-running grpcio server (manual mode).
+
+Skips (via the ``require_grpc_server`` fixture) when grpcio/grpcio-reflection/grpcio-health-checking
+are unavailable or when no server is reachable.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import threading
+from concurrent import futures
+
+import pytest
+
+pytest.importorskip("grpc")
+pytest.importorskip("grpc_reflection")
+pytest.importorskip("grpc_health")
+
+from click.testing import CliRunner
+
+from agctl.cli import cli
+
+# Path fixtures
+FIXTURES_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + "/fixtures"
+sys.path.insert(0, FIXTURES_DIR)
+import echo_pb2
+import echo_pb2_grpc
+sys.path.remove(FIXTURES_DIR)
+
+DESCRIPTOR_FILE = f"{FIXTURES_DIR}/echo_descriptor.pb"
+
+
+@pytest.fixture
+def require_grpc_server():
+    """Skip if a live gRPC server is unreachable.
+
+    Two modes:
+    1. ``AGCTL_TEST_LIVE=1``: start an in-process grpcio Echo server with reflection + health.
+    2. ``AGCTL_TEST_GRPC_ADDR``: connect to an already-running server.
+
+    Yields the ``host:port`` address string.
+    """
+    # Manual mode: use provided address
+    manual_addr = os.environ.get("AGCTL_TEST_GRPC_ADDR")
+    if manual_addr:
+        yield manual_addr
+        return
+
+    # Live mode: start in-process server
+    live = os.environ.get("AGCTL_TEST_LIVE") == "1"
+    if not live:
+        pytest.skip("AGCTL_TEST_LIVE=1 or AGCTL_TEST_GRPC_ADDR not set; skipping live gRPC test")
+
+    # Import grpc modules
+    import grpc
+    from grpc_reflection.v1alpha import reflection
+    from grpc_health.v1 import health
+    from grpc.health.v1 import health_pb2, health_pb2_grpc
+
+    # Implement the Echo servicer
+    class EchoServicer(echo_pb2_grpc.EchoServicer):
+        """Tiny Echo servicer for testing."""
+
+        def Unary(self, request, context):
+            """Unary echo: return the msg field."""
+            return echo_pb2.Response(msg=request.msg)
+
+        def ServerStream(self, request, context):
+            """Server stream: emit N messages."""
+            # Request message only has 'msg' field, not 'n'
+            n = 3  # Default number of messages
+            for i in range(n):
+                yield echo_pb2.Response(msg=f"{request.msg}-{i}", n=i)
+
+        def ClientStream(self, request_iterator, context):
+            """Client stream: concatenate all request msg fields."""
+            msgs = []
+            for req in request_iterator:
+                msgs.append(req.msg)
+            return echo_pb2.Response(msg=" ".join(msgs), n=len(msgs))
+
+        def Bidi(self, request_iterator, context):
+            """Bidi: echo each request."""
+            for req in request_iterator:
+                yield echo_pb2.Response(msg=f"echo-{req.msg}")
+
+    # Create and start the server
+    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
+    echo_pb2_grpc.add_EchoServicer_to_server(EchoServicer(), server)
+
+    # Enable reflection
+    reflection.enable_server_reflection(
+        service_names=[
+            echo_pb2.DESCRIPTOR.services_by_name["Echo"].full_name,
+            reflection.SERVICE_NAME,
+        ],
+        server=server,
+    )
+
+    # Enable health
+    health_servicer = health.HealthServicer()
+    health_pb2_grpc.add_HealthServicer_to_server(health_servicer, server)
+
+    # Set the Echo service to SERVING
+    health_servicer.set(
+        echo_pb2.DESCRIPTOR.services_by_name["Echo"].full_name,
+        health_pb2.HealthCheckResponse.ServingStatus.SERVING,
+    )
+
+    # Bind to ephemeral port
+    port = server.add_insecure_port("127.0.0.1:0")
+    server.start()
+
+    # Run server in background thread
+    stop_event = threading.Event()
+    server_thread = threading.Thread(target=lambda: stop_event.wait() or server.stop(), daemon=True)
+    server_thread.start()
+
+    try:
+        yield f"127.0.0.1:{port}"
+    finally:
+        stop_event.set()
+        server_thread.join(timeout=5)
+
+
+def _write_config(config_path, grpc_addr, reflection="auto", descriptors_path=None):
+    """Write a minimal agctl.yaml for testing."""
+    if descriptors_path:
+        descriptors = f"""  descriptors:
+    - descriptor_set: {descriptors_path}
+"""
+    else:
+        descriptors = ""
+
+    config = f"""version: "3"
+grpc:
+  targets:
+    echo:
+      address: {grpc_addr}
+      use_tls: false
+      reflection: "{reflection}"
+  templates:
+    echo-unary:
+      target: echo
+      service: echo.Echo
+      method: Unary
+    echo-server-stream:
+      target: echo
+      service: echo.Echo
+      method: ServerStream
+    echo-client-stream:
+      target: echo
+      service: echo.Echo
+      method: ClientStream
+    echo-bidi:
+      target: echo
+      service: echo.Echo
+      method: Bidi
+{descriptors}
+"""
+    with open(config_path, "w") as f:
+        f.write(config)
+
+
+def test_grpc_unary_call_and_assert(require_grpc_server):
+    """Unary gRPC call echoes msg; status assertion works; wrong status fails."""
+    addr = require_grpc_server
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        config_path = f.name
+        _write_config(config_path, addr)
+
+    try:
+        runner = CliRunner()
+
+        # 1. Successful unary call
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "grpc",
+                "call",
+                "echo-unary",
+                '--message',
+                '{"msg":"hi"}',
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        import json
+
+        envelope = json.loads(result.output)
+        assert envelope["ok"] is True
+        assert envelope["result"]["message"]["msg"] == "hi"
+
+        # 2. --status OK passes
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "grpc",
+                "call",
+                "echo-unary",
+                '--message',
+                '{"msg":"hi"}',
+                "--status",
+                "OK",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        envelope = json.loads(result.output)
+        assert envelope["ok"] is True
+
+        # 3. --status NOT_FOUND fails (exit 1)
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "grpc",
+                "call",
+                "echo-unary",
+                '--message',
+                '{"msg":"hi"}',
+                "--status",
+                "NOT_FOUND",
+            ],
+        )
+        assert result.exit_code == 1, result.output
+        envelope = json.loads(result.output)
+        assert envelope["ok"] is False
+        assert envelope["error"]["type"] == "AssertionError"
+    finally:
+        os.unlink(config_path)
+
+
+def test_grpc_server_stream(require_grpc_server):
+    """Server streaming emits NDJSON with N message lines + summary, exit 0."""
+    addr = require_grpc_server
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        config_path = f.name
+        _write_config(config_path, addr)
+
+    try:
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "grpc",
+                "call",
+                "echo-server-stream",
+                '--message',
+                '{"msg":"x"}',
+            ],
+        )
+        assert result.exit_code == 0, result.output
+
+        # Parse NDJSON output
+        lines = result.output.strip().split("\n")
+        # Should have multiple message events
+        import json
+
+        # Check that we get message events
+        message_count = 0
+        for line in lines:
+            obj = json.loads(line)
+            if obj.get("event") == "message":
+                message_count += 1
+                msg = obj["message"]
+                # All messages should start with "x-"
+                assert msg["msg"].startswith("x-")
+
+        # Should have at least 3 messages
+        assert message_count >= 3
+    finally:
+        os.unlink(config_path)
+
+
+def test_grpc_client_stream(require_grpc_server):
+    """Client streaming: pipe stdin with NDJSON requests, get one envelope result."""
+    addr = require_grpc_server
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        config_path = f.name
+        _write_config(config_path, addr)
+
+    try:
+        runner = CliRunner()
+        stdin = '{"msg":"a"}\n{"msg":"b"}\n'
+
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "grpc",
+                "call",
+                "echo-client-stream",
+            ],
+            input=stdin,
+        )
+        assert result.exit_code == 0, result.output
+        import json
+
+        envelope = json.loads(result.output)
+        assert envelope["ok"] is True
+        # ClientStream servicer concatenates all request msg fields
+        assert envelope["result"]["message"]["msg"] == "a b"
+        assert envelope["result"]["message"]["n"] == 2
+    finally:
+        os.unlink(config_path)
+
+
+def test_grpc_bidi(require_grpc_server):
+    """Bidi streaming: pipe stdin with 2 requests, get 2 message lines + summary."""
+    addr = require_grpc_server
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        config_path = f.name
+        _write_config(config_path, addr)
+
+    try:
+        runner = CliRunner()
+        stdin = '{"msg":"req1"}\n{"msg":"req2"}\n'
+
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "grpc",
+                "call",
+                "echo-bidi",
+            ],
+            input=stdin,
+        )
+        assert result.exit_code == 0, result.output
+
+        # Parse NDJSON output
+        lines = result.output.strip().split("\n")
+        import json
+
+        # First response
+        resp0_event = json.loads(lines[0])
+        assert resp0_event["event"] == "message"
+        resp0 = resp0_event["message"]
+        assert resp0["msg"] == "echo-req1"
+
+        # Second response
+        resp1_event = json.loads(lines[1])
+        assert resp1_event["event"] == "message"
+        resp1 = resp1_event["message"]
+        assert resp1["msg"] == "echo-req2"
+
+        # Summary envelope
+        summary = json.loads(lines[2])
+        # Just verify we have a summary
+        assert "messages" in summary or "ok" in summary
+    finally:
+        os.unlink(config_path)
+
+
+def test_grpc_nonok_status_result(require_grpc_server):
+    """Non-OK gRPC status is a result (exit 0), not a failure."""
+    addr = require_grpc_server
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        config_path = f.name
+        _write_config(config_path, addr)
+
+    try:
+        runner = CliRunner()
+
+        # Call with an assertion that will fail (simulating a NOT_FOUND scenario)
+        # Since our simple Echo servicer always returns OK, we'll test with --status OK
+        # and verify that the status is included in the result
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "grpc",
+                "call",
+                "echo-unary",
+                '--message',
+                '{"msg":"test"}',
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        import json
+
+        envelope = json.loads(result.output)
+        assert envelope["ok"] is True
+        # Status is included in the result
+        assert "result" in envelope
+        assert "status" in envelope["result"]
+        assert envelope["result"]["status"]["name"] == "OK"
+    finally:
+        os.unlink(config_path)
+
+
+def test_grpc_healthcheck(require_grpc_server):
+    """Healthcheck against the Echo service returns SERVING."""
+    addr = require_grpc_server
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        config_path = f.name
+        _write_config(config_path, addr)
+
+    try:
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "grpc",
+                "healthcheck",
+                "--target",
+                "echo",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        import json
+
+        envelope = json.loads(result.output)
+        assert envelope["ok"] is True
+        assert envelope["result"]["targets"]["echo"]["status"] == "SERVING"
+    finally:
+        os.unlink(config_path)
+
+
+def test_grpc_discover_methods(require_grpc_server):
+    """Discover grpc-methods category for echo-unary template returns request_fields."""
+    addr = require_grpc_server
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        config_path = f.name
+        _write_config(config_path, addr)
+
+    try:
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "discover",
+                "--category",
+                "grpc-methods",
+                "--name",
+                "echo-unary",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        import json
+
+        envelope = json.loads(result.output)
+        assert envelope["ok"] is True
+        # Should have discovered method info from reflection
+        assert "result" in envelope
+        # The result should contain the method info
+        assert envelope["result"]["service"] == "echo.Echo"
+        assert envelope["result"]["method"] == "Unary"
+        # Request fields should be populated from the live descriptor
+        assert "request_fields" in envelope["result"]
+        assert len(envelope["result"]["request_fields"]) > 0
+    finally:
+        os.unlink(config_path)
+
+
+def test_grpc_reflection_then_descriptor_fallback(require_grpc_server):
+    """With reflection off but descriptors set, unary call still works (fallback path)."""
+    addr = require_grpc_server
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        config_path = f.name
+        # reflection: off + descriptors pointing at the .pb file
+        _write_config(config_path, addr, reflection="off", descriptors_path=DESCRIPTOR_FILE)
+
+    try:
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--config",
+                config_path,
+                "grpc",
+                "call",
+                "echo-unary",
+                '--message',
+                '{"msg":"fallback-test"}',
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        import json
+
+        envelope = json.loads(result.output)
+        assert envelope["ok"] is True
+        assert envelope["result"]["message"]["msg"] == "fallback-test"
+    finally:
+        os.unlink(config_path)
diff --git a/tests/unit/test_config_validator.py b/tests/unit/test_config_validator.py
new file mode 100644
index 0000000..16c5ff1
--- /dev/null
+++ b/tests/unit/test_config_validator.py
@@ -0,0 +1,169 @@
+"""Tests for config validator (DESIGN §3.5 dangling refs, §3.6 warnings)."""
+
+import pytest
+
+from agctl.config.models import Config
+from agctl.config.validator import validate_config
+
+
+def test_grpc_template_unknown_target_is_error():
+    """A gRPC template referencing a missing target produces an error."""
+    cfg = Config.model_validate(
+        {
+            "version": "2",
+            "grpc": {
+                "targets": {"existing-target": {"address": "localhost:50051"}},
+                "templates": {
+                    "t1": {
+                        "target": "missing-target",
+                        "service": "s.Svc",
+                        "method": "M",
+                        "description": "A template",
+                    }
+                },
+            },
+        }
+    )
+    errors, warnings = validate_config(cfg)
+    assert errors == [
+        {
+            "path": "grpc.templates.t1.target",
+            "message": "gRPC template references unknown target 'missing-target'",
+        }
+    ]
+    # No template-level warning for this config (description not involved)
+    assert warnings == []
+
+
+def test_grpc_template_known_target_no_error():
+    """A gRPC template referencing an existing target produces no error."""
+    cfg = Config.model_validate(
+        {
+            "version": "2",
+            "grpc": {
+                "targets": {"existing-target": {"address": "localhost:50051"}},
+                "templates": {
+                    "t1": {
+                        "target": "existing-target",
+                        "service": "s.Svc",
+                        "method": "M",
+                        "description": "A template",
+                    }
+                },
+            },
+        }
+    )
+    errors, warnings = validate_config(cfg)
+    assert errors == []
+    assert warnings == []
+
+
+def test_grpc_descriptor_both_set_is_error():
+    """A grpc.descriptors entry with both proto and descriptor_set set is an error."""
+    cfg = Config.model_validate(
+        {
+            "version": "2",
+            "grpc": {
+                "descriptors": [
+                    {"proto": "a.proto", "descriptor_set": "b.pb"}
+                ],
+            },
+        }
+    )
+    errors, warnings = validate_config(cfg)
+    assert errors == [
+        {
+            "path": "grpc.descriptors[0]",
+            "message": "each grpc.descriptors entry must set exactly one of 'proto' or 'descriptor_set'",
+        }
+    ]
+    assert warnings == []
+
+
+def test_grpc_descriptor_neither_set_is_error():
+    """A grpc.descriptors entry with neither proto nor descriptor_set set is an error."""
+    cfg = Config.model_validate(
+        {
+            "version": "2",
+            "grpc": {
+                "descriptors": [{}],
+            },
+        }
+    )
+    errors, warnings = validate_config(cfg)
+    assert errors == [
+        {
+            "path": "grpc.descriptors[0]",
+            "message": "each grpc.descriptors entry must set exactly one of 'proto' or 'descriptor_set'",
+        }
+    ]
+    assert warnings == []
+
+
+def test_grpc_descriptor_exactly_one_ok():
+    """A grpc.descriptors entry with exactly one of proto or descriptor_set is valid."""
+    cfg = Config.model_validate(
+        {
+            "version": "2",
+            "grpc": {
+                "descriptors": [
+                    {"proto": "a.proto", "include_paths": ["."]},
+                    {"descriptor_set": "b.pb"},
+                ],
+            },
+        }
+    )
+    errors, warnings = validate_config(cfg)
+    assert errors == []
+    assert warnings == []
+
+
+def test_grpc_template_missing_description_warns():
+    """A gRPC template with no description produces a warning."""
+    cfg = Config.model_validate(
+        {
+            "version": "2",
+            "grpc": {
+                "targets": {"t1": {"address": "localhost:50051"}},
+                "templates": {
+                    "tmpl1": {
+                        "target": "t1",
+                        "service": "s.Svc",
+                        "method": "M",
+                        "description": None,
+                    }
+                },
+            },
+        }
+    )
+    errors, warnings = validate_config(cfg)
+    assert errors == []
+    assert warnings == [
+        {
+            "path": "grpc.templates.tmpl1",
+            "message": "missing description (discovery degrades without it)",
+        }
+    ]
+
+
+def test_grpc_template_with_description_no_warning():
+    """A gRPC template with a description produces no warning."""
+    cfg = Config.model_validate(
+        {
+            "version": "2",
+            "grpc": {
+                "targets": {"t1": {"address": "localhost:50051"}},
+                "templates": {
+                    "tmpl1": {
+                        "target": "t1",
+                        "service": "s.Svc",
+                        "method": "M",
+                        "description": "Call the method",
+                    }
+                },
+            },
+        }
+    )
+    errors, warnings = validate_config(cfg)
+    assert errors == []
+    assert warnings == []
diff --git a/tests/unit/test_discover_command.py b/tests/unit/test_discover_command.py
index be7aff8..393068a 100644
--- a/tests/unit/test_discover_command.py
+++ b/tests/unit/test_discover_command.py
@@ -963,3 +963,216 @@ def test_discover_item_unknown_log_source(monkeypatch):
     assert payload["ok"] is False
     assert payload["error"]["type"] == "TemplateNotFound"
     assert "Unknown logs source: nope" in payload["error"]["message"]
+
+
+# --------------------------------------------------------------------------- #
+# Task 12: grpc-services / grpc-methods categories
+# --------------------------------------------------------------------------- #
+
+
+def test_discover_summary_includes_grpc(monkeypatch):
+    """Task 12 Test 1: discover summary includes grpc_targets and grpc_methods counts and hint mentions grpc-services/grpc-methods."""
+    result = _run([], monkeypatch)
+    assert result.exit_code == 0
+    payload = _payload(result)
+    assert payload["ok"] is True
+    counts = payload["result"]
+    # Fixture has 1 gRPC target (echo) and 1 template (echo-unary)
+    assert counts["grpc_targets"] == 1
+    assert counts["grpc_methods"] == 1
+    # Hint should mention both new categories
+    assert "grpc-services" in counts["hint"]
+    assert "grpc-methods" in counts["hint"]
+
+
+def test_discover_category_grpc_services(monkeypatch):
+    """Task 12 Test 2: discover --category grpc-services lists gRPC targets."""
+    result = _run(["--category", "grpc-services"], monkeypatch)
+    assert result.exit_code == 0
+    payload = _payload(result)
+    assert payload["command"] == "discover.category"
+    res = payload["result"]
+    assert res["category"] == "grpc-services"
+    assert res["count"] == 1
+    by_name = {item["name"]: item for item in res["items"]}
+    assert "echo" in by_name
+    # Description format: "gRPC target {name} at {address} (tls={use_tls})"
+    desc = by_name["echo"]["description"]
+    assert "gRPC target echo" in desc
+    assert "localhost:50051" in desc
+    assert "tls=False" in desc or "tls=false" in desc.lower()
+
+
+def test_discover_category_grpc_methods(monkeypatch):
+    """Task 12 Test 3: discover --category grpc-methods lists gRPC method templates."""
+    result = _run(["--category", "grpc-methods"], monkeypatch)
+    assert result.exit_code == 0
+    payload = _payload(result)
+    assert payload["command"] == "discover.category"
+    res = payload["result"]
+    assert res["category"] == "grpc-methods"
+    assert res["count"] == 1
+    by_name = {item["name"]: item for item in res["items"]}
+    assert "echo-unary" in by_name
+    # Description is the template description or "service/method"
+    assert by_name["echo-unary"]["description"] == "Unary echo call"
+
+
+def test_discover_item_grpc_methods_schema(monkeypatch):
+    """Task 12 Test 4: discover --category grpc-methods --name echo-unary returns request_fields and call_type."""
+    # Create a fake method descriptor with input_type.fields
+    from google.protobuf.descriptor import FieldDescriptor
+
+    class FakeField:
+        def __init__(self, name, type_int, is_repeated):
+            self.name = name
+            self.type = type_int
+            self.is_repeated = is_repeated
+
+    class FakeInputType:
+        def __init__(self):
+            self.fields = [
+                FakeField("msg", FieldDescriptor.TYPE_STRING, False),  # TYPE_STRING = 9
+                FakeField("count", FieldDescriptor.TYPE_INT64, False),  # TYPE_INT64 = 3
+                FakeField("items", FieldDescriptor.TYPE_STRING, True),  # repeated
+            ]
+
+    class FakeMethodDescriptor:
+        def __init__(self):
+            self.input_type = FakeInputType()
+
+    # Fake gRPC client
+    class FakeGrpcClient:
+        def __init__(self, target, *, descriptors=None):
+            self.target = target
+
+        def find_method(self, service, method):
+            return FakeMethodDescriptor()
+
+        def call_type_of(self, method_descriptor):
+            return "unary"
+
+    # Monkeypatch grpc_commands.new_grpc_client
+    import agctl.commands.grpc_commands as grpc_commands
+    monkeypatch.setattr(grpc_commands, "new_grpc_client", FakeGrpcClient)
+
+    result = _run(["--category", "grpc-methods", "--name", "echo-unary"], monkeypatch)
+    assert result.exit_code == 0
+    payload = _payload(result)
+    assert payload["command"] == "discover.item"
+    res = payload["result"]
+    assert res["category"] == "grpc-methods"
+    assert res["name"] == "echo-unary"
+    assert res["target"] == "echo"
+    assert res["service"] == "echo.Echo"
+    assert res["method"] == "Unary"
+    assert res["call_type"] == "unary"
+    # request_fields should enumerate the fields
+    fields = res["request_fields"]
+    assert len(fields) == 3
+    # msg field: TYPE_STRING, not repeated
+    msg_field = next(f for f in fields if f["name"] == "msg")
+    assert msg_field["type"] == "TYPE_STRING"
+    assert msg_field["repeated"] is False
+    # count field: TYPE_INT64, not repeated
+    count_field = next(f for f in fields if f["name"] == "count")
+    assert count_field["type"] == "TYPE_INT64"
+    assert count_field["repeated"] is False
+    # items field: TYPE_STRING, IS repeated
+    items_field = next(f for f in fields if f["name"] == "items")
+    assert items_field["type"] == "TYPE_STRING"
+    assert items_field["repeated"] is True
+    # example starts with "agctl grpc call echo-unary"
+    assert res["example"].startswith("agctl grpc call echo-unary")
+
+
+def test_discover_item_grpc_methods_unavailable_isolated(monkeypatch):
+    """Task 12 Test 5: discover --category grpc-methods --name unavailable when reflection fails returns unavailable=True instead of crashing."""
+    from agctl.errors import ConfigError
+
+    # Fake client that raises ConfigError (reflection unreachable)
+    class FakeGrpcClient:
+        def __init__(self, target, *, descriptors=None):
+            raise ConfigError("Reflection service unreachable", {"target": target.address})
+
+    # Monkeypatch grpc_commands.new_grpc_client BEFORE importing the module
+    import agctl.commands.grpc_commands as grpc_commands
+    original_new_grpc_client = grpc_commands.new_grpc_client
+    grpc_commands.new_grpc_client = FakeGrpcClient
+
+    # Create a temp config with an unavailable template
+    config_yaml = (
+        'version: "3"\n'
+        "services:\n"
+        '  demo:\n'
+        '    base_url: "http://localhost:9999"\n'
+        "grpc:\n"
+        "  targets:\n"
+        "    echo:\n"
+        '      address: "localhost:50051"\n'
+        "      use_tls: false\n"
+        "      reflection: auto\n"
+        "  descriptors: []\n"
+        "  templates:\n"
+        "    echo-unary:\n"
+        '      description: "Unary echo call"\n'
+        "      target: echo\n"
+        "      service: echo.Echo\n"
+        "      method: Unary\n"
+        "      message:\n"
+        '        msg: "{m}"\n'
+    )
+
+    from pathlib import Path
+    import tempfile
+    try:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            cfg_file = Path(tmp_dir) / "agctl.yaml"
+            cfg_file.write_text(config_yaml)
+
+            runner = CliRunner()
+            result = runner.invoke(
+                cli,
+                ["--config", str(cfg_file), "discover", "--category", "grpc-methods", "--name", "echo-unary"],
+                env=ENV,
+                standalone_mode=False,
+            )
+
+        # Should NOT crash - exit 0 with unavailable marker
+        assert result.exit_code == 0, f"Expected exit 0, got {result.exit_code}. Output: {result.output}"
+        payload = _payload(result)
+        assert payload["ok"] is True
+        res = payload["result"]
+        assert res["category"] == "grpc-methods"
+        assert res["name"] == "echo-unary"
+        assert res["unavailable"] is True
+        assert "error" in res
+        assert "Reflection service unreachable" in res["error"]
+    finally:
+        # Restore the original function
+        grpc_commands.new_grpc_client = original_new_grpc_client
+
+
+def test_discover_search_grpc(monkeypatch):
+    """Task 12 Test 6: discover --search echo finds gRPC targets and templates."""
+    result = _run(["--search", "echo"], monkeypatch)
+    assert result.exit_code == 0
+    payload = _payload(result)
+    assert payload["command"] == "discover.search"
+    res = payload["result"]
+    matches = res["matches"]
+    by_key = {(m["category"], m["name"]) for m in matches}
+    # Should find the echo gRPC service
+    assert ("grpc-services", "echo") in by_key
+    # Should find the echo-unary template
+    assert ("grpc-methods", "echo-unary") in by_key
+
+
+def test_discover_unknown_grpc_target_item(monkeypatch):
+    """Task 12 Test 7: discover --category grpc-services --name nope returns TemplateNotFound."""
+    result = _run(["--category", "grpc-services", "--name", "nope"], monkeypatch)
+    assert result.exit_code == 2
+    payload = _payload(result)
+    assert payload["ok"] is False
+    assert payload["error"]["type"] == "TemplateNotFound"
+    assert "Unknown gRPC target: nope" in payload["error"]["message"]
diff --git a/tests/unit/test_grpc_assertions.py b/tests/unit/test_grpc_assertions.py
new file mode 100644
index 0000000..30723c9
--- /dev/null
+++ b/tests/unit/test_grpc_assertions.py
@@ -0,0 +1,169 @@
+"""Tests for gRPC assertion validation and evaluation."""
+
+import json
+import sys
+
+import pytest
+
+from agctl.assertions import evaluate_grpc_assertions, validate_grpc_assertion_args
+from agctl.errors import AssertionFailure, ConfigError
+
+
+@pytest.fixture
+def grpc_result_ok():
+    """A sample gRPC result dict with OK status and a message payload."""
+    return {
+        "target": "localhost:50051",
+        "service": "test.Service",
+        "method": "GetInfo",
+        "call_type": "unary",
+        "status": {"code": 0, "name": "OK", "message": ""},
+        "message": {"a": 1, "b": {"c": 2}},
+        "initial_metadata": [],
+        "trailers": [],
+    }
+
+
+def test_validate_pairing():
+    """jq_path/equals must be used together (XOR)."""
+    with pytest.raises(ConfigError, match="--jq-path and --equals must be used together"):
+        validate_grpc_assertion_args(jq_path=".x", equals=None)
+
+
+def test_validate_contains_json():
+    """--contains must be valid JSON."""
+    with pytest.raises(ConfigError, match="--contains must be valid JSON"):
+        validate_grpc_assertion_args(contains="{bad")
+
+
+def test_validate_status_name_and_number():
+    """--status accepts both code names and numbers 0-16."""
+    # Valid forms
+    validate_grpc_assertion_args(status="NOT_FOUND")
+    validate_grpc_assertion_args(status=5)
+
+    # Invalid forms
+    with pytest.raises(ConfigError, match="--status must be a gRPC code name or number 0-16"):
+        validate_grpc_assertion_args(status="NOPE")
+    with pytest.raises(ConfigError, match="--status must be a gRPC code name or number 0-16"):
+        validate_grpc_assertion_args(status=99)
+
+
+def test_validate_all_none_ok():
+    """All-None args return None (no-op)."""
+    assert validate_grpc_assertion_args() is None
+
+
+def test_eval_status_pass_and_fail(grpc_result_ok):
+    """Status assertion: name or number -> compare to result['status']['code']."""
+    # Pass: status matches
+    evaluate_grpc_assertions(
+        grpc_result_ok, status="OK", contains=None, match=None, jq_path=None, equals=None
+    )
+
+    # Fail: status mismatch
+    with pytest.raises(AssertionFailure) as exc_info:
+        evaluate_grpc_assertions(
+            grpc_result_ok, status="NOT_FOUND", contains=None, match=None, jq_path=None, equals=None
+        )
+    failures = exc_info.value.detail["failures"]
+    assert len(failures) == 1
+    assert failures[0]["mode"] == "status"
+    assert failures[0]["expected"] == "NOT_FOUND"
+    assert failures[0]["actual"] == "OK"
+
+
+def test_eval_contains(grpc_result_ok):
+    """Contains assertion checks result['message'] subset match."""
+    # Pass: needle exists in message
+    evaluate_grpc_assertions(
+        grpc_result_ok, contains='{"b":{"c":2}}', match=None, jq_path=None, equals=None, status=None
+    )
+
+    # Fail: needle missing
+    with pytest.raises(AssertionFailure) as exc_info:
+        evaluate_grpc_assertions(
+            grpc_result_ok, contains='{"z":1}', match=None, jq_path=None, equals=None, status=None
+        )
+    failures = exc_info.value.detail["failures"]
+    assert len(failures) == 1
+    assert failures[0]["mode"] == "contains"
+    assert failures[0]["needle"] == {"z": 1}
+    assert failures[0]["matched"] is False
+    assert failures[0]["root"] == "response message"
+
+
+def test_eval_match_envelope_rooted(grpc_result_ok):
+    """Match assertion evaluates jq against the whole result dict (envelope-rooted)."""
+    jq = pytest.importorskip("jq")
+
+    # Pass: envelope-rooted expression
+    evaluate_grpc_assertions(grpc_result_ok, match='.status.name == "OK"', jq_path=None, equals=None, contains=None, status=None)
+
+    # Pass: .message reaches into message
+    evaluate_grpc_assertions(grpc_result_ok, match=".message.a == 1", jq_path=None, equals=None, contains=None, status=None)
+
+    # Fail: wrong status name
+    with pytest.raises(AssertionFailure) as exc_info:
+        evaluate_grpc_assertions(
+            grpc_result_ok, match='.status.name == "NOPE"', jq_path=None, equals=None, contains=None, status=None
+        )
+    failures = exc_info.value.detail["failures"]
+    assert len(failures) == 1
+    assert failures[0]["mode"] == "match"
+    assert failures[0]["expr"] == '.status.name == "NOPE"'
+    assert failures[0]["result"] is False
+    assert failures[0]["root"] == "response envelope"
+
+
+def test_eval_jq_path_equals(grpc_result_ok):
+    """jq-path assertion: type-aware comparison against result['message'] value."""
+    jq = pytest.importorskip("jq")
+
+    # Pass: type-aware equal (number matches number)
+    evaluate_grpc_assertions(grpc_result_ok, jq_path=".a", equals="1", match=None, contains=None, status=None)
+
+    # Fail: number != string (type-aware)
+    with pytest.raises(AssertionFailure) as exc_info:
+        evaluate_grpc_assertions(grpc_result_ok, jq_path=".a", equals='"1"', match=None, contains=None, status=None)
+    failures = exc_info.value.detail["failures"]
+    assert len(failures) == 1
+    assert failures[0]["mode"] == "jq-path"
+    assert failures[0]["path"] == ".a"
+    assert failures[0]["expected"] == "1"
+    assert failures[0]["actual"] == 1
+    assert failures[0]["root"] == "response message"
+
+
+def test_eval_multiple_failures_no_shortcircuit(grpc_result_ok):
+    """Multiple assertion failures are collected (no short-circuit)."""
+    with pytest.raises(AssertionFailure) as exc_info:
+        evaluate_grpc_assertions(
+            grpc_result_ok,
+            status="NOT_FOUND",
+            contains='{"missing": "key"}',
+            match=None,
+            jq_path=None,
+            equals=None,
+        )
+    failures = exc_info.value.detail["failures"]
+    assert len(failures) == 2
+    assert {f["mode"] for f in failures} == {"status", "contains"}
+
+
+def test_eval_missing_jq_is_configerror(grpc_result_ok, monkeypatch):
+    """Missing jq lib surfaces as ConfigError with grpc extra hint."""
+    import agctl.assertions as assertions_module
+
+    # Mock _jq to raise ConfigError (simulating missing jq library)
+    def mock_jq_error():
+        raise ConfigError(
+            "jq is required for match/path assertions: pip install 'agctl[db]' or 'agctl[kafka]'",
+            {},
+        )
+
+    monkeypatch.setattr(assertions_module, "_jq", mock_jq_error)
+
+    # Now jq import should fail and surface ConfigError with grpc hint
+    with pytest.raises(ConfigError, match="agctl\\[grpc\\]"):
+        evaluate_grpc_assertions(grpc_result_ok, match=".x")
diff --git a/tests/unit/test_grpc_client.py b/tests/unit/test_grpc_client.py
new file mode 100644
index 0000000..e855b4c
--- /dev/null
+++ b/tests/unit/test_grpc_client.py
@@ -0,0 +1,1212 @@
+"""Tests for GrpcClient DTOs and skeleton construction."""
+
+import sys
+from unittest.mock import patch
+
+import pytest
+# Module-level skip guards: this test suite requires grpc and protobuf extras.
+# pytest.importorskip at module level causes pytest to skip the entire module
+# at collection time if the extras are absent, preserving the project invariant
+# that the unit suite is collectable without optional extras installed.
+pytest.importorskip("grpc")
+pytest.importorskip("google.protobuf")
+
+from agctl.clients.grpc_client import (
+    GrpcClient,
+    GrpcHealthResult,
+    GrpcStatus,
+    GrpcStreamMessage,
+    GrpcUnaryResult,
+)
+from agctl.config.models import GrpcTarget, GrpcTls
+from agctl.errors import ConfigError
+
+
+def test_status_and_result_dataclasses():
+    """Test that all DTOs construct correctly and defaults apply."""
+    # GrpcStatus with default message
+    status = GrpcStatus(code=0, name="OK")
+    assert status.code == 0
+    assert status.name == "OK"
+    assert status.message == ""  # default
+
+    # GrpcUnaryResult with all fields
+    status = GrpcStatus(code=0, name="OK", message="success")
+    result = GrpcUnaryResult(
+        target="localhost:50051",
+        service="MyService",
+        method="MyMethod",
+        call_type="unary",
+        status=status,
+        message={"data": "test"},
+        initial_metadata={"header": "value"},
+        trailers={"trailer": "end"},
+    )
+    assert result.target == "localhost:50051"
+    assert result.service == "MyService"
+    assert result.method == "MyMethod"
+    assert result.call_type == "unary"
+    assert result.status.code == 0
+    assert result.status.name == "OK"
+    assert result.status.message == "success"
+    assert result.message == {"data": "test"}
+    assert result.initial_metadata == {"header": "value"}
+    assert result.trailers == {"trailer": "end"}
+
+    # GrpcUnaryResult with None message (allowed)
+    result_no_msg = GrpcUnaryResult(
+        target="localhost:50051",
+        service="MyService",
+        method="MyMethod",
+        call_type="unary",
+        status=status,
+        message=None,
+        initial_metadata={},
+        trailers={},
+    )
+    assert result_no_msg.message is None
+
+    # GrpcStreamMessage with None trailers (allowed)
+    stream_msg = GrpcStreamMessage(
+        message={"chunk": "data"},
+        trailers=None,
+    )
+    assert stream_msg.message == {"chunk": "data"}
+    assert stream_msg.trailers is None
+
+    # GrpcHealthResult with default note
+    health = GrpcHealthResult(
+        target="localhost:50051",
+        address="localhost:50051",
+        status="SERVING",
+    )
+    assert health.target == "localhost:50051"
+    assert health.address == "localhost:50051"
+    assert health.status == "SERVING"
+    assert health.note is None  # default
+
+
+def test_client_uses_injected_channel_and_skips_grpcio_import():
+    """Test that injected channel/pool are stored and grpcio is NOT imported."""
+    target = GrpcTarget(address="localhost:50051")
+    injected_channel = object()
+    injected_pool = object()
+
+    client = GrpcClient(
+        target,
+        channel=injected_channel,
+        descriptor_pool=injected_pool,
+        timeout_seconds=5.0,
+    )
+
+    # Should store injected objects
+    assert client._channel is injected_channel
+    assert client._pool is injected_pool
+    assert client._target is target
+    assert client._timeout == 5.0
+
+    # Should NOT have imported grpcio (no _grpc attribute set)
+    assert getattr(client, "_grpc", None) is None
+
+
+def test_client_missing_extra_when_no_channel():
+    """Test that missing grpcio extra raises ConfigError when no channel injected."""
+    target = GrpcTarget(address="localhost:50051")
+
+    # Mock the import of grpc by making it raise ImportError
+    import builtins
+
+    original_import = builtins.__import__
+
+    def mock_import(name, *args, **kwargs):
+        if name == "grpc":
+            raise ImportError("No module named 'grpc'")
+        return original_import(name, *args, **kwargs)
+
+    with patch("builtins.__import__", side_effect=mock_import):
+        with pytest.raises(ConfigError) as exc_info:
+            GrpcClient(target)
+
+    # Error message should mention the grpc extra
+    assert "agctl[grpc]" in str(exc_info.value)
+
+
+# Task 5: Descriptor resolution tests (require protobuf)
+pytest.importorskip("google.protobuf")
+
+# Import descriptor-related modules only when protobuf is available
+from google.protobuf import descriptor_pool
+
+
+def test_resolve_descriptors_uses_injected_pool():
+    """Test that injected pool is returned as-is without reflection call."""
+    target = GrpcTarget(address="localhost:50051")
+    injected_channel = object()
+    sentinel_pool = object()  # Sentinel to verify exact object returned
+
+    client = GrpcClient(
+        target,
+        channel=injected_channel,
+        descriptor_pool=sentinel_pool,
+        timeout_seconds=5.0,
+    )
+
+    # Should return the injected pool without any reflection
+    pool = client.resolve_descriptors()
+    assert pool is sentinel_pool
+
+
+def test_find_method_from_echo_descriptor():
+    """Test find_method and call_type_of with echo descriptor pool."""
+    # Load the echo descriptor and build a pool
+    import pathlib
+    from google.protobuf import descriptor_pb2
+
+    descriptor_path = (
+        pathlib.Path(__file__).parent.parent / "fixtures" / "echo_descriptor.pb"
+    )
+    descriptor_bytes = descriptor_path.read_bytes()
+
+    # Parse the FileDescriptorSet
+    file_descriptor_set = descriptor_pb2.FileDescriptorSet()
+    file_descriptor_set.ParseFromString(descriptor_bytes)
+
+    pool = descriptor_pool.DescriptorPool()
+    for file_desc in file_descriptor_set.file:
+        pool.Add(file_desc)
+
+    target = GrpcTarget(address="localhost:50051", reflection="off")
+    injected_channel = object()
+
+    client = GrpcClient(
+        target,
+        channel=injected_channel,
+        descriptor_pool=pool,
+        timeout_seconds=5.0,
+    )
+
+    # Test each method and its call type
+    unary_method = client.find_method("echo.Echo", "Unary")
+    assert client.call_type_of(unary_method) == "unary"
+
+    server_stream_method = client.find_method("echo.Echo", "ServerStream")
+    assert client.call_type_of(server_stream_method) == "server_stream"
+
+    client_stream_method = client.find_method("echo.Echo", "ClientStream")
+    assert client.call_type_of(client_stream_method) == "client_stream"
+
+    bidi_method = client.find_method("echo.Echo", "Bidi")
+    assert client.call_type_of(bidi_method) == "bidi"
+
+
+def test_find_method_unknown_service_and_method():
+    """Test that unknown service/method raises TemplateNotFound."""
+    # Load the echo descriptor and build a pool
+    import pathlib
+    from google.protobuf import descriptor_pb2
+
+    descriptor_path = (
+        pathlib.Path(__file__).parent.parent / "fixtures" / "echo_descriptor.pb"
+    )
+    descriptor_bytes = descriptor_path.read_bytes()
+
+    # Parse the FileDescriptorSet
+    file_descriptor_set = descriptor_pb2.FileDescriptorSet()
+    file_descriptor_set.ParseFromString(descriptor_bytes)
+
+    pool = descriptor_pool.DescriptorPool()
+    for file_desc in file_descriptor_set.file:
+        pool.Add(file_desc)
+
+    target = GrpcTarget(address="localhost:50051", reflection="off")
+    injected_channel = object()
+
+    client = GrpcClient(
+        target,
+        channel=injected_channel,
+        descriptor_pool=pool,
+        timeout_seconds=5.0,
+    )
+
+    # Unknown service should raise TemplateNotFound with detail "service"
+    from agctl.errors import TemplateNotFound
+
+    with pytest.raises(TemplateNotFound) as exc_info:
+        client.find_method("echo.Missing", "Unary")
+    assert exc_info.value.detail.get("service") == "echo.Missing"
+
+    # Unknown method should raise TemplateNotFound with detail "method"
+    with pytest.raises(TemplateNotFound) as exc_info:
+        client.find_method("echo.Echo", "Nope")
+    assert exc_info.value.detail.get("method") == "Nope"
+    assert exc_info.value.detail.get("service") == "echo.Echo"
+
+
+def test_resolve_reflection_unimplemented_off_path_no_descriptors_is_configerror():
+    """Test that with reflection off and no descriptors, ConfigError is raised."""
+    target = GrpcTarget(address="localhost:50051", reflection="off")
+    injected_channel = object()
+
+    client = GrpcClient(
+        target,
+        channel=injected_channel,
+        descriptor_pool=None,
+        descriptors=None,
+        timeout_seconds=5.0,
+    )
+
+    # Should raise ConfigError mentioning grpc.descriptors
+    with pytest.raises(ConfigError) as exc_info:
+        client.resolve_descriptors()
+    assert "grpc.descriptors" in str(exc_info.value)
+
+
+def test_resolve_descriptors_with_fake_reflection_stub():
+    """Test resolve_descriptors with fake reflection stub using file_containing_symbol."""
+    pytest.importorskip("grpc_reflection")
+
+    import pathlib
+    from google.protobuf import descriptor_pb2
+    from grpc_reflection.v1alpha import reflection_pb2
+
+    # Load the echo descriptor fixture
+    descriptor_path = (
+        pathlib.Path(__file__).parent.parent / "fixtures" / "echo_descriptor.pb"
+    )
+    descriptor_bytes = descriptor_path.read_bytes()
+
+    # Parse the FileDescriptorSet
+    file_descriptor_set = descriptor_pb2.FileDescriptorSet()
+    file_descriptor_set.ParseFromString(descriptor_bytes)
+
+    # Create fake reflection stub that responds to file_containing_symbol requests
+    class FakeReflectionStub:
+        def ServerReflectionInfo(self, request_iterator):
+            """Yield responses for list_services and file_containing_symbol requests."""
+            for request in request_iterator:
+                if request.HasField("list_services"):
+                    # Respond with the echo.Echo service
+                    list_response = reflection_pb2.ServerReflectionResponse(
+                        list_services_response=reflection_pb2.ListServiceResponse(
+                            service=[reflection_pb2.ServiceResponse(name="echo.Echo")]
+                        )
+                    )
+                    yield list_response
+                elif request.HasField("file_containing_symbol"):
+                    # Respond with the echo descriptor file
+                    file_descriptor_response = reflection_pb2.FileDescriptorResponse(
+                        file_descriptor_proto=[fd.SerializeToString() for fd in file_descriptor_set.file]
+                    )
+                    yield reflection_pb2.ServerReflectionResponse(
+                        file_descriptor_response=file_descriptor_response
+                    )
+
+    # Create a fake channel with our reflection stub
+    class FakeChannel:
+        def __init__(self):
+            self._reflection_stub = FakeReflectionStub()
+
+    # Monkey-patch the ServerReflectionStub creation to use our fake
+    import grpc_reflection.v1alpha.reflection_pb2_grpc as reflection_grpc
+    original_stub = reflection_grpc.ServerReflectionStub
+
+    def fake_stub_factory(channel):
+        if isinstance(channel, FakeChannel):
+            return channel._reflection_stub
+        return original_stub(channel)
+
+    target = GrpcTarget(address="localhost:50051", reflection="on")
+    fake_channel = FakeChannel()
+
+    client = GrpcClient(
+        target,
+        channel=fake_channel,
+        descriptor_pool=None,
+        descriptors=None,
+        timeout_seconds=5.0,
+    )
+
+    with patch.object(reflection_grpc, "ServerReflectionStub", side_effect=fake_stub_factory):
+        # Should resolve descriptors via reflection
+        pool = client.resolve_descriptors()
+
+        # Verify the pool contains the echo.Echo service
+        service_desc = pool.FindServiceByName("echo.Echo")
+        assert service_desc is not None
+        assert "Unary" in service_desc.methods_by_name
+        assert "ServerStream" in service_desc.methods_by_name
+
+        # Verify find_method works with the resolved pool
+        unary_method = client.find_method("echo.Echo", "Unary")
+        assert client.call_type_of(unary_method) == "unary"
+
+        server_stream_method = client.find_method("echo.Echo", "ServerStream")
+        assert client.call_type_of(server_stream_method) == "server_stream"
+
+
+# Task 6: Call type tests (require protobuf and grpcio)
+pytest.importorskip("google.protobuf")
+pytest.importorskip("grpc")
+
+# Import grpc-related modules only when available
+import grpc
+from google.protobuf import descriptor_pool, descriptor_pb2, message_factory
+import pathlib
+
+
+class _FakeRpcError(grpc.RpcError):
+    """Fake RpcError for testing."""
+
+    def __init__(self, code, details=""):
+        self._code = code
+        self._details = details
+        super().__init__(details)
+
+    def code(self):
+        return self._code
+
+    def details(self):
+        return self._details
+
+
+class _FakeCall:
+    """Fake call object for metadata capture."""
+
+    def __init__(self, initial_metadata=(), trailing_metadata=()):
+        self._initial_metadata = initial_metadata
+        self._trailing_metadata = trailing_metadata
+
+    def initial_metadata(self):
+        return self._initial_metadata
+
+    def trailing_metadata(self):
+        return self._trailing_metadata
+
+
+class _FakeStreamIterator:
+    """Fake stream iterator that models real grpcio.
+
+    Real grpcio's stream iterable (_MultiThreadedRendezvous) inherits
+    trailing_metadata() from Call DIRECTLY on the iterable; there is no
+    _call sub-object (the cython IntegratedCall does not expose it). Mirror
+    that so the trailer-capture code path is exercised against the production
+    behavior. See review finding I2.
+    """
+
+    def __init__(self, items, trailing_metadata=()):
+        self._items = items
+        self._trailing_metadata = trailing_metadata
+
+    def __iter__(self):
+        return iter(self._items)
+
+    def trailing_metadata(self):
+        return self._trailing_metadata
+
+
+class _FakeChannel:
+    """Fake gRPC channel for testing call methods."""
+
+    def __init__(self, response_data=None, error=None, stream_responses=None):
+        self._response_data = response_data
+        self._error = error
+        self._stream_responses = stream_responses or []
+        self._initial_metadata = (("x-request-id", "abc"),)
+        self._trailing_metadata = (("x-trailer", "end"),)
+
+    def _fake_serializer(self, req_bytes):
+        """Fake serializer that just passes bytes through."""
+        return req_bytes
+
+    def _fake_deserializer(self, resp_bytes):
+        """Fake deserializer that just passes bytes through."""
+        return resp_bytes
+
+    def unary_unary(self, full_method, *, request_serializer=None, response_deserializer=None):
+        """Fake unary_unary callable."""
+
+        def invoker(request_bytes, metadata=None, timeout=None):
+            if self._error:
+                raise self._error
+            # Deserialize the response bytes if deserializer provided
+            if response_deserializer and self._response_data is not None:
+                resp_dict = response_deserializer(self._response_data)
+            else:
+                resp_dict = self._response_data
+            return resp_dict, _FakeCall(self._initial_metadata, self._trailing_metadata)
+
+        invoker.with_call = invoker  # Alias for with_call to same function
+        return invoker
+
+    def unary_stream(self, full_method, *, request_serializer=None, response_deserializer=None):
+        """Fake unary_stream callable."""
+
+        def invoker(request_bytes, metadata=None, timeout=None):
+            if self._error:
+                raise self._error
+            # Deserialize and yield response dicts
+            items = []
+            for resp_bytes in self._stream_responses:
+                if response_deserializer:
+                    items.append(response_deserializer(resp_bytes))
+                else:
+                    items.append(resp_bytes)
+            return _FakeStreamIterator(items, self._trailing_metadata)
+
+        return invoker
+
+    def stream_unary(self, full_method, *, request_serializer=None, response_deserializer=None):
+        """Fake stream_unary callable."""
+
+        def invoker(request_iter, metadata=None, timeout=None):
+            if self._error:
+                raise self._error
+            # Consume iterator and return single deserialized response
+            list(request_iter)  # Drain the iterator
+            if response_deserializer and self._response_data is not None:
+                return response_deserializer(self._response_data)
+            return self._response_data
+
+        return invoker
+
+    def stream_stream(self, full_method, *, request_serializer=None, response_deserializer=None):
+        """Fake stream_stream callable."""
+
+        def invoker(request_iter, metadata=None, timeout=None):
+            if self._error:
+                raise self._error
+            # Consume iterator and yield deserialized responses
+            list(request_iter)  # Drain the iterator
+            items = []
+            for resp_bytes in self._stream_responses:
+                if response_deserializer:
+                    items.append(response_deserializer(resp_bytes))
+                else:
+                    items.append(resp_bytes)
+            return _FakeStreamIterator(items, self._trailing_metadata)
+
+        return invoker
+
+
+def _setup_echo_client(fake_channel):
+    """Create a client with echo descriptor pool and fake channel."""
+    descriptor_path = (
+        pathlib.Path(__file__).parent.parent / "fixtures" / "echo_descriptor.pb"
+    )
+    descriptor_bytes = descriptor_path.read_bytes()
+
+    file_descriptor_set = descriptor_pb2.FileDescriptorSet()
+    file_descriptor_set.ParseFromString(descriptor_bytes)
+
+    pool = descriptor_pool.DescriptorPool()
+    for file_desc in file_descriptor_set.file:
+        pool.Add(file_desc)
+
+    target = GrpcTarget(address="localhost:50051", reflection="off")
+
+    client = GrpcClient(
+        target,
+        channel=fake_channel,
+        descriptor_pool=pool,
+        timeout_seconds=5.0,
+    )
+    return client
+
+
+def _serialize_response_message(response_dict):
+    """Serialize a response dict to bytes using the Response message class."""
+    # Load descriptor to get message class
+    descriptor_path = (
+        pathlib.Path(__file__).parent.parent / "fixtures" / "echo_descriptor.pb"
+    )
+    descriptor_bytes = descriptor_path.read_bytes()
+
+    file_descriptor_set = descriptor_pb2.FileDescriptorSet()
+    file_descriptor_set.ParseFromString(descriptor_bytes)
+
+    pool = descriptor_pool.DescriptorPool()
+    for file_desc in file_descriptor_set.file:
+        pool.Add(file_desc)
+
+    # Get Response message descriptor and class
+    response_desc = pool.FindMessageTypeByName("echo.Response")
+    response_class = message_factory.GetMessageClass(response_desc)
+
+    # Serialize dict to bytes via protobuf
+    from google.protobuf import json_format
+
+    msg = response_class()
+    json_format.ParseDict(response_dict, msg, ignore_unknown_fields=False)
+    return msg.SerializeToString()
+
+
+def test_call_unary_success():
+    """Test unary call success with metadata and trailers."""
+    # Serialize the expected response
+    response_dict = {"msg": "hi", "n": 3}
+    response_bytes = _serialize_response_message(response_dict)
+
+    fake_channel = _FakeChannel(response_data=response_bytes)
+    client = _setup_echo_client(fake_channel)
+
+    result = client.call_unary("echo.Echo", "Unary", {"msg": "hi"})
+
+    assert result.call_type == "unary"
+    assert result.status.code == 0
+    assert result.status.name == "OK"
+    assert result.message == {"msg": "hi", "n": 3}
+    assert result.initial_metadata == {"x-request-id": "abc"}
+    assert result.trailers == {"x-trailer": "end"}
+
+
+def test_call_unary_nonok_status_is_result():
+    """Test that non-OK status is returned as result, not raised."""
+    # Create fake RpcError with NOT_FOUND status
+    error = _FakeRpcError(code=grpc.StatusCode.NOT_FOUND, details="nope")
+
+    fake_channel = _FakeChannel(error=error)
+    client = _setup_echo_client(fake_channel)
+
+    result = client.call_unary("echo.Echo", "Unary", {"msg": "hi"})
+
+    # Should return result with error status, NOT raise
+    assert result.status.name == "NOT_FOUND"
+    assert result.status.code == grpc.StatusCode.NOT_FOUND.value[0]
+    assert result.status.message == "nope"
+    assert result.message is None
+
+
+def test_call_unary_deadline_is_operation_timeout():
+    """Test that DEADLINE_EXCEEDED raises OperationTimeout."""
+    from agctl.errors import OperationTimeout
+
+    # Create fake RpcError with DEADLINE_EXCEEDED status
+    error = _FakeRpcError(code=grpc.StatusCode.DEADLINE_EXCEEDED, details="timeout")
+
+    fake_channel = _FakeChannel(error=error)
+    client = _setup_echo_client(fake_channel)
+
+    # Should raise OperationTimeout
+    with pytest.raises(OperationTimeout):
+        client.call_unary("echo.Echo", "Unary", {"msg": "hi"})
+
+
+def test_call_unary_bad_request_json_is_configerror():
+    """Test that unknown field in request JSON raises ConfigError."""
+    fake_channel = _FakeChannel(response_data=b"")  # Won't be called
+    client = _setup_echo_client(fake_channel)
+
+    # Request with unknown field should fail during serialization
+    with pytest.raises(ConfigError):
+        client.call_unary("echo.Echo", "Unary", {"unknown_field": 1})
+
+
+def test_call_server_stream_yields_messages():
+    """Test server streaming yields multiple messages with trailers on final."""
+    # Create two response messages
+    response1_bytes = _serialize_response_message({"msg": "first", "n": 1})
+    response2_bytes = _serialize_response_message({"msg": "second", "n": 2})
+
+    fake_channel = _FakeChannel(stream_responses=[response1_bytes, response2_bytes])
+    client = _setup_echo_client(fake_channel)
+
+    messages = list(client.call_server_stream("echo.Echo", "ServerStream", {"msg": "x"}))
+
+    assert len(messages) == 2
+    assert messages[0].message == {"msg": "first", "n": 1}
+    assert messages[0].trailers is None  # First message has no trailers
+    assert messages[1].message == {"msg": "second", "n": 2}
+    assert messages[1].trailers == {"x-trailer": "end"}  # Final message has trailers
+
+
+def test_call_client_stream_returns_single_result():
+    """Test client streaming returns single result from request iterator."""
+    # Serialize the expected response
+    response_dict = {"msg": "done", "n": 2}
+    response_bytes = _serialize_response_message(response_dict)
+
+    fake_channel = _FakeChannel(response_data=response_bytes)
+    client = _setup_echo_client(fake_channel)
+
+    result = client.call_client_stream(
+        service="echo.Echo", method="ClientStream", request_json_iter=iter([{"msg": "a"}, {"msg": "b"}])
+    )
+
+    assert result.call_type == "client_stream"
+    assert result.status.code == 0
+    assert result.status.name == "OK"
+    assert result.message == {"msg": "done", "n": 2}
+
+
+def test_call_bidi_yields_messages():
+    """Test bidirectional streaming yields multiple messages with trailers on final."""
+    # Create two response messages
+    response1_bytes = _serialize_response_message({"msg": "echo1", "n": 1})
+    response2_bytes = _serialize_response_message({"msg": "echo2", "n": 2})
+
+    fake_channel = _FakeChannel(stream_responses=[response1_bytes, response2_bytes])
+    client = _setup_echo_client(fake_channel)
+
+    messages = list(client.call_bidi(service="echo.Echo", method="Bidi", request_json_iter=iter([{"msg": "a"}])))
+
+    assert len(messages) == 2
+    assert messages[0].message == {"msg": "echo1", "n": 1}
+    assert messages[0].trailers is None  # First message has no trailers
+    assert messages[1].message == {"msg": "echo2", "n": 2}
+    assert messages[1].trailers == {"x-trailer": "end"}  # Final message has trailers
+
+
+# Task 7: healthcheck tests (require grpc_health)
+def test_healthcheck_serving():
+    """Test healthcheck returns SERVING status on success."""
+    pytest.importorskip("grpc_health")
+
+    from grpc_health.v1 import health_pb2
+
+    # Create serialized HealthCheckResponse with SERVING status
+    response = health_pb2.HealthCheckResponse(status=health_pb2.HealthCheckResponse.ServingStatus.SERVING)
+    response_bytes = response.SerializeToString()
+
+    # Create fake channel that returns the canned response
+    class _FakeHealthChannel:
+        def unary_unary(self, full_method, *, request_serializer=None, response_deserializer=None, _registered_method=False):
+            """Fake unary_unary that returns canned health check response."""
+            def invoker(request_bytes, metadata=None, timeout=None):
+                # Deserialize using the health protobuf
+                if response_deserializer:
+                    return response_deserializer(response_bytes)
+                return response_bytes
+            return invoker
+
+        def unary_stream(self, full_method, *, request_serializer=None, response_deserializer=None, _registered_method=False):
+            """Fake unary_stream (not used by healthcheck but required by HealthStub)."""
+            def invoker(request_bytes, metadata=None, timeout=None):
+                return iter([])
+            return invoker
+
+    target = GrpcTarget(address="localhost:50051")
+    client = GrpcClient(target, channel=_FakeHealthChannel(), timeout_seconds=5.0)
+
+    result = client.healthcheck()
+
+    assert result.target == "localhost:50051"
+    assert result.address == "localhost:50051"
+    assert result.status == "SERVING"
+    assert result.note is None
+
+
+def test_healthcheck_unimplemented_is_unknown():
+    """Test healthcheck returns UNKNOWN status on UNIMPLEMENTED RpcError."""
+    pytest.importorskip("grpc_health")
+
+    # Create fake RpcError with UNIMPLEMENTED status
+    error = _FakeRpcError(code=grpc.StatusCode.UNIMPLEMENTED, details="health not implemented")
+
+    # Create fake channel that raises UNIMPLEMENTED error
+    class _FakeHealthChannel:
+        def unary_unary(self, full_method, *, request_serializer=None, response_deserializer=None, _registered_method=False):
+            """Fake unary_unary that raises UNIMPLEMENTED error."""
+            def invoker(request_bytes, metadata=None, timeout=None):
+                raise error
+            return invoker
+
+        def unary_stream(self, full_method, *, request_serializer=None, response_deserializer=None, _registered_method=False):
+            """Fake unary_stream (not used by healthcheck but required by HealthStub)."""
+            def invoker(request_bytes, metadata=None, timeout=None):
+                return iter([])
+            return invoker
+
+    target = GrpcTarget(address="localhost:50051")
+    client = GrpcClient(target, channel=_FakeHealthChannel(), timeout_seconds=5.0)
+
+    result = client.healthcheck()
+
+    assert result.target == "localhost:50051"
+    assert result.address == "localhost:50051"
+    assert result.status == "UNKNOWN"
+    assert result.note == "health service UNIMPLEMENTED"
+
+
+def test_healthcheck_deadline_is_timeout():
+    """Test healthcheck raises OperationTimeout on DEADLINE_EXCEEDED."""
+    pytest.importorskip("grpc_health")
+
+    from agctl.errors import OperationTimeout
+
+    # Create fake RpcError with DEADLINE_EXCEEDED status
+    error = _FakeRpcError(code=grpc.StatusCode.DEADLINE_EXCEEDED, details="timeout")
+
+    # Create fake channel that raises DEADLINE_EXCEEDED error
+    class _FakeHealthChannel:
+        def unary_unary(self, full_method, *, request_serializer=None, response_deserializer=None, _registered_method=False):
+            """Fake unary_unary that raises DEADLINE_EXCEEDED error."""
+            def invoker(request_bytes, metadata=None, timeout=None):
+                raise error
+            return invoker
+
+        def unary_stream(self, full_method, *, request_serializer=None, response_deserializer=None, _registered_method=False):
+            """Fake unary_stream (not used by healthcheck but required by HealthStub)."""
+            def invoker(request_bytes, metadata=None, timeout=None):
+                return iter([])
+            return invoker
+
+    target = GrpcTarget(address="localhost:50051")
+    client = GrpcClient(target, channel=_FakeHealthChannel(), timeout_seconds=5.0)
+
+    # Should raise OperationTimeout
+    with pytest.raises(OperationTimeout):
+        client.healthcheck()
+
+
+# Finding 1: mTLS config tests
+def test_mtls_honors_ca_location_file_bytes():
+    """Test that mTLS ca_location field is read and passed to ssl_channel_credentials."""
+    import tempfile
+
+    # Create a temporary PEM file
+    ca_pem = b"-----BEGIN CERTIFICATE-----\nfake CA cert\n-----END CERTIFICATE-----"
+    with tempfile.NamedTemporaryFile(mode="wb", suffix=".pem", delete=False) as f:
+        f.write(ca_pem)
+        ca_path = f.name
+
+    try:
+        # Mock ssl_channel_credentials to capture arguments
+        import grpc
+        original_ssl_cred = grpc.ssl_channel_credentials
+        ssl_creds_calls = []
+
+        def fake_ssl_creds(root_certificates=None, certificate_chain=None, private_key=None):
+            ssl_creds_calls.append({
+                "root_certificates": root_certificates,
+                "certificate_chain": certificate_chain,
+                "private_key": private_key,
+            })
+            return original_ssl_cred(root_certificates, certificate_chain, private_key)
+
+        with patch.object(grpc, "ssl_channel_credentials", side_effect=fake_ssl_creds):
+            target = GrpcTarget(
+                address="localhost:50051",
+                use_tls=True,
+                tls=GrpcTls(ca_location=ca_path)
+            )
+
+            # This should trigger reading the CA file and passing bytes to ssl_channel_credentials
+            GrpcClient(target)
+
+            # Verify ssl_channel_credentials was called with the CA file bytes
+            assert len(ssl_creds_calls) == 1
+            assert ssl_creds_calls[0]["root_certificates"] == ca_pem
+            assert ssl_creds_calls[0]["certificate_chain"] is None
+            assert ssl_creds_calls[0]["private_key"] is None
+    finally:
+        import os
+        os.unlink(ca_path)
+
+
+def test_mtls_ca_location_nonexistent_file_raises_configerror():
+    """Test that non-existent ca_location file raises ConfigError."""
+    target = GrpcTarget(
+        address="localhost:50051",
+        use_tls=True,
+        tls=GrpcTls(ca_location="/nonexistent/ca.pem")
+    )
+
+    with pytest.raises(ConfigError) as exc_info:
+        GrpcClient(target)
+
+    assert "tls.ca_location file not readable" in str(exc_info.value)
+    assert exc_info.value.detail.get("path") == "/nonexistent/ca.pem"
+
+
+def test_mtls_empty_string_counts_as_unset():
+    """Test that empty string for TLS fields counts as unset (no error)."""
+    import grpc
+
+    # Mock ssl_channel_credentials to verify it's called with None
+    original_ssl_cred = grpc.ssl_channel_credentials
+    ssl_creds_calls = []
+
+    def fake_ssl_creds(root_certificates=None, certificate_chain=None, private_key=None):
+        ssl_creds_calls.append({
+            "root_certificates": root_certificates,
+            "certificate_chain": certificate_chain,
+            "private_key": private_key,
+        })
+        return original_ssl_cred(root_certificates, certificate_chain, private_key)
+
+    with patch.object(grpc, "ssl_channel_credentials", side_effect=fake_ssl_creds):
+        target = GrpcTarget(
+            address="localhost:50051",
+            use_tls=True,
+            tls=GrpcTls(ca_location="", certificate_location="", key_location="")
+        )
+
+        GrpcClient(target)
+
+        # Verify ssl_channel_credentials was called with None for all fields
+        assert len(ssl_creds_calls) == 1
+        assert ssl_creds_calls[0]["root_certificates"] is None
+        assert ssl_creds_calls[0]["certificate_chain"] is None
+        assert ssl_creds_calls[0]["private_key"] is None
+
+
+def test_mtls_override_authority_applied_to_channel():
+    """Test that override_authority is applied to the channel."""
+    import grpc
+
+    # Mock secure_channel to capture options
+    original_secure_channel = grpc.secure_channel
+    secure_channel_calls = []
+
+    def fake_secure_channel(address, credentials, options=None):
+        secure_channel_calls.append({
+            "address": address,
+            "credentials": credentials,
+            "options": options,
+        })
+        # Return a fake channel object
+        class FakeChannel:
+            pass
+        return FakeChannel()
+
+    with patch.object(grpc, "secure_channel", side_effect=fake_secure_channel):
+        target = GrpcTarget(
+            address="localhost:50051",
+            use_tls=True,
+            tls=GrpcTls(override_authority="example.com")
+        )
+
+        GrpcClient(target)
+
+        # Verify secure_channel was called with override options
+        assert len(secure_channel_calls) == 1
+        options = secure_channel_calls[0]["options"]
+        assert options is not None
+        assert ("grpc.ssl_target_name_override", "example.com") in options
+        assert ("grpc.authority", "example.com") in options
+
+
+# Finding 2a: Streaming mid-run error tests
+def test_server_stream_midstream_rpcerror_captures_terminal_status():
+    """Test that mid-stream RpcError is captured into terminal_status and ends iteration."""
+    import grpc
+
+    # Create a fake stream that yields one message then raises RpcError
+    class _FakeStreamWithError:
+        def __init__(self):
+            self._yield_count = 0
+
+        def __iter__(self):
+            return self
+
+        def __next__(self):
+            self._yield_count += 1
+            if self._yield_count == 1:
+                return {"msg": "first"}
+            else:
+                # Raise INTERNAL error on second iteration
+                raise _FakeRpcError(code=grpc.StatusCode.INTERNAL, details="stream error")
+
+    # Create fake channel that raises error during iteration
+    class _FakeChannelWithStreamError:
+        def unary_stream(self, full_method, *, request_serializer=None, response_deserializer=None):
+            def invoker(request_bytes, metadata=None, timeout=None):
+                return _FakeStreamWithError()
+            return invoker
+
+    client = _setup_echo_client(_FakeChannelWithStreamError())
+
+    # Stream should capture the error in terminal_status and stop iteration
+    messages = list(client.call_server_stream("echo.Echo", "ServerStream", {"msg": "x"}))
+
+    # Should have received the first message before the error
+    assert len(messages) == 1
+    assert messages[0].message == {"msg": "first"}
+
+    # Terminal status should capture the INTERNAL error
+    assert client.terminal_status.name == "INTERNAL"
+    assert client.terminal_status.message == "stream error"
+
+
+def test_server_stream_deadline_raises_operation_timeout():
+    """Test that DEADLINE_EXCEEDED during server stream iteration raises OperationTimeout."""
+    from agctl.errors import OperationTimeout
+    import grpc
+
+    # Create a fake stream that raises DEADLINE_EXCEEDED immediately
+    class _FakeStreamWithDeadline:
+        def __iter__(self):
+            raise _FakeRpcError(code=grpc.StatusCode.DEADLINE_EXCEEDED, details="timeout")
+
+    # Create fake channel that raises error during iteration
+    class _FakeChannelWithDeadline:
+        def unary_stream(self, full_method, *, request_serializer=None, response_deserializer=None):
+            def invoker(request_bytes, metadata=None, timeout=None):
+                return _FakeStreamWithDeadline()
+            return invoker
+
+    client = _setup_echo_client(_FakeChannelWithDeadline())
+
+    # Should raise OperationTimeout
+    with pytest.raises(OperationTimeout):
+        list(client.call_server_stream("echo.Echo", "ServerStream", {"msg": "x"}))
+
+
+def test_bidi_midstream_rpcerror_captures_terminal_status():
+    """Test that mid-stream RpcError in bidi is captured into terminal_status and ends iteration."""
+    import grpc
+
+    # Create a fake stream that yields one message then raises RpcError
+    class _FakeStreamWithError:
+        def __init__(self):
+            self._yield_count = 0
+
+        def __iter__(self):
+            return self
+
+        def __next__(self):
+            self._yield_count += 1
+            if self._yield_count == 1:
+                return {"msg": "first"}
+            else:
+                # Raise RESOURCE_EXHAUSTED error on second iteration
+                raise _FakeRpcError(code=grpc.StatusCode.RESOURCE_EXHAUSTED, details="out of resources")
+
+    # Create fake channel that raises error during iteration
+    class _FakeChannelWithStreamError:
+        def stream_stream(self, full_method, *, request_serializer=None, response_deserializer=None):
+            def invoker(request_iter, metadata=None, timeout=None):
+                list(request_iter)  # Drain the iterator
+                return _FakeStreamWithError()
+            return invoker
+
+    client = _setup_echo_client(_FakeChannelWithStreamError())
+
+    # Stream should capture the error in terminal_status and stop iteration
+    messages = list(client.call_bidi(service="echo.Echo", method="Bidi", request_json_iter=iter([{"msg": "a"}])))
+
+    # Should have received the first message before the error
+    assert len(messages) == 1
+    assert messages[0].message == {"msg": "first"}
+
+    # Terminal status should capture the RESOURCE_EXHAUSTED error
+    assert client.terminal_status.name == "RESOURCE_EXHAUSTED"
+    assert client.terminal_status.message == "out of resources"
+
+
+# --- Review fix: C1 - eager stream pre-call serialization --------------------
+def test_call_client_stream_bad_request_json_is_configerror():
+    """C1: malformed request in client-stream iterator raises ConfigError pre-call.
+
+    Eager list-serialization makes the try/except guard live; the channel
+    invoker must never be reached (a generator expr would defer ser() past
+    the guard and surface as a false-green INTERNAL result inside grpcio).
+    """
+    class _TrackingChannel:
+        def __init__(self):
+            self.invoker_called = False
+
+        def stream_unary(self, full_method, *, request_serializer=None, response_deserializer=None):
+            def invoker(request_iter, metadata=None, timeout=None):
+                self.invoker_called = True
+                raise AssertionError("invoker must not be reached on bad request JSON")
+
+            return invoker
+
+    channel = _TrackingChannel()
+    client = _setup_echo_client(channel)
+
+    with pytest.raises(ConfigError) as exc_info:
+        client.call_client_stream(
+            service="echo.Echo",
+            method="ClientStream",
+            request_json_iter=iter([{"msg": "ok"}, {"unknown_field": 1}]),
+        )
+    assert "Failed to serialize request message" in str(exc_info.value)
+    assert channel.invoker_called is False
+
+
+def test_call_bidi_bad_request_json_is_configerror():
+    """C1: malformed request in bidi iterator raises ConfigError pre-call."""
+    class _TrackingChannel:
+        def __init__(self):
+            self.invoker_called = False
+
+        def stream_stream(self, full_method, *, request_serializer=None, response_deserializer=None):
+            def invoker(request_iter, metadata=None, timeout=None):
+                self.invoker_called = True
+                raise AssertionError("invoker must not be reached on bad request JSON")
+
+            return invoker
+
+    channel = _TrackingChannel()
+    client = _setup_echo_client(channel)
+
+    # call_bidi is a generator function: drive iteration to trigger the
+    # (eager, pre-RPC) serialization guard inside its body.
+    with pytest.raises(ConfigError) as exc_info:
+        list(
+            client.call_bidi(
+                service="echo.Echo",
+                method="Bidi",
+                request_json_iter=iter([{"unknown_field": 1}]),
+            )
+        )
+    assert "Failed to serialize request message" in str(exc_info.value)
+    assert channel.invoker_called is False
+
+
+# --- Review fix: I2 - stream trailers read off the iterable ------------------
+def test_call_server_stream_captures_trailers():
+    """I2: final server-stream message carries trailers read off the iterable.
+
+    Real grpcio exposes trailing_metadata() on the stream iterable itself
+    (_MultiThreadedRendezvous), not via a _call sub-object. The updated
+    _FakeStreamIterator models that shape; trailers must be the captured dict.
+    """
+    response1 = _serialize_response_message({"msg": "first", "n": 1})
+    response2 = _serialize_response_message({"msg": "second", "n": 2})
+    fake_channel = _FakeChannel(stream_responses=[response1, response2])
+    client = _setup_echo_client(fake_channel)
+
+    messages = list(client.call_server_stream("echo.Echo", "ServerStream", {"msg": "x"}))
+
+    assert len(messages) == 2
+    assert messages[0].trailers is None
+    assert messages[1].trailers == {"x-trailer": "end"}
+    assert messages[1].trailers is not None  # explicit: not None in production
+
+
+def test_call_bidi_captures_trailers():
+    """I2: final bidi message carries trailers read off the iterable."""
+    response1 = _serialize_response_message({"msg": "echo1", "n": 1})
+    response2 = _serialize_response_message({"msg": "echo2", "n": 2})
+    fake_channel = _FakeChannel(stream_responses=[response1, response2])
+    client = _setup_echo_client(fake_channel)
+
+    messages = list(
+        client.call_bidi(service="echo.Echo", method="Bidi", request_json_iter=iter([{"msg": "a"}]))
+    )
+
+    assert len(messages) == 2
+    assert messages[0].trailers is None
+    assert messages[1].trailers == {"x-trailer": "end"}
+    assert messages[1].trailers is not None
+
+
+# --- Review fix: I6 - unit coverage for _resolve_via_descriptors -------------
+from agctl.config.models import GrpcDescriptorSource
+
+
+def test_resolve_descriptors_descriptor_set_branch():
+    """I6: descriptor_set source builds a pool via resolve_descriptors()."""
+    descriptor_path = pathlib.Path(__file__).parent.parent / "fixtures" / "echo_descriptor.pb"
+
+    target = GrpcTarget(address="h:1", reflection="off")
+    client = GrpcClient(
+        target,
+        channel=object(),
+        descriptors=[GrpcDescriptorSource(descriptor_set=str(descriptor_path))],
+    )
+
+    pool = client.resolve_descriptors()
+    method = client.find_method("echo.Echo", "Unary")
+    assert client.call_type_of(method) == "unary"
+    # Pool resolves the service directly too
+    assert pool.FindServiceByName("echo.Echo") is not None
+
+
+def test_resolve_descriptors_proto_branch(tmp_path):
+    """I6: proto source compiles via protoc (honoring include_paths) and resolves."""
+    import shutil
+
+    src = pathlib.Path(__file__).parent.parent / "fixtures" / "echo.proto"
+    proto_file = tmp_path / "echo.proto"
+    shutil.copy(src, proto_file)
+
+    target = GrpcTarget(address="h:1", reflection="off")
+    client = GrpcClient(
+        target,
+        channel=object(),
+        descriptors=[
+            GrpcDescriptorSource(proto=str(proto_file), include_paths=[str(tmp_path)])
+        ],
+    )
+
+    client.resolve_descriptors()
+    method = client.find_method("echo.Echo", "Unary")
+    assert client.call_type_of(method) == "unary"
+
+
+def test_resolve_descriptors_protoc_failure_is_configerror(tmp_path):
+    """I4: a malformed proto yields ConfigError mentioning protoc (rc != 0)."""
+    # Unterminated service block -> protoc returns nonzero rc (does not raise)
+    proto_file = tmp_path / "bad.proto"
+    proto_file.write_text('syntax = "proto3";\npackage demo;\nservice X {\n')
+
+    target = GrpcTarget(address="h:1", reflection="off")
+    client = GrpcClient(
+        target,
+        channel=object(),
+        descriptors=[GrpcDescriptorSource(proto=str(proto_file))],
+    )
+
+    with pytest.raises(ConfigError) as exc_info:
+        client.resolve_descriptors()
+    assert "protoc" in str(exc_info.value)
+    assert exc_info.value.detail.get("proto") == str(proto_file)
+
+
+def test_resolve_descriptors_multi_file_out_of_order(tmp_path):
+    """I5: multi-file descriptor_set loads regardless of file arrival order.
+
+    protoc emits dependency-first order, so we deliberately reverse the
+    FileDescriptorSet.file list (importer before imported). The reversed order
+    breaks pool.Add with a TypeError ("Depends on file 'b.proto'..."); the
+    AddSerializedFile path tolerates it.
+    """
+    from google.protobuf import descriptor_pb2
+    from grpc_tools import protoc
+
+    (tmp_path / "b.proto").write_text(
+        'syntax = "proto3";\npackage demo;\nmessage B { string v = 1; }\n'
+    )
+    (tmp_path / "a.proto").write_text(
+        'syntax = "proto3";\npackage demo;\nimport "b.proto";\n'
+        "message A { B b = 1; }\n"
+        "service Demo { rpc Get(A) returns (A); }\n"
+    )
+    raw = tmp_path / "raw.pb"
+    rc = protoc.main(
+        [
+            "protoc",
+            "--include_imports",
+            "--proto_path",
+            str(tmp_path),
+            "--descriptor_set_out",
+            str(raw),
+            str(tmp_path / "a.proto"),
+        ]
+    )
+    assert rc == 0
+
+    # Reverse file order to force importer-before-imported.
+    fds = descriptor_pb2.FileDescriptorSet()
+    fds.ParseFromString(raw.read_bytes())
+    reversed_set = descriptor_pb2.FileDescriptorSet()
+    reversed_set.file.extend(reversed(fds.file))
+    descriptor_set = tmp_path / "reversed.pb"
+    descriptor_set.write_bytes(reversed_set.SerializeToString())
+
+    target = GrpcTarget(address="h:1", reflection="off")
+    client = GrpcClient(
+        target,
+        channel=object(),
+        descriptors=[GrpcDescriptorSource(descriptor_set=str(descriptor_set))],
+    )
+
+    pool = client.resolve_descriptors()
+    method = client.find_method("demo.Demo", "Get")
+    assert client.call_type_of(method) == "unary"
+    assert pool.FindMessageTypeByName("demo.A") is not None
+    assert pool.FindMessageTypeByName("demo.B") is not None
diff --git a/tests/unit/test_grpc_commands.py b/tests/unit/test_grpc_commands.py
new file mode 100644
index 0000000..330f9ee
--- /dev/null
+++ b/tests/unit/test_grpc_commands.py
@@ -0,0 +1,1134 @@
+"""Unit tests for `grpc call` command (DESIGN §3.3, D6).
+
+Tests inject a fake gRPC client via monkeypatch to `grpc_commands.new_grpc_client`,
+avoiding any real gRPC connection. The fake mirrors the GrpcClient contract.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import grpc
+import pytest
+from click.testing import CliRunner
+
+from agctl.cli import cli
+from agctl.clients.grpc_client import GrpcStatus, GrpcStreamMessage, GrpcUnaryResult, GrpcHealthResult
+from agctl.commands import grpc_commands
+from agctl.errors import ConfigError
+
+FIXTURE = Path(__file__).parent.parent / "fixtures" / "agctl.yaml"
+
+ENV = {
+    "ORDER_SERVICE_URL": "http://localhost:8081",
+    "PAYMENT_SERVICE_URL": "http://localhost:8082",
+    "PAYMENT_SERVICE_TOKEN": "tok",
+    "KAFKA_BROKER": "localhost",
+    "SCHEMA_REGISTRY_URL": "",
+    "DB_HOST": "h",
+    "DB_NAME": "n",
+    "DB_USER": "u",
+    "DB_PASSWORD": "p",
+    "ANALYTICS_DB_HOST": "ah",
+    "ANALYTICS_DB_USER": "au",
+    "ANALYTICS_DB_PASSWORD": "ap",
+    "TEST_GRPC_ADDR": "localhost:50051",
+}
+
+
+# ---------------------------------------------------------------------------
+# Fake gRPC client (test double)
+# ---------------------------------------------------------------------------
+
+
+class _FakeMethodDescriptor:
+    """Fake method descriptor for call type inspection."""
+
+    def __init__(self, client_streaming: bool = False, server_streaming: bool = False):
+        self.client_streaming = client_streaming
+        self.server_streaming = server_streaming
+
+
+class _FakeGrpcClient:
+    """Fake GrpcClient that returns canned results without touching gRPC."""
+
+    def __init__(self):
+        self._call_unary_result = GrpcUnaryResult(
+            target="localhost:50051",
+            service="echo.Echo",
+            method="Unary",
+            call_type="unary",
+            status=GrpcStatus(code=0, name="OK", message=""),
+            message={"msg": "hi"},
+            initial_metadata={},
+            trailers={},
+        )
+        self._call_client_stream_result = GrpcUnaryResult(
+            target="localhost:50051",
+            service="echo.Echo",
+            method="ClientStream",
+            call_type="client_stream",
+            status=GrpcStatus(code=0, name="OK", message=""),
+            message={"result": "ok"},
+            initial_metadata={},
+            trailers={},
+        )
+        self._healthcheck_result = GrpcHealthResult(
+            target="localhost:50051",
+            address="localhost:50051",
+            status="SERVING",
+            note=None,
+        )
+        self.terminal_status: GrpcStatus = GrpcStatus(0, "OK", "")
+        self.find_method_calls = []
+        self.call_unary_calls = []
+        self.call_client_stream_calls = []
+        self.call_server_stream_calls = []
+        self.call_bidi_calls = []
+        self.healthcheck_calls = []
+
+    def find_method(self, service: str, method: str) -> _FakeMethodDescriptor:
+        """Return a fake method descriptor."""
+        self.find_method_calls.append((service, method))
+        # Default to unary; tests can override by setting the descriptor type
+        return _FakeMethodDescriptor(client_streaming=False, server_streaming=False)
+
+    def call_type_of(self, method_desc) -> str:
+        """Determine call type from fake descriptor."""
+        if method_desc.client_streaming and method_desc.server_streaming:
+            return "bidi"
+        elif method_desc.server_streaming:
+            return "server_stream"
+        elif method_desc.client_streaming:
+            return "client_stream"
+        else:
+            return "unary"
+
+    def call_unary(
+        self,
+        service: str,
+        method: str,
+        message: dict,
+        *,
+        metadata: dict | None = None,
+        timeout: float | None = None,
+    ) -> GrpcUnaryResult:
+        """Return canned unary result."""
+        self.call_unary_calls.append(
+            {"service": service, "method": method, "message": message, "metadata": metadata, "timeout": timeout}
+        )
+        return self._call_unary_result
+
+    def call_client_stream(
+        self,
+        service: str,
+        method: str,
+        request_json_iter,
+        *,
+        metadata: dict | None = None,
+        timeout: float | None = None,
+    ) -> GrpcUnaryResult:
+        """Return canned client-stream result."""
+        messages = list(request_json_iter)
+        self.call_client_stream_calls.append(
+            {"service": service, "method": method, "messages": messages, "metadata": metadata, "timeout": timeout}
+        )
+        return self._call_client_stream_result
+
+    def call_server_stream(
+        self,
+        service: str,
+        method: str,
+        message: dict,
+        *,
+        metadata: dict | None = None,
+        timeout: float | None = None,
+    ):
+        """Yield canned server-stream messages (tests override)."""
+        self.call_server_stream_calls.append(
+            {"service": service, "method": method, "message": message, "metadata": metadata, "timeout": timeout}
+        )
+        # Reset terminal status to OK (default for normal completion)
+        self.terminal_status = GrpcStatus(0, "OK", "")
+        # Default: yield nothing (tests override by setting the yield list)
+        return
+        yield  # Make it a generator
+
+    def call_bidi(
+        self,
+        service: str,
+        method: str,
+        request_json_iter,
+        *,
+        metadata: dict | None = None,
+        timeout: float | None = None,
+    ):
+        """Yield canned bidi stream messages (tests override)."""
+        messages = list(request_json_iter)
+        self.call_bidi_calls.append(
+            {"service": service, "method": method, "messages": messages, "metadata": metadata, "timeout": timeout}
+        )
+        # Reset terminal status to OK (default for normal completion)
+        self.terminal_status = GrpcStatus(0, "OK", "")
+        # Default: yield nothing (tests override by setting the yield list)
+        return
+        yield  # Make it a generator
+
+    def healthcheck(self, service_name: str = ""):
+        """Fake healthcheck - returns canned result."""
+        self.healthcheck_calls.append({"service": service_name})
+        return self._healthcheck_result
+
+
+def install_fake(monkeypatch, fake: _FakeGrpcClient | None = None):
+    """Install a fake gRPC client via monkeypatch."""
+    if fake is None:
+        fake = _FakeGrpcClient()
+    monkeypatch.setattr(grpc_commands, "new_grpc_client", lambda target, descriptors=None: fake)
+    return fake
+
+
+# ---------------------------------------------------------------------------
+# Template mode: unary call
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_template_unary(monkeypatch):
+    """Template mode: grpc call <template> resolves target/service/method and invokes unary call."""
+    fake = install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(cli, ["--config", str(FIXTURE), "grpc", "call", "echo-unary", "--param", "m=hi"])
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["ok"] is True
+    assert out["command"] == "grpc.call"
+    assert out["result"]["message"] == {"msg": "hi"}
+    assert out["result"]["status"]["name"] == "OK"
+    assert out["result"]["call_type"] == "unary"
+
+
+# ---------------------------------------------------------------------------
+# Freeform mode: --address
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_freeform_address(monkeypatch):
+    """Freeform mode: --address with --service/--method invokes unary call."""
+    fake = install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--address", "localhost:50051", "--service", "echo.Echo", "--method", "Unary", "--message", '{"msg":"x"}'],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    assert fake.call_unary_calls == [
+        {
+            "service": "echo.Echo",
+            "method": "Unary",
+            "message": {"msg": "x"},
+            "metadata": None,
+            "timeout": None,
+        }
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Error cases: target/address resolution
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_target_unknown(monkeypatch):
+    """Unknown --target raises ConfigError."""
+    install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(cli, ["--config", str(FIXTURE), "grpc", "call", "--target", "nope", "--service", "S", "--method", "M", "--message", "{}"])
+
+    assert result.exit_code == 2
+    assert "Unknown gRPC target: nope" in result.stdout or "Unknown gRPC target" in result.stdout
+
+
+def test_grpc_call_address_target_mutex(monkeypatch):
+    """--address and --target are mutually exclusive."""
+    install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--target", "echo", "--address", "h:1", "--service", "S", "--method", "M", "--message", "{}"],
+    )
+
+    assert result.exit_code == 2
+    assert "mutually exclusive" in result.stdout or "--address is mutually exclusive with --target" in result.stdout
+
+
+def test_grpc_call_template_mutex(monkeypatch):
+    """Template positional is mutually exclusive with --target/--address/--service/--method."""
+    install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(cli, ["--config", str(FIXTURE), "grpc", "call", "echo-unary", "--service", "x"])
+
+    assert result.exit_code == 2
+    assert "mutually exclusive" in result.stdout
+
+
+# ---------------------------------------------------------------------------
+# Non-OK status is a result (D6), not an error
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_nonok_status_is_result(monkeypatch):
+    """Non-OK gRPC status is returned as a result, not an error."""
+    fake = install_fake(monkeypatch)
+    # Override to return non-OK status
+    fake._call_unary_result = GrpcUnaryResult(
+        target="localhost:50051",
+        service="echo.Echo",
+        method="Unary",
+        call_type="unary",
+        status=GrpcStatus(code=5, name="NOT_FOUND", message="not found"),
+        message=None,
+        initial_metadata={},
+        trailers={},
+    )
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--address", "localhost:50051", "--service", "echo.Echo", "--method", "Unary", "--message", "{}"],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["ok"] is True
+    assert out["result"]["status"]["name"] == "NOT_FOUND"
+
+
+# ---------------------------------------------------------------------------
+# Assertions
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_assertion_status_fail(monkeypatch):
+    """Assertion --status NOT_FOUND fails when actual status is OK."""
+    fake = install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        [
+            "--config",
+            str(FIXTURE),
+            "grpc",
+            "call",
+            "--address",
+            "localhost:50051",
+            "--service",
+            "echo.Echo",
+            "--method",
+            "Unary",
+            "--message",
+            "{}",
+            "--status",
+            "NOT_FOUND",
+        ],
+    )
+
+    assert result.exit_code == 1
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["ok"] is False
+    assert out["error"]["type"] == "AssertionError"
+    assert any(f["mode"] == "status" for f in out["error"]["detail"]["failures"])
+
+
+def test_grpc_call_assertion_match_pass(monkeypatch):
+    """Assertion --match '.status.name == "OK"' passes when status is OK."""
+    fake = install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        [
+            "--config",
+            str(FIXTURE),
+            "grpc",
+            "call",
+            "--address",
+            "localhost:50051",
+            "--service",
+            "echo.Echo",
+            "--method",
+            "Unary",
+            "--message",
+            "{}",
+            '--match',
+            '.status.name == "OK"',
+        ],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+
+
+# ---------------------------------------------------------------------------
+# Client-streaming envelope (stdin NDJSON)
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_client_stream_envelope(monkeypatch):
+    """Client-streaming call reads NDJSON from stdin and returns unary result."""
+    fake = install_fake(monkeypatch)
+    # Override find_method to return client-streaming descriptor
+    def fake_find_method(service: str, method: str) -> _FakeMethodDescriptor:
+        return _FakeMethodDescriptor(client_streaming=True, server_streaming=False)
+
+    fake.find_method = fake_find_method
+    runner = CliRunner(env=ENV)
+
+    stdin_data = '{"msg":"a"}\n{"msg":"b"}\n'
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--target", "echo", "--service", "echo.Echo", "--method", "ClientStream"],
+        input=stdin_data,
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["result"]["call_type"] == "client_stream"
+    assert len(fake.call_client_stream_calls) == 1
+    assert fake.call_client_stream_calls[0]["messages"] == [{"msg": "a"}, {"msg": "b"}]
+
+
+# ---------------------------------------------------------------------------
+# Bad request JSON raises ConfigError
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_bad_request_json_is_configerror(monkeypatch):
+    """Malformed --message raises ConfigError."""
+    fake = install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--address", "localhost:50051", "--service", "echo.Echo", "--method", "Unary", "--message", "not json"],
+    )
+
+    assert result.exit_code == 2
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["error"]["type"] == "ConfigError"
+
+
+# ---------------------------------------------------------------------------
+# Streaming tests (Task 10)
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_server_stream_emits_ndjson_and_summary(monkeypatch):
+    """Server-streaming emits NDJSON messages + summary line."""
+    fake = install_fake(monkeypatch)
+    # Override find_method to return server-streaming descriptor
+    def fake_find_method_server_stream(service: str, method: str) -> _FakeMethodDescriptor:
+        return _FakeMethodDescriptor(client_streaming=False, server_streaming=True)
+
+    fake.find_method = fake_find_method_server_stream
+
+    # Override call_server_stream to yield canned messages
+    def fake_call_server_stream(
+        service, method, message, *, metadata=None, timeout=None
+    ):
+        yield GrpcStreamMessage(message={"msg": "a"}, trailers=None)
+        yield GrpcStreamMessage(message={"msg": "b"}, trailers={"grpc-status": "0"})
+
+    fake.call_server_stream = fake_call_server_stream
+
+    runner = CliRunner(env=ENV)
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--target", "echo", "--service", "echo.Echo", "--method", "ServerStream", "--message", '{"msg":"x"}'],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    lines = result.stdout.strip().split("\n")
+    assert len(lines) == 3, f"Expected 3 lines (2 messages + 1 summary), got {len(lines)}"
+
+    import json
+
+    msg1 = json.loads(lines[0])
+    msg2 = json.loads(lines[1])
+    summary = json.loads(lines[2])
+
+    assert msg1["event"] == "message"
+    assert msg1["message"] == {"msg": "a"}
+    assert msg1["trailers"] is None
+
+    assert msg2["event"] == "message"
+    assert msg2["message"] == {"msg": "b"}
+    assert msg2["trailers"] == {"grpc-status": "0"}
+
+    assert summary["summary"] is True
+    assert summary["messages"] == 2
+    assert summary["matched"] == 2
+
+
+def test_grpc_call_bidi_reads_stdin_and_streams(monkeypatch):
+    """Bidirectional streaming reads stdin NDJSON and streams responses."""
+    fake = install_fake(monkeypatch)
+    # Override find_method to return bidi descriptor
+    def fake_find_method_bidi(service: str, method: str) -> _FakeMethodDescriptor:
+        return _FakeMethodDescriptor(client_streaming=True, server_streaming=True)
+
+    fake.find_method = fake_find_method_bidi
+
+    # Override call_bidi to echo messages back
+    def fake_call_bidi(service, method, request_json_iter, *, metadata=None, timeout=None):
+        requests = list(request_json_iter)
+        # Record the call
+        fake.call_bidi_calls.append(
+            {"service": service, "method": method, "messages": requests, "metadata": metadata, "timeout": timeout}
+        )
+        for req in requests:
+            # Echo back each request
+            yield GrpcStreamMessage(message=req, trailers=None)
+        yield GrpcStreamMessage(message={}, trailers={"grpc-status": "0"})
+
+    fake.call_bidi = fake_call_bidi
+
+    runner = CliRunner(env=ENV)
+    stdin_data = '{"msg":"a"}\n{"msg":"b"}\n'
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--target", "echo", "--service", "echo.Echo", "--method", "Bidi"],
+        input=stdin_data,
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    lines = result.stdout.strip().split("\n")
+    assert len(lines) == 4  # 3 messages (2 echo + 1 final) + 1 summary
+
+    import json
+
+    msg1 = json.loads(lines[0])
+    msg2 = json.loads(lines[1])
+    msg3 = json.loads(lines[2])
+    summary = json.loads(lines[3])
+
+    assert msg1["event"] == "message"
+    assert msg1["message"] == {"msg": "a"}
+
+    assert msg2["event"] == "message"
+    assert msg2["message"] == {"msg": "b"}
+
+    assert msg3["event"] == "message"
+    assert msg3["message"] == {}
+    assert msg3["trailers"] == {"grpc-status": "0"}
+
+    assert summary["summary"] is True
+    assert summary["messages"] == 3
+    assert summary["matched"] == 3
+
+    # Verify the fake client received both stdin messages
+    assert len(fake.call_bidi_calls) == 1
+    assert fake.call_bidi_calls[0]["messages"] == [{"msg": "a"}, {"msg": "b"}]
+
+
+def test_grpc_call_stream_match_filters_and_expect_count(monkeypatch):
+    """Server-streaming with --match filters and --expect-count validates matched count."""
+    fake = install_fake(monkeypatch)
+    # Override find_method to return server-streaming descriptor
+    def fake_find_method_server_stream(service: str, method: str) -> _FakeMethodDescriptor:
+        return _FakeMethodDescriptor(client_streaming=False, server_streaming=True)
+
+    fake.find_method = fake_find_method_server_stream
+
+    # Override call_server_stream to yield messages with different patterns
+    def fake_call_server_stream(
+        service, method, message, *, metadata=None, timeout=None
+    ):
+        yield GrpcStreamMessage(message={"msg": "x", "count": 1}, trailers=None)
+        yield GrpcStreamMessage(message={"msg": "y", "count": 2}, trailers=None)
+        yield GrpcStreamMessage(message={"msg": "x", "count": 3}, trailers={"grpc-status": "0"})
+
+    fake.call_server_stream = fake_call_server_stream
+
+    runner = CliRunner(env=ENV)
+
+    # Test 1: --expect-count 2 with --match '.msg == "x"' (2 matches) → exit 0
+    result = runner.invoke(
+        cli,
+        [
+            "--config", str(FIXTURE),
+            "grpc", "call", "--target", "echo",
+            "--service", "echo.Echo", "--method", "ServerStream",
+            "--message", '{"msg":"x"}',
+            '--match', '.msg == "x"',
+            "--expect-count", "2",
+        ],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    lines = result.stdout.strip().split("\n")
+    import json
+
+    summary = json.loads(lines[-1])
+    assert summary["matched"] == 2
+    assert summary["messages"] == 3
+
+    # Test 2: --expect-count 3 with --match '.msg == "x"' (only 2 matches) → exit 1
+    result = runner.invoke(
+        cli,
+        [
+            "--config", str(FIXTURE),
+            "grpc", "call", "--target", "echo",
+            "--service", "echo.Echo", "--method", "ServerStream",
+            "--message", '{"msg":"x"}',
+            '--match', '.msg == "x"',
+            "--expect-count", "3",
+        ],
+    )
+
+    assert result.exit_code == 1, f"stdout: {result.stdout}"
+    lines = result.stdout.strip().split("\n")
+    summary = json.loads(lines[-1])
+    assert summary["matched"] == 2
+    assert summary["messages"] == 3
+
+
+def test_grpc_call_stream_rejects_unary_assertion_flags(monkeypatch):
+    """Unary assertion flags (--status/--contains/--jq-path/--equals) are rejected on streaming calls."""
+    fake = install_fake(monkeypatch)
+    # Override find_method to return server-streaming descriptor
+    def fake_find_method_server_stream(service: str, method: str) -> _FakeMethodDescriptor:
+        return _FakeMethodDescriptor(client_streaming=False, server_streaming=True)
+
+    fake.find_method = fake_find_method_server_stream
+
+    runner = CliRunner(env=ENV)
+
+    # Test --status (unary assertion flag)
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--target", "echo", "--service", "echo.Echo", "--method", "ServerStream", "--message", '{}', "--status", "OK"],
+    )
+
+    assert result.exit_code == 2, f"stdout: {result.stdout}"
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["error"]["type"] == "ConfigError"
+    assert "unary assertion" in out["error"]["message"].lower() or "not allowed" in out["error"]["message"].lower() or "mutually exclusive" in out["error"]["message"].lower()
+
+
+def test_grpc_call_stream_bad_match_startup_error(monkeypatch):
+    """Malformed --match expression causes ConfigError startup error (no messages streamed)."""
+    fake = install_fake(monkeypatch)
+    # Override find_method to return server-streaming descriptor
+    def fake_find_method_server_stream(service: str, method: str) -> _FakeMethodDescriptor:
+        return _FakeMethodDescriptor(client_streaming=False, server_streaming=True)
+
+    fake.find_method = fake_find_method_server_stream
+
+    # Track if streaming was attempted (should not be)
+    call_server_stream_called = []
+
+    def fake_call_server_stream(service, method, message, *, metadata=None, timeout=None):
+        call_server_stream_called.append(True)
+        yield GrpcStreamMessage(message={"msg": "a"}, trailers=None)
+
+    fake.call_server_stream = fake_call_server_stream
+
+    runner = CliRunner(env=ENV)
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--target", "echo", "--service", "echo.Echo", "--method", "ServerStream", "--message", '{}', '--match', '.msg =='],
+    )
+
+    assert result.exit_code == 2, f"stdout: {result.stdout}"
+    # Should emit exactly one error envelope line (no streaming messages)
+    lines = result.stdout.strip().split("\n")
+    assert len(lines) == 1, f"Expected 1 line (error envelope), got {len(lines)}: {result.stdout}"
+    import json
+
+    out = json.loads(lines[0])
+    assert out["error"]["type"] == "ConfigError"
+    # Verify streaming was never attempted
+    assert len(call_server_stream_called) == 0
+
+
+def test_grpc_call_stream_unknown_target_startup_error(monkeypatch):
+    """Unknown --target causes ConfigError startup error (single envelope line, no streaming)."""
+    fake = install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--target", "nope", "--service", "S", "--method", "M", "--message", '{}'],
+    )
+
+    assert result.exit_code == 2, f"stdout: {result.stdout}"
+    # Should emit exactly one error envelope line
+    lines = result.stdout.strip().split("\n")
+    assert len(lines) == 1, f"Expected 1 line (error envelope), got {len(lines)}: {result.stdout}"
+    import json
+
+    out = json.loads(lines[0])
+    assert out["error"]["type"] == "ConfigError"
+    assert "unknown" in out["error"]["message"].lower()
+
+
+def test_grpc_call_server_stream_summary_carries_nonok_status(monkeypatch):
+    """Server-streaming summary carries non-OK terminal status."""
+    fake = install_fake(monkeypatch)
+    # Override find_method to return server-streaming descriptor
+    def fake_find_method_server_stream(service: str, method: str) -> _FakeMethodDescriptor:
+        return _FakeMethodDescriptor(client_streaming=False, server_streaming=True)
+
+    fake.find_method = fake_find_method_server_stream
+
+    # Override call_server_stream to yield 2 messages then set terminal_status to NOT_FOUND
+    def fake_call_server_stream_nonok(
+        service, method, message, *, metadata=None, timeout=None
+    ):
+        yield GrpcStreamMessage(message={"msg": "a"}, trailers=None)
+        yield GrpcStreamMessage(message={"msg": "b"}, trailers=None)
+        # Set non-OK terminal status
+        fake.terminal_status = GrpcStatus(code=5, name="NOT_FOUND", message="missing")
+
+    fake.call_server_stream = fake_call_server_stream_nonok
+
+    runner = CliRunner(env=ENV)
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--target", "echo", "--service", "echo.Echo", "--method", "ServerStream", "--message", '{"msg":"x"}'],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    lines = result.stdout.strip().split("\n")
+    assert len(lines) == 3, f"Expected 3 lines (2 messages + 1 summary), got {len(lines)}"
+
+    import json
+
+    msg1 = json.loads(lines[0])
+    msg2 = json.loads(lines[1])
+    summary = json.loads(lines[2])
+
+    assert msg1["event"] == "message"
+    assert msg1["message"] == {"msg": "a"}
+
+    assert msg2["event"] == "message"
+    assert msg2["message"] == {"msg": "b"}
+
+    assert summary["summary"] is True
+    assert summary["messages"] == 2
+    assert summary["matched"] == 2
+    # Verify the summary carries the non-OK terminal status
+    assert summary["status"]["name"] == "NOT_FOUND"
+    assert summary["status"]["code"] == 5
+    assert summary["status"]["message"] == "missing"
+
+
+# ---------------------------------------------------------------------------
+# Healthcheck tests (Task 11)
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_healthcheck_single_target(monkeypatch):
+    """Single target healthcheck returns SERVING status with all_serving=True."""
+    fake = install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "healthcheck", "--target", "echo", "--service", ""],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["ok"] is True
+    assert out["command"] == "grpc.healthcheck"
+    assert out["result"]["targets"]["echo"]["status"] == "SERVING"
+    assert out["result"]["targets"]["echo"]["address"] == "localhost:50051"
+    assert "note" not in out["result"]["targets"]["echo"]
+    assert out["result"]["all_serving"] is True
+
+
+def test_grpc_healthcheck_all(monkeypatch):
+    """--all flag checks all configured targets."""
+    fake = install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "healthcheck", "--all"],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["ok"] is True
+    assert out["command"] == "grpc.healthcheck"
+    # Should have one entry for the "echo" target
+    assert "echo" in out["result"]["targets"]
+    assert out["result"]["targets"]["echo"]["status"] == "SERVING"
+    assert out["result"]["all_serving"] is True
+
+
+def test_grpc_healthcheck_unknown_is_unknown_not_error(monkeypatch):
+    """UNKNOWN status (UNIMPLEMENTED health service) is not an error - returns all_serving=False."""
+    fake = install_fake(monkeypatch)
+    # Override healthcheck to return UNKNOWN status with note
+    fake._healthcheck_result = GrpcHealthResult(
+        target="localhost:50051",
+        address="localhost:50051",
+        status="UNKNOWN",
+        note="health service UNIMPLEMENTED",
+    )
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "healthcheck", "--target", "echo"],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["ok"] is True
+    assert out["command"] == "grpc.healthcheck"
+    assert out["result"]["targets"]["echo"]["status"] == "UNKNOWN"
+    assert out["result"]["targets"]["echo"]["note"] == "health service UNIMPLEMENTED"
+    assert out["result"]["all_serving"] is False
+
+
+def test_grpc_healthcheck_unknown_target(monkeypatch):
+    """Unknown --target raises ConfigError."""
+    install_fake(monkeypatch)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "healthcheck", "--target", "nope"],
+    )
+
+    assert result.exit_code == 2, f"stdout: {result.stdout}"
+    import json
+
+    out = json.loads(result.stdout)
+    assert out["error"]["type"] == "ConfigError"
+    assert "Unknown gRPC target" in out["error"]["message"] or "unknown" in out["error"]["message"].lower()
+
+
+# ---------------------------------------------------------------------------
+# Finding 2b: Streaming error handling tests
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_server_stream_midstream_error_carries_status(monkeypatch):
+    """Server-streaming: mid-stream RpcError is captured into terminal_status and emitted as final NDJSON line."""
+    import json
+
+    # Create fake client that yields one message then sets terminal_status to INTERNAL
+    fake = install_fake(monkeypatch)
+
+    # Override find_method to return a server-streaming descriptor
+    def fake_find_method(service, method):
+        fake.find_method_calls.append((service, method))
+        return _FakeMethodDescriptor(client_streaming=False, server_streaming=True)
+
+    fake.find_method = fake_find_method
+
+    # Override call_server_stream to yield one message then set error terminal status
+    def fake_call_server_stream(service, method, message, *, metadata=None, timeout=None):
+        fake.call_server_stream_calls.append({"service": service, "method": method, "message": message, "metadata": metadata, "timeout": timeout})
+        # Yield one message, then set terminal status to INTERNAL error
+        yield GrpcStreamMessage(message={"msg": "first"}, trailers=None)
+        fake.terminal_status = GrpcStatus(
+            code=grpc.StatusCode.INTERNAL.value[0],
+            name="INTERNAL",
+            message="stream error",
+        )
+
+    fake.call_server_stream = fake_call_server_stream
+
+    runner = CliRunner(env=ENV)
+
+    # Use --message with a JSON string (no spaces to avoid quoting issues)
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--address", "localhost:50051", "--service", "echo.Echo", "--method", "ServerStream", "--message", "{\"msg\":\"x\"}"],
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+
+    # Parse NDJSON output
+    lines = [json.loads(line) for line in result.stdout.strip().split("\n")]
+
+    # First line should be the message
+    assert lines[0]["event"] == "message"
+    assert lines[0]["message"]["msg"] == "first"
+
+    # Final line should be the summary with the INTERNAL status
+    assert lines[-1]["summary"] is True
+    assert lines[-1]["status"]["name"] == "INTERNAL"
+    assert lines[-1]["status"]["message"] == "stream error"
+    assert lines[-1]["messages"] == 1
+
+
+def test_grpc_call_stream_deadline_emits_summary_not_traceback(monkeypatch):
+    """Server-streaming: OperationTimeout is emitted as structured NDJSON summary line, not traceback."""
+    import json
+    from agctl.errors import OperationTimeout
+
+    # Create fake client that raises OperationTimeout
+    fake = install_fake(monkeypatch)
+
+    # Override find_method to return a server-streaming descriptor
+    def fake_find_method(service, method):
+        fake.find_method_calls.append((service, method))
+        return _FakeMethodDescriptor(client_streaming=False, server_streaming=True)
+
+    fake.find_method = fake_find_method
+
+    # Override call_server_stream to raise OperationTimeout
+    def fake_call_server_stream(service, method, message, *, metadata=None, timeout=None):
+        fake.call_server_stream_calls.append({"service": service, "method": method, "message": message, "metadata": metadata, "timeout": timeout})
+        raise OperationTimeout(message="timeout", detail={})
+
+    fake.call_server_stream = fake_call_server_stream
+
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--address", "localhost:50051", "--service", "echo.Echo", "--method", "ServerStream", "--message", "{\"msg\":\"x\"}"],
+    )
+
+    assert result.exit_code == 1, f"stdout: {result.stdout}"
+
+    # Parse NDJSON output - should be a single error summary line
+    lines = [json.loads(line) for line in result.stdout.strip().split("\n")]
+
+    # Should have a single line with error and summary
+    assert len(lines) == 1
+    assert lines[0]["summary"] is True
+    assert lines[0]["error"]["type"] == "TimeoutError"
+    assert "timeout" in lines[0]["error"]["message"]
+    assert lines[0]["messages"] == 0
+    assert lines[0]["matched"] == 0
+    # Valid gRPC status code on the error-summary (0-16), never the invented -1 (M1)
+    assert lines[0]["status"]["code"] != -1
+    assert 0 <= lines[0]["status"]["code"] <= 16
+
+    # Verify no Python traceback in output (structured JSON only)
+    assert "Traceback" not in result.stdout
+    assert "OperationTimeout" not in result.stdout or lines[0]["error"]["type"] == "OperationTimeout"
+
+
+def test_grpc_call_bidi_internal_error_emits_summary(monkeypatch):
+    """Bidirectional streaming: InternalError during setup emits structured NDJSON summary."""
+    import json
+
+    # Create fake client that raises a generic exception during bidi setup
+    fake = install_fake(monkeypatch)
+
+    # Override find_method to return a bidi descriptor
+    def fake_find_method(service, method):
+        fake.find_method_calls.append((service, method))
+        return _FakeMethodDescriptor(client_streaming=True, server_streaming=True)
+
+    fake.find_method = fake_find_method
+
+    # Override call_bidi to raise a generic exception
+    def fake_call_bidi(service, method, request_json_iter, *, metadata=None, timeout=None):
+        messages = list(request_json_iter)  # Consume the iterator like the real implementation
+        fake.call_bidi_calls.append({"service": service, "method": method, "messages": messages, "metadata": metadata, "timeout": timeout})
+        raise RuntimeError("unexpected internal error")
+
+    fake.call_bidi = fake_call_bidi
+
+    runner = CliRunner(env=ENV)
+
+    # Use --address to avoid template mode stdin complexity
+    result = runner.invoke(
+        cli,
+        ["--config", str(FIXTURE), "grpc", "call", "--address", "localhost:50051", "--service", "echo.Echo", "--method", "Bidi"],
+        input='{"msg":"a"}\n',
+    )
+
+    assert result.exit_code == 2, f"stdout: {result.stdout}"
+
+    # Parse NDJSON output - should be a single error summary line
+    lines = [json.loads(line) for line in result.stdout.strip().split("\n")]
+
+    # Should have a single line with InternalError
+    assert len(lines) == 1
+    assert lines[0]["summary"] is True
+    assert lines[0]["error"]["type"] == "InternalError"
+    assert "unexpected internal error" in lines[0]["error"]["message"]
+
+    # Verify no Python traceback in output (structured JSON only)
+    assert "Traceback" not in result.stdout
+    assert lines[0]["messages"] == 0
+
+    # Verify no Python traceback in output (structured JSON only)
+    assert "Traceback" not in result.stdout
+
+
+# ---------------------------------------------------------------------------
+# Review-fix tests: --status numeric (I1), single-resolution (I3),
+# streaming partial-count error-summary (M1)
+# ---------------------------------------------------------------------------
+
+
+def test_grpc_call_status_numeric(monkeypatch):
+    """--status accepts numeric codes from the CLI (I1).
+
+    Click declares --status as type=str, so '5' arrives as a string. The
+    validator coerces numeric strings to int before lookup:
+      - --status 5 against a NOT_FOUND (code 5) result -> match, exit 0
+      - --status 0 against an OK (code 0) result -> match, exit 0
+      - --status 99 -> out of range -> ConfigError exit 2 (before the call)
+    """
+    import json
+
+    runner = CliRunner(env=ENV)
+    base = [
+        "--config", str(FIXTURE),
+        "grpc", "call", "--address", "localhost:50051",
+        "--service", "echo.Echo", "--method", "Unary", "--message", "{}",
+    ]
+
+    # NOT_FOUND result -> --status 5 matches -> exit 0
+    fake = install_fake(monkeypatch)
+    fake._call_unary_result = GrpcUnaryResult(
+        target="localhost:50051",
+        service="echo.Echo",
+        method="Unary",
+        call_type="unary",
+        status=GrpcStatus(code=5, name="NOT_FOUND", message=""),
+        message=None,
+        initial_metadata={},
+        trailers={},
+    )
+    r = runner.invoke(cli, base + ["--status", "5"])
+    assert r.exit_code == 0, f"stdout: {r.stdout}"
+
+    # OK result (default fake, code 0) -> --status 0 matches -> exit 0
+    install_fake(monkeypatch)
+    r = runner.invoke(cli, base + ["--status", "0"])
+    assert r.exit_code == 0, f"stdout: {r.stdout}"
+
+    # --status 99 -> out of range -> ConfigError exit 2 (validation, before call)
+    install_fake(monkeypatch)
+    r = runner.invoke(cli, base + ["--status", "99"])
+    assert r.exit_code == 2, f"stdout: {r.stdout}"
+    out = json.loads(r.stdout)
+    assert out["error"]["type"] == "ConfigError"
+
+
+def test_grpc_call_single_resolution(monkeypatch):
+    """One ``grpc call`` resolves target/client/method EXACTLY ONCE (I3).
+
+    Previously resolution was duplicated: _detect_call_type and _grpc_call_core
+    each independently loaded config, built the client, and called find_method
+    (two reflection round-trips for ``reflection: auto`` targets). Now a single
+    _resolve_grpc_call produces one client + one find_method per invocation.
+    """
+    fake = _FakeGrpcClient()
+    build_calls = []
+
+    def counting_factory(target, descriptors=None):
+        build_calls.append(target)
+        return fake
+
+    monkeypatch.setattr(grpc_commands, "new_grpc_client", counting_factory)
+    runner = CliRunner(env=ENV)
+
+    result = runner.invoke(
+        cli, ["--config", str(FIXTURE), "grpc", "call", "echo-unary", "--param", "m=hi"]
+    )
+
+    assert result.exit_code == 0, f"stdout: {result.stdout}"
+    assert len(build_calls) == 1, (
+        f"new_grpc_client called {len(build_calls)} times, expected 1"
+    )
+    assert len(fake.find_method_calls) == 1, (
+        f"find_method called {len(fake.find_method_calls)} times, expected 1"
+    )
+
+
+def test_grpc_call_stream_midstream_error_summary_carries_partial_counts(monkeypatch):
+    """Server-streaming: a mid-stream AgctlError error-summary carries the PARTIAL
+    message/matched counts actually emitted (not 0) and a valid gRPC status code
+    (no invented -1). (M1)"""
+    import json
+    from agctl.errors import OperationTimeout
+
+    fake = install_fake(monkeypatch)
+
+    def fake_find_method(service, method):
+        fake.find_method_calls.append((service, method))
+        return _FakeMethodDescriptor(client_streaming=False, server_streaming=True)
+
+    fake.find_method = fake_find_method
+
+    # Yield two messages, THEN raise OperationTimeout mid-stream
+    def fake_call_server_stream(service, method, message, *, metadata=None, timeout=None):
+        yield GrpcStreamMessage(message={"msg": "a"}, trailers=None)
+        yield GrpcStreamMessage(message={"msg": "b"}, trailers=None)
+        raise OperationTimeout(message="stream timed out", detail={})
+
+    fake.call_server_stream = fake_call_server_stream
+
+    runner = CliRunner(env=ENV)
+    result = runner.invoke(
+        cli,
+        [
+            "--config", str(FIXTURE),
+            "grpc", "call", "--address", "localhost:50051",
+            "--service", "echo.Echo", "--method", "ServerStream",
+            "--message", "{\"msg\":\"x\"}",
+        ],
+    )
+
+    # OperationTimeout -> exit 1
+    assert result.exit_code == 1, f"stdout: {result.stdout}"
+
+    lines = [json.loads(line) for line in result.stdout.strip().split("\n")]
+    # 2 streamed message lines + 1 error-summary line
+    assert len(lines) == 3, f"Expected 3 lines, got {len(lines)}: {result.stdout}"
+    assert lines[0]["event"] == "message"
+    assert lines[1]["event"] == "message"
+
+    # Error-summary carries the PARTIAL counts emitted before the error (M1)
+    summary = lines[2]
+    assert summary["summary"] is True
+    assert summary["error"]["type"] == "TimeoutError"
+    assert summary["messages"] == 2, (
+        f"Expected partial messages=2, got {summary['messages']}"
+    )
+    assert summary["matched"] == 2, (
+        f"Expected partial matched=2, got {summary['matched']}"
+    )
+    # Valid gRPC status code (0-16), never the invented -1 (M1)
+    assert summary["status"]["code"] != -1
+    assert 0 <= summary["status"]["code"] <= 16
+    assert "Traceback" not in result.stdout
+
diff --git a/tests/unit/test_models.py b/tests/unit/test_models.py
index c6df330..5adda81 100644
--- a/tests/unit/test_models.py
+++ b/tests/unit/test_models.py
@@ -5,6 +5,11 @@
     Config,
     DatabaseConnection,
     DatabaseTemplate,
+    GrpcConfig,
+    GrpcDescriptorSource,
+    GrpcTarget,
+    GrpcTemplate,
+    GrpcTls,
     KafkaCluster,
     KafkaConfig,
     KafkaPattern,
@@ -248,3 +253,84 @@ def test_kafka_reactor_accepts_cluster_field():
     # defaults to None when omitted
     plain = KafkaReactor(topic="t", reaction=KafkaReaction(topic="out", value={}))
     assert plain.cluster is None
+
+
+# gRPC model tests (Task 1)
+
+
+def test_grpc_tls_defaults():
+    """GrpcTls() has all four fields None."""
+    tls = GrpcTls()
+    assert tls.ca_location is None
+    assert tls.certificate_location is None
+    assert tls.key_location is None
+    assert tls.override_authority is None
+
+
+def test_grpc_target_defaults():
+    """GrpcTarget(address='localhost:50051') has use_tls is False, tls is None, reflection == 'auto'."""
+    target = GrpcTarget(address="localhost:50051")
+    assert target.address == "localhost:50051"
+    assert target.use_tls is False
+    assert target.tls is None
+    assert target.reflection == "auto"
+
+
+def test_grpc_target_explicit_values():
+    """GrpcTarget(address='x', use_tls=True, reflection='off') keeps those values."""
+    target = GrpcTarget(address="x", use_tls=True, reflection="off")
+    assert target.address == "x"
+    assert target.use_tls is True
+    assert target.reflection == "off"
+
+
+def test_grpc_target_rejects_bad_reflection():
+    """GrpcTarget(address='x', reflection='maybe') raises ValidationError."""
+    with pytest.raises(ValidationError):
+        GrpcTarget(address="x", reflection="maybe")
+
+
+def test_grpc_descriptor_source_all_none():
+    """GrpcDescriptorSource() has proto is None, descriptor_set is None, include_paths == []."""
+    source = GrpcDescriptorSource()
+    assert source.proto is None
+    assert source.descriptor_set is None
+    assert source.include_paths == []
+
+
+def test_grpc_template_defaults():
+    """GrpcTemplate(target='t', service='s.v1.S', method='M') has description is None, metadata == {}, message is None."""
+    tmpl = GrpcTemplate(target="t", service="s.v1.S", method="M")
+    assert tmpl.target == "t"
+    assert tmpl.service == "s.v1.S"
+    assert tmpl.method == "M"
+    assert tmpl.description is None
+    assert tmpl.metadata == {}
+    assert tmpl.message is None
+
+
+def test_grpc_config_empty_default():
+    """GrpcConfig() has targets == {}, descriptors == [], templates == {}."""
+    cfg = GrpcConfig()
+    assert cfg.targets == {}
+    assert cfg.descriptors == []
+    assert cfg.templates == {}
+
+
+def test_config_has_grpc_field():
+    """Config(version='2') has .grpc a GrpcConfig (empty)."""
+    cfg = Config(version="3")
+    assert isinstance(cfg.grpc, GrpcConfig)
+    assert cfg.grpc.targets == {}
+    assert cfg.grpc.descriptors == []
+    assert cfg.grpc.templates == {}
+
+    # Also test constructing with a dict via model_validate
+    cfg2 = Config.model_validate(
+        {
+            "version": "2",
+            "grpc": {"targets": {"svc": {"address": "h:1"}}},
+        }
+    )
+    assert cfg2.grpc.targets["svc"].address == "h:1"
+    assert cfg2.grpc.targets["svc"].reflection == "auto"  # default applied