Platform (platform)

Category: tools | Form: | Symbol: Pf

Unified tool capabilities for agents — workspace, shell, git, web, devtools, delegation, and custom actor tools

Unified tool element that replaces 10+ individual tools (file-read, file-write, shell, git-ops, web-fetch, web-search, code-search, user-interaction, delegation, toolbox). Configure via the capabilities array: workspace (read_file, write_file, edit_file, list_dir, search, glob), shell (bash), git (git_commit, git_log, git_diff, git_branch, git_read_file), web (web_fetch, web_search), devtools (triform_* platform API tools), interaction (ask_question, todo_write, todo_read), delegation (check_delegation, cancel_delegation + per-target delegation entries). The capability_mode controls unlocking: “on_demand” starts with SAFE_DEFAULT_TOOLS (read_file, list_dir, search, glob, ask_question, todo_write, todo_read) and progressively unlocks more; “always” enables all configured capabilities immediately; “off” restricts to read-only. Only attaches to agents (not functions or other actors). The tool_names property is computed at runtime from enabled capabilities — do not set it manually. Each capability group has its own config (allowed_globs, allowed_commands, allowed_domains, scopes, etc.). Custom tools via custom_tools array let you expose any actor element’s invoke as an LLM tool. Delegations array creates per-target delegation tools with custom names visible to the LLM.

Guide

Unified tool element providing all platform capabilities to attached agents. Replaces 10+ individual tool elements with a single configurable modifier.

Overview

The platform element is the primary way to grant agents access to workspace, shell, git, web, devtools, interaction, and delegation capabilities. Instead of attaching separate file-read, file-write, shell, git-ops, etc. elements, you attach one platform element and configure which capability groups are enabled.

Quick Start

# Create a platform tool with workspace + shell + git capabilities
POST /api/my-circle/tools/platform/ {
  "slug": "dev-tools",
  "name": "Developer Tools",
  "spec": {
    "capabilities": ["workspace", "shell", "git"],
    "capability_mode": "on_demand"
  }
}

# Attach to an agent
POST /api/my-circle/tools/platform/dev-tools/ops/attach {
  "target_id": "<agent-uuid>"
}

# Agent now has: read_file, write_file, edit_file, list_dir, search, glob,
#                bash, git_commit, git_log, git_diff, git_branch, git_read_file

Capability Groups

Each capability maps to specific built-in tool names via capability_tool_names() in agent.rs:

Capability	Tool Names	Description
workspace	read_file, write_file, edit_file, list_dir, search, glob	File system operations
shell	bash	Shell command execution
git	git_commit, git_log, git_diff, git_branch, git_read_file	Git version control
web	web_fetch, web_search	Web content and search
devtools	triform_* (11 tools)	Triform platform API access
interaction	ask_question, todo_write, todo_read	User communication
delegation	check_delegation, cancel_delegation + custom per-target	Task delegation

Capability Modes

Mode	Behavior
on_demand	Starts with safe read-only tools (read_file, list_dir, search, glob, ask_question, todo_write, todo_read) and progressively unlocks more as needed. Recommended.
always	All configured capabilities enabled immediately
off	Read-only tools only

Properties

Capability Selection

Property	Type	Default	Description
capability_mode	enum	on_demand	How tools are unlocked
capabilities	string[]	[workspace, shell, git]	Enabled capability groups
tool_names	string[]	[]	Computed at runtime — do not set manually

Workspace Config

Property	Type	Default	Description
allowed_globs	string[]	["**/*"]	Glob patterns for allowed file paths
max_file_size	integer	10485760	Max file size in bytes (10 MiB)
allow_create	boolean	true	Allow creating new files
allow_delete	boolean	false	Allow deleting files

Shell Config

Property	Type	Default	Description
allowed_commands	string[]	[]	Command prefix allowlist (empty = all)
shell_timeout_ms	integer	120000	Timeout (1s–10min)

Git Config

Property	Type	Default	Description
allow_push	boolean	false	Allow pushing to remote
default_branch	string	"main"	Default branch name

Web Config

Property	Type	Default	Description
allowed_domains	string[]	[]	Domain allowlist (empty = all)
max_response_size	integer	5242880	Max response body (5 MiB)

Devtools Config

