feat(rules): consolidate the 36 open rule pack pull requests

autogen/error_handling.yaml

@@ -0,0 +1,41 @@
+policy:
+  id: autogen_error_handling
+  name: AutoGen error contract hygiene
+  category: autogen
+  description: >
+    Rules covering how a registered AutoGen tool surfaces failure. An
+    unhandled exception in a tool breaks the two-agent reply loop the whole
+    conversation is built on, so the failure surfaces as a stalled or aborted
+    chat rather than something either agent can reason about.
+
+rules:
+  - id: AG2-013
+    title: AutoGen tool raises without a structured error contract
+    severity: low
+    confidence: 0.6
+    language: python
+    applies_to:
+      - autogen_tool
+    scope: tool
+    match:
+      all:
+        - has_raise: true
+        - has_try_except: false
+    explanation: >
+      This registered tool raises an exception it never catches. AutoGen
+      executes tools on the executor agent's side of the conversation and sends
+      the result back as that agent's reply, so an uncaught exception either
+      aborts initiate_chat outright or comes back as a stringified traceback
+      posted into the message history. In the second case both agents keep
+      talking with a traceback as the last observation: the assistant has no
+      failure mode to branch on and no signal about whether a retry could
+      succeed, so it re-issues the same call until the max_round or auto-reply
+      cap (AG2-004, AG2-006) ends the conversation. The traceback also stays in
+      the transcript, carrying file paths and internal detail into every
+      subsequent turn's context.
+    fix: >
+      Catch the failure modes you expect and return a structured value the
+      assistant can branch on — name the failure and say whether retrying could
+      help and what would need to change — instead of letting the exception
+      escape the registered function. Reserve raising for programmer errors no
+      amount of agent reasoning can work around.

autogen/observability.yaml

@@ -0,0 +1,39 @@
+policy:
+  id: autogen_observability
+  name: AutoGen tool observability hygiene
+  category: autogen
+  description: >
+    Rules covering how a registered AutoGen tool emits diagnostics. A tool body
+    that prints to stdout writes into the same stream the conversation itself is
+    narrated on, so the record is neither visible to the agents nor separable
+    from the transcript around it.
+
+rules:
+  - id: AG2-018
+    title: AutoGen tool prints to stdout for diagnostics
+    severity: low
+    confidence: 0.65
+    language: python
+    applies_to:
+      - autogen_tool
+    scope: tool
+    match:
+      has_print_call: true
+    explanation: >
+      The registered tool's body calls print(), which writes to the process's
+      stdout. Neither agent sees it — only the return value is posted back into
+      the conversation as the executor's reply — so the output silently
+      disappears in any deployment that captures structured records rather than
+      raw stdout. AutoGen makes that especially deceptive: the conversation
+      itself is narrated to stdout, so a tool print lands in the middle of the
+      transcript and reads as though it were part of the exchange, when in fact
+      it is invisible to the agents reasoning over it and carries no marker for
+      which round or which tool call produced it. Anyone reconstructing the run
+      from a log sink rather than a terminal loses it entirely.
+    fix: >
+      Remove the print(). For operator diagnostics, emit through a module logger
+      (logging.getLogger(__name__).info(...)) so the record carries its own
+      module and level and lands in the application's log sink rather than the
+      conversation narration. If the information needs to reach the assistant,
+      return it as part of the tool's result, which is the only channel the
+      agents actually read.

autogen/path_safety.yaml

@@ -0,0 +1,50 @@
+policy:
+  id: autogen_path_safety
+  name: AutoGen filesystem path safety
+  category: autogen
+  description: >
+    Rules that catch a model-supplied filesystem path flowing into an I/O call
+    inside a registered AutoGen tool without containment. A traversal payload
+    like ../../etc/passwd reaches real filesystem state if the tool does not
+    resolve the path and check it against an allowed root.
+
+rules:
+  - id: AG2-014
+    title: AutoGen tool uses a path parameter in I/O without validation
+    severity: high
+    confidence: 0.7
+    language: python
+    applies_to:
+      - autogen_tool
+    scope: tool
+    # call_uses_unnormalized_path_param is per-param: a tool with two path
+    # params and one .resolve() correctly fires on the unresolved one. A
+    # body-wide check would suppress the finding whenever any normalization
+    # appears, masking real exposure on the other param.
+    match:
+      call_uses_unnormalized_path_param:
+        callees:
+          - open
+          - Path
+        callee_prefixes:
+          - shutil.
+          - os.
+    explanation: >
+      This registered tool takes a path-like parameter and hands it to a file or
+      directory operation without resolving it or checking it against an allowed
+      root, so a model-supplied ../../etc/passwd reaches the real filesystem.
+      Type hints do not close this: a parameter annotated str or Path passes
+      AutoGen's schema generation while still carrying a traversal payload,
+      because the annotation constrains the argument's type and not the region
+      of the filesystem it points at. Registered tools also sidestep the
+      containment AG2-001 is about — a crew may run its generated code inside a
+      Docker executor, but a tool registered with register_for_execution runs in
+      the host process, with the host's filesystem view, whatever the code
+      executor is configured to do. Whatever the tool reads is then posted into
+      the message history both agents keep reasoning over.
+    fix: >
+      Resolve the path with Path(...).resolve() and assert the result sits under
+      an allowed root before touching it, rejecting anything that escapes. Keep
+      that check inside the registered function itself: it is the only boundary
+      the tool path crosses, since the code executor's sandbox does not apply
+      here.

