Daemon: requirement start gate, project directories and agent proposals

- A session started on a requirement first explains its understanding
  read-only and waits for the user's confirmation (requirement_begin /
  requirement_confirm); with a plan, it plans and waits once more. Only a
  turn that ended at the stage shows it as `confirm`.
- Requirements belong to a project id (or none); old paths migrate once.
- Projects take extra directories (`dirs`): Claude --add-dir, Codex
  writable roots, the jucode sandbox's writable dirs.
- Agents belong to a project; their `requirements` tool lists requirements,
  updates progress and only proposes noting or closing one
  (requirement_proposal).
- requirement_prompt is removed.

Author: gaoyu06

crates/agent-core/src/core.rs

@@ -330,6 +330,17 @@ impl AgentCore {
         self.tool_state.set_sandbox(sandbox);
     }
 
+    /// Counts `dirs` as workspace: file tools may write them, and sandboxed
+    /// commands too.
+    pub fn add_writable_dirs(&mut self, dirs: &[PathBuf]) {
+        let mut sandbox = self
+            .tool_state
+            .sandbox()
+            .unwrap_or_else(|| self.config.sandbox.clone());
+        sandbox.writable_dirs.extend_from_slice(dirs);
+        self.tool_state.set_sandbox(Some(sandbox));
+    }
+
     /// Adds host tools and prompt text; they apply from the next turn.
     pub fn set_host_extensions(&mut self, host: crate::host::HostExtensions) {
         self.host = Some(host);

crates/daemon/src/agent_tools.rs

@@ -1,6 +1,6 @@
 //! Tools a long-lived agent's sessions get from the daemon, added to the
 //! engine through `HostExtensions`: `message_agent`, `timer`, `schedule`,
-//! `brief`, `question` and `report`.
+//! `brief`, `question`, `report` and `requirements`.
 
 use crate::{
     hub::Hub,
@@ -29,11 +29,44 @@ pub fn extensions(hub: Arc<Hub>, agent: String, session: String) -> HostExtensio
                 Err(error) => (json!({ "error": error }).to_string(), true),
             }
         }),
-        prompt: Arc::new(move || prompt_hub.agents.prompt(&prompt_agent, &prompt_session)),
+        prompt: Arc::new(move || {
+            let mut prompt = prompt_hub.agents.prompt(&prompt_agent, &prompt_session);
+            prompt.push_str(&project_prompt(&prompt_hub, &prompt_agent));
+            prompt
+        }),
         exclusive: false,
     }
 }
 
+/// The project the agent belongs to: its name and directories.
+fn project_prompt(hub: &Hub, agent: &str) -> String {
+    let Some(project) = hub
+        .agents
+        .get(agent)
+        .and_then(|agent| agent.project)
+        .and_then(|id| crate::projects::project(hub, &id))
+    else {
+        return String::new();
+    };
+    let dirs: Vec<&str> = project["dirs"]
+        .as_array()
+        .into_iter()
+        .flatten()
+        .filter_map(Value::as_str)
+        .collect();
+    format!(
+        "\n<project id=\"{}\" name=\"{}\">\nYou belong to this project; the `requirements` tool lists its requirements.\nMain directory: {}\nExtra directories: {}\n</project>",
+        project["id"].as_str().unwrap_or_default(),
+        project["name"].as_str().unwrap_or_default(),
+        project["path"].as_str().unwrap_or_default(),
+        if dirs.is_empty() {
+            "none".to_string()
+        } else {
+            dirs.join(", ")
+        }
+    )
+}
+
 /// The dispatcher's tools (see `dispatch`), plus `question`.
 fn dispatcher(hub: Arc<Hub>, session: String) -> HostExtensions {
     let prompt_hub = Arc::clone(&hub);
@@ -229,6 +262,10 @@ fn run(
             hub.post_report(&report)?;
             Ok(json!({ "report": report.id }))
         }
+        "requirements" => {
+            let project = hub.agents.get(agent).and_then(|agent| agent.project);
+            crate::requirements::tool(hub, agent, project.as_deref(), session, args)
+        }
         other => Err(format!("unknown tool {other}")),
     }
 }
@@ -335,5 +372,30 @@ fn definitions() -> Vec<Value> {
                 "additionalProperties": false
             }
         }),
