_{The gold dust unmaking the parchment is the gommage. The three pendants below are pictos — signed, single-use grants.}

gommage

« ce qui n'a pas lieu d'être, s'efface. »

Gommage is a deterministic policy and audit layer for matched AI coding-agent tool calls. It evaluates declarative YAML rules, records signed audit evidence, and can require a short-lived signed grant for an exceptional action.

What it does

Gommage maps an observed tool call to capabilities such as git.push:refs/heads/main, fs.write:**/.git/**, or net.out.post. Capability mapping and ordered policy evaluation are deterministic: the same observed call and policy produce the same policy decision regardless of call order or host OS. Picto lookup and consumption are explicit authorization state, so an active, expired, or spent grant changes the final authorization result by design.

An ask_picto rule creates a durable approval request when there is no matching grant. A picto is signed, time-limited, usage-bounded, revocable, and consumed atomically. Every decision and approval event is recorded in the signed audit log.

Gommage is public beta software. Start with a non-critical repository, inspect generated policy before relying on it, and use the beta contract as the source for supported claims: beta contract.

What it does not do

Gommage is a policy decision and audit layer. It does not provide OS-level confinement, mediate every process action, or replace your agent's native permissions.

Keep the controls that already protect your machine:

• Claude Code's native permissions and any host controls you use.
• Codex sandboxing, especially for filesystem and network boundaries outside matched hook events.
• Your existing approval and review process for changes with real consequences.

The exact coverage boundary and threat assumptions are documented in the threat model.

Supported hosts

The release installer supports macOS and Linux. Windows is not currently supported.

Host	Default Gommage coverage	Keep enabled
Claude Code	Bash, file tools, WebFetch / WebSearch, and emitted mcp__… tool names	Native permissions and any OS confinement in use
OpenAI Codex CLI	Bash, parsed apply_patch paths, and emitted mcp__… tool names	Codex sandboxing for boundaries outside matched hook events

Both integrations use the same YAML policies, signed audit trail, and picto store. Coverage is limited to tool calls that the host emits through a matched hook event. Claude Code can surface an approval request in its flow. Codex currently returns a denial for a picto-required call with no matching grant because its hook flow has no interactive approval step.

Read the host-specific boundaries before rollout: Claude Code, Codex, and the compatibility guide.

Try it first

From a checkout, run the isolated demo:

sh scripts/launch-demo.sh

It uses a temporary home and captures an allow, a picto-required action, one-use picto consumption, a hard-stop denial, signed-audit verification, policy fixtures, and a health snapshot. It does not change your real agent configuration.

The demo output and recording guide are in examples/launch-demo.

Install and quickstart

The recommended install path uses signed GitHub Release binaries. The installer verifies Sigstore provenance and SHA-256 before extraction.

curl --proto '=https' --tlsv1.2 -sSf \
  https://raw.githubusercontent.com/Arakiss/gommage/main/scripts/install.sh | sh

For a new host, choose the agent you use:

# Claude Code
gommage quickstart --agent claude --daemon --self-test

# OpenAI Codex CLI
gommage quickstart --agent codex --daemon --self-test

Then verify the installed path:

gommage verify --json

quickstart --agent codex writes the Codex hook configuration. Open a new Codex session after setup so it loads that configuration.

Existing machines

Gommage adds its integration without replacing unrelated host hooks by default. Inspect the local plan before changing a mature setup:

gommage harness diagnose --json
gommage quickstart --agent claude --daemon --dry-run --json
gommage quickstart --agent codex --daemon --dry-run --json

The existing setups guide explains coexistence, backups, rollback, dual-agent runs, and MCP gateway scope. For full installation choices, pinned releases, source builds, and updates, see updating and release signing.

Policy in one rule

Policies live in ~/.gommage/policy.d/. Rules are ordered; keep them narrow and add a fixture for each intended behavior.

- name: gate-main-push
  decision: ask_picto
  required_scope: "git.push:main"
  bind_input: true
  match:
    any_capability:
      - "git.push:refs/heads/main"
      - "git.push:refs/heads/master"
  reason: "pushes to main require review of the exact observed tool call"

bind_input: true is available only with ask_picto. It binds the resulting picto to the canonical hash of the observed tool call, so a grant for one observed input cannot authorize a different call in the same scope. The default is false for compatibility with existing scope-bound policies.

Use gommage map --json to inspect capabilities before writing a rule, and test policy intent with a fixture:

gommage policy test examples/policy-fixtures.yaml --json

The policy cookbook covers common patterns, precedence, and regression fixtures. The Picto guide covers direct grants, approval requests, callbacks, revocation, and exact-input grants.

How a decision flows

matched tool call
  -> capability mapping
  -> ordered YAML policy
  -> allow | deny | ask_picto
  -> signed audit evidence

For ask_picto, Gommage creates or reuses the relevant pending approval request. Approval can mint either a scope-bound picto or, when the rule asks for it, an exact-input picto. A hard stop always remains denied; a picto never bypasses it.

Documentation

Need	Read
Beta scope, guarantees, and exclusions	Beta contract
Threat assumptions and hard-stop boundary	Threat model
Claude Code and Codex coverage	Agent compatibility
Existing hooks, migration, rollback	Existing setups
Rules, precedence, and fixtures	Policy cookbook
Grants, approvals, callbacks, and revocation	Pictos
Health checks and support evidence	Diagnostics
Binary provenance and release verification	Release signing
Architecture and state index	Architecture
Planned work	Roadmap

Agents should use the repository's Gommage skill and inspect gommage harness diagnose --json or gommage harness explain before making claims about a specific machine.

Contributing

Read CONTRIBUTING.md for the determinism contract, policy-fixture rules, local checks, and release process. Report security issues through SECURITY.md.

Acknowledgements

The name and terminology are a tribute to Clair Obscur: Expedition 33 by Sandfall Interactive. Gommage is an independent project and has no affiliation with Sandfall Interactive.

License

MIT