fermata/CLAUDE.md

Package: dirigent_fermata

Harness-agnostic secret redaction engine and policy gate for AI coding agents.

Quick Facts

• Type: Library + binary (fermata)
• Main Entry: src/lib.rs, src/bin/fermata.rs
• Dependencies: ignore, toml, regex, globset, serde, clap (cli feature), aho-corasick, serde_yaml
• Status: v0.2 — secret redaction + policy gate (.botsecrets now includes [policy] section)

Layering

Three concentric layers; nothing inner imports from anything outer.

• core/ — harness-unaware, transport-unaware, sync. Types (Op, Decision), .botignore walker, Policy::check / check_command, path extraction. .botsecrets contains a [policy] section for access control rules (fermata.toml is accepted as an alias for .botsecrets). Sync, no tokio.
  • core/secrets/ — the secret filtering engine:
    • config.rs — .botsecrets TOML parser (SecretsConfig, PolicyConfig) and hierarchical resolution (user, project, local override).
    • manifest.rs — discovers secret-containing files from .botsecrets patterns and loads their content for redaction.
    • parser.rs — multi-format secret file parser (.env, TOML, YAML, JSON). Extracts key-value pairs where the value is a secret.
    • patterns.rs — built-in key name patterns (~30 universal patterns like *_KEY, *_SECRET, *_PASSWORD) and gitleaks-derived regex patterns for heuristic scanning.
    • redactor.rs — Redactor builds an Aho-Corasick automaton from known secret values and replaces them in arbitrary text. Sub-millisecond performance.
    • scanner.rs — Scanner applies heuristic regex patterns to detect secrets not covered by the known-value manifest (entropy-based and format-based detection).
• harness/ — HarnessAdapter trait over a normalized ToolCall (PreToolUse) and PostToolUsePayload (PostToolUse). Each adapter (Claude, future Codex, etc.) lives in its own submodule, feature-gated. PostToolUse enables output redaction via updatedToolOutput before content enters the LLM context.
• bin/fermata.rs — only place where clap, stdio, and exit codes appear.

Release Model

Developed in this monorepo; planned to be exported as a standalone repo in the future for advertising / external distribution. Development stays here. See docs/tools/fermata.md.

Dependency Direction

dirigent_tools depends on dirigent_fermata, never the reverse. Fermata must remain usable as a standalone hook/MCP without dragging in the in-process ACP tool runtime.

Out of scope (v0.2)

Codex / Gemini hook adapters, MCP server mode, readonly_only Bash mode, audit log, filesystem watcher, context taint tracking. Each is a future task with its own plan.

See also

• docs/tools/fermata.md — Dirigent integration plan
• docs/workpad/brainstorm/fermata.md — canonical product spec
• docs/architecture/fermata-security-philosophy.md — security philosophy and the reveal triangle
• .botsecrets format: core/secrets/config.rs — unified config for secret redaction and policy (fermata.toml accepted as alias)