From cb4c64533a9d26a388bb99cb731bd1c8e756fbee Mon Sep 17 00:00:00 2001 From: blockmandev <194144408+blockmandev@users.noreply.github.com> Date: Sun, 15 Nov 2026 12:34:41 -0600 Subject: [PATCH] Audit findings: toolbox gates and text dispatch split out, decide_and_run as named steps The code auditor's four approved findings: - toolbox/mod.rs was 2680 lines (limit 2500); it is 2375. The permission gates (the rules, the mode, the person to ask, the memory engine) moved unchanged to toolbox/gates.rs, and the text tools' dispatch to toolbox/dispatch.rs. - decide_and_run was 266 lines. It is now the gate sequence alone, each gate a named step: admit (the free checks), guard_protected, announce_or_refuse, tell_guards_said_yes and with_guidance. The order is unchanged. - dispatch_text had a complexity of 38. It is now three tables by family (file, session, memory tools) and the modules that own the rest; the shell, document conversion and recorder arms are helpers of their own. - fake_agy_child (test) was 102 lines: its no-server answer, the server start and the JSON-RPC pipe are helpers. cargo clippy --all-targets: clean. cargo test --lib: 2284 passed, 0 failed. --- src/agent/agy/bridged_tests.rs | 145 +++++---- src/toolbox/dispatch.rs | 201 +++++++++++++ src/toolbox/gates.rs | 296 +++++++++++++++++++ src/toolbox/mod.rs | 523 +++++++-------------------------- 4 files changed, 698 insertions(+), 467 deletions(-) create mode 100644 src/toolbox/dispatch.rs create mode 100644 src/toolbox/gates.rs diff --git a/src/agent/agy/bridged_tests.rs b/src/agent/agy/bridged_tests.rs index 4e9c598..4038c87 100644 --- a/src/agent/agy/bridged_tests.rs +++ b/src/agent/agy/bridged_tests.rs @@ -436,67 +436,19 @@ fn step(index: u64, kind: &str, extra: &serde_json::Value) -> serde_json::Value /// handed, then ends the turn with a result line. #[test] fn fake_agy_child() { - use std::io::Write as _; let Some(dir) = std::env::var_os(FAKE_AGY) else { return; }; let dir = PathBuf::from(dir); - let say = |line: serde_json::Value| println!("{line}"); say( serde_json::json!({"event":"init","conversation_id":"fake-conv","init":{"tools":["run_command","invoke_subagent"]}}), ); let hooks_by = std::env::var(HOOKS_BY_ENV).unwrap_or_default(); let result = serde_json::json!({"event":"result","result":{"conversation_id":"fake-conv","status":"SUCCESS","usage":{"input_tokens":1,"output_tokens":1}}}); - if let Ok(how) = std::fs::read_to_string(dir.join(NO_SERVER)) { - if how == "error" { - // As agy refuses a model it does not know: at once, no server. - say( - serde_json::json!({"event":"result","result":{"conversation_id":"","status":"ERROR","error":"model x is not recognized"}}), - ); - std::process::exit(1); - } - say(step( - 1, - "agent_response", - &serde_json::json!({"text_delta": "no tools"}), - )); - say(result); - std::process::exit(0); - } - // The one agent file in the folder it was pointed at: this binary's. - let agent = std::fs::read_dir(dir.join("agents")) - .expect("agents folder") - .filter_map(Result::ok) - .map(|e| e.path()) - .find(|p| p.extension().is_some_and(|x| x == "md")) - .expect("an agent file"); - let file = std::fs::read_to_string(agent).expect("agent file"); - let (command, args) = server_in(&file); - let mut server = std::process::Command::new(&command) - .args(&args) - .stdin(Stdio::piped()) - .stdout(Stdio::piped()) - .spawn() - .expect("start the tool server"); - let mut to = server.stdin.take().expect("stdin"); - let mut from = BufReader::new(server.stdout.take().expect("stdout")); - let mut ask = |id: u64, method: &str, params: serde_json::Value| -> serde_json::Value { - let request = serde_json::json!({"jsonrpc":"2.0","id":id,"method":method,"params":params}); - writeln!(to, "{request}").expect("send"); - to.flush().expect("flush"); - loop { - let mut line = String::new(); - if from.read_line(&mut line).expect("read") == 0 { - panic!("the tool server went away"); - } - // The test harness's own banner is not a reply. - if let Ok(reply) = serde_json::from_str::(&line) { - if reply["id"] == id { - return reply; - } - } - } - }; + answer_without_a_server(&dir, &result); + let mut server = start_agent_files_server(&dir); + let mut mcp = McpPipe::of(&mut server); + let mut ask = |id: u64, method: &str, params: serde_json::Value| mcp.ask(id, method, params); ask( 0, "initialize", @@ -527,7 +479,8 @@ fn fake_agy_child() { "output": reply["result"]["content"][0]["text"]}}), )); } - drop(to); + // Its stdin closed, the server ends. + drop(mcp); let _ = server.wait(); say(step( 9, @@ -538,6 +491,92 @@ fn fake_agy_child() { std::process::exit(0); } +/// One line of [`fake_agy_child`]'s output, as agy prints them. +fn say(line: serde_json::Value) { + println!("{line}"); +} + +/// When the test asked [`fake_agy_child`] to start no server (a `NO_SERVER` +/// file in `dir`): it ends the turn without tools, or — the file saying +/// `error` — refuses at once as agy refuses a model it does not know. Returns +/// only when there is no such file. +fn answer_without_a_server(dir: &Path, result: &serde_json::Value) { + let Ok(how) = std::fs::read_to_string(dir.join(NO_SERVER)) else { + return; + }; + if how == "error" { + // As agy refuses a model it does not know: at once, no server. + say( + serde_json::json!({"event":"result","result":{"conversation_id":"","status":"ERROR","error":"model x is not recognized"}}), + ); + std::process::exit(1); + } + say(step( + 1, + "agent_response", + &serde_json::json!({"text_delta": "no tools"}), + )); + say(result.clone()); + std::process::exit(0); +} + +/// The MCP server named by the one agent file in `dir/agents` — this +/// binary's — started with [`fake_agy_child`]'s own environment, as agy +/// starts it. +fn start_agent_files_server(dir: &Path) -> std::process::Child { + // The one agent file in the folder it was pointed at: this binary's. + let agent = std::fs::read_dir(dir.join("agents")) + .expect("agents folder") + .filter_map(Result::ok) + .map(|e| e.path()) + .find(|p| p.extension().is_some_and(|x| x == "md")) + .expect("an agent file"); + let file = std::fs::read_to_string(agent).expect("agent file"); + let (command, args) = server_in(&file); + std::process::Command::new(&command) + .args(&args) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .spawn() + .expect("start the tool server") +} + +/// JSON-RPC over a started server's stdio, one request at a time, as +/// [`fake_agy_child`] talks to it. Dropped, it closes the server's stdin. +struct McpPipe { + to: std::process::ChildStdin, + from: BufReader, +} + +impl McpPipe { + fn of(server: &mut std::process::Child) -> Self { + Self { + to: server.stdin.take().expect("stdin"), + from: BufReader::new(server.stdout.take().expect("stdout")), + } + } + + /// Send request `id` and wait for the reply with that `id`. + fn ask(&mut self, id: u64, method: &str, params: serde_json::Value) -> serde_json::Value { + use std::io::Write as _; + let request = serde_json::json!({"jsonrpc":"2.0","id":id,"method":method,"params":params}); + writeln!(self.to, "{request}").expect("send"); + self.to.flush().expect("flush"); + loop { + let mut line = String::new(); + if self.from.read_line(&mut line).expect("read") == 0 { + panic!("the tool server went away"); + } + // The test harness's own banner is not a reply. + if let Ok(reply) = serde_json::from_str::(&line) { + if reply["id"] == id { + return reply; + } + } + } + } +} + /// A script at `path` that runs this test binary's `test` with `marker` set /// to `value`, first recording its own arguments to `records_argv` when /// given: NUL-separated on Unix (`printf '%s\0' "$@"`), as cmd's `%*` on diff --git a/src/toolbox/dispatch.rs b/src/toolbox/dispatch.rs new file mode 100644 index 0000000..48ff32e --- /dev/null +++ b/src/toolbox/dispatch.rs @@ -0,0 +1,201 @@ +//! The tools whose answer is text alone, by family. +//! +//! Wired to: [`Toolbox::dispatch_text`] is reached from `Toolbox::dispatch` +//! (`toolbox/mod.rs`) once every gate has passed (`Toolbox::decide_and_run`, +//! the same file). Siblings that also run a tool, by other routes and from +//! the same `dispatch`, which tries them first: `Screenshot` and `RenderPdf` +//! through the headless browser (`toolbox/browser.rs`, `toolbox/pdf.rs`), the +//! desktop's tools (`Toolbox::run_desktop`) and the client's MCP servers' +//! (`Toolbox::run_client_tool`), both in `toolbox/mod.rs`. + +use super::*; + +impl Toolbox { + /// The tools whose answer is text alone, reached from `Toolbox::dispatch`. + /// + /// Every such tool has one arm in one of three tables, by family — the + /// file tools ([`Self::file_tool`]), the session's own + /// ([`Self::session_tool`]) and the memory's ([`Self::memory_tool`]) — + /// and a tool none of them names is asked of the modules that own their + /// tools ([`Self::tool_elsewhere`]). The tables name distinct tools, so + /// their order decides nothing; `tests.rs` asserts every advertised tool + /// runs. + pub(super) fn dispatch_text( + &self, + call_id: &str, + name: &str, + input: &Value, + ) -> Result { + // The file and shell tools parse their own JSON from a string, which is + // the interface they were written to; re-serialising here keeps that + // contract rather than rewriting six working implementations. + let raw = input.to_string(); + let ws = self.root_of_call(name, input); + self.file_tool(name, ws, &raw, input) + .or_else(|| self.session_tool(call_id, name, ws, &raw, input)) + .or_else(|| self.memory_tool(call_id, name, ws, &raw, input)) + .unwrap_or_else(|| self.tool_elsewhere(name, input)) + } + + /// The workspace, or the added directory the call names a path in — + /// and for `Read` alone, a folder only it may open. + fn root_of_call(&self, name: &str, input: &Value) -> &Path { + if name == READ { + self.read_root_for(input) + } else if matches!( + name, + WRITE | EDIT | GLOB | GREP | MULTI_EDIT | NOTEBOOK_EDIT | LS | OUTLINE + ) { + self.root_for(input) + } else { + self.workspace.as_path() + } + } + + /// [`Self::dispatch_text`]'s file tools; `None` for any other name. + fn file_tool( + &self, + name: &str, + ws: &Path, + raw: &str, + input: &Value, + ) -> Option> { + Some(match name { + READ => crate::tools::file_ops::read_file(ws, raw).map_err(|e| e.to_string()), + WRITE => crate::tools::file_ops::write_file(ws, raw).map_err(|e| e.to_string()), + EDIT => crate::tools::file_ops::edit_file(ws, raw).map_err(|e| e.to_string()), + MULTI_EDIT => edits::multi_edit(ws, input), + NOTEBOOK_EDIT => edits::notebook_edit(ws, input), + APPLY_PATCH => edits::apply_patch(input, &|path| self.resolve(path)), + LS => listing::list(ws, input), + GLOB => crate::tools::search::glob_search(ws, input), + GREP => crate::tools::search::grep_search(ws, input), + OUTLINE => outline::run(ws, input), + CONVERT_DOCUMENT => self.convert_document(input), + DIAGNOSTICS => checks::diagnostics(ws, input, &|path| self.resolve(path)), + _ => return None, + }) + } + + /// [`Self::dispatch_text`]'s session tools — the shell, the todo list, + /// skills, subagents and questions; `None` for any other name. + fn session_tool( + &self, + call_id: &str, + name: &str, + ws: &Path, + raw: &str, + input: &Value, + ) -> Option> { + Some(match name { + BASH => self.run_bash(call_id, ws, raw, input), + BASH_OUTPUT => shell::output(&self.state, input), + KILL_SHELL => shell::kill(&self.state, input), + TODO_WRITE => todo::write(&mut self.state.todos(), input), + SKILL => self.read_skill(input), + AGENT => self.run_subagent(input), + ASK_USER_QUESTION => self.ask_here(input), + _ => return None, + }) + } + + /// [`Self::dispatch_text`]'s memory tools — verify, recall, the recorder + /// and the brief; `None` for any other name. + fn memory_tool( + &self, + call_id: &str, + name: &str, + ws: &Path, + raw: &str, + input: &Value, + ) -> Option> { + Some(match name { + crate::verify::VERIFY_TOOL => crate::verify::run_tool(ws), + crate::verify::PLAN_TOOL => Ok(crate::verify::run_plan_tool(ws)), + crate::recall::INDEX_TOOL => crate::recall::run_index_tool(raw, ws), + crate::recall::GET_TOOL => crate::recall::run_get_tool(raw), + crate::recall::TIMELINE_TOOL => crate::recall::run_timeline_tool(raw), + crate::recorder::LOOKUP_TOOL => self.lookup_recorded(call_id, ws, input), + crate::brief::SAVE_TOOL => self.save_brief(raw), + crate::brief_read::READ_TOOL => crate::brief_read::run(ws), + _ => return None, + }) + } + + /// A tool no table of [`Self::dispatch_text`] names, asked of the modules + /// that own their tools, in order: knowledge, the session record, the web + /// (with the headless browser when one is installed) and the team. + fn tool_elsewhere(&self, other: &str, input: &Value) -> Result { + // The page's script, run by the headless browser, for a WebFetch + // that needs it — when the browser is installed. + let render = |url: &str| match self.browser() { + Some(bin) => browser::render_html(bin, url, self.filter_env), + None => Err("no headless browser is installed".to_string()), + }; + let render: Option> = self.browser().is_some().then_some(&render); + crate::knowledge::handle_tool( + other, + input, + &crate::knowledge::CodeContext { + cwd: &self.workspace, + session: &self.session, + resolve: &|path| self.resolve(path), + }, + ) + .or_else(|| { + crate::session_record::handle_tool( + other, + input, + &crate::session_record::Record { + session: &self.session, + workspace: &self.workspace, + }, + ) + }) + .or_else(|| crate::web::handle_tool(other, input, render)) + .or_else(|| self.team.handle(other, input)) + .unwrap_or_else(|| Err(format!("there is no tool called `{other}`"))) + } + + /// `ConvertDocument`, when LibreOffice was found. + fn convert_document(&self, input: &Value) -> Result { + match self.soffice() { + Some(soffice) => { + convert::run(soffice, input, self.filter_env, &|path| self.resolve(path)) + } + None => Err("LibreOffice was not found".to_string()), + } + } + + /// `Bash`: started as a job when it asks to run in the background + /// (`toolbox/shell.rs`), otherwise run here (`Toolbox::run_shell`). + fn run_bash( + &self, + call_id: &str, + ws: &Path, + raw: &str, + input: &Value, + ) -> Result { + if input.get("run_in_background").and_then(Value::as_bool) == Some(true) { + return shell::start(&self.state, ws, input, &self.sandbox()?); + } + // A write through the shell is credited to this agent: the + // engine's window around the command (`shell_window`). + let command = input.get("command").and_then(Value::as_str).unwrap_or(""); + self.shell_window("begin", command, call_id); + let ran = self.run_shell(call_id, ws, raw); + self.shell_window("end", command, call_id); + ran + } + + /// The recorder's lookup tool; the watch, if there is one, is told + /// whether the recorder had the call. + fn lookup_recorded(&self, call_id: &str, ws: &Path, input: &Value) -> Result { + crate::recorder::run_lookup_tool(ws, input).map(|found| { + if let Some(watch) = &self.watch { + watch.recorded(call_id, found.hit, found.observations); + } + found.text + }) + } +} diff --git a/src/toolbox/gates.rs b/src/toolbox/gates.rs new file mode 100644 index 0000000..11f2a71 --- /dev/null +++ b/src/toolbox/gates.rs @@ -0,0 +1,296 @@ +//! The permission gates a call passes before it runs: the settings' rules, the +//! session's mode, the person to ask, and the memory engine. +//! +//! Wired to: every function here is called from [`Toolbox::decide_and_run`] +//! (`toolbox/mod.rs`), in that order — the rules' deny first, then the mode +//! (with the rules' ask and allow), then the operator's pre-tool hook, then +//! the engine. Siblings that also refuse a call, by other routes and in the +//! same function: the agent's tool list (`Toolbox::allows`), the schema check +//! (`toolbox/validate.rs`), the command's allowed-tools +//! (`SessionTools::turn_allowlist`), the guards on protected paths +//! (`Toolbox::refused` and `Toolbox::ask_protected`) and the operator's hooks +//! (`Toolbox::operator_hook_before`), all in `toolbox/mod.rs`. + +use super::*; + +/// What the memory engine decided about one call, before it runs. +pub(super) enum Gate { + /// Run it; `context` is guidance for this action, handed to the model with + /// the result. + Run { context: Option }, + /// Do not run it; the model is told why, as an error. + Refused(String), + /// A question the owner already answered in their app: the answer IS the + /// result, and it is not an error. + Answered(String), + /// The recorder already ran this exact call and served its recorded + /// output ([`crate::hooks::engine::is_served`]): that output IS the + /// result. It arrives shaped like a refusal, and handed back as one it + /// read as a failed call — so the model retried, or worked around a tool + /// that had in fact answered. + Served(String), +} + +impl Toolbox { + /// What the settings' permission rules say about this call, if anything. + pub(super) fn rule_verdict( + &self, + name: &str, + input: &Value, + ) -> Option { + if self.rules.is_empty() { + return None; + } + self.rules + .decide(name, &self.rule_subject(name, input), &self.rule_context()) + } + + /// What a rule's specifier is matched against for this call: the command, + /// the paths or the address it names. + pub(super) fn rule_subject( + &self, + name: &str, + input: &Value, + ) -> crate::permissions::rules::Subject { + use crate::permissions::rules::Subject; + let text = |key: &str| { + input + .get(key) + .and_then(Value::as_str) + .unwrap_or_default() + .to_string() + }; + match name { + BASH => Subject::Command(text("command")), + // A search or a listing with no `path` covers the workspace. + READ | WRITE | EDIT | MULTI_EDIT | NOTEBOOK_EDIT | LS | OUTLINE | GLOB | GREP => { + let path = text("path"); + Subject::Paths(vec![if path.is_empty() { + ".".to_string() + } else { + path + }]) + } + APPLY_PATCH | CONVERT_DOCUMENT | RENDER_PDF => { + let mut paths = self.changed_paths(name, input).unwrap_or_default(); + if let Some(read) = input.get("path").and_then(Value::as_str) { + paths.push(read.to_string()); + } + Subject::Paths(paths) + } + crate::web::FETCH_TOOL => Subject::Url(text("url")), + _ => Subject::None, + } + } + + /// Where a rule's relative paths are resolved, and what `~` is. + pub(super) fn rule_context(&self) -> crate::permissions::rules::PathContext { + crate::permissions::rules::PathContext { + workspace: self.workspace.clone(), + home: crate::admin::home_dir(), + } + } + + /// Whether the session's permission mode, and the settings' `ask` and + /// `allow` rules, let this call run (a `deny` rule was applied before). + /// + /// Decided by the call's [`Reach`]: a tool that only observes runs under + /// every mode; everything else is refused read-only and asked about under + /// `prompt`. A subagent is refused wherever the mode restricts anything, + /// because the agent it would start does not carry this mode and could do + /// what this one may not. + /// + /// The rules come after those two refusals and before the rest: read-only + /// is a promise that nothing changes, which no allow rule breaks. Past it, + /// an `ask` rule asks the person, whatever the mode — even for a tool that + /// only observes — and an `allow` rule runs the call without the `prompt` + /// mode's question. + pub(super) fn mode_allows( + &self, + call_id: &str, + name: &str, + input: &Value, + reach: Reach, + ruled: Option<&crate::permissions::rules::Verdict>, + ) -> Result<(), String> { + use crate::permissions::rules::Effect; + use crate::permissions::PermissionMode; + if let Some(mode) = self.mode { + let restricted = matches!(mode, PermissionMode::ReadOnly | PermissionMode::Prompt); + if name == AGENT && restricted { + return Err(format!( + "this session is {}, and a subagent would not be held to that. Do the \ + work here instead.", + mode.as_str() + )); + } + if mode == PermissionMode::ReadOnly && !reach.only_observes() { + return Err(format!( + "NOT RUN — this session is read-only, and {name} changes the workspace or \ + runs code. Describe the change instead of making it." + )); + } + } + if let Some(verdict) = ruled { + match verdict.effect { + Effect::Ask => { + let reason = format!("the {} asks before this {name}", verdict.describe()); + return self.confirm_with_person(call_id, name, input, &reason); + } + Effect::Allow => { + crate::trace!("tool", "{name} allowed by {}", verdict.describe()); + return Ok(()); + } + // Applied before this was asked. + Effect::Deny => {} + } + } + if reach.only_observes() { + return Ok(()); + } + match self.mode { + Some(PermissionMode::Prompt) => { + let reason = format!("the session asks before every {name}"); + self.confirm_with_person(call_id, name, input, &reason) + } + Some( + PermissionMode::ReadOnly + | PermissionMode::WorkspaceWrite + | PermissionMode::DangerFullAccess + | PermissionMode::Allow, + ) + | None => Ok(()), + } + } + + /// Put this call to the person at the session, for `reason`. Refused when + /// nobody can be asked. + pub(super) fn confirm_with_person( + &self, + call_id: &str, + name: &str, + input: &Value, + reason: &str, + ) -> Result<(), String> { + let shown = self.event_input(name, input); + let ask = crate::hooks::engine::Ask { + call_id, + tool_name: name, + tool_input: &shown, + reason, + }; + let stopped = || { + self.cancel + .as_ref() + .is_some_and(crate::runtime::cancel::CancelToken::is_cancelled) + }; + let answer = self + .prompter + .as_ref() + .and_then(|p| p.confirm(&ask, &stopped)); + crate::telemetry::permission_prompt( + name, + match &answer { + Some(crate::hooks::engine::Verdict::Allow) => "allow", + Some(crate::hooks::engine::Verdict::Deny(_)) => "deny", + None => "unanswered", + }, + ); + match answer { + Some(crate::hooks::engine::Verdict::Allow) => Ok(()), + Some(crate::hooks::engine::Verdict::Deny(why)) => Err(why), + None => Err(format!("NOT RUN — {reason}, and nobody could be asked.")), + } + } + + /// What the memory engine says about this call. + /// + /// # The failure policy (the owner's decision) + /// + /// When the engine cannot decide — it is missing where it was named, it + /// crashed, it ran past its bound — a call that changes or runs something + /// ([`Reach::fails_closed`]) is REFUSED: the guard is a safety function, + /// and a change made because the guard was down is the one it exists to + /// stop. A call that only observes runs, traced. The same rule as the + /// guards file (`Toolbox::refused`, `toolbox/mod.rs`): an unreadable guard + /// must not read as no guard. + pub(super) fn engine_gate( + &self, + call_id: &str, + name: &str, + input: &Value, + reach: Reach, + ) -> Gate { + let gate = self.engine_gate_inner(call_id, name, input, reach); + if self.engine.is_some() { + let (allowed, reason) = match &gate { + Gate::Run { .. } => (true, None), + Gate::Refused(why) => (false, Some(why.clone())), + // The owner answered a question in the app, or the recorder + // served the call: nothing was refused, and that is the result. + Gate::Answered(_) | Gate::Served(_) => (true, None), + }; + self.tell_decided( + call_id, + crate::watch::Decision { + by: crate::watch::Decider::Engine, + allowed, + rule: None, + path: None, + reason: reason + .map(|why| crate::text::truncate(&why, MAX_DECISION_REASON_CHARS)), + }, + ); + } + gate + } + + /// [`Self::engine_gate`]'s decision, before it is told. + fn engine_gate_inner(&self, call_id: &str, name: &str, input: &Value, reach: Reach) -> Gate { + let Some(engine) = &self.engine else { + return Gate::Run { context: None }; + }; + let shown = self.event_input(name, input); + let cancel = self.cancel.as_ref(); + match engine.pre_tool(&self.session, &self.workspace, name, &shown, cancel) { + crate::hooks::engine::PreTool::Allow { context } => Gate::Run { context }, + // Exit 2 on a question is the owner's ANSWER, given in the app. + crate::hooks::engine::PreTool::Block(said) if name == ASK_USER_QUESTION => { + Gate::Answered(said) + } + // Never for a write: the engine serves only reads (`Read`, recall, + // and a one-file `cat`/`head`/`tail`/`sed -n` through the shell), + // and a "served" answer to a write would read as a write that + // landed when none was made. + crate::hooks::engine::PreTool::Block(recorded) + if reach != Reach::Change && crate::hooks::engine::is_served(&recorded) => + { + Gate::Served(recorded) + } + crate::hooks::engine::PreTool::Block(reason) => Gate::Refused(reason), + crate::hooks::engine::PreTool::Ask { reason, context } => { + let ask = crate::hooks::engine::Ask { + call_id, + tool_name: name, + tool_input: &shown, + reason: &reason, + }; + let prompter = self.prompter.as_deref(); + match engine.settle(&ask, &self.session, &self.workspace, prompter, cancel) { + crate::hooks::engine::Verdict::Allow => Gate::Run { context }, + crate::hooks::engine::Verdict::Deny(why) => Gate::Refused(why), + } + } + crate::hooks::engine::PreTool::Failed(why) if reach.fails_closed() => { + Gate::Refused(format!( + "NOT RUN — the Incord guard could not decide on this {name}, and a change \ + is not made unguarded: {why}" + )) + } + crate::hooks::engine::PreTool::Failed(why) => { + crate::trace!("tool", "{name} runs unguarded, the engine failed: {why}"); + Gate::Run { context: None } + } + } + } +} diff --git a/src/toolbox/mod.rs b/src/toolbox/mod.rs index 6b0970a..f529950 100644 --- a/src/toolbox/mod.rs +++ b/src/toolbox/mod.rs @@ -58,7 +58,9 @@ mod client_servers; mod code_edits; mod convert; mod desktop; +mod dispatch; mod edits; +mod gates; mod image; mod listing; mod mcp_client; @@ -76,6 +78,7 @@ pub use code_edits::{ CodeEdits, EditLedger, EngineLedger, LedgerError, Route as EditRoute, ROOT_AGENT, }; pub use desktop::DesktopSetup; +use gates::Gate; pub use image::{Image, ImageFormat, ToolOutput, MAX_IMAGES_PER_RESULT, MAX_IMAGE_EDGE}; pub(crate) use todo::{parse_todos, Priority, TodoStatus}; @@ -460,24 +463,6 @@ impl SessionTools { } } -/// What the memory engine decided about one call, before it runs. -enum Gate { - /// Run it; `context` is guidance for this action, handed to the model with - /// the result. - Run { context: Option }, - /// Do not run it; the model is told why, as an error. - Refused(String), - /// A question the owner already answered in their app: the answer IS the - /// result, and it is not an error. - Answered(String), - /// The recorder already ran this exact call and served its recorded - /// output ([`crate::hooks::engine::is_served`]): that output IS the - /// result. It arrives shaped like a refusal, and handed back as one it - /// read as a failed call — so the model retried, or worked around a tool - /// that had in fact answered. - Served(String), -} - /// The most of the engine's reason a decision carries to a watch, in /// characters. The whole reason is still the call's result. const MAX_DECISION_REASON_CHARS: usize = 500; @@ -1750,13 +1735,17 @@ impl Toolbox { result } - /// Every gate, then the tool: [`Self::run_call`]'s body. - fn decide_and_run( + /// The checks that cost nothing and ask nobody, first of + /// [`Self::decide_and_run`]'s gates: the tool exists, this agent may use + /// it, this session offers it, its input fits its schema, the command + /// that started the turn allows it, and no permission rule denies it. + /// Returns its reach and the rules' verdict, weighed with the mode later + /// (`Toolbox::mode_allows`, `toolbox/gates.rs`). + fn admit( &self, - call_id: &str, name: &str, input: &Value, - ) -> Result { + ) -> Result<(Reach, Option), String> { // A name nobody classified is not a tool: refused before a guard, a // person or the engine is asked about it. A tool of the client's MCP // servers RUNS something nobody here can inspect, so it is `run`: @@ -1835,9 +1824,18 @@ impl Toolbox { )); } } - // BEFORE the call, not after. The sentinel that watches the tree can - // only report a write that already happened; a protected path has to be - // refused while refusing it still means something. + Ok((reach, ruled)) + } + + /// The guards on protected paths, second of [`Self::decide_and_run`]'s + /// gates: a write to a protected path is refused, or put to a person + /// (`Toolbox::ask_protected`). `Ok(true)` when a person allowed it, so the + /// mode does not ask the same person the same thing again. + /// + /// BEFORE the call, not after. The sentinel that watches the tree can + /// only report a write that already happened; a protected path has to be + /// refused while refusing it still means something. + fn guard_protected(&self, call_id: &str, name: &str, input: &Value) -> Result { // Set when a person allowed a protected write, so a session that asks // before every change does not ask the same person the same thing twice. let mut confirmed = false; @@ -1893,6 +1891,29 @@ impl Toolbox { } } } + Ok(confirmed) + } + + /// Every gate, then the tool: [`Self::run_call`]'s body. + /// + /// The order is the contract, each gate a step of its own: the free + /// checks ([`Self::admit`]), the guards on protected paths + /// ([`Self::guard_protected`]), the session's mode and the rules' ask and + /// allow (`Toolbox::mode_allows`), the operator's pre-tool hook + /// ([`Self::operator_hook_before`]), the memory engine + /// (`Toolbox::engine_gate`; both in `toolbox/gates.rs`), and the edit check + /// ([`Self::announce_or_refuse`]). Then the tool runs ([`Self::dispatch`]), + /// its writes are settled, the engine and the operator's post-tool hook + /// are told, and what they said travels with the result + /// ([`Self::with_guidance`]). + fn decide_and_run( + &self, + call_id: &str, + name: &str, + input: &Value, + ) -> Result { + let (reach, ruled) = self.admit(name, input)?; + let confirmed = self.guard_protected(call_id, name, input)?; // The session's mode, before the engine: it is decided here, costs // nothing, and a call it refuses need not cost an engine process. A // call a person already allowed is not asked about again: it is never @@ -1933,43 +1954,8 @@ impl Toolbox { // The edit check, last: every gate above refuses a call for reasons // of its own, and a write announced to the engine and then refused // by one of them would leave a mark for a write that never came. - let announced = if reach == Reach::Change { - match self.announce_writes(call_id, name, input) { - Ok(announced) => announced, - Err(refusal) => { - self.tell_decided( - call_id, - crate::watch::Decision { - by: crate::watch::Decider::Engine, - allowed: false, - rule: None, - path: None, - reason: Some(crate::text::truncate( - &refusal, - MAX_DECISION_REASON_CHARS, - )), - }, - ); - return Err(refusal); - } - } - } else { - code_edits::Announced::default() - }; - // With no engine, the guards had the last word on a call they look - // at, and it was yes. - if self.engine.is_none() && Self::guarded(name) && self.guards.is_ok() { - self.tell_decided( - call_id, - crate::watch::Decision { - by: crate::watch::Decider::Guards, - allowed: true, - rule: None, - path: None, - reason: None, - }, - ); - } + let announced = self.announce_or_refuse(call_id, name, input, reach)?; + self.tell_guards_said_yes(call_id, name); // Every gate passed: the call RUNS, whatever it then returns. CALL_RAN.with(|ran| ran.set(true)); let outcome = self.dispatch(call_id, name, input, reach); @@ -1991,6 +1977,67 @@ impl Toolbox { // and the pre-tool commands printed travels with the result. let mut said_hooks = said_before; said_hooks.extend(self.operator_hook_after(name, input, &outcome)); + Self::with_guidance(outcome, context, &said_hooks) + } + + /// The edit check, last of [`Self::decide_and_run`]'s gates: a call that + /// changes something announces its writes ([`Self::announce_writes`]); + /// when that refuses, the watch is told it was the engine's refusal and + /// the call is not run. A call of any other reach announces nothing. + fn announce_or_refuse( + &self, + call_id: &str, + name: &str, + input: &Value, + reach: Reach, + ) -> Result { + if reach != Reach::Change { + return Ok(code_edits::Announced::default()); + } + match self.announce_writes(call_id, name, input) { + Ok(announced) => Ok(announced), + Err(refusal) => { + self.tell_decided( + call_id, + crate::watch::Decision { + by: crate::watch::Decider::Engine, + allowed: false, + rule: None, + path: None, + reason: Some(crate::text::truncate(&refusal, MAX_DECISION_REASON_CHARS)), + }, + ); + Err(refusal) + } + } + } + + /// With no engine, the guards had the last word on a call they look at, + /// and it was yes: the watch is told so ([`Self::tell_decided`]). + fn tell_guards_said_yes(&self, call_id: &str, name: &str) { + if self.engine.is_none() && Self::guarded(name) && self.guards.is_ok() { + self.tell_decided( + call_id, + crate::watch::Decision { + by: crate::watch::Decider::Guards, + allowed: true, + rule: None, + path: None, + reason: None, + }, + ); + } + } + + /// The call's result with what travels with it: the operator's hooks' + /// lines (`said_hooks`), after the engine's guidance for this action + /// (`context`), appended to the result or the error alike — the one place + /// the model reads them at the moment they apply. + fn with_guidance( + outcome: Result, + context: Option, + said_hooks: &[String], + ) -> Result { let context = match (context, said_hooks.is_empty()) { (context, true) => context, (context, false) => { @@ -2113,257 +2160,6 @@ impl Toolbox { } } - /// What the settings' permission rules say about this call, if anything. - fn rule_verdict( - &self, - name: &str, - input: &Value, - ) -> Option { - if self.rules.is_empty() { - return None; - } - self.rules - .decide(name, &self.rule_subject(name, input), &self.rule_context()) - } - - /// What a rule's specifier is matched against for this call: the command, - /// the paths or the address it names. - fn rule_subject(&self, name: &str, input: &Value) -> crate::permissions::rules::Subject { - use crate::permissions::rules::Subject; - let text = |key: &str| { - input - .get(key) - .and_then(Value::as_str) - .unwrap_or_default() - .to_string() - }; - match name { - BASH => Subject::Command(text("command")), - // A search or a listing with no `path` covers the workspace. - READ | WRITE | EDIT | MULTI_EDIT | NOTEBOOK_EDIT | LS | OUTLINE | GLOB | GREP => { - let path = text("path"); - Subject::Paths(vec![if path.is_empty() { - ".".to_string() - } else { - path - }]) - } - APPLY_PATCH | CONVERT_DOCUMENT | RENDER_PDF => { - let mut paths = self.changed_paths(name, input).unwrap_or_default(); - if let Some(read) = input.get("path").and_then(Value::as_str) { - paths.push(read.to_string()); - } - Subject::Paths(paths) - } - crate::web::FETCH_TOOL => Subject::Url(text("url")), - _ => Subject::None, - } - } - - /// Where a rule's relative paths are resolved, and what `~` is. - fn rule_context(&self) -> crate::permissions::rules::PathContext { - crate::permissions::rules::PathContext { - workspace: self.workspace.clone(), - home: crate::admin::home_dir(), - } - } - - /// Whether the session's permission mode, and the settings' `ask` and - /// `allow` rules, let this call run (a `deny` rule was applied before). - /// - /// Decided by the call's [`Reach`]: a tool that only observes runs under - /// every mode; everything else is refused read-only and asked about under - /// `prompt`. A subagent is refused wherever the mode restricts anything, - /// because the agent it would start does not carry this mode and could do - /// what this one may not. - /// - /// The rules come after those two refusals and before the rest: read-only - /// is a promise that nothing changes, which no allow rule breaks. Past it, - /// an `ask` rule asks the person, whatever the mode — even for a tool that - /// only observes — and an `allow` rule runs the call without the `prompt` - /// mode's question. - fn mode_allows( - &self, - call_id: &str, - name: &str, - input: &Value, - reach: Reach, - ruled: Option<&crate::permissions::rules::Verdict>, - ) -> Result<(), String> { - use crate::permissions::rules::Effect; - use crate::permissions::PermissionMode; - if let Some(mode) = self.mode { - let restricted = matches!(mode, PermissionMode::ReadOnly | PermissionMode::Prompt); - if name == AGENT && restricted { - return Err(format!( - "this session is {}, and a subagent would not be held to that. Do the \ - work here instead.", - mode.as_str() - )); - } - if mode == PermissionMode::ReadOnly && !reach.only_observes() { - return Err(format!( - "NOT RUN — this session is read-only, and {name} changes the workspace or \ - runs code. Describe the change instead of making it." - )); - } - } - if let Some(verdict) = ruled { - match verdict.effect { - Effect::Ask => { - let reason = format!("the {} asks before this {name}", verdict.describe()); - return self.confirm_with_person(call_id, name, input, &reason); - } - Effect::Allow => { - crate::trace!("tool", "{name} allowed by {}", verdict.describe()); - return Ok(()); - } - // Applied before this was asked. - Effect::Deny => {} - } - } - if reach.only_observes() { - return Ok(()); - } - match self.mode { - Some(PermissionMode::Prompt) => { - let reason = format!("the session asks before every {name}"); - self.confirm_with_person(call_id, name, input, &reason) - } - Some( - PermissionMode::ReadOnly - | PermissionMode::WorkspaceWrite - | PermissionMode::DangerFullAccess - | PermissionMode::Allow, - ) - | None => Ok(()), - } - } - - /// Put this call to the person at the session, for `reason`. Refused when - /// nobody can be asked. - fn confirm_with_person( - &self, - call_id: &str, - name: &str, - input: &Value, - reason: &str, - ) -> Result<(), String> { - let shown = self.event_input(name, input); - let ask = crate::hooks::engine::Ask { - call_id, - tool_name: name, - tool_input: &shown, - reason, - }; - let stopped = || { - self.cancel - .as_ref() - .is_some_and(crate::runtime::cancel::CancelToken::is_cancelled) - }; - let answer = self - .prompter - .as_ref() - .and_then(|p| p.confirm(&ask, &stopped)); - crate::telemetry::permission_prompt( - name, - match &answer { - Some(crate::hooks::engine::Verdict::Allow) => "allow", - Some(crate::hooks::engine::Verdict::Deny(_)) => "deny", - None => "unanswered", - }, - ); - match answer { - Some(crate::hooks::engine::Verdict::Allow) => Ok(()), - Some(crate::hooks::engine::Verdict::Deny(why)) => Err(why), - None => Err(format!("NOT RUN — {reason}, and nobody could be asked.")), - } - } - - /// What the memory engine says about this call. - /// - /// # The failure policy (the owner's decision) - /// - /// When the engine cannot decide — it is missing where it was named, it - /// crashed, it ran past its bound — a call that changes or runs something - /// ([`Reach::fails_closed`]) is REFUSED: the guard is a safety function, - /// and a change made because the guard was down is the one it exists to - /// stop. A call that only observes runs, traced. The same rule as the - /// guards file above: an unreadable guard must not read as no guard. - fn engine_gate(&self, call_id: &str, name: &str, input: &Value, reach: Reach) -> Gate { - let gate = self.engine_gate_inner(call_id, name, input, reach); - if self.engine.is_some() { - let (allowed, reason) = match &gate { - Gate::Run { .. } => (true, None), - Gate::Refused(why) => (false, Some(why.clone())), - // The owner answered a question in the app, or the recorder - // served the call: nothing was refused, and that is the result. - Gate::Answered(_) | Gate::Served(_) => (true, None), - }; - self.tell_decided( - call_id, - crate::watch::Decision { - by: crate::watch::Decider::Engine, - allowed, - rule: None, - path: None, - reason: reason - .map(|why| crate::text::truncate(&why, MAX_DECISION_REASON_CHARS)), - }, - ); - } - gate - } - - /// [`Self::engine_gate`]'s decision, before it is told. - fn engine_gate_inner(&self, call_id: &str, name: &str, input: &Value, reach: Reach) -> Gate { - let Some(engine) = &self.engine else { - return Gate::Run { context: None }; - }; - let shown = self.event_input(name, input); - let cancel = self.cancel.as_ref(); - match engine.pre_tool(&self.session, &self.workspace, name, &shown, cancel) { - crate::hooks::engine::PreTool::Allow { context } => Gate::Run { context }, - // Exit 2 on a question is the owner's ANSWER, given in the app. - crate::hooks::engine::PreTool::Block(said) if name == ASK_USER_QUESTION => { - Gate::Answered(said) - } - // Never for a write: the engine serves only reads (`Read`, recall, - // and a one-file `cat`/`head`/`tail`/`sed -n` through the shell), - // and a "served" answer to a write would read as a write that - // landed when none was made. - crate::hooks::engine::PreTool::Block(recorded) - if reach != Reach::Change && crate::hooks::engine::is_served(&recorded) => - { - Gate::Served(recorded) - } - crate::hooks::engine::PreTool::Block(reason) => Gate::Refused(reason), - crate::hooks::engine::PreTool::Ask { reason, context } => { - let ask = crate::hooks::engine::Ask { - call_id, - tool_name: name, - tool_input: &shown, - reason: &reason, - }; - let prompter = self.prompter.as_deref(); - match engine.settle(&ask, &self.session, &self.workspace, prompter, cancel) { - crate::hooks::engine::Verdict::Allow => Gate::Run { context }, - crate::hooks::engine::Verdict::Deny(why) => Gate::Refused(why), - } - } - crate::hooks::engine::PreTool::Failed(why) if reach.fails_closed() => { - Gate::Refused(format!( - "NOT RUN — the Incord guard could not decide on this {name}, and a change \ - is not made unguarded: {why}" - )) - } - crate::hooks::engine::PreTool::Failed(why) => { - crate::trace!("tool", "{name} runs unguarded, the engine failed: {why}"); - Gate::Run { context: None } - } - } - } - /// `path` as an absolute path: a relative one is named under the /// workspace. fn absolute(&self, path: &str) -> String { @@ -2547,107 +2343,6 @@ impl Toolbox { }; ran.map_err(|e| e.to_string()) } - - /// The tools whose answer is text alone. - fn dispatch_text(&self, call_id: &str, name: &str, input: &Value) -> Result { - // The file and shell tools parse their own JSON from a string, which is - // the interface they were written to; re-serialising here keeps that - // contract rather than rewriting six working implementations. - let raw = input.to_string(); - // The workspace, or the added directory the call names a path in — - // and for `Read` alone, a folder only it may open. - let ws = if name == READ { - self.read_root_for(input) - } else if matches!( - name, - WRITE | EDIT | GLOB | GREP | MULTI_EDIT | NOTEBOOK_EDIT | LS | OUTLINE - ) { - self.root_for(input) - } else { - self.workspace.as_path() - }; - - let background = input.get("run_in_background").and_then(Value::as_bool) == Some(true); - // The page's script, run by the headless browser, for a WebFetch - // that needs it — when the browser is installed. - let render = |url: &str| match self.browser() { - Some(bin) => browser::render_html(bin, url, self.filter_env), - None => Err("no headless browser is installed".to_string()), - }; - let render: Option> = self.browser().is_some().then_some(&render); - match name { - READ => crate::tools::file_ops::read_file(ws, &raw).map_err(|e| e.to_string()), - WRITE => crate::tools::file_ops::write_file(ws, &raw).map_err(|e| e.to_string()), - EDIT => crate::tools::file_ops::edit_file(ws, &raw).map_err(|e| e.to_string()), - MULTI_EDIT => edits::multi_edit(ws, input), - NOTEBOOK_EDIT => edits::notebook_edit(ws, input), - APPLY_PATCH => edits::apply_patch(input, &|path| self.resolve(path)), - LS => listing::list(ws, input), - GLOB => crate::tools::search::glob_search(ws, input), - GREP => crate::tools::search::grep_search(ws, input), - OUTLINE => outline::run(ws, input), - CONVERT_DOCUMENT => match self.soffice() { - Some(soffice) => { - convert::run(soffice, input, self.filter_env, &|path| self.resolve(path)) - } - None => Err("LibreOffice was not found".to_string()), - }, - BASH if background => shell::start(&self.state, ws, input, &self.sandbox()?), - BASH => { - // A write through the shell is credited to this agent: the - // engine's window around the command (`shell_window`). - let command = input.get("command").and_then(Value::as_str).unwrap_or(""); - self.shell_window("begin", command, call_id); - let ran = self.run_shell(call_id, ws, &raw); - self.shell_window("end", command, call_id); - ran - } - BASH_OUTPUT => shell::output(&self.state, input), - KILL_SHELL => shell::kill(&self.state, input), - TODO_WRITE => todo::write(&mut self.state.todos(), input), - DIAGNOSTICS => checks::diagnostics(ws, input, &|path| self.resolve(path)), - crate::verify::VERIFY_TOOL => crate::verify::run_tool(ws), - crate::verify::PLAN_TOOL => Ok(crate::verify::run_plan_tool(ws)), - crate::recall::INDEX_TOOL => crate::recall::run_index_tool(&raw, ws), - crate::recall::GET_TOOL => crate::recall::run_get_tool(&raw), - crate::recall::TIMELINE_TOOL => crate::recall::run_timeline_tool(&raw), - crate::recorder::LOOKUP_TOOL => { - crate::recorder::run_lookup_tool(ws, input).map(|found| { - if let Some(watch) = &self.watch { - watch.recorded(call_id, found.hit, found.observations); - } - found.text - }) - } - SKILL => self.read_skill(input), - AGENT => self.run_subagent(input), - ASK_USER_QUESTION => self.ask_here(input), - crate::brief::SAVE_TOOL => self.save_brief(&raw), - crate::brief_read::READ_TOOL => crate::brief_read::run(ws), - other => crate::knowledge::handle_tool( - other, - input, - &crate::knowledge::CodeContext { - cwd: &self.workspace, - session: &self.session, - resolve: &|path| self.resolve(path), - }, - ) - .or_else(|| { - crate::session_record::handle_tool( - other, - input, - &crate::session_record::Record { - session: &self.session, - workspace: &self.workspace, - }, - ) - }) - .or_else(|| crate::web::handle_tool(other, input, render)) - .or_else(|| self.team.handle(other, input)) - .unwrap_or_else(|| Err(format!("there is no tool called `{other}`"))), - } - } } #[cfg(test)]