autogen/tool_definition.yaml

@@ -54,3 +54,95 @@ rules:
       Annotate every parameter with a concrete type (str, int, list[str], a
       typing.Annotated description, etc.). AutoGen propagates these annotations into
       the schema the model sees, so the model emits correctly-shaped arguments.
+
+  - id: AG2-016
+    title: AutoGen tool description is a placeholder
+    severity: low
+    confidence: 0.85
+    language: python
+    applies_to:
+      - autogen_tool
+    scope: tool
+    match:
+      has_description_text:
+        - todo
+        - tbd
+        - fixme
+        - placeholder
+        - no description
+        - does stuff
+    explanation: >
+      The docstring passes the AG2-007 has-a-description check but carries a
+      placeholder marker instead of real content. AutoGen advertises the tool to
+      the assistant through this text, so a stub like "TODO: describe this tool"
+      is functionally indistinguishable from no description at all and the
+      assistant has to guess from the function name. The way AutoGen fails on a
+      bad guess is what makes this expensive: a wrongly chosen tool returns
+      something that does not answer the assistant's intent, the assistant reads
+      that as an inconclusive step and proposes another call, and the pair
+      trades rounds until AG2-004's max_round or AG2-006's auto-reply cap ends
+      the chat — burning the conversation budget on a selection problem no error
+      message points at.
+    fix: >
+      Replace the placeholder with a real description covering what the tool
+      does, what it returns, and when the assistant should call it rather than a
+      neighboring tool. Passing an explicit description= to register_for_llm
+      overrides the docstring and is the clearer place to say it.
+
+  - id: AG2-017
+    title: AutoGen tool description is too short to guide model selection
+    severity: low
+    confidence: 0.8
+    language: python
+    applies_to:
+      - autogen_tool
+    scope: tool
+    match:
+      all:
+        - has_docstring: true
+        - description_length_lt: 40
+    explanation: >
+      A description under 40 characters is rarely enough to convey what a tool
+      does, what it returns, and when to call it rather than a similarly named
+      neighbor. AutoGen passes this text to the assistant as its only selection
+      signal, so a stub like "Gets data." leaves scope and preconditions to
+      guesswork. Each mis-selected call costs a full round of the conversation —
+      the assistant proposes, the executor runs, the result comes back unhelpful
+      — so a thin description spends the max_round budget rather than the run
+      producing an answer.
+    fix: >
+      Expand the description to at least a full sentence covering inputs,
+      outputs, and the situation in which this tool should be used over the
+      alternatives, either in the docstring or via register_for_llm's
+      description= argument.
+
+  - id: AG2-019
+    title: Ambiguous AutoGen tool name
+    severity: low
+    confidence: 0.9
+    language: python
+    applies_to:
+      - autogen_tool
+    scope: tool
+    match:
+      name_in:
+        - process
+        - handle
+        - run
+        - do
+        - execute
+        - perform
+        - work
+        - go
+        - thing
+        - stuff
+    explanation: >
+      The tool name is a generic verb that says nothing about what the tool
+      acts on. The name sits directly beside the description in what the model
+      sees, so it is half the selection signal, and a name like process or
+      handle spends that half on nothing — the model either calls the tool for
+      the wrong job or passes over it entirely. Each wrong pick costs a full round of the conversation — propose, execute, reply — so an ambiguous name spends the AG2-004 max_round budget rather than the chat reaching an answer.
+    fix: >
+      Rename to a verb-object form that names the thing acted on:
+      summarize_invoice, refund_charge, fetch_order_status. Keep the
+      description for the detail and let the name carry the subject.

claude_sdk/network.yaml

@@ -53,3 +53,34 @@ rules:
     fix: >
       Pass `timeout=` (typically 5–30s) to the request. Surface failures as a
       structured error the model can react to.
