Coding Ethos

Policy-as-code enforcement for AI agents: MCP server, CEL policies, Git hooks, SARIF, runtime sandboxing, and static-analysis guardrails.

coding-ethos turns engineering principles into runnable repository policy for human contributors and AI coding agents.

The project currently holds an OpenSSF Best Practices Silver badge and tracks Gold readiness in docs/OPENSSF_GOLD_CHECKLIST.md.

It keeps agent instructions, generated documentation, static-analysis config, Git hooks, agent tool-use guards, MCP tools, CEL custom policies, generated skills, and runtime axioms on one source contract. Human contributors and AI agents see the same standards, run the same checks, and hit the same critical safety gates before bad changes land.

Licensing

coding-ethos is dual-licensed to support both open-source and commercial ecosystems.

Open Source License: The software is available under the AGPLv3. This is ideal for open-source projects, academic use, and individuals.

Commercial License: If you wish to use coding-ethos in a proprietary or closed-source product without being bound by the copyleft requirements of the AGPLv3, we offer commercial licenses. Please contact [email protected] to discuss commercial licensing options.

Use coding-ethos when you need:

• AI-assisted workflow guardrails for Codex, Claude Code, Gemini CLI, and other coding tools.
• A local MCP server for policy checks, lint advice, SARIF remediation, and ETHOS-grounded context.
• Git hook enforcement that catches unsafe commands, protected path edits, unmanaged tool use, and file-growth problems before commit time.
• CEL policy-as-code that keeps repo-specific rules close to the ETHOS principle they enforce.
• SARIF and code-scanning output for CI, pull requests, IDEs, and trend analysis.
• Code intelligence that stores hook traces, SARIF, remediation outcomes, Tree-sitter chunks, AST links, and duckdb-vss metadata in a repo-local DuckDB store for code-intel search.
• A repo-local analytical code-intel index backed by append-only JSONL events and rebuildable DuckDB storage for downstream support analysis.
• Provider-agnostic memory routing that centralizes provider memory files under .coding-ethos/memories/ instead of scattering durable notes across Claude, Codex, and Gemini private state.

30-Second Start

make install
make check
make install-hooks

For full Git plus AI-agent hook cutover:

make cutover-install

Start the local MCP server for configured agents:

bin/coding-ethos-run mcp

The project is built around defense in depth for AI-assisted coding:

• ETHOS as source: coding_ethos.yml and repo overlays are the backbone: principles own their skills, axioms, generated docs, and first-class policy grounding.
• Compiled enforcement: Go hook runtimes evaluate built-in policies and typed CEL expression policies through the same decision model.
• Managed tools: lint and type checks run through generated configs, managed binaries, normalized diagnostics, and trace logging.
• Runtime capabilities: managed tools declare network, Git, sandbox, timeout, memory, CPU, and seccomp capabilities that CEL, MCP, traces, and SARIF can all inspect.
• Sandboxed capture: managed lint can run through the native sandbox helper with Linux namespace isolation, read-only repository and .git policy, disconnected network for offline tools, declared write paths, and normalized denial evidence.
• Agent steering: Claude, Codex, and Gemini receive generated hook settings, MCP server configuration, skills, prompt addenda, and compact axiom advice.
• Repair feedback: lint findings, blocked policy decisions, skill hints, and MCP guidance all point agents back to the relevant ETHOS contract.

Why It Matters

AI coding work fails hardest when guidance and enforcement drift apart:

• a Markdown rule says one thing
• a linter checks another thing
• a Git hook allows a third thing through
• an agent sees the mismatch and treats the safety system as broken

coding-ethos closes that gap by compiling the repo's working agreement into the places contributors actually work:

Agents Used In This Repository

coding-ethos is developed with human review and AI-agent assistance. The project explicitly targets and has been shaped by work with:

• Codex from OpenAI: coding, review, refactoring, documentation, and repo-policy workflow validation.
• Claude Code: coding, hook integration, generated skill surfaces, and policy feedback loops.
• Gemini CLI: review prompts, generated prompt packs, and independent agent-hook compatibility checks.

Agent assistance does not change the quality bar. Generated or agent-authored changes are expected to pass the same hooks, static analysis, tests, review feedback, and ETHOS policy gates as human-authored changes.

The project heavily dogfoods its own guardrails: Codex, Claude, and Gemini are run through the generated hooks, MCP configuration, skills, axioms, managed toolchain, and policy feedback surfaces while developing coding-ethos itself.

