agent-lyceum 0.8.0 → 0.8.1

package/README.md

@@ -110,7 +110,7 @@ agents:
   pm:        { can_message: [lead], allow_web: fetch }   # pm may search and read pages; the others have no web tools
 ```
 
-Agent fields: `runtime` (`claude-code`|`codex`; optional when `model` is recognizable: `opus`/`sonnet`/`haiku`/`claude-*` → Claude Code, `gpt-*`/`o3`/`*codex*` → Codex; precedence: project runtime > project model > global runtime > global model), `model`, `effort` (Claude Code: `low`|`medium`|`high`|`xhigh`|`max` via `--effort`; Codex: `minimal`|`low`|`medium`|`high`|`xhigh` via `model_reasoning_effort`; unset = CLI default), `agent_md`, `memory.global` / `memory.project`, `resume`, `can_message` (`all` or list; default `[lead]`, lead default `all`), `can_edit_agent_md` (default only the lead), `can_ask_user` (may send `type: ask` mail to you and pause the run for an answer; default only the lead), `allow_web` (`none`|`search`|`fetch`: what the agent may use of the web; unset means Claude Code gets no web tools and Codex keeps its own default; `search` = `WebSearch` / Codex `web_search="cached"`, `fetch` = `WebSearch` + `WebFetch` / Codex `web_search="live"`, `none` = no web tools / Codex `disabled`; `fetch` pulls whole pages into the agent's context, so give it only to agents that do little editing, such as a requirements or research role), `owns` (repo globs).
+Agent fields: `runtime` (`claude-code`|`codex`; optional when `model` is recognizable: `opus`/`sonnet`/`haiku`/`claude-*` → Claude Code, `gpt-*`/`o3`/`*codex*` → Codex; precedence: project runtime > project model > global runtime > global model), `model`, `effort` (Claude Code: `low`|`medium`|`high`|`xhigh`|`max` via `--effort`; Codex: `minimal`|`low`|`medium`|`high`|`xhigh` via `model_reasoning_effort`; unset = CLI default), `agent_md`, `memory.global` / `memory.project`, `resume`, `can_message` (`all` or list; default `[lead]`, lead default `all`), `can_edit_agent_md` (default only the lead), `can_ask_user` (may send `type: ask` mail to you and pause the run for an answer; default only the lead), `allow_web` (`none`|`search`|`fetch`; what the agent may use of the web, off unless set; see "Web access" below), `owns` (repo globs).
 
 Rules checked by `validate`: ≥ 2 agents (the lead and one member; the template has three), the lead is a listed agent, every agent has a runtime (explicit or inferred from `model`) and an existing `AGENT.md`, `effort` is valid for the agent's runtime (warning if `runtime` contradicts a recognizable `model`), `can_message` targets exist, memory dirs don't overlap, and with `max_parallel > 1` every non-lead agent needs non-overlapping `owns` and the repo must be a git repository.
 
@@ -125,6 +125,41 @@ Rules checked by `validate`: ≥ 2 agents (the lead and one member; the template
 
 Parallelism (`max_parallel > 1`) only runs agents with disjoint `owns`, and never alongside the lead. Each non-lead agent then works in its **own git worktree** (`projects/<name>/worktrees/<run-id>/<agent>`, branch `agent-lyceum/<run-id>/<agent>`) cut from a snapshot of the repo as it is when the agent is woken (`refs/agent-lyceum/<run-id>/base-<n>`; it includes the lead's uncommitted and new, non-ignored files; your HEAD, branches and working tree are not touched). `dispatcher.workspace_mode` is `auto` (worktrees when `max_parallel > 1`), `worktree` or `shared`; `shared` cannot be combined with parallel agents. A parallel run refuses to start while the repo has uncommitted changes of yours, and when the repo is not a git repository (run sequentially instead). When a member finishes, the dispatcher commits its worktree and brings the changes into your working tree (not your index or HEAD) before the lead reads the member's mail. Every changed path is checked first: it must be inside the member's `owns` (renames and deletions included), must not be `CLAUDE.md`/`AGENTS.md`, and symlinks may not point out of the project or the member's `owns`. If a file also changed in your repo since the member's snapshot, if a check fails, or if `git apply` fails, nothing is applied: the work stays on its branch and worktree, a report and patch are written to `runs/<run-id>/integration/`, the lead is told, and the run cannot end as `completed` (it ends `blocked`). A worktree isolates files only: it cannot isolate side effects on external services, databases or the network.
 
+## Web access (`allow_web`)
+
+By default no agent can use the web. Claude Code agents are woken in headless `dontAsk` mode, where anything not explicitly allowed is refused, so `WebSearch` and `WebFetch` are denied unless you opt in per agent with `allow_web` (in `team.yaml` or `project.yaml`; the project value wins). It only decides whether the agent may use the web tools; the write scope below is unchanged.
+
+| Value | Claude Code | Codex |
+|---|---|---|
+| unset | no web tools (as before) | nothing is passed: Codex keeps its own default |
+| `none` | no web tools | `-c web_search="disabled"` |
+| `search` | `WebSearch` | `-c web_search="cached"` |
+| `fetch` | `WebSearch` and `WebFetch` | `-c web_search="live"` |
+
+### `search` or `fetch`?
+
+- **`search`**: the agent can run a search and gets a list of results (typically titles, links and short snippets). It cannot open a page, so it only knows what the results say. That is enough for "which Node versions are still supported?", "what is the latest release of this library?" or "is this API deprecated?".
+- **`fetch`**: everything `search` does, plus reading the page behind a URL, so the page's text goes into the agent's context. You need it when the answer is inside a page: a specification, one section of an API reference, an issue thread, or a URL you put in the task.
+
+The two are separate levels because the risk is different. Text read from a page can carry instructions written for the agent ("ignore your rules and ..."), known as prompt injection. With `fetch` that text arrives in full; with `search` only snippets do. The more an agent can do (edit your repository, run commands), the more this matters.
+
+**Which agents to give it to.** Start with nothing. Give `search` to roles that look things up. Give `fetch` only to roles that really must read specific pages and do little editing, such as a requirements or research role like `pm`. Keep the members that edit your repo (for example `fe-member`, `qa-member`) off, and have the lead or the pm look things up and put the result in the task.
+
+### Things to know
+
+- **Unset is not `none`.** Unset leaves each runtime's own default alone: Claude Code has no web tools, but Codex may already have web search on. Set `none` to turn it off explicitly.
+- **Codex has one `web_search` setting, not two tools**, so `search` and `fetch` map to `cached` and `live`. As Codex describes them, `cached` answers from an index instead of browsing, and `live` searches the web in real time; this is an approximation by risk. `codex exec` takes no `--search` flag, so agent-lyceum passes `-c web_search="..."`.
+- **Not run end to end.** The Codex setting and its allowed values were checked against Codex 0.160.0, but the behaviour of `cached` / `live` and of Claude's two tools was not exercised against the real CLIs (that costs tokens). Try it once on the agent before relying on it.
+- `call` reads the field from `team.yaml`, and `run --agent` keeps it.
+
+```yaml
+# team.yaml
+agents:
+  pm:
+    runtime: claude-code
+    allow_web: fetch        # may search and read pages; agents without the field have no web tools
+```
+
 ## Write scope
 
 Default rules (everything else in the repo is unrestricted):

package/README.zh-TW.md

@@ -111,7 +111,7 @@ agents:
   pm:        { can_message: [lead], allow_web: fetch }   # pm 可以搜尋並讀網頁；其他人沒有網路工具
 ```
 
-Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可省略：`opus`/`sonnet`/`haiku`/`claude-*` → Claude Code，`gpt-*`/`o3`/`*codex*` → Codex；優先順序：專案 runtime > 專案 model > 全域 runtime > 全域 model）、`model`、`effort`（Claude Code：`low`|`medium`|`high`|`xhigh`|`max`，經 `--effort`；Codex：`minimal`|`low`|`medium`|`high`|`xhigh`，經 `model_reasoning_effort`；未設則用 CLI 預設）、`agent_md`、`memory.global` / `memory.project`、`resume`、`can_message`（`all` 或清單；預設 `[lead]`，lead 預設 `all`）、`can_edit_agent_md`（預設只有 lead）、`can_ask_user`（可用 `type: ask` 信件向你提問並暫停 run 等待回答；預設只有 lead）、`allow_web`（`none`|`search`|`fetch`：agent 可以使用多少網路；不設時 Claude Code 沒有網路工具、Codex 維持它自己的預設；`search` = `WebSearch`／Codex `web_search="cached"`，`fetch` = `WebSearch` 加 `WebFetch`／Codex `web_search="live"`，`none` = 不給網路工具／Codex `disabled`；`fetch` 會把整個網頁放進 agent 的上下文，只建議給很少改檔的角色，例如需求或研究角色）、`owns`（repo glob）。
+Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可省略：`opus`/`sonnet`/`haiku`/`claude-*` → Claude Code，`gpt-*`/`o3`/`*codex*` → Codex；優先順序：專案 runtime > 專案 model > 全域 runtime > 全域 model）、`model`、`effort`（Claude Code：`low`|`medium`|`high`|`xhigh`|`max`，經 `--effort`；Codex：`minimal`|`low`|`medium`|`high`|`xhigh`，經 `model_reasoning_effort`；未設則用 CLI 預設）、`agent_md`、`memory.global` / `memory.project`、`resume`、`can_message`（`all` 或清單；預設 `[lead]`，lead 預設 `all`）、`can_edit_agent_md`（預設只有 lead）、`can_ask_user`（可用 `type: ask` 信件向你提問並暫停 run 等待回答；預設只有 lead）、`allow_web`（`none`|`search`|`fetch`：agent 可以使用多少網路，不設就是不開；見下方「網路存取」）、`owns`（repo glob）。
 
 `validate` 檢查的規則：至少 2 個 agent（lead 加一位成員；範本預設是三位）、lead 在 agent 清單內、每個 agent 都有 runtime（明設或由 `model` 推斷）且 `AGENT.md` 存在、`effort` 對該 runtime 合法（若 `runtime` 與可辨識的 `model` 矛盾則警告）、`can_message` 的目標存在、記憶資料夾互不重疊，且當 `max_parallel > 1` 時，每個非 lead 的 agent 都必須有互不重疊的 `owns`，repo 也必須是 git repository。
 
