foxclaw 0.1.0 → 0.1.2

package/python/tests/test_tool_center.py

@@ -0,0 +1,129 @@
+"""工具中心第1期 · 技能台真实化 + 安装审核门 + 治理 端到端验证。
+判定:assert 失败→Traceback→run_all 记失败;正常退出=通过。"""
+import sys, os, tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+def test_tool_center():
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    _DATA = tempfile.mkdtemp(prefix="foxclaw_toolc_")
+    os.environ["FOXCLAW_DATA_DIR"] = _DATA
+
+    from fastapi.testclient import TestClient
+    from foxclaw.api import app
+
+    WEBAPI = {"id": "wx_weather", "name": "天气", "description": "查天气", "kind": "web_api",
+              "triggers": ["天气"], "side_effect": "read",
+              "endpoint": "https://example.com/api/weather", "http_method": "GET"}
+
+    with TestClient(app) as c:
+        print("=" * 60); print("工具中心 · 技能台 + 审核门 + 治理 验证"); print("=" * 60)
+
+        # 1. 安装 web_api 技能(https 只读 → allow)
+        r = c.post("/api/ahs/skills", json=WEBAPI)
+        assert r.status_code == 200, r.text
+        assert r.json()["created"] is True
+        print("[1] 安装 web_api 技能 OK")
+
+        # 2. 列表里出现且 source=user
+        r = c.get("/api/ahs/skills"); assert r.status_code == 200
+        ids = {s["id"]: s for s in r.json()["skills"]}
+        assert "wx_weather" in ids and ids["wx_weather"]["source"] == "user"
+        print("[2] 列表含新技能且 source=user OK")
+
+        # 3. 拒绝 local kind
+        r = c.post("/api/ahs/skills", json={**WEBAPI, "id": "x_local", "kind": "local"})
+        assert r.status_code == 400
+        print("[3] 拒绝 local kind(400) OK")
+
+        # 4. 拒绝非法 endpoint
+        r = c.post("/api/ahs/skills", json={**WEBAPI, "id": "x_bad", "endpoint": "ftp://x"})
+        assert r.status_code == 400
+        print("[4] 拒非法 endpoint(400) OK")
+
+        # 5. mcp 缺字段
+        r = c.post("/api/ahs/skills", json={"id": "x_mcp", "name": "m", "kind": "mcp", "side_effect": "read"})
+        assert r.status_code == 400
+        print("[5] mcp 缺 server/tool(400) OK")
+
+        # 6. 启停
+        r = c.patch("/api/ahs/skills/wx_weather", json={"enabled": False})
+        assert r.status_code == 200 and r.json()["skill"]["enabled"] is False
+        r = c.patch("/api/ahs/skills/wx_weather", json={"enabled": True})
+        assert r.json()["skill"]["enabled"] is True
+        print("[6] 启停切换 OK")
+
+        # 7. 删内置 → 409(取列表里第一个 builtin)
+        r = c.get("/api/ahs/skills")
+        builtin = next((s["id"] for s in r.json()["skills"] if s["source"] == "builtin"), None)
+        if builtin:
+            rd = c.delete(f"/api/ahs/skills/{builtin}")
+            assert rd.status_code == 409, rd.text
+            print("[7] 内置技能不可删(409) OK")
+            # 7b. 用内置 id 安装 → 拒(不能覆盖内置)
+            rc = c.post("/api/ahs/skills", json={**WEBAPI, "id": builtin})
+            assert rc.status_code == 409, rc.text
+            print("[7b] 用内置 id 安装被拒(409) OK")
+        else:
+            print("[7] 跳过(无内置技能)")
+
+        # 8. 测试调用:read 技能直接跑(返回 SkillResult 结构)
+        r = c.post("/api/ahs/skills/wx_weather/test", json={"args": {}})
+        assert r.status_code == 200 and "success" in r.json()
+        print("[8] 测试调用返回 SkillResult OK")
+
+        # 9. 安装审核门:打本地地址的 web_api 安装期被 deny(403)
+        r = c.post("/api/ahs/skills", json={"id": "ssrf_t", "name": "s", "description": "", "kind": "web_api",
+                   "triggers": ["x"], "side_effect": "read", "endpoint": "http://127.0.0.1:8000/api/status"})
+        assert r.status_code == 403, r.text
+        assert r.json()["detail"]["error"] == "install_denied"
+        print("[9] 安装审核门 deny 本地地址(403) OK")
+
+        # 9b. 有副作用技能未确认 → 409 needs_ack;acknowledged 后 → 200(且持久,供步12 round-trip)
+        _send = {"id": "send_x", "name": "发信", "description": "", "kind": "web_api",
+                 "triggers": ["发"], "side_effect": "send", "endpoint": "https://example.com/send"}
+        r = c.post("/api/ahs/skills", json=_send)
+        assert r.status_code == 409 and r.json()["detail"]["needs_ack"] is True, r.text
+        r = c.post("/api/ahs/skills", json={**_send, "acknowledged": True})
+        assert r.status_code == 200, r.text
+        print("[9b] 副作用技能需确认(409→200) OK")
+
+        # 10. 治理端点可用
+        assert c.get("/api/ahs/breaker").status_code == 200
+        assert c.get("/api/ahs/hooks/audit").status_code == 200
+        print("[10] 治理端点(breaker/audit) OK")
+
+        # 10b. 信任分级:内置 calculator(local)=high、内置 mcp=low、用户 web_api=mid
+        sk = {s["id"]: s for s in c.get("/api/ahs/skills").json()["skills"]}
+        assert sk["calculator"]["trust"] == "high", sk["calculator"]["trust"]
+        assert sk["gmail_send"]["trust"] == "low", sk["gmail_send"]["trust"]   # 内置但 mcp→低
+        assert sk["wx_weather"]["trust"] == "mid"
+        print("[10b] 信任分级 high/mid/low OK")
+
+        # 10c. deny 封杀:封杀后测试调用被拦 + blocked 标;解封恢复
+        c.post("/api/ahs/policy/deny", json={"id": "wx_weather"})
+        r = c.post("/api/ahs/skills/wx_weather/test", json={"args": {}, "confirmed": True}).json()
+        assert r["status"] == "blocked" and "封杀" in r["message"], r
+        assert next(s for s in c.get("/api/ahs/skills").json()["skills"] if s["id"] == "wx_weather")["blocked"] is True
+        assert "wx_weather" in c.get("/api/ahs/policy").json()["deny"]
+        assert c.delete("/api/ahs/policy/deny/wx_weather").status_code == 200
+        assert "wx_weather" not in c.get("/api/ahs/policy").json()["deny"]
+        assert next(s for s in c.get("/api/ahs/skills").json()["skills"] if s["id"] == "wx_weather")["blocked"] is False
+        print("[10c] deny 封杀/解封 kill-switch OK")
+
+        # 11. 删除用户技能
+        assert c.delete("/api/ahs/skills/wx_weather").status_code == 200
+        r = c.get("/api/ahs/skills"); assert "wx_weather" not in {s["id"] for s in r.json()["skills"]}
+        print("[11] 删除用户技能 OK")
+
+    # 12. 持久化 round-trip:直建新 OS(同数据目录),已安装的 send_x 应仍在
+    from foxclaw import Foxclaw
+    os2 = Foxclaw(data_dir=_DATA)
+    assert os2.skill_registry.get("send_x") is not None, "重启后用户技能丢失"
+    assert os2.skill_registry.get("send_x").source == "user"
+    print("[12] 重启后用户技能仍在(持久化 round-trip) OK")
+
+    print("\n工具中心第1期验证全部通过")
+
+if __name__ == "__main__":
+    test_tool_center()

