Design: L2 team-scoped workspace access (knowledge base files, per-user write opt-in, tool approval)

## Background

AgentTeams runs teams of QwenPaw workers behind a Matrix collaboration layer. Beyond the L1 admin (admin/manager), L2 business users (Human CRs with `accessibleTeams`) operate inside their own teams. This issue records the design for letting L2 users operate their own team's agents without L1 involvement:

1. **Read/edit the team knowledge base** (each worker's `MEMORY.md`, `memory/**`, `digest/**`) from the web frontend (W3 knowledge base tab).
2. **Per-user write control** — L1 decides which L2 users may write, not just read.
3. **Per-worker tool-approval policy** — which tool calls run automatically and which pause for a human approval.

## Design decisions (as implemented)

### 1. Team-scoped, W8 anti-probing
- The boundary is the worker's **team**: an L2 human may only touch workers in their own teams (Human CR `accessibleTeams`); team leaders likewise (read-only on the write surfaces below).
- Out-of-scope workers are **hidden as `404`** (never `403`) — a scoped caller cannot probe which workers exist in other teams (W8). The authorizer deliberately allows the sensitive actions for humans cross-team, exactly like `ActionGet`; the handler is the real boundary.

### 2. Knowledge base files (PR #1208)
- Fixed-subpath proxy to the worker's qwenpaw app: `tree` / `file-metadata` / `file-content` (read + download) / `file-content` (write).
- **Path allowlist**: `MEMORY.md` (a single top-level file — exactly one segment, `MEMORY.md/foo` rejected), `memory/**`, `digest/**` (nested, ≤4 segments). Everything else — `.copaw/agent.json` (credentials), `SOUL.md`/`PROFILE.md` (behavior files), `skills/`, dot-segments, traversal — is rejected `400` before the worker is touched.
- **Concurrency**: writes require `If-Match` (ETag) on existing files and forbid it on new files; upstream `409` passes through. Workers auto-append to their memory files, so a skipped ETag check is a lost update.

### 3. Per-user write access: explicit opt-in, fail-closed default
- New `Human.spec.workspaceFileAccess: read | readwrite`.
- **Empty/missing = `read`.** Writing requires an explicit `readwrite` set by L1 (`agt apply` or `PUT /api/v1/humans/{name}`); revocation is clearing the field.
- Rationale: defaulting to `readwrite` would silently grant every pre-existing L2 human a new ability to modify worker knowledge files at the moment the controller is upgraded. Defaults must not expand permissions across upgrades — granting is an explicit act. (This was the original proposal; flipped per review, see #1208.)
- Team leaders stay read-only on this API (the leader's policy surface is chat/owner, not REST).
- Downloads follow the **read** scope (not gated by `workspaceFileAccess`) — downloading is a read operation.

### 4. Tool approval (separate PR, linked below)
- `GET/PUT /api/v1/workers/{name}/approval` proxies the worker's `/workspace/running-config` surface for `approval_level`: `STRICT` / `SMART` / `AUTO` (upstream default) / `OFF`. Values are validated against the fixed four-token set before the worker is touched (the upstream model accepts any string; the proxy is the validation boundary).
- Same scope boundary as the KB write; same safe-write pattern (GET full config → change one field → PUT the full object; upstream `409` passes through).

### 5. Runtime & deployment constraints
- Embedded mode only (the proxies dial worker containers on the shared docker network; kube mode → uniform `503`).
- Version gate: workers on a QwenPaw version without the relevant router surface the upstream `404` verbatim so clients can show "worker upgrade required".

## Security model summary

| Surface | Read | Write |
|:--|:--|:--|
| KB files (tree / metadata / content / download) | L1 any team; L2 + leaders own team | L1 any team; L2 own team **only while `workspaceFileAccess=readwrite`**; leaders `403` |
| Tool-approval level | L1 any team; L2 + leaders own team | L1 any team; L2 own team; leaders `403` |

- Cross-scope access: `404` (existence hidden), never `403`.
- All writes are audit-logged (worker, path/level, caller, role).
- No CRD-level permission for workers or their service accounts on these endpoints (worker self-service is a separate surface).

## Known limitations (accepted for v1)

- Tool-approval writes are last-writer-wins under the upstream per-file path lock (the running-config API has no ETag); concurrent edits by two humans are serialized by the lock, and `409` passes through for retry.
- The KB write `If-Match` contract covers the known auto-append hazard (memory files); any future worker-side writer must honor the ETag.

## Linked PRs

- #1208 — worker KB file endpoints + `workspaceFileAccess` (items 1–3 above)
- #1216 — worker tool-approval endpoints (item 4)
- #1212 — worker-scoped write API (related: same authorizer/handler boundary pattern)

---

## 中文摘要

L2 业务用户（Human CR + `accessibleTeams`）在自己团队范围内管理 agent 的设计记录：① 团队知识库读写（`MEMORY.md` / `memory/**` / `digest/**`，固定子路径代理 + 路径白名单 + ETag 并发契约）② 逐用户写权限（`Human.spec.workspaceFileAccess`，**缺省/空 = read，写 = 显式 opt-in**——升级不静默扩权）③ 逐 worker 工具审批级别（`approval_level` 四档，安全写模式）。统一边界：团队 scope → W8 跨团队 `404` 隐藏（authorizer 放行、handler 是真边界）→ leader 写 `403` 只读 → 审计日志。仅 embedded 模式，旧版 worker 版本门 404 透传。详见上方各节。