aria-code 0.52.0__py3-none-any.whl

aria_code/apps/cli/tools/system_tools.py

@@ -0,0 +1,726 @@
+"""System-level tools: run_command, web_fetch, github.
+
+All functions are pure (no module-level globals). Console output is
+injected via keyword args so aria_cli.py thin wrappers supply the
+Rich console and global state defaults.
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import re
+import shlex
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+_ROOT = Path(__file__).parent.parent.parent.parent  # aria-code/
+if str(_ROOT) not in sys.path:
+    sys.path.insert(0, str(_ROOT))
+
+from aria_code.safety import evaluate_command_policy  # noqa: E402
+
+
+def _persist_command_output(command: str, stdout: str, stderr: str, returncode: int) -> dict:
+    """Persist full command output when it is too large for inline tool context."""
+    stdout_lines = stdout.splitlines()
+    stderr_lines = stderr.splitlines()
+    if (
+        len(stdout) <= 2500
+        and len(stderr) <= 1200
+        and len(stdout_lines) <= 18
+        and len(stderr_lines) <= 8
+    ):
+        return {}
+    try:
+        from aria_code.artifacts import create_artifact, write_artifact_metadata
+
+        record = create_artifact(
+            "command-output",
+            "shell",
+            "command_output",
+            ".txt",
+            timestamp=datetime.now(),
+        )
+        text = (
+            f"$ {command}\n"
+            f"exit_code={returncode}\n\n"
+            "===== STDOUT =====\n"
+            f"{stdout}"
+            "\n\n===== STDERR =====\n"
+            f"{stderr}"
+        )
+        record.path.write_text(text, encoding="utf-8", errors="replace")
+        write_artifact_metadata(record, {
+            "kind": "command_output",
+            "status": "complete" if returncode == 0 else "failed",
+            "created_at": datetime.now().isoformat(timespec="seconds"),
+            "command": command,
+            "exit_code": returncode,
+            "stdout_chars": len(stdout),
+            "stderr_chars": len(stderr),
+            "stdout_truncated_inline": len(stdout) > 5000,
+            "stderr_truncated_inline": len(stderr) > 2000,
+        })
+        return {"full_output_path": str(record.path)}
+    except Exception:
+        return {}
+
+
+def _cprint(msg: str, *, console, has_rich: bool) -> None:
+    if has_rich and console is not None:
+        console.print(msg)
+    else:
+        plain = re.sub(r"\[/?[^\]]+\]", "", msg)
+        print(plain)
+
+
+def tool_run_command(
+    params: dict,
+    *,
+    console=None,
+    has_rich: bool = True,
+) -> dict:
+    """Run a shell command and return output.
+
+    ``params`` should contain ``permission_mode`` and ``network_enabled``
+    (filled in by the aria_cli.py wrapper from the active globals).
+    """
+    command = params.get("command", "")
+    # LLMs sometimes send command as a list e.g. ['bash', '-lc', '...'] — normalize to string
+    if isinstance(command, list):
+        import shlex as _shlex
+        command = _shlex.join(str(c) for c in command)
+        params["command"] = command
+    if not command:
+        return {"success": False, "error": "Missing 'command' parameter"}
+
+    effective_policy = params.get("policy", "safe")
+    if params.get("user_approved") and effective_policy == "safe":
+        effective_policy = "balanced"
+
+    decision = evaluate_command_policy(
+        command,
+        effective_policy,
+        # "safe" is a *policy* name, not a mode — it never matched
+        # PermissionMode and silently resolved to workspace-write. Both
+        # executors supply a real mode, so this default is only reached
+        # by a caller that bypasses them; read-only is the right answer
+        # there.
+        mode=params.get("permission_mode", "read-only"),
+        network_enabled=bool(params.get("network_enabled", True)),
+    )
+    command = decision.normalized_command
+
+    dangerous = ["rm -rf /", "mkfs", "dd if=", "> /dev/", ":(){ :", "fork bomb"]
+    for d in dangerous:
+        if d in command:
+            return {"success": False, "error": f"Blocked dangerous command: {command}"}
+
+    # Prevent executing text/doc files as Python — they are analysis reports, not scripts
+    import re as _re_cmd
+    _py3_file = _re_cmd.search(r'\bpython3?\s+["\']?(\S+\.(?:txt|md|docx|csv|json|log))', command)
+    if _py3_file:
+        _bad_file = _py3_file.group(1)
+        return {
+            "success": False,
+            "error": (
+                f"拒绝执行: '{_bad_file}' 是文本/分析文件，不是 Python 脚本。\n"
+                "如需展示分析结果，请直接输出文字，或将分析结论写入 .py 文件后执行。"
+            ),
+        }
+
+    if params.get("dry_run"):
+        return {"success": True, "data": {
+            "command": command,
+            "risk": decision.risk,
+            "policy": decision.policy,
+            "requires_approval": getattr(decision, "requires_approval", False),
+            "network": getattr(decision, "network", False),
+            "dry_run": True,
+        }}
+    if not decision.allowed:
+        return {"success": False, "error": decision.reason}
+    try:
+        cwd = params.get("cwd", None)
+        timeout = min(params.get("timeout", 120), 300)
+        use_shell = True
+        argv = None
+        if decision.risk == "low":
+            has_shell_meta = any(ch in command for ch in ["|", "&", ";", "<", ">", "$", "`", "\n"])
+            if not has_shell_meta:
+                try:
+                    argv = shlex.split(command)
+                    if argv:
+                        use_shell = False
+                except ValueError:
+                    use_shell = True
+                    argv = None
+
+        sandbox = params.get("sandbox", False)
+        if sandbox:
+            try:
+                from aria_code.apps.cli.sandbox import run_in_docker_sandbox
+                result = run_in_docker_sandbox(
+                    command=command,
+                    cwd=cwd,
+                    timeout=timeout,
+                    image="python:3.11-slim"
+                )
+            except Exception as e:
+                return {"success": False, "error": f"Sandbox execution failed: {e}"}
+        else:
+            result = subprocess.run(
+                argv if (argv and not use_shell) else command,
+                shell=use_shell,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                cwd=cwd,
+            )
+        full_stdout = result.stdout
+        full_stderr = result.stderr
+        output = full_stdout[-5000:] if len(full_stdout) > 5000 else full_stdout
+        stderr = full_stderr[-2000:] if len(full_stderr) > 2000 else full_stderr
+        output_artifact = _persist_command_output(command, full_stdout, full_stderr, result.returncode)
+
+        # ── Auto-fix loop (up to 3 rounds for python3 scripts) ──────────────
+        MAX_AUTO_FIX_ROUNDS = 3
+        _cmd_tail = (
+            command.strip().split("python3 ", 1)[-1].strip().split()
+            if command.strip().startswith("python3 ") else []
+        )
+        if result.returncode != 0 and _cmd_tail:
+            script_path = _cmd_tail[0]
+            script_p = pathlib.Path(script_path).expanduser().resolve()
+
+            for _fix_round in range(MAX_AUTO_FIX_ROUNDS):
+                combined_err = (output + " " + stderr).strip()
+                auto_fixed = False
+
+                if not (script_p.exists() and script_p.suffix == ".py"):
+                    break
+                script_content = script_p.read_text(errors="replace")
+
+                name_match = re.search(r"NameError: name ['\"](\w+)['\"] is not defined", combined_err)
+                if name_match and not auto_fixed:
+                    missing = name_match.group(1)
+                    import_map = {
+                        "os": "import os", "sys": "import sys", "re": "import re",
+                        "json": "import json", "math": "import math", "time": "import time",
+                        "np": "import numpy as np", "pd": "import pandas as pd",
+                        "yf": "import yfinance as yf", "plt": "import matplotlib.pyplot as plt",
+                        "mpf": "import mplfinance as mpf",
+                        "datetime": "from datetime import datetime, timedelta",
+                        "Path": "from pathlib import Path",
+                        "timedelta": "from datetime import datetime, timedelta",
+                        "go": "import plotly.graph_objects as go",
+                        "px": "import plotly.express as px",
+                        "ta": "import pandas_ta as ta", "warnings": "import warnings",
+                        "make_subplots": "from plotly.subplots import make_subplots",
+                        "bt": "import backtrader as bt", "vbt": "import vectorbt as vbt",
+                        "ccxt": "import ccxt", "requests": "import requests",
+                        "BeautifulSoup": "from bs4 import BeautifulSoup",
+                        "tqdm": "from tqdm import tqdm",
+                        "xgb": "import xgboost as xgb",
+                        "Prophet": "from prophet import Prophet",
+                        "arch": "from arch import arch_model",
+                        "statsmodels": "import statsmodels.api as sm",
+                        "sm": "import statsmodels.api as sm",
+                    }
+                    fix_import = import_map.get(missing)
+                    if fix_import and fix_import not in script_content:
+                        lines = script_content.split("\n")
+                        insert_at = 0
+                        for i, l in enumerate(lines):
+                            if l.strip().startswith("#!") or l.strip().startswith("# -*-"):
+                                insert_at = i + 1
+                            else:
+                                break
+                        lines.insert(insert_at, fix_import)
+                        if missing == "plt" and "matplotlib.use" not in script_content:
+                            lines.insert(insert_at, "import matplotlib; matplotlib.use('Agg')")
+                        script_p.write_text("\n".join(lines))
+                        auto_fixed = True
+                        _cprint(
+                            f"  [#C08050]Auto-fix[{_fix_round+1}/{MAX_AUTO_FIX_ROUNDS}]:"
+                            f"[/#C08050] [dim]added '{fix_import}'[/dim]",
+                            console=console, has_rich=has_rich,
+                        )
+
+                if not auto_fixed and (
+                    "cannot be resolved at runtime" in combined_err.lower()
+                    or ("matplotlib" in combined_err and "backend" in combined_err.lower())
+                ):
+                    if "matplotlib.use" not in script_content and "matplotlib.pyplot" in script_content:
+                        script_content = script_content.replace(
+                            "import matplotlib.pyplot as plt",
+                            "import matplotlib; matplotlib.use('Agg')\nimport matplotlib.pyplot as plt",
+                        )
+                        script_p.write_text(script_content)
+                        auto_fixed = True
+                        _cprint(
+                            f"  [#C08050]Auto-fix[{_fix_round+1}]:[/#C08050]"
+                            " [dim]added matplotlib.use('Agg')[/dim]",
+                            console=console, has_rich=has_rich,
+                        )
+
+                key_match = re.search(
+                    r"KeyError: ['\"]?(Close|Open|High|Low|Volume|Adj Close)", combined_err
+                )
+                if key_match and not auto_fixed and "yfinance" in script_content:
+                    if "columns.droplevel" not in script_content:
+                        fix_line = (
+                            "\n# Fix yfinance MultiIndex columns\n"
+                            "if isinstance(df.columns, pd.MultiIndex):\n"
+                            "    df.columns = df.columns.droplevel(1)\n"
+                        )
+                        dl_match = re.search(r"(.*=\s*yf\.download\([^)]+\))", script_content)
+                        if dl_match:
+                            script_content = script_content.replace(
+                                dl_match.group(0), dl_match.group(0) + fix_line
+                            )
+                            script_p.write_text(script_content)
+                            auto_fixed = True
+                            _cprint(
+                                f"  [#C08050]Auto-fix[{_fix_round+1}]:[/#C08050]"
+                                " [dim]MultiIndex column fix[/dim]",
+                                console=console, has_rich=has_rich,
+                            )
+
+                attr_match = re.search(
+                    r"AttributeError: '(\w+)' object has no attribute '(\w+)'", combined_err
+                )
+                if attr_match and not auto_fixed:
+                    obj_type, attr_name = attr_match.group(1), attr_match.group(2)
+                    if obj_type == "DataFrame" and attr_name == "append":
+                        script_content = re.sub(
+                            r"(\w+)\.append\(([^)]+)\)",
+                            r"pd.concat([\1, \2], ignore_index=True)",
+                            script_content,
+                        )
+                        script_p.write_text(script_content)
+                        auto_fixed = True
+                        _cprint(
+                            f"  [#C08050]Auto-fix[{_fix_round+1}]:[/#C08050]"
+                            " [dim]DataFrame.append→pd.concat[/dim]",
+                            console=console, has_rich=has_rich,
+                        )
+
+                if not auto_fixed and "TypeError" in combined_err:
+                    if "auto_adjust" in combined_err and "auto_adjust" in script_content:
+                        script_content = re.sub(
+                            r",\s*auto_adjust\s*=\s*(True|False)", "", script_content
+                        )
+                        script_p.write_text(script_content)
+                        auto_fixed = True
+                        _cprint(
+                            f"  [#C08050]Auto-fix[{_fix_round+1}]:[/#C08050]"
+                            " [dim]removed deprecated auto_adjust param[/dim]",
+                            console=console, has_rich=has_rich,
+                        )
+
+                mod_match = re.search(r"No module named ['\"]?(\w+)", combined_err)
+                if mod_match and not auto_fixed:
+                    missing_mod = mod_match.group(1)
+                    pip_map = {
+                        "mplfinance": "mplfinance", "plotly": "plotly",
+                        "pandas_ta": "pandas_ta", "ta": "ta",
+                        "sklearn": "scikit-learn", "cv2": "opencv-python",
+                        "bs4": "beautifulsoup4", "PIL": "Pillow",
+                        "backtrader": "backtrader", "vectorbt": "vectorbt",
+                        "ccxt": "ccxt", "prophet": "prophet",
+                        "arch": "arch", "xgboost": "xgboost",
+                        "lightgbm": "lightgbm", "statsmodels": "statsmodels",
+                        "akshare": "akshare", "tushare": "tushare",
+                        "empyrical": "empyrical", "pyfolio": "pyfolio",
+                        "seaborn": "seaborn", "openpyxl": "openpyxl",
+                    }
+                    pip_pkg = pip_map.get(missing_mod, missing_mod)
+                    _cprint(
+                        f"  [#C08050]Auto-fix[{_fix_round+1}]:[/#C08050]"
+                        f" [dim]pip3 install {pip_pkg}[/dim]",
+                        console=console, has_rich=has_rich,
+                    )
+                    pip_result = subprocess.run(
+                        f"pip3 install {pip_pkg}", shell=True, capture_output=True,
+                        text=True, timeout=60,
+                    )
+                    if pip_result.returncode == 0:
+                        auto_fixed = True
+
+                if auto_fixed:
+                    _cprint(
+                        f"  [dim]Re-running after auto-fix (round {_fix_round+1}/{MAX_AUTO_FIX_ROUNDS})...[/dim]",
+                        console=console, has_rich=has_rich,
+                    )
+                    result = subprocess.run(
+                        command, shell=True, capture_output=True, text=True,
+                        timeout=timeout, cwd=cwd,
+                    )
+                    full_stdout = result.stdout
+                    full_stderr = result.stderr
+                    output = full_stdout[-5000:] if len(full_stdout) > 5000 else full_stdout
+                    stderr = full_stderr[-2000:] if len(full_stderr) > 2000 else full_stderr
+                    output_artifact = _persist_command_output(
+                        command, full_stdout, full_stderr, result.returncode
+                    )
+                    if result.returncode == 0:
+                        break
+                else:
+                    break
+        # ── End auto-fix ─────────────────────────────────────────────────────
+
+        if has_rich and console is not None:
+            if result.returncode == 0:
+                console.print(f"  [green]Command completed[/green] [dim](exit {result.returncode})[/dim]")
+            else:
+                console.print(f"  [dim]Command exited {result.returncode}[/dim]")
+            out_preview = output.strip().splitlines()[:6]
+            for ol in out_preview:
+                console.print(f"    [dim]{ol[:120]}[/dim]")
+            if len(output.strip().splitlines()) > 6:
+                console.print("    [dim]...truncated[/dim]")
+            if output_artifact.get("full_output_path"):
+                console.print("    [dim]full output saved[/dim]")
+            if stderr.strip() and result.returncode != 0:
+                for el in stderr.strip().splitlines()[:3]:
+                    console.print(f"    [red]{el[:120]}[/red]")
+        else:
+            print(f"  Command exit: {result.returncode}")
+        data = {
+            "command": command, "exit_code": result.returncode,
+            "stdout": output, "stderr": stderr,
+            "stdout_truncated": len(full_stdout) > 5000,
+            "stderr_truncated": len(full_stderr) > 2000,
+        }
+        data.update(output_artifact)
+        return {"success": True, "data": data}
+    except subprocess.TimeoutExpired:
+        return {"success": False, "error": f"Command timed out ({timeout}s)"}
+    except KeyboardInterrupt:
+        _cprint("  [dim]Command interrupted[/dim]", console=console, has_rich=has_rich)
+        return {"success": False, "error": "Command interrupted by user (Ctrl+C)"}
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def tool_web_fetch(params: dict) -> dict:
+    """Fetch the text content of any URL."""
+    url = params.get("url", "").strip()
+    if not url:
+        return {"success": False, "error": "Missing 'url' parameter"}
+    if not url.startswith(("http://", "https://")):
+        url = "https://" + url
+    max_chars = min(int(params.get("max_chars", 4000)), 12000)
+    timeout   = min(int(params.get("timeout", 15)), 30)
+    try:
+        import urllib.request as _ur
+        import ssl as _ssl
+        _prx = _ur.getproxies()
+        # SEC EDGAR rejects browser-spoofed UAs from scripts (403) and requires
+        # a declarative UA with contact info — the root cause of "verify via
+        # 10-Q" tasks silently degrading to aggregator sites. Honor SEC's rule
+        # for sec.gov; keep a browser UA for sites that block obvious bots.
+        from urllib.parse import urlparse as _urlparse
+        _host = (_urlparse(url).hostname or "").lower()
+        if _host == "sec.gov" or _host.endswith(".sec.gov"):
+            _contact = os.environ.get("ARIA_SEC_CONTACT", "").strip() or "research@aria-code.local"
+            _ua = f"aria-code research client ({_contact})"
+        else:
+            _ua = (
+                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/124.0 Safari/537.36"
+            )
+        headers = {
+            "User-Agent": _ua,
+            "Accept": "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8",
+        }
+        _gh_m = re.match(
+            r"https://github\.com/([^/]+/[^/]+)/blob/([^?#]+)", url
+        )
+        if _gh_m:
+            url = f"https://raw.githubusercontent.com/{_gh_m.group(1)}/{_gh_m.group(2)}"
+
+        import requests as _req
+        s = _req.Session()
+        s.proxies = _prx
+        # Certificate verification ON by default — research data fetched over
+        # an unverified channel is tamperable. ARIA_WEB_FETCH_INSECURE=1 is
+        # the explicit escape hatch for TLS-intercepting corporate proxies.
+        s.verify = os.environ.get("ARIA_WEB_FETCH_INSECURE", "") != "1"
+        r = s.get(url, headers=headers, timeout=timeout)
+        r.raise_for_status()
+        raw = r.text
+
+        ct = r.headers.get("content-type", "")
+        if "json" in ct or raw.lstrip().startswith(("{", "[")):
+            return {"success": True, "data": {
+                "url": url, "content_type": ct,
+                "text": raw[:max_chars], "length": len(raw),
+            }}
+
+        text = re.sub(r"<script[^>]*>.*?</script>", " ", raw, flags=re.DOTALL | re.I)
+        text = re.sub(r"<style[^>]*>.*?</style>",   " ", text, flags=re.DOTALL | re.I)
+        text = re.sub(r"<[^>]+>",     " ", text)
+        text = re.sub(r"&nbsp;",      " ", text)
+        text = re.sub(r"&amp;",       "&", text)
+        text = re.sub(r"&lt;",        "<", text)
+        text = re.sub(r"&gt;",        ">", text)
+        text = re.sub(r"&quot;",      '"', text)
+        text = re.sub(r"\s{3,}",      "\n", text)
+        text = text.strip()
+
+        return {"success": True, "data": {
+            "url": url, "content_type": ct,
+            "text": text[:max_chars], "length": len(text),
+            "truncated": len(text) > max_chars,
+        }}
+    except Exception as e:
+        return {"success": False, "error": f"web_fetch failed: {e}"}
+
+
+def tool_github(
+    params: dict,
+    *,
+    console=None,
+    has_rich: bool = True,
+) -> dict:
+    """GitHub API / gh CLI integration.
+
+    actions: list_prs, list_issues, view_pr, view_issue, create_pr,
+             list_commits, read_file, search, pr_diff, pr_checks
+    """
+    action = params.get("action", "list_prs").lower().replace("-", "_")
+    cwd    = params.get("cwd") or None
+    policy = "safe"
+
+    def _gh(cmd: str, timeout: int = 20) -> dict:
+        import shutil
+        if not shutil.which("gh"):
+            return {"success": False,
+                    "error": "gh CLI not found. Install: brew install gh && gh auth login"}
+        return tool_run_command(
+            {"command": cmd, "cwd": cwd, "timeout": timeout, "policy": policy},
+            console=console,
+            has_rich=has_rich,
+        )
+
+    if action in ("list_prs", "prs", "pull_requests"):
+        state = params.get("state", "open")
+        limit = int(params.get("limit", 20))
+        return _gh(f"gh pr list --state {state} --limit {limit} "
+                   "--json number,title,author,state,headRefName,url")
+
+    if action in ("list_issues", "issues"):
+        state = params.get("state", "open")
+        limit = int(params.get("limit", 20))
+        label = f' --label "{params["label"]}"' if params.get("label") else ""
+        return _gh(f"gh issue list --state {state} --limit {limit}{label} "
+                   "--json number,title,author,state,labels,url")
+
+    if action in ("view_pr", "pr"):
+        number = params.get("number") or params.get("pr")
+        if not number:
+            return {"success": False, "error": "Missing 'number' parameter"}
+        return _gh(f"gh pr view {number} "
+                   "--json number,title,body,state,headRefName,baseRefName,additions,deletions,files,url")
+
+    if action in ("view_issue", "issue"):
+        number = params.get("number") or params.get("issue")
+        if not number:
+            return {"success": False, "error": "Missing 'number' parameter"}
+        return _gh(f"gh issue view {number} "
+                   "--json number,title,body,state,labels,comments,url")
+
+    if action == "create_pr":
+        title  = params.get("title", "")
+        body   = params.get("body", "")
+        branch = params.get("branch", "")
+        base   = params.get("base", "main")
+        if not title:
+            return {"success": False, "error": "Missing 'title' for create_pr"}
+        b_flag = f"--head {shlex.quote(branch)}" if branch else ""
+        cmd = (
+            f"gh pr create --title {shlex.quote(title)} "
+            f"--body {shlex.quote(body)} "
+            f"--base {shlex.quote(base)} {b_flag}"
+        )
+        return _gh(cmd, timeout=30)
+
+    if action in ("list_commits", "commits", "log"):
+        limit = int(params.get("limit", 10))
+        return _gh(
+            f"gh api repos/{{owner}}/{{repo}}/commits?per_page={limit} "
+            "--jq '[.[] | {sha: .sha[:7], "
+            'message: .commit.message | split("\\n")[0], '
+            "author: .commit.author.name, date: .commit.author.date}]'"
+        )
+
+    if action == "search":
+        q    = params.get("q") or params.get("query", "")
+        kind = params.get("kind", "code")
+        if not q:
+            return {"success": False, "error": "Missing 'q' parameter"}
+        return _gh(f"gh search {kind} {shlex.quote(q)} --limit 10 "
+                   "--json url,path,textMatches", timeout=15)
+
+    if action in ("read_file", "file"):
+        ref       = params.get("ref", "")
+        file_path = params.get("path", "")
+        if ref:
+            m = re.match(r"([^@:]+)@([^:]+):(.+)", ref)
+            if m:
+                repo, branch, fp = m.groups()
+                url = f"https://raw.githubusercontent.com/{repo}/{branch}/{fp}"
+                return tool_web_fetch({"url": url, "max_chars": 20000})
+        if file_path:
+            return _gh(f"gh api repos/{{owner}}/{{repo}}/contents/{file_path} "
+                       "--jq '.content' | base64 -d")
+        return {"success": False, "error": "Provide 'ref' (owner/repo@branch:path) or 'path'"}
+
+    if action in ("pr_diff", "diff"):
+        number = params.get("number") or params.get("pr")
+        if not number:
+            return {"success": False, "error": "Missing 'number' parameter"}
+        return _gh(f"gh pr diff {number}", timeout=30)
+
+    if action in ("pr_checks", "checks", "ci"):
+        number = params.get("number") or params.get("pr")
+        return _gh(f"gh pr checks {number or ''}")
+
+    if action in ("git_status", "status"):
+        return tool_run_command(
+            {"command": "git status --short && echo '---' && git log --oneline -5",
+             "cwd": cwd, "policy": policy},
+            console=console, has_rich=has_rich,
+        )
+
+    if action in ("commit_and_push", "commit", "push"):
+        message   = params.get("message", "")
+        branch    = params.get("branch", "")
+        add_files = params.get("files", [])
+        repo      = params.get("repo", "")    # e.g. "artherahq/aria-code"
+        coauthor  = params.get("coauthor", "")
+
+        if not message:
+            return {"success": False, "error": "Missing 'message' for commit_and_push"}
+
+        # ── Aria Code[bot] identity via GitHub App ─────────────────────────────
+        try:
+            from aria_code.apps.cli.github_app_auth import (
+                get_installation_token, get_aria_git_url,
+                aria_bot_env, ARIA_BOT_NAME, ARIA_BOT_EMAIL,
+            )
+            owner = (repo.split("/")[0] if repo else None) or "artherahq"
+            token = get_installation_token(owner)
+            bot_env = aria_bot_env()
+            auth_available = True
+        except Exception as _auth_err:
+            # Fall back to local git credentials if App not configured
+            token = None
+            bot_env = {
+                "GIT_AUTHOR_NAME":     "Aria Code",
+                "GIT_AUTHOR_EMAIL":    "aria-code[bot]@artherahq.com",
+                "GIT_COMMITTER_NAME":  "Aria Code",
+                "GIT_COMMITTER_EMAIL": "aria-code[bot]@artherahq.com",
+            }
+            auth_available = False
+            ARIA_BOT_NAME  = "Aria Code"
+            ARIA_BOT_EMAIL = "aria-code[bot]@artherahq.com"
+
+        env_prefix = " ".join(f'{k}="{v}"' for k, v in bot_env.items()) + " "
+
+        # ── Build commit message with co-author attribution ────────────────────
+        body = message
+        if coauthor:
+            body += f"\n\nCo-Authored-By: {coauthor}"
+        # Always credit the Aria GitHub account so it appears in Contributors
+        if auth_available:
+            try:
+                from aria_code.apps.cli.github_app_auth import ARIA_GITHUB_LOGIN, ARIA_GITHUB_EMAIL
+                body += f"\n\nCo-Authored-By: {ARIA_GITHUB_LOGIN} <{ARIA_GITHUB_EMAIL}>"
+            except ImportError:
+                pass
+        user_name  = tool_run_command({"command": "git config user.name",  "policy": "safe", "cwd": cwd}).get("output", "").strip()
+        user_email = tool_run_command({"command": "git config user.email", "policy": "safe", "cwd": cwd}).get("output", "").strip()
+        if user_name and user_email and user_email != ARIA_BOT_EMAIL:
+            body += f"\n\nCo-Authored-By: {user_name} <{user_email}>"
+
+        # ── Stage ──────────────────────────────────────────────────────────────
+        stage_cmd = ("git add " + " ".join(shlex.quote(f) for f in add_files)) if add_files else "git add -A"
+        stage_result = tool_run_command(
+            {"command": stage_cmd, "cwd": cwd, "policy": policy},
+            console=console, has_rich=has_rich,
+        )
+        if not stage_result.get("success"):
+            return stage_result
+
+        # ── Commit ─────────────────────────────────────────────────────────────
+        safe_body = body.replace('"', '\\"').replace('$', '\\$')
+        commit_result = tool_run_command(
+            {"command": f'{env_prefix}git commit -m "{safe_body}"',
+             "cwd": cwd, "policy": policy},
+            console=console, has_rich=has_rich,
+        )
+        if not commit_result.get("success"):
+            return commit_result
+
+        # ── Push (use App token remote if available) ───────────────────────────
+        push_branch = branch or tool_run_command(
+            {"command": "git rev-parse --abbrev-ref HEAD", "policy": "safe", "cwd": cwd}
+        ).get("output", "").strip() or "main"
+
+        if auth_available and token and repo:
+            auth_url   = get_aria_git_url(repo, token)
+            push_cmd   = f"git push {shlex.quote(auth_url)} {shlex.quote(push_branch)}"
+        else:
+            push_cmd   = f"git push origin {shlex.quote(push_branch)}"
+
+        push_result = tool_run_command(
+            {"command": push_cmd, "cwd": cwd, "policy": policy, "timeout": 60},
+            console=console, has_rich=has_rich,
+        )
+        return {
+            **push_result,
+            "committed_as": f"{ARIA_BOT_NAME} <{ARIA_BOT_EMAIL}>",
+            "branch": push_branch,
+            "app_auth": auth_available,
+        }
+
+    return {
+        "success": False,
+        "error": (
+            f"Unknown GitHub action: '{action}'. "
+            "Use: list_prs, list_issues, view_pr, view_issue, create_pr, "
+            "list_commits, search, read_file, pr_diff, pr_checks, "
+            "git_status, commit_and_push"
+        ),
+    }
+
+
+def tool_ask_user(params: dict, *, console=None, has_rich: bool = True) -> dict:
+    """Pause execution and ask the user for clarification or a decision."""
+    question = params.get("question", "")
+    if not question:
+        return {"success": False, "error": "Missing 'question' parameter"}
+    
+    if has_rich and console is not None:
+        from rich.prompt import Prompt
+        console.print(f"\n[bold magenta]🤔 Agent needs clarification:[/bold magenta] {question}")
+        try:
+            answer = Prompt.ask("[cyan]Your answer[/cyan]")
+        except (KeyboardInterrupt, EOFError):
+            return {"success": False, "error": "User cancelled the input."}
+    else:
+        print(f"\nAgent needs clarification: {question}")
+        try:
+            answer = input("Your answer: ")
+        except (KeyboardInterrupt, EOFError):
+            return {"success": False, "error": "User cancelled the input."}
+            
+    return {"success": True, "data": {"user_answer": answer}}
+