kimi-plugin-cc: Instructions file for Claude Code

AGENTS.md

Project context for coding agents working in this repository. This is the contract sheet: each bullet states what must not regress, in present tense, with a pointer to the full mechanics and rationale in docs/invariants.md (§ numbers below). Keep this file under 32 KB. CLAUDE.md imports it with @AGENTS.md, so there is one source and nothing to mirror. Release history lives in CHANGELOG.md and ROADMAP-TO-GA.md § Post-GA audit log, never here.

Quick reference

• Version: 2.4.3 (kimi-code, subprocess transport, native agent-core-v2).
• Native-v2 safety (§1): every executed tool passes managed PreToolUse; the sole chain-breaking plan-file allow is NEVER armed. Preserve all four closures: same-child-home preflight rejects every normalized default_plan_mode spelling (before spawn and at spawn, including Stop hook; remedy the config key, not setup); deny Enter/ExitPlanMode for every label; resume requires proven native-v2 lineage and every-agent raw journal scan for plan taint; refuse tower/subagent_fork/master experimental selectors. Exact per-operation NATIVE_V2_CERTIFIED rows require source tag scan, plan-ON bypass control and operation smoke; legacy KIMI_TESTED_MINORS never gains 0.42. Require the first stream line to be the exact-version marker for v2 and refuse it on v1. Validate Bash.cwd against the trusted root before command policy. Full refusal codes, normalization rules and evidence: docs/invariants.md §1 and certification provenance §2.
• Hook-pin durability (§1): the canonical hook command never embeds a version-stamped Node token; preferStableNodePath prefers process.argv0 only when absolute and realpath-identical; verifyHookInstalled runs access(nodeBin, X_OK) fail-closed on the token parsed back from the built command (refusal_kind:"node-bin-not-executable" is the one refusal whose remedy is NOT /kimi:setup). Re-pin-recoverable refusals carry retryable_after_setup; agents re-pin via ${CLAUDE_PLUGIN_ROOT}/scripts/companion.sh setup and retry ONCE only when it is literally true and setup exits 0. In-verifier auto-repin is REJECTED — do not re-propose.
• Test discipline (§1): detached-worker hook-enforcement tests MUST run the companion as a real node subprocess through a symlink with NO KIMI_PLUGIN_CC_NODE_BIN override and NO KIMI_PLUGIN_CC_SKIP_HOOK_CHECK. A real-binary smoke MUST assert its own precondition when the behaviour depends on host state; never write a "plan-file write is denied under plan mode" smoke — that path is never armed, so green would be the vacuous-precondition failure.
• Upstream compat (§2): native-v2 certification is EXACT and per-operation in runtime/kimi-engine.ts; all eight operations support 0.42.0, 0.43.0, 0.43.1, 2.0.0–2.0.2, 2.1.0–2.1.1, 2.2.0 and 2.3.0–2.3.3. Legacy-v1 ends at 0.41.x for an explicitly pinned binary. The sole plan-service allow still bypasses hooks through 2.3.3 (MoonshotAI/kimi-code#3431); retain every no-plan closure. Each audit re-verifies ALL surfaces in docs/upstream-compat-audit.md and docs/invariants.md §2, including engine/session provenance, hook ordering/schema/aggregation, Write/Edit path and Bash command+cwd, bootstrap/config/trust, plan/restore routes, print argv, goal interception/exits, child hooks, finite budgets and exported swarm concurrency. Monitor reports never certify. Exact 2.3.2/2.3.3 swarm activation/deactivation uses authenticated loopback web lifecycles around the single kimi -p -r runner; preserve model/auto/swarm profile with plan off, marker/version/session identity, memory-only token and journal proof. runSwarm owns deactivation, with remaining budget normally and one separate 2s cancellable recovery attempt; cancellation starts no fresh server. Process ownership/quiescence uncertainty prevents success and preserves diagnostics, raw output and write worktree. Root loss requires prior identity; PGID changes are not exit. Smoke must correlate distinct child journals, assigned Write/Edit paths and toolCallIds with results—not aggregate denials or coordinator-only work. Evidence: docs/native-v2-status.md.
• Toolchain: Node >= 22.5, TypeScript, bun for development; npm CLI for registry operations, including package installation
• Workflow: edit runtime/**/*.ts → bun run check (build + typecheck + test + drift gate)
• Installed-state verification: For questions about what a host is actually running, resolve that host's active version-stamped install cache and run its bundled scripts/companion.sh setup --check. The checkout, package metadata, and another host's cache are not proof of active runtime state.
• Credential-bearing config (§3): ~/.kimi-code/config.toml can hold a BYO-provider apiKey, and ~/.kimi-code/credentials/ is the real OAuth-token store (always has been — not a per-version migration). For routine checks never read, print, copy or retain either; use the sanitized setup --check or setup --models [--json] projection. Model listing internally parses config but emits only routing fields, never secrets or raw parser errors; it never reads the OAuth store or makes provider calls. An explicitly authorized diagnosis of config.toml is restricted to the managed hook block with credentials redacted; credentials/ is never read or copied.