+        json!({
+            "type": "function",
+            "name": "requirements",
+            "description": "The user's requirements (what they mean to get done). `list` shows those of your project (`project`: another project's id, or `none` for unassigned ones; `state` filters). `get` shows one in full: words, progress, start gate, pending proposal. `propose_create` and `propose_close` only propose: the user is asked, and nothing changes until they accept. Do not propose the same thing twice; a pending proposal shows in `list`. `progress` adds to a requirement's progress record directly: list items are appended once each.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "action": { "type": "string", "enum": ["list", "get", "propose_create", "propose_close", "progress"] },
+                    "requirement": { "type": "string", "description": "Requirement id (R-12), for get, propose_close and progress." },
+                    "project": { "type": "string", "description": "For list: a project id, or none for unassigned requirements." },
+                    "state": { "type": "string", "enum": ["idea", "open", "done", "parked", "proposed"], "description": "For list." },
+                    "text": { "type": "string", "description": "For propose_create: the requirement in the user's language." },
+                    "reason": { "type": "string", "description": "For propose_create and propose_close: why, in one line the user reads." },
+                    "outcome": { "type": "string", "enum": ["done", "parked"], "description": "For propose_close." },
+                    "decided": { "type": "array", "items": { "type": "string" } },
+                    "done": { "type": "array", "items": { "type": "string" } },
+                    "doing": { "type": "array", "items": { "type": "string" } },
+                    "blocked": { "type": "array", "items": { "type": "string" } },
+                    "next": { "type": "array", "items": { "type": "string" } },
+                    "note": { "type": "string", "description": "For progress: a note that replaces the previous one." }
+                },
+                "required": ["action"],
+                "additionalProperties": false
+            }
+        }),
     ]
 }

crates/daemon/src/agents.rs

@@ -60,6 +60,8 @@ pub struct Agent {
     /// workspaces had their own (clients put those in the default one). It
     /// runs whichever workspace is open.
     pub workspace: Option<String>,
+    /// The project it belongs to (its `cwd` is the project's main directory).
+    pub project: Option<String>,
 }
 
 #[derive(Debug, Clone, PartialEq)]
@@ -84,6 +86,7 @@ impl Agent {
                 "mode": dir.mode,
             })).collect::<Vec<_>>(),
             "command_rules": rules_to_json(&self.command_rules),
+            "project": self.project,
         });
         if let Some(icon) = &self.icon {
             value["icon"] = icon.clone();
@@ -182,6 +185,7 @@ impl Agents {
             color: value["color"].as_str().map(str::to_string),
             avatar_seed: value["avatar_seed"].as_str().map(str::to_string),
             workspace: value["workspace"].as_str().map(str::to_string),
+            project: value["project"].as_str().map(str::to_string),
         })
     }
 
@@ -228,12 +232,14 @@ impl Agents {
             color: None,
             avatar_seed: None,
             workspace: None,
+            project: None,
         };
         let mut settings = agent.to_json();
         settings.as_object_mut().map(|map| map.remove("id"));
         settings["avatar_seed"] = json!(random_hex(8).map_err(|error| error.to_string())?);
         set_appearance(&mut settings, appearance)?;
         set_workspace(&mut settings, appearance);