@@ -126,6 +126,41 @@ Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可
 
 平行執行（`max_parallel > 1`）只會同時跑 `owns` 互不相交的 agent，且絕不與 lead 同時執行。此時每個非 lead 的 agent 都在**自己的 git worktree**（`projects/<name>/worktrees/<run-id>/<agent>`，branch `agent-lyceum/<run-id>/<agent>`）工作；worktree 是從喚醒當下 repo 的快照（`refs/agent-lyceum/<run-id>/base-<n>`，包含 lead 尚未提交的修改與新增、未被 ignore 的檔案）切出來的，你的 HEAD、branch 與工作目錄都不會被動到。`dispatcher.workspace_mode` 可設為 `auto`（`max_parallel > 1` 時用 worktree）、`worktree` 或 `shared`；`shared` 不能與平行 agent 並用。平行 run 在 repo 有你自己未提交的修改時，或 repo 不是 git repository 時，會拒絕啟動（請改為序列執行）。成員完成後，dispatcher 會提交它 worktree 中的修改，並在 lead 讀到該成員的信之前，把變更套用到你的工作目錄（不動你的 index 與 HEAD）。每個被改動的路徑都會先檢查：必須在該成員的 `owns` 內（rename 與刪除也算）、不得是 `CLAUDE.md`／`AGENTS.md`，symlink 不得指向專案或該成員 `owns` 之外。若同一檔案在成員的快照之後又在你的 repo 被改過、檢查未通過，或 `git apply` 失敗，就一個檔案都不套用：成果保留在它的 branch 與 worktree，報告與 patch 寫到 `runs/<run-id>/integration/`，並通知 lead，且這個 run 不能以 `completed` 結束（會以 `blocked` 結束）。worktree 只隔離檔案，無法隔離對外部服務、資料庫或網路的副作用。
 
