Struct AgentToolState 

pub struct AgentToolState {

    pub writes: Arc<WriteBudget>,
    pub builtins: Arc<BuiltinTools>,
    pub mcp: Arc<Mutex<ToolExecutor>>,
    pub builtin_names: HashSet<String>,
    pub launch_overrides: Arc<HashMap<String, ToolPolicy>>,
    pub safe_keys: Arc<HashSet<String>>,
    pub run_allows: Arc<Mutex<HashSet<String>>>,
    pub stage_allows: Arc<Mutex<HashSet<String>>>,
    pub stage_allows_index: Arc<Mutex<Option<usize>>>,
    pub stage_perms: Arc<Mutex<HashMap<String, String>>>,
    pub stage_perms_by_index: Arc<Vec<HashMap<String, String>>>,
    pub stage_required: Arc<Mutex<HashSet<String>>>,
    pub stage_required_by_index: Arc<Vec<HashSet<String>>>,
    pub agent_perms: Arc<HashMap<String, String>>,
    pub global_perms: Arc<HashMap<String, ToolPolicy>>,
    pub blueprint_may_loosen: bool,
    pub interaction: HubInteractionBackend,
    pub unattended: bool,
    pub stage_name: Arc<Mutex<String>>,
    pub subagent: Option<SubAgentHandle>,
    pub sandbox: Option<Arc<SandboxManager>>,
    pub script_tools: Arc<Mutex<ScriptToolSet>>,
    pub script_tool_names: Arc<Mutex<HashSet<String>>>,
    pub script_host: Arc<dyn ScriptHost>,
    pub dynamic: Option<Arc<DynamicToolCtx>>,
}

Everything one agent needs to execute a tool call: the executors, its policy layers, and its interaction backend. All fields are cheap Arcs so a clone is moved into each exec_for closure. The stage-scoped fields (stage_perms/stage_name) are shared handles the host updates as the agent changes stage.

Fields

writes: Arc<WriteBudget>

The write ceilings in effect, and what this run has spent of them.

Shared rather than copied because the running total has to survive across every batch this run makes - a per-run budget that reset per batch would bound nothing.

builtins: Arc<BuiltinTools>

Built-in tool executor (holds the agent’s workdir).

mcp: Arc<Mutex<ToolExecutor>>

MCP tool executor.

builtin_names: HashSet<String>

Names of the built-in tools (dispatch routes builtin vs MCP).

launch_overrides: Arc<HashMap<String, ToolPolicy>>

--yolo / --allow / --ask / --deny launch overrides.

safe_keys: Arc<HashSet<String>>

Keys that need no prompt at all: the shipped safe list plus whatever the user’s [safe_commands] adds. Resolved once at spawn and never mutated, so reading it needs no lock.

Unlike a grant, a safe entry matches by program as well as exactly: naming cat covers cat notes.md, because otherwise it would cover nothing anybody runs. See crate::shell_keys::program_of.

run_allows: Arc<Mutex<HashSet<String>>>

Grant keys the user allowed for the rest of the run.

stage_allows: Arc<Mutex<HashSet<String>>>

Grant keys the user allowed for the current stage only, cleared by sync_stage when the run moves to a different stage.

A std mutex rather than the async one run_allows uses, because sync_stage is synchronous and clearing a grant must happen on the same tick the stage changes. Every read here is a contains with no await held, so the two lock kinds never contend for longer than a lookup.

stage_allows_index: Arc<Mutex<Option<usize>>>

The stage index stage_allows was granted under, so re-entering the same stage (a plan -> plan revision loop) keeps its grants while moving on drops them.

stage_perms: Arc<Mutex<HashMap<String, String>>>

The current stage’s tool_permissions - re-synced by sync_stage on each stage change (a std mutex so the sync system can update it synchronously).

stage_perms_by_index: Arc<Vec<HashMap<String, String>>>

Every stage’s tool_permissions, indexed by stage index; sync_stage copies the entered stage’s map into stage_perms.

stage_required: Arc<Mutex<HashSet<String>>>

The current stage’s required_tools - the human-in-the-loop tools it keeps through an unattended run. Re-synced by sync_stage, and read on every interaction so a kept tool reaches a real person instead of UnattendedInteraction. Empty for an attended run, where nothing is dropped and nothing needs keeping.

stage_required_by_index: Arc<Vec<HashSet<String>>>

Every stage’s required_tools, indexed by stage index.

agent_perms: Arc<HashMap<String, String>>

Blueprint-level [tool_permissions].

global_perms: Arc<HashMap<String, ToolPolicy>>

Config-level tool permissions.

blueprint_may_loosen: bool

[security] allow_blueprint_permissions: whether this manifest’s [tool_permissions] may exceed the built-in default for a tool the user has not configured. See BLUEPRINT_LOOSENABLE in crate::tools.

interaction: HubInteractionBackend

The agent’s interaction backend (ask_user + tool approvals).

unattended: bool

--yolo: nobody is watching this run, so the tools that block on a person are not advertised at all. Should one be called anyway, it is answered by UnattendedInteraction rather than parked on the hub for ever - unless the stage kept it in required_tools, in which case a real prompt is exactly what the blueprint asked for.

stage_name: Arc<Mutex<String>>

The current stage name, for tagging interactions (re-synced on stage change).

subagent: Option<SubAgentHandle>

Handle for the sub-agent tools (spawn/check/wait/send/kill), or None when this agent can’t reach the host (e.g. in unit tests).

sandbox: Option<Arc<SandboxManager>>

The agent’s sandbox manager, or None when no stage is sandboxed. Held here so sync_stage can point it at the entered stage’s sandbox; the same Arc is also an ECS component (for teardown at reap) and is wired into builtins as the shell tool’s executor.

script_tools: Arc<Mutex<ScriptToolSet>>

The agent’s discovered Rhai script tools, compiled at spawn. Behind a mutex so a dynamic_tools agent’s mid-run re-scan can swap the set in place; static agents never mutate it.

script_tool_names: Arc<Mutex<HashSet<String>>>

Names of the script tools, for routing dispatch to the Rhai executor. Mutable alongside script_tools on a dynamic re-scan.

script_host: Arc<dyn ScriptHost>

The host functions script tools call, with [tool_script_permissions] enforcement (Layer 3) already baked in.

dynamic: Option<Arc<DynamicToolCtx>>

Present only for dynamic_tools agents: everything needed to re-discover and re-advertise this agent’s tools mid-run.

Trait Implementations

impl Clone for AgentToolState

fn clone(&self) -> AgentToolState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.