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.

Schedule create and enabled-state control are Administration actions. Both require approval under Allow all and Development defaults, including initially paused creation and disable. Reads remain Read actions. Exact overrides and external policy retain their authority. Risk auto does not automatically approve persistent schedule controls. The strict tools accept no owner, application, Workspace, session, or run provenance; the host binds these from active authenticated run and delegation evidence. Application scopes remain an independent requirement. Schedule fields are immutable except enabled state, and controls require the canonical revision returned by an authorized read. Agent schedule input snapshots are limited to 48 KiB so the complete immutable inputs fit in the approval review. workflow.definition.read is the Read action shared by registered-definition listing and inspection. workflow.definition.register is an Administration action for validated definition registration; Desktop operators use the separately scoped authenticated import API. workflow.run.read and workflow.run.start describe independent workflow-run inspection and allocation; their authenticated API scopes are distinct from chat runs.

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, session.set_title, 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, plugin.resource.read, 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, task creation or updates, 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¶

Published CLI and Desktop builds include a pinned rg for command searches. When shell.run has execute authority for that exact file, rg resolves to the managed copy before an ambient executable. Its presence does not change the approval and sandbox rules for shell.run. For ordinary workspace search, filesystem.search remains available without process execution, including in Plan Mode. It accepts regular expressions by default, an optional file glob, and a result limit. Workspace searches and repo.map honor repository ignore rules. Use filesystem.search for arbitrary code or text matches; repo.symbol_search only matches literal substrings in structural declarations. Source and debug Desktop builds do not stage the release ripgrep binary, so use filesystem.search there unless an executable has been explicitly configured.

For direct command searches in a published build, pass argv so the tool resolver selects the managed executable without relying on a shell PATH. The isolated Windows shell has a restricted PATH, so command: "rg ..." can fail even when the exact bundled executable is granted:

{"argv":["rg","-n","load_plugin|discover_plugins","crates/colossus-plugins"],"justification":"Find the plugin loader implementation."}

The equivalent filesystem.search call works without process execution:

{"pattern":"load_plugin|discover_plugins","path":"crates/colossus-plugins","glob":"**/*.rs","max_matches":50}

The model-visible tool description includes the host operating system before the agent's first command. It is a hint for native execution; a configured OCI container may use a different OS, and command syntax still depends on the selected shell.

timeout_ms is an execution deadline, including supervised cleanup. Its model-visible maximum follows the selected workspace's sandbox.timeoutMs, which defaults to fifteen minutes. Omission uses the policy ceiling; an explicit request may narrow it. The max_output_bytes argument is bounded by both the sandbox and the tool's 1 MiB ceiling. A stricter request-time policy remains authoritative. See Sandbox resource limits.

Managed shell sessions¶

Set yield_time_ms to return a tracked process handle after a short wait. The default wait is 10 seconds when lifetime is supplied; each wait is limited to 30 seconds. Commands without either field retain synchronous behavior.

{"command":"cargo test","justification":"Verify the requested changes.","yield_time_ms":1000,"lifetime":"run"}

Use lifetime: "workspace" explicitly for a development server or other process that must continue across later conversation turns. Keep the server in the foreground inside its managed session. Shell & or nohup does not create a managed lifetime. Wait until the response reports running before ending the initiating turn; a launch still awaiting authorization or startup is cancelled when that run ends.

{"command":"npm run dev -- --host 127.0.0.1","justification":"Serve the requested local preview.","yield_time_ms":1000,"lifetime":"workspace"}

Reads and waits accept max_output_bytes from 16384 to 65536. Responses contain session, ordered chunks, next_sequence, and gap; pass next_sequence as the next after_sequence. Status distinguishes starting, running, stopping, exited, stopped, timed_out, failed, interrupted, and outcome_unknown. Only a confirmed exit code can establish command success. Output may be truncated by the policy ceiling or the 64 KiB/256-chunk retained log window. Restart discards the in-memory logs and reports a gap.

Run-owned sessions are stopped when their run finishes, fails, or is cancelled. Workspace sessions survive turns after reaching running, until they exit, are stopped, reach the original execution deadline, or their runtime shuts down. Neither background lifetime nor waiting raises sandbox.timeoutMs. Increase that explicit workspace ceiling for servers that need more than the default fifteen minutes. Managed sessions reserve concurrency through cleanup. sandbox.maxConcurrency limits each actor/run independently and defaults to one. A separate workspace capacity of 32 active sessions bounds total resource use across runs and applications.

Desktop's Active shells tool shows the selected runtime's released logs, status, origin, and deadline, with search, follow, copy, and Stop. Active shells retain their Managed Local runtime when switching workspaces. Quitting Desktop stops Managed Local shells; disconnecting from an External target leaves that runtime in charge. This is a log viewer, with no interactive stdin or PTY authority. Network and listener permissions remain those of the selected sandbox; background lifetime adds none.

shell.run accepts exactly one invocation form:

{"command":"cargo test -p colossus-runtime --lib","justification":"Check runtime tests for regressions in the changed code.","cwd":".","timeout_ms":120000}

{"argv":["git","status","--short"],"justification":"Identify existing workspace changes before editing.","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.

Both forms require justification, a nonblank plain-text task purpose of at most 512 Unicode characters, without control or bidirectional characters. Do not include credentials, hidden reasoning, or claims of authorization. This field is required even when policy or the approval mode permits execution without an interactive prompt. An invalid explanation executes nothing and can be corrected within normal turn limits.

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. Explicitly enabled plugin MCP operations use plugin.mcp.PLUGIN.SERVER.tools and plugin.mcp.PLUGIN.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 explicitly enabled plugin MCP actions are added only from the active run snapshot and workspace overlay.

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.

Plain-language task scheduling¶

workflow.task.schedule is the agent-facing calendar-task tool. Its strict arguments are schedule_id, task, calendar, starts_at, misfire_policy, enabled, and idempotency_key. task contains a name, instructions, explicit tool ceiling, and optional configured model/effort preferences. calendar contains an IANA timezone, HH:mm local time, and ISO weekdays; an empty weekday list means daily. starts_at must be the exact first UTC occurrence matching those calendar fields. Serialized task content must fit the 48 KiB inline approval review bound.

The trusted runtime derives the internal definition and empty workflow inputs. The tool rejects workflow identifiers, hashes, elapsed cadence, origin, session, and run fields. Its effect action and policy capability are workflow.schedule.create; it does not introduce a separate approval exemption. Application runs require schedules:read, schedules:create, workflows:read, and workflows:register plus an explicit tool grant. Task tool names do not grant their own action permissions.

Use workflow.schedule.list to check for an existing request and workflow.schedule.get to confirm the stored task. Retry identities are scoped to the application owner and exact canonical request. Retain them across uncertain responses. The bundled colossus/schedule-task skill documents this flow.

workflow.schedule.delete accepts only schedule_id and the freshly inspected 64-character etag. It uses the workflow.schedule.delete effect action and normal approval obligations; application callers need schedules:read, schedules:control, and an explicit tool grant. It rejects foreign and unknown-owner legacy records. Deletion appends a durable tombstone, stops future ticks, and removes the schedule from the active catalog. Already allocated runs and their ownership remain intact. The same reviewed deletion can be reconciled without another append, but deleted IDs cannot be allocated again. Lost mutation responses are never retried automatically.