Property	Type	Default	Description
scopes	string[]	10 default scopes	API scopes in resource:action format

Interaction Config

Property	Type	Default	Description
interaction_timeout_ms	integer	300000	User response timeout (5 min)

Delegation Config

Property	Type	Default	Description
max_concurrent	integer	5	Max concurrent delegations
delegation_timeout_ms	integer	600000	Delegation timeout (10 min)
workspace_propagation	boolean	true	Propagate workspace changes from delegates
delegations	object[]	[]	Per-target delegation tools

Custom Tools

Property	Type	Default	Description
custom_tools	object[]	[]	Expose explicitly allowlisted element operations as LLM tools

Each custom tool entry:

custom_tools:
  - ref: "my-validator"
    enabled: true
    operations:
      - op: "invoke"
        name: "validate_data"          # Tool name visible to LLM
        description: "Validate JSON"   # Description for LLM
        timeout_ms: 30000
        safety: read
        input_schema:
          type: object
          required: [payload]
          properties:
            payload:
              type: object

Custom tools are fail-closed:

• No target operation is exposed unless it is listed in operations.
• One operation becomes one LLM-visible tool with its own schema, description, timeout, and safety metadata.
• ref can be a UUID, slug, qualified circle/slug, or a legacy path where the final slug segment resolves to an element.
• The runtime validates that the target element supports the requested operation before the tool is shown to the agent.
• capability_mode: "off" still allows explicitly configured custom tools, but it does not grant shell, git, devtools, workspace write, or other broad tools.

A safe domain-helper pattern is a platform element with custom_tools only, capability_mode: "off", and no broad capabilities. This lets a chat agent call bounded read helpers without receiving generic platform or shell access.

Tool Dispatch

When the agent calls a tool, the dispatch in native_llm.rs routes through 4 layers:

1. Quota check — rate limits on web_fetch, web_search
2. Custom platform tools — explicit custom_tools[].operations[], routed through OperationDispatcher
3. Dynamic devtools — element-specific tools from devtools config
4. Sandbox proxy — if CODER_WORKER_URL set, routes file/search/bash through isolation executor
5. Built-in dispatch — local execution for all other tools

For file tools (read_file, write_file, edit_file, list_dir), the agent’s circle workspace takes priority when available.

Modifier Behavior

Field	Value
applies_to	agents only
cascade_behavior	nearest
fail_action	allow
evaluation_order	10 (runs early)

Errors

Code	Class	Retryable	Description
PLATFORM_CAPABILITY_DISABLED	auth	No	Tool belongs to disabled capability group
PLATFORM_SCOPE_DENIED	auth	No	Operation not allowed by scopes
PLATFORM_CUSTOM_TOOL_NOT_FOUND	not_found	No	Custom tool ref couldn’t resolve
PLATFORM_SHELL_TIMEOUT	timeout	Yes	Shell command exceeded timeout
PLATFORM_DELEGATION_TIMEOUT	timeout	Yes	Delegation exceeded timeout

When to Use

• Always use platform as the default tool element for agents
• Only add browser or user-browser if the agent needs web browsing capabilities
• For maximum safety, use capability_mode: "on_demand" with minimal capabilities
• Use custom_tools to expose domain-specific functions as LLM-callable tools without granting broad devtools, shell, git, or workspace capabilities

Relationships

• Attaches to: triformer
• Uses: prompt, variable

Capabilities

• workspace-access: Read, write, edit files and search code in the agent workspace
• shell-execution: Execute shell commands
• git-operations: Git version control operations
• web-access: Fetch web content and search the web
• platform-devtools: Triform platform API access
• user-interaction: Ask questions and manage todos for the user
• task-delegation: Delegate tasks to other actors
• custom-tools: Expose any actor as an LLM-callable tool
• executable: Element can be invoked to execute operations

Properties

