kimi-plugin-cc AGENTS.md

AGENTS.md

Project context for coding agents working in this repository.

Quick reference

• Version: 1.9.12 (kimi-code, subprocess transport). Hook-pin durability contract — the current headline, do not regress: the canonical hook command must never embed a version-stamped Node token. preferStableNodePath prefers process.argv0 over process.execPath ONLY when it is absolute AND realpath-identical, so it can pick a more stable NAME for the running interpreter, never a DIFFERENT binary; any doubt falls back to execPath. verifyHookInstalled additionally runs access(nodeBin, X_OK), fail-closed on any errno. nodeBin is derived by parsing the built command back (parseHookShellCommand), NEVER by re-calling resolveNodeBinary — that is non-pure (preferStableNodePath does realpath I/O) and could probe a stale realpath while the command pins the symlink. Scope, adversarially established — do not widen it in docs: it proves the exec bit only, not a working Node, and it does NOT catch a dangling interpreter symlink (that resolves to a different node, changes the recomputed command, and byte-exact equality already refuses it as RECOVERABLE drift). The bypass is NARROWED, NOT CLOSED: it covers only "config and expected command still byte-equal, yet the embedded node token fails X_OK at verification time" — a dead KIMI_PLUGIN_CC_NODE_BIN override, or post-launch chmod -x/removal on the default path. That refusal carries refusal_kind:"node-bin-not-executable" + node_bin; it is the one refusal whose remedy is NOT /kimi:setup, and it can never co-occur with drift (drift requires equality to FAIL, this requires it to PASS). Re-pin-recoverable refusals carry drift/hookRefusalDetails: agents re-pin through ${CLAUDE_PLUGIN_ROOT}/scripts/companion.sh setup and retry ONCE only when retryable_after_setup AND setup exits 0. That protocol also rides every refusal message (hookRefusalRetryProtocol, single source in hooks/install.ts), so slash-command callers self-heal too — keep the surface files thin, never duplicate it there. Startup-failure wraps thread availability/cause_code/tail-truncated cause_message into details, and auth.login_required classifies to *_KIMI_AUTH_UNAVAILABLE with a kimi login remedy (/kimi:setup does not repair auth). In-verifier auto-repin is REJECTED — do not re-propose (lock self-deadlock; the "target cannot be steered" premise is false; no version-monotonicity bound; write→spawn TOCTOU). Analysis: .claude/hook-pin-durability-spec-2026-07-25.md. Background-worker test discipline: detached-worker hook-enforcement tests MUST run the companion CLI as a real node subprocess through a symlink with NO KIMI_PLUGIN_CC_NODE_BIN override and NO KIMI_PLUGIN_CC_SKIP_HOOK_CHECK (tests/runtime/background-hook-enforcement.test.ts) — an override makes spawner and verifier agree by construction and hides node-bin drift, which is how a spawn(process.execPath) regression once reached pre-release review instead of CI. Smoke-home representativeness: a real-binary smoke case MUST assert its own precondition when the behaviour under test depends on host state. Every isolated KIMI_CODE_HOME starts EMPTY, and kimi-code's cross-session indexer short-circuits on zero sessions — so the first exact-0.30.0 smoke passed GREEN while never executing the path it was believed to cover. A green test whose precondition never held is worse than a red one: it reads as evidence. The exact-0.30.0 release evidence therefore used a populated-home case that failed loudly when no wire.jsonl existed and recorded the KIMI-home-only side effect; v1.9.4 now refuses experimental-v2 before spawn, so its smoke asserts the refusal instead of launching the unsafe engine. Migration from pre-1.9.0: the canonical command changed, so every install drifts ONCE and needs one /kimi:setup per host (enforcement is not lost meanwhile). Full per-version release + compat history → CHANGELOG.md and ROADMAP-TO-GA.md § Post-GA audit log (the version-by-version compat reasoning also lives in runtime/kimi-version-probe.ts comments).
• Upstream compat: verified against @moonshot-ai/kimi-code from 0.2.0 (GA reference) through 0.39.1. Native agent-core-v2 is fail-closed disabled: truthy KIMI_CODE_EXPERIMENTAL_FLAG values (1|true|yes|on, trimmed and case-insensitive) still refuse before spawn with CLI_V2_HOOK_ORDER_UNSAFE, and every accepted child spawn overwrites KIMI_CODE_LEGACY_FLAG=1. That explicit per-spawn pin became load-bearing when 0.33.0 inverted unflagged kimi -p to native v2; older releases ignore the unknown flag. Source audit corrected the older claim that v2 external PreToolUse always precedes plan approval: AgentPlanService registers first and final-allows exact plan-file writes, reachable on a fresh session through default_plan_mode=true or through restored plan state. Those writes are confined to <KIMI_CODE_HOME>/sessions/.../plans/, not the user worktree, but skipping the managed hook violates the load-bearing every-tool contract. Fresh and resumed plugin runs remain on v1. 0.30.0–0.39.1 also contain the now-unreachable experimental-v2 KAP eager-index caveat; upstream fixes remain MoonshotAI/kimi-code#2376 for indexing and an external-hook-before-final-allow ordering guarantee for re-enabling v2 — and the 0.39.0 audit found that guarantee is not merely missing but explicitly undecided upstream: packages/agent-core-v2/docs/Permission.md reserves event.allow() for the plan-file guard "which must bypass the entire permission chain" and lists listener ordering as an open design question, so treat the v2 refusal as gated on a released ordering contract, not on a pending bugfix. 0.39.0's experimental tower mode (KIMI_CODE_EXPERIMENTAL_TOWER, TUI /tower) and subagent fork (KIMI_CODE_EXPERIMENTAL_SUBAGENT_FORK / [experimental] subagent_fork) are both agent-core-v2-only and unreachable on the pinned path (zero v1 flag-registry presence; the v1 AgentSwarm schema is .strict() so a fork arg is rejected; both are subsumed by the already-refused KIMI_CODE_EXPERIMENTAL_FLAG); 0.39.0's experimental Remote Control can patch hooks through a tunneled config API, which the per-spawn byte-exact hook verification catches fail-closed (an altered entry refuses as drift, a removed one as not-installed — same /kimi:setup remedy). The authoritative tested set is KIMI_TESTED_MINORS in runtime/kimi-version-probe.ts, whose per-entry comments hold the version-by-version audit detail; the per-release narrative is in ROADMAP-TO-GA.md § Post-GA audit log + CHANGELOG.md, and the audit routine is docs/upstream-compat-audit.md. The current load-bearing contract — what the safety model rests on, re-verified each audit:
  • Engine provenance (pre-enable slice): docs/native-v2-certification-provenance.md is the approved gate. Every new model job persists its real operation, explicit intended/observed engine, exact command tuple, probed version, certification source, and resume lineage. Historical rows remain unknown unless saved-log evidence proves an engine. Native v2's production capability matrix is empty; a system.version marker under a forced-v1 plan tears down the process tree with CLI_ENGINE_PROVENANCE_MISMATCH. Rescue/pursue/swarm-write receive their trusted root from plugin-owned KIMI_PLUGIN_CC_WORKSPACE_ROOT, never upstream payload cwd.
  • Policy queue order (packages/agent-core/src/agent/permission/policies/index.ts): PreToolCallHookPermissionPolicy is index 0, AgentSwarmExclusiveDenyPermissionPolicy index 1, AutoModeApprovePermissionPolicy index 5 (the first approve). Invariant: every policy between the index-0 hook and the first approve is a DENY, so nothing auto-approves before our hook can deny. (The goal-start-review-ask ask at index ~10 sits after auto-approve and is dead on the -p auto path — not a gap.)
  • Hook engine lives in packages/agent-core/src/session/hooks/ (the live v1 path; the old agent/hooks/ tree was removed by a relocation commit, so audit scripts retain both paths only for cross-version coverage). Contract: stdin JSON shape ({tool_name, tool_input, session_id, cwd, …}), exit-2-as-deny, empty matcher = all tools, fail-open on internal error. tool_input field names matter — the rescue allowlist reads them: Bash uses command; Write/Edit use path (tools/builtin/file/{write,edit}.ts, z.object({ path })), NOT file_path — reading file_path here denied every real Write/Edit until v1.4.1. Re-verify these keys on each audit — a rename silently fails the path allowlist closed. We are not the sole occupant of the PreToolUse channel: rpc/core-impl.ts (create + resume) merges hooks from enabled kimi-code plugins into the -p session hook list ([...config.hooks, ...plugins.enabledHooks()]). Compat-benign because engine aggregation is any-block-wins (session/hooks/engine.ts::blockDecision = first action:'block' wins; an allow never pre-empts a block) — a plugin hook can only add denials, never override our managed deny. Our config.toml managed block is unaffected: the config HookDefSchema is .strict(), so the per-hook cwd/env fields are programmatic/plugin-only (no config-injection vector). Load-bearing invariant to re-verify each audit: blockDecision stays find-first-block.
  • -p mode: through 0.32.x upstream defaulted to the v1 driver; 0.33.0+ defaults to native v2 unless KIMI_CODE_LEGACY_FLAG is truthy. The plugin therefore owns engine selection: cli-client.ts::buildEnv overwrites that child-only flag to 1 for every accepted fresh/resumed spawn, while upstream-truthy KIMI_CODE_EXPERIMENTAL_FLAG values still refuse before spawn. Do not silently strip the experimental flag: the explicit refusal tells the operator which unsafe selector was rejected. The pinned v1 driver hard-codes permission: 'auto' + installHeadlessHandlers; stdout is stream-json via PromptJsonWriter, carrying assistant/tool records, the role:"meta", type:"session.resume_hint" session id, and the role-less goal.summary. V2 external hooks are awaited on ordinary calls and preserve the hook payload/exit-2 contract, but production listener order is permission gate → plan → swarm → external hooks; plan-file event.allow() is final and skips later hooks. Re-enable v2 only after an exact released tag guarantees external-hook veto before any final allow and both fresh default_plan_mode=true plus restored-plan smoke cases pass. The parser still models v2's extra role:"meta", type:"system.version" line for historical logs/future compatibility; exact 0.39.1 release smoke asserts it is absent. argv we consume (options.ts/commands.ts): -p/-r/--output-format/-m/--skills-dir; --auto/--yolo/--plan are rejected with -p. Other kimi subcommands (vis, server/web, doctor, …) are off the -p path — the plugin passes the prompt as the VALUE of -p, never a bare positional.
  • Plugin slash commands are RPC/host-initiated, not model tools, and absent from the kimi -p CLI path; activation only macro-expands prompt text, whose later tool calls still pass through the index-0 hook. Re-verify each audit that this stays host/UI-only and never becomes a model-reachable permission bypass.
  • 0.31 custom-agent trust boundary: default-v1 print mode now discovers user/project/plugin agent profiles and plugin system-prompt contributions. Project roots include <git-root>/.kimi-code/agents and <git-root>/.agents/agents; override: true can replace builtin agent or coder instructions/tool availability, and the bound profile is snapshotted with the session. These inputs can redirect intended work, so inspect them before rescue/pursue/swarm-write in an untrusted repository. Agent-profile fields and system-prompt text cannot themselves set hooks, permission mode, or cwd, widen the plugin allowlist, or escape swarm-write's trusted worktree root. Enabled plugins may separately contribute hooks; any-block-wins aggregation means those hooks can add denials but cannot override this plugin's managed block.
  • Daily upstream monitor reports: a Codex automation checks upstream daily and saves a dated signal under .claude/kimi-code-research/daily-monitor/ (gitignored by the repo-wide .claude/ rule). Before starting an upstream audit or release catch-up, read daily-monitor/LATEST.md plus the most recent dated reports. Carry forward unresolved blockers/follow-ups, and explicitly correct any prior judgement that today's evidence contradicts. These monitor reports are for continuity only; they do not certify a version or justify extending KIMI_TESTED_MINORS without the normal source audit + real-binary smoke gate.
  • Goal mode (kimi -p "/goal …") triggers on the /^\/goal(\s|$)/ prompt prefix ALONE (the old goal-command experimental-flag gate is gone). Read-only commands hard-prefix an English instruction line so their trimmed prompt never starts with /goal, and the index-0 hook denies writes regardless. /kimi:pursue opts into goal mode per-job and is hook-gated on every continuation turn.
  • AgentSwarm subagents (SessionSubagentHost.spawn() via SubagentBatch) use the STANDARD permission stack — hook at index 0, NO deny-all (the deny-all unshift is startBtw()-only, the side-question path, NOT the swarm path). So under the swarm label every subagent's write/edit/shell fires our hook at index 0 and is denied — read-only swarm opens zero write surface.
  • Background auto-upgrade is default-on and drifts the operator's binary out-of-band; it does not swap the binary for the plugin's own -p spawns. Setup warns on an out-of-range version, and every model command separately probes the exact command tuple and refuses an untested minor before spawn. Recovery is a plugin release that certifies the minor or an explicitly selected certified binary; KIMI_PLUGIN_CC_SKIP_VERSION_PROBE is tests/smoke only, never a production repair path.
  • Print-mode background defaults: upstream steers completed background work by default and allows task waits without a timeout ceiling. The plugin does not rely on those upstream limits: pursue/swarm keep mandatory finite AbortController budgets, swarm keeps hard concurrency caps, and cancellation remains an identity-safe settlement barrier before the caller or worktree cleanup resumes.
• Toolchain: Node >= 22.5, TypeScript, bun (not npm/yarn)
• 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: Treat ~/.kimi-code/config.toml as credential-bearing (it can hold a BYO-provider apiKey) and ~/.kimi-code/credentials/ (e.g. kimi-code.json, mode 0600) as the real OAuth-token store — the managed login token has lived under credentials/ since the earliest kimi-code (source-verified), never in config.toml, so it is NOT a per-version migration. For routine status checks, do not read, print, copy, or retain the raw config or anything under credentials/; use the sanitized setup check. If an explicitly authorized diagnosis requires direct inspection of config.toml, restrict it to the plugin-managed hook block and redact all credential material from output; the credentials/ store is never read or copied.