# https://github.com/paudley/coding-ethos Project Manual
Generated at: 2026-06-19 16:47:39 UTC
## Table of Contents
- [Project Overview & Architecture](#page-1)
- [Policy Enforcement, MCP & Agent Hooks](#page-2)
- [Code Intelligence & Telemetry Storage](#page-3)
- [Runtime Sandboxing, Managed Tools & Security](#page-4)
## Project Overview & Architecture
### Related Pages
Related topics: [Policy Enforcement, MCP & Agent Hooks](#page-2), [Code Intelligence & Telemetry Storage](#page-3)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/paudley/coding-ethos/blob/main/README.md)
- [coding_ethos.yml](https://github.com/paudley/coding-ethos/blob/main/coding_ethos.yml)
- [coding_ethos/CODING_ETHOS.md](https://github.com/paudley/coding-ethos/blob/main/coding_ethos/CODING_ETHOS.md)
- [ETHOS.md](https://github.com/paudley/coding-ethos/blob/main/ETHOS.md)
- [AGENTS.md](https://github.com/paudley/coding-ethos/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/paudley/coding-ethos/blob/main/CLAUDE.md)
# Project Overview & Architecture
## Purpose and Scope
`coding-ethos` is a governance, policy, and agent-routing framework for software projects. It provides a structured way to encode engineering standards, route work to specialized agents, and capture remediation evidence. The repository acts as both a reference implementation and a configuration backbone that other projects can adopt to enforce consistent development practices.
The project is documented across several layered entry points. [README.md](https://github.com/paudley/coding-ethos/blob/main/README.md) serves as the top-level orientation, while [coding_ethos/CODING_ETHOS.md](https://github.com/paudley/coding-ethos/blob/main/coding_ethos/CODING_ETHOS.md) and [ETHOS.md](https://github.com/paudley/coding-ethos/blob/main/ETHOS.md) capture the normative rules of the "ethos." Agent-facing guidance is split between [AGENTS.md](https://github.com/paudley/coding-ethos/blob/main/AGENTS.md) and [CLAUDE.md](https://github.com/paudley/coding-ethos/blob/main/CLAUDE.md), which give different autonomous agents consistent operational instructions. Source: [README.md:1-40](https://github.com/paudley/coding-ethos/blob/main/README.md).
The latest release, **v0.3.0**, introduced hardened policy extension seams, remediation evidence payloads, centralized agent routing, and persistent remediation storage in the code-intel subsystem. Source: [community release notes (v0.3.0)](https://github.com/paudley/coding-ethos/blob/main/README.md).
## High-Level Architecture
The system is organized around four cooperating concerns: **policy**, **agents**, **hooks**, and **code-intel**. Policy documents define what is allowed; agents perform the work; hooks intercept and route operations; and code-intel stores evidence that work was actually done correctly.
```mermaid
flowchart LR
A[Developer / CI] --> B[Hooks Layer]
B --> C{Agent Router}
C --> D[Policy Agent]
C --> E[Code Intel Agent]
C --> F[Remediation Agent]
D --> G[(Policy Seams)]
E --> H[(Code Intel Store)]
F --> I[(Evidence Payloads)]
G --> A
H --> A
I --> A
```
The configuration root is [coding_ethos.yml](https://github.com/paudley/coding-ethos/blob/main/coding_ethos.yml), which the hooks layer reads to decide how to dispatch work. Source: [coding_ethos.yml:1-60](https://github.com/paudley/coding-ethos/blob/main/coding_ethos.yml).
## Core Subsystems
### Policy and Extension Seams
The policy subsystem encodes the project's engineering standards. The v0.3.0 release specifically hardened "policy extension seams" so that custom rules can be plugged in without rewriting core logic. This makes the policy layer a stable contract that downstream consumers can extend. Source: [PR #38 release notes](https://github.com/paudley/coding-ethos/blob/main/README.md).
### Agent Layer
The agent layer is split across multiple focused agents (policy, code-intel, remediation, etc.). Each agent has a defined contract described in [AGENTS.md](https://github.com/paudley/coding-ethos/blob/main/AGENTS.md), while agent-specific instructions for Claude-based agents live in [CLAUDE.md](https://github.com/paudley/coding-ethos/blob/main/CLAUDE.md). The v0.3.0 release added structured **remediation evidence payloads** so agents can prove that a fix was applied, not just claimed. Source: [PR #39 release notes](https://github.com/paudley/coding-ethos/blob/main/README.md).
### Hooks and Routing
The hooks subsystem centralizes agent routing and code-intel dispatch. Rather than scattering routing logic across individual agents, v0.3.0 moved this concern into a single, auditable layer. This reduces duplicate routing code and gives operators one place to add or modify dispatch behavior. Source: [PR #40 release notes](https://github.com/paudley/coding-ethos/blob/main/README.md).
### Code Intel and Evidence Storage
The code-intel subsystem stores remediation outcomes and other intelligence gathered during agent runs. In v0.3.0, this store became the canonical home for remediation evidence, making it queryable for audits and downstream tooling. Source: [PR (code-intel remediation) release notes](https://github.com/paudley/coding-ethos/blob/main/README.md).
## Configuration Surface
| File | Role | Read by |
|---|---|---|
| `coding_ethos.yml` | Root configuration: agents, hooks, policies | Hooks layer, agent router |
| `coding_ethos/CODING_ETHOS.md` | Normative coding standards | All agents |
| `ETHOS.md` | Top-level ethos statement | Humans and agents |
| `AGENTS.md` | Agent contracts and behavior | All agents |
| `CLAUDE.md` | Claude-specific operational guidance | Claude-based agents |
Configuration is intentionally hierarchical: the YAML file controls *mechanics*, while the Markdown files control *values and behavior*. This split lets operators tune dispatch without editing prose, and lets maintainers update guidance without breaking machine-readable config. Source: [coding_ethos.yml:1-30](https://github.com/paudley/coding-ethos/blob/main/coding_ethos.yml); [ETHOS.md:1-20](https://github.com/paudley/coding-ethos/blob/main/ETHOS.md).
## Common Failure Modes
- **Policy drift**: when `coding_ethos/CODING_ETHOS.md` and `AGENTS.md` disagree, agents may follow stale guidance. The hardened seams in v0.3.0 aim to surface these conflicts at extension time. Source: [PR #38 release notes](https://github.com/paudley/coding-ethos/blob/main/README.md).
- **Missing evidence**: remediation steps that do not produce a structured evidence payload are not stored in code-intel, breaking audit trails. Source: [PR #39 release notes](https://github.com/paudley/coding-ethos/blob/main/README.md).
- **Routing duplication**: pre-v0.3.0, routing logic was scattered; the centralized hooks layer now requires removing redundant route definitions during upgrades. Source: [PR #40 release notes](https://github.com/paudley/coding-ethos/blob/main/README.md).
## See Also
- [Coding Standards & Ethos](coding-ethos-standards.md)
- [Agent Contracts](agents.md)
- [Hooks and Routing](hooks-routing.md)
- [Code Intel Store](code-intel.md)
---
## Policy Enforcement, MCP & Agent Hooks
### Related Pages
Related topics: [Project Overview & Architecture](#page-1), [Code Intelligence & Telemetry Storage](#page-3)
Related Source Files
The following source files were used to generate this page:
- [go/internal/policy/compiler.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/policy/compiler.go)
- [go/internal/mcp/server.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/mcp/server.go)
- [go/internal/hooks/runner.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/hooks/runner.go)
- [go/internal/agentproxy/intercept.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/agentproxy/intercept.go)
- [go/internal/agentmsg/remediation.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/agentmsg/remediation.go)
- [go/internal/evaluators/evaluator.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/evaluators/evaluator.go)
# Policy Enforcement, MCP & Agent Hooks
## Overview
The `coding-ethos` repository defines a layered governance model in which three subsystems cooperate to keep agent-driven code generation aligned with project rules. The **policy enforcement** layer compiles declarative policy modules and evaluates actions against them; the **MCP server** exposes those policies (and code-intelligence lookups) as Model Context Protocol tools; and the **agent hooks** subsystem intercepts agent invocations, routes them through the appropriate code-intel and remediation pipelines, and records evidence of any corrective actions taken.
This triad was the focus of the v0.3.0 release, which hardened policy extension seams (PR #38), added remediation evidence payloads (PR #39), and centralized agent routing and code-intel inside the hooks runner (PR #40). Together, these changes turn a loose set of checkers into a deterministic enforcement pipeline.
## Policy Enforcement
### Policy Compiler
The compiler is the entry point for converting human-authored policy modules (Solidity-style or DSL configurations bundled with the project) into an in-memory representation that evaluators can consume. The compiler is intentionally narrow in scope: it parses, validates, and emits a normalized rule set. Extension seams added in v0.3.0 expose stable interfaces so that downstream consumers — primarily the MCP server and the hooks runner — can attach custom rule providers without modifying the compiler core. Source: [go/internal/policy/compiler.go]()
### Evaluators
Evaluators consume the compiled policy graph and answer the question *"is this proposed action allowed?"* for a given agent request. They are invoked both synchronously (during MCP tool calls that need a precondition check) and asynchronously (when the hooks runner batches decisions for a multi-step agent workflow). The evaluator contract returns a structured verdict rather than a boolean so the hooks runner can attach remediation hints. Source: [go/internal/evaluators/evaluator.go]()
## MCP Server
The MCP server surfaces coding-ethos capabilities to external agents that speak the Model Context Protocol. It registers tools backed by the policy compiler and the code-intel index, and it delegates every privileged operation through the evaluator before returning a response. Because MCP clients expect schema-strict payloads, the server is the canonical place where policy verdicts and remediation evidence are serialized for transit. Source: [go/internal/mcp/server.go]()
The server is stateless with respect to long-lived agent sessions; conversation context lives in the hooks runner, which forwards only the slice of state the MCP tool needs for a single call.
## Agent Hooks and Routing
### Hook Runner
The hooks runner is the orchestration layer. It is invoked by `agentproxy` for every agent lifecycle event (pre-tool, post-tool, on-error) and is responsible for:
1. Resolving which code-intel index slice is relevant for the current working directory.
2. Routing the request to the appropriate MCP tool or local evaluator.
3. Capturing the verifier response and, if needed, asking `agentmsg` to attach a remediation evidence payload.
4. Emitting a normalized audit record.
Centralizing this routing inside the runner (PR #40) removed duplicated routing logic that previously lived in each hook implementation. Source: [go/internal/hooks/runner.go]()
### Agent Proxy Intercept
`agentproxy` sits between the agent runtime and the tool implementations. The intercept layer's job is to enrich raw tool invocations with the context (file paths, diff hunks, working directory) that evaluators require. It is deliberately thin so that policy decisions remain attributable to the evaluator rather than the transport layer. Source: [go/internal/agentproxy/intercept.go]()
## Remediation Evidence
When an evaluator returns a non-compliant verdict, the system does more than reject the action — it produces a remediation evidence payload that tells the agent exactly which rule was violated and what corrective action would satisfy it. PR #39 introduced first-class payloads in `agentmsg` so that remediation hints are durable, versionable, and consumable by both the MCP server and downstream code-intel storage. Source: [go/internal/agentmsg/remediation.go]()
## End-to-End Flow
```mermaid
sequenceDiagram
participant Agent
participant Proxy as agentproxy/intercept
participant Runner as hooks/runner
participant MCP as mcp/server
participant Eval as evaluators
participant Remed as agentmsg/remediation
Agent->>Proxy: tool invocation
Proxy->>Runner: enriched event + context
Runner->>MCP: route to MCP tool
MCP->>Eval: evaluate policy
Eval-->>MCP: verdict (allow/deny + hints)
alt denied
MCP->>Remed: build evidence payload
Remed-->>Runner: remediation record
Runner-->>Proxy: reject with payload
else allowed
Runner-->>Proxy: allow + audit record
end
Proxy-->>Agent: final response
```
## Common Failure Modes
- **Compiler extension regressions**: custom rule providers compiled against an older seam may fail to register. Pin to the v0.3.0 seam interface when extending the compiler. Source: [go/internal/policy/compiler.go]()
- **Evaluator timeouts on large diffs**: evaluators may exceed MCP client timeouts when validating large generated files. The hooks runner batches decisions for multi-step workflows to mitigate this, but single-shot MCP calls should remain bounded. Source: [go/internal/evaluators/evaluator.go]()
- **Missing remediation payload**: if a hook bypasses the runner (legacy code paths), the response will lack the remediation evidence produced by `agentmsg`. Always route through `hooks/runner`. Source: [go/internal/agentmsg/remediation.go]()
## See Also
- Project README for the high-level ethos and policy authoring guide.
- Wiki page on Code Intelligence and the remediation index (referenced by PR #40's code-intel changes).
- v0.3.0 release notes for the motivating PRs #38, #39, and #40.
---
## Code Intelligence & Telemetry Storage
### Related Pages
Related topics: [Policy Enforcement, MCP & Agent Hooks](#page-2), [Runtime Sandboxing, Managed Tools & Security](#page-4)
Related Source Files
The following source files were used to generate this page:
- [go/internal/codeintel/duckdb_store.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/codeintel/duckdb_store.go)
- [go/internal/codeintel/event_log.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/codeintel/event_log.go)
- [go/internal/codeintel/sarif.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/codeintel/sarif.go)
- [go/internal/codeintel/decisions.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/codeintel/decisions.go)
- [go/internal/codeintel/repo_map.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/codeintel/repo_map.go)
- [go/internal/astfacts/astfacts.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/astfacts/astfacts.go)
# Code Intelligence & Telemetry Storage
## Overview
The `codeintel` package is the persistent substrate of `coding-ethos`. It captures every signal the agent emits while auditing or remediating a repository — scanner output, policy decisions, AST-derived facts, and repository metadata — and stores them in a local [DuckDB](https://duckdb.org/) database so that subsequent runs, reports, and review sessions can query the same canonical history. Source: [go/internal/codeintel/duckdb_store.go]()
In release v0.3.0 the telemetry layer gained two notable capabilities that surface in this page: structured **remediation evidence payloads** carried by the agent (`feat(agent): add remediation evidence payloads`, PR #39) and a **centralized routing** layer that funnels agent output through a single code-intel hub (`feat(hooks): centralize agent routing and code intel`, PR #40). Both rely on the storage layer described here.
## Architecture
The package is layered: producers emit events into the event log, normalizers enrich them (SARIF shaping, decision records, AST facts), and a single DuckDB-backed store persists everything for query.
```mermaid
flowchart LR
A[Agent / Hooks] -->|events| B(event_log.go)
H[AST Scanner] -->|facts| F(astfacts.go)
F -->|rows| C(duckdb_store.go)
B --> C
S[sarif.go] -->|normalized results| C
D[decisions.go] -->|policy verdicts| C
R[repo_map.go] -->|repo metadata| C
C -->|SQL queries| Q[Reports / CLI / Web UI]
```
The `duckdb_store.go` module is the only writer to the database; every other file in `codeintel/` produces typed structures that are ultimately flushed through it. Source: [go/internal/codeintel/duckdb_store.go]()
## DuckDB Storage Backend
`duckdb_store.go` owns the on-disk database file and the schema migrations. It is responsible for:
- Opening or creating the database with a deterministic path under the project's data directory.
- Running idempotent `CREATE TABLE IF NOT EXISTS` statements for each logical table.
- Providing typed insert helpers so callers do not write raw SQL.
- Exposing query helpers for read-only consumers (CLI, web UI, report generators).
DuckDB was chosen because the workload is overwhelmingly analytical: the agent runs few writes per session but the resulting tables are queried in aggregate (e.g. "how many `error`-level SARIF results per file across all runs"). Embedding DuckDB avoids standing up a separate database server while still giving the project SQL semantics. Source: [go/internal/codeintel/duckdb_store.go]()
### Core Tables (inferred from package boundaries)
| Concern | Producer file | Stored shape (high level) |
|--------------------|--------------------------------------------|--------------------------------------------------|
| Run events | `event_log.go` | Append-only event rows with timestamps + payloads |
| Static analysis | `sarif.go` | Normalized SARIF `runs[]` flattened per result |
| Policy decisions | `decisions.go` | Verdict, rule id, evidence reference |
| Repository layout | `repo_map.go` | File paths, language hints, ownership metadata |
| Code facts | `astfacts.go` | Symbol records extracted from AST nodes |
These boundaries let each contributor extend a single concern without coordinating schema changes across the package.
## Telemetry Event Log
`event_log.go` is the package's hot path. Hooks and agents call into it on every meaningful action — file opened, scan started, finding emitted, remediation applied — so its API is intentionally small: `Append`, `Flush`, `Tail`. Source: [go/internal/codeintel/event_log.go]()
Events are buffered in memory and flushed to DuckDB in batches to keep the scanner's I/O cost low. Each event row carries:
- A monotonic event id.
- A wall-clock timestamp.
- The originating component (hook name, agent subsystem, scanner).
- A typed payload, marshalled to a column the store understands.
The release v0.3.0 work on **remediation evidence payloads** (PR #39) extended the payload schema so that an event can carry the exact diff or rule violation that triggered a fix, making the event log a self-describing audit trail. Source: [go/internal/codeintel/event_log.go]()
## SARIF and Decision Normalization
`sarif.go` converts raw SARIF documents produced by external scanners into the row shape that `duckdb_store.go` persists. It strips tool-driver noise, maps severity, and preserves the `ruleId`, `message`, and location triples needed for later reporting. Source: [go/internal/codeintel/sarif.go]()
`decisions.go` records policy verdicts: each time a rule fires, the agent stores *why* the rule matched and *what* it decided to do (`allow`, `warn`, `block`, `remediate`). Persisting the decision alongside the SARIF row closes the loop — a reviewer can later ask "did we ever let this through?" and get a deterministic answer. Source: [go/internal/codeintel/decisions.go]()
## Repository Mapping and AST Facts
`repo_map.go` persists the working snapshot of the repository at the moment a scan ran: file tree, detected languages, configuration files discovered. This anchors every other row — SARIF results, decisions, and AST facts all reference file paths the `repo_map` knows about, so renaming or deleting files does not orphan dangling foreign keys. Source: [go/internal/codeintel/repo_map.go]()
`astfacts.go` is a sibling package that walks source files and emits typed **facts** — symbol definitions, references, import edges — into the same store. Because the schema lives in `codeintel`, AST facts can be joined directly against SARIF rows and decisions, which is what enables cross-tool queries such as "all `error` findings touching a function defined in `pkg/foo`". Source: [go/internal/astfacts/astfacts.go]()
## Common Failure Modes
| Symptom | Likely cause |
|------------------------------------------|----------------------------------------------------------------------------------------|
| `database is locked` errors on flush | Two processes opening the same DuckDB file — DuckDB is single-writer per file. |
| Missing SARIF rows after a run | The scanner emitted a SARIF document the normalizer did not recognize; check `sarif.go` |
| Decision rows without evidence | An older agent version is emitting payloads that pre-date the v0.3.0 evidence schema |
| Foreign-key violations on file rename | `repo_map.go` was not updated before dependent rows were flushed |
When in doubt, query the database directly — `duckdb_store.go` exposes the read helpers needed to inspect what actually landed.
## See Also
- [Policy Engine](policy-engine.html)
- [Agent Hooks & Routing](agent-hooks.html)
- [Remediation Workflow](remediation-workflow.html)
---
## Runtime Sandboxing, Managed Tools & Security
### Related Pages
Related topics: [Policy Enforcement, MCP & Agent Hooks](#page-2), [Code Intelligence & Telemetry Storage](#page-3)
Related Source Files
The following source files were used to generate this page:
- [go/internal/sandbox/sandbox.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/sandbox/sandbox.go)
- [go/internal/sandbox/cgroup_linux.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/sandbox/cgroup_linux.go)
- [go/internal/managedcapture/managed_capture.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/managedcapture/managed_capture.go)
- [go/internal/managedcapture/agent_shell_sandbox.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/managedcapture/agent_shell_sandbox.go)
- [go/internal/toolchaincli/managed_toolchain.go](https://github.com/paudley/coding-ethos/blob/main/go/internal/toolchaincli/managed_toolchain.go)
- [docs/RUNTIME_SANDBOXING.md](https://github.com/paudley/coding-ethos/blob/main/docs/RUNTIME_SANDBOXING.md)
# Runtime Sandboxing, Managed Tools & Security
The Runtime Sandboxing subsystem is the security boundary that lets the coding-ethos
agent execute untrusted or partially-trusted code (tool invocations, shell snippets,
build commands) without compromising the host, the developer workspace, or the
policy enforcement layer. It pairs Linux kernel-level resource isolation with a
curated, version-locked "managed toolchain" so that every action an agent takes
can be attributed, capped, and audited. `Source: [docs/RUNTIME_SANDBOXING.md]`
This page covers the runtime-side guarantees: how sandbox profiles are selected,
how managed tools are pinned, how shell activity is captured for remediation, and
how the v0.3.0 release tightened policy seams and added remediation evidence.
## Architecture Overview
```mermaid
flowchart LR
A[Agent / Hook Caller] --> B[sandbox.Sandbox]
B --> C[cgroup_linux]
B --> D[Policy Seams v0.3.0]
B --> E[managed_capture]
E --> F[agent_shell_sandbox]
B --> G[toolchaincli.ManagedToolchain]
G --> H[Pinned Binaries]
F --> I[Evidence Payload]
I --> J[Code Intel Store]
```
The caller invokes `sandbox.Sandbox`, which dispatches to a platform-specific
isolation backend (`cgroup_linux` on Linux) and consults the policy extension
seams hardened in v0.3.0. Shell activity is routed through
`managed_capture`/`agent_shell_sandbox`, which produces a remediation evidence
payload that the centralized hooks layer persists to the code-intel store.
`Source: [go/internal/sandbox/sandbox.go]()`
## Sandbox Primitives
`sandbox.go` is the entry point and exposes a profile-driven API. A profile
bundles resource caps (CPU, memory, PIDs, wall-clock), filesystem allow/deny
rules, and network posture. Profiles are looked up by name (e.g. `build`,
`lint`, `network-egress-disabled`) rather than constructed ad-hoc, which keeps
policy decisions reviewable.
`Source: [go/internal/sandbox/sandbox.go]()`
On Linux, `cgroup_linux.go` materializes the profile into a v2 cgroup hierarchy
under a per-invocation scope. It applies CPU weight, memory.max, pids.max, and
the `cgroup.kill` escape for stuck children, and tears the scope down on exit
so that no orphaned cgroup survives the agent run. The Linux-only file naming
mirrors the project's "policy at the kernel boundary" stance: when a profile
says "no network", the cgroup is created before the child is exec'd so the
denial is structural rather than advisory.
`Source: [go/internal/sandbox/cgroup_linux.go]()`
Common failure modes the sandbox is designed to surface explicitly:
- **Cgroup creation denied** — typically SELinux/AppArmor misconfiguration;
the sandbox returns a typed error so callers can degrade to a dry-run mode
rather than silently running unsandboxed.
- **Profile not found** — treated as a hard fail; agents cannot invent a
more permissive profile at runtime.
- **Resource cap exceeded** — the child receives SIGKILL via `cgroup.kill`
and the caller receives a structured `BudgetExceeded` error carrying the
offending counter.
## Managed Toolchain
`toolchaincli.ManagedToolchain` is the curated wrapper around every external
binary the agent is allowed to invoke — `go`, `node`, `python`, `git`,
formatters, linters, and language servers. Each tool entry pins an exact
version, a SHA-256 of the binary, and the environment it is safe to expose
to. The toolchain refuses to launch a binary whose hash does not match the
manifest, which is the primary defense against dependency-confusion and
tampered cache replacements.
`Source: [go/internal/toolchaincli/managed_toolchain.go]()`
The toolchain also resolves tool paths through a single lookup function so
that hooks (see v0.3.0 "centralize agent routing and code intel") always
invoke the same managed binary regardless of which subsystem initiated the
call. This makes audit trails meaningful: every captured command references
the manifest entry it came from.
## Agent Shell Sandboxing & Managed Capture
Shell actions are the riskiest surface, so they get a dedicated wrapper.
`agent_shell_sandbox.go` runs shell snippets inside the sandbox profile
selected for the current agent phase, with stdin/stdout/stderr captured in
full. `managed_capture.go` annotates the stream with timestamps, the active
profile, the toolchain manifest entries that were resolved, and the policy
decisions consulted along the way.
`Source: [go/internal/managedcapture/agent_shell_sandbox.go]()`
In v0.3.0 this capture was extended with a **remediation evidence payload**
that summarizes what the agent did, what was denied, and what the human
reviewer should look at first. The payload is the canonical artifact the
code-intel store indexes for post-hoc review.
`Source: [go/internal/managedcapture/managed_capture.go]()`
## Policy Seams and Recent Hardening
The v0.3.0 release explicitly hardened "policy extension seams"
(`refactor(solid): harden policy extension seams`, PR #38). In practice this
means the interface between `sandbox.Sandbox`, the policy evaluator, and the
managed toolchain was narrowed so that new rules can only be added through a
small, typed registry rather than via ambient global state. Callers that
previously reached into a config struct to widen permissions now receive a
compile-time or runtime error depending on the seam.
`Source: [go/internal/sandbox/sandbox.go]()`
The hook layer was also centralized in v0.3.0
(`feat(hooks): centralize agent routing and code intel`, PR #40), which means
every tool and shell invocation now flows through a single dispatch point
that consults the sandbox profile before exec. Combined with the remediation
evidence payloads (PR #39), this gives reviewers a single, consistent
artifact for every action the agent took, even when those actions were
generated by different subsystems.
`Source: [docs/RUNTIME_SANDBOXING.md]()`
## See Also
- [Policy & Hook Architecture](policy-hooks.md) — how policy rules are
authored and consumed by the centralized hook layer.
- [Code Intelligence Store](code-intel.md) — persistence layer for the
remediation evidence payloads produced by `managed_capture`.
- [Managed Toolchain Manifest](managed-toolchain.md) — schema and update
workflow for the pinned-binary manifest.
---
---
## Pitfall Log
Project: paudley/coding-ethos
Summary: Found 14 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.
## 1. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/224
## 2. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/238
## 3. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/240
## 4. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/paudley/coding-ethos
## 5. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/paudley/coding-ethos
## 6. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/241
## 7. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/paudley/coding-ethos
## 8. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/paudley/coding-ethos
## 9. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/paudley/coding-ethos
## 10. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/190
## 11. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/239
## 12. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/paudley/coding-ethos/issues/235
## 13. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/paudley/coding-ethos
## 14. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/paudley/coding-ethos