Property	Type	Default	Description
capability_mode	string	"always"	How tool capabilities are granted. ‘always’ (recommended) enables all configured capabilities immediately — lowest latency to first response. ‘on_demand’ starts with safe read-only tools and progressively unlocks more via a per-message LLM classification (adds 1-3s before each reply). ‘off’ restricts to read-only tools only.
capabilities	array	["workspace","shell","git","browser"]	Enabled capability groups
tool_names	array	[]	Computed tool names — resolved from enabled capabilities
agent_instructions	string	""	Core skill guide injected on first tool use. Teaches the agent how to use platform tools. Source: skills/SKILL.md
skill_references	object	{}	Reference guides for advanced topics. Keyed by topic name, served via the help command.
allowed_globs	array	["**/*"]	Glob patterns for allowed file paths
max_file_size	integer	10485760	Maximum file size in bytes for read operations (min 1, max 100 MiB)
allow_create	boolean	true	Allow creating new files
allow_delete	boolean	false	Allow deleting files
allowed_commands	array	[]	Allowed command prefixes (empty = all allowed)
shell_timeout_ms	integer	120000	Shell command timeout in milliseconds (min 1 s, max 10 min)
allow_push	boolean	false	Allow pushing to remote
default_branch	string	"main"	Default branch name
allowed_domains	array	[]	Allowed domains for fetch/search (empty = all)
max_response_size	integer	5242880	Maximum response body size in bytes (min 1, max 100 MiB)
scopes	array	["elements:read","elements:write","files:read","files:write","execute:read","execute:write","deploy:read","analyze:read","llm:chat","issues:write"]	API scopes granted to the agent
interaction_timeout_ms	integer	300000	User response timeout in milliseconds (min 1 s, max 1 hour)
max_concurrent	integer	5	Maximum concurrent delegations (min 1, max 100)
delegation_timeout_ms	integer	600000	Delegation timeout in milliseconds (min 1 s, max 1 hour)
workspace_propagation	boolean	true	Propagate workspace changes from delegates back to parent
delegations	array	[]	Per-target delegation tools — each entry becomes a distinct tool
custom_tools	array	[]	Custom tools — expose explicitly allowlisted operations on target elements as LLM tools

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attach

Post /ops/attach | Auth: Read

Attach this tool to a target agent element

This is the critical operation that grants an agent access to tools. POST the tool’s attach endpoint with target_id=<agent_uuid>. The agent’s enabled_tools list is recomputed on every invocation, so attaching/detaching takes effect on the next agent run. The target must be an element listed in the tool’s contract.yaml attaches list (typically agents).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

detach

Post /ops/detach | Auth: Read

Detach this tool from a target agent element

Removes tool access from the agent. Takes effect on next agent invocation. Requires the same target_id used in attach.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

invoke

Post /ops/invoke | Auth: Execute

Invoke the tool with input

Tools are primarily invoked indirectly by agents (the agent loop calls tools automatically). Direct invoke is for standalone testing. Input must match the tool’s port schema. Use ?async=true to get a run_id for polling. Browser tools return screenshots as base64 PNG.

list_attachments

Get /ops/targets | Auth: Read

List all agents this tool is attached to

Returns all agent elements where this tool is currently attached. Shows target_id, target_type, priority, and cascade_policy.

logs

Get /ops/logs | Auth: Read

Get execution logs

mcp_tool_def

Get /ops/mcp/tool | Auth: Read

Get this tool’s MCP tool definition (name, description, inputSchema)

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

reset

Post /ops/reset | Auth: Execute

Reset tool state to idle

Use when a tool is stuck in error state. Resets to idle so it can be invoked again. For browser tools, this also clears the CDP session — the next navigation starts fresh.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

run_get

Get /ops/runs/{run_id} | Auth: Read

Get details of a specific run

runs

Get /ops/runs | Auth: Read

List execution runs

schema

Get /ops/schema | Auth: Read

Get input/output port schemas (MCP tools/list compatible)

Returns the MCP-compatible tool schema. Useful for validating what inputs a tool expects before invoking. For platform tools, the schema reflects currently enabled capabilities.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
PLATFORM_CAPABILITY_DISABLED	auth	no	Requested tool belongs to a capability group that is not enabled
PLATFORM_SCOPE_DENIED	auth	no	Operation not allowed by configured scopes
PLATFORM_CUSTOM_TOOL_NOT_FOUND	not_found	no	Custom tool reference could not be resolved
PLATFORM_SHELL_TIMEOUT	timeout	yes	Shell command exceeded timeout
PLATFORM_DELEGATION_TIMEOUT	timeout	yes	Delegation exceeded timeout