-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
@@ -622,4 +622,3 @@ WeChat :
-
diff --git a/README.id.md b/README.id.md
index d3c556dde..5aa7b58f5 100644
--- a/README.id.md
+++ b/README.id.md
@@ -18,7 +18,7 @@
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Malay](README.my.md) | [English](README.md) | **Bahasa Indonesia**
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | **Bahasa Indonesia** | [Malay](README.my.md) | [English](README.md)
@@ -615,4 +615,3 @@ Discord: 
-
diff --git a/README.it.md b/README.it.md
index 6fe6c5e17..57dd014b3 100644
--- a/README.it.md
+++ b/README.it.md
@@ -18,7 +18,7 @@
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **Italiano** | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **Italiano** | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
diff --git a/README.ja.md b/README.ja.md
index 793c41fcb..64bff9ee9 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -18,7 +18,7 @@
-[中文](README.zh.md) | **日本語** | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | **日本語** | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
diff --git a/README.ko.md b/README.ko.md
new file mode 100644
index 000000000..341c09812
--- /dev/null
+++ b/README.ko.md
@@ -0,0 +1,626 @@
+
+
+
+ 
+ 
+ -SipeedIO-black?style=flat&logo=x&logoColor=white){kind=icon}
|
+
+ |
+
+
+ |
+
+
+
+
+
풀스택 엔지니어 모드 |
+로깅 및 계획 |
+웹 검색 및 학습 |
+
|---|---|---|
|
+
|
+
|
+
| 개발 · 배포 · 확장 | +스케줄링 · 자동화 · 기억 | +탐색 · 인사이트 · 트렌드 | +
+
+
+
+
+
+
+
+
 |
