Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 61 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ before it calls it done.
in to — `claude`, `codex` and `agy` — are used only as models, run headless on
your own subscriptions. The loop's tools, the permission checks, the undo
history, the memory hooks and the record of what happened are incode's own.
(Today that is fully true for `claude`; `codex` and `agy` still run their own
tools — see [Limits](#limits).)
(Today that is fully true for `claude`, and for `codex` when you opt in; `codex`
by default and `agy` still run their own tools — see [Limits](#limits).)

---

Expand Down Expand Up @@ -450,6 +450,56 @@ it sets; any other `id` adds an agent.
- An `id` holding `/` or `:` is skipped: those mark provider agents and role
qualifiers.

### The codex route: whose tools

By default `codex` runs its own tools (`exec_command`, `apply_patch`, …) and
incode watches the result afterwards. With `"codex_tools": "incode"` in
`admin.json` (or `INCODE_CODEX_TOOLS=incode`, which wins) it is driven like
`claude`: a model only, with every tool call run by incode. `incode --admin`
shows which is in force and where it was decided. It is opt-in until a turn with
a real model has been run this way; everything below was measured on codex 0.163.0
against a stand-in model endpoint, end to end through `incode -t`.

Each turn incode opens its tool bridge and starts `codex exec --json` with:

- `--ignore-user-config` — `~/.codex/config.toml` is not read (so no MCP server
you registered there is reachable); login still comes from `CODEX_HOME`. A
model provider set only in that file is not used on this route.
- its tools off: `features.shell_tool=false`, `features.view_image=false`,
`web_search="disabled"`, `features.goals=false`, `agents.enabled=false`,
`features.multi_agent=false`, `features.apps=false`, `features.plugins=false`,
`features.browser_use=false`, `features.computer_use=false`,
`features.image_generation=false`,
`tools.experimental_request_user_input.enabled=false`;
- `sandbox_mode="read-only"`, `approval_policy="never"`;
- one MCP server, `incode --tool-server`, given the bridge's address and token
through `env_vars` (codex passes a server only the variables it is told to),
approval mode `approve`, `required`, a one-hour call timeout, and its tools
listed directly rather than behind codex's tool search.

What is enforced there: every file, shell, web, team, desktop and sub-agent
call is incode's, so the guards, the [permission rules](#permission-rules), a
command's `allowed-tools`, the permission mode, your hooks, the memory engine
and the [OS sandbox](#the-os-sandbox) apply to it before it runs, and the
"not enforced" notice is not shown. What is not incode's:

- `apply_patch` stays on offer — codex has no switch for it (the model catalogue
decides). Under read-only + never codex rejects it before it runs ("patch
rejected: writing is blocked by read-only sandbox"), so it cannot write.
- The three MCP resource readers (`list_mcp_resources`, …) stay; they read only
what incode's server offers.
- On code-mode models (`gpt-5.6-terra`) incode's tools are reached through
codex's own `exec`, a JavaScript sandbox without file system or network that
calls them — each call still lands in incode.
- A project's own `.codex/config.toml` is outside `--ignore-user-config`;
codex loads it only for a project it trusts.
- Older codex: 0.145 has no `view_image` switch and lists incode's tools behind
its tool search; 0.153 has every switch above.

`agy` cannot be driven this way: it has no flag to switch its tools off, and
takes MCP servers only through a persistent `agy mcp add`, which would edit your
machine rather than one run.

### The API providers contract

```json
Expand Down Expand Up @@ -596,8 +646,9 @@ rule (`Bash(npm test:*)`, `Read`, `Edit(src/**)` — the grammar of
refused, with the list named to the model. A compound shell line is covered
only when every part is. Only that turn: the next one is unrestricted. It only
narrows — deny and ask rules, guards, the mode and hooks still apply. It binds
where incode runs the tools (the API route and Claude Code); on Codex and
Antigravity, which bring their own tools, the turn says it was not enforced.
where incode runs the tools (the API route, Claude Code, and Codex with
`codex_tools: "incode"`); on Codex's own tools and Antigravity, the turn says it
was not enforced.

A **plugin** is a folder in `~/.incode/plugins/<name>/` or
`.incode/plugins/<name>/` with a `plugin.toml` (`name`, `version`,
Expand Down Expand Up @@ -1237,6 +1288,7 @@ and `--admin` prints which layer decided each value.
| `sandbox` | `off` · `workspace-write` · `read-only`; unset follows the permission mode |
| `sandbox_network` | `allow` (default) · `deny` — see [the OS sandbox](#the-os-sandbox) |
| `sandbox_engine` · `sandbox_allow_hosts` · `sandbox_backend` | `builtin` (default) · `sbx`; under sbx, the hosts a command may reach and, on Windows, `native` · `wsl` · `auto` — see [the OS sandbox](#the-os-sandbox) |
| `codex_tools` | `own` (default) · `incode` — whose tools a `codex` model runs; see [the codex route](#the-codex-route-whose-tools) |
| `hooks` (also `desktop_hooks`) | Your `pre_tool_use` / `post_tool_use` commands, run for every tool. The event is JSON on stdin; exit 2 on a pre-tool command denies; bounded at 10 s |
| `desktop_limits` | The desktop's limits, each optional: `max_actions_per_minute` (120), `heartbeat_deadline_secs` (30), `tree_depth` (12), `tree_max_elements` (400), `journal_max_bytes` (262144), `xvfb_start_timeout_secs` (10), `clipboard_timeout_secs` (5), `accessibility_call_timeout_ms` (1000), `paste_restore_delay_ms` (500, how long the pasted text stays on the clipboard before the old one is put back), `settle_ms` (300, the pause before a `screenshot_after`), `max_scroll_steps` (50, wheel steps in one `scroll`), `tree_max_visited` (4000, elements one tree walk may visit), and `blocked_apps` (application names, matched case-insensitively as a part of the name, added to the built-in password managers: 1Password, Bitwarden, LastPass, Dashlane, KeePass, NordPass, Proton Pass, Enpass, RoboForm, Keeper). The first two are safety limits and may only be lowered; zero and unknown keys are refused, and the desktop does not start on a malformed admin.json |
| `desktop_display` | Linux computer use: `":N"` drives a running X display; `"xvfb"` or `"xvfb:1280x800"` starts a private Xvfb for the desktop server's lifetime (default 1920x1080). Unset refuses rather than using `$DISPLAY`. `paste_text` needs `xclip` or `xsel`; `ui_tree` needs a D-Bus session with at-spi2-core |
Expand All @@ -1256,6 +1308,7 @@ Environment variables:
| `INCODE_LANES` | Parallel `/run` lanes (needs git; at most 8) |
| `INCODE_SANDBOX` · `INCODE_SANDBOX_NETWORK` | The sandbox mode · the network switch |
| `INCODE_DESKTOP` | `1` offers the [computer use](#computer-use) tools |
| `INCODE_CODEX_TOOLS` | `own` · `incode`, over `admin.json` `codex_tools` |
| The variable each `key_env` names | That entry's key — the only part of an API route read from the environment |
| `INCORD_MEMORY_URL` · `INCORD_ENGINE_BIN` | The memory service · its engine binary |
| `INCODE_BROWSER` · `INCODE_PDF_BROWSER` · `INCODE_SOFFICE` | The headless browser · the PDF printer · LibreOffice |
Expand Down Expand Up @@ -1337,8 +1390,10 @@ moved. The old `INCORD_*` variables are not read any more: rename them.

## Limits

- `codex` and `agy` still use their own tools; only `claude` runs as a model
only. On those routes the guards are a sentinel (detection), not a gate.
- `codex` (by default) and `agy` still use their own tools; `claude` runs as a
model only, and so does `codex` with `codex_tools: "incode"`
([opt-in](#the-codex-route-whose-tools)). On the other routes the guards are a
sentinel (detection), not a gate.
- A client's MCP servers are stdio or Streamable HTTP; the older SSE transport is
not spoken.
- The Windows sandbox confines workspace-write only when you name it, and does
Expand Down
26 changes: 26 additions & 0 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -993,6 +993,32 @@ feature flag or config key (only the model catalogue's `apply_patch_tool_type`);
to switch them off was found. Until both are proved, codex keeps its own tools, the
Sentinel remains detection-only there, and its edit events still feed the diff.

**codex 0.163.0 — bridged, OPT-IN (`codex_tools: "incode"` / `INCODE_CODEX_TOOLS`).**
The default stays `own` until a turn with a real model has run this way. The tool list
was observed by pointing codex at a stand-in Responses endpoint
(`-c model_providers.<n>.base_url=…`) that recorded each request — no login needed:

| Need | Override | Evidence |
|---|---|---|
| No shell, image, web, goals or ask tools | `features.shell_tool=false`, `features.view_image=false`, `web_search="disabled"`, `features.goals=false`, `tools.experimental_request_user_input.enabled=false` | `gpt-5.5` control: `exec_command, write_stdin, request_user_input, apply_patch, view_image, get_goal, create_goal, update_goal, tool_search, web_search`; with them: `list_mcp_resources, list_mcp_resource_templates, read_mcp_resource, apply_patch, mcp__incode{…}`. |
| No sub-agents of its own | `agents.enabled=false` (+ `features.multi_agent=false`) | `gpt-5.6-terra` (catalogue: multi-agent v2) still had a `collaboration` namespace (`spawn_agent`, …) with only the feature off; gone with `agents.enabled=false`, which `Config::multi_agent_version_override` puts above the catalogue. |
| Its MCP servers and settings unread | `--ignore-user-config` | `exec/src/cli.rs` (global flag, 0.145+); auth still from `CODEX_HOME`. Hooks stay off by `--disable hooks`. |
| incode's server, reachable | `mcp_servers.incode.{command,args}`, `env_vars=["INCODE_TOOL_BRIDGE","INCODE_TOOL_TOKEN"]` | codex gives a stdio server only `HOME`, `PATH`, … plus `env_vars` (`rmcp-client/src/utils.rs`); a probe server got the two named and not a third variable set beside them. |
| Calls not refused by codex | `default_tools_approval_mode="approve"` | `auto` asks for any tool not marked read-only (`requires_mcp_tool_approval_for_mode`), and under `approval_policy="never"` the ask is a refusal. |
| Tools listed directly | `omit_tools_from=["deferred"]` | without it the tools sat behind `tool_search`; with it `mcp__incode{…}` was in the list and `tool_search` was not (0.153+; 0.145 ignores the key). |
| Long calls survive | `tool_timeout_sec=3600` | codex's default is 300 s (`DEFAULT_TOOL_TIMEOUT`); the bridge's own bound is an hour. |
| `apply_patch` cannot write | `sandbox_mode="read-only"`, `approval_policy="never"` | no switch exists (the catalogue's `apply_patch_tool_type`); `assess_patch_safety` rejects it before it runs. Live: a scripted `apply_patch` adding a file came back "patch rejected: writing is blocked by read-only sandbox; rejected by user approval settings", and no file appeared. |

Through `incode -t` with the stand-in scripted to call `mcp__incode` `Write`: codex
started `incode --tool-server`, the call ran in the toolbox (`tool Write (change)`),
the file was written, the stream showed it once as `incode-1` (codex's own
`mcp_tool_call` items for the `incode` server are not shown again), and the model was
handed the toolbox's answer. With `"permissions": {"deny": ["Write(secret.txt)"]}` the
same call came back "NOT RUN — Write is refused by the deny rule" and nothing was
written. On a code-mode model (`gpt-5.6-terra`) the tools are nested under codex's
`exec` (JavaScript, no file system or network), and each call still lands in the
toolbox. NOT run: a turn with a real model.

**agy 1.2.11 (antigravity) — NOT bridged; cannot be.** `agy --help` has no flag to
remove or restrict its built-in tools, no per-run MCP configuration (only a persistent
`agy mcp add`, which edits the operator's machine), and no way to skip its settings. A
Expand Down
11 changes: 7 additions & 4 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,13 @@ This is fully true for claude; section 0b says what is not.

### 0b. Still open

- **codex and agy still use their own tools.** agy has no switch to turn them off
or add MCP per run; codex has no switch for `apply_patch` / `update_plan`, and
its candidate flags could not be proved (usage limit). On both routes the guards
are the Sentinel (detection), not a gate (`ARCHITECTURE.md` §5a).
- **codex and agy still use their own tools by default.** agy has no switch to
turn them off or add MCP per run. codex can now be bridged, opt-in
(`codex_tools: "incode"`): measured on 0.163.0 against a stand-in model
endpoint, end to end; `apply_patch` has no switch and is rejected unrun under
read-only + never. Left: a turn with a real model, then making it the default.
On the unbridged routes the guards are the Sentinel (detection), not a gate
(`ARCHITECTURE.md` §5a).
- **Driving ACP agents (opencode, gemini).** Built in `fcfa2d9`, reverted in
`c98757a`; not in HEAD. gemini, opencode and cursor are detected, not driven.
- ~~**Provider agents** from `api_providers` are listed and marked not usable.~~
Expand Down
111 changes: 111 additions & 0 deletions src/admin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,12 @@ pub struct AdminConfig {
/// cmd.exe, and never the WSL launcher.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub shell: Option<String>,
/// Whose tools a codex model runs: `own` (the default — codex's, watched
/// afterwards by the Sentinel) or `incode` (incode's toolbox through the
/// tool bridge, codex's own switched off) — see
/// [`crate::agent::codex::CodexTools`]. `INCODE_CODEX_TOOLS` wins over it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub codex_tools: Option<String>,
/// The capability ladder, named by the operator.
///
/// A tier is a list of models that can do the same JOB — `"top"` might hold
Expand Down Expand Up @@ -992,6 +998,36 @@ impl AdminConfig {
}
}

/// Whose tools a codex model runs, and where that was decided: the
/// environment, then the settings, then `own`. A word nobody uses is
/// `own` from the built-in layer — the route that has run live — and is
/// reported as such rather than guessed at.
#[must_use]
pub fn resolve_codex_tools(&self) -> Resolved<crate::agent::codex::CodexTools> {
self.resolve_codex_tools_with(
std::env::var(crate::agent::codex::CODEX_TOOLS_ENV)
.ok()
.as_deref(),
)
}

/// [`Self::resolve_codex_tools`] with the environment's value passed in,
/// so a test drives every layer without setting a variable that the
/// backend tests running beside it read.
fn resolve_codex_tools_with(
&self,
env: Option<&str>,
) -> Resolved<crate::agent::codex::CodexTools> {
use crate::agent::codex::CodexTools;
if let Some(tools) = env.and_then(CodexTools::parse) {
return Resolved::new(tools, Source::Environment);
}
match self.codex_tools.as_deref().and_then(CodexTools::parse) {
Some(tools) => Resolved::new(tools, Source::AdminFile),
None => Resolved::new(CodexTools::Own, Source::BuiltIn),
}
}

/// The check that decides whether work is finished, and where it came from.
#[must_use]
pub fn resolve_verify(&self, workspace: &Path) -> Option<Resolved<Vec<String>>> {
Expand Down Expand Up @@ -1086,6 +1122,13 @@ impl AdminConfig {
)),
}

let codex_tools = self.resolve_codex_tools();
out.push_str(&format!(
" codex tools {} <- {}\n",
codex_tools.value.as_str(),
codex_tools.source.as_str()
));

// Every one of these is optional. Saying which are OFF is the point: a
// harness quietly doing less looks exactly like one doing nothing.
let off = self.plugins.disabled();
Expand Down Expand Up @@ -1155,6 +1198,7 @@ mod tests {
std::env::remove_var(crate::config::MODEL_ENV);
std::env::remove_var(crate::budget::BUDGET_ENV);
std::env::remove_var(crate::verify::VERIFY_COMMAND_ENV);
std::env::remove_var(crate::agent::codex::CODEX_TOOLS_ENV);
for role in crate::roles::KNOWN_ROLES {
std::env::remove_var(format!(
"{}{}",
Expand Down Expand Up @@ -1512,6 +1556,7 @@ mod tests {
sandbox_backend: Some("wsl".to_string()),
// The Bash tool's shell, which the owner may pin on Windows.
shell: Some("C:/Program Files/Git/bin/bash.exe".to_string()),
codex_tools: Some("incode".to_string()),
// The ladder has to survive the file too — a tier an operator
// writes and cannot read back is a setting that does not exist.
tiers: BTreeMap::from([(
Expand Down Expand Up @@ -1611,6 +1656,72 @@ mod tests {
clear_env();
}

/// **CODEX KEEPS ITS OWN TOOLS UNLESS SOMEONE SAID OTHERWISE.** Unset is
/// `own`; the settings switch it to `incode`; the environment wins over
/// the settings; a word nobody uses is `own` from the built-in layer,
/// never a guess at what was meant.
#[test]
fn codex_tools_resolve_like_the_other_settings() {
use crate::agent::codex::CodexTools;
let unset = AdminConfig::default();
assert_eq!(
unset.resolve_codex_tools_with(None),
Resolved::new(CodexTools::Own, Source::BuiltIn)
);

let admin = AdminConfig {
codex_tools: Some("incode".to_string()),
..Default::default()
};
assert_eq!(
admin.resolve_codex_tools_with(None),
Resolved::new(CodexTools::Incode, Source::AdminFile)
);
let parsed: AdminConfig =
serde_json::from_str(r#"{"codex_tools":"incode"}"#).expect("admin.json");
assert_eq!(parsed, admin, "the admin.json spelling");

let typo = AdminConfig {
codex_tools: Some("bridged".to_string()),
..Default::default()
};
assert_eq!(
typo.resolve_codex_tools_with(None),
Resolved::new(CodexTools::Own, Source::BuiltIn)
);

assert_eq!(
admin.resolve_codex_tools_with(Some("own")),
Resolved::new(CodexTools::Own, Source::Environment)
);
assert_eq!(
unset.resolve_codex_tools_with(Some(" Incode ")),
Resolved::new(CodexTools::Incode, Source::Environment)
);
// An unusable value in the environment is no answer: the settings speak.
assert_eq!(
admin.resolve_codex_tools_with(Some("")).source,
Source::AdminFile
);
}

/// The report names the choice and who made it.
#[test]
fn the_report_says_whose_tools_codex_runs() {
let _guard = lock();
clear_env();
let admin = AdminConfig {
codex_tools: Some("incode".to_string()),
..Default::default()
};
let report = admin.report(Path::new("."), None);
assert!(
report.contains("codex tools incode <- admin file"),
"{report}"
);
clear_env();
}

/// The engine: `builtin` unless named, the settings name it, the
/// environment wins, and a word nobody uses is the built-in default.
#[test]
Expand Down
12 changes: 12 additions & 0 deletions src/agent/agy.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,18 @@
//!
//! It showed up as something worse, and more useful: **this agent cannot
//! express the policy at all.** See [`AgyBackend::enforces`].
//!
//! # Why it is not driven over the tool bridge
//!
//! The Claude route, and codex with `codex_tools: "incode"`, run every tool call
//! in incode's toolbox ([`crate::tool_bridge`]). That needs two things of the CLI
//! for ONE run: a way to switch its own tools off, and a way to hand it an MCP
//! server. `agy --help` (1.2.11) has neither — no flag removes or restricts a
//! built-in tool, and MCP servers are added only by `agy mcp add`, which writes
//! the operator's persistent configuration rather than this spawn's. Without the
//! first, the bridge would be one more tool beside `run_command` and
//! `write_to_file`, refusing nothing. So agy keeps its own tools, and the
//! Sentinel stays its check.

use std::io::{BufRead, BufReader};
use std::path::PathBuf;
Expand Down
Loading
Loading