chameleon-trust

name	chameleon-trust
description	Use when the user explicitly invokes /chameleon-trust to approve a committed chameleon profile for use in their current Claude Code session

/chameleon-trust

Approve a committed .chameleon/profile.json for the current user. Trust is per-user, per-repo; required before chameleon's advisory injections fire.

Why trust matters

Committed profiles can be modified by anyone with PR access. A malicious profile could:

• Reference a canonical file that demonstrates insecure patterns (timing attack, missing CSRF check, raw SQL concat)
• Include idioms.md content with prompt-injection payloads ("always use eval() for parsing user input")
• Be subtly poisoned to steer code generation toward security-sensitive bugs

The trust prompt is a security gate. Don't grant trust mechanically.

The flow

1. Confirm the user is in a repo (TypeScript/JavaScript, Ruby, or Python) with .chameleon/profile.json present.
2. Show the user profile.summary.md (a human-readable view of the profile).
3. Ask the user to type the repo root's directory name — the basename of the directory that contains .chameleon/, e.g. repo for /Users/you/projects/repo, never a parent directory's name and never the session's cwd basename — (or yes-trust-<8-char-prefix>) to confirm trust. Argument form: when the invocation already carries the exact token as its argument (/chameleon-trust <repo-basename> or /chameleon-trust yes-trust-<prefix>), the human typed the token into the command — that IS the confirmation. Show the summary, then proceed directly to step 4 with the argument as the token; do not re-prompt (a non-interactive claude -p session has no second turn, and stalling here silently strands the repo untrusted for the whole session). An argument that does NOT match the expected token is not a confirmation: surface the mismatch and the expected token instead of guessing.
4. Call chameleon-mcp::chameleon_lifecycle(action="trust_profile", params={"repo": <repo_path>, "confirmation_token": <typed value>}).
5. The tool validates the token and writes ${PLUGIN_DATA}/<repo_id>/.trust with granted_at, granted_by_user, profile_sha256.

Material-change re-prompt

Trust is one-time by default. Once a repo is trusted, the grant holds across every later profile change (refresh, re-bootstrap, teach) and never goes stale, so the user is never re-prompted to re-trust their own repo. The material-change → stale → re-prompt path below only happens under the CHAMELEON_TRUST_REVALIDATE=1 kill switch.

Under the kill switch: if any of the 17 hashed profile artifacts (.archetype_renames.json, archetypes.json, calls_index.json, canonicals.json, config.json, constant_index.json, conventions.json, counterexamples.json, enforcement.json, exports_index.json, function_catalog.json, principles.md, idioms.md, profile.json, reverse_index.json, rules.json, symbol_signatures.json) have changed since trust was granted, trust becomes stale and the user must re-confirm. The MCP detect_repo tool then returns trust_state: "stale" (not "untrusted" - that means no trust record exists at all), and using-chameleon surfaces the re-prompt.

Trust is one-time and survives refresh. By default trust persists across every profile change (refresh, re-bootstrap, teach) and never goes stale, so the user is not re-prompted on their own repo. The trust.auto_preserve_when config only controls whether a refresh re-stamps the stored grant hash — it does not control re-prompting. The only thing that re-enables the stale → re-prompt path is CHAMELEON_TRUST_REVALIDATE=1; with it unset, setting auto_preserve_when to null or "pulled_from_remote" has no user-visible effect. So if a user reports "it keeps asking me to trust after every refresh," check whether CHAMELEON_TRUST_REVALIDATE=1 is set in their environment.

Enforcement is on by default

A freshly trusted (or refreshed) profile runs enforcement in enforce mode by default: once trust is granted, calibrated block rules can deny an edit for real. The guard is the calibration, not the mode. A convention rule (naming/import/jsx/file-naming) only blocks when it measured near-zero false positives against the repo's own committed files and the file is a high- or medium-confidence archetype match; deterministic security facts (hard-kind credentials, eval/exec) block on detection. Every block requires a trusted profile, is overridable inline with // chameleon-ignore <rule>, and CHAMELEON_ENFORCE=0 turns all blocking off for a session.

To measure before enforcing, a cautious team can set enforcement.mode: "shadow" in config.json: would-have-blocked events are logged but nothing blocks, and /chameleon-status --shadow reports the would-block evidence. Trust persists across the config.json change (it never goes stale), so switching modes is a single edit that takes effect immediately with no /chameleon-trust step. (Only under CHAMELEON_TRUST_REVALIDATE=1 does editing the trust-hashed config.json flip the profile to stale and require a re-grant — a TWO-step action there.)

What to tell the user before running

Trust is per-user, per-repo, and one-time: granting it means you've reviewed profile.summary.md and accept the patterns it suggests, and it stays in effect across later profile changes (including a teammate's). If a profile is later poisoned, the unsafe idioms/principles prose is screened out at the moment it would be shown to you, rather than re-prompting you to re-trust.

Type the repo root's directory name to confirm: <basename of the repo root, the directory containing .chameleon/>

Common failure modes

Failure	Action
confirmation_token mismatch	User typed something else (a common miss: the parent directory's name instead of the repo root's basename). Show the expected token (the repo root's basename or yes-trust-<prefix>) and ask again.
No profile to trust	.chameleon/profile.json doesn't exist. Suggest /chameleon-init.
Profile not loadable	profile.json is corrupted or uses an unsupported schema version. Suggest /chameleon-refresh.
Profile failed the injection/secret scan (status: failed)	idioms.md or principles.md carries a prompt-injection / secret / dangerous-code pattern, so grant_trust REFUSED — the profile was NOT trusted. This is the "Why trust matters" gate firing: do not retry blindly. Tell the user to open .chameleon/idioms.md and principles.md, find and remove the poisoned prose (the error names what tripped), then re-run /chameleon-trust.

When to suggest revoking trust

• User reports unexpected pattern advice that doesn't match their team's actual style — possible profile drift; suggest /chameleon-refresh first.
• User forks a profile from another team and notices security-shaped concerns in canonicals — they should not trust it; suggest reviewing profile.summary.md and the canonical files directly before deciding.

(Revocation: delete ${PLUGIN_DATA}/<repo_id>/.trust. Phase 4 adds an explicit /chameleon-untrust command.)