package/python/tests/test_tool_parallel.py

@@ -0,0 +1,113 @@
+"""工具调度:只读并发 / 写与未声明串行 / 单工具超时 / 污点回主线程合并。
+
+背景:`agents/mixins/tool_exec.py` 原本逐个 `_dispatch_tool` 串行,一个慢工具阻塞整轮,
+且完全无单工具超时——模型一次发两个只读工具(联网+召回)要等两倍时间,网络卡死则整轮挂住。
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+from foxclaw.agents.mixins import tool_exec as _te
+from foxclaw.agents.mixins.tool_exec import ToolExecMixin
+
+
+class _Fake(ToolExecMixin):
+    """只保留调度层:闸门走真实 registry + permission,执行被 monkeypatch 替换。"""
+
+    def __init__(self):
+        self.calls: list[str] = []
+        self._taint_level = 0
+
+    def _think(self, **kwargs):
+        return None, None
+
+
+def _make(monkeypatch, behavior) -> _Fake:
+    fake = _Fake()
+
+    def _invoke(agent, name, args, taint_sink=None):
+        agent.calls.append(name)
+        return behavior(name, args, taint_sink)
+
+    monkeypatch.setattr(_te, "_invoke_tool", _invoke)
+    return fake
+
+
+def _calls(*pairs):
+    return [{"name": n, "args": a} for n, a in pairs]
+
+
+def test_readonly_tools_run_concurrently(monkeypatch) -> None:
+    barrier = threading.Barrier(2, timeout=3)
+
+    def behave(name, args, sink):
+        barrier.wait()          # 串行时第二个永远到不了 → BrokenBarrierError
+        return f"{name}:ok"
+
+    fake = _make(monkeypatch, behave)
+    t0 = time.monotonic()
+    out = fake._run_tools(_calls(("web_search", {"query": "python 3.14"}),
+                                 ("recall_memory", {"query": "项目约定"})))
+    elapsed = time.monotonic() - t0
+    assert out == ["web_search:ok", "recall_memory:ok"]
+    assert elapsed < 2.0, f"两个只读工具应并发执行,实际耗时 {elapsed:.2f}s"
+
+
+def test_slow_tool_is_cut_off(monkeypatch) -> None:
+    monkeypatch.setenv("FOXCLAW_TOOL_TIMEOUT", "0.3")
+
+    def behave(name, args, sink):
+        time.sleep(2)
+        return "late"
+
+    fake = _make(monkeypatch, behave)
+    t0 = time.monotonic()
+    out = fake._dispatch_tool("web_search", {"query": "x"})
+    assert "超过" in out and "未返回" in out
+    assert "不要编造" in out
+    assert time.monotonic() - t0 < 1.5, "超时后必须立刻返回,不能等工具自己结束"
+
+
+def test_taint_collected_in_worker_and_merged_in_main(monkeypatch) -> None:
+    def behave(name, args, sink):
+        sink.append(3 if name == "web_search" else 2)   # worker 只能收集,不能直接写会话污点
+        return "ok"
+
+    fake = _make(monkeypatch, behave)
+    fake._run_tools(_calls(("web_search", {"query": "x"}),
+                           ("recall_memory", {"query": "y"})))
+    assert fake._taint_level == 3, "并发执行后污点应取最大值合并回会话"
+
+
+def test_single_readonly_call_still_merged(monkeypatch) -> None:
+    def behave(name, args, sink):
+        sink.append(2)
+        return "ok"
+
+    fake = _make(monkeypatch, behave)
+    assert fake._dispatch_tool("recall_memory", {"query": "y"}) == "ok"
+    assert fake._taint_level == 2
+
+
+def test_undeclared_tool_never_executed_and_batch_serialized(monkeypatch) -> None:
+    def behave(name, args, sink):
+        return "ok"
+
+    fake = _make(monkeypatch, behave)
+    out = fake._run_tools(_calls(("web_search", {"query": "x"}),
+                                 ("write_file", {"path": "a.md"})))
+    assert "未知工具 write_file" in out[1]
+    assert fake.calls == ["web_search"], "未声明能力的工具必须被闸门挡住,不进入执行"
+
+
+def test_missing_required_arg_reports_instead_of_executing(monkeypatch) -> None:
+    def behave(name, args, sink):                 # pragma: no cover - 不应被调用
+        raise AssertionError("入参校验失败时不该执行工具")
+
+    fake = _make(monkeypatch, behave)
+    out = fake._run_tools([{"name": "web_search", "args": {}}])
+    assert "入参不合法" in out[0]
+    assert "query" in out[0]
+    assert fake.calls == []

package/python/tests/test_tool_params.py

@@ -0,0 +1,103 @@
+"""M4 · 工具入参校验 + permission Stage 1 真正生效(回归)。
+
+病根(三条断链):
+  1. tools.py 构造了完整 JSON Schema,但**只发给模型**,执行侧从不校验;
+  2. base._dispatch_tool 构造 permission spec 时传 `params={}`(恒空)
+     → permission 管线 Stage 1 的必填校验**永不触发**;
+  3. model_router 解析 tool_calls 参数失败时静默替换为 `{}`
+     → 模型给了非法 JSON 也不报错,它以为工具已执行。
+
+本文件锁定:声明的 schema 在执行侧真正生效,且失败对模型可见。
+"""
+import sys
+import types
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.core.tools import default_registry, tool_capability
+from foxclaw.skills.permission import evaluate
+
+
+def check(cond, msg):
+    if not cond:
+        raise AssertionError(f"✗ {msg}")
+    print(f"  ✓ {msg}")
+
+
+def main():
+    print("=" * 60)
+    print("M4 · 工具入参校验")
+    print("=" * 60)
+    r = default_registry()
+
+    print("\n【1】schema 可从注册表取到(执行侧与模型侧同一份真源)")
+    sch = r.param_schema("web_search")
+    check(bool(sch), "web_search 有 parameters schema")
+    check(sch.get("required") == ["query"], f"required 声明正确({sch.get('required')})")
+    check(bool(r.param_schema("不存在的工具") == {}), "未知工具返回空 schema(不抛异常)")
+
+    print("\n【2】必填参数缺失被检出")
+    errs = r.validate_args("web_search", {})
+    check(any("query" in e for e in errs), f"缺 query 被检出({errs})")
+    errs = r.validate_args("web_search", {"query": ""})
+    check(any("query" in e for e in errs), f"空字符串 query 也算缺失({errs})")
+
+    print("\n【3】类型不符被检出(C 类:静默失败改为可见)")
+    errs = r.validate_args("web_search", {"query": {"a": 1}})
+    check(any("类型" in e for e in errs), f"dict 传 string 位被检出({errs})")
+    # top_k 声明在 recall_memory 上(不在 web_search),故用它验 integer 校验
+    errs = r.validate_args("recall_memory", {"query": "x", "top_k": "ten"})
+    check(any("类型" in e for e in errs), f"字符串传 integer 被检出({errs})")
+    errs = r.validate_args("recall_memory", {"query": "x", "top_k": True})
+    check(not any("top_k" in e for e in errs),
+          f"bool 不被误判为 integer({errs})")  # bool 是 int 子类,须排除
+    # 未在 schema 中声明的额外字段应放过(不引入 jsonschema 依赖的宽松设计)
+    check(r.validate_args("web_search", {"query": "ok", "未声明字段": 1}) == [],
+          "未声明的额外字段不报错(避免过度约束模型)")
+
+    print("\n【4】合法入参通过(不误拦)")
+    check(r.validate_args("web_search", {"query": "今天天气"}) == [],
+          "合法 query 无错误")
+    check(r.validate_args("recall_memory", {"query": "x", "top_k": 8}) == [],
+          "合法 top_k 无错误")
+
+    print("\n【5】permission Stage 1 真正生效(此前 params={} 恒不触发)")
+    for tool, args, want in [("web_search", {}, "ask"),
+                             ("recall_memory", {"query": "x"}, "allow")]:
+        sch_t = r.param_schema(tool)
+        req = set(sch_t.get("required") or [])
+        params = {k: {"required": k in req, "type": v.get("type")}
+                  for k, v in (sch_t.get("properties") or {}).items()
+                  if isinstance(v, dict)}
+        spec = types.SimpleNamespace(id=f"tool:{tool}", params=params,
+                                     **tool_capability(tool))
+        d = evaluate(spec, args, confirmed=False)
+        check(d.decision == want,
+              f"{tool} args={args} → {d.decision}(期望 {want})")
+        if args == {}:
+            check("缺少必填参数" in d.reason,
+                  f"Stage 1 检出缺参:{d.reason}")
+
+    print("\n【6】参数解析失败不再静默(args_parse_failed 标记存在)")
+    import inspect
+    from foxclaw.core.model_router import ModelRouter
+    # 检查整个类:标记可能随重构从 call_tools 移到 _call_openai_tools 等子方法,
+    # 锁「类内存在该标记」而非锁某个方法名(避免重构后误报)。
+    src = inspect.getsource(ModelRouter)
+    check("args_parse_failed" in src,
+          "call_tools 标记解析失败(可观测)")
+    check("llm.tool_args_unparsable" in src,
+          "解析失败进 tracing(可归因)")
+
+    print("\n" + "=" * 60)
+    print("M4 全部通过")
+    print("=" * 60)
+
+
+def test_tool_params():
+    main()
+
+
+if __name__ == "__main__":
+    main()

package/python/tests/test_tool_use.py

@@ -0,0 +1,242 @@
+"""
+P2 function-calling(工具化)守卫测试 —— 全离线,不打真实 LLM/网络。
+
+覆盖:
+  1. P1 运行时事实基准注入(_runtime_context / _inject_runtime 幂等)。
+  2. ToolRegistry:默认工具集、deny 过滤、tool_use 开关读 env。
+  3. ModelRouter.call_tools:不支持 tools 的 provider → supported=False(降级)。
+  4. _reply_with_tools:多轮工具循环(调用→回灌→最终答);不支持 → None(fallback)。
+  5. _dispatch_tool:web_search 命中 / 个人数据否决 / recall_memory / deny 闸。
+"""
+import os, sys, types
+from pathlib import Path
+os.environ.setdefault("HF_HUB_OFFLINE", "1")
+os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+os.environ["FOXCLAW_EMBEDDING_MODEL"] = "foxclaw-nonexistent-fast"
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.core import tools as T
+from foxclaw.core.model_router import ModelRouter
+from foxclaw.agents.base import CognitiveAgent
+
+
+# ── 1. P1 运行时注入 ───────────────────────────────────────────────────────────
+def test_runtime_context_and_idempotent():
+    r = ModelRouter(provider="stub")
+    ctx = r._runtime_context()
+    assert "运行时信息" in ctx and "模型" in ctx and "当前日期时间" in ctx
+    a = r._inject_runtime("你是助手。")
+    assert a.startswith("【运行时信息")
+    assert r._inject_runtime(a) == a, "二次注入必须幂等(防 stream→complete 重复)"
+
+
+# ── 2. ToolRegistry ────────────────────────────────────────────────────────────
+def test_registry_default_and_deny():
+    reg = T.default_registry()
+    assert set(reg.names()) == {"web_search", "recall_memory"}
+    names = [s["function"]["name"] for s in reg.schemas()]
+    assert "web_search" in names and "recall_memory" in names
+    os.environ["FOXCLAW_TOOL_DENY"] = "web_search"
+    try:
+        names2 = [s["function"]["name"] for s in reg.schemas()]
+        assert "web_search" not in names2 and "recall_memory" in names2
+        assert T.is_tool_denied("web_search")
+    finally:
+        os.environ.pop("FOXCLAW_TOOL_DENY", None)
+
+
+def test_tool_use_flag_default_off():
+    os.environ.pop("FOXCLAW_TOOL_USE", None)
+    assert T.tool_use_enabled() is False, "默认必须关(behavior-preserving)"
+    os.environ["FOXCLAW_TOOL_USE"] = "1"
+    try:
+        assert T.tool_use_enabled() is True
+    finally:
+        os.environ.pop("FOXCLAW_TOOL_USE", None)
+
+
+# ── 3. call_tools 降级 ─────────────────────────────────────────────────────────
+def test_call_tools_unsupported_degrades():
+    r = ModelRouter(provider="stub")
+    assert r.supports_tools() is False
+    res = r.call_tools("sys", [{"role": "user", "content": "hi"}], [])
+    assert res["supported"] is False and res["tool_calls"] == []
+
+
+# ── 4. 工具循环 ────────────────────────────────────────────────────────────────
+class _FakeRouter:
+    """脚本化 call_tools:按序返回预设结果,记录每轮 messages 长度。"""
+    def __init__(self, script):
+        self.script = list(script)
+        self.seen = []
+
+    def supports_tools(self):
+        return True
+
+    def call_tools(self, system, messages, schemas, tool_choice="auto", agent_id=""):
+        self.seen.append((tool_choice, list(messages)))
+        return self.script.pop(0)
+
+    @staticmethod
+    def format_tool_result(tc, result):
+        return {"role": "tool", "tool_call_id": tc.get("id", ""), "content": str(result)}
+
+
+def _fake_agent(router):
+    a = types.SimpleNamespace()
+    a.router = router
+    a.system_prompt = "sys"
+    a.AGENT_ID = "assistant"
+    a._dispatch_tool = lambda name, args: f"RESULT[{name}:{args.get('query','')}]"
+    return a
+
+
+def test_reply_with_tools_multi_round():
+    router = _FakeRouter([
+        # 第1轮:模型要求调 web_search
+        {"supported": True, "text": "", "assistant_msg": {"role": "assistant", "content": ""},
+         "tool_calls": [{"id": "c1", "name": "web_search", "args": {"query": "最新模型"}}]},
+        # 第2轮:拿到结果后给最终答案
+        {"supported": True, "text": "根据搜索,最新是 X。", "tool_calls": [],
+         "assistant_msg": {"role": "assistant", "content": "根据搜索,最新是 X。"}},
+    ])
+    agent = _fake_agent(router)
+    out = CognitiveAgent._reply_with_tools(agent, "有哪些新模型",
+                                           [{"role": "user", "content": "有哪些新模型"}])
+    assert out == "根据搜索,最新是 X。"
+    # 第2轮的 messages 必须已追加 assistant(带 tool_calls)+ tool 结果
+    _, round2_msgs = router.seen[1]
+    roles = [m["role"] for m in round2_msgs]
+    assert "assistant" in roles and "tool" in roles
+    assert any("RESULT[web_search" in str(m.get("content", "")) for m in round2_msgs)
+
+
+def test_reply_with_tools_direct_answer_no_tool():
+    router = _FakeRouter([
+        {"supported": True, "text": "你好呀!", "tool_calls": [],
+         "assistant_msg": {"role": "assistant", "content": "你好呀!"}},
+    ])
+    agent = _fake_agent(router)
+    out = CognitiveAgent._reply_with_tools(agent, "你好", [{"role": "user", "content": "你好"}])
+    assert out == "你好呀!" and len(router.seen) == 1
+
+
+def test_reply_with_tools_unsupported_returns_none():
+    agent = types.SimpleNamespace(router=types.SimpleNamespace(supports_tools=lambda: False),
+                                  system_prompt="s", AGENT_ID="a")
+    out = CognitiveAgent._reply_with_tools(agent, "t", [{"role": "user", "content": "t"}])
+    assert out is None, "不支持 tools 必须返回 None 让上层 fallback"
+
+
+def test_reply_with_tools_empty_answer_returns_none():
+    # 阶段五·步骤15:模型无工具调用且文本为空 → 返回 None 让上层 fallback(不再"空回复且不回退")
+    router = _FakeRouter([
+        {"supported": True, "text": "", "tool_calls": [],
+         "assistant_msg": {"role": "assistant", "content": ""}},
+    ])
+    agent = _fake_agent(router)
+    out = CognitiveAgent._reply_with_tools(agent, "你好", [{"role": "user", "content": "你好"}])
+    assert out is None, "空答必须返回 None 让上层 fallback"
+
+
+# ── 5. 工具分派 ────────────────────────────────────────────────────────────────
+def test_dispatch_web_search_ok(monkeypatch):
+    from foxclaw.core import web_search as ws
+    monkeypatch.setattr(ws, "search_answer", lambda q: {"answer": "实时答案XYZ", "references": []})
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "web_search", {"query": "OpenAI 新模型"})
+    assert "实时答案XYZ" in out
+
+
+def test_dispatch_web_search_personal_veto():
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "web_search", {"query": "我本月支出多少"})
+    assert "本地" in out, "私人财务问题不得外发联网"
+
+
+def test_dispatch_recall_memory():
+    agent = types.SimpleNamespace(
+        _recall_memory=lambda q, top_k=5: [{"content": "用户喜欢灰色"}])
+    out = CognitiveAgent._dispatch_tool(agent, "recall_memory", {"query": "颜色偏好"})
+    assert "灰色" in out
+
+
+def test_dispatch_denied(monkeypatch):
+    monkeypatch.setenv("FOXCLAW_TOOL_DENY", "web_search")
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "web_search", {"query": "x"})
+    assert "禁用" in out
+
+
+# ── 6. 动作级权限闸(permission 管线 + HITL)──────────────────────────────────────
+def test_tool_capability_readonly_and_failclosed():
+    assert T.tool_capability("web_search")["read_only"] is True
+    assert T.tool_capability("recall_memory")["side_effect"] == "read"
+    # 未声明的新工具 → fail-closed:当有副作用 + 外部
+    cap = T.tool_capability("some_future_write_tool")
+    assert cap["read_only"] is False and cap["side_effect"] == "write" and cap["external"] is True
+
+
+def test_permission_gate_allows_readonly_asks_sideeffect():
+    import types as _t
+    from foxclaw.skills import permission as perm
+    ro = _t.SimpleNamespace(id="tool:web_search", params={}, **T.tool_capability("web_search"))
+    assert perm.evaluate(ro, {}, confirmed=False).decision == "allow"
+    send = _t.SimpleNamespace(id="tool:send_email", params={},
+                              side_effect="send", read_only=False, external=True, destructive=False)
+    d = perm.evaluate(send, {}, confirmed=False)
+    assert d.decision == "ask" and d.requires_confirmation
+
+
+def test_dispatch_hitl_blocks_side_effect_tool(monkeypatch):
+    """核心:若工具被判为有副作用(写/发送),_dispatch_tool 走 HITL——不执行、返回需确认。"""
+    from foxclaw.core import web_search as ws
+    called = {"n": 0}
+    monkeypatch.setattr(ws, "search_answer",
+                        lambda q: called.__setitem__("n", called["n"] + 1) or {"answer": "x"})
+    # 把 web_search 强制降级为有副作用 → 应被闸门拦成 HITL
+    monkeypatch.setattr(T, "tool_capability",
+                        lambda name: {"side_effect": "send", "read_only": False,
+                                      "external": True, "destructive": False})
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "web_search", {"query": "x"})
+    assert "确认" in out and called["n"] == 0, "有副作用工具必须 HITL、不自动执行"
+
+
+def test_dispatch_unknown_tool():
+    agent = types.SimpleNamespace(_think=lambda **k: None)
+    out = CognitiveAgent._dispatch_tool(agent, "nonexistent_tool", {"x": 1})
+    assert "未知工具" in out
+
+
+def test_tool_path_injects_preferences(monkeypatch):
+    """回归(Finding 1):工具路径也要注入用户偏好,不能开工具化就丢掉"越用越懂你"。"""
+    monkeypatch.setenv("FOXCLAW_TOOL_USE", "1")
+    captured = {}
+    fake = types.SimpleNamespace()
+    fake._sanitize_history = lambda h, max_turns=12: []
+    fake.router = types.SimpleNamespace(supports_tools=lambda: True)
+    fake.AGENT_ID = "assistant"
+    fake._ability_augment = lambda t, m: m
+    fake._skill_augment = lambda t, m: m
+    # 偏好注入:把标记并进最后一条 user
+    fake._pref_augment = lambda m: (list(m[:-1]) +
+        [{"role": "user", "content": "【用户偏好】喜欢简洁\n\n" + m[-1]["content"]}])
+
+    def _rwt(task, messages, stop_event=None):
+        captured["msgs"] = messages
+        return "好的,已处理。"
+    fake._reply_with_tools = _rwt
+    fake._think = lambda **k: None
+    fake._store_memory = lambda *a, **k: None
+    fake._maybe_store_preference = lambda t: None
+
+    out = "".join(CognitiveAgent.stream_reply(fake, "帮我总结这段"))
+    assert "已处理" in out
+    assert any("喜欢简洁" in str(x.get("content", "")) for x in captured["msgs"]), \
+        "工具路径必须注入用户偏好(Finding 1)"
+
+
+if __name__ == "__main__":
+    import pytest
+    pytest.main([__file__, "-v"])