Defense In Depth

Policy is intentionally layered. No single hook, file, or agent instruction is trusted as the only line of defense.

coding_ethos.yml      repo_ethos.yml
       │                    │
       ├──── merged ethos ──┤
       │                    │
       ▼                    ▼
AGENTS.md / CLAUDE.md / GEMINI.md / ETHOS.md
.agents/ethos/ deep docs
.agent-context/ prompt addons
.agents/skills/ remediation playbooks
runtime axioms with MCP next steps
principle-owned CEL policies

config.yaml          repo_config.yaml
       │                    │
       ├── merged enforcement config
       │
       ├── generated tool configs
       ├── transitional CEL expression policies
       ├── Gemini prompt pack
       ├── Go policy bundle
       ├── Git hook runtime
       ├── agent hook runtime
       └── MCP server tools

The same inputs drive guidance and enforcement. Unknown linter findings still flow through normally; findings tied to ETHOS principles can receive stronger, policy-grounded advice instead of generic tool text. When a finding maps to a generated skill, agent-facing output includes a compact skill_id hint and a next action to load that remediation playbook.

Skills and axioms are part of the same defense-in-depth plan, not decorative prompt text. Skills provide provider-portable remediation playbooks. Axioms are short principle-local reminders that hooks surface when they are related to a policy decision, always on lint calls, and statistically on other post-hook events. Rendered axiom advice includes the MCP call an agent should use next, so advice can escalate from compact guidance to policy_explain, skill_lookup, or skill_recommend without dumping full context into every hook response.

CEL support extends that same model to repo-specific policy. First-class CEL policies live with the ETHOS principle they enforce in coding_ethos.yml. Config-level policy.expressions remains available for consumer overlays and for transitional policy that has not yet been expressed as part of the ETHOS contract. The compiler checks CEL up front, dispatches it through hook and lint paths, and emits normal policy decisions with ETHOS grounding and skill hints.

Source-aware policy follows the documented AST, CEL, and SARIF architecture. Go collects normalized Tree-sitter facts, CEL owns configurable policy predicates, and SARIF carries stable AST identity plus remediation metadata. The same facts feed hook preflight, lint policy, SARIF, MCP, and code-intelligence storage. New Python, Go, shell, JavaScript/TypeScript, YAML, JSON, TOML, or config policies should extend that path before adding ad hoc text scanners or policy-specific AST walkers.

Runtime capability policy uses the same path. Managed tools declare whether they need network, Git, environment access, writable paths, sandbox profiles, timeouts, memory, CPU, and seccomp profiles. Those facts are available to CEL as tool_capabilities, exposed through MCP, retained in .coding-ethos traces, and copied into SARIF run properties. The built-in managed-tool contract blocks ordinary lint tools that forget to declare offline/no-Git behavior or resource bounds.

Runtime sandboxing is the complementary data plane. The current Go runtime can run managed lint capture through a repo-owned native helper with Linux namespaces, Linux Landlock write policy for a read-only repository and .git, disconnected network for offline tools, declared writable paths, hard timeouts, cgroup resource requests, and seccomp profile metadata. Linux cgroup limits are prepared before process start in a delegated hierarchy and cleaned up after exit when the host delegates cgroup control. There is no operator sandbox mode: Linux runs sandbox-profiled managed tools through the native sandbox helper, and non-Linux platforms do not select Linux namespace sandboxing. On Linux, namespace creation is a hard gate; if the host kernel or policy blocks the native sandbox, managed sandboxed execution is blocked with runtime.sandbox_dependency or runtime.sandbox_denial diagnostics. Non-Linux platforms report that Linux namespace enforcement is not available and use the best available process execution evidence. See docs/RUNTIME_SANDBOXING.md.