+
+  - id: CSDK-020
+    title: TypeScript Claude SDK tool HTTP call has no timeout
+    severity: high
+    confidence: 0.6
+    language: typescript
+    applies_to:
+      - claude_sdk_tool
+    scope: tool
+    match:
+      has_http_call_without_timeout: true
+    explanation: >
+      This TypeScript Claude SDK tool makes an outbound HTTP call (fetch /
+      axios / got / undici) with no deadline — no signal, timeout, or
+      abortSignal option. Node's fetch has no implicit deadline, so a slow or
+      unresponsive host blocks the tool callback until the socket eventually
+      dies. Because the call sits inside the agent's turn, that stalls the
+      conversation rather than failing it: the model gets no result and no
+      error, the turn cannot advance, and a max_turns cap does not help because
+      the run is stuck inside a single turn rather than taking too many. In a
+      server embedding the SDK it also holds the request worker for the
+      duration. The exposure compounds with CSDK-013: a tool that fetches a
+      model-controlled URL and cannot time out can be pointed at an internal
+      host that simply never answers.
+    fix: >
+      Attach a deadline. On modern runtimes,
+      await fetch(url, { signal: AbortSignal.timeout(15_000) }); on older ones,
+      create an AbortController, abort it from a setTimeout, pass
+      controller.signal, and clear the timer in a finally. axios and got take a
+      timeout option directly. Return the abort as a structured tool error so
+      the model can retry or route around it instead of the turn hanging.

claude_sdk/observability.yaml

@@ -0,0 +1,41 @@
+policy:
+  id: claude_sdk_observability
+  name: Claude Agent SDK tool observability hygiene
+  category: claude_sdk
+  description: >
+    Rules covering how a Claude Agent SDK tool emits diagnostics. A tool body
+    that prints to stdout writes somewhere neither the model nor the
+    application's log sink reads, and can corrupt a transport that uses stdout
+    as a protocol channel.
+
+rules:
+  - id: CSDK-019
+    title: Tool prints to stdout for diagnostics
+    severity: low
+    confidence: 0.65
+    language: python
+    applies_to:
+      - claude_sdk_tool
+    scope: tool
+    match:
+      has_print_call: true
+    explanation: >
+      The tool body calls print(), which writes diagnostics to the process's
+      stdout. The model never sees that output — only the tool's return value
+      flows back into the agent loop — so the print silently disappears in any
+      deployment that captures structured records rather than raw stdout. Two
+      Claude-SDK-specific consequences make it worse than a lost log line. A
+      tool defined in a Python SDK server is commonly served to the agent over
+      an MCP stdio transport, where stdout carries the JSON-RPC frames: a loose
+      print interleaves with them and the client hits a parse error on a line
+      that is not JSON. And when the SDK is driven programmatically, the host
+      application is reading the SDK's own message stream, so tool prints land
+      interleaved with it rather than in the application's logs, attributable to
+      no particular turn or tool call.
+    fix: >
+      Remove the print(). For operator diagnostics, emit through a module logger
+      (logging.getLogger(__name__).info(...)) so the record carries its module
+      and level and lands in the application's log sink; where the tool may be
+      served over a stdio transport, make sure that handler writes to stderr,
+      which the transport leaves alone. If the information needs to reach the
+      model, include it in the tool's return value instead.

claude_sdk/tool_definition.yaml

@@ -183,3 +183,61 @@ rules:
       Expand the description to at least a full sentence covering inputs,
       outputs, and the situation in which this tool should be used over
       alternatives.
+
+  - id: CSDK-021
+    title: TypeScript Claude SDK tool description is a placeholder
+    severity: low
+    confidence: 0.85
+    language: typescript
+    applies_to:
+      - claude_sdk_tool
+    scope: tool
+    match:
+      has_description_text:
+        - todo
+        - tbd
+        - fixme
+        - placeholder
+        - no description
+        - does stuff
+    explanation: >
+      The tool sets a description, so it passes CSDK-014, but the string is a
+      placeholder rather than real content. That leaves the tool in exactly the
+      state CSDK-014 exists to prevent: the TypeScript SDK has no docstring
+      fallback, so this argument is the entire account of the tool in the
+      prompt, and "TODO: describe this tool" tells the model nothing the tool
+      name did not. Nothing reports it — the SDK does not warn, the Zod schema
+      still validates, and the only symptom is a tool the model calls at the
+      wrong moment or never reaches for at all.
+    fix: >
+      Replace the placeholder with a real description covering what the tool
+      does, what it returns, and when the model should call it rather than a
+      neighboring tool. The SDK passes the string to the model verbatim, so
+      write it for the model rather than a human maintainer.
+
+  - id: CSDK-022
+    title: TypeScript Claude SDK tool description is too short to guide model selection
+    severity: low
+    confidence: 0.8
+    language: typescript
+    applies_to:
+      - claude_sdk_tool
+    scope: tool
+    match:
+      all:
+        - has_docstring: true
+        - description_length_lt: 40
+    explanation: >
+      A description under 40 characters is rarely enough to convey what a tool
+      does, what it returns, and when to call it rather than a similarly named
+      neighbor. With no docstring fallback in the TypeScript SDK, a stub like
+      "Gets data." is the whole prompt-side account of the tool, so scope and
+      preconditions are left to guesswork. The Zod input schema does not close
+      the gap: it constrains the shape of the arguments once the model has
+      decided to call this tool, and says nothing about whether calling it was
+      the right move.
+    fix: >
+      Expand the description to at least a full sentence covering inputs,
+      outputs, and the situation in which this tool should be used over the
+      alternatives. Where two tools are easy to confuse, say in each which one
+      the other case belongs to.