Hook management

Tama stores hook source and structured configuration, exposes the CLI and MCP catalogue, and carries the runtime paths that enforce approved policy. The repository is never runtime state: logs, transcripts, credentials, shell profiles, local settings, caches, and machine-specific state stay outside it.

#Source of truth

1. shared-hooks/registry.json declares hook ids, events, commands, blocking status, runtime placement, and provider adapters.
2. shared-hooks/catalog-metadata.json carries durable category, lifecycle, purpose, rationale, and side-effect metadata.
3. tama-core reads those structured sources for the Rust CLI, MCP server, desktop catalogue snapshot, and product checks.

Do not duplicate a hook description in a command or prose file. Update the structured catalogue, then inspect it through tama list --json, tama show <hook-id> --json, or the matching MCP tools.

#Repository layout

• shared-hooks/, codex-hooks/, and claude-hooks/ contain archived hook source and the shared registry.
• repo-githooks/ contains project Git entrypoints.
• rust/crates/tama-core/ is the catalogue and validation library.
• rust/crates/tama-cli/ is the supported CLI implementation; rust/crates/tama-mcp-server/ exposes catalogue operations.
• rust/crates/tama-adaptive/ owns the runner, symbolic policy, immutable telemetry, feedback bridge, and repair doctor.
• adaptive/policy.json is the frozen symbolic tier and autonomy policy.

#Catalogue commands

tama list
tama list --json
tama show block-git-hook-bypass
tama show block-git-hook-bypass --json
tama validate --json
tama install-plan --json

The install plan separates agent runtime adapters, editor coverage, the MCP server, user-global Git dispatchers, repository Git entrypoints, and operating-system policy. An installed surface proves only its declared scope; Tama does not infer native Kimi, arbitrary editor-save, or device-wide coverage.

#Installation and repository cleanup

tama install writes the user-global pre-commit and pre-push dispatchers only. It preserves existing hooks and changes global Git configuration only when explicitly requested. It does not activate every agent, editor, MCP, or operating-system integration.

tama find-violations scans tracked and untracked-but-not-ignored repository files through the real pre-write policy without changing them. tama clean gives the structured report to a bounded model worker and rescans under the same hooks; generated lock and registry files stay outside that repair loop.

#MCP tools

• list_hooks lists structured catalogue entries.
• show_hook returns one hook and its event bindings.
• read_hook_source reads the archived source for one hook.
• validate_hooks checks catalogue consistency.
• find_violations returns the same structured repository report as the CLI.

#Changing a hook

1. Place source under the owning archive directory.
2. Update the registry and catalogue metadata with identity, event, command, timeout, blocking mode, category, purpose, rationale, and side effects.
3. Exercise the real runtime path that claims enforcement. Synthetic payload replay, mocks, and dry-run-only evidence do not prove live blocking.
4. Keep commits limited to hook source, structured catalogue/configuration, and applicable product checks. Exclude runtime state, credentials, logs, profiles, and caches.

#Security rules

Never commit settings, environment files, shell profiles, logs, transcripts, credentials, private keys, session cookies, or Keychain exports. Hook archives may contain forbidden patterns by design, so any bypass for the Tama source repository must be explicit and scoped.