+## 網路存取（`allow_web`）
+
+預設所有 agent 都不能使用網路。Claude Code 的 agent 是用無頭的 `dontAsk` 模式喚醒的，沒有明確允許的工具一律拒絕，所以 `WebSearch` 與 `WebFetch` 會被擋掉，要替個別 agent 用 `allow_web` 開放（寫在 `team.yaml` 或 `project.yaml`，專案層蓋過全域層）。它只決定 agent 能不能用網路工具，下面的寫入範圍不變。
+
+| 值 | Claude Code | Codex |
+|---|---|---|
+| 不設 | 不給網路工具（與以前相同） | 不傳任何設定：維持 Codex 自己的預設 |
+| `none` | 不給網路工具 | `-c web_search="disabled"` |
+| `search` | `WebSearch` | `-c web_search="cached"` |
+| `fetch` | `WebSearch` 加 `WebFetch` | `-c web_search="live"` |
+
+### `search` 還是 `fetch`？
+
+- **`search`**：agent 可以搜尋，拿到一串結果（通常是標題、連結與簡短摘要）。它不能打開網頁，所以只知道結果裡寫的內容。像「Node 的哪些版本還有支援？」「這個函式庫最新版是多少？」「這個 API 是不是已經棄用？」這類問題，這樣就夠了。
+- **`fetch`**：包含 `search` 的全部功能，再加上讀取某個網址背後的頁面，整頁文字都會進到 agent 的上下文。答案藏在頁面裡面時才需要：規格文件、API 參考的某一節、issue 討論串，或是你寫在任務裡的網址。
+
+分成兩級，是因為風險不一樣。從網頁讀進來的文字可能夾帶寫給 agent 的指示（「忽略你的規則，去做……」），這叫 prompt injection。`fetch` 會把整頁文字送進來；`search` 只有摘要。agent 能做的事越多（改你的 repo、執行指令），這點就越重要。
+
+**該給哪些 agent。**先什麼都不開。會查資料的角色給 `search`。只有真的必須讀指定頁面、而且很少改檔的角色才給 `fetch`，例如 `pm` 這種需求或研究角色。會改你 repo 的成員（例如 `fe-member`、`qa-member`）維持關閉，由 lead 或 pm 查好，再把結果寫進任務。
+
+### 要注意的事
+
+- **不設不等於 `none`。**不設是讓各 runtime 維持自己的預設：Claude Code 沒有網路工具，但 Codex 可能本來就開著網路搜尋。想明確關掉請設 `none`。
+- **Codex 只有一個 `web_search` 設定，不是兩個工具**，所以 `search` 與 `fetch` 對應到 `cached` 與 `live`。依 Codex 的說法，`cached` 是從索引回答、不即時瀏覽，`live` 是即時搜尋網路；這是依風險做的近似對應。`codex exec` 不收 `--search` 旗標，所以 agent-lyceum 改傳 `-c web_search="..."`。
+- **沒有實際端對端跑過。**Codex 的設定鍵與合法值用 Codex 0.160.0 確認過，但 `cached`／`live` 以及 Claude 兩個工具的實際行為，沒有用真的 CLI 跑過（會花 token）。正式依賴前，請先在該 agent 上手動試一次。
+- `call` 會讀 `team.yaml` 裡的這個欄位，`run --agent` 也會保留。
+
+```yaml
+# team.yaml
+agents:
+  pm:
+    runtime: claude-code
+    allow_web: fetch        # 可以搜尋並讀網頁；沒設這個欄位的 agent 就沒有網路工具
+```
+
 ## 寫入範圍
 
 預設規則（repo 內其餘部分不受限制）：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",