fix: address code review issues — DLP, thread safety, API naming

- Resolve README.md merge conflict
- NODE9_SKIP=1 now emits a warning and writes an audit entry (no silent bypass)
- configure() is now thread-safe via threading.Lock
- DLP scan covers all string args, not just params named filename/content
- _dispatch() renamed to dispatch() — public API should not have underscore
  (_dispatch kept as deprecated alias with DeprecationWarning)
- workspace validated at __init__ time with clear error if path doesn't exist
- @internal docstring clarifies it logs to stdout, not to audit trail
- README: shell=True examples now include sanitization warning
- README: _dispatch references updated to dispatch()

Author: node9ai

README.md

@@ -1,10 +1,6 @@
 # node9-python
 
-<<<<<<< dev
-Execution security for Python AI agents — audit, policy enforcement, and DLP in one package.
-=======
-Execution security for Python AI agents, one decorator, zero config.
->>>>>>> main
+Execution security for Python AI agents — audit, policy enforcement, and DLP in one package. One decorator, zero config.
 
 Works two ways:
 - **`@protect`** — add governance to any existing agent (LangChain, CrewAI, AutoGen, plain Python)
@@ -45,6 +41,8 @@ def write_file(path: str, content: str) -> None:
 @protect("bash")
 def run_shell(command: str) -> str:
     import subprocess
+    # Note: @protect gates on human approval but does NOT sanitize `command`.
+    # Use shlex.split() + shell=False for untrusted input.
     return subprocess.check_output(command, shell=True, text=True)
 
 try:
@@ -130,7 +128,9 @@ class CiAgent(Node9Agent):
     def run_tests(self, command: str) -> str:
         """Run the test suite and return output."""
         import subprocess
-        return subprocess.check_output(command, shell=True, text=True)
+        # Note: @protect gates on human approval but does NOT sanitize `command`.
+    # Use shlex.split() + shell=False for untrusted input.
+    return subprocess.check_output(command, shell=True, text=True)
 
     @tool("write_code")
     def write_code(self, filename: str, content: str) -> str:
@@ -164,7 +164,7 @@ while True:
     results = []
     for block in response.content:
         if block.type == "tool_use":
-            result = agent._dispatch(block.name, block.input)  # DLP + audit happen here
+            result = agent.dispatch(block.name, block.input)  # DLP + audit happen here
             results.append({"type": "tool_result", "tool_use_id": block.id, "content": result})
     messages.append({"role": "user", "content": results})
 ```
@@ -215,7 +215,7 @@ Patterns detected: AWS keys, GitHub tokens, Slack tokens, OpenAI keys, Stripe ke
 
 ```python
 try:
-    agent._dispatch("delete_file", {"path": "/etc/hosts"})
+    agent.dispatch("delete_file", {"path": "/etc/hosts"})
 except ActionDeniedException as e:
     # e.negotiation = "Action 'delete_file' was blocked by Node9: policy. Choose a different approach."
     response = llm.invoke(e.negotiation)

node9/__init__.py

@@ -2,24 +2,30 @@
 node9 — Execution security for Python AI agents.
 """
 
+import threading
+
 from ._decorator import protect
 from ._exceptions import ActionDeniedException, DaemonNotFoundError
 from ._dlp import dlp_scan, safe_path
 from ._agent import Node9Agent, tool, internal
 from . import _config
 
+_configure_lock = threading.Lock()
+
 
 def configure(*, agent_name: str = "", policy: str = "") -> None:
     """
     Set agent identity at runtime. Alternative to NODE9_AGENT_NAME / NODE9_AGENT_POLICY env vars.
-    Call before the first evaluate() / @protect / agent._dispatch().
+    Call before the first evaluate() / @protect / agent.dispatch().
+    Thread-safe — safe to call from concurrent async frameworks (LangGraph, FastMCP).
 
     policy values: "audit" | "require_approval" | "block_on_rules" | "" (SaaS default)
     """
-    if agent_name:
-        _config.AGENT_NAME = agent_name
-    if policy:
-        _config.AGENT_POLICY = policy
+    with _configure_lock:
+        if agent_name:
+            _config.AGENT_NAME = agent_name
+        if policy:
+            _config.AGENT_POLICY = policy
 
 
 __all__ = [

node9/_agent.py

@@ -78,20 +78,24 @@ def wrapper(self: "Node9Agent", *args: Any, **kwargs: Any) -> Any:
             bound.apply_defaults()
             call_args = {k: v for k, v in bound.arguments.items() if k != "self"}
 
-            # DLP scan
-            filename = call_args.get("filename") or call_args.get("path") or ""
-            content  = call_args.get("content") or ""
-            if filename or content:
-                hit = dlp_scan(str(filename), str(content))
-                if hit:
-                    raise ActionDeniedException(name, f"DLP blocked: {hit}")
-
-            # Path safety
-            if filename and hasattr(self, "_workspace") and self._workspace:
-                try:
-                    safe_path(str(filename), self._workspace)
-                except ValueError as e:
-                    raise ActionDeniedException(name, str(e)) from e
+            # DLP scan — all string args, not just well-known names
+            path_arg = call_args.get("filename") or call_args.get("path") or ""
+            all_content = "\n".join(
+                str(v) for v in call_args.values() if isinstance(v, str)
+            )
+            hit = dlp_scan(str(path_arg), all_content)
+            if hit:
+                raise ActionDeniedException(name, f"DLP blocked: {hit}")
+
+            # Path safety — any arg that looks like a file path
+            if hasattr(self, "_workspace") and self._workspace:
+                for v in call_args.values():
+                    if isinstance(v, str) and ("/" in v or "\\" in v):
+                        try:
+                            safe_path(v, self._workspace)
+                        except ValueError as e:
+                            raise ActionDeniedException(name, str(e)) from e
+                        break
 
             run_id = getattr(self, "_run_id", "")
             evaluate(name, call_args, run_id=run_id)
@@ -114,8 +118,10 @@ def internal(fn: Callable) -> Callable:
     """
     Marks a Node9Agent method as infrastructure (git plumbing, workspace setup).
 