+  |
+  |
+  |
+
+
+런처 UI 없이 `picoclaw` 코어 바이너리만 있는 최소 환경에서는 명령줄과 JSON 설정 파일만으로도 모든 설정을 마칠 수 있습니다.
+
+**1. 초기화**
+
+```bash
+picoclaw onboard
+```
+
+그러면 `~/.picoclaw/config.json`과 워크스페이스 디렉터리가 생성됩니다.
+
+**2. 설정** (`~/.picoclaw/config.json`)
+
+```jsonc
+{
+ "agents": {
+ "defaults": {
+ "model_name": "gpt-5.4"
+ }
+ },
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ // api_key는 이제 .security.yml에서 로드됩니다.
+ }
+ ]
+}
+```
+
+> 사용 가능한 모든 옵션이 포함된 전체 설정 템플릿은 저장소의 `config/config.example.json`을 참고하세요.
+>
+> 참고: `config.example.json` 형식은 버전 0이며 민감 정보가 포함되어 있습니다. 실행 시 자동으로 버전 1+로 마이그레이션되며, 이후 `config.json`에는 비민감 정보만 저장되고 민감 정보는 `.security.yml`에 저장됩니다. 민감 정보를 직접 수정해야 한다면 `docs/security_configuration.md`를 참고하세요.
+
+**3. 채팅**
+
+```bash
+# 단발성 질문
+picoclaw agent -m "2+2는 얼마야?"
+
+# 대화형 모드
+picoclaw agent
+
+# 채팅 앱 연동용 게이트웨이 시작
+picoclaw gateway
+```
+
+
에이전트 소셜 네트워크 참여하기
+
+CLI 또는 통합된 채팅 앱에서 메시지를 한 번만 보내면 PicoClaw를 에이전트 소셜 네트워크에 연결할 수 있습니다.
+
+**`https://clawdchat.ai/skill.md`를 읽고 안내에 따라 [ClawdChat.ai](https://clawdchat.ai)에 참여하세요**
+
+## 🖥️ CLI 레퍼런스
+
+| 명령어 | 설명 |
+| ------------------------- | ------------------------------ |
+| `picoclaw onboard` | 설정 및 워크스페이스 초기화 |
+| `picoclaw auth weixin` | QR로 WeChat 계정 연결 |
+| `picoclaw agent -m "..."` | 에이전트와 채팅 |
+| `picoclaw agent` | 대화형 채팅 모드 |
+| `picoclaw gateway` | 게이트웨이 시작 |
+| `picoclaw status` | 상태 표시 |
+| `picoclaw version` | 버전 정보 표시 |
+| `picoclaw model` | 기본 모델 조회 또는 변경 |
+| `picoclaw cron list` | 모든 예약 작업 목록 표시 |
+| `picoclaw cron add ...` | 예약 작업 추가 |
+| `picoclaw cron disable` | 예약 작업 비활성화 |
+| `picoclaw cron remove` | 예약 작업 삭제 |
+| `picoclaw skills list` | 설치된 스킬 목록 표시 |
+| `picoclaw skills install` | 스킬 설치 |
+| `picoclaw migrate` | 이전 버전 데이터 마이그레이션 |
+| `picoclaw auth login` | 프로바이더 인증 |
+
+### ⏰ 예약 작업 / 리마인더
+
+PicoClaw는 `cron` 도구를 통해 예약 리마인더와 반복 작업을 지원합니다.
+
+* **1회성 리마인더**: "10분 후에 알려줘" -> 10분 후 한 번 실행
+* **반복 작업**: "2시간마다 알려줘" -> 2시간마다 실행
+* **Cron 표현식**: "매일 오전 9시에 알려줘" -> cron 표현식 사용
+
+현재 지원하는 스케줄 유형, 실행 모드, 명령 작업 게이트, 저장 방식은 [docs/cron.md](docs/cron.md)를 참고하세요.
+
+## 📚 문서
+
+이 README보다 더 자세한 가이드는 다음 문서를 참고하세요.
+
+| 주제 | 설명 |
+|------|------|
+| [도커 & 빠른 시작](docs/docker.md) | Docker Compose 설정, 런처/에이전트 모드 |
+| [채팅 앱](docs/chat-apps.md) | 17개 이상의 채널 설정 가이드 |
+| [설정](docs/configuration.md) | 환경 변수, 워크스페이스 레이아웃, 보안 샌드박스 |
+| [예약 작업과 Cron](docs/cron.md) | Cron 스케줄 유형, 전달 모드, 명령 게이트, 작업 저장 |
+| [프로바이더와 모델](docs/providers.md) | 30개 이상의 LLM 프로바이더, 모델 라우팅, model_list 설정 |
+| [Spawn & 비동기 작업](docs/spawn-tasks.md) | 빠른 작업, spawn을 이용한 장기 작업, 비동기 서브에이전트 오케스트레이션 |
+| [Hooks](docs/hooks/README.md) | 이벤트 기반 Hook 시스템: 관찰자, 인터셉터, 승인 훅 |
+| [Steering](docs/steering.md) | 실행 중인 에이전트 루프에서 도구 호출 사이에 메시지 주입 |
+| [SubTurn](docs/subturn.md) | 서브에이전트 조정, 동시성 제어, 생명주기 |
+| [문제 해결](docs/troubleshooting.md) | 자주 발생하는 문제와 해결 방법 |
+| [도구 설정](docs/tools_configuration.md) | 도구별 활성화/비활성화, exec 정책, MCP, 스킬 |
+| [하드웨어 호환성](docs/hardware-compatibility.md) | 테스트된 보드, 최소 요구사항 |
+
+## 🤝 기여 & 로드맵
+
+PR은 언제든 환영합니다! 코드베이스는 의도적으로 작고 읽기 쉽게 유지하고 있습니다.
+
+가이드라인은 [커뮤니티 로드맵](https://github.com/sipeed/picoclaw/issues/988)과 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.
+
+개발자 그룹도 준비 중입니다. 첫 PR이 머지되면 함께할 수 있습니다!
+
+커뮤니티 그룹:
+
+Discord:
diff --git a/README.md b/README.md
index a48a53d47..eb0d389d2 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | **English**
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | **English**
diff --git a/README.my.md b/README.my.md
index f00fb438c..f8e602f83 100644
--- a/README.my.md
+++ b/README.my.md
@@ -18,7 +18,7 @@
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | **Malay** | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | **Malay** | [English](README.md)
diff --git a/README.pt-br.md b/README.pt-br.md
index db11d4d82..65d23d1d1 100644
--- a/README.pt-br.md
+++ b/README.pt-br.md
@@ -18,7 +18,7 @@
-[中文](README.zh.md) | [日本語](README.ja.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
diff --git a/README.vi.md b/README.vi.md
index 78b8a9a59..1d70d0615 100644
--- a/README.vi.md
+++ b/README.vi.md
@@ -18,7 +18,7 @@
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
diff --git a/README.zh.md b/README.zh.md
index 2ba0913fc..e61ff7e28 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -18,7 +18,7 @@
-**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+**中文** | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
@@ -620,4 +620,3 @@ WeChat:
-
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 480244127..f36a98ff6 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -26,18 +26,9 @@ RUN apk add --no-cache ca-certificates tzdata curl
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD wget -q --spider http://localhost:18790/health || exit 1
-# Copy binary
+# Copy binary and first-run entrypoint (same as release image).
COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw
+COPY docker/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
-# Create non-root user and group
-RUN addgroup -g 1000 picoclaw && \
- adduser -D -u 1000 -G picoclaw picoclaw
-
-# Switch to non-root user
-USER picoclaw
-
-# Run onboard to create initial directories and config
-RUN /usr/local/bin/picoclaw onboard
-
-ENTRYPOINT ["picoclaw"]
-CMD ["gateway"]
+ENTRYPOINT ["/entrypoint.sh"]
diff --git a/docker/Dockerfile.heavy b/docker/Dockerfile.heavy
index cbc243e39..2a9fc742d 100644
--- a/docker/Dockerfile.heavy
+++ b/docker/Dockerfile.heavy
@@ -48,20 +48,13 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
# Copy binary
COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw
-# Reuse existing node user (UID/GID 1000) — rename to picoclaw
-RUN deluser node 2>/dev/null; delgroup node 2>/dev/null; \
- addgroup -g 1000 picoclaw 2>/dev/null; \
- adduser -D -u 1000 -G picoclaw -h /home/picoclaw picoclaw 2>/dev/null || true
-
-USER picoclaw
-
# Run onboard to create initial directories and config
RUN /usr/local/bin/picoclaw onboard
# Copy default workspace
-COPY --chown=picoclaw:picoclaw workspace/ /home/picoclaw/.picoclaw/workspace/
+COPY workspace/ /root/.picoclaw/workspace/
-VOLUME /home/picoclaw/.picoclaw/workspace
+VOLUME /root/.picoclaw/workspace
ENTRYPOINT ["picoclaw"]
CMD ["gateway"]
diff --git a/docs/hooks/README.md b/docs/hooks/README.md
index ec3bbc46a..5be0f30b5 100644
--- a/docs/hooks/README.md
+++ b/docs/hooks/README.md
@@ -28,6 +28,69 @@ The currently exposed synchronous hook points are:
Everything else is exposed as read-only events.
+## Hook Actions
+
+Hooks can return different actions to control the flow:
+
+| Action | Applicable Stages | Effect |
+| --- | --- | --- |
+| `continue` | All interceptors | Pass through without modification |
+| `modify` | `before_llm`, `after_llm`, `before_tool`, `after_tool` | Modify request/response and continue |
+| `respond` | `before_tool` | Return a tool result directly, skip actual tool execution |
+| `deny_tool` | `before_tool` | Deny tool execution, return error message |
+| `abort_turn` | All interceptors | Abort the current turn |
+| `hard_abort` | All interceptors | Force stop the entire agent loop |
+
+### The `respond` Action
+
+The `respond` action is special: it allows a `before_tool` hook to provide the tool result directly, skipping the actual tool execution. This is useful for:
+
+1. **Plugin tool injection**: External hooks can implement tools without registering them in the tool registry
+2. **Tool result caching**: Return cached results for repeated tool calls
+3. **Tool mocking**: Return mock results for testing purposes
+
+When a hook returns `respond` with a `HookResult`, the agent loop:
+1. Skips the actual tool execution
+2. Uses the provided result as if the tool had executed
+3. Continues the turn normally with the result
+
+Example (Go in-process hook):
+
+```go
+func (h *MyHook) BeforeTool(
+ ctx context.Context,
+ call *agent.ToolCallHookRequest,
+) (*agent.ToolCallHookRequest, agent.HookDecision, error) {
+ if call.Tool == "my_plugin_tool" {
+ next := call.Clone()
+ next.HookResult = &tools.ToolResult{
+ ForLLM: "Plugin tool executed successfully",
+ Silent: false,
+ IsError: false,
+ }
+ return next, agent.HookDecision{Action: agent.HookActionRespond}, nil
+ }
+ return call, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+```
+
+Example (Python process hook):
+
+```python
+def handle_before_tool(params: dict) -> dict:
+ tool = params.get("tool", "")
+ if tool == "my_plugin_tool":
+ return {
+ "action": "respond",
+ "result": {
+ "for_llm": "Plugin tool executed successfully",
+ "silent": False,
+ "is_error": False
+ }
+ }
+ return {"action": "continue"}
+```
+
## Execution Order
`HookManager` sorts hooks like this:
diff --git a/docs/hooks/README.zh.md b/docs/hooks/README.zh.md
index 46c7c9392..2170d45c8 100644
--- a/docs/hooks/README.zh.md
+++ b/docs/hooks/README.zh.md
@@ -28,6 +28,69 @@
其余 lifecycle 通过事件形式只读暴露。
+## Hook Actions
+
+Hook 可以返回不同的 action 来控制流程：
+
+| Action | 适用阶段 | 效果 |
+| --- | --- | --- |
+| `continue` | 所有拦截型 | 放行，不做修改 |
+| `modify` | `before_llm`, `after_llm`, `before_tool`, `after_tool` | 改写请求/响应后放行 |
+| `respond` | `before_tool` | 直接返回工具结果，跳过实际工具执行 |
+| `deny_tool` | `before_tool` | 拒绝工具执行，返回错误信息 |
+| `abort_turn` | 所有拦截型 | 中止当前 turn |
+| `hard_abort` | 所有拦截型 | 强制终止整个 agent loop |
+
+### `respond` Action
+
+`respond` action 是特殊的：它允许 `before_tool` hook 直接提供工具结果，跳过实际工具执行。适用于：
+
+1. **插件工具注入**：外部 hook 可以实现工具，无需在 ToolRegistry 注册
+2. **工具结果缓存**：对重复调用返回缓存结果
+3. **工具模拟**：测试时返回模拟结果
+
+当 hook 返回 `respond` 并携带 `HookResult` 时，agent loop 会：
+1. 跳过实际工具执行
+2. 使用提供的结果作为工具执行结果
+3. 正常继续 turn 流程
+
+示例（Go 进程内 hook）：
+
+```go
+func (h *MyHook) BeforeTool(
+ ctx context.Context,
+ call *agent.ToolCallHookRequest,
+) (*agent.ToolCallHookRequest, agent.HookDecision, error) {
+ if call.Tool == "my_plugin_tool" {
+ next := call.Clone()
+ next.HookResult = &tools.ToolResult{
+ ForLLM: "Plugin tool executed successfully",
+ Silent: false,
+ IsError: false,
+ }
+ return next, agent.HookDecision{Action: agent.HookActionRespond}, nil
+ }
+ return call, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+```
+
+示例（Python process hook）：
+
+```python
+def handle_before_tool(params: dict) -> dict:
+ tool = params.get("tool", "")
+ if tool == "my_plugin_tool":
+ return {
+ "action": "respond",
+ "result": {
+ "for_llm": "Plugin tool executed successfully",
+ "silent": False,
+ "is_error": False
+ }
+ }
+ return {"action": "continue"}
+```
+
## 执行顺序
HookManager 的排序规则是：
diff --git a/docs/hooks/hook-json-protocol.md b/docs/hooks/hook-json-protocol.md
new file mode 100644
index 000000000..58b6e323b
--- /dev/null
+++ b/docs/hooks/hook-json-protocol.md
@@ -0,0 +1,568 @@
+# Hook JSON-RPC Protocol Details
+
+All hooks use `JSON-RPC 2.0` format, with one JSON message per line, transmitted via stdio.
+
+---
+
+## Basic Protocol Structure
+
+### Request (PicoClaw → Hook)
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"hook.xxx","params":{...}}
+```
+
+### Response (Hook → PicoClaw)
+
+Success:
+```json
+{"jsonrpc":"2.0","id":1,"result":{...}}
+```
+
+Error:
+```json
+{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"error message"}}
+```
+
+---
+
+## 1. `hook.hello` (Handshake)
+
+Handshake must be completed at startup, otherwise the hook process will be terminated.
+
+### Request
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "hook.hello",
+ "params": {
+ "name": "py_review_gate",
+ "version": 1,
+ "modes": ["observe", "tool", "approve"]
+ }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `name` | hook name (from configuration) |
+| `version` | protocol version, currently `1` |
+| `modes` | capability modes supported by the hook |
+
+### Response
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "ok": true,
+ "name": "python-review-gate"
+ }
+}
+```
+
+---
+
+## 2. `hook.before_llm`
+
+Triggered before sending request to LLM. Can be used to inject tools.
+
+### Request
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 2,
+ "method": "hook.before_llm",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "ParentTurnID": "",
+ "SessionKey": "session-1",
+ "Iteration": 0,
+ "TracePath": "runTurn",
+ "Source": "turn.llm.request"
+ },
+ "model": "claude-sonnet",
+ "messages": [
+ {"role": "user", "content": "hello"}
+ ],
+ "tools": [
+ {
+ "type": "function",
+ "function": {
+ "name": "echo",
+ "description": "echo text",
+ "parameters": {"type": "object"}
+ }
+ }
+ ],
+ "options": {
+ "temperature": 0.7
+ },
+ "channel": "cli",
+ "chat_id": "chat-1",
+ "graceful_terminal": false
+ }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `meta` | event metadata for tracing |
+| `model` | requested model name |
+| `messages` | conversation history |
+| `tools` | list of available tool definitions |
+| `options` | LLM parameters (temperature, max_tokens, etc.) |
+| `channel` | request source channel |
+| `chat_id` | session ID |
+
+### Response (Tool Injection Example)
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 2,
+ "result": {
+ "action": "modify",
+ "request": {
+ "model": "claude-sonnet",
+ "messages": [{"role": "user", "content": "hello"}],
+ "tools": [
+ {
+ "type": "function",
+ "function": {
+ "name": "echo",
+ "description": "echo",
+ "parameters": {}
+ }
+ },
+ {
+ "type": "function",
+ "function": {
+ "name": "my_plugin_tool",
+ "description": "Plugin injected tool",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "query": {"type": "string"}
+ }
+ }
+ }
+ }
+ ]
+ }
+ }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `action` | decision action (see table below) |
+| `request` | modified request object |
+
+---
+
+## 3. `hook.after_llm`
+
+Triggered after receiving LLM response. Can modify response content.
+
+### Request
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 3,
+ "method": "hook.after_llm",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "SessionKey": "session-1"
+ },
+ "model": "claude-sonnet",
+ "response": {
+ "role": "assistant",
+ "content": "Hi!",
+ "tool_calls": [
+ {
+ "id": "tc-1",
+ "type": "function",
+ "function": {
+ "name": "echo",
+ "arguments": "{\"text\":\"hi\"}"
+ }
+ }
+ ]
+ },
+ "channel": "cli",
+ "chat_id": "chat-1"
+ }
+}
+```
+
+### Response
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 3,
+ "result": {
+ "action": "continue"
+ }
+}
+```
+
+---
+
+## 4. `hook.before_tool`
+
+Triggered before tool execution. Can modify tool name and arguments, deny execution, or return result directly.
+
+### Request
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 4,
+ "method": "hook.before_tool",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "SessionKey": "session-1"
+ },
+ "tool": "echo_text",
+ "arguments": {
+ "text": "hello"
+ },
+ "channel": "cli",
+ "chat_id": "chat-1"
+ }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `tool` | tool name |
+| `arguments` | tool arguments |
+
+### Response (Modify Arguments)
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 4,
+ "result": {
+ "action": "modify",
+ "call": {
+ "tool": "echo_text",
+ "arguments": {
+ "text": "modified hello"
+ }
+ }
+ }
+}
+```
+
+### Response (Deny Execution)
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 4,
+ "result": {
+ "action": "deny_tool",
+ "reason": "Invalid arguments"
+ }
+}
+```
+
+### Response (Return Result Directly - respond)
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 4,
+ "result": {
+ "action": "respond",
+ "call": {
+ "tool": "my_plugin_tool",
+ "arguments": {
+ "query": "hello"
+ }
+ },
+ "result": {
+ "for_llm": "Plugin tool executed successfully",
+ "for_user": "",
+ "silent": false,
+ "is_error": false
+ }
+ }
+}
+```
+
+The `respond` action allows hooks to return tool results directly, skipping actual tool execution. Use cases:
+1. **Plugin tool injection**: External hooks can implement tools without registering in ToolRegistry
+2. **Tool result caching**: Return cached results for repeated calls
+3. **Tool mocking**: Return mock results during testing
+
+| Field | Description |
+|-------|-------------|
+| `action` | must be `respond` |
+| `call` | modified call information (optional) |
+| `result` | tool result to return directly |
+
+---
+
+## 5. `hook.after_tool`
+
+Triggered after tool execution completes. Can modify the result returned to LLM.
+
+### Request
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 5,
+ "method": "hook.after_tool",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "SessionKey": "session-1"
+ },
+ "tool": "echo_text",
+ "arguments": {
+ "text": "hello"
+ },
+ "result": {
+ "for_llm": "echoed: hello",
+ "for_user": "",
+ "silent": false,
+ "is_error": false,
+ "async": false,
+ "media": [],
+ "artifact_tags": [],
+ "response_handled": false
+ },
+ "duration": 15000000,
+ "channel": "cli",
+ "chat_id": "chat-1"
+ }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `result.for_llm` | content returned to LLM |
+| `result.for_user` | content sent to user |
+| `result.silent` | whether silent (not sent to user) |
+| `result.is_error` | whether it's an error |
+| `result.async` | whether executed asynchronously |
+| `result.media` | list of media references |
+| `result.artifact_tags` | local artifact path tags |
+| `result.response_handled` | whether response has been handled |
+| `duration` | execution time (nanoseconds) |
+
+### Response
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 5,
+ "result": {
+ "action": "continue"
+ }
+}
+```
+
+---
+
+## 6. `hook.approve_tool`
+
+Approval hook for deciding whether to allow execution of sensitive tools.
+
+### Request
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 6,
+ "method": "hook.approve_tool",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "SessionKey": "session-1"
+ },
+ "tool": "bash",
+ "arguments": {
+ "command": "rm -rf /"
+ },
+ "channel": "cli",
+ "chat_id": "chat-1"
+ }
+}
+```
+
+### Response (Approved)
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 6,
+ "result": {
+ "approved": true
+ }
+}
+```
+
+### Response (Denied)
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 6,
+ "result": {
+ "approved": false,
+ "reason": "Dangerous command, execution denied"
+ }
+}
+```
+
+---
+
+## 7. `hook.event` (notification)
+
+Observer event, broadcast only, no response required. `id` is `0` or absent.
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "hook.event",
+ "params": {
+ "Kind": "tool_exec_start",
+ "Meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1"
+ },
+ "Payload": {
+ "Tool": "echo_text",
+ "Arguments": {"text": "hello"}
+ }
+ }
+}
+```
+
+Common `Kind` values:
+- `turn_start` / `turn_end`
+- `llm_request` / `llm_response`
+- `tool_exec_start` / `tool_exec_end` / `tool_exec_skipped`
+- `steering_injected`
+- `interrupt_received`
+- `error`
+
+---
+
+## Action Options
+
+| action | Applicable hooks | Effect |
+|--------|-----------------|--------|
+| `continue` | All interceptor types | Pass through without modification |
+| `modify` | `before_llm`, `before_tool`, `after_llm`, `after_tool` | Modify request/response and pass through |
+| `respond` | `before_tool` | Return tool result directly, skip actual execution. **Note: AfterTool is NOT called (design decision - respond provides final answer).** |
+| `deny_tool` | `before_tool` | Deny tool execution |
+| `abort_turn` | All interceptor types | Abort current turn, return error |
+| `hard_abort` | All interceptor types | Force stop entire agent loop |
+
+---
+
+## Complete Flow Example
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"hook.hello","params":{"name":"my_hook","version":1,"modes":["tool","approve"]}}
+{"jsonrpc":"2.0","id":1,"result":{"ok":true,"name":"my_hook"}}
+{"jsonrpc":"2.0","id":2,"method":"hook.before_llm","params":{"model":"claude-sonnet","messages":[{"role":"user","content":"hello"}],"tools":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"action":"continue"}}
+{"jsonrpc":"2.0","id":3,"method":"hook.before_tool","params":{"tool":"bash","arguments":{"command":"ls"}}}
+{"jsonrpc":"2.0","id":3,"result":{"action":"continue"}}
+{"jsonrpc":"2.0","id":4,"method":"hook.approve_tool","params":{"tool":"bash","arguments":{"command":"ls"}}}
+{"jsonrpc":"2.0","id":4,"result":{"approved":true}}
+{"jsonrpc":"2.0","id":5,"method":"hook.after_tool","params":{"tool":"bash","arguments":{"command":"ls"},"result":{"for_llm":"file1.txt\nfile2.txt"},"duration":5000000}}
+{"jsonrpc":"2.0","id":5,"result":{"action":"continue"}}
+{"jsonrpc":"2.0","id":6,"method":"hook.after_llm","params":{"model":"claude-sonnet","response":{"role":"assistant","content":"Files listed"}}}
+{"jsonrpc":"2.0","id":6,"result":{"action":"continue"}}
+```
+
+---
+
+## Plugin Tool Injection via `before_llm` and `before_tool`
+
+Standard flow for plugin tool injection:
+
+1. In `before_llm`, inject tool definition to let LLM know the tool is available
+2. In `before_tool`, use `respond` action to return tool execution result directly
+
+### `before_llm` Inject Tool Definition
+
+```python
+def handle_before_llm(params: dict) -> dict:
+ tools = params.get("tools", [])
+
+ # Add plugin tool definition
+ tools.append({
+ "type": "function",
+ "function": {
+ "name": "my_plugin_tool",
+ "description": "Plugin provided tool",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "Input content"}
+ },
+ "required": ["input"]
+ }
+ }
+ })
+
+ return {
+ "action": "modify",
+ "request": {
+ "model": params["model"],
+ "messages": params["messages"],
+ "tools": tools,
+ "options": params.get("options", {})
+ }
+ }
+```
+
+### `before_tool` Return Execution Result
+
+```python
+def handle_before_tool(params: dict) -> dict:
+ tool = params.get("tool", "")
+
+ if tool == "my_plugin_tool":
+ # Implement tool logic here
+ args = params.get("arguments", {})
+ input_text = args.get("input", "")
+
+ # Return result directly, no need to register in ToolRegistry
+ return {
+ "action": "respond",
+ "result": {
+ "for_llm": f"Plugin tool executed successfully, input: {input_text}",
+ "silent": False,
+ "is_error": False
+ }
+ }
+
+ return {"action": "continue"}
+```
+
+This way, external hooks can fully implement plugin tools without registering any tool implementation inside PicoClaw.
\ No newline at end of file
diff --git a/docs/hooks/hook-json-protocol.zh.md b/docs/hooks/hook-json-protocol.zh.md
new file mode 100644
index 000000000..675e0a429
--- /dev/null
+++ b/docs/hooks/hook-json-protocol.zh.md
@@ -0,0 +1,568 @@
+# Hook JSON-RPC 协议详解
+
+所有 hook 使用 `JSON-RPC 2.0` 格式，每行一个 JSON 消息，通过 stdio 传输。
+
+---
+
+## 基础协议结构
+
+### 请求（PicoClaw → Hook）
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"hook.xxx","params":{...}}
+```
+
+### 响应（Hook → PicoClaw）
+
+成功：
+```json
+{"jsonrpc":"2.0","id":1,"result":{...}}
+```
+
+错误：
+```json
+{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"错误信息"}}
+```
+
+---
+
+## 1. `hook.hello`（握手）
+
+启动时必须完成握手，否则 hook 进程会被终止。
+
+### 请求
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "hook.hello",
+ "params": {
+ "name": "py_review_gate",
+ "version": 1,
+ "modes": ["observe", "tool", "approve"]
+ }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `name` | hook 名称（来自配置） |
+| `version` | 协议版本，当前为 `1` |
+| `modes` | hook 支持的能力模式 |
+
+### 响应
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "result": {
+ "ok": true,
+ "name": "python-review-gate"
+ }
+}
+```
+
+---
+
+## 2. `hook.before_llm`
+
+在发送请求给 LLM 之前触发。可用于注入工具。
+
+### 请求
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 2,
+ "method": "hook.before_llm",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "ParentTurnID": "",
+ "SessionKey": "session-1",
+ "Iteration": 0,
+ "TracePath": "runTurn",
+ "Source": "turn.llm.request"
+ },
+ "model": "claude-sonnet",
+ "messages": [
+ {"role": "user", "content": "hello"}
+ ],
+ "tools": [
+ {
+ "type": "function",
+ "function": {
+ "name": "echo",
+ "description": "echo text",
+ "parameters": {"type": "object"}
+ }
+ }
+ ],
+ "options": {
+ "temperature": 0.7
+ },
+ "channel": "cli",
+ "chat_id": "chat-1",
+ "graceful_terminal": false
+ }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `meta` | 事件元数据，用于追踪 |
+| `model` | 请求的模型名称 |
+| `messages` | 对话历史 |
+| `tools` | 可用工具定义列表 |
+| `options` | LLM 参数（temperature、max_tokens 等） |
+| `channel` | 请求来源通道 |
+| `chat_id` | 会话 ID |
+
+### 响应（注入工具示例）
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 2,
+ "result": {
+ "action": "modify",
+ "request": {
+ "model": "claude-sonnet",
+ "messages": [{"role": "user", "content": "hello"}],
+ "tools": [
+ {
+ "type": "function",
+ "function": {
+ "name": "echo",
+ "description": "echo",
+ "parameters": {}
+ }
+ },
+ {
+ "type": "function",
+ "function": {
+ "name": "my_plugin_tool",
+ "description": "插件注入的工具",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "query": {"type": "string"}
+ }
+ }
+ }
+ }
+ ]
+ }
+ }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `action` | 决策动作（见下表） |
+| `request` | 修改后的请求对象 |
+
+---
+
+## 3. `hook.after_llm`
+
+在收到 LLM 响应后触发。可修改响应内容。
+
+### 请求
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 3,
+ "method": "hook.after_llm",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "SessionKey": "session-1"
+ },
+ "model": "claude-sonnet",
+ "response": {
+ "role": "assistant",
+ "content": "Hi!",
+ "tool_calls": [
+ {
+ "id": "tc-1",
+ "type": "function",
+ "function": {
+ "name": "echo",
+ "arguments": "{\"text\":\"hi\"}"
+ }
+ }
+ ]
+ },
+ "channel": "cli",
+ "chat_id": "chat-1"
+ }
+}
+```
+
+### 响应
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 3,
+ "result": {
+ "action": "continue"
+ }
+}
+```
+
+---
+
+## 4. `hook.before_tool`
+
+在执行工具前触发。可修改工具名称和参数，或拒绝执行，或直接返回结果。
+
+### 请求
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 4,
+ "method": "hook.before_tool",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "SessionKey": "session-1"
+ },
+ "tool": "echo_text",
+ "arguments": {
+ "text": "hello"
+ },
+ "channel": "cli",
+ "chat_id": "chat-1"
+ }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `tool` | 工具名称 |
+| `arguments` | 工具参数 |
+
+### 响应（改写参数）
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 4,
+ "result": {
+ "action": "modify",
+ "call": {
+ "tool": "echo_text",
+ "arguments": {
+ "text": "modified hello"
+ }
+ }
+ }
+}
+```
+
+### 响应（拒绝执行）
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 4,
+ "result": {
+ "action": "deny_tool",
+ "reason": "参数不合法"
+ }
+}
+```
+
+### 响应（直接返回结果 - respond）
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 4,
+ "result": {
+ "action": "respond",
+ "call": {
+ "tool": "my_plugin_tool",
+ "arguments": {
+ "query": "hello"
+ }
+ },
+ "result": {
+ "for_llm": "Plugin tool executed successfully",
+ "for_user": "",
+ "silent": false,
+ "is_error": false
+ }
+ }
+}
+```
+
+`respond` action 允许 hook 直接返回工具结果，跳过实际工具执行。适用于：
+1. **插件工具注入**：外部 hook 可实现工具，无需在 ToolRegistry 注册
+2. **工具结果缓存**：对重复调用返回缓存结果
+3. **工具模拟**：测试时返回模拟结果
+
+| 字段 | 说明 |
+|------|------|
+| `action` | 必须为 `respond` |
+| `call` | 修改后的调用信息（可选） |
+| `result` | 直接返回的工具结果 |
+
+---
+
+## 5. `hook.after_tool`
+
+在工具执行完成后触发。可修改返回给 LLM 的结果。
+
+### 请求
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 5,
+ "method": "hook.after_tool",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "SessionKey": "session-1"
+ },
+ "tool": "echo_text",
+ "arguments": {
+ "text": "hello"
+ },
+ "result": {
+ "for_llm": "echoed: hello",
+ "for_user": "",
+ "silent": false,
+ "is_error": false,
+ "async": false,
+ "media": [],
+ "artifact_tags": [],
+ "response_handled": false
+ },
+ "duration": 15000000,
+ "channel": "cli",
+ "chat_id": "chat-1"
+ }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `result.for_llm` | 返回给 LLM 的内容 |
+| `result.for_user` | 发送给用户的内容 |
+| `result.silent` | 是否静默（不发送给用户） |
+| `result.is_error` | 是否为错误 |
+| `result.async` | 是否异步执行 |
+| `result.media` | 媒体引用列表 |
+| `result.artifact_tags` | 本地产物路径标签 |
+| `result.response_handled` | 是否已处理响应 |
+| `duration` | 执行耗时（纳秒） |
+
+### 响应
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 5,
+ "result": {
+ "action": "continue"
+ }
+}
+```
+
+---
+
+## 6. `hook.approve_tool`
+
+审批型 hook，用于决定是否允许执行敏感工具。
+
+### 请求
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 6,
+ "method": "hook.approve_tool",
+ "params": {
+ "meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1",
+ "SessionKey": "session-1"
+ },
+ "tool": "bash",
+ "arguments": {
+ "command": "rm -rf /"
+ },
+ "channel": "cli",
+ "chat_id": "chat-1"
+ }
+}
+```
+
+### 响应（批准）
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 6,
+ "result": {
+ "approved": true
+ }
+}
+```
+
+### 响应（拒绝）
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 6,
+ "result": {
+ "approved": false,
+ "reason": "危险命令，禁止执行"
+ }
+}
+```
+
+---
+
+## 7. `hook.event`（notification）
+
+观察型事件，仅广播，无需响应。`id` 为 `0` 或不存在。
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "hook.event",
+ "params": {
+ "Kind": "tool_exec_start",
+ "Meta": {
+ "AgentID": "agent-1",
+ "TurnID": "turn-1"
+ },
+ "Payload": {
+ "Tool": "echo_text",
+ "Arguments": {"text": "hello"}
+ }
+ }
+}
+```
+
+常见 `Kind` 值：
+- `turn_start` / `turn_end`
+- `llm_request` / `llm_response`
+- `tool_exec_start` / `tool_exec_end` / `tool_exec_skipped`
+- `steering_injected`
+- `interrupt_received`
+- `error`
+
+---
+
+## action 可选值
+
+| action | 适用 hook | 效果 |
+|--------|----------|------|
+| `continue` | 所有拦截型 | 放行，不做修改 |
+| `modify` | `before_llm`, `before_tool`, `after_llm`, `after_tool` | 改写请求/响应后放行 |
+| `respond` | `before_tool` | 直接返回工具结果，跳过实际执行 |
+| `deny_tool` | `before_tool` | 拒绝执行该工具 |
+| `abort_turn` | 所有拦截型 | 中止当前 turn，返回错误 |
+| `hard_abort` | 所有拦截型 | 强制终止整个 agent loop |
+
+---
+
+## 完整流程示例
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"hook.hello","params":{"name":"my_hook","version":1,"modes":["tool","approve"]}}
+{"jsonrpc":"2.0","id":1,"result":{"ok":true,"name":"my_hook"}}
+{"jsonrpc":"2.0","id":2,"method":"hook.before_llm","params":{"model":"claude-sonnet","messages":[{"role":"user","content":"hello"}],"tools":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"action":"continue"}}
+{"jsonrpc":"2.0","id":3,"method":"hook.before_tool","params":{"tool":"bash","arguments":{"command":"ls"}}}
+{"jsonrpc":"2.0","id":3,"result":{"action":"continue"}}
+{"jsonrpc":"2.0","id":4,"method":"hook.approve_tool","params":{"tool":"bash","arguments":{"command":"ls"}}}
+{"jsonrpc":"2.0","id":4,"result":{"approved":true}}
+{"jsonrpc":"2.0","id":5,"method":"hook.after_tool","params":{"tool":"bash","arguments":{"command":"ls"},"result":{"for_llm":"file1.txt\nfile2.txt"},"duration":5000000}}
+{"jsonrpc":"2.0","id":5,"result":{"action":"continue"}}
+{"jsonrpc":"2.0","id":6,"method":"hook.after_llm","params":{"model":"claude-sonnet","response":{"role":"assistant","content":"已列出文件"}}}
+{"jsonrpc":"2.0","id":6,"result":{"action":"continue"}}
+```
+
+---
+
+## 通过 `before_llm` 和 `before_tool` 实现插件工具注入
+
+插件工具注入的标准流程：
+
+1. 在 `before_llm` 中注入工具定义，让 LLM 知道有这个工具可用
+2. 在 `before_tool` 中使用 `respond` action 直接返回工具执行结果
+
+### `before_llm` 注入工具定义
+
+```python
+def handle_before_llm(params: dict) -> dict:
+ tools = params.get("tools", [])
+
+ # 添加插件工具定义
+ tools.append({
+ "type": "function",
+ "function": {
+ "name": "my_plugin_tool",
+ "description": "插件提供的工具",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "input": {"type": "string", "description": "输入内容"}
+ },
+ "required": ["input"]
+ }
+ }
+ })
+
+ return {
+ "action": "modify",
+ "request": {
+ "model": params["model"],
+ "messages": params["messages"],
+ "tools": tools,
+ "options": params.get("options", {})
+ }
+ }
+```
+
+### `before_tool` 返回执行结果
+
+```python
+def handle_before_tool(params: dict) -> dict:
+ tool = params.get("tool", "")
+
+ if tool == "my_plugin_tool":
+ # 在这里实现工具逻辑
+ args = params.get("arguments", {})
+ input_text = args.get("input", "")
+
+ # 直接返回结果，无需在 ToolRegistry 注册
+ return {
+ "action": "respond",
+ "result": {
+ "for_llm": f"插件工具执行成功，输入: {input_text}",
+ "silent": False,
+ "is_error": False
+ }
+ }
+
+ return {"action": "continue"}
+```
+
+通过这种方式，外部 hook 可以完全实现插件工具，无需在 PicoClaw 内部注册任何工具实现。
\ No newline at end of file
diff --git a/docs/hooks/plugin-tool-injection.md b/docs/hooks/plugin-tool-injection.md
new file mode 100644
index 000000000..9e699867b
--- /dev/null
+++ b/docs/hooks/plugin-tool-injection.md
@@ -0,0 +1,587 @@
+# Plugin Tool Injection Example
+
+This document demonstrates how to use PicoClaw's hook system to implement external plugin tool injection, allowing LLM to call tools implemented by external hook processes.
+
+---
+
+## Core Principle
+
+Through the hook system's `respond` action, external hooks can:
+
+1. Inject tool **definitions** in `before_llm`, letting LLM know the tool is available
+2. Return tool **execution results** directly in `before_tool` using `respond` action, skipping ToolRegistry
+
+This way, external hooks can fully implement plugin tools without registering any tools inside PicoClaw.
+
+---
+
+## Complete Example: Weather Query Plugin
+
+Below is a complete Python hook example implementing a weather query plugin tool.
+
+### 1. Hook Script Implementation
+
+Save as `/tmp/weather_plugin.py`:
+
+```python
+#!/usr/bin/env python3
+"""Weather query plugin hook example"""
+from __future__ import annotations
+
+import json
+import sys
+import signal
+from typing import Any
+
+# Simulated weather data
+WEATHER_DATA = {
+ "Beijing": {"temp": 15, "weather": "Sunny", "humidity": 45},
+ "Shanghai": {"temp": 18, "weather": "Cloudy", "humidity": 60},
+ "Guangzhou": {"temp": 25, "weather": "Sunny", "humidity": 70},
+ "Shenzhen": {"temp": 26, "weather": "Cloudy", "humidity": 75},
+}
+
+
+def get_weather(city: str) -> dict:
+ """Get weather data (simulated)"""
+ data = WEATHER_DATA.get(city)
+ if data:
+ return {
+ "for_llm": f"{city} weather: {data['weather']}, temperature {data['temp']}°C, humidity {data['humidity']}%",
+ "for_user": "",
+ "silent": False,
+ "is_error": False,
+ }
+ return {
+ "for_llm": f"Weather data not found for city {city}",
+ "for_user": "",
+ "silent": False,
+ "is_error": True,
+ }
+
+
+def handle_hello(params: dict) -> dict:
+ return {"ok": True, "name": "weather-plugin"}
+
+
+def handle_before_llm(params: dict) -> dict:
+ """Inject weather query tool definition"""
+ tools = params.get("tools", [])
+
+ # Add weather query tool
+ tools.append({
+ "type": "function",
+ "function": {
+ "name": "get_weather",
+ "description": "Query weather information for a specified city",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "city": {
+ "type": "string",
+ "description": "City name, e.g.: Beijing, Shanghai, Guangzhou"
+ }
+ },
+ "required": ["city"]
+ }
+ }
+ })
+
+ return {
+ "action": "modify",
+ "request": {
+ "model": params.get("model"),
+ "messages": params.get("messages", []),
+ "tools": tools,
+ "options": params.get("options", {}),
+ }
+ }
+
+
+def handle_before_tool(params: dict) -> dict:
+ """Handle tool call, return result directly"""
+ tool = params.get("tool", "")
+ args = params.get("arguments", {})
+
+ if tool == "get_weather":
+ city = args.get("city", "")
+ result = get_weather(city)
+
+ # Use respond action to return result directly, skip ToolRegistry
+ return {
+ "action": "respond",
+ "result": result,
+ }
+
+ # Other tools continue normal flow
+ return {"action": "continue"}
+
+
+def handle_request(method: str, params: dict) -> dict:
+ if method == "hook.hello":
+ return handle_hello(params)
+ if method == "hook.before_llm":
+ return handle_before_llm(params)
+ if method == "hook.before_tool":
+ return handle_before_tool(params)
+ if method == "hook.after_llm":
+ return {"action": "continue"}
+ if method == "hook.after_tool":
+ return {"action": "continue"}
+ if method == "hook.approve_tool":
+ return {"approved": True}
+ raise KeyError(f"method not found: {method}")
+
+
+def send_response(message_id: int, result: Any | None = None, error: str | None = None) -> None:
+ payload: dict[str, Any] = {
+ "jsonrpc": "2.0",
+ "id": message_id,
+ }
+ if error is not None:
+ payload["error"] = {"code": -32000, "message": error}
+ else:
+ payload["result"] = result if result is not None else {}
+
+ sys.stdout.write(json.dumps(payload, ensure_ascii=True) + "\n")
+ sys.stdout.flush()
+
+
+def main() -> int:
+ for raw_line in sys.stdin:
+ line = raw_line.strip()
+ if not line:
+ continue
+
+ try:
+ message = json.loads(line)
+ except json.JSONDecodeError:
+ continue
+
+ method = message.get("method")
+ message_id = message.get("id", 0)
+ params = message.get("params") or {}
+
+ if not message_id:
+ continue
+
+ try:
+ result = handle_request(str(method or ""), params)
+ send_response(int(message_id), result=result)
+ except KeyError as exc:
+ send_response(int(message_id), error=str(exc))
+ except Exception as exc:
+ send_response(int(message_id), error=f"unexpected error: {exc}")
+
+ return 0
+
+
+if __name__ == "__main__":
+ signal.signal(signal.SIGINT, lambda *_: raise SystemExit(0))
+ signal.signal(signal.SIGTERM, lambda *_: raise SystemExit(0))
+ raise SystemExit(main())
+```
+
+### 2. Configure PicoClaw
+
+Add hook configuration in the config file:
+
+```json
+{
+ "hooks": {
+ "enabled": true,
+ "processes": {
+ "weather_plugin": {
+ "enabled": true,
+ "priority": 100,
+ "transport": "stdio",
+ "command": ["python3", "/tmp/weather_plugin.py"],
+ "intercept": ["before_llm", "before_tool"]
+ }
+ }
+ }
+}
+```
+
+### 3. Test Results
+
+When user asks "What's the weather in Beijing today?":
+
+1. PicoClaw sends `hook.before_llm`, hook injects `get_weather` tool definition
+2. LLM sees tool definition, decides to call `get_weather(city="Beijing")`
+3. PicoClaw sends `hook.before_tool`, hook uses `respond` action to return weather data
+4. LLM receives result, replies to user "Beijing is sunny today, temperature 15°C"
+
+---
+
+## Flow Diagram
+
+```
+User: "What's the weather in Beijing today?"
+ ↓
+ PicoClaw
+ ↓
+ hook.before_llm
+ ↓ (inject get_weather tool definition)
+ LLM request
+ ↓
+ LLM decides to call get_weather(city="Beijing")
+ ↓
+ hook.before_tool
+ ↓ (respond action returns weather data)
+ Return result directly to LLM
+ ↓ (skip ToolRegistry)
+ LLM replies: "Beijing is sunny today, temperature 15°C"
+```
+
+---
+
+## Key Points
+
+### `before_llm` Inject Tool Definition
+
+Tool definition follows OpenAI function calling format:
+
+```json
+{
+ "type": "function",
+ "function": {
+ "name": "tool_name",
+ "description": "tool description",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "param_name": {
+ "type": "string",
+ "description": "parameter description"
+ }
+ },
+ "required": ["list of required parameters"]
+ }
+ }
+}
+```
+
+### `before_tool` Use respond Action
+
+`respond` action response format:
+
+```json
+{
+ "action": "respond",
+ "result": {
+ "for_llm": "Content returned to LLM",
+ "for_user": "Optional, content sent to user",
+ "silent": false,
+ "is_error": false,
+ "media": ["Optional, media reference list"],
+ "response_handled": false
+ }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `for_llm` | Required, LLM will see this content |
+| `for_user` | Optional, sent directly to user |
+| `silent` | When true, not sent to user |
+| `is_error` | When true, indicates execution failure |
+| `media` | Optional, media file references (images, files, etc.) |
+| `response_handled` | When true, indicates user request is handled, turn will end |
+
+---
+
+## Media File Handling
+
+The `respond` action supports returning media files (images, files, etc.). There are two processing modes:
+
+### 1. Automatic Delivery (`response_handled=true`)
+
+When `response_handled=true`, media files are automatically sent to the user and the turn ends:
+
+```json
+{
+ "action": "respond",
+ "result": {
+ "for_llm": "Image sent to user",
+ "for_user": "",
+ "media": ["media://abc123"],
+ "response_handled": true
+ }
+}
+```
+
+Use cases:
+- Image generation plugin directly returning results
+- File download plugin sending files to user
+
+### 2. LLM Visible (`response_handled=false`)
+
+When `response_handled=false`, media references are passed to the LLM, which can see the content in the next request:
+
+```json
+{
+ "action": "respond",
+ "result": {
+ "for_llm": "Image loaded, path: /tmp/image.png [file:/tmp/image.png]",
+ "media": ["media://abc123"]
+ }
+}
+```
+
+After seeing the content, the LLM can decide:
+- Use `send_file` tool to send to user
+- Analyze image content and reply to user
+- Other processing approaches
+
+### Media Reference Format
+
+Media references use the `media://` protocol:
+
+```
+media://
+
+
