feat(agent-harness): define commands tools and permission policy

[iscekic]

No new behavior — this change defines actions but does not make them available in the product.

---

Summary

commandAdmission rejects agent permission changes and stale sends or mode changes; callers must supply the origin from command ingress.
evaluateDispatch uses DispatchPolicy and stored approval state; identity changes require a new call, and executing or settled calls cannot dispatch again.
ask requires approval except for trusted reads; yolo skips only approval, preserving denials, access, revision, availability, question, and client checks.

Files

• packages/agent-harness/src/policy.ts — Added (A), source: 69 lines (+69/-0). Adds admission and dispatch decisions without executing actions. Compares the call identifier, run, name, definition version, arguments, context, effect, and execution target. Uses stored approval and execution state instead of proposed replacements. Keeps approval across mode or revision updates for an unchanged call when the current checks pass. Callers must derive trustedRead from a local definition, not remote annotations.

CommandSchema and ReadInputSchema, with inferred Command and ReadInput types, define nine mutations and five reads with strict identity and pagination contracts.
canonicalizeValidatedInput and fingerprintCommand normalize validated commands and authenticated scope with injected hashing; commandReplayDecision returns new, replay, or command_conflict.
setPermissionMode requires acknowledgePendingActions for yolo, while client registration retains older advertised versions; these definitions do not store or execute commands.

Files

• packages/agent-harness/src/commands.ts — Added (A), source: 121 lines (+121/-0). Defines getOrCreateConversation, sendMessage, setPermissionMode, resolveInteraction, cancelRun, claimClientTool, completeClientTool, registerClient, and revokeClient. Mutations require protocolVersion, clientId, and commandId; conversation actions also require conversationId. Messages require nonblank text, a model, and a permission revision, with an optional variant. Mode changes require an expected revision; pending-action acknowledgement defaults to false. Interaction resolutions support approval, denial, question answers, and dismissal. Client completions require a grant, generation, and outcome; registration accepts only client tools with nonblank versions. Defines getConversation, getSnapshot, getCommand, getEvents, and getHistory; page limits run from 1 through 200. Events require an after cursor and default to 200 results; history defaults to 50 results with a nullable before cursor. Fingerprinting sorts nested object keys, preserves array order, and normalizes defaults. The caller supplies authenticated actor and conversation scope plus the platform's sha256 function. Conversation mismatches fail; extra authority fields, including transport credentials and timestamps, do not enter the hash. Reusing a stored command identity with a changed fingerprint returns a conflict rather than a replay.

toolDefinitions, ToolNameSchema, and ToolRequestSchema define 21 version-1 tools with strict input and output schemas, effects, and executor kinds, rejecting unnamed tools.
ScreenSchema restricts navigation; QuestionSchema, QuestionResponseSchema, and validQuestionResponse enforce stable identifiers, selection bounds, optional free text, and explicit cancellation.
The backend must install an executor before advertising a tool; ToolName and ToolRequest expose inferred types without enabling runtime actions.

Files

• packages/agent-harness/src/tools.ts — Added (A), source: 202 lines (+202/-0). Adds backend definitions for organizations, members, usage, repositories, invitations, session search, attachment, start, continuation, stop, and progress. Adds Model Context Protocol (MCP) discovery and calls, plus web search and retrieval. App tools use the client executor: app.currentScreen is a read, while navigation, preferences, notifications, and settings declare side effects. Questions use the interaction executor. Invitations and session mutations have side effects. MCP calls use the unknown effect and require a server identifier, tool name, configuration version, and definition version. MCP discovery includes input and output schemas; calls return content with optional structured content. Web search requests allow one through five results and default to five; page addresses permit only http or https. Pages and attached session messages require untrusted: true. Screens allow quick chat, organization members, preferences, or an identified session; preferences allow only showToolDetails and reasoningDefaultExpanded. Notification results report granted, denied, undetermined, or unavailable permission; settings results report whether settings opened. Questions require unique choice identifiers, matching response identifiers, and valid selection bounds; free text cannot replace required selections. allowFreeText defaults to false; explicit allowCancellation controls dismissal, including questions that permit only cancellation. Answers reject duplicate or unknown choices and blank text; cancellation-only questions cannot return an empty answer.

Tests: 1 test file added (A): packages/agent-harness/src/policy.test.ts (622 lines; +622/-0). Covers replay, schema validation, questions, all 21 tools, and 54 effect/executor/mode/revision combinations. The implementer reports 172 targeted tests; the reviewer reports 158 policy tests and passing scoped checks.
Generated: 0 files changed.

---

Visual Changes

Visual Changes: N/A

Verification

Manual verification: not run for this level because it adds inert portable commands, tool definitions, and policy only.
Full runtime verification runs on the completed stack tip.

Reviewer Notes

Human steps

No human steps apply before merge or after merge.

Worktrees

• Repository: Kilo-Org/cloud.
• Worktree: /Users/igor/Projects/.worktrees/shared-agent-harness-3bb0.
• Branch: shared-agent-harness-3bb0-s3; base: origin/shared-agent-harness-3bb0-s2.

Notes

E2E: This level adds inert portable commands, tool definitions, and policy only. Full runtime verification runs on the completed stack tip.

Stacked PRs — merge bottom to top. Each level shows only its own diff.

