Repository Public License
1<!--2ORIX OS Automation3File: docs/api/tool-api.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Tool API and capability manifest89The per-tool reference (arguments, outputs, tiers) is generated from the code: [`tools.md`](tools.md). This page10describes the contract every tool obeys. The types live in `Packages/ORIXCore/Sources/ORIXCore/Tools.swift` and11`Security.swift`.1213## The contract1415```swift16public protocol ORIXTool: Sendable {17 var identifier: String { get }18 var manifest: ToolManifest { get }19 func requirements(for input: ToolInput, context: ToolExecutionContext) throws -> ToolRequirements20 func execute(input: ToolInput, context: ToolExecutionContext) async throws -> ToolResult21}22```2324`requirements` is pure. It validates the meaning of the arguments, resolves every path with25`PathResolver.canonical` (tilde, relative to the run's working directory, `..` removed, symlinks resolved) and26returns the exact capabilities, the tier of this call, and one sentence describing what will happen. `execute`27then acts only on those resolved targets.2829A tool never checks policy, never asks for approval and never redacts. `ToolExecutor` does all three around it.3031## Manifest3233| Field | Meaning |34|---|---|35| `identifier` | `family.action`, unique |36| `name`, `version`, `summary` | Shown to people and to the model |37| `family` | `filesystem`, `shell`, `git`, `http`, `documents`, `python`, `script`, `system`, `applescript`, `accessibility`, `screen`, `browser`, `skill` |38| `inputSchema`, `outputSchema` | JSON Schema subset: `type`, `properties`, `required`, `additionalProperties`, `items`, `enum`, numeric and length bounds, `pattern` |39| `sideEffect` | `read`, `write`, `external`, `destructive`, `privileged` |40| `defaultTier` | 0–3; a call can state its own tier in `requirements` |41| `macPermissions` | macOS privacy permissions the tool depends on |42| `defaultTimeoutSeconds`, `maxOutputBytes` | Limits applied by the executor |43| `concurrency` | `unlimited`, `serial` (one call of this tool at a time), `exclusive` (GUI control) |44| `supportsDryRun` | The tool can describe what it would do without doing it |45| `idempotent` | Repeating the call cannot add effects. Only idempotent steps are retried automatically |46| `redactedInputKeys` | Argument keys hidden in logs, events and approval sheets |47| `outputIsUntrusted` | Output carries outside content and is framed as data when returned to a model |4849`ToolManifest.problems()` rejects inconsistent manifests (a read tool above tier 0, a destructive tool below50tier 2, a malformed identifier). The registry refuses to register such a tool.5152## Capabilities5354A capability is one specific authority: `fileRead(path)`, `fileWrite(path)`, `fileDelete(path)`,55`processExec(executable)`, `scriptRuntime(name)`, `appAutomation(bundleID)`, `accessibility(bundleID)`,56`screenCapture(scope)`, `network(host)`, `browser(host)`, `secret(reference)`, `clipboardRead`, `clipboardWrite`,57`notify`, `externalSend(channel)`, `appControl(bundleID)`, `skill(id)`.5859`Capability.covers` never widens: write does not imply read or delete; a path covers itself and its descendants60by whole components; a host covers only itself, or its subdomains with `*.`.6162## Tiers6364| Tier | Meaning | Who can allow it |65|---|---|---|66| 0 | Read-only | A grant, or an approval |67| 1 | Reversible local write (new files, in-place edits with a backup, move to Trash) | A grant of tier ≥ 1, or an approval |68| 2 | Consequential (scripts, network sends, app control, GUI input, git push, installs) | A grant of tier 2 (for example accepted workflow permissions), or an approval |69| 3 | High-risk or irreversible (permanent deletion, force push) | Only a contemporaneous approval of that exact call |7071## What the executor does with a call72731. Unknown tool → `failed / not_found`.742. Arguments against `inputSchema` → `invalidInput`; nothing runs.753. `requirements`; a file capability in a protected location → `denied`, audited as a policy violation.764. Capabilities inside the run's artifacts folder are granted implicitly; the rest go to the policy engine.775. `deny` → `denied`. `needsApproval` → the approval broker; no answer or a refusal → `notApproved`.786. An idempotency key already executed successfully in this run returns the stored result.797. Concurrency gate, then execution with a timeout; cancellation and emergency stop end it.808. Thrown `ToolError` → structured result. Output against `outputSchema`. Redaction. Truncation.819. Single-use grants are consumed; the call is audited; `toolRequested` / `toolFinished` events are stored.8283`invoke` never throws. Every outcome is a `ToolResult` whose `status` is one of `succeeded`, `simulated`, `failed`,84`denied`, `notApproved`, `blockedPermission`, `timedOut`, `canceled`, `invalidInput`, `unsupported`.8586## Subprocesses8788Tools that start programs use `ProcessRunner`: explicit argument vector (no shell), minimal environment, explicit89working directory, own process group, timeout, SIGTERM then SIGKILL of the group, bounded output. Script tools90(`shell.script`, `python.run`, `script.swift`, `script.javascript`, skills) run inside a generated Seatbelt profile:91writes only in the granted folders and the run's artifacts folder, no network unless a host was granted, no access92to credential stores. Seatbelt cannot filter by host: a confined process with network access can reach any host.9394## Adding a tool9596Add a type conforming to `ORIXTool` in the package of its family, list it in that package's `…Tools.all()`, and97write an integration test that runs it for real. If it needs authority that does not map to an existing98capability, that is a change to `ORIXCore` and to the policy engine, not something to approximate.99