-    - Never calls evaluate() — no SaaS call, no blocking
-    - Logs locally only: [node9 internal] method_name(args)
+    - Never calls evaluate() — no SaaS call, no blocking, no DLP scan
+    - Logs to stdout: [node9 internal] method_name(args)
+    - Use only for non-agent-decision code (git, workspace setup, file plumbing).
+      Do NOT use to bypass governance on agent-controlled actions.
     """
     @functools.wraps(fn)
     def wrapper(self: "Node9Agent", *args: Any, **kwargs: Any) -> Any:
@@ -138,21 +144,33 @@ class Node9Agent:
     Provides:
     - Agent identity and policy (set once, applied to every tool call)
     - Per-run UUID for grouping audit entries in the dashboard
-    - _build_tools()  — neutral tool spec for use with any LLM
     - build_tools_anthropic() — Anthropic input_schema format
     - build_tools_openai()    — OpenAI parameters format
-    - _dispatch()     — route LLM tool calls to @tool methods
+    - dispatch()      — route LLM tool calls to @tool methods (primary integration point)
 
     The LLM loop is NOT here — implement it in your subclass using whichever
     framework or API client you need.
+
+    When to use Node9Agent vs @protect:
+    - Node9Agent: greenfield agents where you control the tool definitions
+    - @protect:   retrofitting governance onto existing functions/classes
     """
 
     agent_name: str = ""
     policy:     str = "audit"
 
     def __init__(self, workspace: str = ""):
-        self._run_id    = str(uuid.uuid4())
-        self._workspace = os.path.realpath(workspace) if workspace else os.getcwd()
+        self._run_id = str(uuid.uuid4())
+        if workspace:
+            resolved = os.path.realpath(workspace)
+            if not os.path.isdir(resolved):
+                raise ValueError(
+                    f"Node9Agent workspace does not exist: {workspace!r}. "
+                    "Create the directory before constructing the agent."
+                )
+            self._workspace = resolved
+        else:
+            self._workspace = os.getcwd()
 
         from . import _config
         _config.AGENT_NAME   = self.agent_name or type(self).__name__
@@ -239,10 +257,14 @@ def build_tools_openai(self) -> list[dict]:
     # Dispatch
     # -------------------------------------------------------------------------
 
-    def _dispatch(self, tool_name: str, tool_input: dict) -> str:
+    def dispatch(self, tool_name: str, tool_input: dict) -> str:
         """
         Route a tool call by name to the matching @tool method.
         Returns a string result — or negotiation text if the action was denied.
+
+        This is the primary integration point for LLM loops:
+            result = agent.dispatch(block.name, block.input)  # Anthropic
+            result = agent.dispatch(call.function.name, json.loads(call.function.arguments))  # OpenAI
         """
         for attr_name in dir(type(self)):
             method = getattr(type(self), attr_name, None)
@@ -257,3 +279,13 @@ def _dispatch(self, tool_name: str, tool_input: dict) -> str:
                 except Exception as e:
                     return f"Error: {e}"
         return f"Unknown tool: {tool_name}"
+
+    def _dispatch(self, tool_name: str, tool_input: dict) -> str:
+        """Deprecated alias for dispatch(). Use dispatch() instead."""
+        import warnings
+        warnings.warn(
+            "Node9Agent._dispatch() is deprecated — use .dispatch() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.dispatch(tool_name, tool_input)

node9/_client.py

@@ -256,6 +256,13 @@ def evaluate(tool_name: str, args: dict[str, Any], *, run_id: str = "") -> None:
     Raises ActionDeniedException if the action is denied.
     """
     if os.environ.get("NODE9_SKIP") == "1":
+        import warnings
+        warnings.warn(
+            f"[Node9] NODE9_SKIP=1 — governance bypassed for '{tool_name}'. "
+            "Do not use in production.",
+            stacklevel=3,
+        )
+        _offline_audit(tool_name, {**args, "_skip": True}, run_id=run_id)
         return
 
     if os.environ.get("NODE9_API_KEY"):