Map --read-only/--plan-only for the agent tool to its native --permission-mode (agent v0.24.0)

[konard]

Summary

Maps the agent tool's read-only / planning flags to its native, enforceable --permission-mode (introduced in @link-assistant/agent v0.24.0), instead of rejecting them as "not enforceable".

Flag	agent mapping	Semantics
--read-only	agent --permission-mode readonly	Deny every edit and any non read-only shell command, never asks
--plan-only	agent --permission-mode plan	Deny edits, allow read-only shell, ask before anything else

Other tools continue to treat --plan-only as an alias for --read-only; only agent honors the readonly/plan distinction because its CLI does.

Fixes #39.

Changes

• JS + Rust parity:
  • agent tool config now reports supportsReadOnly: true / supports_read_only: true.
  • buildArgs resolves --permission-mode from an explicit permissionMode, else plan for planOnly, else readonly for readOnly.
  • Added typed permission (OpenCode-compatible --permission '<json>') passthrough.
  • New planOnly / plan_only option threaded through CLI parser → start-agent binary → library → command builder. --plan-only sets both readOnly and planOnly; readOnlyRequested = readOnly || planOnly drives the support check and per-tool builders.
  • The "does not support enforceable read-only mode" rejection now lists agent as supported and only fires for genuinely unsupported tools.
• Docs: README matrix row, feature bullets, Read-only Planning Mode section, CLI/API option docs, and docs/common-concepts.md updated; removed the "unrestricted OpenCode fork" / "no permissions system" framing in favor of the native permission system.
• Changesets: JS (agent-permission-mode.md, minor) and Rust (20260617_120000_agent_permission_mode.md, minor).

How to reproduce / verify

Before, start-agent --tool agent --read-only ... threw Tool "agent" does not support enforceable read-only mode. Now it builds agent --permission-mode readonly.

buildAgentCommand({ tool: 'agent', workingDirectory: '/tmp', readOnly: true });
// => ... agent --permission-mode readonly
buildAgentCommand({ tool: 'agent', workingDirectory: '/tmp', planOnly: true });
// => ... agent --permission-mode plan

Tests

• JS (node --test): added agentTool buildArgs tests (readonly, plan, explicit permissionMode override, permission JSON passthrough, supportsReadOnly), and replaced the agent-rejection command-builder test with readonly/plan mapping tests plus an unknown-tool rejection test. All pass.
• Rust (cargo test): replaced test_build_agent_command_read_only_rejects_agent_tool with ..._agent_read_only_uses_readonly_mode, ..._agent_plan_only_uses_plan_mode, and ..._read_only_rejects_unknown_tool; added --plan-only CLI parser test. All pass. cargo fmt --check and cargo clippy clean; JS eslint/prettier clean (only pre-existing complexity warnings).

[konard]

Working session summary

All four CI runs (both JavaScript CI/CD and Rust CI/CD, push + PR triggered) passed on the final commit. The work is complete.

Summary

Issue #39 is resolved. The agent tool's read-only/planning flags now map to its native, enforceable --permission-mode (agent v0.24.0) instead of being rejected:

• --tool agent --read-only → agent --permission-mode readonly (hard read-only, never asks)
• --tool agent --plan-only → agent --permission-mode plan (deny edits, allow read-only shell, ask before anything else)

What changed (JS + Rust parity)

• agent tool config reports supportsReadOnly: true / supports_read_only: true.
• buildArgs resolves --permission-mode from explicit permissionMode, else plan for planOnly, else readonly for readOnly; added typed permission (--permission '<json>') passthrough.
• New planOnly / plan_only option threaded through CLI parser → start-agent binary → library → command builder. --plan-only sets both flags; readOnlyRequested = readOnly || planOnly drives the support check. Other tools keep treating --plan-only as an alias for --read-only; only agent honors the readonly/plan distinction.
• The rejection error now lists agent as supported and only fires for genuinely unsupported tools.
• Docs (README matrix/bullets/Read-only section/API docs, docs/common-concepts.md) updated; removed the "unrestricted OpenCode fork" / "no permissions system" framing.
• Changesets added for both packages (minor bump).

Verification

• JS node --test: all pass (added agent readonly/plan/override/permission/supportsReadOnly tests; replaced agent-rejection test with mapping tests + unknown-tool rejection test).
• Rust cargo test: all pass; cargo fmt --check and cargo clippy clean; JS eslint/prettier clean (only pre-existing complexity warnings).
• All 4 CI runs green on the final commit de0cfbf.

PR #41 updated, marked ready for review: #41

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $8.131340
• Calculated by Anthropic: $9.000729
• Difference: $0.869389 (+10.69%)

📊 Context and tokens usage:

Claude Opus 4.8: (2 sub-sessions)

1. 116.4K / 1M (12%) input tokens, 23.8K / 128K (19%) output tokens
2. 92.1K / 1M (9%) input tokens, 23.2K / 128K (18%) output tokens

Total: (21.2K new + 233.8K cache writes + 10.4M cache reads) input tokens, 53.3K output tokens, $8.124553 cost

Claude Haiku 4.5:

• 5.1K / 200K (3%) input tokens, 344 / 64K (1%) output tokens

Total: 5.1K input tokens, 344 output tokens, $0.006787 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Main model: Claude Opus 4.8 (claude-opus-4-8)
• Additional models:
  • Claude Haiku 4.5 (claude-haiku-4-5-20251001)

📎 Log file uploaded as Gist (4497KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.