*: update with more case and polished docs

Signed-off-by: Chojan Shang <chojan.shang@vesoft.com>

Author: Chojan Shang

README.md

@@ -136,6 +136,7 @@ Full example with streaming and lifecycle hooks lives in [examples/echo_agent.py
 - Project docs (MkDocs): https://psiace.github.io/agent-client-protocol-python/
 - Local sources: `docs/`
   - [Quickstart](docs/quickstart.md)
+  - [Releasing](docs/releasing.md)
 
 ## Gemini CLI bridge
 

docs/index.md

@@ -46,5 +46,6 @@ An opt-in smoke test lives at `tests/test_gemini_example.py`. Enable it with `AC
 ## Documentation map
 
 - [Quickstart](quickstart.md): install, run, and embed the echo agent, plus next steps for extending it
+- [Releasing](releasing.md): schema upgrade workflow, version bumps, and publishing checklist
 
 Source code lives under `src/acp/`, while tests and additional examples are available in `tests/` and `examples/`. If you plan to contribute, see the repository README for the development workflow.

docs/releasing.md

@@ -0,0 +1,56 @@
+# Releasing
+
+This project tracks the ACP schema tags published by
+[`agentclientprotocol/agent-client-protocol`](https://github.com/agentclientprotocol/agent-client-protocol).
+Every release should line up with one of those tags so that the generated `acp.schema` module, examples, and package
+version remain consistent.
+
+## 准备阶段
+
+1. 选择目标 schema 版本（例如 `v0.4.5`），并重新生成协议文件：
+
+   ```bash
+   ACP_SCHEMA_VERSION=v0.4.5 make gen-all
+   ```
+
+   该命令会下载对应的 schema 包并重写 `schema/` 与 `src/acp/schema.py`。
+
+2. 同步更新 `pyproject.toml` 中的版本号，并根据需要调整 `uv.lock`。
+
+3. 运行基础校验：
+
+   ```bash
+   make check
+   make test
+   ```
+
+   `make check` 会执行 Ruff 格式化/静态检查、类型分析以及依赖完整性校验；`make test` 则运行 pytest（含 doctest）。
+
+4. 更新文档与示例（例如 Gemini 集成）以反映变化。
+
+## 提交与合并
+
+1. 确认 diff 仅包含预期变动：schema 源文件、生成的 Pydantic 模型、版本号以及相应文档。
+2. 使用 Conventional Commits（如 `release: v0.4.5`）提交，并在 PR 中记录：
+   - 引用的 ACP schema 标签
+   - `make check` / `make test` 的结果
+   - 重要的行为或 API 变更
+3. 获得评审通过后合并 PR。
+
+## 通过 GitHub Release 触发发布
+
+仓库采用 GitHub Workflow (`on-release-main.yml`) 自动完成发布。主干合并完成后：
+
+1. 在 GitHub Releases 页面创建新的 Release，选择目标标签（形如 `v0.4.5`）。如标签不存在，Release 创建过程会自动打上该标签。
+2. Release 发布后，工作流会：
+   - 将标签写回 `pyproject.toml`（以保证包版本与标签一致）
+   - 构建并通过 `uv publish` 发布到 PyPI（使用 `PYPI_TOKEN` 机密）
+   - 使用 `mkdocs gh-deploy` 更新 GitHub Pages 文档
+
+无需在本地执行 `uv build` 或 `uv publish`；只需确保 Release 草稿信息完整（新增特性、兼容性注意事项等）。
+
+## 其他注意事项
+
+- Schema 有破坏性修改时，请同步更新 `tests/test_json_golden.py`、端到端用例（如 `tests/test_rpc.py`）以及相关示例。
+- 如果需要清理生成文件，可运行 `make clean`，之后重新执行 `make gen-all`。
+- 发布前务必确认 `ACP_ENABLE_GEMINI_TESTS` 等可选测试在必要环境下运行通过，以避免 Release 后出现回归。

tests/test_rpc.py

@@ -40,7 +40,12 @@
     AgentMessageChunk,
     AllowedOutcome,
     DeniedOutcome,
+    PermissionOption,
     TextContentBlock,
+    ToolCallLocation,
+    ToolCallProgress,
+    ToolCallStart,
+    ToolCallUpdate,
     UserMessageChunk,
 )
 
@@ -416,6 +421,169 @@ async def test_ignore_invalid_messages():
             await asyncio.wait_for(s.client_reader.readline(), timeout=0.1)
 
 
+class _ExampleAgent(Agent):
+    __test__ = False
+
+    def __init__(self) -> None:
+        self._conn: AgentSideConnection | None = None
+        self.permission_response: RequestPermissionResponse | None = None
+        self.prompt_requests: list[PromptRequest] = []
+
+    def bind(self, conn: AgentSideConnection) -> "_ExampleAgent":
+        self._conn = conn
+        return self
+
+    async def initialize(self, params: InitializeRequest) -> InitializeResponse:
+        return InitializeResponse(protocolVersion=params.protocolVersion)
+
+    async def newSession(self, params: NewSessionRequest) -> NewSessionResponse:
+        return NewSessionResponse(sessionId="sess_demo")
+
+    async def prompt(self, params: PromptRequest) -> PromptResponse:
+        assert self._conn is not None
+        self.prompt_requests.append(params)
+
+        await self._conn.sessionUpdate(
+            SessionNotification(
+                sessionId=params.sessionId,
+                update=AgentMessageChunk(
+                    sessionUpdate="agent_message_chunk",
+                    content=TextContentBlock(type="text", text="I'll help you with that."),
+                ),
+            )
+        )
+
+        await self._conn.sessionUpdate(
+            SessionNotification(
+                sessionId=params.sessionId,
+                update=ToolCallStart(
+                    sessionUpdate="tool_call",
+                    toolCallId="call_1",
+                    title="Modifying configuration",
+                    kind="edit",
+                    status="pending",
+                    locations=[ToolCallLocation(path="/project/config.json")],
+                    rawInput={"path": "/project/config.json"},
+                ),
+            )
+        )
+
+        permission_request = RequestPermissionRequest(
+            sessionId=params.sessionId,
+            toolCall=ToolCallUpdate(
+                toolCallId="call_1",
+                title="Modifying configuration",
+                kind="edit",
+                status="pending",
+                locations=[ToolCallLocation(path="/project/config.json")],
+                rawInput={"path": "/project/config.json"},
+            ),
+            options=[
+                PermissionOption(kind="allow_once", name="Allow", optionId="allow"),
+                PermissionOption(kind="reject_once", name="Reject", optionId="reject"),
+            ],
+        )
+        response = await self._conn.requestPermission(permission_request)
+        self.permission_response = response
+
+        if isinstance(response.outcome, AllowedOutcome) and response.outcome.optionId == "allow":
+            await self._conn.sessionUpdate(
+                SessionNotification(
+                    sessionId=params.sessionId,
+                    update=ToolCallProgress(
+                        sessionUpdate="tool_call_update",
+                        toolCallId="call_1",
+                        status="completed",
+                        rawOutput={"success": True},
+                    ),
+                )
+            )
+            await self._conn.sessionUpdate(
+                SessionNotification(
+                    sessionId=params.sessionId,
+                    update=AgentMessageChunk(
+                        sessionUpdate="agent_message_chunk",
+                        content=TextContentBlock(type="text", text="Done."),
+                    ),
+                )
+            )
+
+        return PromptResponse(stopReason="end_turn")
+
+
+class _ExampleClient(TestClient):
+    __test__ = False
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.permission_requests: list[RequestPermissionRequest] = []
+
+    async def requestPermission(self, params: RequestPermissionRequest) -> RequestPermissionResponse:
+        self.permission_requests.append(params)
+        if not params.options:
+            return RequestPermissionResponse(outcome=DeniedOutcome(outcome="cancelled"))
+        option = params.options[0]
+        return RequestPermissionResponse(outcome=AllowedOutcome(optionId=option.optionId, outcome="selected"))
+
+
+@pytest.mark.asyncio
+async def test_example_agent_permission_flow():
+    async with _Server() as s:
+        agent = _ExampleAgent()
+        client = _ExampleClient()
+
+        agent_conn = ClientSideConnection(lambda _conn: client, s.client_writer, s.client_reader)
+        AgentSideConnection(lambda conn: agent.bind(conn), s.server_writer, s.server_reader)
+
+        init = await agent_conn.initialize(InitializeRequest(protocolVersion=1))
+        assert init.protocolVersion == 1
+
+        session = await agent_conn.newSession(NewSessionRequest(mcpServers=[], cwd="/workspace"))
+        assert session.sessionId == "sess_demo"
+
+        prompt = PromptRequest(
+            sessionId=session.sessionId,
+            prompt=[TextContentBlock(type="text", text="Please edit config")],
+        )
+        resp = await agent_conn.prompt(prompt)
+        assert resp.stopReason == "end_turn"
+
+        for _ in range(50):
+            if len(client.notifications) >= 4:
+                break
+            await asyncio.sleep(0.02)
+
+        assert len(client.notifications) >= 4
+        session_updates = [getattr(note.update, "sessionUpdate", None) for note in client.notifications]
+        assert session_updates[:4] == ["agent_message_chunk", "tool_call", "tool_call_update", "agent_message_chunk"]
+
+        first_message = client.notifications[0].update
+        assert isinstance(first_message, AgentMessageChunk)
+        assert first_message.content.text == "I'll help you with that."
+
+        tool_call = client.notifications[1].update
+        assert isinstance(tool_call, ToolCallStart)
+        assert tool_call.title == "Modifying configuration"
+        assert tool_call.status == "pending"
+
+        tool_update = client.notifications[2].update
+        assert isinstance(tool_update, ToolCallProgress)
+        assert tool_update.status == "completed"
+        assert tool_update.rawOutput == {"success": True}
+
+        final_message = client.notifications[3].update
+        assert isinstance(final_message, AgentMessageChunk)
+        assert final_message.content.text == "Done."
+
+        assert len(client.permission_requests) == 1
+        options = client.permission_requests[0].options
+        assert [opt.optionId for opt in options] == ["allow", "reject"]
+
+        assert agent.permission_response is not None
+        assert isinstance(agent.permission_response.outcome, AllowedOutcome)
+        assert agent.permission_response.outcome.optionId == "allow"
+
+
 @pytest.mark.asyncio
 async def test_spawn_agent_process_roundtrip(tmp_path):
     script = Path(__file__).parents[1] / "examples" / "echo_agent.py"