Code-intelligence storage is the memory layer for this evidence. The repo-local DuckDB store ingests hook traces, lint traces, SARIF, remediation outcomes, hook usage analytics, Tree-sitter chunks, graph edges, AST-to-finding links, architectural decisions, decision links, and duckdb-vss metadata. Append-only .coding-ethos/events/*.jsonl files are the durable live telemetry surface, and .coding-ethos/code-intel.duckdb is the rebuildable analytical query index used by downstream support analysis. A DuckDB-resident term index provides exact search, while duckdb-vss stores derived embedding rows for hybrid retrieval without a daemon or hosted vector service. MCP tools expose search, code indexing, focused chunk lookup, decision rationale, embedding candidates, and index status so relevant context is available before broad file reads or repeated failed repairs. See docs/CODE_INTEL.md and docs/CODE_INTEL_STORAGE.md. Multi-repo workspaces add a separate .coding-ethos-workspace/ registry at a parent workspace root while keeping each repository's own code-intel DuckDB store independent.

Repository trust surfaces are part of the product. The public repo now carries CODEOWNERS, structured issue templates for policy rules, hook false positives, and MCP tool requests, GitHub Discussion templates, Dependabot cooldowns for all managed ecosystems, restricted Actions allow-lists, CodeQL, OSV-Scanner, zizmor, Scorecard, fuzz smoke, release attestations, and SBOM generation. See docs/TRUST_SIGNALS.md.

For larger platform directions such as deeper MCP context serving, policy-language support, IDE integration, SARIF/CI components, red-team testing, ETHOS inheritance, and agent remediation loops, see docs/STRATEGIC_ROADMAP.md. The documentation landing page is docs/index.md, and promotion/security trust work is tracked in docs/TRUST_SIGNALS.md. Supply-chain trust controls, Scorecard publishing, GitHub artifact attestations, SBOM generation, PyPI Trusted Publishing, and verification commands are documented in docs/SUPPLY_CHAIN_ATTESTATIONS.md. CI publishes JUnit XML, Python coverage, and Go coverage artifacts for public test evidence. The security posture is summarized in docs/THREAT_MODEL.md, and release readiness is documented in docs/RELEASE.md. The verified demo transcript is docs/DEMO.md. For positioning and adoption planning, see docs/COMPARISON.md, docs/INTEGRATIONS.md, and examples/. The CEL-first policy-language design is tracked in docs/POLICY_LANGUAGE_STRATEGY.md. CI/CD usage and SARIF upload examples are documented in docs/CI_CD_SARIF.md. Runnable and copyable examples start in examples/.

MCP Server

coding-ethos includes a local stdio MCP server backed by the same compiled policy bundle and generated skill metadata used by Git hooks and agent hooks. The design and expansion plan are documented in docs/MCP_SERVER.md. The server is exposed through the managed runtime:

bin/coding-ethos-run mcp

The first tools are intentionally narrow and auditable:

• policy_check_command: check a proposed shell command before running it.
• policy_check_edit: check a proposed file edit before applying it.
• cerun_check: preflight the exact command an agent should run through the cerun/agent-shell boundary without executing it.
• cerun_run: deliberately execute a command through the repo-local cerun wrapper and return captured output, exit status, and follow-up guidance.
• managed_lint: run managed lint capture for Ruff, mypy, pyright, pylint, ESLint, SQLFluff, and other captured tools; when no tool is supplied, run compiled coding-ethos policy lint checks for current work.
• lint_advice: map a lint diagnostic to ETHOS policy, advice, and skill hints.
• sarif_remediation_advice: turn SARIF or retained trace evidence into focused ETHOS-grounded repair guidance.
• sarif_risk_summary: summarize a SARIF run for policy, skill, file, tool, severity, and next-action risk signals.
• sarif_trend_analysis: compare SARIF runs or retained traces for introduced, fixed, persisting, reopened, and worsening findings.
• sarif_policy_feedback: report unmapped diagnostics, missing skills, weak severity mappings, and noisy rules for policy authors.
• tool_capabilities: list managed tool capabilities, including network/Git tags, sandbox profile, timeout, memory, CPU, seccomp profile metadata, and declared read/write paths.
• policy_explain: return the compiled explanation for a policy ID.
• skill_lookup: return an ETHOS-derived skill playbook by skill ID.
• remediation_explain: expand an emitted agent_remediation item into policy, principle, skill, and retry guidance.
• modern_web_guidance_search: search current advisory Modern Web Guidance through coding-ethos cache, provenance, and standard output handling.
• modern_web_guidance_retrieve: retrieve one or more Modern Web Guidance guides by ID without invoking upstream npx directly from agent prompts.
• modern_web_guidance_list: list available Modern Web Guidance guide IDs and categories with package provenance and cache status.
• code_intel_overview: return a task-shaped repository orientation with ranked files, freshness metadata, evidence counts, and exact follow-up MCP calls.
• code_intel_workspace_status: report registered workspace repositories, stale per-repo indexes, cross-repo co-change candidates, and conservative contract evidence.
• code_intel_search: retrieve stored SARIF/remediation/code-chunk evidence with the DuckDB term index and duckdb-vss vector search.
• code_intel_answer: retrieve cited code-intel evidence for a repository question with retrieval_quality separate from answer confidence.
• semantic_search: retrieve exact indexed repository code chunks by semantic query before broad grep or whole-file reads.
• code_intel_index_status: report DuckDB/duckdb-vss index freshness and embedding coverage.
• code_similarity_check: preflight proposed code against indexed repository symbols using normalized hashes and MinHash LSH.
• code_intel_repo_map: return a compact repository-wide AST map with ranked files, git-history hotspots, hidden couplings, symbols, and signatures for startup orientation.
• code_intel_context_card: compose a compact file/symbol triage card with chunks, graph context, linked findings, freshness, and follow-up MCP calls.
• code_intel_change_risk: summarize modification risk for target files from indexed chunks, git-history hotspots/co-changes, reviewer suggestions, repeated failures, and recommended checks.
• code_intel_health: rank deterministic refactoring targets from indexed structure, structural clones, git signals, LCOV coverage, and repeated failure evidence with persisted trend snapshots.
• code_intel_skill_health: report generated skill provenance, 7-day and 30-day usage windows, unused skills, frequently failing skills, improving skills, stale skills, and unknown skill IDs from remediation-outcome evidence.
• code_intel_why: return architectural decisions and decision-health signals for a query, path, symbol, or status before changing code.
• code_intel_session_snapshot: return the canonical coding_ethos.session.v1 snapshot derived from hook traces, proxy telemetry, memory activity, and code-intel freshness without broad source reads.
• code_intel_proxy_denials: explain stored proxy denial events by session, provider, or policy from the code-intel ledger.
• code_intel_index_code: refresh Tree-sitter chunks for Go, Python, JavaScript/TypeScript, shell, YAML, JSON, and TOML paths.
• code_intel_code_chunks: fetch focused symbol/config chunks before broad file reads.
• code_intel_code_context: expand a known chunk, symbol path, or file line into nearest AST context, graph edges, and linked findings.
• code_intel_embedding_candidates: return compact traceable records for an approved embedding producer.
• skill_recommend: recommend ETHOS-derived skills for the task at hand.

Hook, provider-native block responses, lint, SARIF, and trace outputs also include an agent_remediation payload when a violation can be explained. Each item carries a stable remediation ID, policy ID, ETHOS principle IDs, skill ID, failed action or file location, concrete next steps, rerun commands when known, and the next MCP call an agent should make. Agents can pass the full item to remediation_explain, or follow the embedded policy_explain or skill_lookup call directly. See Agent Remediation Payloads.

Tool definitions include coding_ethos metadata that tells clients whether a tool is advisory, reads files, executes managed tools, may mutate state, and persists traces. Agents should call managed_lint instead of invoking linters directly so target resolution, generated config integrity, managed tool versions, evidence maps, skill hints, and trace logging stay on the enforced path. When MCP is not available, use the repo-local wrapper:

bin/lint --staged
bin/lint --changed
bin/lint --full

Agents should call tool_capabilities before choosing a managed tool when runtime behavior matters; it is the MCP view of the same capability facts CEL uses for policy decisions.

The MCP server is advisory context, not a bypass. Hook enforcement remains on the normal Git and agent-hook paths, and MCP responses come from the same compiled policy inputs as those enforcement paths.

ETHOS Skills

Skills are generated remediation playbooks, not a separate hand-maintained documentation layer. coding_ethos.yml defines each skill with its ETHOS principles, trigger terms, short hint, focus, and remediation steps. make build renders those skills into the portable .agents/skills/ tree and the native Claude, Codex, and Gemini skill locations.

The compiled policy bundle carries the same skill metadata. Runtime lint and hook results attach a skill_id when a finding maps through an evidence map, overlaps a skill's ETHOS principles, or matches a skill trigger term. Agent-facing output stays compact: TOON and human output emit the skill ID, short hint, and next action instead of dumping the full skill body into the agent context.

Skill use and observable outcomes are measured in the repo-local code-intel store. skill_lookup and skill_recommend record unknown-outcome observations when a code-intel root is configured, explicit remediation outcomes record success or repeat failure, and skill-health/code_intel_skill_health report 7-day and 30-day trends. These reports are measurement-only: learned or evolved skills are not promoted into generated repo artifacts without a separate explicit policy change.

coding-ethos can also import retained lint and hook traces into a local DuckDB code-intelligence store for repeated-failure and remediation search:

bin/coding-ethos-run code-intel ingest-traces
bin/coding-ethos-run code-intel repeated-failures --policy-id python.unused_imports
bin/coding-ethos-run code-intel search --text 'unused import'
bin/coding-ethos-run code-intel git-signals --path pkg/app.py --paths pkg/app.py,pkg/store.py
bin/coding-ethos-run code-intel health --refresh --lcov coverage/lcov.info
bin/coding-ethos-run code-intel anatomy-map --path pkg --format toon
ls pkg | bin/coding-ethos-run code-intel enrich-listing --command 'ls pkg'
bin/coding-ethos-run code-intel repo-map --path pkg/app.py
bin/coding-ethos-run code-intel graph-report --path pkg --format toon
bin/coding-ethos-run code-intel centrality --path pkg --format toon
bin/coding-ethos-run code-intel surprises --path pkg --format toon
bin/coding-ethos-run code-intel decisions add --title 'Use explicit startup' --rationale 'Startup should be inspectable.' --path pkg/app.py
bin/coding-ethos-run code-intel decisions import docs/decisions
bin/coding-ethos-run code-intel decisions list --path pkg/app.py --query startup
bin/coding-ethos-run code-intel decisions health --path pkg/app.py
bin/coding-ethos-run code-intel rebuild-index
bin/coding-ethos-run code-intel hook-usage --risk-category bypass
bin/coding-ethos-run code-intel record-hook-review --trace-id hook-1 --disposition false_positive
bin/coding-ethos-run code-intel hook-reviews --disposition false_positive
bin/coding-ethos-run code-intel compact-context --path pkg/app.py
bin/coding-ethos-run code-intel proxy-file-read --session-id sess-1 --path pkg/app.py
bin/coding-ethos-run code-intel proxy-sessions --provider codex
bin/coding-ethos-run code-intel proxy-events --session-id sess-1
bin/coding-ethos-run code-intel session-snapshot --session-id sess-1 --format toon
bin/coding-ethos-run code-intel context-advice --session-id sess-1 --format toon
bin/coding-ethos-run code-intel repeated-edits --path pkg/app.py
bin/coding-ethos-run code-intel remediation-outcomes --outcome repeated
bin/coding-ethos-run code-intel remediation-effectiveness --policy-id python.unused_imports
bin/coding-ethos-run code-intel skill-health --format toon
bin/coding-ethos-run code-intel embedding-candidates --record-kind remediation_outcome
bin/coding-ethos-run code-intel embedding-records --backend duckdb-vss
bin/coding-ethos-run code-intel hybrid-search --text 'unused import' --model-id voyage-code-3 --vector '0.1,0.2,0.3'
bin/coding-ethos-run code-intel downstream-analysis --format toon

The live telemetry surface lives in .coding-ethos/events/*.jsonl, and the rebuildable analytical index lives at .coding-ethos/code-intel.duckdb. These repo-local artifacts are derived from retained traces, SARIF, AST chunks, proxy session events, remediation records, hook review labels, LCOV coverage, health snapshots, architectural decisions, and vector metadata. They are not replacements for hooks or CEL policy evaluation.

Modern Web Guidance

Modern Web Guidance is exposed as an advisory, latest-on-demand external guidance source. Agents should use the coding-ethos MCP tools first, or the CLI fallback when MCP is unavailable:

bin/coding-ethos-run web-guidance list
bin/coding-ethos-run web-guidance search "navigation drawer CSS popover"
bin/coding-ethos-run web-guidance retrieve navigation-drawer

The adapter resolves modern-web-guidance@latest only inside an explicit list, search, or retrieve operation. It stores response records and npm artifacts under .coding-ethos/cache/modern-web-guidance/, emits TOON by default, and includes package name, resolved version, dist-tag, fetch time, guide IDs, source URL, content hash, and cache status in every response. The guidance remains advisory: repo policy, user instructions, ETHOS, CEL policy, and local browser-support constraints stay authoritative.

Configure the integration in config.toml or a consuming repo's repo_config.toml:

[web_guidance.modern_web]
enabled = true
cache_ttl = "24h"
allow_network_refresh = true
browser_policy = ""

The recent code-intel graph work gives agents a richer orientation layer before they edit. graph-report combines repo-map ranking, store counts, stored health snapshots, provenance classes, deterministic topology communities, central node ranking, surprise edges, and Markdown document links. Markdown links are conservative: explicit repo path references produce documents edges, optional path#symbol fragments produce mentions, and rationale-like headings produce advisory rationale_for links. Extracted documentation references are DOC_DERIVED; rationale classification is INFERRED; neither class can permit or block policy decisions.

Decision intelligence adds the decisions CLI group and MCP code_intel_why tool. Manual decisions and indexed inline WHY:, DECISION:, and TRADEOFF: markers link rationale to paths and symbols, while decision health reports stale, conflicting, overlapping, or ungoverned areas before an agent edits. decisions import reads explicitly opted-in Markdown decision records from adr/, docs/adr/, docs/decisions/, .coding-ethos/decisions/, or a provided path. Imported records require YAML front matter with coding_ethos_decision: true or a decision / architecture-decision tag, so ordinary README examples and rationale headings are not promoted to decisions.

Managed sandbox policy also supports repo-specific network-capable test tools without making the whole suite networked. A consumer repo can list a managed tool such as go-test under sandbox.network_tools in repo_config.yaml when its real tests bind loopback sockets or otherwise require networking. Unlisted managed tools keep the default no-network sandbox posture.

downstream-analysis is the read-only support view for downstream repo ergonomics. It opens an existing code-intelligence database in read-only mode, scans retained hook logs, and reports hook friction, blocker trends, lint hotspots, affected command families for blocking policies, repeated remediation loops, large-file pressure, toolchain failures, stale code context, and DuckDB lock evidence without creating the store. When the database is missing or unavailable it still scans retained hook-run and lint-run logs for support signals. Use --format json|toon|human to choose between the stable automation payload, compact TOON handoff, or a short operator-readable summary. The compact output puts blocking friction, affected command families, repeated remediation loops, storage repair commands, and evidence gaps ahead of high-volume allowed events. rebuild-index refreshes the DuckDB analytical index from append-only events and retained event logs, then removes obsolete store files after rebuild.

Inspect the repo-local disk output surface before pruning or deeper analysis:

bin/coding-ethos-run status
bin/coding-ethos-run status --format json
bin/coding-ethos-run status --write status.md
bin/coding-ethos-run output report
bin/coding-ethos-run output report --format json --include-temp
bin/coding-ethos-run output prune --dry-run --all
bin/coding-ethos-run output prune --scope proxy_temp_evidence --older-than 24h --include-temp
bin/coding-ethos-run output prune --scope lint_traces --older-than 30d --apply
bin/coding-ethos-run output prune --scope code_intel_db --older-than 90d --apply --vacuum

The report is non-destructive. It inventories retained hook runs and component logs, lint traces, the code-intelligence database, sandbox/cache/state directories, Modern Web Guidance cache, runtime caches, local SARIF artifacts, prune traces, and optional OS temp evidence. Code-intelligence report rows include health snapshot, target, and LCOV coverage counts alongside trace, hook, proxy, and FTS row counts. The prune command uses the same registry, defaults to preview mode, refuses unknown surface IDs, skips symlinks, and requires --apply before deleting files. Retention policies support max_age, keep_last, max_bytes, code-intel row pruning through row_retention_days or --older-than, and optional --vacuum. Apply runs write .coding-ethos/prune-runs/*.json traces when they delete files, prune rows, vacuum, or hit errors. Output lifecycle defaults live in config.toml; consuming repos can override outputs.* in repo_config.toml without changing the existing YAML enforcement config path.

coding-ethos-run status is the operator handoff surface. It combines runtime artifact readiness, output-surface inventory, code-intel DuckDB stats, recent hook failures, hook-review and false-positive counts, stale/prunable surface counts, and recommended next actions into TOON, JSON, or human output. Use --write status.md when handing a repo to another operator or agent; blocker exit semantics remain reserved for command execution errors, while degraded local state is represented in the report's status field.

code-intel context-advice and status include context/token economy guidance only when advisory thresholds are crossed. The advisor reads the existing code-intel session snapshot, proxy events, token/compression counters, and output-surface inventory, then emits JSON or compact TOON recommendations for repeated file/listing reads, tool-call pressure, stale or spilled outputs, truncation/compression, and high session token volume. SessionStart receives the same compact advice block only when there is actionable pressure. Configure thresholds under proxy.context_advisor in repo_config.yaml; these heuristics are advisory and do not participate in enforcement decisions. Pass --include-temp to code-intel context-advice when the operator needs OS temp spill evidence included in the count.

Code-intel maintenance treats database files as derived indexes and evidence logs as durable audit material. Automatic maintenance prunes old DuckDB rows, checkpoints and compacts the DuckDB index, removes stale DuckDB sidecar files, applies the explicit .coding-ethos/events age/count/size budget, and validates .coding-ethos/code-intel-rebuild.lock by PID before clearing stale locks. If the host cannot answer PID liveness, cleanup falls back to the configured stale lock age, so a dead rebuild process does not block later maintenance. Live DuckDB database files are report-only prune candidates: oversized stores are surfaced for operators, while the automated path uses row retention, checkpointing, compaction, and sidecar cleanup instead of deleting active indexes.

The directory anatomy map is inspired by Aider's repo map: agents get a compact symbol preview before deciding which files to open, while coding-ethos keeps the repo-local Go AST index as the source of truth. The proxy transform preserves the original directory listing and appends a compact TOON anatomy block with normal in-memory transform evidence. Successful Bash ls and tree PostToolUse outputs are conservatively recognized through the shell parser, refreshed against the repo-local AST index, and emitted as live proxy context with a proxy.directory_anatomy event. ls listings stay directory-local; tree listings refresh recursive source files, and tree -L N caps the anatomy map at the same displayed depth. enrich-listing remains the runnable CLI bridge for applying the same append-only transform to captured listing output; it does not persist a proxy event by itself.

At SessionStart, the hook runtime refreshes the repo-local AST index and injects a compact coding_ethos_repo_map when source facts are available. The same map is exposed through MCP as the code_intel_repo_map tool and the coding-ethos://code-intel/repo-map resource, so agents can refresh or expand startup orientation without broad directory listings or whole-file reads.

The proxy-file-read bridge records session-scoped file read cache evidence in the same proxy ledger. The first unchanged read records a normal file_read event with the file content hash. A later read of the same path in the same session recomputes the file hash and, when it still matches, records a cache_hit event and returns a short cached-read stub instead of resending the file body. This is the reusable core for future transparent read interception.

bin/coding-ethos-run agent-proxy passthrough --upstream <url> --listen 127.0.0.1:<port> starts the baseline Agent API proxy. This mode preserves provider requests and responses without payload inspection, mutation, blocking, TLS interception, CA installation, or trust-store changes. Agent proxy routing is not exported by coding-ethos unless CODE_ETHOS_AGENT_API_PROXY=1 and CODE_ETHOS_AGENT_API_PROXY_URL=<proxy-url> are both set; pre-existing operator proxy environment variables remain ordinary inherited process environment. The status report includes agent_api_proxy, and pass-through requests record body-free proxy.pass_through evidence with payload_body_retained=false.

When the sandboxed agent shell receives explicit proxy routing or interception CA trust, sandbox evidence records only the injected variable names in env_bindings; proxy URLs and CA paths are not copied into the evidence.

Agent search, glob, and read PostToolUse hooks add compact code-intel enrichment when the repo-local index is available. The TOON hint includes detected repo paths, likely symbols, direct graph edges, repeated-failure evidence, risk flags, and exact MCP follow-up calls such as code_intel_context_card {"path":"pkg/app.py"}. Missing or stale code-intel does not block the tool result; the hook emits a concise refresh hint with coding-ethos-code-intel rebuild-index. Repositories can disable or cap this context with proxy.code_intel_enrichment in repo_config.yaml.

PreToolUse hooks also perform narrow semantic policy injection. Mutating Git intents such as policy-git commit inject the safe-git-workflow skill pointer and policy-git reminder only for that turn. File-target tool calls that name Python files inject compact Python static-analysis guidance and the relevant skill pointer instead of front-loading every Python policy into startup context. Read-only Git inspection commands stay quiet.

Provider-native file read tools are the supported path for reading source. Claude-style Bash file-tool emulation such as cat <path>, sed -n '1,20p' <path>, awk ... <path>, tee <path>, and echo/printf write-redirection forms are blocked before execution so the provider preserves