Hooks and guards

Opt into context hooks that shrink tool output, and run the local guardrail checks that keep a shared workshop sane.

Goal#

Turn on the two opt-in harness context hooks (both default off), install and run orch guard checks, and pick a guard.profile that decides how much of this orch wires up for you.

Context hooks (opt-in, off by default)#

orch.yaml:

context:
  hooks:
    post_tool: true    # Claude Code PostToolUse / OpenCode tool.execute.after
    pre_compact: true  # Claude Code PreCompact

• post_tool shrinks an oversized tool result before it reaches the model (orch hook post-tool), using the same crush/externalize settings as context.guidance. It skips any tool name listed in context.guidance.protect_tools (default: Bash, PowerShell, Read, Grep, Glob, Edit, Write, Agent, Task, WebFetch, Shell, bash, read_file, write_file — coding tools where a lossy rewrite would hide a real result).
• pre_compact runs the same condenser as orch memory condense on .workflow/BOARD.md and .orch/LAST_SESSION.md just before the harness's native compaction discards the transcript — so the board's ## Clarified section and open checkboxes survive byte-for-byte instead of being summarized away.

Neither hook does anything on its own: both need orch guard wire --claude (or --profile) to actually install them into ~/.claude/settings.json / the OpenCode plugin folder.

orch guard checks#

orch guard dup <file>            # deny/warn on a file that duplicates a shared symbol or clones a function body
orch guard code-lang [root]      # identifiers/strings must match workspace.code_lang
orch guard lang [root]           # docs must match workspace.locale
orch guard ddl [files...]        # migrations/CREATE TABLE need a seeder/repository companion
orch guard tracker [TRACKER.md]  # TRACKER.md status table sanity (T1–T4)
orch guard lock <path> --holder  # deny editing shared/** without a valid lock

orch guard dup is advisory by default — it prints where the existing copy lives and lets the write proceed. Set guard.dup.mode: block in orch.yaml to deny the write instead (off disables the scan entirely). guard.dup.window / min_tokens / max_files tune the clone scan.

Steps#

1. Pick a profile (or accept the recommended default):

   orch guard profile lite     # docs + skills; no hooks (recommended day-1)
   orch guard profile shared   # + git pre-commit/pre-push on shared/project repos
   orch guard profile strict   # + Claude user-hook wire, locale/tracker awareness
   orch guard profile bring    # keep your own CLAUDE/rules; orch only adds locks/symbols
   orch guard profile none     # orch.yaml only
   

2. Wire the adapters for that profile:

   orch guard wire --profile
   

   Or wire specific adapters directly: --git, --claude, --cursor.

3. Install git hooks directly (independent of guard wire):

   orch guard hooks install [repo]
   orch guard hooks status [repo]
   orch guard hooks run [repo]       # what the installed hooks actually call
   

Verify#

orch guard profile
orch guard hooks status

Undo#

orch guard unwire            # removes Claude/Cursor/OpenCode adapters
orch guard unwire --git      # also removes git pre-commit/pre-push
orch guard hooks uninstall [repo]

Related#

• memory-and-ledger.md — what pre_compact condenses.
• troubleshooting.md — "hook did nothing" when the workspace isn't registered.