makoto 0.1.0

MAKOTO: Mission Integrity for Autonomous Agent Swarms

MAKOTO

Your AI agent should not be able to deploy production just because it can call a tool.

MAKOTO gives agents signed, bounded missions. A tool runs only when the agent brings a valid proof-carrying tool call.

agent: deploy production
tool:  DENIED - missing signed work order

MAKOTO is not another agent framework. It is the missing control layer for agent frameworks.

Agents do not get broad permissions. They get signed missions.

Install

python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python examples/deploy_denied_demo.py

Expected:

DENIED: Tool is explicitly forbidden: deploy_production
BLOCKED BY TOOL: Tool deploy_production requires a MAKOTO proof

Or run the one-file copy-paste demo:

python3 examples/one_file_demo.py

Why This Exists

Most agent frameworks answer:

How can an agent complete this task?

MAKOTO answers:

Is this agent allowed to run this tool, for this mission, right now?

That difference matters when agents can merge code, send email, move money, close accounts, rotate secrets, call APIs, or deploy production.

What OSS Includes

• MissionCampaignPermit
• SignedWorkOrder
• ProofCarryingToolCall
• OutcomeRecord
• signed audit events
• resource conflict locking
• campaign replay
• local SQLite ledger for development
• @protected_tool(...) decorator
• dangerous tool catalog with risk scores
• CLI: makoto demo, makoto wrap, makoto explain, makoto score, makoto check, makoto init, makoto sign, makoto verify, makoto export-schemas
• release helpers: makoto version, makoto doctor
• dependency-free adapters for OpenAI-style, Claude-style, Gemini-style, LangGraph-style, CrewAI-style, and AutoGen-style tool calls

What MAKOTO Is Not

• Not an agent framework
• Not a sandbox
• Not a production gateway by itself
• Not a compliance certification

MAKOTO OSS is the protocol, SDK, verifier, and local enforcement reference.

30-Second Demo

makoto demo
makoto demo --short
python3 examples/one_file_demo.py

The default demo uses a generic pull-request safety workflow: an AI agent may read CI logs and run tests, but it cannot merge, deploy, or rotate secrets without a signed work order that allows those tools.

Create A Quickstart Project

makoto init my-makoto-demo
cd my-makoto-demo
python app.py

Public Use Cases

The OSS examples are intentionally neutral and useful for most developers:

• CI / Pull Request Safety: read logs and run tests, but do not merge or deploy.
• Research Agent Safety: read notes and write summaries, but do not send email.
• Finance Review Safety: draft approval notes, but do not send payments.
• Customer Support Safety: draft replies, but do not issue refunds.

Run them:

python3 examples/one_file_demo.py
python3 examples/deploy_denied_demo.py
python3 examples/local_agent_loop.py
python3 examples/ci_safety_demo.py
python3 examples/research_safety_demo.py
python3 examples/finance_safety_demo.py
python3 examples/customer_support_safety_demo.py
python3 examples/openai_style_adapter_demo.py
python3 examples/claude_style_adapter_demo.py
python3 examples/gemini_style_adapter_demo.py
python3 examples/framework_adapter_demo.py

Connect It To Your Agent

MAKOTO works with any setup where your application receives a tool call and then executes it:

• local Python agents
• local LLMs through Ollama, llama.cpp, vLLM, or custom runners
• OpenAI-style tool calling
• Claude-style tool calling
• Gemini-style function calling
• LangGraph / CrewAI / AutoGen
• MCP servers

Pattern:

model requests tool -> MAKOTO authorizes -> protected tool verifies -> tool runs

See docs/INTEGRATIONS.md.

Wrap Any Command

Use makoto wrap to put a local command behind a MAKOTO tool check.

Without a signed work order, the command is denied and a denial explanation JSON is written to /tmp:

makoto wrap --tool deploy_production -- echo "deploying..."
makoto explain /tmp/makoto_denied_deploy_production.json

For local demos, --allow-dev creates a short-lived development mission first:

makoto wrap --tool run_tests --allow-dev -- python3 -c "print('tests passed')"

Production tools should verify MAKOTO_PROOF or use @protected_tool(...) inside the tool boundary.

Safety Score

Score how much MAKOTO coverage a local project has:

makoto score

The score checks for dangerous tool names, @protected_tool(...) usage, campaigns, signed work orders, proof-carrying tool calls, and recorded outcomes.

Minimal Code

from makoto import MakotoClient, protected_tool

client = MakotoClient()

# After creating a campaign and signed work order:
proof = client.authorize_tool_call(
    work_order_id=work_order.work_order_id,
    agent_id="ci-agent-01",
    tool_name="run_tests",
    tool_input={"pull_request": 42},
)

@protected_tool("run_tests", client)
def run_tests(*, tool_input):
    return {"passed": True}

run_tests(tool_input={"pull_request": 42}, makoto_proof=proof)

Core Rule

Tools should execute only after verifying a proof-carrying tool call:

if not client.verify_tool_call(proof):
    raise PermissionError("Missing valid MAKOTO proof chain")

Or wrap a Python tool directly:

from makoto import protected_tool

@protected_tool("run_tests", client)
def run_tests(*, tool_input):
    return {"passed": True}

run_tests(tool_input={"pull_request": 42}, makoto_proof=proof)

Protocol Verification

The CLI can validate MAKOTO protocol objects without running the enterprise gateway:

makoto verify campaign examples/campaign.json

If you also provide the development HMAC secret used to sign the object, the CLI verifies the signature:

MAKOTO_HMAC_SECRET=dev-secret makoto sign campaign examples/campaign.json --out /tmp/campaign.signed.json
MAKOTO_HMAC_SECRET=dev-secret makoto verify campaign /tmp/campaign.signed.json

Export JSON Schemas

makoto export-schemas ./schemas

Open-Core Boundary

Open source:

• protocol objects and schema export
• canonical JSON and hashing
• basic local signer/verifier
• local SDK and SQLite development ledger
• @protected_tool(...) local enforcement example

Commercial:

• non-bypassable gateway
• Cedar/OPA policy engine
• MCP tool proxy
• enterprise Postgres ledger
• swarm routing, conflict management, and witness orchestration
• ATC dashboard
• regulatory/causal/learning layers

The current default signer is an HMAC development signer so the core runs without external dependencies. The signer boundary is explicit and can be replaced with Ed25519/KMS/HSM in production.