Decision Traces
Automatic audit trail of tool invocations and agent decisions, with querying and enrichment.
Overview
Decision traces are automatically captured from MCP tool invocations. They record what tool was called, with what inputs, what it produced, and optionally why — forming a complete audit trail.
Viewing Decisions
trellis decision list
trellis decision list --tool trellis_issue_*
trellis decision show DEC-1
trellis decision chain issue:TRL-5
Programmatic API
import { recordDecision, queryDecisions } from "trellis/decisions";
const dec = await recordDecision(ctx, {
toolName: "trellis_issue_create",
input: { title: "Add parser" },
output: { id: "TRL-5" },
rationale: "Needed for TypeScript support",
});
// Query by tool pattern
const decs = queryDecisions(ctx, { tool: "trellis_issue_*" });
// Full decision chain for an entity
const chain = queryDecisions(ctx, { entity: "TRL-5" });
Enrichment Hooks
External agent harnesses can enrich traces with rationale, alternatives, and prompt context via the pre/post hook API:
import { registerHook } from "trellis/decisions";
registerHook("pre", async (ctx, input) => {
// Add context before tool execution
return { ...input, context: await gatherContext() };
});
registerHook("post", async (ctx, input, output) => {
// Add rationale after execution
return { rationale: "Chose this approach because..." };
});