Kocoro AGENTS.md

Kocoro Project Guide (AGENTS.md)

Condensed mirror of CLAUDE.md — rules + greppable symbols. If they disagree, CLAUDE.md and the code win.

Keep this file under 24 KB (CI asserts) — cut prose, not rules. Within 1 KB of the ceiling, adding bytes requires cutting at least as many from this file (CI asserts).

Kocoro is the Go CLI/runtime (shan) for Shannon agents. Production: daemon + Desktop + Cloud. Also TUI, one-shot CLI, MCP, schedules.

Layout: cmd/ (Cobra) + internal/<pkg>/; daemon/ drives agent/.

Working Rules

• go.mod is the source of truth for the Go version.
• Prefer existing repo patterns over new abstractions; keep changes tied to the task.
• Verify API response bodies, not just status codes.
• No parallel _enhanced variants — update existing code in place.
• Risky behavior changes keep operator-visible flags, rollback paths, focused tests.
• Test locally before pushing dependency or generated-code changes.
• New const max[A-Z]\w+ = <small_int>: the comment MUST name (1) the workload, (2) the symptom when it binds, (3) the override path. Prefer viper.SetDefault(...) for liftable caps. Re-check small-int caps on model-family upgrades — 200K-era defaults bind silently at 1M.

Doc Co-Maintenance

Feature changes update README.md, CLAUDE.md, and this file.

The bundled kocoro skill is the AI-facing source of truth for the daemon HTTP API. Every mux.HandleFunc(...) in daemon/server.go the agent calls needs a matching skills/bundled/skills/kocoro/references/*.md entry in the SAME PR. Desktop-only transport endpoints stay out; their contract lives in docs/desktop-wire-fixtures/.

Tools

• Required fields: every Run() MUST check each ToolInfo.Required field is non-zero right after json.Unmarshal and return agent.ValidationError(...), NOT a bare ToolResult{IsError: true} (Go can't tell missing from zero). The [validation error] prefix is load-bearing: LoopDetector.isValidationErrorSig force-stops on 3 consecutive.
• Priority: local > MCP > gateway, deduped by name. MCP-vs-MCP collisions resolve to the alphabetically-first server (RebuildRegistryForHealth); the shadowed tool is logged, never registered.
• Exposure (agent/exposure.go EffectiveToolExposure): explicit ToolExposure first, then source default — local Direct; MCP/gateway/ integration Deferred. ask_user_question is explicitly Direct. web_search / web_fetch / x_search are Direct only when ToolSource()==SourceGateway (tools/exposure.go ServerTool.ToolExposure); a same-named MCP or integration tool keeps its Deferred default so a third-party catalog cannot widen the base schema surface. GUI/process automation and calendar/schedule mutations are Deferred; calendar/schedule reads stay Direct.
• tool_search uses deterministic BM25 (agent/toolsearch_index.go, toolSearchDefaultLimit 8) with exact select: lookup. The 16K Direct-schema budget is a regression diagnostic and MUST NEVER reclassify tools at runtime.
• Skill allowed-tools is execution-time denial, NOT schema filtering — the tools array stays byte-stable for the prompt cache. agent.SkillExempt (think, tool_search, use_skill) is for pure infrastructure only; do NOT exempt side-effecting tools.
• Concurrency: the dispatcher batches by IsConcurrencySafeCall, not IsReadOnlyCall; tools without a ConcurrencySafeChecker fall back to their IsReadOnlyCall value. BashTool implements it in tools/bash_concurrency.go, gated by agent.bash_concurrency_enabled (default true): only a strict read-only leading token AND no shell metacharacters (incl. \n / \r) is eligible; everything else stays in a size-1 serial batch.
• tool_status running/completed carry tool_use_id (capability tool_use_id_events).
• set_work_plan (daemon/work_plan.go): full-snapshot 2–8-step checklist, daemon non-ephemeral runs only. Runtime owns plan_id/revision/lifecycle/close_reason; closure comes from LastRunStatus, never a model claim, and bumps the revision. work_plan.updated fires only after the covering save. Not dup-exempt; SkillExempt; never journaled. Capability work_plan_v1.
• Every RequiresApproval()==true tool needs a description (5-15 words, model-written). The daemon does NOT block on a missing one; UI clients MUST use description?.trim() || fallback, NOT nullish coalescing.
• Integration requires_approval=true → normal approval flow (daemon.auto_approve bypasses); Always Allow persistence refused — DisallowsAlwaysAllowPersistence gates flag/broker/persist/runtime; stale always_allow_tools entries ignored. Config writes (incl. agent-sync pull) drop denied entries (dropRegistryDeniedAlwaysAllow, registry miss keeps); RefreshIntegrationTools + resetIntegrationToolsForPrincipal prune after rebuild (pruneDeniedAlwaysAllowGrants). Drop skips the LWW stamp; both prunes push on write. Absent=false; Cloud gates marked schemas on integration_requires_approval.
• Trusted material_side_effect=false permits observational batching without the journal; absent is fail-closed. Stable request_id; material calls add Idempotency-Key. Only provider_unavailable/provider_rejected are known-no-effect. Preserve provider/model/unit/cost via ToolResult/EmitUsage. Exhausted call_in_progress → outcome_unknown: never resend under a new ID.
• Outcome-unknown material results narrate as ordinary tool errors; the same-turn latch (agent/unknown_outcome_gate.go) blocks byte-identical tool+args repeats until the next user message.
• SourceIntegration is identity-scoped. Key mutation invalidates generations before source clear, without the dispatch writer. Failed new-identity listing leaves it empty; same-identity refresh failure keeps it. ServerTool binds list credential/principal generation; stale clones fail pre-dispatch, caches can't revive them. Auth/integration/MCP-health/reload swaps share one lock. Auth rebuilds both overlays: credential-bound cloud/publish/image drop, calendar/non-auth tools survive. cloud_delegate, publish/list/retract, and generate/edit lease generation through all Run retries. Serialize auth across accounts/keys.
• X publishing only via Cloud X tools (x_prepare_post removed). browser/computer_use/builtin Playwright block X composer/publish controls; Playwright omits browser_run_code/browser_evaluate; CDP: any X target blocks mutation; non-CDP: no claim; shell/custom MCP unguarded.