Runtime verification (E2E, user advocacy, simplify) runs on the tip PR over every level.
Every level keeps its own checks, its own bot review, and its own threads; each one is answered on its own PR.
Each level is its own deliverable: it builds and passes its own checks alone.
A finding on a level is repaired on that level, then carried upward with stack.sh forward.

1. shared-agent-harness-3bb0 — chore(agent-harness): register workspaces and enforce CI boundaries #5632
2. shared-agent-harness-3bb0-s2 — feat(agent-harness): define portable domain and snapshots #5637
3. shared-agent-harness-3bb0-s3 — feat(agent-harness): define commands tools and permission policy #5639 ← this PR
4. shared-agent-harness-3bb0-s4 — feat(agent-harness): share client state and cursor recovery #5643
5. shared-agent-harness-3bb0-s5 — feat(agent-harness): persist command intents and execution receipts #5647
6. shared-agent-harness-3bb0-s6 — feat(db): add harness ingress grants and retirement fences #5655
7. shared-agent-harness-3bb0-s7 — feat(agent-harness): deliver legacy history and project durable text #5659
8. shared-agent-harness-3bb0-s8 — feat(agent-harness): authorize durable grants and registered clients #5662
9. shared-agent-harness-3bb0-s9 — feat(agent-harness): fence retirement and retry payload cleanup #5667
10. shared-agent-harness-3bb0-s10 — feat(agent-harness): persist authoritative state in SQLite #5675
11. shared-agent-harness-3bb0-s11 — feat(agent-harness): admit durable runs and revisioned commands #5678
12. shared-agent-harness-3bb0-s12 — feat(agent-harness): recover queued runs and stream checkpointed steps #5688
13. shared-agent-harness-3bb0-s13 — feat(agent-harness): resolve interactions and dispatch tools sequentially #5693
14. shared-agent-harness-3bb0-s14 — feat(agent-harness): fence designated client tool execution #5697
15. shared-agent-harness-3bb0-s15 — feat(agent-harness): synchronize durable snapshots and legacy history #5701
16. shared-agent-harness-3bb0-s16 — feat(agent-harness): reuse authorized invitations with durable replay #5704
17. shared-agent-harness-3bb0-s17 — feat(integrations): bound repository transport for harness reads #5710
18. shared-agent-harness-3bb0-s18 — feat(integrations): expose bounded authorized repository reads #5714
19. shared-agent-harness-3bb0-s19 — feat(agent-harness): expose named authorized resource reads #5718
20. shared-agent-harness-3bb0-s20 — feat(sessions): bound history transport for harness reads #5724
21. shared-agent-harness-3bb0-s21 — feat(agent-harness): read scoped Cloud Agent context and progress #5726
22. shared-agent-harness-3bb0-s22 — fix(agent-harness): preserve ordered Cloud Agent dispatch identity #5731
23. shared-agent-harness-3bb0-s23 — feat(agent-harness): hand coding work to authorized Cloud Agent sessions #5733
24. shared-agent-harness-3bb0-s24 — feat(agent-harness): authorize scoped MCP gateway connections #5737
25. shared-agent-harness-3bb0-s25 — feat(agent-harness): bound MCP gateway transport in the Worker #5740
26. shared-agent-harness-3bb0-s26 — feat(agent-harness): execute validated remote MCP tools #5743
27. shared-agent-harness-3bb0-s27 — refactor(exa): share provider dispatch and usage recording #5746
28. shared-agent-harness-3bb0-s28 — feat(agent-harness): authorize bounded web provider requests #5747
29. shared-agent-harness-3bb0-s29 — feat(agent-harness): normalize web sources and preserve citations #5749
30. shared-agent-harness-3bb0-s30 — feat(agent-harness): define closed internal operation contracts #5753
31. shared-agent-harness-3bb0-s31 — feat(agent-harness): authorize internal maintenance operations #5754
32. shared-agent-harness-3bb0-s32 — feat(agent-harness): authorize named Kilo operation dispatch #5755
33. shared-agent-harness-3bb0-s33 — feat(agent-harness): authorize internal provider operations #5757
34. shared-agent-harness-3bb0-s34 — feat(agent-harness): secure the internal operations endpoint #5758
35. shared-agent-harness-3bb0-s35 — feat(agent-harness): bound and sanitize model streams #5767
36. shared-agent-harness-3bb0-s36 — feat(agent-harness): secure billed model inference #5776
37. shared-agent-harness-3bb0-s37 — test(agent-harness): cover model gateway security boundaries #5777 (tip)

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

Reviewed the new agent-harness command, tool, and permission-policy definitions (inert, not wired to runtime) with high confidence; admission, dispatch, fingerprinting, and schema gates match the stated contracts.

Files Reviewed (4 files)

• packages/agent-harness/src/commands.ts
• packages/agent-harness/src/policy.ts
• packages/agent-harness/src/tools.ts
• packages/agent-harness/src/policy.test.ts

---

_{Reviewed by grok-4.6 · Input: 144.7K · Output: 20.3K · Cached: 348.9K}

_{Review guidance: REVIEW.md from base branch shared-agent-harness-3bb0-s2}

[iscekic]

Closing: the owner stopped this workflow section. The branch is retained.