react-agent-harness 0.3.1__tar.gz → 0.4.0__tar.gz

{react_agent_harness-0.3.1/react_agent_harness.egg-info → react_agent_harness-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: react-agent-harness
-Version: 0.3.1
+Version: 0.4.0
 Summary: Multi-agent LLM orchestration: hybrid DAG planning, two-tier memory, streaming
 Requires-Python: >=3.10
 License-File: LICENSE

{react_agent_harness-0.3.1 → react_agent_harness-0.4.0}/README.md

@@ -38,6 +38,8 @@ harness/events.py           BusEvent + EventType — canonical event vocabulary
 harness/llm/openai.py       OpenAILLM — OpenAI adapter with usage + cost tracking
 harness/annotation.py       Annotation store + AnnotationHook — RLHF trajectory capture
 harness/hitl.py             HITL approval gate — interactive CLI, session-allow list
+harness/tool_policy.py      Persistent tool policy — user-scoped allow rules, CLI management
+harness/console.py          ConsoleRenderer — centralised BusEvent formatting for CLI apps
 harness/steering.py         Async steering — agent.steer(text), StdinRouter pub/sub, FileSteer, factory helpers
 harness/checkpoint.py       CheckpointStore + _ResumeHint + maybe_resume_key — pluggable run-state persistence (file + Redis); auto-resume built into dispatch_stream / run_stream
 harness/otel.py             OTELHook — OpenTelemetry span exporter (opt-in)
@@ -74,6 +76,7 @@ explicit control.
 | `examples/executor_bridge_demo.py` | `ExecutorBridge` backends side-by-side: allowlist, env scrubbing, Docker network/fs isolation, timeout, positional-arg tools. | `ah-executor` and/or Docker |
 | `examples/durable_memory_demo.py` | Redis (semantic) + LanceDB (episodic) memory persistence across two related goals. | `OPENAI_API_KEY`, `[openai,redis,lance]`, Redis reachable |
 | `examples/mcp_demo.py` | Connects to an MCP filesystem server and gives the agent its tools. | `OPENAI_API_KEY`, `[openai,mcp]`, `npx` |
+| `examples/mcp_auth_demo.py` | Connects to an authenticated remote MCP server using bearer or auth-file credentials. | `OPENAI_API_KEY`, `[openai,mcp]`, `MCP_URL`, `MCP_BEARER_TOKEN` or `MCP_AUTH_PROVIDER` |
 | `examples/subscription_auth_demo.py` | Runs an agent through subscription-backed providers: direct `openai-codex` OAuth or direct `claude-code` OAuth. | `agent-harness login openai-codex` or `agent-harness login claude-code` |
 
 ## Adding a new domain (3 steps)
@@ -337,22 +340,96 @@ async for event in runtime.run_stream("investigate GPU spike on worker-07"):
         print(event.payload["answer"])
 ```
 
+### 4. Pre-built — `run_with_plan` / `run_with_plan_stream`
+
+Supply a hand-written `Plan` and bypass the LLM planner entirely. Use
+this for deterministic, repeatable workflows where the decomposition is
+known upfront — CI pipelines, ETL jobs, scheduled tasks. The plan is
+validated against registered agents before execution; everything
+downstream (parallel batches, replan-on-failure, synthesis, memory
+writes, steering) is identical to `run_stream`.
+
+```python
+from orchestrator.planner import Plan, Task
+
+plan = Plan([
+    Task("t1", "analyst",  "Analyse error logs from the last hour"),
+    Task("t2", "reporter", "Write an incident summary", depends_on=["t1"]),
+])
+
+# streaming
+async for event in runtime.run_with_plan_stream(plan, goal="Incident report"):
+    if event.type == EventType.DONE:
+        print(event.payload["answer"])
+
+# blocking
+result = await runtime.run_with_plan(plan, goal="Incident report")
+```
+
+The `goal` string is passed to the synthesiser and used for memory
+context injection into agents — even though the plan shape is fixed, the
+agents themselves still read from memory.
+
+If a task fails mid-run and `on_failure="replan"`, the replan call does
+go to the LLM — the bypass is for the *initial* plan only.
+
+---
+
 Event types by path:
 
-| Event | Dispatch | Routed | Direct | Orchestrated |
-|---|---|---|---|---|
-| `DISPATCH` | ✓ | — | — | — |
-| `ROUTE` | ✓ (simple) | ✓ | — | — |
-| `THOUGHT` / `TOKEN` / `ACTION` / `OBSERVATION` | ✓ | ✓ | ✓ | ✓ |
-| `TASK_DONE` | ✓ | ✓ | ✓ | ✓ |
-| `PLAN` / `REPLAN` / `SYNTHESIS` / `DONE` | ✓ (complex) | — | — | ✓ |
-| `ERROR` | ✓ | ✓ | ✓ | ✓ |
+| Event | Dispatch | Routed | Direct | Orchestrated | Pre-built |
+|---|---|---|---|---|---|
+| `DISPATCH` | ✓ | — | — | — | — |
+| `ROUTE` | ✓ (simple) | ✓ | — | — | — |
+| `THOUGHT` / `TOKEN` / `ACTION` / `OBSERVATION` | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `TASK_DONE` | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `PLAN` / `REPLAN` / `SYNTHESIS` / `DONE` | ✓ (complex) | — | — | ✓ | ✓ |
+| `ERROR` | ✓ | ✓ | ✓ | ✓ | ✓ |
 
 `TOKEN` events fire only when your LLM client exposes
 `async def stream_complete(system, messages) -> AsyncGenerator[str, None]`.
 Non-streaming clients still work — they emit the full response in one
 `THOUGHT` event per step.
 
+## Console rendering
+
+`ConsoleRenderer` handles all `BusEvent` types with consistent label
+and truncation formatting so event-loop boilerplate stays out of your
+scripts.
+
+```python
+from harness.console import ConsoleRenderer, trunc
+
+renderer = ConsoleRenderer(
+    truncate=140,          # max chars for long text fields
+    sep_char="─",          # separator character
+    sep_width=72,          # separator width
+    agent_label_width=16,  # width of [agent_id] column
+    show_tokens=False,     # True to print TOKEN events inline
+)
+
+async for event in runtime.dispatch_stream(goal):
+    renderer.render(event)   # handles every EventType
+```
+
+For events with custom section headers (e.g. a "PROJECT HEALTH REPORT"
+block), handle that event yourself and skip `render` for it — the
+renderer is additive:
+
+```python
+async for event in runtime.run_stream(goal):
+    if event.type == EventType.DONE:
+        renderer.sep("═")
+        print("MY CUSTOM HEADER")
+        renderer.sep("═")
+        print(event.payload["answer"])
+    else:
+        renderer.render(event)
+```
+
+`trunc(s, n)` is exported for standalone use when you need to truncate
+a string to `n` characters with a trailing `…`.
+
 ## Working memory budget
 
 `AgentConfig.working_memory_max_tokens` controls per-agent eviction (default
@@ -518,7 +595,48 @@ async with MCPServerConnection(params, server_name="filesystem") as conn:
 Supports **stdio** and **SSE** transports. The `MCPServerConnection` context
 manager handles the full lifecycle — connect, discover, and cleanup.
 
-See `examples/mcp_demo.py` for a runnable example.
+Remote MCP servers can receive static headers or bearer tokens through an auth
+provider:
+
+```python
+import os
+from tools.mcp import MCPServerConnection, StaticMCPAuth
+
+auth = StaticMCPAuth(
+    headers={
+        "DD_API_KEY": os.environ["DD_API_KEY"],
+        "DD_APPLICATION_KEY": os.environ["DD_APPLICATION_KEY"],
+    }
+)
+
+async with MCPServerConnection(
+    {"url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp"},
+    server_name="datadog",
+    auth=auth,
+) as conn:
+    conn.register_tools(tool_registry)
+```
+
+OAuth-style auth files can be reused for MCP bearer auth:
+
+```python
+from tools.mcp import MCPServerConnection, OAuthMCPAuth
+
+auth = OAuthMCPAuth.from_auth_file(
+    "~/.agent-harness/auth/auth.json",
+    provider="datadog-mcp",
+)
+
+async with MCPServerConnection(
+    {"url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp"},
+    server_name="datadog",
+    auth=auth,
+) as conn:
+    conn.register_tools(tool_registry)
+```
+
+See `examples/mcp_demo.py` for local stdio MCP and `examples/mcp_auth_demo.py`
+for authenticated remote MCP.
 
 ## OpenTelemetry Tracing
 
@@ -699,10 +817,10 @@ When the agent calls `write_file` or `delete_file` a prompt appears:
   Run:   3f7a1b2c-...:file_agent
   ID:    a1b2-c3d4
 ────────────────────────────────────────────────────────────
-  y = approve once  |  a = allow 'delete_file' for session  |  n = reject  |  <text> = steer
+  y = approve once  |  a = allow 'delete_file' for session  |  A = always allow 'delete_file'  |  n = reject  |  <text> = steer
   Ctrl-C to pause. Resume: python my_script.py --resume 3f7a1b2c-...:file_agent
 ────────────────────────────────────────────────────────────
-  Approve? [y/n/a/correction]:
+  Approve? [y/n/a/A/correction]:
 ```
 
 **Prompt semantics:**
@@ -712,11 +830,19 @@ When the agent calls `write_file` or `delete_file` a prompt appears:
 | `y` / `yes` | Tool runs once |
 | `n` / `no` | Tool skipped; agent sees a rejection observation |
 | `a` / `allow` | Tool runs **and** added to session allow-list; no further prompts for this tool (or command prefix for shell-like tools) |
+| `A` / `always` | Tool runs **and** a user-scoped allow rule is stored in `~/.agent-harness/policies/tool_policy.json` |
 | any other text | Correction: tool skipped, text injected into `WorkingMemory` as a user message; LLM self-corrects on the next step |
 
-For shell-like tools (`shell`, `bash`, `run`, `exec`), `a` allows the **first
-word** of the command — e.g. typing `a` when approving `shell git commit ...`
-allows all `git` commands for the session but still prompts for `shell rm ...`.
+For shell-like tools (`shell`, `bash`, `run`, `exec`), `a` and `A` allow the
+**first word** of the command — e.g. approving `shell git commit ...` allows
+all `git` commands in that scope but still prompts for `shell rm ...`.
+Persistent rules are user-local, not repo files. Manage them with:
+
+```bash
+agent-harness policy list
+agent-harness policy revoke <rule-id>
+agent-harness policy clear
+```
 
 **Wall-time budget** is suspended while waiting for input — human think-time
 does not count against `max_wall_time_seconds`.
@@ -909,3 +1035,20 @@ key-bindings (like Enter-submits and Alt-Enter/Ctrl-J-newline) across both paths
 
 See `examples/complex_sysaudit_demo.py` for stdin steering across three
 agents alongside HITL on the shell tool.
+
+## AgentConfig reference
+
+| Field | Default | Description |
+|---|---|---|
+| `agent_id` | required | Unique identifier for the agent |
+| `role` | required | Plain-English description used by the planner for agent selection |
+| `system_prompt` | required | Base system prompt for the agent |
+| `allowed_tools` | required | Tool names the agent may call |
+| `max_steps` | `10` | Maximum ReAct iterations before the run is terminated |
+| `max_wall_time_seconds` | (guardrail) | See `GuardrailConfig` |
+| `memory_context_enabled` | `True` | Prepend relevant long-term memory to the system prompt |
+| `confidence_from_llm` | `True` | Use the `confidence` field from the LLM response; set `False` to always return `1.0` |
+| `working_memory_max_tokens` | `8000` | Token budget for in-context working memory before rolling summarisation kicks in |
+| `hitl_tools` | `[]` | Tool names that require human approval before execution |
+| `checkpoint_every` | `0` | Write a crash-resumable checkpoint every N steps; `0` disables periodic checkpoints |
+| `stream_tokens` | `False` | Emit `TOKEN` events as the LLM streams. Disabled by default — enable if you want to render partial output in real time: `AgentConfig(..., stream_tokens=True)` |

{react_agent_harness-0.3.1 → react_agent_harness-0.4.0}/agents/base.py

@@ -61,6 +61,7 @@ class AgentConfig:
     max_steps: int = 10
     memory_context_enabled: bool = True
     confidence_from_llm: bool = True  # if False, confidence=1.0 on success
+    stream_tokens: bool = False  # if True, TOKEN events are emitted as the LLM streams
     working_memory_max_tokens: int = 8000  # WorkingMemory eviction threshold; tune per agent
     hitl_tools: list[str] = None  # tools requiring human approval; None = no HITL
     checkpoint_every: int = 0  # write a resumable checkpoint every N steps; 0 = disabled
@@ -649,11 +650,12 @@ class BaseAgent:
                     messages=messages,
                 ):
                     accumulated += token
