Skip to content
Sign in

ladder

v0.1.0

Constraints and capabilities on one ladder, as an iii worker. A constraint is what an agent may not do; each one names the rung that carries it, and the ladder refuses a call in the rule's own words from the harness's pre-call hook. Needs iii 0.26.0 or newer, because it speaks observers.

Install

bash
iii trigger compose::add worker=ladder@0.1.0

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Agent-ready brief for v0.1.0
Install, config, dependencies, readme, skills and API reference, all in one place. Fetch as agent-context.md for an LLM to consume.
The same content rendered as discrete blocks below is exposed as a single markdown document at /registry/workers/ladder.md?version=0.1.0. Paste it into an LLM prompt or pipe it through curl from a worker.

Install

iii trigger compose::add worker=ladder@0.1.0

Dependencies

No dependencies for v0.1.0

Readme

README.md

ladder

Constraints and capabilities on one ladder, as an iii worker. A constraint is what an agent may not do; a capability is what it may. They are the same shape: a rule with a rung, the mechanism that carries it. The ladder refuses a call in the rule's own words, from the harness's pre-call hook, and serves the ladder as data: what is carried where, how much of it is measured rather than hoped for, and what moving one would do. It needs iii 0.26.0 or newer, because it speaks observers.

iii call compose::add worker=ladder

The six rungs

Rung Carried by What it can see
0 prose in the charter nothing. It asks
1 the grant: what the phase may call function ids, before any call
2 a hook on the tool call the arguments, before the write lands
3 a callback inside the turn the call, and it may hold it for a person
4 the delivery gate the finished diff, before the commit
5 CI the merged tree, after everybody left

A rung is a place, not a strictness. Rung 3 sees a function call, and a shell command is one call whose contents it does not read. Rung 4 sees the diff and never sees the call. Neither can see what the other sees, so a rule that matters names both.

Climbing costs something. Rung 0 is free and enforces nothing. Rung 2 needs a predicate somebody writes and maintains. Pick the cheapest rung that can actually see the thing your rule is about.

A primitive is two files with one name

team/rules/no-secrets.md is the rule. team/rules/no-secrets.py is the predicate. The .md alone gives you rung 0. Add the .py and the same primitive turns mechanical:

  • kind comes from the directory. rules/ is a rule, skills/ is a skill.
  • side comes from the kind. A rule constrains; a skill is a capability.
  • layer is the one thing you declare: project, team, or org.
  • rung follows from the layer and from whether a script exists beside it.

A rule's script may also be a function id on the bus, so a check can be written in any language and run by whatever worker hosts it.

Configuration

Variable Default What it is
LADDER_REPO the working directory the repository whose .agents/ the ladder reads
LADDER_HOME the worker's own directory where shipped (team/org) primitives live
III_URL ws://localhost:49134 the engine

The repository's own .agents/settings.json permissions.deny entries are honoured first, at rung 2, before any team rule: a project is never refused by a team rule for something it had already forbidden itself. Pass permissions in a call's payload for a caller that can see the settings file when the worker cannot.

Run it as a host process when it must read a target repository. A sandboxed package worker mounts only its own source; the target repository does not exist inside that sandbox, and a ladder that reads a settings file that is not there reports a repository with no permissions — which looks exactly like permissions that are not enforced. ghola therefore runs its own copy with path:// in worker-compose.yaml, and installs this registry worker where the repository it judges is the project's own.

Functions

Function What it does
ladder::gate the harness::hook::on-pre-call observer: refuses or holds a call that breaks a constraint, in the rule's own words
ladder::list everything on the ladder, both sides, with rungs, catches, and withheld
ladder::explain one primitive, and what each rung it names can actually see
ladder::evaluate ask about a proposed write at a given rung, without being a turn
ladder::move promote, demote, carry, drop or remove a primitive. Commits nothing
ladder::add scaffold a new primitive on the rung its level and script imply
ladder::refused the refusal event source. Private, observable: observe it, only this worker fires it
iii call ladder::list --json '{"repo":"/path/to/repo"}'
iii call ladder::evaluate --json '{"repo":"...","function_id":"shell::exec","arguments":{"command":"rm -rf /"},"rung":2}'
worker.observe("ladder::refused", "audit::on-refusal")

ladder::list reports measured_share: the fraction of primitives carried somewhere a machine records what they caught. It makes the gap visible and counted; it does not make feedforward reliable.

License

MIT. Repository: tacoda/ladder.

API reference (JSON)

agent-api-reference.json
{
  "functions": [
    {
      "description": "Scaffold a new primitive on the rung its level and its script imply",
      "metadata": {},
      "name": "ladder::add",
      "request_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      },
      "response_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      }
    },
    {
      "description": "Ask the ladder about a proposed write at a given rung, without being a turn",
      "metadata": {},
      "name": "ladder::evaluate",
      "request_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      },
      "response_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      }
    },
    {
      "description": "One primitive, and what each rung it names can actually see",
      "metadata": {},
      "name": "ladder::explain",
      "request_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      },
      "response_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      }
    },
    {
      "description": "pre-call hook: refuse a call that breaks a constraint, in its own words",
      "metadata": {},
      "name": "ladder::gate",
      "request_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      },
      "response_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      }
    },
    {
      "description": "Everything on the ladder, both sides, with rungs, direction and catches",
      "metadata": {},
      "name": "ladder::list",
      "request_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      },
      "response_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      }
    },
    {
      "description": "promote, demote, carry, drop or remove. One verb moves either side",
      "metadata": {},
      "name": "ladder::move",
      "request_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      },
      "response_schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object"
      }
    },
    {
      "description": "A constraint refused or held a call. Carries the primitive, the rung that caught it, the reason given to the model, and what the call was about. Observe it; only this worker fires it.",
      "metadata": {},
      "name": "ladder::refused",
      "request_schema": {},
      "response_schema": {}
    }
  ]
}

Search the registry

Find workers, kits and executables, or jump to a page.