+        set_project(&mut settings, appearance)?;
         let write = || -> io::Result<()> {
             fs::create_dir_all(dir.join("memory"))?;
             fs::write(
@@ -252,8 +258,9 @@ impl Agents {
 
     /// Changes the settings present in `changes` (`name`, `enabled`,
     /// `approval_mode`, `sandbox`, `network`, `directories`,
-    /// `command_rules`, `icon`, `color`, `avatar_seed`, `workspace`), keeping the rest of
-    /// `agent.json`; `role` rewrites `role.md`.
+    /// `command_rules`, `icon`, `color`, `avatar_seed`, `workspace`,
+    /// `project` with `cwd`), keeping the rest of `agent.json`; `role`
+    /// rewrites `role.md`.
     pub fn update(&self, id: &str, changes: &Value) -> Result<Agent, String> {
         if !valid_id(id) {
             return Err(format!("unknown agent {id}"));
@@ -295,6 +302,7 @@ impl Agents {
         }
         set_appearance(&mut settings, changes)?;
         set_workspace(&mut settings, changes);
+        set_project(&mut settings, changes)?;
         let text = serde_json::to_string_pretty(&settings).map_err(|error| error.to_string())?;
         fs::write(&path, text + "\n").map_err(|error| error.to_string())?;
         if let Some(role) = changes["role"].as_str() {
@@ -545,6 +553,26 @@ fn set_workspace(settings: &mut Value, changes: &Value) {
     }
 }
 
+/// Applies `project` from `changes` (null clears it). A project comes with
+/// `cwd`, its main directory, where the agent then works.
+fn set_project(settings: &mut Value, changes: &Value) -> Result<(), String> {
+    match changes.get("project") {
+        Some(Value::String(id)) => {
+            let cwd = changes["cwd"]
+                .as_str()
+                .ok_or("a project needs its directory")?;
+            if !Path::new(cwd).is_dir() {
+                return Err(format!("not a directory: {cwd}"));
+            }
+            settings["project"] = json!(id);
+            settings["cwd"] = json!(cwd);
+        }
+        Some(Value::Null) => settings["project"] = Value::Null,
+        _ => {}
+    }
+    Ok(())
+}
+
 /// Applies `icon`, `color` and `avatar_seed` from `changes`; `null` clears
 /// one. Only shapes and sizes are checked here: an SVG icon is sanitized by
 /// the clients that draw it.

crates/daemon/src/engines/claude.rs

@@ -156,9 +156,17 @@ pub fn command(id: &str, options: &Options) -> Command {
     {
         command.args(["--effort", effort]);
     }
+    add_dirs(&mut command, options);
     command
 }
 
+/// The project's extra directories, which Claude Code may work in too.
+fn add_dirs(command: &mut Command, options: &Options) {
+    for dir in &options.dirs {
+        command.arg("--add-dir").arg(dir);
+    }
+}
+
 /// Claude Code's own TUI resuming conversation `id`, in the session's
 /// permission mode and model (for the GUI ⇄ TUI handoff).
 pub fn tui(id: &str, options: &Options, saved: bool) -> Command {
@@ -184,6 +192,7 @@ pub fn tui(id: &str, options: &Options, saved: bool) -> Command {
     if let Some(model) = &options.model {
         command.args(["--model", model]);
     }
+    add_dirs(&mut command, options);
     // A daemon started from inside Claude Code inherits that session's
     // markers; with them the TUI counts as a nested child and does not save
     // its transcript, so turns typed there would be lost on the way back.
@@ -3430,4 +3439,21 @@ mod tests {
         #[cfg(unix)]
         assert_eq!(project_dir(&home, &link), project_dir(&home, &real));
     }
+
+    #[test]
+    fn the_projects_extra_dirs_are_added_to_both_commands() {
+        let options = Options {
+            dirs: vec![PathBuf::from("/work/api"), PathBuf::from("/work/docs")],
+            ..Options::default()
+        };
+        for command in [command("s-1", &options), tui("s-1", &options, true)] {
+            let args: Vec<String> = command
+                .get_args()
+                .map(|a| a.to_string_lossy().to_string())
+                .collect();
+            let joined = args.join(" ");
+            assert!(joined.contains("--add-dir /work/api"), "{joined}");
+            assert!(joined.contains("--add-dir /work/docs"), "{joined}");
+        }
+    }
 }

crates/daemon/src/engines/codex.rs

@@ -57,12 +57,15 @@ pub fn tui(id: Option<&str>, options: &Options) -> Command {
     if mode == "full-auto" {
         command.arg("--dangerously-bypass-approvals-and-sandbox");
     } else {
-        let (approval, sandbox) = policy(mode);
+        let (approval, sandbox) = policy(mode, &options.dirs);
         command.args(["-a", approval, "-s", sandbox_mode(&sandbox)]);
     }
     if let Some(model) = &options.model {
         command.args(["-m", model]);
     }
+    for dir in &options.dirs {
+        command.arg("--add-dir").arg(dir);
+    }
     command
 }
 
@@ -145,13 +148,14 @@ fn engine_mode(mode: &str) -> &'static str {
     }
 }
 
-/// The approval policy and sandbox policy of an engine mode.
-fn policy(mode: &str) -> (&'static str, Value) {
+/// The approval policy and sandbox policy of an engine mode; `dirs` (the
+/// project's extra directories) are writable besides the workspace.
+fn policy(mode: &str, dirs: &[PathBuf]) -> (&'static str, Value) {
     match mode {
         // Auto: workspace writes, with a reviewer subagent deciding approvals.
         "auto-edit" | "auto" => (
             "on-request",
-            json!({ "type": "workspaceWrite", "writableRoots": [], "networkAccess": false, "excludeTmpdirEnvVar": false, "excludeSlashTmp": false }),
+            json!({ "type": "workspaceWrite", "writableRoots": dirs, "networkAccess": false, "excludeTmpdirEnvVar": false, "excludeSlashTmp": false }),
         ),
         "full-auto" => ("never", json!({ "type": "dangerFullAccess" })),
         _ => (
@@ -373,6 +377,8 @@ impl Item {
 
 pub struct Codex {
     cwd: PathBuf,
+    /// The project's extra directories: writable in workspace-write.
+    dirs: Vec<PathBuf>,
     mode: &'static str,
     next_id: u64,
     /// Our outstanding requests: id → (method, tag).
@@ -440,6 +446,7 @@ impl Codex {
     pub fn new(cwd: &Path, options: &Options) -> Self {
         Self {
             cwd: cwd.to_path_buf(),
+            dirs: options.dirs.clone(),
             mode: engine_mode(options.approval_mode.as_deref().unwrap_or_default()),
             next_id: 0,
             pending: HashMap::new(),
@@ -488,7 +495,7 @@ impl Codex {
     }
 
     fn turn_start(&mut self, input: Vec<Value>) -> String {
-        let (approval, sandbox) = policy(self.mode);
+        let (approval, sandbox) = policy(self.mode, &self.dirs);
         let mut params = json!({
             "threadId": self.thread,
             "input": input,
@@ -844,7 +851,7 @@ impl Codex {
         }
         match method.as_str() {
             "initialize" => {
-                let (approval, sandbox) = policy(self.mode);
+                let (approval, sandbox) = policy(self.mode, &self.dirs);
                 let open = json!({ "cwd": self.cwd, "approvalPolicy": approval, "sandbox": sandbox_mode(&sandbox) });
                 self.open_params = open.clone();
                 let mut frames =
@@ -2894,4 +2901,24 @@ mod tests {
             ("a", "fix login")
         );
     }
+
+    #[test]
+    fn the_projects_extra_dirs_are_writable_roots() {
+        let options = Options {
+            approval_mode: Some("auto-edit".to_string()),
+            dirs: vec![PathBuf::from("/work/api")],
+            ..Options::default()
+        };
+        let mut c = Codex::new(Path::new("/work/app"), &options);
+        let turn: Value = serde_json::from_str(&c.turn_start(Vec::new())).unwrap();
+        assert_eq!(
+            turn["params"]["sandboxPolicy"]["writableRoots"],
+            json!(["/work/api"])
+        );
+        let args: Vec<String> = tui(Some("t-1"), &options)
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert!(args.join(" ").contains("--add-dir /work/api"), "{args:?}");
+    }
 }

crates/daemon/src/engines/mod.rs

@@ -85,6 +85,9 @@ pub struct Options {
     pub fast: bool,
     /// Claude: show thinking summaries (Some(false) hides them).
     pub thinking: Option<bool>,
+    /// Claude / Codex: directories besides `cwd` the engine may work in (the
+    /// project's extra directories; set by `spawn`, never by a client).
+    pub dirs: Vec<PathBuf>,
 }
 
 impl Options {
@@ -120,6 +123,7 @@ impl Options {
             effort: text("effort"),
             fast: value["fast"] == true,
             thinking: value["thinking"].as_bool(),
+            dirs: Vec::new(),
         }
     }
 
@@ -527,6 +531,10 @@ pub fn spawn(
     options: Options,
     transcript: Vec<Value>,
 ) -> Result<(String, Sender<Value>, u64), String> {
+    let options = Options {
+        dirs: crate::projects::extra_dirs(&hub, &cwd),
+        ..options
+    };
     let (command, gateway_key) = command(kind, id.as_deref().unwrap_or_default(), &options)?;
     let process = match Process::spawn(command, &cwd) {
         Ok(process) => process,
@@ -724,6 +732,7 @@ impl Session<'_> {
                     next.env = options.env.clone();
                     next.gateway = next.gateway.or(options.gateway);
                     next.approval_mode = next.approval_mode.or(options.approval_mode.clone());
+                    next.dirs = crate::projects::extra_dirs(self.hub, &self.cwd);
                     current = next.clone();
                     process.stop();
                     let id = self.id.clone().unwrap_or_default();

crates/daemon/src/hub.rs

@@ -118,6 +118,7 @@ impl Hub {
         let requirements = crate::requirements::Requirements::load(
             store.dir(),
             uploads.dir().join("requirements"),
+            &store.workspaces(),
         );
         Arc::new_cyclic(|me| Self {
             me: me.clone(),