# PhoneWork — Development Guide

## Quick Reference

| Need | Where to look |
|------|---------------|
| Project architecture, deployment, bot commands | `README.md` |
| Claude Agent SDK usage patterns and tested examples | `docs/claude/` |
| SDK migration plan (subprocess → ClaudeSDKClient) | `.claude/plans/toasty-pondering-nova.md` |
| SDK session implementation (secretary model) | `agent/sdk_session.py` |
| Feishu card / markdown formatting | `docs/feishu/` |

## Claude Agent SDK

When writing code that uses `claude-agent-sdk`, **first read `docs/claude/`**:

- `_sdk_test_common.py` — .env auth loading pattern (`setup_auth()`, `auth_env()`, `make_tmpdir()`)
- `test_query_read_edit.py` — `query()` one-shot: Read + Edit with `allowed_tools`
- `test_client_write_resume.py` — `ClaudeSDKClient`: Write + session resume via `resume=session_id`
- `test_hooks_audit_deny.py` — Hooks: `PostToolUse` audit + `PreToolUse` deny

### Key rules (verified by testing)

- Use `allowed_tools` for permission auto-approval. **Do not pass custom lists to `tools=`** — it causes CLI exit code 1.
- Auth: set `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` in `.env`; pass via `ClaudeAgentOptions(env=auth_env())`. Clear `ANTHROPIC_API_KEY` to avoid auth conflicts.
- SDK does not strip ANSI escape codes from `ResultMessage.result` — handle in application layer if needed.
- On Windows, use manual `make_tmpdir()` / `remove_tmpdir()` instead of `tempfile.TemporaryDirectory()` context manager to avoid cleanup races with CLI subprocesses.

## Project Structure

```
bot/           Feishu event handling, commands, message sending
orchestrator/  LangChain agent + tools (session management, shell, files, web)
agent/         SDK session (secretary model), session manager, hooks, audit
router/        Multi-host routing (public VPS side)
host_client/   Host client (behind NAT, connects to router)
shared/        Wire protocol for router ↔ host communication
docs/claude/   Claude Agent SDK examples and reference tests
docs/feishu/   Feishu API reference
```

## Running Tests

```bash
cd docs/claude
../../.venv/Scripts/python test_query_read_edit.py
../../.venv/Scripts/python test_client_write_resume.py
../../.venv/Scripts/python test_hooks_audit_deny.py
```

Requires `.env` at project root with `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`.