-                    yield BusEvent(
-                        type=EventType.TOKEN,
-                        agent_id=self.config.agent_id,
-                        token=token,
-                    )
+                    if self.config.stream_tokens:
+                        yield BusEvent(
+                            type=EventType.TOKEN,
+                            agent_id=self.config.agent_id,
+                            token=token,
+                        )
                 response = _parse_action_json(accumulated)
                 if response is None:
                     logger.warning(
@@ -736,10 +738,10 @@ class BaseAgent:
         if not (self._checkpoint_store and tool_name in self.config.hitl_tools):
             return None
 
-        from harness.hitl import ApprovalRequest, is_session_allowed, request_approval
+        from harness.hitl import ApprovalRequest, is_allowed, request_approval
 
-        if is_session_allowed(tool_name, tool_args):
-            return None  # fast-path: human already allowed this tool/prefix for session
+        if is_allowed(tool_name, tool_args):
+            return None  # fast-path: human already allowed this tool/prefix
 
         approval_id = str(uuid.uuid4())
         await self._checkpoint_store.write(
@@ -840,33 +842,35 @@ class BaseAgent:
         pending: dict,
     ) -> AsyncGenerator[BusEvent, None]:
         """Re-prompt approval for a step interrupted by a crash, then complete it."""
-        from harness.hitl import ApprovalRequest, request_approval
+        from harness.hitl import ApprovalRequest, is_allowed, request_approval
 
         tool_name = pending["tool"]
         tool_args = pending["args"]
         step = pending["step"]
         llm_response = pending["llm_response"]
 
-        approval = await request_approval(
-            ApprovalRequest(
-                approval_id=pending["approval_id"],
-                run_id=self._resume_key,  # standalone: ckp_id; orchestrated: outer run_id
-                agent_id=self.config.agent_id,
-                tool=tool_name,
-                args=tool_args,
-                step=step,
-                timestamp=datetime.now(timezone.utc).isoformat(),
-            ),
-            self._guard,
-        )
+        approval = None
+        if not is_allowed(tool_name, tool_args):
+            approval = await request_approval(
+                ApprovalRequest(
+                    approval_id=pending["approval_id"],
+                    run_id=self._resume_key,  # standalone: ckp_id; orchestrated: outer run_id
+                    agent_id=self.config.agent_id,
+                    tool=tool_name,
+                    args=tool_args,
+                    step=step,
+                    timestamp=datetime.now(timezone.utc).isoformat(),
+                ),
+                self._guard,
+            )
 
-        if approval.correction:
+        if approval is not None and approval.correction:
             await self._inject_human_guidance(llm_response, approval.correction, run_id, step)
             return
 
         observation = (
             await self._execute_tool(tool_name, tool_args)
-            if approval.approved
+            if approval is None or approval.approved
             else f"Tool rejected by human: {approval.correction or 'no reason given'}"
         )
         obs_display = "[image]" if _is_image_block(observation) else str(observation)[:500]

{react_agent_harness-0.3.1 → react_agent_harness-0.4.0}/harness/cli.py

@@ -14,6 +14,7 @@ from harness.llm.auth import (
     OpenAICodexOAuthClient,
     default_auth_file,
 )
+from harness.tool_policy import ToolPolicyStore, default_policy_file
 
 PROVIDERS = ["openai-codex", "claude-code"]
 
@@ -35,6 +36,16 @@ def main() -> int:
     logout_cmd.add_argument("provider", choices=PROVIDERS)
     logout_cmd.add_argument("--auth-file", default=str(default_auth_file()))
 
+    policy = sub.add_parser("policy", help="manage persistent tool policy")
+    policy_sub = policy.add_subparsers(dest="policy_command", required=True)
+    policy_list = policy_sub.add_parser("list", help="list persistent policy rules")
+    policy_list.add_argument("--policy-file", default=str(default_policy_file()))
+    policy_revoke = policy_sub.add_parser("revoke", help="remove one policy rule")
+    policy_revoke.add_argument("rule_id")
+    policy_revoke.add_argument("--policy-file", default=str(default_policy_file()))
+    policy_clear = policy_sub.add_parser("clear", help="remove all policy rules")
+    policy_clear.add_argument("--policy-file", default=str(default_policy_file()))
+
     args = parser.parse_args()
     try:
         if args.command == "login":
@@ -52,6 +63,14 @@ def main() -> int:
                 return _logout_oauth_provider(Path(args.auth_file).expanduser(), "openai-codex")
             if args.provider == "claude-code":
                 return _logout_oauth_provider(Path(args.auth_file).expanduser(), "claude-code")
+        if args.command == "policy":
+            path = Path(args.policy_file).expanduser()
+            if args.policy_command == "list":
+                return _policy_list(path)
+            if args.policy_command == "revoke":
+                return _policy_revoke(path, args.rule_id)
+            if args.policy_command == "clear":
+                return _policy_clear(path)
     except Exception as e:
         print(f"agent-harness: {e}", file=sys.stderr)
         return 1
@@ -133,5 +152,26 @@ def _write_oauth_credential(path: Path, cred: OAuthCredential) -> None:
     provider._write_credential(cred)
 
 
+def _policy_list(path: Path) -> int:
+    store = ToolPolicyStore(path)
+    rules = [rule.to_dict() for rule in store.list_rules()]
+    print(json.dumps({"policy_file": str(path), "rules": rules}, indent=2))
+    return 0
+
+
+def _policy_revoke(path: Path, rule_id: str) -> int:
+    if not ToolPolicyStore(path).revoke(rule_id):
+        print(f"Policy rule not found: {rule_id}", file=sys.stderr)
+        return 1
+    print(f"Removed policy rule: {rule_id}")
+    return 0
+
+
+def _policy_clear(path: Path) -> int:
+    count = ToolPolicyStore(path).clear()
+    print(f"Removed {count} policy rule(s)")
+    return 0
+
+
 if __name__ == "__main__":
     raise SystemExit(main())

react_agent_harness-0.4.0/harness/console.py

@@ -0,0 +1,166 @@
+"""Standard console renderer for BusEvent streams."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TextIO
+
+from harness.events import BusEvent, EventType
+
+
+def trunc(s: str, n: int) -> str:
+    """Truncate *s* to *n* characters, appending '…' when clipped."""
+    return s if len(s) <= n else s[:n] + "…"
+
+
+class ConsoleRenderer:
+    """Renders BusEvent objects to a text stream.
+
+    Centralises all event-type formatting so callers don't duplicate
+    THOUGHT/ACTION/OBSERVATION/... blocks and separator/truncation helpers.
+
+    Args:
+        truncate:           Max characters for long text fields.
+        sep_char:           Character used for separator lines.
+        sep_width:          Width of separator lines.
+        agent_label_width:  Width of the ``[agent_id]`` label column.
+        show_tokens:        If True, TOKEN events are printed inline.
+        out:                Output stream (defaults to ``sys.stdout``).
+    """
+
+    def __init__(
+        self,
+        *,
+        truncate: int = 140,
+        sep_char: str = "─",
+        sep_width: int = 72,
+        agent_label_width: int = 16,
+        show_tokens: bool = False,
+        out: TextIO | None = None,
+    ) -> None:
+        self._truncate = truncate
+        self._sep_char = sep_char
+        self._sep_width = sep_width
+        self._label_w = agent_label_width
+        self._show_tokens = show_tokens
+        self._out = out or sys.stdout
+        self._in_token_stream = False
+
+    # ── public helpers ────────────────────────────────────────────────────────
+
+    def sep(self, char: str | None = None, w: int | None = None) -> None:
+        """Print a separator line."""
+        print((char or self._sep_char) * (w or self._sep_width), file=self._out)
+
+    def render(self, event: BusEvent) -> None:
+        """Print formatted output for one BusEvent."""
+        if event.type == EventType.TOKEN:
+            if self._show_tokens:
+                if not self._in_token_stream:
+                    self._in_token_stream = True
+                self._out.write(event.token)
+                self._out.flush()
+            return
+
+        # Close any in-progress token stream before the next event line.
+        if self._in_token_stream:
+            self._out.write("\n")
+            self._out.flush()
+            self._in_token_stream = False
+
+        t = event.type
+        p = event.payload
+
+        if t == EventType.DISPATCH:
+            print(
+                f"\n[dispatch]   complexity={p.get('complexity')}  path={p.get('path')}",
+                file=self._out,
+            )
+
+        elif t == EventType.ROUTE:
+            print(
+                f"[route]      → {p.get('agent_id')}: {trunc(p.get('rationale', ''), 90)}",
+                file=self._out,
+            )
+
+        elif t == EventType.PLAN:
+            tasks = p.get("plan", {}).get("tasks", [])
+            print(f"\n[plan]       {len(tasks)} tasks", file=self._out)
+            for task in tasks:
+                deps = f"  ← {task['depends_on']}" if task.get("depends_on") else ""
+                print(
+                    f"             {task['id']}@{task['agent_id']}: "
+                    f"{trunc(task.get('instruction', ''), 70)}{deps}",
+                    file=self._out,
+                )
+
+        elif t == EventType.THOUGHT:
+            thought = p.get("thought", "")
+            if thought:
+                print(
+                    f"{self._label(event)} think   {trunc(thought, 110)}",
+                    file=self._out,
+                )
+
+        elif t == EventType.ACTION:
+            args = json.dumps(p.get("args", {}), default=str)
+            print(
+                f"{self._label(event)} action  {p.get('tool')}({trunc(args, 90)})",
+                file=self._out,
+            )
+
+        elif t == EventType.OBSERVATION:
+            obs = p.get("observation", "")
+            print(
+                f"{self._label(event)} obs     {trunc(obs, 110)}",
+                file=self._out,
+            )
+
+        elif t == EventType.HUMAN_GUIDANCE:
+            print(
+                f"\n{self._label(event)} ▶ steered  step={p.get('step')}  text={p.get('text')!r}",
+                file=self._out,
+            )
+
+        elif t == EventType.TASK_DONE:
+            print(
+                f"{self._label(event)} ✓ done  "
+                f"confidence={p.get('confidence', 0):.2f}  steps={p.get('steps', '?')}",
+                file=self._out,
+            )
+
+        elif t == EventType.REPLAN:
+            print(
+                f"\n[replan]     #{p.get('replan_count')} — trigger={p.get('trigger_task', '?')}",
+                file=self._out,
+            )
+
+        elif t == EventType.SYNTHESIS:
+            print(
+                f"\n[synthesis]  confidence={p.get('confidence', 0):.2f}",
+                file=self._out,
+            )
+
+        elif t == EventType.DONE:
+            print(file=self._out)
+            self.sep("═")
+            print(p.get("answer", "(no answer)"), file=self._out)
+            self.sep()
+            print(
+                f"Confidence: {p.get('confidence', 0):.2f}  |  "
+                f"Replans: {p.get('replan_count', 0)}  |  "
+                f"Cost: ${p.get('cost_usd', 0):.4f}  |  "
+                f"Time: {p.get('elapsed_seconds', 0):.1f}s",
+                file=self._out,
+            )
+
+        elif t == EventType.ERROR:
+            print(f"\n[error]      {event.error}", file=sys.stderr)
+
+    # ── private helpers ───────────────────────────────────────────────────────
+
+    def _label(self, event: BusEvent) -> str:
+        if event.agent_id:
+            return f"[{event.agent_id:<{self._label_w}}]"
+        return f"[{event.type.value:<{self._label_w}}]"

{react_agent_harness-0.3.1 → react_agent_harness-0.4.0}/harness/hitl.py

@@ -8,7 +8,7 @@ Same-session flow:
   2. A checkpoint is written to the CheckpointStore (step + WorkingMemory +
      pending tool).  BudgetGuard clock suspends.
   3. Approval banner is printed to the terminal.
-  4. Human types  y / n / a / <correction>  in the terminal.
+  4. Human types  y / n / a / A / <correction>  in the terminal.
   5. Guard resumes; agent continues (or injects correction and skips the tool).
 
 Crash / Ctrl-C / kill flow:
@@ -22,7 +22,7 @@ Crash / Ctrl-C / kill flow:
 The UUID printed at the prompt is an audit reference only.
 
 Correction steering:
-  Any text that isn't y/yes/a/allow/n/no is treated as a correction.
+  Any text that isn't y/yes/a/allow/A/always/n/no is treated as a correction.
   The gated tool is skipped and the text is injected into WorkingMemory
   as a user message, so the LLM sees it on the next think step.
 
@@ -32,6 +32,11 @@ Session allow:
   first word of the command arg (e.g. 'git'), so allowing 'git' doesn't also
   allow 'rm'.  Subsequent calls matching the key skip checkpoint + banner.
   Use is_session_allowed(tool, args) to query the list from outside.
+
+Persistent allow:
+  Typing  A  or  always  approves the current call and writes a user-scoped
+  allow rule to ~/.agent-harness/policies/tool_policy.json. Rules are narrow:
+  shell-like tools are scoped by first command word, other tools by tool name.
 """
 
 from __future__ import annotations
@@ -73,6 +78,18 @@ def is_session_allowed(tool: str, args: dict) -> bool:
     return _session_key(tool, args) in _session_allowed
 
 
+def is_persistently_allowed(tool: str, args: dict) -> bool:
+    """True if this tool+args combination is allowed by the user policy file."""
+    from harness.tool_policy import ToolPolicyStore
+
+    return ToolPolicyStore().is_allowed(tool, args)
+
+
+def is_allowed(tool: str, args: dict) -> bool:
+    """True if this tool+args combination is session- or user-policy allowed."""
+    return is_session_allowed(tool, args) or is_persistently_allowed(tool, args)
+
+
 def _session_label(tool: str, args: dict) -> str:
     """Human-readable description of what 'a' would allow."""
     _, prefix = _session_key(tool, args)
@@ -122,6 +139,7 @@ class ApprovalResponse:
     approved: bool
     correction: str | None = None  # non-None → steering; tool is skipped
     session_allow: bool = False  # True → add (tool, prefix) to _session_allowed
+    persistent_allow: bool = False  # True → write a user-scoped allow rule
 
 
 # ── CLI gate ──────────────────────────────────────────────────────────────────
@@ -140,21 +158,29 @@ def _print_banner(req: ApprovalRequest) -> None:
     print(f"  ID:    {req.approval_id}")
     print(_SEP)
     print(
-        f"  y = approve once  |  a = allow '{label}' for session  |  n = reject  |  <text> = steer"
+        "  y = approve once  |  "
+        f"a = allow '{label}' for session  |  "
+        f"A = always allow '{label}'  |  "
+        "n = reject  |  <text> = steer"
     )
     print(f"  Ctrl-C to pause. Resume: python {script} --resume {req.run_id}")
     print(_SEP)
 
 
 def _parse_stdin(approval_id: str, raw: str) -> ApprovalResponse:
-    lo = raw.strip().lower()
+    stripped = raw.strip()
+    if stripped == "A":
+        return ApprovalResponse(approval_id=approval_id, approved=True, persistent_allow=True)
+    lo = stripped.lower()
     if lo in ("y", "yes"):
         return ApprovalResponse(approval_id=approval_id, approved=True)
     if lo in ("a", "allow"):
         return ApprovalResponse(approval_id=approval_id, approved=True, session_allow=True)
+    if lo in ("always", "allow always"):
+        return ApprovalResponse(approval_id=approval_id, approved=True, persistent_allow=True)
     if lo in ("n", "no"):
         return ApprovalResponse(approval_id=approval_id, approved=False)
-    return ApprovalResponse(approval_id=approval_id, approved=True, correction=raw.strip() or None)
+    return ApprovalResponse(approval_id=approval_id, approved=True, correction=stripped or None)
 
 
 async def request_approval(
@@ -172,6 +198,7 @@ async def request_approval(
       y / yes     → approved, tool runs
       n / no      → rejected, tool skipped (error observation returned)
       a / allow   → approved + session-allow registered; tool runs
+      A / always  → approved + user policy allow registered; tool runs
       <any text>  → correction injected into WorkingMemory; tool skipped
 
     Holds stdout_lock for the duration so concurrent agent events don't
@@ -190,7 +217,7 @@ async def request_approval(
 
     async with stdout_lock:
         router = get_active_router()
-        approve_prompt = "  Approve? [y/n/a/correction]: "
+        approve_prompt = "  Approve? [y/n/a/A/correction]: "
         # If a router is active, reserve the next stdin read BEFORE printing
         # the banner so the user's typed answer routes to HITL (not steering).
         hitl_future: Any = (
@@ -226,4 +253,9 @@ async def request_approval(
         if resp.session_allow:
             _session_allowed.add(_session_key(req.tool, req.args))
             print(f"  ✓ '{_session_label(req.tool, req.args)}' allowed for this session\n")
+        if resp.persistent_allow:
+            from harness.tool_policy import ToolPolicyStore
+
+            rule = ToolPolicyStore().add_allow_rule(tool=req.tool, args=req.args)
+            print(f"  ✓ '{_session_label(req.tool, req.args)}' always allowed ({rule.id})\n")
         return resp