Instructions and Settings¶

Instructions define agent behavior; settings define adapter/model mechanics. Both are lexical and apply to following calls.

Single-Line Instructions¶

> system: Answer with evidence from available tools.

Use a single line for one stable rule. It is rendered when active state is materialized.

Multiline Instructions¶

[audience] = maintainers

> system:
    Act as a release engineer for <audience>.
    Inspect evidence before reaching a conclusion.
    Report uncertainty explicitly.

Continuation lines are newline-joined. Multiline system bodies are read-only templates: literal text, <name> substitutions, and inline Python substitutions are allowed. Output fields and procedure calls are not.

> system:
    Current mode: <`args.mode`>.

An instruction cannot declare [output] or call <helper()>; compute that value before the directive and substitute the resulting variable. Use <``> when the instruction itself must mention a literal triple-backtick fence.

Settings Blocks¶

> settings:
    temperature: 0.2
    max_tokens: 1024
    parallel_tool_calls: false

Plain values parse as booleans, null/none, integers, floats, Python literals when valid, or otherwise strings.

Use backticks for explicit Python objects:

> settings:
    stop_sequences: `["END", "DONE"]`
    extra_body: `{"mode": "json"}`
    parallel_tool_calls: `False`

Backticks are necessary for computed values and remove ambiguity about list, dict, or object identity.

Merge and Filtering¶

Settings merge by key. A later value replaces the same earlier key while unmentioned keys remain:

> settings:
    temperature: 0.2
    timeout: 30

@patient_call() -> str:
  > settings:
      timeout: 120
>> Complete the task and return [answer: str].
  = <answer>

The inner call retains temperature: 0.2 and uses timeout: 120.

Kedi validates setting names against its known public setting inventory, then filters the merged mapping at the adapter boundary. Pydantic receives supported ModelSettings; DSPy receives supported dspy.LM kwargs; LangChain receives its chat-model fields; harnesses receive their own process/runtime settings.

Common Framework Settings¶

Common fields include temperature, max_tokens, timeout, top_p, parallel_tool_calls, tool_choice, retry controls, stop sequences, and provider extension bodies. Exact support still depends on the active adapter and model provider.

Do not copy a provider-specific setting into every profile. Keep it in the profile that owns that backend.

Harness Settings¶

ACP accepts cwd, env, and timeout. Codex accepts fields including cwd, sandbox, approval_policy, config, model_provider, service_tier, and timeout. Claude accepts fields including cwd, env, tools, allowed_tools, disallowed_tools, permission_mode, max_turns, and max_budget_usd.

> agent:
    acp: npx @zed-industries/codex-acp
> settings:
    cwd: /workspace/project
    env: `{"LOG_LEVEL": "INFO"}`
    timeout: 120

cwd is passed to ACP, Codex, and Claude where supported. Relative child-agent working directories are constrained by their parent safety boundary.

Claude appends > system: content to its Claude Code preset, preserving built-in file behavior. Non-interactive Claude defaults to permission_mode: acceptEdits; set tool and permission fields explicitly to narrow it. Codex defaults to workspace-write unless settings narrow or replace its sandbox.

Unknown and Inapplicable Settings¶

Unknown setting names are parser/LSP errors. A known union-level key can still be irrelevant to a selected backend and is filtered rather than passed blindly. Adapter docs list the exact mapping.

Prefer a minimal settings block. Every additional provider knob is part of the profile's operational contract and should have a tested reason.

Conversation history and compaction are intentionally not model settings. Use > history: enabled for stateful calls or the expanded history policy described in Caching and Conversation History.