Tools and action classes¶

config effective is the authority for all active and hidden candidates. tools list is the authority for the current model-visible catalog, JSON Schemas, source, family, action class, effect identity, decision, prerequisites, mutation labels, and output bounds.

Every tool schema denies unknown fields. Tool availability does not imply permission. The access profile and exact overrides decide visibility and the built-in decision; policy, approval, trust, the Safety Kernel, permits, sandbox obligations, quarantine, and post-effect release remain independent.

repo.file_summary applies both the requested line ceiling and a 64 KiB serialized result ceiling. Its preview and structural-hint collections are byte-bounded before they enter durable tool history; preview_truncated is true when either the line or encoded-byte ceiling was reached. This keeps generated or minified long lines from consuming an entire model input budget.

Plan Mode catalog and lifecycle actions¶

Plan Mode narrows the already-resolved tool catalog; it never widens access. A Create turn exposes plan.create, while an Update turn exposes plan.update. The latter schema contains only replacement content and steps: the runtime binds the exact plan ID and expected revision, so the model cannot redirect the write.

The remaining Plan Mode allowlist is:

• echo, tool.search, and interactive user.ask;
• filesystem.list, filesystem.read, filesystem.search, git.status, git.diff, git.show, repo.map, repo.symbol_search, repo.references, repo.file_summary, and patch.preview;
• context.show, context.snapshots, skill.resource.read, task.create, task.list, decision.list, plan.show, memory.list, memory.search, agent.result, and agent.list.

Normal access resolution and prerequisites can remove entries from that list. Plan Mode never offers filesystem writes, patch application, command/process execution, approval, networking, delegation, plan execution, or plan discard.

plan.discard is an operator-only Local State action rather than a model tool. plan.approve_request remains Administration. Direct execution and approved-plan Goal handoff both use the plan.execute Execution action. Update, discard, approval, and execution all cross the ordinary effect gateway; terminal commands do not bypass access, policy, approval, permits, or audit.

shell.run¶

shell.run accepts exactly one invocation form:

{"command":"cargo test -p colossus-runtime --lib","cwd":".","timeout_ms":120000}

{"argv":["git","status","--short"],"cwd":"."}

command is the recommended form for a bounded non-interactive script. Colossus selects the trusted shell supplied by workspace-development or one explicit shell grant and invokes it without startup profiles. argv preserves exact execution and requires its first entry to resolve to one configured or derived executable. Shell wrappers used in argv cannot request login, interactive, or startup-profile behavior.

Under a configured isolating boundary, cwd remains inside the canonical workspace. Colossus supplies an isolated HOME/temp directory and sanitized absolute PATH; model arguments cannot override those names or proxy variables. Under acknowledged danger full access, the working directory may be any existing host directory, executables resolve through ambient PATH, and the child receives ambient environment and networking. Output and a maximum of 64 observed proxy origins are quarantined before release.

Under development, execution remains approval-required. workspace-development supplies resources but never changes that action decision.

Tool-to-action exceptions¶

Most effectful built-ins use the same exact tool and action name. These are the exceptions operators need when writing action overrides:

Connected integration operations use their generated tool name as the action name. Verified pack tools use pack.tool.PACK.TOOL; pack MCP operations use pack.mcp.PACK.SERVER.tools and pack.mcp.PACK.SERVER.call. Inspect the exact active names with config effective.

Plan lifecycle operations that have no model-callable tool keep their action identity: operator discard is plan.discard, and either execution strategy is plan.execute.

Exact built-in action catalog¶

The following names are the complete first-party catalog accepted by exact access overrides. Dynamic integration and verified-pack actions are added only from their active trusted declarations.

Effect action classes¶

Exact action names are printed by tools list and config effective. They fall into these operational classes:

An action decision never supplies a resource grant. allow_all still requires a trusted registered action, valid explicit, profile-derived, or ambient obligations, and permit-bound execution. Configured * remains public HTTP(S)-only. Ambient authority is a separate acknowledged mode and permits exact private, loopback, link-local, and metadata HTTP(S) origins.

Call and recovery contract¶

• Tool arguments are validated before execution.
• Malformed provider arguments receive at most two bounded correction turns and never reach an adapter.
• A permit is one-use, short-lived, actor/request/decision-bound, and opaque outside the policy boundary.
• Each effect records request, decision, approval, start, and terminal evidence.
• A missing terminal event after start becomes outcome_unknown.
• Unknown external effects are not silently retried.
• Credentials remain references and raw values are hard-redacted.