feat(hooks): allow hooks to answer tool approvals

[rullerzhou-afk]

Related Issue

Closes #1326

Problem

PermissionRequest hooks can observe a native tool approval but cannot answer it. PreToolUse can deny a call, but an allow result only means that the hook does not object, so manual mode still opens the native approval UI. External approval surfaces therefore cannot approve a request without creating a second prompt.

What changed

• Add an opt-in experimental PermissionDecisionRequest hook for ordinary tool approvals in both agent-core implementations.
• Bind every structured response to the exact permission_request_id; decisions are per request and are not persisted as reusable rules.
• Aggregate matching hooks conservatively: any valid deny wins, while allow requires every matching hook to return a valid allow for the current request.
• Fall back to the existing native approval flow on no match, malformed output, mismatched IDs, hook errors, non-decision exits, or timeouts. Cancellation remains cancellation.
• Keep custom-continuation approvals, including plan review, on the native flow.
• Expose the experimental config/environment flag and plugin contract, add telemetry attribution, bilingual documentation, tests, and a CLI changeset.

UI compatibility

A hook decision is resolved before the existing session approval broker is called. It therefore does not create a pending interaction for the TUI, Kimi Web, or Kimi Code for VS Code to render. When hooks produce no valid decision, the unchanged broker path creates the normal native approval request.

Verification

• Current rebased head cefca4902:
  • Full @moonshot-ai/agent-core-v2 suite: 328 test files and 5,263 tests passed.
  • Focused @moonshot-ai/agent-core: 204 tests passed; Klient contract: 9 tests passed.
  • TypeScript checks passed for agent-core, agent-core-v2, Klient, and Klient examples.
  • The agent-core-v2 import-boundary check passed for 1,236 files.
• Real Kimi Code CLI TUI test on the current rebased head, in manual mode with K2.7 Coding and an existing OAuth login copied into an isolated temporary KIMI_CODE_HOME:
  • A structured allow carrying the exact request ID approved one Bash call without opening the native approval panel; the command produced KIMI_E2E_ALLOW_OK.
  • An allow carrying a mismatched request ID was ignored. The native four-option approval panel appeared, and the command ran only after selecting Approve once.
  • A structured deny carrying the exact request ID blocked the command without opening the native approval panel and surfaced the external-hook reason.
  • The three runs produced exactly three hook invocations, with three distinct non-empty permission request IDs and three distinct non-empty tool-call IDs.
• The formal ~/.kimi-code config and OAuth credential were unchanged. The temporary credential copy, config, session, and hook records were deleted after the test.
• The earlier PR head also passed a real Kimi Web manual-mode smoke test without a web approval dialog or stale pending state.
• VitePress built both documentation locales successfully.
• oxlint --type-aware completed with 0 errors.
• git diff --check passed.

Checklist

• I have read the CONTRIBUTING document.
• I have linked a related issue, or explained the problem above.
• I have added tests that prove my feature works.
• Ran gen-changesets skill, or this PR needs no changeset.
• Ran gen-docs skill, or this PR needs no doc update. The current main branch does not contain the skill's required docs/scripts/sync-changelog.mjs; the mirrored English/Chinese hook docs were reviewed directly and the VitePress build passes.

[changeset-bot]

🦋 Changeset detected

Latest commit: cefca49

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@moonshot-ai/kimi-code	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR